Add Python SDK thread.run convenience methods

[shaqayeq-oai]

TL;DR

Add thread.run(...) / async thread.run(...) convenience methods to the Python SDK for the common case.

• add RunInput = Input | str and RunResult with final_response, collected items, and optional usage
• keep thread.turn(...) strict and lower-level for streaming, steering, interrupting, and raw generated Turn access
• update Python SDK docs, quickstart examples, and tests for the sync and async convenience flows

Validation

• python3 -m pytest sdk/python/tests/test_public_api_signatures.py sdk/python/tests/test_public_api_runtime_behavior.py
• python3 -m pytest sdk/python/tests/test_real_app_server_integration.py -k 'thread_run_convenience or async_thread_run_convenience' (skipped in this environment)

[owenlin0]

API looks super clean in the examples, love to see it!

just a comment about organization, but pre-approving

[owenlin0]

IMO it'd be great to introduce some structure so api.py doesn't become too monolithic (and also so Codex itself can follow a better file structure in future changes!)

Let's keep api.py minimal as the public facade and where the generated Codex / Thread methods live

Codex suggests this:

Extract the handwritten convenience logic into private modules:

• _inputs.py: TextInput, ImageInput, LocalImageInput, SkillInput, MentionInput, Input, RunInput, _to_wire_input, _normalize_run_input
• _run.py: RunResult, _collect_run_result, _collect_async_run_result, _raise_for_failed_turn, assistant-text extraction
• optionally _turn_handles.py: TurnHandle and AsyncTurnHandle if you want the bottom half slimmer too

thoughts?

[shaqayeq-oai]

I reverted the _turn_handles.py split because it introduced an awkward api.py <-> _turn_handles.py circular typing dependency around AsyncCodex / AsyncTurnHandle. We can make it work with TYPE_CHECKING or a private protocol, but that felt like more complexity than value