Add Python SDK public API and examples

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

sdk/python/docs/faq.md

@@ -8,24 +8,42 @@
 
 ## `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.
+- `Turn.run()` / `AsyncTurn.run()` is the easiest path. It consumes events until completion and returns `TurnResult`.
+- `Turn.stream()` / `AsyncTurn.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.
 
 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 +79,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 +90,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:`).
+- Forgetting to `close()` (or not using context managers).
 - Ignoring `TurnResult.status` and `TurnResult.error`.
-- Mixing SDK input classes with raw dicts incorrectly in minimal API paths.
+- Mixing SDK input classes with raw dicts incorrectly.