mirror of
https://github.com/pchuan98/codex.git
synced 2026-07-01 00:31:56 +08:00
Ahmed Ibrahim
eb1cc3824c
## Why The initial public `openai-codex` beta should read and install like a normal published Python package before a release tag is created. This follows merged PR #24828, which establishes the independent SDK beta release plumbing and exact runtime dependency. ## What changed - Rewrote `sdk/python/README.md` as a compact PyPI-facing beta package page: published installation, one quickstart, short login examples, built-in help, and links to deeper guides. - Updated the getting-started guide, API reference, FAQ, and examples index to present the published beta consistently without repeating onboarding in the package landing page or reference page. - Made `pip install openai-codex` the primary install path while beta releases are the only published SDK releases, with `--pre` documented for opting into prereleases after a stable release exists. - Added curated `help()` / `pydoc` docstrings across the public API and generated public convenience methods through `scripts/update_sdk_artifacts.py`. - Declared the repository `Apache-2.0` license expression and Documentation URL in package metadata, without introducing a duplicated SDK-local license file. - Kept the source distribution focused on installable package material (`src/openai_codex`, `README.md`, and `pyproject.toml`); the repository docs and runnable examples remain linked from the PyPI README. - Built release artifacts in an Alpine container on the Ubuntu runner, matching Python SDK CI and allowing type generation to install the published `musllinux` runtime wheel. - Added `twine check --strict` to the release workflow so malformed PyPI metadata or rendered README content fails before publishing. - Added focused SDK assertions for beta metadata, the exact runtime pin, source distribution contents, and the built-in Python documentation surface. ## Validation - Ran `uv run --frozen --extra dev ruff check scripts/update_sdk_artifacts.py src/openai_codex tests/test_public_api_signatures.py tests/test_artifact_workflow_and_binaries.py` before the final README-only reductions and review-fix follow-ups. - Built `openai_codex-0.1.0b1-py3-none-any.whl` and `openai_codex-0.1.0b1.tar.gz` before the final README-only reductions and review-fix follow-ups. - Ran `python -m twine check --strict` on both built artifacts before the final README-only reductions and review-fix follow-ups. - Verified artifact metadata reports `Apache-2.0` without a duplicated SDK-local license file. - Verified `inspect.getdoc(...)` resolves documentation for the package, `Codex`, `CodexConfig`, and key generated thread methods. - Rebased the documentation/readiness change onto merged PR #24828 without changing the intended SDK or workflow file contents. - Final verification is delegated to online CI for this PR.
175 lines
4.1 KiB
Markdown
175 lines
4.1 KiB
Markdown
# Getting Started
|
|
|
|
This guide gets a published OpenAI Codex Python SDK beta installation running
|
|
with a multi-turn thread.
|
|
|
|
## 1. Install
|
|
|
|
Install the SDK:
|
|
|
|
```bash
|
|
pip install openai-codex
|
|
```
|
|
|
|
For a reproducible install of this release:
|
|
|
|
```bash
|
|
pip install openai-codex==0.1.0b1
|
|
```
|
|
|
|
Requirements:
|
|
|
|
- Python `>=3.10`
|
|
- An existing Codex account session, or one of the login flows below
|
|
|
|
The SDK installs its compatible `openai-codex-cli-bin` runtime dependency
|
|
automatically. While beta releases are the only published SDK releases, this
|
|
normal install command selects the latest beta. After a stable release exists,
|
|
use `pip install --pre openai-codex` to opt into a newer prerelease.
|
|
|
|
## 2. Authenticate When Needed
|
|
|
|
Existing Codex authentication is reused automatically. For ChatGPT browser
|
|
login:
|
|
|
|
```python
|
|
from openai_codex import Codex
|
|
|
|
with Codex() as codex:
|
|
login = codex.login_chatgpt()
|
|
print(login.auth_url)
|
|
print(login.wait().success)
|
|
```
|
|
|
|
For device-code login:
|
|
|
|
```python
|
|
with Codex() as codex:
|
|
login = codex.login_chatgpt_device_code()
|
|
print(login.verification_url, login.user_code)
|
|
print(login.wait().success)
|
|
```
|
|
|
|
For API-key login:
|
|
|
|
```python
|
|
with Codex() as codex:
|
|
codex.login_api_key("sk-...")
|
|
print(codex.account().account)
|
|
```
|
|
|
|
## 3. Run A Turn
|
|
|
|
```python
|
|
from openai_codex import Codex, Sandbox
|
|
|
|
with Codex() as codex:
|
|
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
|
|
result = thread.run("Say hello in one sentence.")
|
|
|
|
print("Thread:", thread.id)
|
|
print("Text:", result.final_response)
|
|
print("Items:", len(result.items))
|
|
```
|
|
|
|
`Thread.run(...)` starts a turn, waits for completion, and returns
|
|
`TurnResult`. Plain strings are shorthand for `TextInput(...)`.
|
|
|
|
Use `Thread.turn(...)` when you need a `TurnHandle` for streaming, steering,
|
|
or interrupting an active turn.
|
|
|
|
## 4. Choose Sandbox Access
|
|
|
|
Use one enum for the initial thread and later turn overrides:
|
|
|
|
```python
|
|
from openai_codex import Codex, Sandbox
|
|
|
|
with Codex() as codex:
|
|
thread = codex.thread_start(sandbox=Sandbox.workspace_write)
|
|
thread.run("Make the requested changes.")
|
|
review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)
|
|
```
|
|
|
|
Available presets:
|
|
|
|
- `Sandbox.read_only`: read files without allowing writes.
|
|
- `Sandbox.workspace_write`: read files and write inside the workspace and
|
|
configured writable roots; this is the normal default for workspace work.
|
|
- `Sandbox.full_access`: run without filesystem access restrictions.
|
|
|
|
When `sandbox=` is omitted, Codex uses its configured default. A turn override
|
|
also applies to subsequent turns on that thread.
|
|
|
|
## 5. Continue A Thread
|
|
|
|
```python
|
|
from openai_codex import Codex
|
|
|
|
with Codex() as codex:
|
|
thread = codex.thread_start()
|
|
thread.run("Summarize Rust ownership in two bullets.")
|
|
result = thread.run("Now explain it to a Python developer.")
|
|
print(result.final_response)
|
|
```
|
|
|
|
To resume a stored thread later:
|
|
|
|
```python
|
|
with Codex() as codex:
|
|
thread = codex.thread_resume("thr_123")
|
|
print(thread.run("Continue where we left off.").final_response)
|
|
```
|
|
|
|
## 6. Use The Async Client
|
|
|
|
```python
|
|
import asyncio
|
|
|
|
from openai_codex import AsyncCodex, Sandbox
|
|
|
|
|
|
async def main() -> None:
|
|
async with AsyncCodex() as codex:
|
|
thread = await codex.thread_start(sandbox=Sandbox.workspace_write)
|
|
result = await thread.run("Continue where we left off.")
|
|
print(result.final_response)
|
|
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
## 7. Get Help
|
|
|
|
Python's built-in documentation tools cover the curated SDK surface:
|
|
|
|
```python
|
|
import openai_codex
|
|
from openai_codex import Codex, CodexConfig
|
|
|
|
help(openai_codex)
|
|
help(Codex)
|
|
help(CodexConfig)
|
|
```
|
|
|
|
```bash
|
|
python -m pydoc openai_codex
|
|
```
|
|
|
|
## Developing From This Repository
|
|
|
|
Contributors working from a checkout can install development dependencies from
|
|
the repository:
|
|
|
|
```bash
|
|
cd sdk/python
|
|
uv sync --extra dev
|
|
source .venv/bin/activate
|
|
```
|
|
|
|
## Next Stops
|
|
|
|
- [API reference](https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md)
|
|
- [FAQ](https://github.com/openai/codex/blob/main/sdk/python/docs/faq.md)
|
|
- [Runnable examples](https://github.com/openai/codex/blob/main/sdk/python/examples/README.md)
|