mirror of https://github.com/openai/codex.git synced 2026-05-14 16:22:51 +00:00

Files

Ahmed Ibrahim b4bc02439f [4/8] Define Python SDK public API surface (#21896 )

## Why

The SDK package root should be the ergonomic public client API, not a
dump of every generated app-server schema type. Generated models still
need a supported import path, but callers should be able to tell which
names are high-level SDK entrypoints and which names are protocol value
models.

## What

- Define a curated root `__all__` for clients, handles, input helpers,
retry helpers, config, and public errors.
- Add a `types` module as the supported home for generated app-server
response, event, enum, and helper models.
- Update docs and examples to import protocol/value models from the type
module.
- Add tests that lock root exports, type-module exports, star-import
behavior, and example import hygiene.

## Stack

1. #21891 `[1/8]` Pin Python SDK runtime dependency
2. #21893 `[2/8]` Generate Python SDK types from pinned runtime
3. #21895 `[3/8]` Run Python SDK tests in CI
4. This PR `[4/8]` Define Python SDK public API surface
5. #21905 `[5/8]` Rename Python SDK package to `openai-codex`
6. #21910 `[6/8]` Add high-level Python SDK approval mode
7. #22014 `[7/8]` Add Python SDK app-server integration harness
8. #22021 `[8/8]` Add Python SDK Ruff formatting

## Verification

- Added public API signature tests for root exports, `types` exports,
and example imports.

---------

Co-authored-by: Codex <noreply@openai.com>

2026-05-12 00:57:44 +03:00

3.2 KiB

Raw Blame History

Getting Started

This is the fastest path from install to a multi-turn thread using the public SDK surface.

The SDK is experimental. Treat the API, bundled runtime strategy, and packaging details as unstable until the first public release.

1) Install

From repo root:

cd sdk/python
uv sync
source .venv/bin/activate

Requirements:

Python >=3.10
uv
installed openai-codex-cli-bin runtime package, or an explicit codex_bin override
local Codex auth/session configured

2) Run your first turn (sync)

from codex_app_server import Codex

with Codex() as codex:
    server = codex.metadata.serverInfo
    print("Server:", None if server is None else server.name, None if server is None else server.version)

    thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
    result = thread.run("Say hello in one sentence.")

    print("Thread:", thread.id)
    print("Text:", result.final_response)
    print("Items:", len(result.items))

What happened:

Codex() started and initialized codex app-server.
thread_start(...) created a thread.
thread.run("...") started a turn, consumed events until completion, and returned the final assistant response plus collected items and usage.
result.final_response is None when no final-answer or phase-less assistant message item completes for the turn.
use thread.turn(...) when you need a TurnHandle for streaming, steering, interrupting, or turn IDs/status
one client can consume multiple active turns concurrently; turn streams are routed by turn ID

3) Continue the same thread (multi-turn)

from codex_app_server import Codex

with Codex() as codex:
    thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})

    first = thread.run("Summarize Rust ownership in 2 bullets.")
    second = thread.run("Now explain it to a Python developer.")

    print("first:", first.final_response)
    print("second:", second.final_response)

4) Async parity

Use async with AsyncCodex() as the normal async entrypoint. AsyncCodex initializes lazily, and context entry makes startup/shutdown explicit.

import asyncio
from codex_app_server import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
        result = await thread.run("Continue where we left off.")
        print(result.final_response)


asyncio.run(main())

5) Resume an existing thread

from codex_app_server import Codex

THREAD_ID = "thr_123"  # replace with a real id

with Codex() as codex:
    thread = codex.thread_resume(THREAD_ID)
    result = thread.run("Continue where we left off.")
    print(result.final_response)

6) Public app-server types

The convenience wrappers live at the package root. Public app-server value and event types live under:

from codex_app_server.types import ThreadReadResponse, Turn, TurnStatus

7) Next stops

API surface and signatures: docs/api-reference.md
Common decisions/pitfalls: docs/faq.md
End-to-end runnable examples: examples/README.md

3.2 KiB Raw Blame History