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>

sdk/python/docs/faq.md

@@ -8,24 +8,45 @@
 
 ## `run()` vs `stream()`
 
-- `Turn.run()` is the easiest path. It consumes events until completion and returns `TurnResult`.
-- `Turn.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
+- `TurnHandle.run()` / `AsyncTurnHandle.run()` is the easiest path. It consumes events until completion and returns the canonical generated app-server `Turn` model.
+- `TurnHandle.stream()` / `AsyncTurnHandle.stream()` yields raw notifications (`Notification`) so you can react event-by-event.
 
 Choose `run()` for most apps. Choose `stream()` for progress UIs, custom timeout logic, or custom parsing.
 
 ## Sync vs async clients
 
-- `Codex` is the minimal sync SDK and best default.
-- `AsyncAppServerClient` wraps the sync transport with `asyncio.to_thread(...)` for async-friendly call sites.
+- `Codex` is the sync public API.
+- `AsyncCodex` is an async replica of the same public API shape.
+- Prefer `async with AsyncCodex()` for async code. It is the standard path for
+  explicit startup/shutdown, and `AsyncCodex` initializes lazily on context
+  entry or first awaited API use.
 
 If your app is not already async, stay with `Codex`.
 
-## `thread(...)` vs `thread_resume(...)`
+## Public kwargs are snake_case
 
-- `codex.thread(thread_id)` only binds a local helper to an existing thread ID.
-- `codex.thread_resume(thread_id, ...)` performs a `thread/resume` RPC and can apply overrides (model, instructions, sandbox, etc.).
+Public API keyword names are snake_case. The SDK still maps them to wire camelCase under the hood.
 
-Use `thread(...)` for simple continuation. Use `thread_resume(...)` when you need explicit resume semantics or override fields.
+If you are migrating older code, update these names:
+
+- `approvalPolicy` -> `approval_policy`
+- `baseInstructions` -> `base_instructions`
+- `developerInstructions` -> `developer_instructions`
+- `modelProvider` -> `model_provider`
+- `modelProviders` -> `model_providers`
+- `sortKey` -> `sort_key`
+- `sourceKinds` -> `source_kinds`
+- `outputSchema` -> `output_schema`
+- `sandboxPolicy` -> `sandbox_policy`
+
+## Why only `thread_start(...)` and `thread_resume(...)`?
+
+The public API keeps only explicit lifecycle calls:
+
+- `thread_start(...)` to create new threads
+- `thread_resume(thread_id, ...)` to continue existing threads
+
+This avoids duplicate ways to do the same operation and keeps behavior explicit.
 
 ## Why does constructor fail?
 
@@ -61,7 +82,7 @@ python scripts/update_sdk_artifacts.py \
 A turn is complete only when `turn/completed` arrives for that turn ID.
 
 - `run()` waits for this automatically.
-- With `stream()`, make sure you keep consuming notifications until completion.
+- With `stream()`, keep consuming notifications until completion.
 
 ## How do I retry safely?
 
@@ -72,6 +93,6 @@ Do not blindly retry all errors. For `InvalidParamsError` or `MethodNotFoundErro
 ## Common pitfalls
 
 - Starting a new thread for every prompt when you wanted continuity.
-- Forgetting to `close()` (or not using `with Codex() as codex:`).
-- Ignoring `TurnResult.status` and `TurnResult.error`.
-- Mixing SDK input classes with raw dicts incorrectly in minimal API paths.
+- Forgetting to `close()` (or not using context managers).
+- Assuming `run()` returns extra SDK-only fields instead of the generated `Turn` model.
+- Mixing SDK input classes with raw dicts incorrectly.