feat(ogx-api): introduce ogx_api.provider and ogx_api.types namespaces (#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
#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: #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>

Author: cdoern

docs/docs/concepts/apis/api_leveling.mdx

@@ -72,6 +72,15 @@ The leveling introduced in this document relates to the stability of the API and
 
 Providers can iterate as much as they want on functionality as long as they work within the bounds of an API. If they need to change the API, then the API should not be `/v1`, or those breaking changes can only happen on a y-stream release basis.
 
+### Public surfaces of the `ogx-api` package
+
+The [`ogx-api`](https://pypi.org/project/ogx-api/) Python package — consumed by external/out-of-tree providers and SDK code generation — exposes two distinct public surfaces, each with its own stability rules:
+
+- **`ogx_api.provider`** — the Provider SDK: `Api` enum, `ProviderSpec` family, protocol classes (`Inference`, `Responses`, `VectorIO`, …), schema utilities, `Resource` base classes, version constants, validators. Levelled as a single cohesive contract; currently `v1`-stable. Removals or signature changes require a major version bump of `ogx-api`.
+- **`ogx_api.types`** — API datatypes: request/response Pydantic models, content blocks, errors, value types. Each datatype's level is inherited from the highest-stability route that references it (a type used by any `/v1` route is `v1`-stable).
+
+Top-level imports (`from ogx_api import X`) remain supported for backwards compatibility and resolve to the same objects as the namespaced imports. New code should prefer the explicit namespace path to make the contract boundary obvious. Sub-module imports (`from ogx_api.responses import ...`) remain unsupported and are not covered by this policy.
+
 ### Approval and Announcement Process for Breaking Changes
 
 - **PR Labeling**: Any pull request that introduces a breaking API change must be clearly labeled with `breaking-change`.

src/ogx_api/provider/__init__.py

@@ -0,0 +1,150 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""
+Provider SDK surface for OGX.
+
+This namespace contains the symbols an out-of-tree provider needs to register
+itself with the OGX server: protocol classes, provider specs, the `Api` enum,
+the `webmethod` decorator, schema utilities, and shared resource/value types.
+
+The Provider SDK surface is levelled as a single cohesive contract — see
+`docs/docs/concepts/apis/api_leveling.mdx` for the stability rules. The whole
+surface is `v1`-stable; removals or renames require a major version bump of
+the `ogx-api` package.
+
+Symbols re-exported here also remain importable from the top level (`from
+ogx_api import X`) for backwards compatibility. New code should prefer
+`from ogx_api.provider import X` to make the contract explicit.
+"""
+
+# Protocol classes — the abstract interfaces a provider implements.
+from ogx_api.admin import Admin
+from ogx_api.batches import Batches
+from ogx_api.connectors import Connectors
+from ogx_api.conversations import Conversations
+from ogx_api.datatypes import (
+    Api,
+    DynamicApiMeta,
+    Error,
+    ExternalApiSpec,
+    HealthResponse,
+    HealthStatus,
+    InlineProviderSpec,
+    ModelsProtocolPrivate,
+    ProviderSpec,
+    RemoteProviderConfig,
+    RemoteProviderSpec,
+    RoutingTable,
+    ShieldsProtocolPrivate,
+    ToolGroupsProtocolPrivate,
+    VectorStoresProtocolPrivate,
+)
+from ogx_api.file_processors import FileProcessors
+from ogx_api.files import Files
+from ogx_api.inference import Inference, InferenceProvider, ModelStore
+from ogx_api.inspect_api import Inspect
+from ogx_api.interactions import Interactions
+from ogx_api.messages import Messages
+
+# Shared resource/value types. Canonical home is `ogx_api.types`; re-exported
+# here because providers import them as part of registration / protocol
+# implementations.
+from ogx_api.models import Model, Models
+from ogx_api.prompts import Prompts
+from ogx_api.providers import Providers
+from ogx_api.resource import Resource, ResourceType
+from ogx_api.responses import Responses
+from ogx_api.safety import Safety, ShieldStore
+from ogx_api.schema_utils import (
+    CallableT,
+    ExtraBodyField,
+    SchemaInfo,
+    clear_dynamic_schema_types,
+    get_registered_schema_info,
+    iter_dynamic_schema_types,
+    iter_json_schema_types,
+    iter_registered_schema_types,
+    json_schema_type,
+    register_dynamic_schema_type,
+    register_schema,
+)
+from ogx_api.shields import Shield, Shields
+from ogx_api.tools import ToolGroup, ToolGroups, ToolRuntime, ToolStore
+from ogx_api.validators import validate_embeddings_input_is_text
+from ogx_api.vector_io import VectorIO
+from ogx_api.vector_stores import VectorStore
+from ogx_api.version import OGX_API_V1, OGX_API_V1ALPHA, OGX_API_V1BETA
+
+__all__ = [
+    # Core provider machinery
+    "Api",
+    "DynamicApiMeta",
+    "Error",
+    "ExternalApiSpec",
+    "HealthResponse",
+    "HealthStatus",
+    "InlineProviderSpec",
+    "ProviderSpec",
+    "RemoteProviderConfig",
+    "RemoteProviderSpec",
+    "RoutingTable",
+    # Protocol-private mixins
+    "ModelsProtocolPrivate",
+    "ShieldsProtocolPrivate",
+    "ToolGroupsProtocolPrivate",
+    "VectorStoresProtocolPrivate",
+    # Resource base classes
+    "Resource",
+    "ResourceType",
+    # Schema utilities
+    "CallableT",
+    "ExtraBodyField",
+    "SchemaInfo",
+    "clear_dynamic_schema_types",
+    "get_registered_schema_info",
+    "iter_dynamic_schema_types",
+    "iter_json_schema_types",
+    "iter_registered_schema_types",
+    "json_schema_type",
+    "register_dynamic_schema_type",
+    "register_schema",
+    # Version constants
+    "OGX_API_V1",
+    "OGX_API_V1ALPHA",
+    "OGX_API_V1BETA",
+    # Validators
+    "validate_embeddings_input_is_text",
+    # API protocol classes
+    "Admin",
+    "Batches",
+    "Connectors",
+    "Conversations",
+    "FileProcessors",
+    "Files",
+    "Inference",
+    "InferenceProvider",
+    "ModelStore",
+    "Inspect",
+    "Interactions",
+    "Messages",
+    "Models",
+    "Prompts",
+    "Providers",
+    "Responses",
+    "Safety",
+    "ShieldStore",
+    "Shields",
+    "ToolGroups",
+    "ToolRuntime",
+    "ToolStore",
+    "VectorIO",
+    # Shared resource/value types (canonical home in ogx_api.types)
+    "Model",
+    "Shield",
+    "ToolGroup",
+    "VectorStore",
+]

src/ogx_api/pyproject.toml

@@ -64,6 +64,8 @@ packages = [
     "ogx_api.tools",
     "ogx_api.vector_io",
     "ogx_api.connectors",
+    "ogx_api.provider",
+    "ogx_api.types",
 ]
 
 # 3. List every root-level .py file as a module.