mirror of
https://github.com/openai/codex.git
synced 2026-05-20 19:23:21 +00:00
e7bffc5a20
## Summary
- Allow thread.turn and turn.steer, including async variants, to accept
RunInput so plain strings work alongside typed input objects.
- Export RunInput and update the SDK artifact generator so regenerated
turn methods keep the same signature and normalization.
- Update docs, examples, notebook cells, and tests to use string
shorthand for text-only turns while keeping typed inputs for multimodal
input.
## Validation
- uv run --extra dev ruff format .
- uv run --extra dev ruff check --output-format=github .
- python3 -m py_compile sdk/python/src/openai_codex/__init__.py
sdk/python/src/openai_codex/api.py
sdk/python/src/openai_codex/_inputs.py
sdk/python/scripts/update_sdk_artifacts.py
sdk/python/tests/test_public_api_signatures.py
sdk/python/tests/test_app_server_streaming.py
sdk/python/tests/test_app_server_turn_controls.py
sdk/python/tests/test_real_app_server_integration.py
- python3 -c "import json;
json.load(open('sdk/python/notebooks/sdk_walkthrough.ipynb'))"
- sdk/python/.venv/bin/python -c "import inspect, openai_codex; from
openai_codex import Thread, AsyncThread, TurnHandle, AsyncTurnHandle,
RunInput; funcs=[Thread.run, Thread.turn, AsyncThread.run,
AsyncThread.turn, TurnHandle.steer, AsyncTurnHandle.steer]; assert
all(inspect.signature(fn).parameters['input'].annotation == 'RunInput'
for fn in funcs); assert RunInput is openai_codex.RunInput"
110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# OpenAI Codex Python SDK (Experimental)
|
||
|
||
Experimental Python SDK for `codex app-server` JSON-RPC v2 over stdio, with a small default surface optimized for real scripts and apps.
|
||
|
||
The generated wire-model layer is sourced from the pinned `openai-codex-cli-bin`
|
||
runtime package and exposed as Pydantic models with snake_case Python fields
|
||
that serialize back to the app-server’s camelCase wire format.
|
||
The package root exports the ergonomic client API; public app-server value and
|
||
event types live in `openai_codex.types`.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
cd sdk/python
|
||
uv sync
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Published SDK builds pin an exact `openai-codex-cli-bin` runtime dependency
|
||
with the same version as the SDK. Pass `AppServerConfig(codex_bin=...)` only
|
||
when you intentionally want to run against a specific local app-server binary.
|
||
|
||
## Quickstart
|
||
|
||
```python
|
||
from openai_codex import Codex
|
||
|
||
with Codex() as codex:
|
||
# Call login_api_key(...) first when this app-server session is not
|
||
# already authenticated.
|
||
thread = codex.thread_start(model="gpt-5")
|
||
result = thread.run("Say hello in one sentence.")
|
||
print(result.final_response)
|
||
print(len(result.items))
|
||
```
|
||
|
||
`thread.run(...)` and `thread.turn(...).run()` return `TurnResult`. Its
|
||
`final_response` is `None` when the turn completes without a final-answer or
|
||
phase-less assistant message item.
|
||
|
||
## Login
|
||
|
||
Use the auth helper that matches your app:
|
||
|
||
```python
|
||
from openai_codex import Codex
|
||
|
||
with Codex() as codex:
|
||
codex.login_api_key("sk-...")
|
||
account = codex.account()
|
||
print(account.account)
|
||
```
|
||
|
||
Interactive ChatGPT login returns a handle. Open the provided URL or device-code
|
||
page, then wait for the matching completion event:
|
||
|
||
```python
|
||
with Codex() as codex:
|
||
login = codex.login_chatgpt()
|
||
print(login.auth_url)
|
||
completed = login.wait()
|
||
print(completed.success)
|
||
```
|
||
|
||
Use `login_chatgpt_device_code()` for device-code auth, `handle.cancel()` to
|
||
stop an in-progress interactive login, and `logout()` to clear the active
|
||
app-server account session.
|
||
|
||
## Docs map
|
||
|
||
- Golden path tutorial: `docs/getting-started.md`
|
||
- API reference (signatures + behavior): `docs/api-reference.md`
|
||
- Common decisions and pitfalls: `docs/faq.md`
|
||
- Runnable examples index: `examples/README.md`
|
||
- Jupyter walkthrough notebook: `notebooks/sdk_walkthrough.ipynb`
|
||
|
||
## Examples
|
||
|
||
Start here:
|
||
|
||
```bash
|
||
cd sdk/python
|
||
python examples/01_quickstart_constructor/sync.py
|
||
python examples/01_quickstart_constructor/async.py
|
||
```
|
||
|
||
## Runtime
|
||
|
||
Published SDK builds are pinned to an exact `openai-codex-cli-bin` package
|
||
version, and that runtime package carries the platform-specific binary for the
|
||
target wheel. The SDK package version and runtime package version must match.
|
||
|
||
## Compatibility and versioning
|
||
|
||
- Package: `openai-codex`
|
||
- Runtime package: `openai-codex-cli-bin`
|
||
- Python: `>=3.10`
|
||
- Target protocol: Codex `app-server` JSON-RPC v2
|
||
- Versioning rule: the SDK package version is the underlying Codex runtime version
|
||
|
||
## Notes
|
||
|
||
- `Codex()` is eager and performs startup + `initialize` in the constructor.
|
||
- Use context managers (`with Codex() as codex:`) to ensure shutdown.
|
||
- Plain strings are accepted anywhere a turn input is accepted; they are
|
||
shorthand for `TextInput(...)`.
|
||
- Prefer `thread.run("...")` for the common case. Use `thread.turn(...)` when
|
||
you need streaming, steering, or interrupt control.
|
||
- For transient overload, use `retry_on_overload` from the package root.
|