Python SDK (Local)

# SpawnCodex SDK Documentation

A static, double-click documentation set for the local Python SDK wrapper around `codex exec`. The SDK now supports sync + async execution, live streaming, retries/backoff, and persistent named sessions.

### Run Codex from Python

Use `run()` and `run_prompt()` for deterministic non-interactive tasks.

### Async API

Use `run_async()`, `resume_async()`, and async live runs for asyncio workflows.

### Stream Events Live

Use `run_live()`/`run_live_async()` to consume JSONL events as they arrive.

### Retry Policy

Use `RetryPolicy` on `CodexLocalClient` for built-in backoff retries.

### Telemetry Hooks

Use `event_hook` to capture structured command/retry/live/session events.

### Persistent Sessions

Use `JsonFileSessionStore` with session names to resume across process restarts.

### Schema Output

Use `run_with_schema()` to constrain final output with JSON Schema.

## SDK Capabilities

- Typed request/result models with thread IDs, turn status, usage, and helper properties.
- Sync and async execution methods for run/resume/thread flows.
- Live streaming support for both `subprocess.Popen` and asyncio subprocess APIs.
- Retry/backoff policy with jitter, timeout handling, and total retry-window limits.
- Pluggable session stores: in-memory and JSON-file persistence.
- Session metadata records with bounded turn history and legacy-file migration.
- Structured observability events via `CodexClientEvent` + `event_hook`.
- Large unit test suite covering sync, live, async, retries, and session-store behavior.

## Quick Start in 30 Seconds

    from codex_local_sdk import CodexExecRequest, CodexLocalClient, RetryPolicy, SandboxMode

    client = CodexLocalClient(
        retry_policy=RetryPolicy(max_attempts=3, initial_backoff_seconds=0.5, jitter_ratio=0.2),
    )

    result = client.run(
        CodexExecRequest(
            prompt="Summarize this repository in 5 bullets.",
            sandbox=SandboxMode.READ_ONLY,
        ),
        timeout_seconds=120,
    )
    print(result.final_message)

See full setup on the Getting Started page.

## Documentation Structure

Page | Purpose | Best For
--- | --- | ---
Getting Started | Install, async setup, retries, and persistent sessions. | Initial SDK onboarding.
API Reference | Full class/method reference including async and stores. | Implementation and integration work.
Live Runs & Threads | Streaming, session continuation, and async live patterns. | Automation and orchestration.
Examples Cookbook | Scenario-based snippets and runnable example mapping. | Copy/paste starting points.
Testing & Quality | Suite layout and quality checks for new features. | Contributors and maintainers.