codex/sdk/python/README.md

Codex App Server Python SDK (Experimental)

Experimental Python SDK for codex app-server JSON-RPC v2. The generated wire models come from the bundled v2 schema and use snake_case Python fields while preserving camelCase wire serialization.

It gives you a small typed API for:

• starting or resuming threads
• creating turns from Python
• streaming events or waiting for a final TurnResult
• using the same shape in sync and async code

Experimental

This SDK is still experimental.

• it is not published yet
• API details may still change before the first release
• packaging and release workflow are still evolving

Use it for local development, dogfooding, and iteration inside this repo. Do not treat it as a stable public package yet.

What You Need

• Python >=3.10
• local Codex auth/session already configured
• this repo checked out locally

Install From Source

cd sdk/python
python -m pip install -e .

The package includes bundled Codex runtime binaries and automatically selects the binary for the current platform through AppServerConfig().codex_bin.

Core Model

The public API is intentionally small:

• Codex / AsyncCodex: session entrypoint
• Thread / AsyncThread: a conversation thread
• Turn / AsyncTurn: one user turn within a thread
• TurnResult: final status, text, items, and usage

Typical flow:

1. create a Codex client
2. start or resume a thread
3. create a turn from input
4. call run() or iterate stream()

Quickstart

Sync

from codex_app_server import Codex, TextInput

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5",
        config={"model_reasoning_effort": "high"},
    )
    result = thread.turn(TextInput("Say hello in one sentence.")).run()

    print("status:", result.status)
    print("text:", result.text)

Async

import asyncio

from codex_app_server import AsyncCodex, TextInput


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(
            model="gpt-5",
            config={"model_reasoning_effort": "high"},
        )
        turn = await thread.turn(TextInput("Say hello in one sentence."))
        result = await turn.run()

        print("status:", result.status)
        print("text:", result.text)


asyncio.run(main())

Current Limitations

• Only one active Turn.stream() or Turn.run() consumer is supported per client instance.
• Starting a second active turn consumer on the same Codex or AsyncCodex raises RuntimeError.
• Codex() is eager and performs startup plus initialize in the constructor.

Behavior Notes

• AsyncCodex is intended to be used with async with AsyncCodex() as codex:.
• TurnResult.text prefers streamed assistant deltas and falls back to completed raw response items when no deltas are emitted.
• For transient overload handling, use retry_on_overload(...).

Learn By Example

Runnable examples:

cd sdk/python
python examples/01_quickstart_constructor/sync.py
python examples/01_quickstart_constructor/async.py

More docs:

• Getting started: docs/getting-started.md
• API reference: docs/api-reference.md
• FAQ and pitfalls: docs/faq.md
• Examples index: examples/README.md
• Notebook walkthrough: notebooks/sdk_walkthrough.ipynb

Maintainer Workflow

Refresh bundled binaries and generated artifacts with:

cd sdk/python
python scripts/update_sdk_artifacts.py --channel stable --bundle-all-platforms

or:

cd sdk/python
python scripts/update_sdk_artifacts.py --channel alpha --bundle-all-platforms

Compatibility

• Package name: codex-app-server-sdk
• SDK version in this repo: 0.2.0
• Target protocol: Codex app-server JSON-RPC v2