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

codex_python-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: codex-python
+Version: 1.0.0
+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`
+- `ThreadOptions`: `model`, `sandbox_mode`, `working_directory`, `skip_git_repo_check`
+- `TurnOptions`: `output_schema`
+
+## 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.0/README.md

@@ -0,0 +1,117 @@
+# 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`
+- `ThreadOptions`: `model`, `sandbox_mode`, `working_directory`, `skip_git_repo_check`
+- `TurnOptions`: `output_schema`
+
+## 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.0/codex/__init__.py

@@ -0,0 +1,70 @@
+"""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, CodexOptions, SandboxMode, ThreadOptions, TurnOptions
+from codex.thread import Input, RunResult, RunStreamedResult, Thread, UserInput
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Codex",
+    "CodexError",
+    "CodexExecError",
+    "CodexParseError",
+    "ThreadRunError",
+    "Thread",
+    "RunResult",
+    "RunStreamedResult",
+    "Input",
+    "UserInput",
+    "CodexOptions",
+    "ThreadOptions",
+    "TurnOptions",
+    "ApprovalMode",
+    "SandboxMode",
+    "ThreadEvent",
+    "ThreadStartedEvent",
+    "TurnStartedEvent",
+    "TurnCompletedEvent",
+    "TurnFailedEvent",
+    "ItemStartedEvent",
+    "ItemUpdatedEvent",
+    "ItemCompletedEvent",
+    "ThreadError",
+    "ThreadErrorEvent",
+    "Usage",
+    "ThreadItem",
+    "AgentMessageItem",
+    "ReasoningItem",
+    "CommandExecutionItem",
+    "FileChangeItem",
+    "McpToolCallItem",
+    "WebSearchItem",
+    "TodoListItem",
+    "ErrorItem",
+]

codex_python-1.0.0/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.0/codex/codex.py

@@ -0,0 +1,22 @@
+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)
+        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.0/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.0/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
+)

codex_python-1.0.0/codex/exec.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from codex._binary import bundled_codex_path
+from codex.errors import CodexExecError
+from codex.options import SandboxMode
+
+INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE"
+PYTHON_SDK_ORIGINATOR = "codex_sdk_py"
+
+
+@dataclass(slots=True, frozen=True)
+class CodexExecArgs:
+    input: str
+    base_url: str | None = None
+    api_key: str | None = None
+    thread_id: str | None = None
+    images: list[str] | None = None
+    model: str | None = None
+    sandbox_mode: SandboxMode | None = None
+    working_directory: str | None = None
+    skip_git_repo_check: bool = False
+    output_schema_file: str | None = None
+
+
+class CodexExec:
+    def __init__(self, executable_path: str | None = None) -> None:
+        if executable_path is not None:
+            path = Path(executable_path)
+        else:
+            try:
+                path = bundled_codex_path()
+            except CodexExecError as bundled_error:
+                system_codex = shutil.which("codex")
+                if system_codex is None:
+                    raise CodexExecError(
+                        f"{bundled_error} Also failed to find `codex` on PATH."
+                    ) from bundled_error
+                path = Path(system_codex)
+        self.executable_path = str(path)
+
+    def run(self, args: CodexExecArgs) -> Iterator[str]:
+        command_args: list[str] = ["exec", "--experimental-json"]
+
+        if args.model is not None:
+            command_args.extend(["--model", args.model])
+        if args.sandbox_mode is not None:
+            command_args.extend(["--sandbox", args.sandbox_mode])
+        if args.working_directory is not None:
+            command_args.extend(["--cd", args.working_directory])
+        if args.skip_git_repo_check:
+            command_args.append("--skip-git-repo-check")
+        if args.output_schema_file is not None:
+            command_args.extend(["--output-schema", args.output_schema_file])
+        if args.images is not None:
+            for image in args.images:
+                command_args.extend(["--image", image])
+        if args.thread_id:
+            command_args.extend(["resume", args.thread_id])
+
+        env = os.environ.copy()
+        if INTERNAL_ORIGINATOR_ENV not in env:
+            env[INTERNAL_ORIGINATOR_ENV] = PYTHON_SDK_ORIGINATOR
+        if args.base_url is not None:
+            env["OPENAI_BASE_URL"] = args.base_url
+        if args.api_key is not None:
+            env["CODEX_API_KEY"] = args.api_key
+
+        try:
+            child = subprocess.Popen(
+                [self.executable_path, *command_args],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                env=env,
+            )
+        except OSError as exc:
+            raise CodexExecError(
+                f"Failed to spawn codex executable at '{self.executable_path}': {exc}"
+            ) from exc
+
+        if child.stdin is None:
+            child.kill()
+            raise CodexExecError("Child process has no stdin")
+        if child.stdout is None:
+            child.kill()
+            raise CodexExecError("Child process has no stdout")
+        if child.stderr is None:
+            child.kill()
+            raise CodexExecError("Child process has no stderr")
+
+        try:
+            child.stdin.write(args.input)
+            child.stdin.close()
+        except OSError as exc:
+            child.kill()
+            raise CodexExecError(f"Failed to write input to codex process: {exc}") from exc
+
+        try:
+            for line in child.stdout:
+                yield line.rstrip("\r\n")
+        finally:
+            child.stdout.close()
+
+        exit_code = child.wait()
+        stderr = child.stderr.read()
+        child.stderr.close()
+
+        if exit_code != 0:
+            raise CodexExecError(f"Codex exec exited with code {exit_code}: {stderr}")

codex_python-1.0.0/codex/items.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypedDict
+
+CommandExecutionStatus = Literal["in_progress", "completed", "failed"]
+PatchChangeKind = Literal["add", "delete", "update"]
+PatchApplyStatus = Literal["completed", "failed"]
+McpToolCallStatus = Literal["in_progress", "completed", "failed"]
+
+
+class CommandExecutionItem(TypedDict):
+    id: str
+    type: Literal["command_execution"]
+    command: str
+    aggregated_output: str
+    status: CommandExecutionStatus
+    exit_code: NotRequired[int]
+
+
+class FileUpdateChange(TypedDict):
+    path: str
+    kind: PatchChangeKind
+
+
+class FileChangeItem(TypedDict):
+    id: str
+    type: Literal["file_change"]
+    changes: list[FileUpdateChange]
+    status: PatchApplyStatus
+
+
+class McpToolCallItem(TypedDict):
+    id: str
+    type: Literal["mcp_tool_call"]
+    server: str
+    tool: str
+    status: McpToolCallStatus
+
+
+class AgentMessageItem(TypedDict):
+    id: str
+    type: Literal["agent_message"]
+    text: str
+
+
+class ReasoningItem(TypedDict):
+    id: str
+    type: Literal["reasoning"]
+    text: str
+
+
+class WebSearchItem(TypedDict):
+    id: str
+    type: Literal["web_search"]
+    query: str
+
+
+class ErrorItem(TypedDict):
+    id: str
+    type: Literal["error"]
+    message: str
+
+
+class TodoItem(TypedDict):
+    text: str
+    completed: bool
+
+
+class TodoListItem(TypedDict):
+    id: str
+    type: Literal["todo_list"]
+    items: list[TodoItem]
+
+
+ThreadItem = (
+    AgentMessageItem
+    | ReasoningItem
+    | CommandExecutionItem
+    | FileChangeItem
+    | McpToolCallItem
+    | WebSearchItem
+    | TodoListItem
+    | ErrorItem
+)

codex_python-1.0.0/codex/options.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ApprovalMode = Literal["never", "on-request", "on-failure", "untrusted"]
+SandboxMode = Literal["read-only", "workspace-write", "danger-full-access"]
+
+
+@dataclass(slots=True, frozen=True)
+class CodexOptions:
+    codex_path_override: str | None = None
+    base_url: str | None = None
+    api_key: str | None = None
+
+
+@dataclass(slots=True, frozen=True)
+class ThreadOptions:
+    model: str | None = None
+    sandbox_mode: SandboxMode | None = None
+    working_directory: str | None = None
+    skip_git_repo_check: bool = False
+
+
+@dataclass(slots=True, frozen=True)
+class TurnOptions:
+    output_schema: dict[str, object] | None = None