codex-ai

Gemini-first API helpers for the Codex ecosystem. The active surface is direct Gemini text, JSON, Gemini image, and Imagen generation. OpenAI provides modern Responses API text, structured JSON, and streaming helpers. The router/dispatcher layer is kept for legacy text workflows.

Install

pip install codex-ai
pip install "codex-ai[gemini]"
pip install "codex-ai[openai]"
pip install "codex-ai[openai,gemini]"

Requires Python 3.12 or newer.

Optional agent skill

Starting with version 0.2.6, the package includes an offline guide for agents integrating codex-ai into another project. Installing the Python package alone does not change that project's files. Install the guide explicitly:

python -m codex_ai.agent_skills install --project /path/to/project

The installer manages .agents/skills/codex-ai/ and a marked instruction block in the target project's AGENTS.md. It preserves unrelated content and refuses to overwrite local changes to managed files. See the agent skill installation guide for status, package upgrades, updates, deletion, and Windows examples. The installer itself needs no provider SDK extra.

Gemini Direct API

from pathlib import Path

from pydantic import BaseModel

from codex_ai import GeminiProvider, ImageInput


class LootItem(BaseModel):
    name: str
    power: int


gemini = GeminiProvider(api_key="AIza...")

text = await gemini.generate_text("Write one short tavern rumor.")
loot = await gemini.generate_json("Create one loot item.", schema=LootItem)
image_bytes, content_type = await gemini.generate_image_bytes(
    "Square tactical dark fantasy ruined capital city map, no labels.",
    model="gemini-3-pro-image-preview",
    response_mime_type="image/png",
    image_config={"aspect_ratio": "1:1", "image_size": "4K"},
)

source_image_bytes = Path("source.png").read_bytes()
edited_bytes, edited_content_type = await gemini.generate_image_bytes(
    "Keep the composition, but redraw it as a watercolor map.",
    response_mime_type="image/png",
    input_images=[ImageInput(data=source_image_bytes, mime_type="image/png")],
)

imagen_bytes, imagen_content_type = await gemini.generate_imagen_bytes(
    "A fantasy clan banner, game icon style.",
    response_mime_type="image/jpeg",
)

answer(prompt) remains available as a compatibility wrapper for text generation.

generate_image_bytes() targets Gemini image models through generate_content and treats response_mime_type as a preferred/fallback MIME type. It does not pass image MIME values to Gemini's text response_mime_type config field. Pass Gemini image controls such as aspect_ratio and image_size with image_config; if a 4K request is rejected, the Gemini provider retries once with 2K. Pass input_images with ImageInput items to provide reference/edit-source images for Gemini image models. Use generate_imagen_bytes() for Imagen models; that path uses generate_images and passes the requested MIME as output_mime_type.

OpenAI Responses API

from pydantic import BaseModel

from codex_ai import OpenAIProvider


class LootItem(BaseModel):
    name: str
    power: int


openai = OpenAIProvider(api_key="sk-...")

text = await openai.generate_text("Write one short tavern rumor.")
loot = await openai.generate_json("Create one loot item.", schema=LootItem)

async for chunk in openai.stream_text("Tell a short story."):
    print(chunk, end="")

The OpenAI provider uses the Responses API and the openai 2.x SDK. Responses are not stored by default. Its default gpt-5.6-luna model uses reasoning={"effort": "none"} to retain a cost- and latency-sensitive role; override the model and reasoning options per request when a workload needs more capability.

Legacy Text Router

from codex_ai import GeminiProvider, LLMDispatcher, LLMMessage, LLMRouter, PromptResult

router = LLMRouter()


@router.prompt("chat")
async def build_chat(text: str, **kw) -> PromptResult:
    return PromptResult(
        messages=[LLMMessage(role="user", content=text)],
        system="You are a helpful assistant.",
    )


dispatcher = LLMDispatcher(provider=GeminiProvider(api_key="AIza..."))
dispatcher.include_router(router)

response = await dispatcher.process("chat", text="Hello!")

Use this path only when you already have prompt builders registered through LLMRouter. New Gemini integrations should call generate_text(), generate_json(), generate_image_bytes(), or generate_imagen_bytes() directly.

Modules

Development

uv sync --extra dev
uv run pytest
uv run mypy src/
uv run pre-commit run --all-files
uv build --no-sources

Documentation

Full docs with architecture, API reference, and data flow diagrams:

codexdlc.github.io/codex-ai