codex-python 0.3.0__tar.gz → 1.0.0b2__tar.gz

codex_python-1.0.0b2/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 1.0.0b2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Classifier: Operating System :: OS Independent
+License-File: LICENSE
+Summary: Python SDK for Codex CLI with bundled platform binaries
+Keywords: codex,sdk,cli,automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/gersmann/codex-python
+Project-URL: Issues, https://github.com/gersmann/codex-python/issues
+Project-URL: Repository, https://github.com/gersmann/codex-python
+
+# codex-python
+
+Python SDK for Codex with bundled `codex` binaries inside platform wheels.
+
+The SDK mirrors the TypeScript SDK behavior:
+- Spawns `codex exec --experimental-json`
+- Streams JSONL events
+- Supports thread resume, structured output schemas, images, sandbox/model options
+
+## Install
+
+```bash
+pip install codex-python
+```
+
+## Quickstart
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+
+result = thread.run("Diagnose the failing tests and propose a fix")
+print(result.final_response)
+print(result.items)
+```
+
+## Streaming
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+
+stream = thread.run_streamed("Investigate this bug")
+for event in stream.events:
+    if event["type"] == "item.completed":
+        print(event["item"])
+    elif event["type"] == "turn.completed":
+        print(event["usage"])
+```
+
+## Structured output
+
+```python
+from codex import Codex, TurnOptions
+
+schema = {
+    "type": "object",
+    "properties": {"summary": {"type": "string"}},
+    "required": ["summary"],
+    "additionalProperties": False,
+}
+
+client = Codex()
+thread = client.start_thread()
+result = thread.run("Summarize repository status", TurnOptions(output_schema=schema))
+print(result.final_response)
+```
+
+## Input with local images
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+result = thread.run(
+    [
+        {"type": "text", "text": "Describe these screenshots"},
+        {"type": "local_image", "path": "./ui.png"},
+        {"type": "local_image", "path": "./diagram.jpg"},
+    ]
+)
+```
+
+## Resume a thread
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.resume_thread("thread_123")
+thread.run("Continue from previous context")
+```
+
+## Options
+
+- `CodexOptions`: `codex_path_override`, `base_url`, `api_key`, `config`, `env`
+- `ThreadOptions`: `model`, `sandbox_mode`, `working_directory`, `skip_git_repo_check`, `model_reasoning_effort`, `network_access_enabled`, `web_search_mode`, `web_search_enabled`, `approval_policy`, `additional_directories`
+- `TurnOptions`: `output_schema`, `signal`
+
+## Cancellation
+
+```python
+import threading
+
+from codex import Codex, TurnOptions
+
+cancel = threading.Event()
+
+client = Codex()
+thread = client.start_thread()
+stream = thread.run_streamed("Long running task", TurnOptions(signal=cancel))
+
+cancel.set()
+for event in stream.events:
+    print(event)
+```
+
+## Bundled binary behavior
+
+By default, the SDK resolves the bundled binary at:
+
+`codex/vendor/<target-triple>/codex/{codex|codex.exe}`
+
+If the bundled binary is not present (for example in a source checkout), the SDK falls back to
+`codex` on `PATH`.
+
+You can always override with `CodexOptions(codex_path_override=...)`.
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+If you want to test vendored-binary behavior locally, fetch binaries into `codex/vendor`:
+
+```bash
+python scripts/fetch_codex_binary.py --target-triple x86_64-unknown-linux-musl
+```
+

codex_python-1.0.0b2/README.md

@@ -0,0 +1,135 @@
+# codex-python
+
+Python SDK for Codex with bundled `codex` binaries inside platform wheels.
+
+The SDK mirrors the TypeScript SDK behavior:
+- Spawns `codex exec --experimental-json`
+- Streams JSONL events
+- Supports thread resume, structured output schemas, images, sandbox/model options
+
+## Install
+
+```bash
+pip install codex-python
+```
+
+## Quickstart
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+
+result = thread.run("Diagnose the failing tests and propose a fix")
+print(result.final_response)
+print(result.items)
+```
+
+## Streaming
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+
+stream = thread.run_streamed("Investigate this bug")
+for event in stream.events:
+    if event["type"] == "item.completed":
+        print(event["item"])
+    elif event["type"] == "turn.completed":
+        print(event["usage"])
+```
+
+## Structured output
+
+```python
+from codex import Codex, TurnOptions
+
+schema = {
+    "type": "object",
+    "properties": {"summary": {"type": "string"}},
+    "required": ["summary"],
+    "additionalProperties": False,
+}
+
+client = Codex()
+thread = client.start_thread()
+result = thread.run("Summarize repository status", TurnOptions(output_schema=schema))
+print(result.final_response)
+```
+
+## Input with local images
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.start_thread()
+result = thread.run(
+    [
+        {"type": "text", "text": "Describe these screenshots"},
+        {"type": "local_image", "path": "./ui.png"},
+        {"type": "local_image", "path": "./diagram.jpg"},
+    ]
+)
+```
+
+## Resume a thread
+
+```python
+from codex import Codex
+
+client = Codex()
+thread = client.resume_thread("thread_123")
+thread.run("Continue from previous context")
+```
+
+## Options
+
+- `CodexOptions`: `codex_path_override`, `base_url`, `api_key`, `config`, `env`
+- `ThreadOptions`: `model`, `sandbox_mode`, `working_directory`, `skip_git_repo_check`, `model_reasoning_effort`, `network_access_enabled`, `web_search_mode`, `web_search_enabled`, `approval_policy`, `additional_directories`
+- `TurnOptions`: `output_schema`, `signal`
+
+## Cancellation
+
+```python
+import threading
+
+from codex import Codex, TurnOptions
+
+cancel = threading.Event()
+
+client = Codex()
+thread = client.start_thread()
+stream = thread.run_streamed("Long running task", TurnOptions(signal=cancel))
+
+cancel.set()
+for event in stream.events:
+    print(event)
+```
+
+## Bundled binary behavior
+
+By default, the SDK resolves the bundled binary at:
+
+`codex/vendor/<target-triple>/codex/{codex|codex.exe}`
+
+If the bundled binary is not present (for example in a source checkout), the SDK falls back to
+`codex` on `PATH`.
+
+You can always override with `CodexOptions(codex_path_override=...)`.
+
+## Development
+
+```bash
+make lint
+make test
+```
+
+If you want to test vendored-binary behavior locally, fetch binaries into `codex/vendor`:
+
+```bash
+python scripts/fetch_codex_binary.py --target-triple x86_64-unknown-linux-musl
+```

codex_python-1.0.0b2/codex/__init__.py

@@ -0,0 +1,85 @@
+"""Python SDK for embedding Codex via the bundled CLI binary."""
+
+from codex.codex import Codex
+from codex.errors import CodexError, CodexExecError, CodexParseError, ThreadRunError
+from codex.events import (
+    ItemCompletedEvent,
+    ItemStartedEvent,
+    ItemUpdatedEvent,
+    ThreadError,
+    ThreadErrorEvent,
+    ThreadEvent,
+    ThreadStartedEvent,
+    TurnCompletedEvent,
+    TurnFailedEvent,
+    TurnStartedEvent,
+    Usage,
+)
+from codex.items import (
+    AgentMessageItem,
+    CommandExecutionItem,
+    ErrorItem,
+    FileChangeItem,
+    McpToolCallItem,
+    ReasoningItem,
+    ThreadItem,
+    TodoListItem,
+    WebSearchItem,
+)
+from codex.options import (
+    ApprovalMode,
+    CancelSignal,
+    CodexConfigObject,
+    CodexConfigValue,
+    CodexOptions,
+    ModelReasoningEffort,
+    SandboxMode,
+    ThreadOptions,
+    TurnOptions,
+    WebSearchMode,
+)
+from codex.thread import Input, RunResult, RunStreamedResult, Thread, UserInput
+	.0.0-beta.2"
+
+__all__ = [
+    "Codex",
+    "CodexError",
+    "CodexExecError",
+    "CodexParseError",
+    "ThreadRunError",
+    "Thread",
+    "RunResult",
+    "RunStreamedResult",
+    "Input",
+    "UserInput",
+    "CodexOptions",
+    "ThreadOptions",
+    "TurnOptions",
+    "ApprovalMode",
+    "SandboxMode",
+    "ModelReasoningEffort",
+    "WebSearchMode",
+    "CodexConfigValue",
+    "CodexConfigObject",
+    "CancelSignal",
+    "ThreadEvent",
+    "ThreadStartedEvent",
+    "TurnStartedEvent",
+    "TurnCompletedEvent",
+    "TurnFailedEvent",
+    "ItemStartedEvent",
+    "ItemUpdatedEvent",
+    "ItemCompletedEvent",
+    "ThreadError",
+    "ThreadErrorEvent",
+    "Usage",
+    "ThreadItem",
+    "AgentMessageItem",
+    "ReasoningItem",
+    "CommandExecutionItem",
+    "FileChangeItem",
+    "McpToolCallItem",
+    "WebSearchItem",
+    "TodoListItem",
+    "ErrorItem",
+]

codex_python-1.0.0b2/codex/_binary.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import platform
+from pathlib import Path
+
+from codex.errors import CodexExecError
+
+
+def resolve_target_triple(system_name: str | None = None, machine_name: str | None = None) -> str:
+    system = (system_name or platform.system()).lower()
+    machine = (machine_name or platform.machine()).lower()
+
+    if system in {"linux", "android"}:
+        if machine in {"x86_64", "amd64"}:
+            return "x86_64-unknown-linux-musl"
+        if machine in {"aarch64", "arm64"}:
+            return "aarch64-unknown-linux-musl"
+    elif system == "darwin":
+        if machine in {"x86_64", "amd64"}:
+            return "x86_64-apple-darwin"
+        if machine in {"aarch64", "arm64"}:
+            return "aarch64-apple-darwin"
+    elif system in {"windows", "win32"}:
+        if machine in {"x86_64", "amd64"}:
+            return "x86_64-pc-windows-msvc"
+        if machine in {"aarch64", "arm64"}:
+            return "aarch64-pc-windows-msvc"
+
+    raise CodexExecError(f"Unsupported platform: {system} ({machine})")
+
+
+def bundled_codex_path(target_triple: str | None = None) -> Path:
+    triple = target_triple or resolve_target_triple()
+    package_root = Path(__file__).resolve().parent
+    binary_name = "codex.exe" if "windows" in triple else "codex"
+    binary_path = package_root / "vendor" / triple / "codex" / binary_name
+    if not binary_path.exists():
+        raise CodexExecError(
+            "Bundled codex binary not found at "
+            f"{binary_path}. Install a platform wheel or provide codex_path_override."
+        )
+    return binary_path

codex_python-1.0.0b2/codex/codex.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from codex.exec import CodexExec
+from codex.options import CodexOptions, ThreadOptions
+from codex.thread import Thread
+
+
+class Codex:
+    """Main entrypoint for interacting with Codex threads."""
+
+    def __init__(self, options: CodexOptions | None = None) -> None:
+        resolved = options or CodexOptions()
+        self._exec = CodexExec(
+            resolved.codex_path_override,
+            env_override=resolved.env,
+            config_overrides=resolved.config,
+        )
+        self._options = resolved
+
+    def start_thread(self, options: ThreadOptions | None = None) -> Thread:
+        return Thread(self._exec, self._options, options or ThreadOptions())
+
+    def resume_thread(self, id: str, options: ThreadOptions | None = None) -> Thread:
+        if id == "":
+            raise ValueError("id must be non-empty")
+        return Thread(self._exec, self._options, options or ThreadOptions(), id)

codex_python-1.0.0b2/codex/errors.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+class CodexError(RuntimeError):
+    """Base error for the Python Codex SDK."""
+
+
+class CodexExecError(CodexError):
+    """Raised when the Codex CLI process fails."""
+
+
+class CodexParseError(CodexError):
+    """Raised when streaming JSONL events cannot be parsed."""
+
+
+class ThreadRunError(CodexError):
+    """Raised when a run or stream fails before turn completion."""

codex_python-1.0.0b2/codex/events.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+from codex.items import ThreadItem
+
+
+class ThreadStartedEvent(TypedDict):
+    type: Literal["thread.started"]
+    thread_id: str
+
+
+class TurnStartedEvent(TypedDict):
+    type: Literal["turn.started"]
+
+
+class Usage(TypedDict):
+    input_tokens: int
+    cached_input_tokens: int
+    output_tokens: int
+
+
+class TurnCompletedEvent(TypedDict):
+    type: Literal["turn.completed"]
+    usage: Usage
+
+
+class ThreadError(TypedDict):
+    message: str
+
+
+class TurnFailedEvent(TypedDict):
+    type: Literal["turn.failed"]
+    error: ThreadError
+
+
+class ItemStartedEvent(TypedDict):
+    type: Literal["item.started"]
+    item: ThreadItem
+
+
+class ItemUpdatedEvent(TypedDict):
+    type: Literal["item.updated"]
+    item: ThreadItem
+
+
+class ItemCompletedEvent(TypedDict):
+    type: Literal["item.completed"]
+    item: ThreadItem
+
+
+class ThreadErrorEvent(TypedDict):
+    type: Literal["error"]
+    message: str
+
+
+ThreadEvent = (
+    ThreadStartedEvent
+    | TurnStartedEvent
+    | TurnCompletedEvent
+    | TurnFailedEvent
+    | ItemStartedEvent
+    | ItemUpdatedEvent
+    | ItemCompletedEvent
+    | ThreadErrorEvent
+)