Add Python SDK public API and examples (#14446)

## 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-07-01 00:31:56 +08:00 · 2026-03-17 16:05:56 -07:00
parent 0d1539e74c
commit fc75d07504
46 changed files with 5081 additions and 69 deletions
@@ -0,0 +1,98 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import (
+    assistant_text_from_turn,
+    ensure_local_sdk_src,
+    find_turn_by_id,
+    runtime_config,
+)
+
+ensure_local_sdk_src()
+
+import asyncio
+import random
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from codex_app_server import (
+    AsyncCodex,
+    JsonRpcError,
+    ServerBusyError,
+    TextInput,
+    TurnStatus,
+    is_retryable_error,
+)
+
+ResultT = TypeVar("ResultT")
+
+
+async def retry_on_overload_async(
+    op: Callable[[], Awaitable[ResultT]],
+    *,
+    max_attempts: int = 3,
+    initial_delay_s: float = 0.25,
+    max_delay_s: float = 2.0,
+    jitter_ratio: float = 0.2,
+) -> ResultT:
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    delay = initial_delay_s
+    attempt = 0
+    while True:
+        attempt += 1
+        try:
+            return await op()
+        except Exception as exc:  # noqa: BLE001
+            if attempt >= max_attempts or not is_retryable_error(exc):
+                raise
+            jitter = delay * jitter_ratio
+            sleep_for = min(max_delay_s, delay) + random.uniform(-jitter, jitter)
+            if sleep_for > 0:
+                await asyncio.sleep(sleep_for)
+            delay = min(max_delay_s, delay * 2)
+
+
+async def main() -> None:
+    async with AsyncCodex(config=runtime_config()) as codex:
+        thread = await codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
+
+        try:
+            result = await retry_on_overload_async(
+                _run_turn(thread, "Summarize retry best practices in 3 bullets."),
+                max_attempts=3,
+                initial_delay_s=0.25,
+                max_delay_s=2.0,
+            )
+        except ServerBusyError as exc:
+            print("Server overloaded after retries:", exc.message)
+            print("Text:")
+            return
+        except JsonRpcError as exc:
+            print(f"JSON-RPC error {exc.code}: {exc.message}")
+            print("Text:")
+            return
+
+        persisted = await thread.read(include_turns=True)
+        persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)
+        if result.status == TurnStatus.failed:
+            print("Turn failed:", result.error)
+
+        print("Text:", assistant_text_from_turn(persisted_turn))
+
+
+def _run_turn(thread, prompt: str):
+    async def _inner():
+        turn = await thread.turn(TextInput(prompt))
+        return await turn.run()
+
+    return _inner
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,47 @@
+import sys
+from pathlib import Path
+
+_EXAMPLES_ROOT = Path(__file__).resolve().parents[1]
+if str(_EXAMPLES_ROOT) not in sys.path:
+    sys.path.insert(0, str(_EXAMPLES_ROOT))
+
+from _bootstrap import (
+    assistant_text_from_turn,
+    ensure_local_sdk_src,
+    find_turn_by_id,
+    runtime_config,
+)
+
+ensure_local_sdk_src()
+
+from codex_app_server import (
+    Codex,
+    JsonRpcError,
+    ServerBusyError,
+    TextInput,
+    TurnStatus,
+    retry_on_overload,
+)
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
+
+    try:
+        result = retry_on_overload(
+            lambda: thread.turn(TextInput("Summarize retry best practices in 3 bullets.")).run(),
+            max_attempts=3,
+            initial_delay_s=0.25,
+            max_delay_s=2.0,
+        )
+    except ServerBusyError as exc:
+        print("Server overloaded after retries:", exc.message)
+        print("Text:")
+    except JsonRpcError as exc:
+        print(f"JSON-RPC error {exc.code}: {exc.message}")
+        print("Text:")
+    else:
+        persisted = thread.read(include_turns=True)
+        persisted_turn = find_turn_by_id(persisted.thread.turns, result.id)
+        if result.status == TurnStatus.failed:
+            print("Turn failed:", result.error)
+        print("Text:", assistant_text_from_turn(persisted_turn))