codex/sdk/python/examples
Ahmed Ibrahim 0db49a7e6a
[codex] Rename Python SDK AppServerConfig to CodexConfig (#24800)
## Why

`AppServerConfig` is exported as part of the ergonomic Python SDK
surface and passed to `Codex(...)` and `AsyncCodex(...)`. That name
exposes the underlying app-server transport at the same layer where
users are configuring the Codex client. `CodexConfig` makes the common
callsite read naturally and names the object it configures.

## What changed

- Renamed the public configuration dataclass from `AppServerConfig` to
`CodexConfig`.
- Updated `Codex`, `AsyncCodex`, and the transport clients to accept
`CodexConfig`.
- Updated binary-resolution messages, package exports, docs, examples,
and related coverage to use the new public name.

## API impact

```python
from openai_codex import Codex, CodexConfig

with Codex(config=CodexConfig(codex_bin="/path/to/codex")) as codex:
    ...
```

Callers should now import and construct `CodexConfig`; `AppServerConfig`
is no longer part of the Python SDK surface.

## Validation

- `uv run --frozen --extra dev ruff check src/openai_codex scripts
examples tests`
- Tests are deferred to online CI for this PR.
History 2026-05-27 16:10:15 -07:00
..
01_quickstart_constructor [8/8] Add Python SDK Ruff formatting (#22021) 2026-05-12 01:10:29 +03:00
02_turn_run [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
03_turn_stream_events [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
04_models_and_metadata [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
05_existing_thread [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
06_thread_lifecycle_and_controls [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
07_image_and_text [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
08_local_image_and_text [codex] Return TurnResult from Python turn handles (#23151) 2026-05-17 06:17:22 -07:00
09_async_parity [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
10_error_handling_and_retry [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
11_cli_mini_app [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
12_turn_params_kitchen_sink [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
13_model_select_and_turn_params [codex] Add friendly Python SDK sandbox presets (#24772) 2026-05-27 11:11:04 -07:00
14_turn_controls [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00
15_login_and_account sdk/python: add first-class login support (#23093) 2026-05-16 19:49:28 -07:00
_bootstrap.py [codex] Rename Python SDK AppServerConfig to CodexConfig (#24800) 2026-05-27 16:10:15 -07:00
README.md [codex] Accept string input for Python turns (#23162) 2026-05-17 09:05:44 -07:00

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 openai_codex and openai_codex.types.

Examples use plain strings for text-only turns and typed input objects for multimodal or structured input lists.

Prerequisites

  • Python >=3.10
  • Install SDK dependencies for the same Python interpreter you will use to run examples

Recommended setup (from sdk/python):

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

Run examples

From sdk/python:

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

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 steer() and interrupt() demos with concise summaries
  • 15_login_and_account/
    • browser-login handle lifecycle, cancellation, and account inspection