Adding a New API Provider

This guide walks you through adding a new in-tree API provider to OGX. Start by reviewing the core concepts, then pick the API your provider implements (Inference, Responses, VectorIO, etc.) and where it runs:

• Remote providers make requests to an external service (src/ogx/providers/remote).
• Inline providers execute locally (src/ogx/providers/inline).

Steps

1. Register the provider in the registry for its API, and declare any pip dependencies it needs.
2. Add a config class — a Pydantic model that uses Field(..., description=...) on each field. These descriptions are used to auto-generate the provider docs.
3. Include it in a distribution if it should be available by default: add the provider to the relevant distribution template's config.yaml, then run ./scripts/distro_codegen.py. Note that distro_codegen.py fails if a distribution template imports a provider's implementation rather than just its config / model-alias definitions, so keep get_distribution_template() to config and model-alias imports only.

Example PRs to get started:

• Grok Inference
• Nvidia Inference
• MCP Tool Runtime

Inference providers: OpenAIMixin

For OpenAI-compatible inference APIs, use the OpenAIMixin to avoid reimplementing the client and request logic. It provides openai_completion(), openai_chat_completion(), openai_embeddings(), check_model_availability(), and a client property that builds an AsyncOpenAI client from your credentials. Subclasses only need to implement get_base_url():

@abstractmethod
def get_base_url(self) -> str:
    """Return the OpenAI-compatible API base URL, e.g. "https://api.openai.com/v1"."""
    ...

Testing the provider

Install the provider's (or distribution's) dependencies first, e.g. ogx stack list-deps <distro> | xargs -L1 uv pip install.

• Integration tests live in tests/integration and use the ogx_client package (against a running server, or inline via OGXAsLibraryClient). A provider's sample_run_config() typically references env vars for API keys; set those before running the tests. See tests/integration/README.md.
• Unit tests live in tests/unit/providers and run in CI. See tests/unit/README.md.

Submitting your PR

1. Ensure all tests pass.
2. Include a test plan in your PR summary.
3. Document any known limitations.