codex/sdk/python/examples/README.md

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

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 therefore resolves codex from:

• CODEX_PYTHON_SDK_CODEX_BIN, if set
• otherwise codex on PATH

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 extra package build step is required beyond installing dependencies for your active interpreter and making a codex binary available.

Recommended first run

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 and print raw notifications
• 04_models_and_metadata/
  • read server metadata and model list
• 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 bundled 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/
  • one turn using most optional turn(...) params (sync + async)
• 13_model_select_and_turn_params/
  • list models, pick highest model + highest supported reasoning effort, run turns, print message and usage