python-sdk: generated type foundation (all v2 schemas) by shaqayeq-oai · Pull Request #13953 · openai/codex

shaqayeq-oai · 2026-03-08T08:55:11Z

Summary

Foundation PR only (base for PR #3).

This PR contains the SDK runtime foundation and generated artifacts:

pinned runtime binary in sdk/python/bin/ (codex or codex.exe by platform)
single maintenance script: sdk/python/scripts/update_sdk_artifacts.py
generated protocol/types artifacts under:
- sdk/python/src/codex_app_server/generated/protocol_types.py
- sdk/python/src/codex_app_server/generated/schema_types.py
- sdk/python/src/codex_app_server/generated/v2_all/*
generation-contract test wiring (tests/test_contract_generation.py)

Release asset behavior

update_sdk_artifacts.py now:

selects latest release by channel (--channel stable|alpha)
resolves the correct asset for current OS/arch
extracts platform binary (codex on macOS/Linux, codex.exe on Windows)
keeps runtime on single pinned binary source in sdk/python/bin/

Scope boundary

✅ PR (cleanup) add link to https://cookbook.openai.com for apply_patch and minor tidy up #2 = binary + generation pipeline + generated types foundation
❌ PR (cleanup) add link to https://cookbook.openai.com for apply_patch and minor tidy up #2 does not include examples/integration logic polish (that is PR move all tests under tests/ #3)

Validation

Ran: python scripts/update_sdk_artifacts.py --channel stable
Regenerated and committed resulting generated artifacts
Local tests pass on branch

Description: - pin datamodel-code-generator to an exact version and invoke it through the active interpreter - make generate_types own the maintained generated surfaces and regenerate committed artifacts - make sdk/python tests hermetic and regeneration checks idempotent

owenlin0

Can we run datamodel_code_generator against the json schema bundle at codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json instead of over the codex-rs/app-server-protocol/schema/json/v2/ directory? I think that should fix duplicate definitions (e.g. PlanType).

Also, I asked Codex to walk me through the app-server schema -> python pipeline, and it seems like we have these stages:

Source To Raw Models: app-server json schema -> pydantic types
Raw Models To Curated Python Shapes: a subset of manually curated types which outputs both TypedDict and Pydantic types
Raw Models To Public API Signatures: generated Pydantic model -> ergonomic Python method signature

Can we simplify? Codex suggests this:

The simplest functional shape is:

one canonical generated wire-model layer

Pydantic only

no handwritten “curated schema shapes”

a thin handwritten client/public API on top
That is the direction I’d recommend.

Use the bundled schema codex_app_server_protocol.v2.schemas.json as the canonical input, and generate a single Pydantic model namespace from it.

The Python-facing models should use snake_case field names, but serialize and validate against camelCase on the wire.

I think that should allow us to delete protocol_types.py and schema_types.py

owenlin0 · 2026-03-09T16:51:27Z

sdk/python/scripts/update_sdk_artifacts.py

+    ("codex_app_server.generated.v2_all.TurnStartParams", "Personality"): "TurnPersonality",
+    ("codex_app_server.generated.v2_all.TurnStartParams", "ReasoningEffort"): "TurnReasoningEffort",
+    ("codex_app_server.generated.v2_all.TurnStartParams", "SandboxPolicy"): "TurnSandboxPolicy",
+    ("codex_app_server.generated.v2_all.TurnStartParams", "ReasoningSummary"): "TurnReasoningSummary",


curious why we need these type aliases, since things like ReasoningSummary is meant to be a shared type across a couple RPCs (same with the others here like Personality etc.)

owenlin0 · 2026-03-09T16:52:50Z

sdk/python/src/codex_app_server/generated/v2_all/ContextCompactedNotification.py

+
+class ContextCompactedNotification(BaseModel):
+    threadId: str
+    turnId: str


to make things more pythonic, wonder if it's possible to produce these generated fields as snake_case, but send it over the wire to app-server as camelCase?

owenlin0 · 2026-03-09T16:53:27Z

sdk/python/README.md

@@ -0,0 +1,77 @@
+# Codex App Server Python SDK


probably worth adding (experimental) for now

owenlin0 · 2026-03-09T16:54:28Z

sdk/python/src/codex_app_server/generated/protocol_types.py

+    source: dict[str, Any]
+    status: dict[str, Any]
+    turns: list[TurnObject]
+    updatedAt: int


snake_case would be so nice here

owenlin0 · 2026-03-09T16:54:44Z

sdk/python/src/codex_app_server/generated/protocol_types.py

+
+# Generated by scripts/update_sdk_artifacts.py
+
+class ThreadObject(TypedDict):


curious, why do we need a *Object suffix?

owenlin0 · 2026-03-09T16:55:57Z

sdk/python/src/codex_app_server/generated/schema_types.py

+    updatedAt: int
+
+@dataclass(slots=True, kw_only=True)
+class Thread:


What's the difference between ThreadDict vs. Thread (defined here) vs. ThreadObject (defined in protocol_types.py)? Do we need all those types? Can we simplify?

owenlin0 · 2026-03-09T17:00:16Z

sdk/python/src/codex_app_server/generated/v2_all/AccountLoginCompletedNotification.py

+
+class AccountLoginCompletedNotification(BaseModel):
+    error: Optional[str] = None
+    loginId: Optional[str] = None


nit: I think str | None = None is more idiomatic these days for optional types

owenlin0 · 2026-03-09T17:01:16Z

sdk/python/src/codex_app_server/generated/v2_all/AccountUpdatedNotification.py

+    chatgptAuthTokens = "chatgptAuthTokens"
+
+
+class AuthMode(RootModel[Union[AuthMode1, AuthMode2, AuthMode3]]):


Curious why AuthMode is generated this way vs. PlanType below (which seems better and is less verbose)

owenlin0 · 2026-03-09T17:02:36Z

sdk/python/src/codex_app_server/generated/v2_all/AccountRateLimitsUpdatedNotification.py

+    unlimited: bool
+
+
+class PlanType(Enum):


Seems like shared enums are not generated once and imported (i.e. we define PlanType multiple times across various files) - possible to fix?

owenlin0

much cleaner, thanks! just some non-blocking comments

owenlin0 · 2026-03-09T22:49:26Z

sdk/python/src/codex_app_server/client.py

+        }
+        return self.request("turn/start", payload, response_model=TurnStartResponse)
+
+    def turn_text(


nit: turn_text seems unnecessary?

owenlin0 · 2026-03-09T22:50:37Z

sdk/python/src/codex_app_server/client.py

+            active_thread_id = started.thread.id
+        return self.run_text_turn(active_thread_id, text)
+
+    def ask(


do we need ask and ask_result? These seem a bit weird

owenlin0 · 2026-03-09T22:51:44Z

sdk/python/src/codex_app_server/client.py

+            if notification.method in target_methods:
+                return out
+
+    def run_text_turn(


what's the use case of run_text_turn? do we need it?

owenlin0 · 2026-03-09T22:53:26Z

sdk/python/src/codex_app_server/models.py

+class TextTurnResult:
+    thread_id: str
+    turn_id: str
+    deltas: list[AgentMessageDeltaNotification]


similarly, do we need TextTurnResult? wondering if we can remove.

but if you really do want it, instead of storing deltas could we store a list of agent messages instead? it'd feel a little less weird. (but still unclear of the use case of this)

owenlin0 · 2026-03-09T22:54:06Z

sdk/python/tests/test_client_rpc_methods.py

+def test_codex_event_notifications_are_typed() -> None:
+    client = AppServerClient()
+    event = client._coerce_notification(
+        "codex/event/turn_aborted",


FYI we are dropping codex/event/* from app-server API very soon. No need to invest in any support for these

shaqayeq-oai added 3 commits March 8, 2026 00:47

2026-03-08 Remove legacy python SDK notification aliases

4e4f81d

2026-03-08 Regenerate python SDK artifacts for current schema

0ef657d

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

Merge branch 'main' into shaqayeq/python-sdk-types-foundation

17818d6

owenlin0 reviewed Mar 9, 2026

View reviewed changes

shaqayeq-oai added 2 commits March 9, 2026 12:42

2026-03-09 Simplify experimental python SDK wire models

eb98b16

2026-03-09 Flatten enum-like schema oneOfs for python codegen

ffe4006

owenlin0 approved these changes Mar 9, 2026

View reviewed changes

shaqayeq-oai added 4 commits March 9, 2026 22:59

2026-03-09 Remove python SDK low-level text turn helpers

92d5cfd

Merge branch 'main' into shaqayeq/python-sdk-types-foundation

1097244

2026-03-09 Regenerate python SDK artifacts after main merge

dc00741

2026-03-10 Use generic unknown notification fallback example

ce3d8be

shaqayeq-oai merged commit 6baeec6 into main Mar 10, 2026
15 checks passed

shaqayeq-oai deleted the shaqayeq/python-sdk-types-foundation branch March 10, 2026 08:00

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

python-sdk: generated type foundation (all v2 schemas)#13953

python-sdk: generated type foundation (all v2 schemas)#13953
shaqayeq-oai merged 10 commits intomainfrom
shaqayeq/python-sdk-types-foundation

shaqayeq-oai commented Mar 8, 2026

owenlin0 left a comment

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 left a comment

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

owenlin0 Mar 9, 2026

Uh oh!

Labels

3 participants


		# Generated by scripts/update_sdk_artifacts.py

		class ThreadObject(TypedDict):

		chatgptAuthTokens = "chatgptAuthTokens"


		class AuthMode(RootModel[Union[AuthMode1, AuthMode2, AuthMode3]]):

Conversation

shaqayeq-oai commented Mar 8, 2026

Summary

Release asset behavior

Scope boundary

Validation

owenlin0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

owenlin0 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Labels

3 participants