docs(api): document datatype stability and ogx-api package surfaces#5719
Open
cdoern wants to merge 3 commits intoogx-ai:mainfrom
Open
docs(api): document datatype stability and ogx-api package surfaces#5719cdoern wants to merge 3 commits intoogx-ai:mainfrom
cdoern wants to merge 3 commits intoogx-ai:mainfrom
Conversation
Expand the API stability policy to cover the ogx-api Python package as a distinct public contract. Define two surfaces — API datatypes (ogx_api.types.*, level inherited from referencing routes) and the Provider SDK (ogx_api.provider.*, a single v1-stable surface) — with per-surface compatibility rules, deprecation timelines, and pinning recommendations for external providers. Replace the stale post_training example with the current /v1alpha and /v1beta routes, and replace the abandoned conformance-tracking issue link with descriptions of the suites that exist today (backward-compat, openresponses-conformance, external-spec coverage, test-external). Drop the unimplemented x-stability/oasdiff section. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Charlie Doern <cdoern@redhat.com>
Strip the in-progress namespace paths from the policy doc; the sub-namespace split will land in a follow-up PR. The two-surface conceptual model stays — bucketing rules define which surface a symbol belongs to regardless of its current import path. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Signed-off-by: Charlie Doern <cdoern@redhat.com>
cdoern
requested review from
bbrowning,
franciscojavierarceo,
leseb,
mattf and
raghotham
as code owners
4 tasks
skamenan7
pushed a commit
to skamenan7/llama-stack
that referenced
this pull request
May 6, 2026
ogx-ai#5740) ## Summary Splits the public surface of the `ogx-api` Python package into two import namespaces, as called out in the API Stability policy work in ogx-ai#5719. No file moves, no behavioral changes — just aggregate `__init__.py` modules that re-export from existing per-API submodules. - **`ogx_api.provider`** (59 symbols) — Provider SDK surface for out-of-tree providers: `Api`, `ProviderSpec`/`InlineProviderSpec`/`RemoteProviderSpec`, protocol classes (`Inference`, `Responses`, `VectorIO`, `Safety`, `Files`, …), schema utilities (`webmethod`, `json_schema_type`, `register_schema`), `Resource`/`ResourceType`, version constants, validators. Levelled as a single `v1`-stable contract per the policy. - **`ogx_api.types`** (413 symbols) — API datatype surface: request/response Pydantic models, content blocks, errors, value types. Each datatype's stability is inherited from the highest-stability route that references it. Shared resource/value types (`Model`, `Shield`, `ToolGroup`, `VectorStore`) are canonically in `ogx_api.types` and re-exported from `ogx_api.provider` for provider-side ergonomics — these are the only allowed overlap. ### Backwards compatibility Top-level imports (`from ogx_api import X`) continue to work unchanged for every symbol. New code should prefer the explicit namespace path: ```python from ogx_api.provider import Api, Inference, ProviderSpec from ogx_api.types import OpenAIResponseObject, ChatCompletionMessage ``` ### Out of scope - Physically moving files into the new directories. - Deprecating or warning on top-level imports. - Touching internal `ogx` server imports. ## Test plan - [x] New contract test `tests/unit/test_ogx_api_namespaces.py` (5 cases): asserts disjoint namespaces, top-level back-compat (every namespaced symbol resolves to the same object via `ogx_api`), and presence of core symbols. **All pass.** - [x] Broader unit-test sweep: `uv run pytest tests/unit/ --ignore=tests/unit/providers` → **973 passed**. Provider-test failures in this env are pre-existing missing optional deps (`moto`, `databricks`), not introduced here. - [x] `pre-commit run` clean on touched files (ruff, ruff-format, mypy, license-headers, API spec codegen all pass; the `check-init-py` hook fails on macOS bash 3.2 — pre-existing, unrelated). - [ ] CI to run `test-external.yml` and `test-external-provider-module.yml` against this branch to confirm out-of-tree provider builds still work via top-level imports. ## Related - Policy doc PR: ogx-ai#5719 (defines the two-surface model conceptually). This PR is the implementation. Trivial doc conflict expected on whichever merges second; either is straightforward to resolve. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Charlie Doern <cdoern@redhat.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
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
Expands
docs/docs/concepts/apis/api_leveling.mdxto cover theogx-apiPython package as a distinct public contract alongside the HTTP API surface. Pre-1.0 cleanup so the stability story is coherent before we ship.What changed
ogx-apiinto two surfaces:ogx_api.types.*) — level inherited from the highest-stability route that references the type, with per-level compat tables and explicit breaking/non-breaking lists.ogx_api.provider.*) — a singlev1-stable surface for the plugin ABI (Api,ProviderSpec, protocol classes,webmethod, etc.). Removals/renames/signature changes are major-bump-only; deprecations carry across one major. Includes external-provider pinning recommendations.ogx_api.__init__./v1removals can't happen in the same Y-stream as the deprecation flag; renames are deprecations, not in-place swaps.backward-compat.yml,openresponses-conformance.yml, external-spec coverage scripts,test-external*) and what each one catches. Adds an "Outstanding work before 1.0" punch list.post_trainingexample with current/v1alphaand/v1betaroutes, fixed thev1alpha1typo, removed the broken#3237link.x-stability/oasdiff section (unimplemented; not worth keeping aspirational).Open questions for review
v1-stable — confirm the team agrees, given protocol classes still occasionally gain abstract methods.ogx_api.types/ogx_api.provider) is called out as in-progress. Happy to follow up with the actual refactor in a separate PR if there's appetite.docs/docs/api-experimental/index.mdx) still listsDatasets/DatasetIO/Eval/BenchmarksAPIs that no longer exist — out of scope here, but flagging.Test plan
docs/docs/concepts/apis/api_leveling.mdxlocally (docs-buildworkflow) and verify anchors resolve (#deprecation-timeline,#public-datatype-stability,#conformance-testing)..github/workflows/(no renamed/removed workflows referenced).🤖 Generated with Claude Code