python-sdk: split stream and control examples (2026-03-16)

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

sdk/python/examples/03_turn_stream_events/async.py

@@ -5,7 +5,12 @@ _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 ensure_local_sdk_src, runtime_config
+from _bootstrap import (
+    assistant_text_from_turn,
+    ensure_local_sdk_src,
+    find_turn_by_id,
+    runtime_config,
+)
 
 ensure_local_sdk_src()
 
@@ -17,26 +22,40 @@ from codex_app_server import AsyncCodex, TextInput
 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"})
-        turn = await thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
-
-        # Best effort controls: models can finish quickly, so races are expected.
-        try:
-            _ = await turn.steer(TextInput("Keep it brief and stop after 20 numbers."))
-            print("steer: sent")
-        except Exception as exc:
-            print("steer: skipped", type(exc).__name__)
-
-        try:
-            _ = await turn.interrupt()
-            print("interrupt: sent")
-        except Exception as exc:
-            print("interrupt: skipped", type(exc).__name__)
+        turn = await thread.turn(TextInput("Explain SIMD in 3 short bullets."))
 
         event_count = 0
+        saw_started = False
+        saw_delta = False
+        completed_status = "unknown"
+
         async for event in turn.stream():
             event_count += 1
-            print(event.method, event.payload)
+            if event.method == "turn/started":
+                saw_started = True
+                print("stream.started")
+                continue
+            if event.method == "item/agentMessage/delta":
+                delta = getattr(event.payload, "delta", "")
+                if delta:
+                    if not saw_delta:
+                        print("assistant> ", end="", flush=True)
+                    print(delta, end="", flush=True)
+                    saw_delta = True
+                continue
+            if event.method == "turn/completed":
+                completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
 
+        if saw_delta:
+            print()
+        else:
+            persisted = await thread.read(include_turns=True)
+            persisted_turn = find_turn_by_id(persisted.thread.turns, turn.id)
+            final_text = assistant_text_from_turn(persisted_turn).strip() or "[no assistant text]"
+            print("assistant>", final_text)
+
+        print("stream.started.seen:", saw_started)
+        print("stream.completed:", completed_status)
         print("events.count:", event_count)
 
 

sdk/python/examples/03_turn_stream_events/sync.py

@@ -5,7 +5,12 @@ _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 ensure_local_sdk_src, runtime_config
+from _bootstrap import (
+    assistant_text_from_turn,
+    ensure_local_sdk_src,
+    find_turn_by_id,
+    runtime_config,
+)
 
 ensure_local_sdk_src()
 
@@ -13,24 +18,38 @@ from codex_app_server import Codex, TextInput
 
 with Codex(config=runtime_config()) as codex:
     thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
-    turn = thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
-
-    # Best effort controls: models can finish quickly, so races are expected.
-    try:
-        _ = turn.steer(TextInput("Keep it brief and stop after 20 numbers."))
-        print("steer: sent")
-    except Exception as exc:
-        print("steer: skipped", type(exc).__name__)
-
-    try:
-        _ = turn.interrupt()
-        print("interrupt: sent")
-    except Exception as exc:
-        print("interrupt: skipped", type(exc).__name__)
+    turn = thread.turn(TextInput("Explain SIMD in 3 short bullets."))
 
     event_count = 0
+    saw_started = False
+    saw_delta = False
+    completed_status = "unknown"
+
     for event in turn.stream():
         event_count += 1
-        print(event.method, event.payload)
+        if event.method == "turn/started":
+            saw_started = True
+            print("stream.started")
+            continue
+        if event.method == "item/agentMessage/delta":
+            delta = getattr(event.payload, "delta", "")
+            if delta:
+                if not saw_delta:
+                    print("assistant> ", end="", flush=True)
+                print(delta, end="", flush=True)
+                saw_delta = True
+            continue
+        if event.method == "turn/completed":
+            completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
 
+    if saw_delta:
+        print()
+    else:
+        persisted = thread.read(include_turns=True)
+        persisted_turn = find_turn_by_id(persisted.thread.turns, turn.id)
+        final_text = assistant_text_from_turn(persisted_turn).strip() or "[no assistant text]"
+        print("assistant>", final_text)
+
+    print("stream.started.seen:", saw_started)
+    print("stream.completed:", completed_status)
     print("events.count:", event_count)

sdk/python/examples/14_turn_controls/async.py

@@ -0,0 +1,71 @@
+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,
+    runtime_config,
+)
+
+ensure_local_sdk_src()
+
+import asyncio
+
+from codex_app_server import AsyncCodex, TextInput
+
+
+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"})
+        steer_turn = await thread.turn(TextInput("Count from 1 to 40 with commas, then one summary sentence."))
+        steer_result = "sent"
+        try:
+            _ = await steer_turn.steer(TextInput("Keep it brief and stop after 10 numbers."))
+        except Exception as exc:
+            steer_result = f"skipped {type(exc).__name__}"
+
+        steer_event_count = 0
+        steer_completed_status = "unknown"
+        steer_completed_turn = None
+        async for event in steer_turn.stream():
+            steer_event_count += 1
+            if event.method == "turn/completed":
+                steer_completed_turn = event.payload.turn
+                steer_completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
+
+        steer_preview = assistant_text_from_turn(steer_completed_turn).strip() or "[no assistant text]"
+
+        interrupt_turn = await thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
+        interrupt_result = "sent"
+        try:
+            _ = await interrupt_turn.interrupt()
+        except Exception as exc:
+            interrupt_result = f"skipped {type(exc).__name__}"
+
+        interrupt_event_count = 0
+        interrupt_completed_status = "unknown"
+        interrupt_completed_turn = None
+        async for event in interrupt_turn.stream():
+            interrupt_event_count += 1
+            if event.method == "turn/completed":
+                interrupt_completed_turn = event.payload.turn
+                interrupt_completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
+
+        interrupt_preview = assistant_text_from_turn(interrupt_completed_turn).strip() or "[no assistant text]"
+
+        print("steer.result:", steer_result)
+        print("steer.final.status:", steer_completed_status)
+        print("steer.events.count:", steer_event_count)
+        print("steer.assistant.preview:", steer_preview)
+        print("interrupt.result:", interrupt_result)
+        print("interrupt.final.status:", interrupt_completed_status)
+        print("interrupt.events.count:", interrupt_event_count)
+        print("interrupt.assistant.preview:", interrupt_preview)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/python/examples/14_turn_controls/sync.py

@@ -0,0 +1,63 @@
+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,
+    runtime_config,
+)
+
+ensure_local_sdk_src()
+
+from codex_app_server import Codex, TextInput
+
+with Codex(config=runtime_config()) as codex:
+    thread = codex.thread_start(model="gpt-5.4", config={"model_reasoning_effort": "high"})
+    steer_turn = thread.turn(TextInput("Count from 1 to 40 with commas, then one summary sentence."))
+    steer_result = "sent"
+    try:
+        _ = steer_turn.steer(TextInput("Keep it brief and stop after 10 numbers."))
+    except Exception as exc:
+        steer_result = f"skipped {type(exc).__name__}"
+
+    steer_event_count = 0
+    steer_completed_status = "unknown"
+    steer_completed_turn = None
+    for event in steer_turn.stream():
+        steer_event_count += 1
+        if event.method == "turn/completed":
+            steer_completed_turn = event.payload.turn
+            steer_completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
+
+    steer_preview = assistant_text_from_turn(steer_completed_turn).strip() or "[no assistant text]"
+
+    interrupt_turn = thread.turn(TextInput("Count from 1 to 200 with commas, then one summary sentence."))
+    interrupt_result = "sent"
+    try:
+        _ = interrupt_turn.interrupt()
+    except Exception as exc:
+        interrupt_result = f"skipped {type(exc).__name__}"
+
+    interrupt_event_count = 0
+    interrupt_completed_status = "unknown"
+    interrupt_completed_turn = None
+    for event in interrupt_turn.stream():
+        interrupt_event_count += 1
+        if event.method == "turn/completed":
+            interrupt_completed_turn = event.payload.turn
+            interrupt_completed_status = getattr(event.payload.turn.status, "value", str(event.payload.turn.status))
+
+    interrupt_preview = assistant_text_from_turn(interrupt_completed_turn).strip() or "[no assistant text]"
+
+    print("steer.result:", steer_result)
+    print("steer.final.status:", steer_completed_status)
+    print("steer.events.count:", steer_event_count)
+    print("steer.assistant.preview:", steer_preview)
+    print("interrupt.result:", interrupt_result)
+    print("interrupt.final.status:", interrupt_completed_status)
+    print("interrupt.events.count:", interrupt_event_count)
+    print("interrupt.assistant.preview:", interrupt_preview)

sdk/python/examples/README.md

@@ -60,7 +60,7 @@ python examples/01_quickstart_constructor/async.py
 - `02_turn_run/`
   - inspect full turn output fields
 - `03_turn_stream_events/`
-  - stream and print raw notifications
+  - stream a turn with a small curated event view
 - `04_models_and_metadata/`
   - read server metadata and model list
 - `05_existing_thread/`
@@ -81,3 +81,5 @@ python examples/01_quickstart_constructor/async.py
   - 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
+- `14_turn_controls/`
+  - separate best-effort `steer()` and `interrupt()` demos with concise summaries