ogx: Instructions file for Codex

Agent Guidelines for OGX

This file provides guidance for AI coding agents working on this codebase. It complements CONTRIBUTING.md with agent-specific instructions. Human contributors should follow the conventions in CONTRIBUTING.md.

Project Overview

OGX is an API server implementing the OpenAI Responses API, Chat Completions, Embeddings, and supporting APIs (files, vector stores, batches, eval, and responses guardrails). It supports multiple inference backends (OpenAI, Azure, Bedrock, vLLM, Ollama, WatsonX, etc.) through a provider architecture.

Repository Layout

src/ogx/              # Server implementation
  core/                       # Request routing, server, storage
  providers/
    inline/                   # Built-in providers (responses, eval, vector_io, etc.)
    remote/                   # Remote provider adapters (OpenAI, Azure, vLLM, etc.)
    registry/                 # Provider registration specs
    utils/                    # Shared provider utilities (OpenAI mixin, MCP, etc.)
  distributions/              # Distribution configs (starter, ci-tests, etc.)
src/ogx_api/          # API definitions, Pydantic models, FastAPI routes
tests/
  unit/                       # Unit tests
  integration/                # Integration tests with recording/replay system

Python & Tooling

• Python 3.12 is required. Pre-commit hooks only work with 3.12.
• Use uv for all dependency management and script execution.
• Run scripts with uv run, never bare python3 or python.
• Use standard library modules when possible.
• All function signatures must have type hints. Prefer Pydantic models for validation.
• Code must pass mypy. Check the exclude list in pyproject.toml for known exceptions.
• Use def _function_name for private functions.
• Prefer explicit top-level imports over inline imports.
• Do not use exceptions as control flow.

Code Style

• Comments must add value. Do not write filler comments that describe the next line.
• Add comments only to clarify surprising behavior that is not obvious from the code.
• Good variable naming and clear code organization matters more than comments.
• Do NOT remove existing comments unless they are factually wrong.
• Error messages must be prefixed with "Failed to ...".
• Use structured logging via from ogx.log import get_logger. Always use key-value style: logger.info("Processing request", model=model_id, provider=provider) instead of f-strings or %-style formatting. The pre-commit hook Block f-string logging enforces this.
• The pre-commit hook Ensure 'ogx.log' usage for logging enforces that all logging uses the project's logger, not the standard library directly.
• Use httpx2 for all HTTP client code. The pre-commit hook Block direct httpx imports (use httpx2) rejects import httpx / from httpx import unless the line is marked # allow-direct-httpx. The marked exceptions are deliberate boundaries: the google-genai client option (vertexai/utils.py), the mcp 1.x SDK (utils/tools/mcp.py), the generated client-SDK boundary (library_client.py, api_recorder.py), and the dual exception mapping (core/exceptions/mapping.py).