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

Files

Owen Lin 9b3332e62f fix(python-sdk): stop checking in codex binaries; stage pinned runtim… (#14232 )

…e package

## Summary

This changes the Python SDK packaging model so we no longer commit
`codex`
binaries into `sdk/python`.

Instead, published SDK builds now depend on a separate `codex-cli-bin`
runtime
package that carries the platform-specific `codex` binary. The SDK and
runtime
can be staged together with an exact version pin, so the published
Python SDK
still resolves to a Codex version we know is compatible.

The SDK now resolves `codex` in this order:

- `AppServerConfig.codex_bin` if explicitly set
- installed `codex-cli-bin` runtime package

There is no `PATH` fallback anymore. Published installs either use the
pinned
runtime or fail loudly, and local development uses an explicit
`codex_bin`
override when working from the repo.

## What changed

- removed checked-in binaries from `sdk/python/src/codex_app_server/bin`
- changed `AppServerClient` to resolve `codex` from:
  - explicit `AppServerConfig.codex_bin`
  - installed `codex-cli-bin`
- kept `AppServerConfig.codex_bin` override support for local/dev use
- added a new `sdk/python-runtime` package template for the pinned
runtime
- updated `scripts/update_sdk_artifacts.py` to stage releasable
SDK/runtime
  packages instead of downloading binaries into the repo
- made `codex-cli-bin` build as a platform-specific wheel
- made `codex-cli-bin` wheel-only by rejecting `sdist` builds
- updated docs/tests to match the new packaging flow and explicit
local-dev
  contract

## Why

Checking in six platform binaries made the repo much heavier and tied
normal
source changes to release artifacts.

This keeps the compatibility guarantees we want, but moves them into
packaging:

- the published SDK can depend on an exact `codex-cli-bin==...`
- the runtime package carries the platform-specific binary
- users still get a pinned runtime
- the repo no longer needs to store those binaries

It also makes the runtime contract stricter and more predictable:

- published installs never silently fall back to an arbitrary `codex` on
`PATH`
- local development remains supported through explicit `codex_bin`
- `codex-cli-bin` is distributed as platform wheels only, which avoids
unsafe
source-distribution installs for a package that embeds a prebuilt binary

## Validation

- ran targeted Python SDK tests:
- `python3 -m pytest
sdk/python/tests/test_artifact_workflow_and_binaries.py
sdk/python/tests/test_client_rpc_methods.py
sdk/python/tests/test_contract_generation.py`
- exercised the staging flow with a local dummy binary to verify
SDK/runtime
  staging end to end
- verified the staged runtime package builds a platform-specific wheel
(`Root-Is-Purelib: false`) rather than a universal `py3-none-any` wheel
- added test coverage for the explicit-only runtime resolution model
- added test coverage that `codex-cli-bin` rejects `sdist` builds

---------

Co-authored-by: sdcoffey <stevendcoffey@gmail.com>

2026-03-10 13:53:08 -07:00

2.9 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 .

Published SDK builds pin an exact codex-cli-bin runtime dependency. For local repo development, pass AppServerConfig(codex_bin=...) to point at a local build explicitly.

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

Runtime packaging

The repo no longer checks codex binaries into sdk/python.

Published SDK builds are pinned to an exact codex-cli-bin package version, and that runtime package carries the platform-specific binary for the target wheel.

For local repo development, the checked-in sdk/python-runtime package is only a template for staged release artifacts. Editable installs should use an explicit codex_bin override instead.

Maintainer workflow

cd sdk/python
python scripts/update_sdk_artifacts.py generate-types
python scripts/update_sdk_artifacts.py \
  stage-sdk \
  /tmp/codex-python-release/codex-app-server-sdk \
  --runtime-version 1.2.3
python scripts/update_sdk_artifacts.py \
  stage-runtime \
  /tmp/codex-python-release/codex-cli-bin \
  /path/to/codex \
  --runtime-version 1.2.3

This supports the CI release flow:

run generate-types before packaging
stage codex-app-server-sdk once with an exact codex-cli-bin==... dependency
stage codex-cli-bin on each supported platform runner with the same pinned runtime version
build and publish codex-cli-bin as platform wheels only; do not publish an sdist

Compatibility and versioning

Package: codex-app-server-sdk
Runtime package: codex-cli-bin
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.9 KiB Raw Blame History Unescape Escape