mirror of
https://github.com/openai/codex.git
synced 2026-05-05 03:47:01 +00:00
0127cef5db
This is PR 2 of the Python SDK PyPI publishing split. [PR 1](https://github.com/openai/codex/pull/18862) refreshed the generated SDK bindings; this PR makes the runtime package itself publishable, and PR 3 will wire the SDK package/version pinning to this runtime package. ## Summary - Rename the runtime distribution to `openai-codex-cli-bin` while keeping the import package as `codex_cli_bin`. - Make the runtime package wheel-only and build `py3-none-<platform>` wheels instead of interpreter-specific wheels. - Add `stage-runtime --codex-version` and `--platform-tag` so release staging can produce the platform wheel matrix from Codex release tags. - Add focused artifact workflow tests for version normalization, platform tag injection, and runtime wheel metadata. ## Why Rename There is already an unofficial PyPI package, [`codex-bin`](https://pypi.org/project/codex-bin/), distributing OpenAI Codex binaries. Publishing the official SDK runtime dependency as `openai-codex-cli-bin` makes the ownership clear, avoids confusing the SDK-pinned runtime wheel with that unowned wrapper, and keeps the import package unchanged as `codex_cli_bin`. ## Tests - `uv run --extra dev pytest tests/test_artifact_workflow_and_binaries.py` -> 21 passed - `uv run --extra dev python scripts/update_sdk_artifacts.py stage-runtime /tmp/codex-python-pr2-rebased/runtime-stage /tmp/codex-python-pr2-rebased/codex --codex-version rust-v0.116.0-alpha.1 --platform-tag macosx_11_0_arm64` - `uv run --with build --extra dev python -m build --wheel /tmp/codex-python-pr2-rebased/runtime-stage` - `uv run --with twine --extra dev twine check /tmp/codex-python-pr2-rebased/runtime-stage/dist/openai_codex_cli_bin-0.116.0a1-py3-none-macosx_11_0_arm64.whl` ## Note - Full `uv run --extra dev pytest` currently fails because regenerating from schemas already on `main` adds new DeviceKey Python types. I left that generated catch-up out of this runtime-only PR.
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# Python SDK Examples
|
|
|
|
Each example folder contains runnable versions:
|
|
|
|
- `sync.py` (public sync surface: `Codex`)
|
|
- `async.py` (public async surface: `AsyncCodex`)
|
|
|
|
All examples intentionally use only public SDK exports from `codex_app_server`.
|
|
|
|
## Prerequisites
|
|
|
|
- Python `>=3.10`
|
|
- Install SDK dependencies for the same Python interpreter you will use to run examples
|
|
|
|
Recommended setup (from `sdk/python`):
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
python -m pip install -U pip
|
|
python -m pip install -e .
|
|
```
|
|
|
|
When running examples from this repo checkout, the SDK source uses the local
|
|
tree and does not bundle a runtime binary. The helper in `examples/_bootstrap.py`
|
|
uses the installed `openai-codex-cli-bin` runtime package.
|
|
|
|
If the pinned `openai-codex-cli-bin` runtime is not already installed, the bootstrap
|
|
will download the matching GitHub release artifact, stage a temporary local
|
|
`openai-codex-cli-bin` package, install it into your active interpreter, and clean up
|
|
the temporary files afterward.
|
|
|
|
Current pinned runtime version: `0.116.0-alpha.1`
|
|
|
|
## Run examples
|
|
|
|
From `sdk/python`:
|
|
|
|
```bash
|
|
python examples/<example-folder>/sync.py
|
|
python examples/<example-folder>/async.py
|
|
```
|
|
|
|
The examples bootstrap local imports from `sdk/python/src` automatically, so no
|
|
SDK wheel install is required. You only need the Python dependencies for your
|
|
active interpreter and an installed `openai-codex-cli-bin` runtime package (either
|
|
already present or automatically provisioned by the bootstrap).
|
|
|
|
## Recommended first run
|
|
|
|
```bash
|
|
python examples/01_quickstart_constructor/sync.py
|
|
python examples/01_quickstart_constructor/async.py
|
|
```
|
|
|
|
## Index
|
|
|
|
- `01_quickstart_constructor/`
|
|
- first run / sanity check
|
|
- `02_turn_run/`
|
|
- inspect full turn output fields
|
|
- `03_turn_stream_events/`
|
|
- stream a turn with a small curated event view
|
|
- `04_models_and_metadata/`
|
|
- discover visible models for the connected runtime
|
|
- `05_existing_thread/`
|
|
- resume a real existing thread (created in-script)
|
|
- `06_thread_lifecycle_and_controls/`
|
|
- thread lifecycle + control calls
|
|
- `07_image_and_text/`
|
|
- remote image URL + text multimodal turn
|
|
- `08_local_image_and_text/`
|
|
- local image + text multimodal turn using a generated temporary sample image
|
|
- `09_async_parity/`
|
|
- parity-style sync flow (see async parity in other examples)
|
|
- `10_error_handling_and_retry/`
|
|
- overload retry pattern + typed error handling structure
|
|
- `11_cli_mini_app/`
|
|
- interactive chat loop
|
|
- `12_turn_params_kitchen_sink/`
|
|
- structured output with a curated advanced `turn(...)` configuration
|
|
- `13_model_select_and_turn_params/`
|
|
- list models, pick highest model + highest supported reasoning effort, run turns, print message and usage
|
|
- `14_turn_controls/`
|
|
- separate best-effort `steer()` and `interrupt()` demos with concise summaries
|