docs(api): API reference docs umbrella (AGE-3734)#4314
Draft
mmabrouk wants to merge 17 commits into
Draft
Conversation
Introduce a shared concept page documenting the artifact / variant / revision pattern used by applications, workflows, evaluators, and testsets. Covers commit semantics, retrieval references, revision log, and archive/unarchive. Factors out a pattern that would otherwise have to be repeated in every per-resource reference page. The applications, workflows, evaluators, and testsets concept pages (landing in parallel PRs) link to this page instead of redefining the model.
- Add `docs/docs/reference/api-guide/05-applications.mdx` covering what an application is, versioning, invocation, deployment, simple vs structured endpoints, catalog, lifecycle, and an end-to-end worked example. - Add docstrings to all 35 Applications FastAPI handlers (29 structured + 6 simple), explaining what each endpoint does and when to pick it over a similar one. - Add `Field(description=...)` to every field on the applications request and response models, including the catalog and simple-application models. - Every endpoint was exercised against `eu.cloud.agenta.ai` before its docstring was written. - Hooks skipped in sandbox; will be run locally before merge. No secrets in this PR (docs + docstrings only).
- Note that revisions carry the payload, not just commit metadata. - Add environments as a deployment pointer alongside artifact/variant/revision. - Reference the existing /concepts/concepts overview page. - Replace temperature-only example with a realistic application revision payload (prompt, messages, llm_config). - Explain what a reference is (id, slug, slug+version) before describing retrieve precedence. - Spell out "most specific wins" as revision > variant > environment. - Rename "Revision log" to "Listing revision history" so the heading matches the verb pattern used by the other sections. - Clarify the fork verb ties to POST /variants/fork.
Aggregates the 8 sub-PRs that add concept pages and endpoint docstrings for the REST API reference. Sub-PRs base off this branch so forward links (versioning <-> applications, workflows, evaluators, testsets, tracing, folders, evaluations) resolve during docs build. When all sub-PRs are merged into this branch, this PR merges into main.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
The ag_config wrapper was removed by migration 91d3b4a8c27f_fix_ag_config
(2025-04-24); revision payloads now live under data.parameters directly.
Verified against eu.cloud.agenta.ai: posting with the old ag_config
envelope returns HTTP 200 but stores data: {} because extra fields are
silently dropped. The corrected shape (data.parameters.prompt.*) stores
the payload correctly.
docs(docs): add versioning concept page
…plications-endpoints Resolve conflict in api/oss/src/apis/fastapi/applications/models.py: response envelopes now extend the new Support base class (from oss.src.utils.exceptions) while keeping the documentation docstrings and Field(description=...) introduced on this branch. No conflicts elsewhere. Router and concept page pick up cleanly from main.
…lders-endpoints Bring in main + the landed versioning concept page so the folders PR can ship on top of the umbrella branch. Conflict resolution: - api/oss/src/apis/fastapi/folders/models.py: the umbrella switched the three response models (FolderResponse, FoldersResponse, FolderIdResponse) to inherit from `Support` so they carry support_id / support_ts. Combined with the Field(description=...) annotations from this branch.
Run pnpm clean-api-docs && pnpm gen-api-docs to refresh the generated *.api.mdx pages against the current openapi.json. Picks up the support_id / support_ts fields on response envelopes and other minor regen drift.
`POST /applications/variants/fork` now raises `400 Bad Request` when the fork target is invalid (introduced in 77cb317 "workflow-related fork issues"). Add a short note to the handler docstring so the generated OpenAPI reflects the failure mode. No behavioral change.
Drop the docs/docs/reference/api/*.api.mdx regeneration from this PR. Those files are auto-generated from openapi.json and produce a lot of noise in domain PRs. They will be regenerated at a later stage in the workflow, once openapi.json itself is updated from the branch code (not from production, which is what update-api-docs does by default). Leaves the actual docstring + Field(description=...) changes in api/oss/src/apis/fastapi/folders/ intact.
docs(api): folders endpoint docstrings + concept page
…' into docs/age-3734-applications-endpoints
Rewrites the intro to lead with the customer-facing model (chat / completion endpoint), introduces the built-in application types up front, and links custom workflows as another kind of application. Splits the `data` payload section so `uri` + `schemas` are explained as drivers of execution before the catalog is referenced. Removes remaining em dashes.
…dpoints docs(api): applications endpoint docstrings + concept page
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Umbrella PR aggregating the AGE-3734 API reference documentation effort. The 8 sub-PRs below base off this branch instead of
mainso that forward links between concept pages (versioning ↔ applications, workflows, evaluators, testsets, tracing, folders, evaluations) resolve during the Docusaurus build.Each sub-PR contains a concept page plus the FastAPI handler docstrings and
Field(description=...)updates for its domain. Style guide:.claude/skills/write-docs/SKILL.md. Project plan:tmp-docs-analysis/plan.md.Sub-PRs
Merge flow
Test plan
npm run buildindocs/passes with no broken-link errorsruff formatandruff checkclean inapi/