codex-sdk-py 0.0.3__py3-none-any.whl

codex_sdk/__init__.py

@@ -0,0 +1,135 @@
+"""
+Codex SDK for Python.
+
+A Python SDK for the OpenAI Codex agent.
+
+Corresponds to: src/index.ts
+"""
+
+from __future__ import annotations
+
+# Main classes
+from .codex import Codex
+
+# Options
+from .codex_options import (
+    CodexConfigObject,
+    CodexConfigValue,
+    CodexOptions,
+)
+
+# Events
+from .events import (
+    ItemCompletedEvent,
+    ItemStartedEvent,
+    ItemUpdatedEvent,
+    ThreadError,
+    ThreadErrorEvent,
+    ThreadEvent,
+    ThreadStartedEvent,
+    TurnCompletedEvent,
+    TurnFailedEvent,
+    TurnStartedEvent,
+    Usage,
+)
+
+# Items
+from .items import (
+    AgentMessageItem,
+    CommandExecutionItem,
+    CommandExecutionStatus,
+    ErrorItem,
+    FileChangeItem,
+    FileUpdateChange,
+    McpContentBlock,
+    McpToolCallItem,
+    McpToolCallStatus,
+    McpToolError,
+    McpToolResult,
+    PatchApplyStatus,
+    PatchChangeKind,
+    ReasoningItem,
+    ThreadItem,
+    TodoItem,
+    TodoListItem,
+    WebSearchItem,
+)
+from .thread import (
+    ImageUserInput,
+    Input,
+    RunResult,
+    RunStreamedResult,
+    StreamedTurn,
+    TextUserInput,
+    Thread,
+    Turn,
+    UserInput,
+)
+from .thread_options import (
+    ApprovalMode,
+    ModelReasoningEffort,
+    SandboxMode,
+    ThreadOptions,
+    WebSearchMode,
+)
+from .turn_options import TurnOptions
+
+__version__ = "0.0.3"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes
+    "Codex",
+    "Thread",
+    "Turn",
+    "RunResult",
+    "StreamedTurn",
+    "RunStreamedResult",
+    # Input types
+    "Input",
+    "UserInput",
+    "TextUserInput",
+    "ImageUserInput",
+    # Events
+    "ThreadEvent",
+    "ThreadStartedEvent",
+    "TurnStartedEvent",
+    "TurnCompletedEvent",
+    "TurnFailedEvent",
+    "ItemStartedEvent",
+    "ItemUpdatedEvent",
+    "ItemCompletedEvent",
+    "ThreadError",
+    "ThreadErrorEvent",
+    "Usage",
+    # Items
+    "ThreadItem",
+    "AgentMessageItem",
+    "ReasoningItem",
+    "CommandExecutionItem",
+    "CommandExecutionStatus",
+    "FileChangeItem",
+    "FileUpdateChange",
+    "PatchChangeKind",
+    "PatchApplyStatus",
+    "McpToolCallItem",
+    "McpToolCallStatus",
+    "McpToolResult",
+    "McpToolError",
+    "McpContentBlock",
+    "WebSearchItem",
+    "TodoListItem",
+    "TodoItem",
+    "ErrorItem",
+    # Options
+    "CodexOptions",
+    "CodexConfigValue",
+    "CodexConfigObject",
+    "ThreadOptions",
+    "ApprovalMode",
+    "SandboxMode",
+    "ModelReasoningEffort",
+    "WebSearchMode",
+    "TurnOptions",
+]

codex_sdk/codex.py

@@ -0,0 +1,79 @@
+"""
+Main Codex class for interacting with the Codex agent.
+
+Corresponds to: src/codex.ts
+"""
+
+from __future__ import annotations
+
+from .codex_options import CodexOptions
+from .exec import CodexExec
+from .thread import Thread
+from .thread_options import ThreadOptions
+
+
+class Codex:
+    """
+    Codex is the main class for interacting with the Codex agent.
+
+    Use the `start_thread()` method to start a new thread or
+    `resume_thread()` to resume a previously started thread.
+
+    Example:
+        ```python
+        from codex_sdk import Codex
+
+        codex = Codex()
+        thread = codex.start_thread()
+        result = await thread.run("Hello, world!")
+        print(result.final_response)
+        ```
+    """
+
+    def __init__(self, options: CodexOptions | None = None) -> None:
+        """
+        Initialize the Codex client.
+
+        Args:
+            options: Optional configuration for the Codex client.
+        """
+        options = options or {}
+        self._exec = CodexExec(
+            executable_path=options.get("codex_path_override"),
+            env=options.get("env"),
+            config_overrides=options.get("config"),
+        )
+        self._options = options
+
+    def start_thread(self, options: ThreadOptions | None = None) -> Thread:
+        """
+        Starts a new conversation with an agent.
+
+        Args:
+            options: Optional thread-specific configuration.
+
+        Returns:
+            A new Thread instance.
+        """
+        options = options or {}
+        return Thread(self._exec, self._options, options)
+
+    def resume_thread(
+        self,
+        thread_id: str,
+        options: ThreadOptions | None = None,
+    ) -> Thread:
+        """
+        Resumes a conversation with an agent based on the thread id.
+
+        Threads are persisted in ~/.codex/sessions.
+
+        Args:
+            thread_id: The id of the thread to resume.
+            options: Optional thread-specific configuration.
+
+        Returns:
+            A Thread instance connected to the existing conversation.
+        """
+        options = options or {}
+        return Thread(self._exec, self._options, options, thread_id)

codex_sdk/codex_options.py

@@ -0,0 +1,53 @@
+"""
+Codex options type definitions.
+
+Corresponds to: src/codexOptions.ts
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict, Union
+
+# Recursive type for config values
+CodexConfigValue = Union[
+    str,
+    int,
+    float,
+    bool,
+    list["CodexConfigValue"],
+    "CodexConfigObject",
+]
+
+
+class CodexConfigObject(TypedDict, total=False):
+    """A nested configuration object for Codex CLI overrides."""
+
+    pass
+
+
+class CodexOptions(TypedDict, total=False):
+    """Configuration options for the Codex client."""
+
+    codex_path_override: str
+    """Custom path to the Codex CLI binary."""
+
+    base_url: str
+    """Base URL for the API."""
+
+    api_key: str
+    """API key for authentication."""
+
+    config: CodexConfigObject
+    """
+    Additional --config key=value overrides to pass to the Codex CLI.
+
+    Provide a dict and the SDK will flatten it into dotted paths and
+    serialize values as TOML literals so they are compatible with the CLI's
+    --config parsing.
+    """
+
+    env: dict[str, str]
+    """
+    Environment variables passed to the Codex CLI process.
+    When provided, the SDK will not inherit variables from os.environ.
+    """

codex_sdk/events.py

@@ -0,0 +1,107 @@
+"""
+Thread event type definitions.
+
+Based on event types from codex-rs/exec/src/exec_events.rs
+
+Corresponds to: src/events.ts
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+from .items import ThreadItem
+
+
+class Usage(TypedDict):
+    """Describes the usage of tokens during a turn."""
+
+    input_tokens: int
+    """The number of input tokens used during the turn."""
+    cached_input_tokens: int
+    """The number of cached input tokens used during the turn."""
+    output_tokens: int
+    """The number of output tokens used during the turn."""
+
+
+class ThreadError(TypedDict):
+    """Fatal error emitted by the stream."""
+
+    message: str
+
+
+class ThreadStartedEvent(TypedDict):
+    """Emitted when a new thread is started as the first event."""
+
+    type: Literal["thread.started"]
+    thread_id: str
+    """The identifier of the new thread. Can be used to resume the thread later."""
+
+
+class TurnStartedEvent(TypedDict):
+    """
+    Emitted when a turn is started by sending a new prompt to the model.
+
+    A turn encompasses all events that happen while the agent is processing the prompt.
+    """
+
+    type: Literal["turn.started"]
+
+
+class TurnCompletedEvent(TypedDict):
+    """Emitted when a turn is completed. Typically right after the assistant's response."""
+
+    type: Literal["turn.completed"]
+    usage: Usage
+
+
+class TurnFailedEvent(TypedDict):
+    """Indicates that a turn failed with an error."""
+
+    type: Literal["turn.failed"]
+    error: ThreadError
+
+
+class ItemStartedEvent(TypedDict):
+    """
+    Emitted when a new item is added to the thread.
+
+    Typically the item is initially 'in progress'.
+    """
+
+    type: Literal["item.started"]
+    item: ThreadItem
+
+
+class ItemUpdatedEvent(TypedDict):
+    """Emitted when an item is updated."""
+
+    type: Literal["item.updated"]
+    item: ThreadItem
+
+
+class ItemCompletedEvent(TypedDict):
+    """Signals that an item has reached a terminal state—either success or failure."""
+
+    type: Literal["item.completed"]
+    item: ThreadItem
+
+
+class ThreadErrorEvent(TypedDict):
+    """Represents an unrecoverable error emitted directly by the event stream."""
+
+    type: Literal["error"]
+    message: str
+
+
+# Top-level JSONL events emitted by codex exec
+ThreadEvent = (
+    ThreadStartedEvent
+    | TurnStartedEvent
+    | TurnCompletedEvent
+    | TurnFailedEvent
+    | ItemStartedEvent
+    | ItemUpdatedEvent
+    | ItemCompletedEvent
+    | ThreadErrorEvent
+)