mirror of
https://github.com/openai/codex.git
synced 2026-04-26 07:35:29 +00:00
9b3332e62f
…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>
96 lines
2.9 KiB
Markdown
96 lines
2.9 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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
|
||
|
||
```python
|
||
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:
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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`.
|