Add Python SDK public API and examples by shaqayeq-oai · Pull Request #14446 · openai/codex

shaqayeq-oai · 2026-03-12T07:40:14Z

TL;DR

WIP esp the examples

Thin the Python SDK public surface so the wrapper layer returns canonical app-server generated models directly.

keeps Codex / AsyncCodex / Thread / Turn and input helpers, but removes alias-only type layers and custom result models
metadata now returns InitializeResponse and run() returns the generated app-server Turn
updates docs, examples, notebook, and tests to use canonical generated types and regenerates v2_all.py against current schema
keeps the pinned runtime-package integration flow and real integration coverage

Validation

PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests
GH_TOKEN="$(gh auth token)" RUN_REAL_CODEX_TESTS=1 PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests -rs

Co-authored-by: Codex <noreply@openai.com>

2026-03-12 Switch the repo-source Python SDK real coverage over to a pinned runtime-package flow backed by GitHub release artifacts instead of PATH or explicit binary overrides. - add sdk/python/_runtime_setup.py to download the release codex archive for a requested CODEX_PYTHON_RUNTIME_VERSION, stage a temporary codex-cli-bin package, and install it into a target Python environment with cleanup - refactor real integration tests to run repo-source SDK code against an isolated site-packages target that contains the staged codex-cli-bin runtime - update examples and notebook bootstrap to install and use the runtime package, and stop consulting CODEX_PYTHON_SDK_CODEX_BIN or PATH - switch the failing turn-run and model-selection examples to runtime-compatible model selection for the pinned release binary - keep the main SDK runtime resolution model unchanged: explicit codex_bin or installed codex-cli-bin Validation: - python3 -m pytest sdk/python/tests - RUN_REAL_CODEX_TESTS=1 CODEX_PYTHON_RUNTIME_VERSION=0.115.0-alpha.11 python3 -m pytest sdk/python/tests/test_real_app_server_integration.py Co-authored-by: Codex <noreply@openai.com>

Remove CODEX_PYTHON_RUNTIME_VERSION from the repo bootstrap path and always provision the checked-in pinned codex-cli-bin runtime version for examples, notebook, and real integration coverage. This keeps repo-source Python execution aligned with one binary contract, rewires the real integration harness and notebook bootstrap to use the pinned runtime directly, and updates the docs to describe automatic pinned-runtime provisioning instead of env-driven overrides. Validation: - RUN_REAL_CODEX_TESTS=1 python3 -m pytest sdk/python/tests -rs - RUN_REAL_CODEX_TESTS=1 python3 -m pytest sdk/python/tests/test_real_app_server_integration.py -rs Co-authored-by: Codex <noreply@openai.com>

Update the repo-run examples that still hardcoded gpt-5 so they use the same gpt-5.4 path already succeeding elsewhere in this runtime. This fixes the quickstart, lifecycle, multimodal, parity, CLI, retry, and kitchen-sink examples that were failing with the runtime-side tool_search compatibility error under gpt-5. Validation: - ran all 25 sdk/python example scripts locally - no examples reported failed turns after the model update - remaining empty-item outputs are limited to 02_turn_run and 03_turn_stream_events for follow-up investigation Co-authored-by: Codex <noreply@openai.com>

Update the sync and async turn-run examples to read the thread after a completed turn and print the persisted item count instead of the empty immediate TurnResult.items list. This makes the example output match the current app-server behavior, where the completed turn payload can have empty items even though the persisted thread turn later contains the generated items. Validation: - python3 sdk/python/examples/02_turn_run/sync.py - python3 sdk/python/examples/02_turn_run/async.py Co-authored-by: Codex <noreply@openai.com>

owenlin0

this is a great start! just some initial thoughts about keeping the SDK as thin a wrapper around app-server as possible. will have to think about the public interface a bit more

owenlin0 · 2026-03-14T17:45:27Z

+    turn_id: str
+    status: TurnStatus
+    error: TurnError | None
+    text: str


Instead of defining our own types, wherever possible it'd be great to just use the generated Python types directly. So instead of defining a TurnResult, could we just use the auto-generated Turn object? this would mean no text and usage fields, which I think is actually good IMO

my thinking is that we take a lot of thought in developing the app-server API and it should be the canonical interface, so the more we expose it directly the better

Same goes for the various types below

Remove the SDK alias/result layers so the wrapper surface returns canonical generated app-server models directly. - delete public type alias modules and regenerate v2_all.py against current schema - return InitializeResponse from metadata and generated Turn from run() - update docs, examples, notebook, and tests to use canonical generated models and repo-only text extraction helpers Validation: - PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests - GH_TOKEN="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" RUN_REAL_CODEX_TESTS=1 PYTHONPATH=sdk/python/src python3 -m pytest sdk/python/tests -rs Co-authored-by: Codex <noreply@openai.com>

Rename the public SDK wrapper objects from Turn/AsyncTurn to TurnHandle/AsyncTurnHandle so the wrapper control object is clearly distinct from the canonical generated app-server Turn model. Update the top-level exports, public API docs, runtime behavior test coverage, and the Python SDK codegen helper so future generated method signatures preserve the new wrapper names. Co-authored-by: Codex <noreply@openai.com>

…-16) Normalize validated initialize metadata back onto InitializeResponse so successful metadata access exposes populated serverInfo fields even when they were derived from userAgent. Also make async lifecycle guidance explicit in the public surface by documenting async with AsyncCodex() as the preferred entrypoint and aligning the AsyncCodex metadata error message with that model. Co-authored-by: Codex <noreply@openai.com>

shaqayeq-oai · 2026-03-16T22:16:27Z

+
+
+@dataclass(slots=True)
+class TurnHandle:


WIP
I kept the wrapper layer for now since it’s still where the per-turn control methods live, but renamed it to TurnHandle/AsyncTurnHandle so we don’t have two different public things both called Turn. The generated app-server Turn stays the canonical returned type, and this wrapper is just the handle around that flow but lmk if we would rather do it differently.

…6-03-16) - bump the repo-managed runtime bootstrap to rust-v0.116.0-alpha.1 so example and integration paths match the current SDK thread/start schema - make release artifact download more robust by retrying metadata lookups without stale auth and preferring deterministic release asset URLs - refresh generated Python artifacts and signature expectations so artifact drift tests pass on the current branch shape - replace the checked-in local image asset with a generated temporary PNG used by the examples and notebook local-image flow - add lightweight tests for pinned runtime doc drift and invalid-auth fallback in runtime metadata resolution Co-authored-by: Codex <noreply@openai.com>

- make 03_turn_stream_events a clean streaming example with curated event output - add 14_turn_controls as a separate steer and interrupt demo with concise summaries - update the notebook and runtime-backed example assertions to match the new example shapes Co-authored-by: Codex <noreply@openai.com>

owenlin0

this looks quite nice! I think we can layer on some nice convenience methods (borrowed from TS SDK) that we can do as a followup to make the common case easy:

Add a convenience Thread.run() / AsyncThread.run() method that returns the final assistant response and collected items.
Have those methods accept plain strings as input instead of having to construct TextInput.

(in addition to the lower-level thread.turn(...) method that returns a turn handle, if the client needs to steer/interrupt/etc.)

owenlin0

naming nit: public_api.py -> api.py?

Co-authored-by: Codex <noreply@openai.com>

Base automatically changed from dev/shaqayeq/python-sdk-extract to main March 12, 2026 16:22

shaqayeq-oai and others added 2 commits March 12, 2026 10:15

Add Python SDK public API and examples

fd4beb8

Co-authored-by: Codex <noreply@openai.com>

shaqayeq-oai force-pushed the dev/shaqayeq/python-sdk-public-api branch from 1655fc4 to 3cf1306 Compare March 12, 2026 17:20

github-actions bot mentioned this pull request Mar 13, 2026

📊 AI CLI 工具社区动态日报 2026-03-13 rollysys/agents-radar#77

Open

etraut-openai added the oai PRs contributed by OpenAI employees label Mar 13, 2026

shaqayeq-oai and others added 3 commits March 13, 2026 13:50

Merge branch 'main' into dev/shaqayeq/python-sdk-public-api

b4b6c66

owenlin0 reviewed Mar 14, 2026

View reviewed changes

shaqayeq-oai and others added 3 commits March 16, 2026 14:04

shaqayeq-oai commented Mar 16, 2026

View reviewed changes

shaqayeq-oai and others added 4 commits March 16, 2026 15:47

Merge branch 'main' into dev/shaqayeq/python-sdk-public-api

2cd71de

Delete sdk/python/examples/assets/sample_scene.png

cd84a3f

owenlin0 approved these changes Mar 17, 2026

View reviewed changes

owenlin0 reviewed Mar 17, 2026

View reviewed changes

shaqayeq-oai and others added 3 commits March 17, 2026 14:13

python-sdk: rename public_api module to api (2026-03-17)

c45ff3a

Co-authored-by: Codex <noreply@openai.com>

python-sdk: polish example output contracts (2026-03-17)

3fba6cf

Co-authored-by: Codex <noreply@openai.com>

python-sdk: fix advanced notebook walkthrough (2026-03-17)

da3cad3

Co-authored-by: Codex <noreply@openai.com>

shaqayeq-oai merged commit fc75d07 into main Mar 17, 2026
17 checks passed

shaqayeq-oai deleted the dev/shaqayeq/python-sdk-public-api branch March 17, 2026 23:05

github-actions bot locked and limited conversation to collaborators Mar 17, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Python SDK public API and examples#14446

Add Python SDK public API and examples#14446
shaqayeq-oai merged 16 commits intomainfrom
dev/shaqayeq/python-sdk-public-api

shaqayeq-oai commented Mar 12, 2026 •

edited

Loading

Uh oh!

owenlin0 left a comment

Uh oh!

Uh oh!

Uh oh!

owenlin0 Mar 14, 2026

Uh oh!

owenlin0 Mar 14, 2026

Uh oh!

shaqayeq-oai Mar 16, 2026 •

edited

Loading

Uh oh!

owenlin0 left a comment

Uh oh!

owenlin0 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants



		@dataclass(slots=True)
		class TurnHandle:

Conversation

shaqayeq-oai commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

Validation

Uh oh!

owenlin0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

owenlin0 Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

owenlin0 Mar 14, 2026

Choose a reason for hiding this comment

Uh oh!

shaqayeq-oai Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

owenlin0 left a comment

Choose a reason for hiding this comment

Uh oh!

owenlin0 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shaqayeq-oai commented Mar 12, 2026 •

edited

Loading

shaqayeq-oai Mar 16, 2026 •

edited

Loading