{"owner":"ogx-ai","repo":"ogx","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md"],"skills":{"CLAUDE.md":"See @AGENTS.md for guidelines on working with this codebase.\n\n## Design Context\n\n### Users\n\nBackend engineers, application developers, and platform teams evaluating or adopting OGX for production AI workloads. They arrive from GitHub, blog posts, or search. They already use OpenAI/Anthropic SDKs and want to know: can I point my existing code at this server and have it just work? They are practical, time-constrained, and skeptical of marketing fluff. They read docs in dark terminals, IDEs, and browser tabs at all hours.\n\n### Brand Personality\n\n**Powerful, flexible, production-grade.** Not flashy. Not cute. Not corporate. The kind of project where the README is better than most companies' entire docs site. Speaks in code examples, not marketing copy. Respects the developer's time above all else.\n\nThree words: **capable, direct, trustworthy.**\n\n### Aesthetic Direction\n\n- **Tone**: Technical confidence without pretension. Think: well-organized CLI output, a clean terminal, a tool that does exactly what it says.\n- **Theme**: Dark mode default, both supported. Dark should feel like a refined terminal environment, not \"glowing neon AI dashboard.\" Light should feel like clean paper, not washed-out gray.\n- **Anti-references**: Purple-to-blue gradients, animated gradient text, icon-in-colored-circle card grids, \"Works with 20+ providers!\" vanity stats, marquee scrolling logos, decorative mesh backgrounds. All of these are present on the current site and should be replaced.\n- **Color**: Move away from purple as primary. The logo uses a deep navy-to-teal gradient. The palette should feel grounded, not synthetic. Consider warm neutrals or muted earth tones as an alternative to the current purple/teal AI palette.\n- **Typography**: Current fonts (Space Grotesk, Inter) are on the overused list. Find something with more character that still reads as technical and trustworthy.\n\n### Design Principles\n\n1. **Show, don't decorate.** Every visual element must communicate information. No decorative gradients, glows, or animations that exist for \"wow factor.\"\n2. **Code is the hero.** The most important thing on the landing page is a working code example. Make it prominent, readable, and real.\n3. **Earn trust through clarity.** Clean structure, consistent spacing, and direct language signal competence better than any visual flourish.\n4. **Respect the scroll.** Every section must justify its existence. If it doesn't answer a question the developer has, cut it.\n5. **No AI slop.** If a pattern appears on 50 AI-generated landing pages, it doesn't belong here. When in doubt, do less.\n","AGENTS.md":"# Agent Guidelines for OGX\n\nThis file provides guidance for AI coding agents working on this codebase.\nIt complements [CONTRIBUTING.md](CONTRIBUTING.md) with agent-specific instructions.\nHuman contributors should follow the conventions in CONTRIBUTING.md.\n\n## Project Overview\n\nOGX is an API server implementing the OpenAI Responses API, Chat Completions,\nEmbeddings, and supporting APIs (files, vector stores, batches, eval, and responses guardrails). It supports\nmultiple inference backends (OpenAI, Azure, Bedrock, vLLM, Ollama, WatsonX, etc.) through\na provider architecture.\n\n## Repository Layout\n\n```text\nsrc/ogx/              # Server implementation\n  core/                       # Request routing, server, storage\n  providers/\n    inline/                   # Built-in providers (responses, eval, vector_io, etc.)\n    remote/                   # Remote provider adapters (OpenAI, Azure, vLLM, etc.)\n    registry/                 # Provider registration specs\n    utils/                    # Shared provider utilities (OpenAI mixin, MCP, etc.)\n  distributions/              # Distribution configs (starter, ci-tests, etc.)\nsrc/ogx_api/          # API definitions, Pydantic models, FastAPI routes\ntests/\n  unit/                       # Unit tests\n  integration/                # Integration tests with recording/replay system\n```\n\n## Python & Tooling\n\n- **Python 3.12** is required. Pre-commit hooks only work with 3.12.\n- Use `uv` for all dependency management and script execution.\n- Run scripts with `uv run`, never bare `python3` or `python`.\n- Use standard library modules when possible.\n- All function signatures must have type hints. Prefer Pydantic models for validation.\n- Code must pass `mypy`. Check the exclude list in `pyproject.toml` for known exceptions.\n- Use `def _function_name` for private functions.\n- Prefer explicit top-level imports over inline imports.\n- Do not use exceptions as control flow.\n\n## Code Style\n\n- Comments must add value. Do not write filler comments that describe the next line.\n- Add comments only to clarify surprising behavior that is not obvious from the code.\n- Good variable naming and clear code organization matters more than comments.\n- Do NOT remove existing comments unless they are factually wrong.\n- Error messages must be prefixed with \"Failed to ...\".\n- Use structured logging via `from ogx.log import get_logger`. Always use\n  key-value style: `logger.info(\"Processing request\", model=model_id, provider=provider)`\n  instead of f-strings or %-style formatting. The pre-commit hook\n  `Block f-string logging` enforces this.\n- The pre-commit hook `Ensure 'ogx.log' usage for logging` enforces that all\n  logging uses the project's logger, not the standard library directly.\n\n## Git Conventions\n\n- Always use `--signoff` (`-s`) when creating commits.\n- Do not amend commits and force push during PR review. Use new commits instead.\n- Use `git merge main` to update branches, not `git rebase`.\n- Commit messages must use [conventional commits](https://www.conventionalcommits.org/)\n  format and full sentences, not bullet points.\n- Merge `upstream/main` before pushing a branch to avoid CI failures from stale code.\n\n## Testing\n\n- Unit tests: `./scripts/unit-tests.sh` or `uv run pytest tests/unit/ -x --tb=short`\n- Run pre-commit checks: `uv run pre-commit run --all-files`\n\n### Integration Tests\n\nIntegration tests use a recording/replay system. Recordings are JSON files in\n`tests/integration/*/recordings/` keyed by SHA256 hashes of HTTP request bodies.\nWhen modifying code that changes request bodies sent to providers, recordings may\nneed to be re-recorded.\n\nRun integration tests via the CI script (same command used in GitHub Actions):\n\n```bash\n# Replay mode (default) — uses pre-recorded responses, no API keys needed\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Re-record missing recordings (requires API keys, e.g. OPENAI_API_KEY)\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --inference-mode record-if-missing \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Run a full suite\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt --suite responses\n```\n\nKey flags: `--stack-config` (required), `--setup` (`gpt`, `ollama`, `vllm`),\n`--inference-mode` (`replay`, `record`, `record-if-missing`), `--file` (single file),\n`--pattern` (pytest `-k` filter), `--suite` (`base`, `responses`, `vision`).\n\nIf a test fails in replay mode with \"Recording not found\", re-run with\n`--inference-mode record-if-missing` and commit the new recording files.\nRecording locally requires an API key for the provider under test (e.g.\n`OPENAI_API_KEY` for `--setup gpt`). If you do not have a key, repository\nmaintainers can trigger the record workflow on GitHub via\n`.github/workflows/record-integration-tests.yml`.\n\n## Provider Architecture\n\nEach provider implements a protocol (e.g., `Inference`, `Responses`, `VectorIO`) and is\nregistered in `src/ogx/providers/registry/`. Provider specs include:\n\n- `provider_type`: e.g., `remote::openai`, `inline::builtin`\n- `module`: Python module path\n- `config_class`: Pydantic config class path\n- `api_dependencies`: APIs this provider depends on\n- `deprecation_warning`: For deprecated providers (triggers runtime warning)\n- `toolgroup_id`: For tool_runtime providers that auto-register tool groups\n\nConfiguration classes must use Pydantic `Field` with `description` parameters —\nthese generate the provider documentation automatically.\n\n## Distribution Configs\n\nDistribution YAML files in `src/ogx/distributions/` are partially auto-generated.\nAfter changing provider configs, run:\n\n```bash\nuv run ./scripts/distro_codegen.py\nuv run ./scripts/provider_codegen.py\n```\n\nDo not edit generated files in `docs/docs/providers/` manually.\n\n## API Changes\n\nWhen modifying or extending APIs:\n\n1. Update models in `src/ogx_api/`\n2. Regenerate OpenAPI specs: `uv run ./scripts/run_openapi_generator.sh`\n3. Check for breaking changes — the pre-commit hook `Check API spec for breaking changes`\n   enforces backward compatibility.\n4. Include a test plan with a testing script and execution output in your PR description.\n\nThe full stability contract — HTTP API levels (`/v1alpha`, `/v1beta`, `/v1`),\nthe two `ogx-api` package surfaces (`ogx_api.types`, `ogx_api.provider`),\nconfig schema rules, and the data storage compatibility guarantees across\nZ/Y/X-stream upgrades — is documented in\n[`docs/docs/concepts/apis/api_leveling.mdx`](docs/docs/concepts/apis/api_leveling.mdx).\nRead it before adding a new API, graduating an API between levels, removing\nor renaming a field on a `v1` datatype, or changing on-disk storage schemas.\n\n## Common Patterns\n\n### Adding a new parameter to an existing API\n\n1. Add the field to the Pydantic model in `src/ogx_api/`\n2. Thread it through the provider protocol and implementation\n3. Update affected distribution configs if needed\n4. Regenerate specs and docs\n5. Add unit test cases covering the new parameter\n\n### Adding a deprecated alias for a renamed provider\n\nUse the existing `deprecation_warning` field on `InlineProviderSpec` or `RemoteProviderSpec`.\nSearch for existing examples: `grep -r \"deprecation_warning\" src/ogx/providers/registry/`\n\n### Before adding any new pattern\n\nSearch the codebase for existing examples of the same pattern first.\nUse `grep` to find how deprecation, validation, configuration, or aliasing is already\nhandled elsewhere.\n\n## Keeping Documentation Up to Date\n\nWhen making code changes, check whether the following documentation needs updating:\n\n- `README.md` — the root README contains an ASCII architecture diagram showing API\n  endpoints, inference providers, vector stores, tools/connectors, and file storage.\n  Update it when adding or removing providers, APIs, or backend integrations.\n- `ARCHITECTURE.md` — system overview, request flow, provider architecture, API layer,\n  storage, configuration, and test recording system\n- Module-level `README.md` files in key directories:\n  - `src/ogx/README.md`, `src/ogx/core/README.md`\n  - `src/ogx/core/server/README.md`, `src/ogx/core/storage/README.md`\n  - `src/ogx/core/routing_tables/README.md`\n  - `src/ogx/providers/README.md`, `src/ogx/providers/inline/README.md`\n  - `src/ogx/providers/remote/README.md`, `src/ogx/providers/registry/README.md`\n  - `src/ogx/providers/utils/README.md`, `src/ogx/providers/utils/inference/README.md`\n  - `src/ogx/providers/inline/agents/README.md`\n  - `src/ogx/providers/inline/tool_runtime/README.md`\n  - `src/ogx/providers/remote/inference/README.md`\n  - `src/ogx/distributions/README.md`\n  - `scripts/README.md`\n- `tests/README.md`, `tests/unit/README.md`, `tests/integration/README.md`\n\nThese files help LLMs and new contributors navigate the codebase. If your change\nadds, removes, or renames modules, providers, APIs, or storage backends, update\nthe relevant documentation to stay in sync.\n"},"files":{"CLAUDE.md":"See @AGENTS.md for guidelines on working with this codebase.\n\n## Design Context\n\n### Users\n\nBackend engineers, application developers, and platform teams evaluating or adopting OGX for production AI workloads. They arrive from GitHub, blog posts, or search. They already use OpenAI/Anthropic SDKs and want to know: can I point my existing code at this server and have it just work? They are practical, time-constrained, and skeptical of marketing fluff. They read docs in dark terminals, IDEs, and browser tabs at all hours.\n\n### Brand Personality\n\n**Powerful, flexible, production-grade.** Not flashy. Not cute. Not corporate. The kind of project where the README is better than most companies' entire docs site. Speaks in code examples, not marketing copy. Respects the developer's time above all else.\n\nThree words: **capable, direct, trustworthy.**\n\n### Aesthetic Direction\n\n- **Tone**: Technical confidence without pretension. Think: well-organized CLI output, a clean terminal, a tool that does exactly what it says.\n- **Theme**: Dark mode default, both supported. Dark should feel like a refined terminal environment, not \"glowing neon AI dashboard.\" Light should feel like clean paper, not washed-out gray.\n- **Anti-references**: Purple-to-blue gradients, animated gradient text, icon-in-colored-circle card grids, \"Works with 20+ providers!\" vanity stats, marquee scrolling logos, decorative mesh backgrounds. All of these are present on the current site and should be replaced.\n- **Color**: Move away from purple as primary. The logo uses a deep navy-to-teal gradient. The palette should feel grounded, not synthetic. Consider warm neutrals or muted earth tones as an alternative to the current purple/teal AI palette.\n- **Typography**: Current fonts (Space Grotesk, Inter) are on the overused list. Find something with more character that still reads as technical and trustworthy.\n\n### Design Principles\n\n1. **Show, don't decorate.** Every visual element must communicate information. No decorative gradients, glows, or animations that exist for \"wow factor.\"\n2. **Code is the hero.** The most important thing on the landing page is a working code example. Make it prominent, readable, and real.\n3. **Earn trust through clarity.** Clean structure, consistent spacing, and direct language signal competence better than any visual flourish.\n4. **Respect the scroll.** Every section must justify its existence. If it doesn't answer a question the developer has, cut it.\n5. **No AI slop.** If a pattern appears on 50 AI-generated landing pages, it doesn't belong here. When in doubt, do less.\n","AGENTS.md":"# Agent Guidelines for OGX\n\nThis file provides guidance for AI coding agents working on this codebase.\nIt complements [CONTRIBUTING.md](CONTRIBUTING.md) with agent-specific instructions.\nHuman contributors should follow the conventions in CONTRIBUTING.md.\n\n## Project Overview\n\nOGX is an API server implementing the OpenAI Responses API, Chat Completions,\nEmbeddings, and supporting APIs (files, vector stores, batches, eval, and responses guardrails). It supports\nmultiple inference backends (OpenAI, Azure, Bedrock, vLLM, Ollama, WatsonX, etc.) through\na provider architecture.\n\n## Repository Layout\n\n```text\nsrc/ogx/              # Server implementation\n  core/                       # Request routing, server, storage\n  providers/\n    inline/                   # Built-in providers (responses, eval, vector_io, etc.)\n    remote/                   # Remote provider adapters (OpenAI, Azure, vLLM, etc.)\n    registry/                 # Provider registration specs\n    utils/                    # Shared provider utilities (OpenAI mixin, MCP, etc.)\n  distributions/              # Distribution configs (starter, ci-tests, etc.)\nsrc/ogx_api/          # API definitions, Pydantic models, FastAPI routes\ntests/\n  unit/                       # Unit tests\n  integration/                # Integration tests with recording/replay system\n```\n\n## Python & Tooling\n\n- **Python 3.12** is required. Pre-commit hooks only work with 3.12.\n- Use `uv` for all dependency management and script execution.\n- Run scripts with `uv run`, never bare `python3` or `python`.\n- Use standard library modules when possible.\n- All function signatures must have type hints. Prefer Pydantic models for validation.\n- Code must pass `mypy`. Check the exclude list in `pyproject.toml` for known exceptions.\n- Use `def _function_name` for private functions.\n- Prefer explicit top-level imports over inline imports.\n- Do not use exceptions as control flow.\n\n## Code Style\n\n- Comments must add value. Do not write filler comments that describe the next line.\n- Add comments only to clarify surprising behavior that is not obvious from the code.\n- Good variable naming and clear code organization matters more than comments.\n- Do NOT remove existing comments unless they are factually wrong.\n- Error messages must be prefixed with \"Failed to ...\".\n- Use structured logging via `from ogx.log import get_logger`. Always use\n  key-value style: `logger.info(\"Processing request\", model=model_id, provider=provider)`\n  instead of f-strings or %-style formatting. The pre-commit hook\n  `Block f-string logging` enforces this.\n- The pre-commit hook `Ensure 'ogx.log' usage for logging` enforces that all\n  logging uses the project's logger, not the standard library directly.\n\n## Git Conventions\n\n- Always use `--signoff` (`-s`) when creating commits.\n- Do not amend commits and force push during PR review. Use new commits instead.\n- Use `git merge main` to update branches, not `git rebase`.\n- Commit messages must use [conventional commits](https://www.conventionalcommits.org/)\n  format and full sentences, not bullet points.\n- Merge `upstream/main` before pushing a branch to avoid CI failures from stale code.\n\n## Testing\n\n- Unit tests: `./scripts/unit-tests.sh` or `uv run pytest tests/unit/ -x --tb=short`\n- Run pre-commit checks: `uv run pre-commit run --all-files`\n\n### Integration Tests\n\nIntegration tests use a recording/replay system. Recordings are JSON files in\n`tests/integration/*/recordings/` keyed by SHA256 hashes of HTTP request bodies.\nWhen modifying code that changes request bodies sent to providers, recordings may\nneed to be re-recorded.\n\nRun integration tests via the CI script (same command used in GitHub Actions):\n\n```bash\n# Replay mode (default) — uses pre-recorded responses, no API keys needed\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Re-record missing recordings (requires API keys, e.g. OPENAI_API_KEY)\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --inference-mode record-if-missing \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Run a full suite\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt --suite responses\n```\n\nKey flags: `--stack-config` (required), `--setup` (`gpt`, `ollama`, `vllm`),\n`--inference-mode` (`replay`, `record`, `record-if-missing`), `--file` (single file),\n`--pattern` (pytest `-k` filter), `--suite` (`base`, `responses`, `vision`).\n\nIf a test fails in replay mode with \"Recording not found\", re-run with\n`--inference-mode record-if-missing` and commit the new recording files.\nRecording locally requires an API key for the provider under test (e.g.\n`OPENAI_API_KEY` for `--setup gpt`). If you do not have a key, repository\nmaintainers can trigger the record workflow on GitHub via\n`.github/workflows/record-integration-tests.yml`.\n\n## Provider Architecture\n\nEach provider implements a protocol (e.g., `Inference`, `Responses`, `VectorIO`) and is\nregistered in `src/ogx/providers/registry/`. Provider specs include:\n\n- `provider_type`: e.g., `remote::openai`, `inline::builtin`\n- `module`: Python module path\n- `config_class`: Pydantic config class path\n- `api_dependencies`: APIs this provider depends on\n- `deprecation_warning`: For deprecated providers (triggers runtime warning)\n- `toolgroup_id`: For tool_runtime providers that auto-register tool groups\n\nConfiguration classes must use Pydantic `Field` with `description` parameters —\nthese generate the provider documentation automatically.\n\n## Distribution Configs\n\nDistribution YAML files in `src/ogx/distributions/` are partially auto-generated.\nAfter changing provider configs, run:\n\n```bash\nuv run ./scripts/distro_codegen.py\nuv run ./scripts/provider_codegen.py\n```\n\nDo not edit generated files in `docs/docs/providers/` manually.\n\n## API Changes\n\nWhen modifying or extending APIs:\n\n1. Update models in `src/ogx_api/`\n2. Regenerate OpenAPI specs: `uv run ./scripts/run_openapi_generator.sh`\n3. Check for breaking changes — the pre-commit hook `Check API spec for breaking changes`\n   enforces backward compatibility.\n4. Include a test plan with a testing script and execution output in your PR description.\n\nThe full stability contract — HTTP API levels (`/v1alpha`, `/v1beta`, `/v1`),\nthe two `ogx-api` package surfaces (`ogx_api.types`, `ogx_api.provider`),\nconfig schema rules, and the data storage compatibility guarantees across\nZ/Y/X-stream upgrades — is documented in\n[`docs/docs/concepts/apis/api_leveling.mdx`](docs/docs/concepts/apis/api_leveling.mdx).\nRead it before adding a new API, graduating an API between levels, removing\nor renaming a field on a `v1` datatype, or changing on-disk storage schemas.\n\n## Common Patterns\n\n### Adding a new parameter to an existing API\n\n1. Add the field to the Pydantic model in `src/ogx_api/`\n2. Thread it through the provider protocol and implementation\n3. Update affected distribution configs if needed\n4. Regenerate specs and docs\n5. Add unit test cases covering the new parameter\n\n### Adding a deprecated alias for a renamed provider\n\nUse the existing `deprecation_warning` field on `InlineProviderSpec` or `RemoteProviderSpec`.\nSearch for existing examples: `grep -r \"deprecation_warning\" src/ogx/providers/registry/`\n\n### Before adding any new pattern\n\nSearch the codebase for existing examples of the same pattern first.\nUse `grep` to find how deprecation, validation, configuration, or aliasing is already\nhandled elsewhere.\n\n## Keeping Documentation Up to Date\n\nWhen making code changes, check whether the following documentation needs updating:\n\n- `README.md` — the root README contains an ASCII architecture diagram showing API\n  endpoints, inference providers, vector stores, tools/connectors, and file storage.\n  Update it when adding or removing providers, APIs, or backend integrations.\n- `ARCHITECTURE.md` — system overview, request flow, provider architecture, API layer,\n  storage, configuration, and test recording system\n- Module-level `README.md` files in key directories:\n  - `src/ogx/README.md`, `src/ogx/core/README.md`\n  - `src/ogx/core/server/README.md`, `src/ogx/core/storage/README.md`\n  - `src/ogx/core/routing_tables/README.md`\n  - `src/ogx/providers/README.md`, `src/ogx/providers/inline/README.md`\n  - `src/ogx/providers/remote/README.md`, `src/ogx/providers/registry/README.md`\n  - `src/ogx/providers/utils/README.md`, `src/ogx/providers/utils/inference/README.md`\n  - `src/ogx/providers/inline/agents/README.md`\n  - `src/ogx/providers/inline/tool_runtime/README.md`\n  - `src/ogx/providers/remote/inference/README.md`\n  - `src/ogx/distributions/README.md`\n  - `scripts/README.md`\n- `tests/README.md`, `tests/unit/README.md`, `tests/integration/README.md`\n\nThese files help LLMs and new contributors navigate the codebase. If your change\nadds, removes, or renames modules, providers, APIs, or storage backends, update\nthe relevant documentation to stay in sync.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"See @AGENTS.md for guidelines on working with this codebase.\n\n## Design Context\n\n### Users\n\nBackend engineers, application developers, and platform teams evaluating or adopting OGX for production AI workloads. They arrive from GitHub, blog posts, or search. They already use OpenAI/Anthropic SDKs and want to know: can I point my existing code at this server and have it just work? They are practical, time-constrained, and skeptical of marketing fluff. They read docs in dark terminals, IDEs, and browser tabs at all hours.\n\n### Brand Personality\n\n**Powerful, flexible, production-grade.** Not flashy. Not cute. Not corporate. The kind of project where the README is better than most companies' entire docs site. Speaks in code examples, not marketing copy. Respects the developer's time above all else.\n\nThree words: **capable, direct, trustworthy.**\n\n### Aesthetic Direction\n\n- **Tone**: Technical confidence without pretension. Think: well-organized CLI output, a clean terminal, a tool that does exactly what it says.\n- **Theme**: Dark mode default, both supported. Dark should feel like a refined terminal environment, not \"glowing neon AI dashboard.\" Light should feel like clean paper, not washed-out gray.\n- **Anti-references**: Purple-to-blue gradients, animated gradient text, icon-in-colored-circle card grids, \"Works with 20+ providers!\" vanity stats, marquee scrolling logos, decorative mesh backgrounds. All of these are present on the current site and should be replaced.\n- **Color**: Move away from purple as primary. The logo uses a deep navy-to-teal gradient. The palette should feel grounded, not synthetic. Consider warm neutrals or muted earth tones as an alternative to the current purple/teal AI palette.\n- **Typography**: Current fonts (Space Grotesk, Inter) are on the overused list. Find something with more character that still reads as technical and trustworthy.\n\n### Design Principles\n\n1. **Show, don't decorate.** Every visual element must communicate information. No decorative gradients, glows, or animations that exist for \"wow factor.\"\n2. **Code is the hero.** The most important thing on the landing page is a working code example. Make it prominent, readable, and real.\n3. **Earn trust through clarity.** Clean structure, consistent spacing, and direct language signal competence better than any visual flourish.\n4. **Respect the scroll.** Every section must justify its existence. If it doesn't answer a question the developer has, cut it.\n5. **No AI slop.** If a pattern appears on 50 AI-generated landing pages, it doesn't belong here. When in doubt, do less.\n","category":"root","tokens":650},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Guidelines for OGX\n\nThis file provides guidance for AI coding agents working on this codebase.\nIt complements [CONTRIBUTING.md](CONTRIBUTING.md) with agent-specific instructions.\nHuman contributors should follow the conventions in CONTRIBUTING.md.\n\n## Project Overview\n\nOGX is an API server implementing the OpenAI Responses API, Chat Completions,\nEmbeddings, and supporting APIs (files, vector stores, batches, eval, and responses guardrails). It supports\nmultiple inference backends (OpenAI, Azure, Bedrock, vLLM, Ollama, WatsonX, etc.) through\na provider architecture.\n\n## Repository Layout\n\n```text\nsrc/ogx/              # Server implementation\n  core/                       # Request routing, server, storage\n  providers/\n    inline/                   # Built-in providers (responses, eval, vector_io, etc.)\n    remote/                   # Remote provider adapters (OpenAI, Azure, vLLM, etc.)\n    registry/                 # Provider registration specs\n    utils/                    # Shared provider utilities (OpenAI mixin, MCP, etc.)\n  distributions/              # Distribution configs (starter, ci-tests, etc.)\nsrc/ogx_api/          # API definitions, Pydantic models, FastAPI routes\ntests/\n  unit/                       # Unit tests\n  integration/                # Integration tests with recording/replay system\n```\n\n## Python & Tooling\n\n- **Python 3.12** is required. Pre-commit hooks only work with 3.12.\n- Use `uv` for all dependency management and script execution.\n- Run scripts with `uv run`, never bare `python3` or `python`.\n- Use standard library modules when possible.\n- All function signatures must have type hints. Prefer Pydantic models for validation.\n- Code must pass `mypy`. Check the exclude list in `pyproject.toml` for known exceptions.\n- Use `def _function_name` for private functions.\n- Prefer explicit top-level imports over inline imports.\n- Do not use exceptions as control flow.\n\n## Code Style\n\n- Comments must add value. Do not write filler comments that describe the next line.\n- Add comments only to clarify surprising behavior that is not obvious from the code.\n- Good variable naming and clear code organization matters more than comments.\n- Do NOT remove existing comments unless they are factually wrong.\n- Error messages must be prefixed with \"Failed to ...\".\n- Use structured logging via `from ogx.log import get_logger`. Always use\n  key-value style: `logger.info(\"Processing request\", model=model_id, provider=provider)`\n  instead of f-strings or %-style formatting. The pre-commit hook\n  `Block f-string logging` enforces this.\n- The pre-commit hook `Ensure 'ogx.log' usage for logging` enforces that all\n  logging uses the project's logger, not the standard library directly.\n\n## Git Conventions\n\n- Always use `--signoff` (`-s`) when creating commits.\n- Do not amend commits and force push during PR review. Use new commits instead.\n- Use `git merge main` to update branches, not `git rebase`.\n- Commit messages must use [conventional commits](https://www.conventionalcommits.org/)\n  format and full sentences, not bullet points.\n- Merge `upstream/main` before pushing a branch to avoid CI failures from stale code.\n\n## Testing\n\n- Unit tests: `./scripts/unit-tests.sh` or `uv run pytest tests/unit/ -x --tb=short`\n- Run pre-commit checks: `uv run pre-commit run --all-files`\n\n### Integration Tests\n\nIntegration tests use a recording/replay system. Recordings are JSON files in\n`tests/integration/*/recordings/` keyed by SHA256 hashes of HTTP request bodies.\nWhen modifying code that changes request bodies sent to providers, recordings may\nneed to be re-recorded.\n\nRun integration tests via the CI script (same command used in GitHub Actions):\n\n```bash\n# Replay mode (default) — uses pre-recorded responses, no API keys needed\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Re-record missing recordings (requires API keys, e.g. OPENAI_API_KEY)\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt \\\n  --inference-mode record-if-missing \\\n  --file tests/integration/responses/test_compact_responses.py\n\n# Run a full suite\nuv run --no-sync ./scripts/integration-tests.sh \\\n  --stack-config server:ci-tests --setup gpt --suite responses\n```\n\nKey flags: `--stack-config` (required), `--setup` (`gpt`, `ollama`, `vllm`),\n`--inference-mode` (`replay`, `record`, `record-if-missing`), `--file` (single file),\n`--pattern` (pytest `-k` filter), `--suite` (`base`, `responses`, `vision`).\n\nIf a test fails in replay mode with \"Recording not found\", re-run with\n`--inference-mode record-if-missing` and commit the new recording files.\nRecording locally requires an API key for the provider under test (e.g.\n`OPENAI_API_KEY` for `--setup gpt`). If you do not have a key, repository\nmaintainers can trigger the record workflow on GitHub via\n`.github/workflows/record-integration-tests.yml`.\n\n## Provider Architecture\n\nEach provider implements a protocol (e.g., `Inference`, `Responses`, `VectorIO`) and is\nregistered in `src/ogx/providers/registry/`. Provider specs include:\n\n- `provider_type`: e.g., `remote::openai`, `inline::builtin`\n- `module`: Python module path\n- `config_class`: Pydantic config class path\n- `api_dependencies`: APIs this provider depends on\n- `deprecation_warning`: For deprecated providers (triggers runtime warning)\n- `toolgroup_id`: For tool_runtime providers that auto-register tool groups\n\nConfiguration classes must use Pydantic `Field` with `description` parameters —\nthese generate the provider documentation automatically.\n\n## Distribution Configs\n\nDistribution YAML files in `src/ogx/distributions/` are partially auto-generated.\nAfter changing provider configs, run:\n\n```bash\nuv run ./scripts/distro_codegen.py\nuv run ./scripts/provider_codegen.py\n```\n\nDo not edit generated files in `docs/docs/providers/` manually.\n\n## API Changes\n\nWhen modifying or extending APIs:\n\n1. Update models in `src/ogx_api/`\n2. Regenerate OpenAPI specs: `uv run ./scripts/run_openapi_generator.sh`\n3. Check for breaking changes — the pre-commit hook `Check API spec for breaking changes`\n   enforces backward compatibility.\n4. Include a test plan with a testing script and execution output in your PR description.\n\nThe full stability contract — HTTP API levels (`/v1alpha`, `/v1beta`, `/v1`),\nthe two `ogx-api` package surfaces (`ogx_api.types`, `ogx_api.provider`),\nconfig schema rules, and the data storage compatibility guarantees across\nZ/Y/X-stream upgrades — is documented in\n[`docs/docs/concepts/apis/api_leveling.mdx`](docs/docs/concepts/apis/api_leveling.mdx).\nRead it before adding a new API, graduating an API between levels, removing\nor renaming a field on a `v1` datatype, or changing on-disk storage schemas.\n\n## Common Patterns\n\n### Adding a new parameter to an existing API\n\n1. Add the field to the Pydantic model in `src/ogx_api/`\n2. Thread it through the provider protocol and implementation\n3. Update affected distribution configs if needed\n4. Regenerate specs and docs\n5. Add unit test cases covering the new parameter\n\n### Adding a deprecated alias for a renamed provider\n\nUse the existing `deprecation_warning` field on `InlineProviderSpec` or `RemoteProviderSpec`.\nSearch for existing examples: `grep -r \"deprecation_warning\" src/ogx/providers/registry/`\n\n### Before adding any new pattern\n\nSearch the codebase for existing examples of the same pattern first.\nUse `grep` to find how deprecation, validation, configuration, or aliasing is already\nhandled elsewhere.\n\n## Keeping Documentation Up to Date\n\nWhen making code changes, check whether the following documentation needs updating:\n\n- `README.md` — the root README contains an ASCII architecture diagram showing API\n  endpoints, inference providers, vector stores, tools/connectors, and file storage.\n  Update it when adding or removing providers, APIs, or backend integrations.\n- `ARCHITECTURE.md` — system overview, request flow, provider architecture, API layer,\n  storage, configuration, and test recording system\n- Module-level `README.md` files in key directories:\n  - `src/ogx/README.md`, `src/ogx/core/README.md`\n  - `src/ogx/core/server/README.md`, `src/ogx/core/storage/README.md`\n  - `src/ogx/core/routing_tables/README.md`\n  - `src/ogx/providers/README.md`, `src/ogx/providers/inline/README.md`\n  - `src/ogx/providers/remote/README.md`, `src/ogx/providers/registry/README.md`\n  - `src/ogx/providers/utils/README.md`, `src/ogx/providers/utils/inference/README.md`\n  - `src/ogx/providers/inline/agents/README.md`\n  - `src/ogx/providers/inline/tool_runtime/README.md`\n  - `src/ogx/providers/remote/inference/README.md`\n  - `src/ogx/distributions/README.md`\n  - `scripts/README.md`\n- `tests/README.md`, `tests/unit/README.md`, `tests/integration/README.md`\n\nThese files help LLMs and new contributors navigate the codebase. If your change\nadds, removes, or renames modules, providers, APIs, or storage backends, update\nthe relevant documentation to stay in sync.\n","category":"root","tokens":2267}]}