mirror of
https://github.com/openai/codex.git
synced 2026-05-03 19:06:58 +00:00
0f40261e86
**note**: a large chunk of this diff comes from regenerating Python types after app-server schema changes on `main`. This is PR 3 of 3 for the Python SDK PyPI publishing split. PR #18862 refreshed the generated SDK surface, and PR #18865 made the runtime package publishable as `openai-codex-cli-bin`; this final PR makes the SDK package publishable as `openai-codex-app-server-sdk` and pins both packages to the same Codex runtime version. The key idea is that the published SDK version is the Codex runtime version. That one version now drives the SDK package version, the exact runtime dependency, the client version reported by the SDK, and the bootstrap runtime pin. This keeps release-time versioning in one lane instead of scattering checked-in literals through the package. ## What changed - Rename the SDK distribution from `codex-app-server-sdk` to `openai-codex-app-server-sdk` for conflict-free PyPI publishing. - Use `stage-sdk --codex-version ...` with one Codex version for both the SDK package version and exact `openai-codex-cli-bin` dependency. - Preserve hidden legacy `--runtime-version` / `--sdk-version` args only to reject mismatched versions during staging. - Map PEP 440 package versions back to Codex release tags for runtime setup downloads, e.g. `0.116.0a1` -> `rust-v0.116.0-alpha.1`. - Derive `codex_app_server.__version__`, the default `AppServerConfig.client_version`, and `_runtime_setup.pinned_runtime_version()` from the SDK package/project version instead of hardcoding duplicate version strings. - Carry the current generated SDK refresh from `main` so `generate-types` stays clean after recent app-server schema changes. - Update `sdk/python/uv.lock` for the renamed editable package. ## Validation - `uv run --extra dev pytest` in `sdk/python` -> 59 passed, 37 skipped. - Targeted `uv run ruff check` for the touched SDK files. - `git diff --check`. - Staged runtime with `--codex-version rust-v0.116.0-alpha.1 --platform-tag macosx_11_0_arm64`. - Staged SDK with `--codex-version rust-v0.116.0-alpha.1`. - Built runtime wheel, SDK wheel, and SDK sdist. - `twine check /tmp/codex-python-pr3-build/dist/*` -> passed. - Clean venv smoke installed `openai-codex-app-server-sdk==0.116.0a1` from local dist and pulled `openai-codex-cli-bin==0.116.0a1`. - Smoke imports passed for `Codex` and `bundled_codex_path()`.
84 lines
2.7 KiB
Markdown
84 lines
2.7 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
|
|
uv sync
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
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.
|
|
|
|
The pinned runtime version comes from the SDK package version.
|
|
|
|
## 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
|