openai-codex 0.1.0b1__tar.gz

openai_codex-0.1.0b1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: openai-codex
+Version: 0.1.0b1
+Summary: Python SDK for Codex
+Project-URL: Homepage, https://github.com/openai/codex
+Project-URL: Repository, https://github.com/openai/codex
+Project-URL: Issues, https://github.com/openai/codex/issues
+Project-URL: Documentation, https://github.com/openai/codex/tree/main/sdk/python/docs
+Author: OpenAI
+License-Expression: Apache-2.0
+Keywords: agents,ai,codex,llm,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: openai-codex-cli-bin==0.132.0
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator==0.31.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenAI Codex Python SDK (Beta)
+
+Build Python applications that start Codex threads, run turns, stream progress,
+and control workspace access.
+
+> [!NOTE]
+> `openai-codex` is in beta. Public APIs may change before `1.0`.
+
+## Install
+
+Install the SDK:
+
+```bash
+pip install openai-codex
+```
+
+For reproducible environments, install this release exactly:
+
+```bash
+pip install openai-codex==0.1.0b1
+```
+
+The SDK requires Python `>=3.10` and installs its compatible Codex runtime
+dependency automatically. While beta releases are the only published SDK
+releases, the normal install command selects the latest beta. After a stable
+release exists, use `pip install --pre openai-codex` to explicitly select a
+newer prerelease.
+
+## Quickstart
+
+The SDK reuses your existing Codex authentication when one is already
+available:
+
+```python
+from openai_codex import Codex
+
+with Codex() as codex:
+    thread = codex.thread_start()
+    result = thread.run("Explain this repository in three bullets.")
+    print(result.final_response)
+```
+
+`thread.run(...)` returns a `TurnResult` containing the final response,
+collected items, and token usage.
+
+## Authentication
+
+Existing Codex authentication is reused automatically. To start ChatGPT
+browser login explicitly:
+
+```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)
+    login.wait()
+```
+
+For API-key login:
+
+```python
+with Codex() as codex:
+    codex.login_api_key("sk-...")
+```
+
+## Built-In Help
+
+Use Python's standard `help(openai_codex)`, `help(Codex)`, or
+`python -m pydoc openai_codex` documentation tools.
+
+## Documentation
+
+- [Getting started](https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md)
+- [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)
+- [Examples](https://github.com/openai/codex/blob/main/sdk/python/examples/README.md)
+
+The package is licensed under the
+[repository Apache License 2.0](https://github.com/openai/codex/blob/main/LICENSE).

openai_codex-0.1.0b1/README.md

@@ -0,0 +1,89 @@
+# OpenAI Codex Python SDK (Beta)
+
+Build Python applications that start Codex threads, run turns, stream progress,
+and control workspace access.
+
+> [!NOTE]
+> `openai-codex` is in beta. Public APIs may change before `1.0`.
+
+## Install
+
+Install the SDK:
+
+```bash
+pip install openai-codex
+```
+
+For reproducible environments, install this release exactly:
+
+```bash
+pip install openai-codex==0.1.0b1
+```
+
+The SDK requires Python `>=3.10` and installs its compatible Codex runtime
+dependency automatically. While beta releases are the only published SDK
+releases, the normal install command selects the latest beta. After a stable
+release exists, use `pip install --pre openai-codex` to explicitly select a
+newer prerelease.
+
+## Quickstart
+
+The SDK reuses your existing Codex authentication when one is already
+available:
+
+```python
+from openai_codex import Codex
+
+with Codex() as codex:
+    thread = codex.thread_start()
+    result = thread.run("Explain this repository in three bullets.")
+    print(result.final_response)
+```
+
+`thread.run(...)` returns a `TurnResult` containing the final response,
+collected items, and token usage.
+
+## Authentication
+
+Existing Codex authentication is reused automatically. To start ChatGPT
+browser login explicitly:
+
+```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)
+    login.wait()
+```
+
+For API-key login:
+
+```python
+with Codex() as codex:
+    codex.login_api_key("sk-...")
+```
+
+## Built-In Help
+
+Use Python's standard `help(openai_codex)`, `help(Codex)`, or
+`python -m pydoc openai_codex` documentation tools.
+
+## Documentation
+
+- [Getting started](https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md)
+- [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)
+- [Examples](https://github.com/openai/codex/blob/main/sdk/python/examples/README.md)
+
+The package is licensed under the
+[repository Apache License 2.0](https://github.com/openai/codex/blob/main/LICENSE).

openai_codex-0.1.0b1/examples/README.md

@@ -0,0 +1,91 @@
+# Python SDK Examples
+
+Each example folder contains runnable versions:
+
+- `sync.py` (public sync surface: `Codex`)
+- `async.py` (public async surface: `AsyncCodex`)
+
+All examples intentionally use only public SDK exports from `openai_codex`
+and `openai_codex.types`.
+
+Examples use plain strings for text-only turns and typed input objects for
+multimodal or structured input lists.
+
+## Prerequisites
+
+- Python `>=3.10`
+- Install the SDK for the same Python interpreter you will use to run examples
+
+Install the published beta:
+
+```bash
+python -m pip install openai-codex
+```
+
+The SDK installs its pinned `openai-codex-cli-bin` runtime dependency.
+The pinned runtime version comes from the SDK package dependency.
+
+## Run From A Checkout
+
+Contributors using these checked-in scripts should install development
+dependencies from `sdk/python`:
+
+```bash
+uv sync --extra dev
+source .venv/bin/activate
+```
+
+The examples bootstrap local SDK imports from `sdk/python/src`. If the pinned
+runtime is not already installed, the bootstrap installs the matching runtime
+package for the active interpreter and cleans up temporary files afterward.
+
+## Run examples
+
+From `sdk/python`:
+
+```bash
+python examples/<example-folder>/sync.py
+python examples/<example-folder>/async.py
+```
+
+The checked-in examples use the local SDK source tree automatically.
+
+## Recommended first run
+
+```bash
+python examples/01_quickstart_constructor/sync.py
+python examples/01_quickstart_constructor/async.py
+```
+
+## Index
+
+- `01_quickstart_constructor/`
+  - first run / sanity check
+- `02_turn_run/`
+  - inspect full turn output fields
+- `03_turn_stream_events/`
+  - stream a turn with a small curated event view
+- `04_models_and_metadata/`
+  - discover visible models for the connected runtime
+- `05_existing_thread/`
+  - resume a real existing thread (created in-script)
+- `06_thread_lifecycle_and_controls/`
+  - thread lifecycle + control calls
+- `07_image_and_text/`
+  - remote image URL + text multimodal turn
+- `08_local_image_and_text/`
+  - local image + text multimodal turn using a generated temporary sample image
+- `09_async_parity/`
+  - parity-style sync flow (see async parity in other examples)
+- `10_error_handling_and_retry/`
+  - overload retry pattern + typed error handling structure
+- `11_cli_mini_app/`
+  - interactive chat loop
+- `12_turn_params_kitchen_sink/`
+  - structured output with a curated advanced `turn(...)` configuration
+- `13_model_select_and_turn_params/`
+  - list models, pick highest model + highest supported reasoning effort, run turns, print message and usage
+- `14_turn_controls/`
+  - separate `steer()` and `interrupt()` demos with concise summaries
+- `15_login_and_account/`
+  - browser-login handle lifecycle, cancellation, and account inspection

openai_codex-0.1.0b1/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openai-codex"
+version = "0.1.0b1"
+description = "Python SDK for Codex"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "OpenAI" }]
+keywords = ["codex", "sdk", "llm", "ai", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["pydantic>=2.12", "openai-codex-cli-bin==0.132.0"]
+
+[project.urls]
+Homepage = "https://github.com/openai/codex"
+Repository = "https://github.com/openai/codex"
+Issues = "https://github.com/openai/codex/issues"
+Documentation = "https://github.com/openai/codex/tree/main/sdk/python/docs"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "datamodel-code-generator==0.31.2", "ruff>=0.15.8"]
+
+[tool.hatch.build]
+exclude = [
+  ".venv/**",
+  ".venv2/**",
+  ".pytest_cache/**",
+  "dist/**",
+  "build/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openai_codex"]
+include = [
+  "src/openai_codex/py.typed",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/openai_codex/**",
+  "README.md",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+required-version = ">=0.15.8"
+line-length = 100
+extend-exclude = [
+  "notebooks/**",
+  "src/openai_codex/generated/**",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "C4"]
+ignore = ["E501"]
+preview = true
+extend-safe-fixes = ["ALL"]
+unfixable = ["F841"]
+
+[tool.ruff.lint.per-file-ignores]
+"examples/**/*.py" = ["E402"]
+"tests/test_real_app_server_integration.py" = ["E402"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.uv]
+exclude-newer = "7 days"
+exclude-newer-package = { openai-codex-cli-bin = "2026-05-20T21:00:00Z" }
+index-strategy = "first-index"
+
+[tool.uv.pip]
+exclude-newer = "7 days"
+exclude-newer-package = { openai-codex-cli-bin = "2026-05-20T21:00:00Z" }
+index-strategy = "first-index"

openai_codex-0.1.0b1/src/openai_codex/__init__.py

@@ -0,0 +1,93 @@
+"""Python SDK for running Codex workflows.
+
+Start with :class:`Codex` for synchronous applications or
+:class:`AsyncCodex` for async applications. Most programs create a thread and
+run a turn::
+
+    from openai_codex import Codex, Sandbox
+
+    with Codex() as codex:
+        thread = codex.thread_start(sandbox=Sandbox.workspace_write)
+        result = thread.run("Describe this project.")
+        print(result.final_response)
+"""
+
+from ._version import __version__
+from .api import (
+    ApprovalMode,
+    AsyncChatgptLoginHandle,
+    AsyncCodex,
+    AsyncDeviceCodeLoginHandle,
+    AsyncThread,
+    AsyncTurnHandle,
+    ChatgptLoginHandle,
+    Codex,
+    DeviceCodeLoginHandle,
+    ImageInput,
+    Input,
+    InputItem,
+    LocalImageInput,
+    MentionInput,
+    RunInput,
+    Sandbox,
+    SkillInput,
+    TextInput,
+    Thread,
+    TurnHandle,
+    TurnResult,
+)
+from .client import CodexConfig
+from .errors import (
+    CodexError,
+    CodexRpcError,
+    InternalRpcError,
+    InvalidParamsError,
+    InvalidRequestError,
+    JsonRpcError,
+    MethodNotFoundError,
+    ParseError,
+    RetryLimitExceededError,
+    ServerBusyError,
+    TransportClosedError,
+    is_retryable_error,
+)
+from .retry import retry_on_overload
+
+__all__ = [
+    "__version__",
+    "CodexConfig",
+    "Codex",
+    "AsyncCodex",
+    "ApprovalMode",
+    "Sandbox",
+    "ChatgptLoginHandle",
+    "DeviceCodeLoginHandle",
+    "AsyncChatgptLoginHandle",
+    "AsyncDeviceCodeLoginHandle",
+    "Thread",
+    "AsyncThread",
+    "TurnHandle",
+    "AsyncTurnHandle",
+    "TurnResult",
+    "Input",
+    "InputItem",
+    "RunInput",
+    "TextInput",
+    "ImageInput",
+    "LocalImageInput",
+    "SkillInput",
+    "MentionInput",
+    "retry_on_overload",
+    "CodexError",
+    "TransportClosedError",
+    "JsonRpcError",
+    "CodexRpcError",
+    "ParseError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "InvalidParamsError",
+    "InternalRpcError",
+    "ServerBusyError",
+    "RetryLimitExceededError",
+    "is_retryable_error",
+]

openai_codex-0.1.0b1/src/openai_codex/_approval_mode.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import NoReturn
+
+from .generated.v2_all import (
+    ApprovalsReviewer,
+    AskForApproval,
+    AskForApprovalValue,
+)
+
+
+class ApprovalMode(str, Enum):
+    """High-level approval behavior for escalated permission requests."""
+
+    deny_all = "deny_all"
+    auto_review = "auto_review"
+
+
+def _approval_mode_settings(
+    approval_mode: ApprovalMode,
+) -> tuple[AskForApproval, ApprovalsReviewer | None]:
+    """Map the public approval mode to generated app-server start params."""
+    if not isinstance(approval_mode, ApprovalMode):
+        supported = ", ".join(mode.value for mode in ApprovalMode)
+        raise ValueError(f"approval_mode must be one of: {supported}")
+
+    match approval_mode:
+        case ApprovalMode.auto_review:
+            return (
+                AskForApproval(root=AskForApprovalValue.on_request),
+                ApprovalsReviewer.auto_review,
+            )
+        case ApprovalMode.deny_all:
+            return AskForApproval(root=AskForApprovalValue.never), None
+        case _:
+            return _assert_never_approval_mode(approval_mode)
+
+
+def _assert_never_approval_mode(approval_mode: NoReturn) -> NoReturn:
+    """Make approval mode mapping exhaustive for static type checkers."""
+    raise AssertionError(f"Unhandled approval mode: {approval_mode!r}")
+
+
+def _approval_mode_override_settings(
+    approval_mode: ApprovalMode | None,
+) -> tuple[AskForApproval | None, ApprovalsReviewer | None]:
+    """Map an optional public approval mode to app-server override params."""
+    if approval_mode is None:
+        return None, None
+    return _approval_mode_settings(approval_mode)

openai_codex-0.1.0b1/src/openai_codex/_initialize_metadata.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from .models import InitializeResponse, ServerInfo
+
+
+def _split_user_agent(user_agent: str) -> tuple[str | None, str | None]:
+    raw = user_agent.strip()
+    if not raw:
+        return None, None
+    if "/" in raw:
+        name, version = raw.split("/", 1)
+        return (name or None), (version or None)
+    parts = raw.split(maxsplit=1)
+    if len(parts) == 2:
+        return parts[0], parts[1]
+    return raw, None
+
+
+def validate_initialize_metadata(payload: InitializeResponse) -> InitializeResponse:
+    user_agent = (payload.userAgent or "").strip()
+    server = payload.serverInfo
+
+    server_name: str | None = None
+    server_version: str | None = None
+
+    if server is not None:
+        server_name = (server.name or "").strip() or None
+        server_version = (server.version or "").strip() or None
+
+    if (server_name is None or server_version is None) and user_agent:
+        parsed_name, parsed_version = _split_user_agent(user_agent)
+        if server_name is None:
+            server_name = parsed_name
+        if server_version is None:
+            server_version = parsed_version
+
+    normalized_server_name = (server_name or "").strip()
+    normalized_server_version = (server_version or "").strip()
+    if not user_agent or not normalized_server_name or not normalized_server_version:
+        raise RuntimeError(
+            "initialize response missing required metadata "
+            f"(user_agent={user_agent!r}, server_name={normalized_server_name!r}, server_version={normalized_server_version!r})"
+        )
+
+    if server is None:
+        payload.serverInfo = ServerInfo(
+            name=normalized_server_name,
+            version=normalized_server_version,
+        )
+    else:
+        server.name = normalized_server_name
+        server.version = normalized_server_version
+
+    return payload

openai_codex-0.1.0b1/src/openai_codex/_inputs.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .models import JsonObject
+
+
+@dataclass(slots=True)
+class TextInput:
+    """Text supplied to a turn or steering request."""
+
+    text: str
+
+
+@dataclass(slots=True)
+class ImageInput:
+    """Remote image URL supplied as turn input."""
+
+    url: str
+
+
+@dataclass(slots=True)
+class LocalImageInput:
+    """Local image path supplied as turn input."""
+
+    path: str
+
+
+@dataclass(slots=True)
+class SkillInput:
+    """Named skill reference supplied as turn input."""
+
+    name: str
+    path: str
+
+
+@dataclass(slots=True)
+class MentionInput:
+    """Named resource mention supplied as turn input."""
+
+    name: str
+    path: str
+
+
+InputItem = TextInput | ImageInput | LocalImageInput | SkillInput | MentionInput
+Input = list[InputItem] | InputItem
+RunInput = Input | str
+
+
+def _to_wire_item(item: InputItem) -> JsonObject:
+    if isinstance(item, TextInput):
+        return {"type": "text", "text": item.text}
+    if isinstance(item, ImageInput):
+        return {"type": "image", "url": item.url}
+    if isinstance(item, LocalImageInput):
+        return {"type": "localImage", "path": item.path}
+    if isinstance(item, SkillInput):
+        return {"type": "skill", "name": item.name, "path": item.path}
+    if isinstance(item, MentionInput):
+        return {"type": "mention", "name": item.name, "path": item.path}
+    raise TypeError(f"unsupported input item: {type(item)!r}")
+
+
+def _to_wire_input(input: Input) -> list[JsonObject]:
+    if isinstance(input, list):
+        return [_to_wire_item(i) for i in input]
+    return [_to_wire_item(input)]
+
+
+def _normalize_run_input(input: RunInput) -> Input:
+    if isinstance(input, str):
+        return TextInput(input)
+    return input