mirror of https://github.com/openai/codex.git synced 2026-04-25 07:05:38 +00:00

Files

Shaqayeq 6baeec68bd python-sdk: generated type foundation (all v2 schemas) (#13953 )

## Summary
Foundation PR only (base for PR #3).

This PR contains the SDK runtime foundation and generated artifacts:

- pinned runtime binary in `sdk/python/bin/` (`codex` or `codex.exe` by
platform)
- single maintenance script:
`sdk/python/scripts/update_sdk_artifacts.py`
- generated protocol/types artifacts under:
  - `sdk/python/src/codex_app_server/generated/protocol_types.py`
  - `sdk/python/src/codex_app_server/generated/schema_types.py`
  - `sdk/python/src/codex_app_server/generated/v2_all/*`
- generation-contract test wiring (`tests/test_contract_generation.py`)

## Release asset behavior
`update_sdk_artifacts.py` now:
- selects latest release by channel (`--channel stable|alpha`)
- resolves the correct asset for current OS/arch
- extracts platform binary (`codex` on macOS/Linux, `codex.exe` on
Windows)
- keeps runtime on single pinned binary source in `sdk/python/bin/`

## Scope boundary
- ✅ PR #2 = binary + generation pipeline + generated types foundation
- ❌ PR #2 does **not** include examples/integration logic polish (that
is PR #3)

## Validation
- Ran: `python scripts/update_sdk_artifacts.py --channel stable`
- Regenerated and committed resulting generated artifacts
- Local tests pass on branch

2026-03-10 01:00:46 -07:00

2.4 KiB

Raw Blame History

Codex App Server Python SDK (Experimental)

Experimental Python SDK for codex app-server JSON-RPC v2 over stdio, with a small default surface optimized for real scripts and apps.

The generated wire-model layer is currently sourced from the bundled v2 schema and exposed as Pydantic models with snake_case Python fields that serialize back to the app-server’s camelCase wire format.

Install

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

Quickstart

from codex_app_server import Codex, TextInput

with Codex() as codex:
    thread = codex.thread_start(model="gpt-5")
    result = thread.turn(TextInput("Say hello in one sentence.")).run()
    print(result.text)

Docs map

Golden path tutorial: docs/getting-started.md
API reference (signatures + behavior): docs/api-reference.md
Common decisions and pitfalls: docs/faq.md
Runnable examples index: examples/README.md
Jupyter walkthrough notebook: notebooks/sdk_walkthrough.ipynb

Examples

Start here:

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

Bundled runtime binaries (out of the box)

The SDK ships with platform-specific bundled binaries, so end users do not need updater scripts.

Runtime binary source (single source, no fallback):

src/codex_app_server/bin/darwin-arm64/codex
src/codex_app_server/bin/darwin-x64/codex
src/codex_app_server/bin/linux-arm64/codex
src/codex_app_server/bin/linux-x64/codex
src/codex_app_server/bin/windows-arm64/codex.exe
src/codex_app_server/bin/windows-x64/codex.exe

Maintainer workflow (refresh binaries/types)

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

This refreshes all bundled OS/arch binaries and regenerates protocol-derived Python types.

Compatibility and versioning

Package: codex-app-server-sdk
Current SDK version in this repo: 0.2.0
Python: >=3.10
Target protocol: Codex app-server JSON-RPC v2
Recommendation: keep SDK and codex CLI reasonably up to date together

Notes

Codex() is eager and performs startup + initialize in the constructor.
Use context managers (with Codex() as codex:) to ensure shutdown.
For transient overload, use codex_app_server.retry.retry_on_overload.

2.4 KiB Raw Blame History Unescape Escape