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

codex_sdk_py-0.0.3.dist-info/METADATA

@@ -0,0 +1,423 @@
+Metadata-Version: 2.4
+Name: codex-sdk-py
+Version: 0.0.3
+Summary: Python SDK for the OpenAI Codex agent
+Project-URL: Homepage, https://github.com/nogataka/codex-sdk-python
+Project-URL: Documentation, https://github.com/nogataka/codex-sdk-python#readme
+Project-URL: Repository, https://github.com/nogataka/codex-sdk-python
+Project-URL: Issues, https://github.com/nogataka/codex-sdk-python/issues
+Author-email: OpenAI <support@openai.com>
+License-Expression: Apache-2.0
+Keywords: agent,ai,codex,openai,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Codex SDK for Python
+
+Embed the Codex agent in your workflows and apps.
+
+The Python SDK wraps the bundled `codex` binary. It spawns the CLI and exchanges JSONL events over stdin/stdout.
+
+## Installation
+
+```bash
+pip install codex-sdk-py
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+import asyncio
+from codex_sdk import Codex
+
+async def main():
+    codex = Codex()
+    thread = codex.start_thread()
+    turn = await thread.run("Diagnose the test failure and propose a fix")
+
+    print(turn.final_response)
+    print(turn.items)
+
+asyncio.run(main())
+```
+
+Call `run()` repeatedly on the same `Thread` instance to continue that conversation.
+
+```python
+next_turn = await thread.run("Implement the fix")
+```
+
+### Streaming responses
+
+`run()` buffers events until the turn finishes. To react to intermediate progress—tool calls, streaming responses, and file change notifications—use `run_streamed()` instead, which returns an async generator of structured events.
+
+```python
+async def stream_example():
+    codex = Codex()
+    thread = codex.start_thread()
+
+    streamed = await thread.run_streamed("Diagnose the test failure and propose a fix")
+
+    async for event in streamed.events:
+        match event.get("type"):
+            case "item.completed":
+                print("item", event.get("item"))
+            case "turn.completed":
+                print("usage", event.get("usage"))
+```
+
+### Structured output
+
+The Codex agent can produce a JSON response that conforms to a specified schema. The schema can be provided for each turn as a plain JSON object.
+
+```python
+schema = {
+    "type": "object",
+    "properties": {
+        "summary": {"type": "string"},
+        "status": {"type": "string", "enum": ["ok", "action_required"]},
+    },
+    "required": ["summary", "status"],
+    "additionalProperties": False,
+}
+
+turn = await thread.run("Summarize repository status", {"output_schema": schema})
+print(turn.final_response)
+```
+
+You can also create a JSON schema from a [Pydantic model](https://docs.pydantic.dev/) using `model_json_schema()`.
+
+```python
+from pydantic import BaseModel
+from typing import Literal
+
+class StatusResponse(BaseModel):
+    summary: str
+    status: Literal["ok", "action_required"]
+
+turn = await thread.run(
+    "Summarize repository status",
+    {"output_schema": StatusResponse.model_json_schema()}
+)
+print(turn.final_response)
+```
+
+### Attaching images
+
+Provide structured input entries when you need to include images alongside text. Text entries are concatenated into the final prompt while image entries are passed to the Codex CLI via `--image`.
+
+```python
+turn = await thread.run([
+    {"type": "text", "text": "Describe these screenshots"},
+    {"type": "local_image", "path": "./ui.png"},
+    {"type": "local_image", "path": "./diagram.jpg"},
+])
+```
+
+### Resuming an existing thread
+
+Threads are persisted in `~/.codex/sessions`. If you lose the in-memory `Thread` object, reconstruct it with `resume_thread()` and keep going.
+
+```python
+import os
+
+saved_thread_id = os.environ["CODEX_THREAD_ID"]
+thread = codex.resume_thread(saved_thread_id)
+await thread.run("Implement the fix")
+```
+
+### Working directory controls
+
+Codex runs in the current working directory by default. To avoid unrecoverable errors, Codex requires the working directory to be a Git repository. You can skip the Git repository check by passing the `skip_git_repo_check` option when creating a thread.
+
+```python
+thread = codex.start_thread({
+    "working_directory": "/path/to/project",
+    "skip_git_repo_check": True,
+})
+```
+
+### Sandbox modes
+
+Control how the agent interacts with your filesystem using `sandbox_mode`.
+
+```python
+from codex_sdk import Codex, SandboxMode
+
+thread = codex.start_thread({
+    "sandbox_mode": SandboxMode.WORKSPACE_WRITE,
+})
+```
+
+Available modes:
+- `SandboxMode.READ_ONLY` - Agent can only read files
+- `SandboxMode.WORKSPACE_WRITE` - Agent can read/write in the workspace
+- `SandboxMode.DANGER_FULL_ACCESS` - Full filesystem access (use with caution)
+
+### Approval policies
+
+Control when the agent requires approval for actions.
+
+```python
+from codex_sdk import Codex, ApprovalMode
+
+thread = codex.start_thread({
+    "approval_policy": ApprovalMode.ON_FAILURE,
+})
+```
+
+Available modes:
+- `ApprovalMode.NEVER` - Never require approval
+- `ApprovalMode.ON_REQUEST` - Approve on explicit request
+- `ApprovalMode.ON_FAILURE` - Approve after failures
+- `ApprovalMode.UNTRUSTED` - Always require approval
+
+### Cancelling a turn
+
+Use `asyncio.Event` to cancel an ongoing turn (equivalent to `AbortSignal` in TypeScript).
+
+```python
+import asyncio
+
+async def cancellable_example():
+    codex = Codex()
+    thread = codex.start_thread()
+
+    cancel_event = asyncio.Event()
+
+    async def cancel_after_delay():
+        await asyncio.sleep(5)
+        cancel_event.set()
+
+    # Start cancellation timer
+    asyncio.create_task(cancel_after_delay())
+
+    try:
+        turn = await thread.run(
+            "Long running task",
+            {"cancel_event": cancel_event}
+        )
+    except asyncio.CancelledError:
+        print("Turn was cancelled")
+```
+
+### Controlling the Codex CLI environment
+
+By default, the Codex CLI inherits the Python process environment. Provide the optional `env` parameter when instantiating the `Codex` client to fully control which variables the CLI receives—useful for sandboxed hosts.
+
+```python
+codex = Codex({
+    "env": {
+        "PATH": "/usr/local/bin",
+    },
+})
+```
+
+The SDK still injects its required variables (such as `OPENAI_BASE_URL` and `CODEX_API_KEY`) on top of the environment you provide.
+
+### Passing `--config` overrides
+
+Use the `config` option to provide additional Codex CLI configuration overrides. The SDK accepts a dict, flattens it into dotted paths, and serializes values as TOML literals before passing them as repeated `--config key=value` flags.
+
+```python
+codex = Codex({
+    "config": {
+        "show_raw_agent_reasoning": True,
+        "sandbox_workspace_write": {"network_access": True},
+    },
+})
+```
+
+Thread options still take precedence for overlapping settings because they are emitted after these global overrides.
+
+## API Reference
+
+### Classes
+
+#### `Codex`
+Main entry point for the SDK.
+
+```python
+codex = Codex(options: CodexOptions | None = None)
+```
+
+Methods:
+- `start_thread(options: ThreadOptions | None = None) -> Thread` - Start a new conversation
+- `resume_thread(thread_id: str, options: ThreadOptions | None = None) -> Thread` - Resume an existing conversation
+
+#### `Thread`
+Represents a conversation with the agent.
+
+Properties:
+- `id: str | None` - Thread ID (populated after first turn)
+
+Methods:
+- `async run(input: Input, turn_options: TurnOptions | None = None) -> Turn` - Execute a turn and return results
+- `async run_streamed(input: Input, turn_options: TurnOptions | None = None) -> StreamedTurn` - Execute a turn with streaming events
+
+#### `Turn`
+Result of a completed turn.
+
+```python
+@dataclass
+class Turn:
+    items: list[ThreadItem]      # All items produced during the turn
+    final_response: str          # The agent's final response text
+    usage: Usage | None          # Token usage statistics
+```
+
+#### `StreamedTurn`
+Result of a streamed turn.
+
+```python
+@dataclass
+class StreamedTurn:
+    events: AsyncGenerator[ThreadEvent, None]  # Async generator of events
+```
+
+### Types
+
+#### Input Types
+- `Input = str | list[UserInput]` - User input (string or structured)
+- `TextUserInput` - Text input: `{"type": "text", "text": "..."}`
+- `ImageUserInput` - Image input: `{"type": "local_image", "path": "..."}`
+
+#### Event Types
+- `ThreadStartedEvent` - Thread started
+- `TurnStartedEvent` - Turn started
+- `TurnCompletedEvent` - Turn completed (includes usage)
+- `TurnFailedEvent` - Turn failed (includes error)
+- `ItemStartedEvent` - Item started
+- `ItemUpdatedEvent` - Item updated
+- `ItemCompletedEvent` - Item completed
+- `ThreadErrorEvent` - Unrecoverable error
+
+#### Item Types
+- `AgentMessageItem` - Agent's response text
+- `ReasoningItem` - Agent's reasoning summary
+- `CommandExecutionItem` - Shell command execution
+- `FileChangeItem` - File modifications
+- `McpToolCallItem` - MCP tool invocation
+- `WebSearchItem` - Web search query
+- `TodoListItem` - Agent's task list
+- `ErrorItem` - Non-fatal error
+
+### Enums
+
+```python
+class SandboxMode(StrEnum):
+    READ_ONLY = "read-only"
+    WORKSPACE_WRITE = "workspace-write"
+    DANGER_FULL_ACCESS = "danger-full-access"
+
+class ApprovalMode(StrEnum):
+    NEVER = "never"
+    ON_REQUEST = "on-request"
+    ON_FAILURE = "on-failure"
+    UNTRUSTED = "untrusted"
+
+class ModelReasoningEffort(StrEnum):
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+
+class WebSearchMode(StrEnum):
+    DISABLED = "disabled"
+    CACHED = "cached"
+    LIVE = "live"
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/openai/codex.git
+cd codex/sdk/python
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+### Running tests
+
+```bash
+pytest tests/ -v
+```
+
+### Linting and formatting
+
+```bash
+# Lint
+ruff check codex_sdk/
+
+# Format
+ruff format codex_sdk/
+
+# Type check
+mypy codex_sdk/
+```
+
+## Release Process
+
+Releases are automated via GitHub Actions.
+
+### Creating a release
+
+1. Update the version in `codex_sdk/__init__.py`:
+   ```python
+   __version__ = "0.1.0"
+   ```
+
+2. Commit the version change:
+   ```bash
+   git add codex_sdk/__init__.py
+   git commit -m "Bump version to 0.1.0"
+   ```
+
+3. Create and push a tag:
+   ```bash
+   git tag v0.1.0
+   git push origin main --tags
+   ```
+
+4. GitHub Actions will automatically:
+   - Build the package
+   - Publish to PyPI
+   - Create a GitHub Release
+
+### Required secrets
+
+Set the following secrets in your GitHub repository:
+
+- `PYPI_TOKEN`: Your PyPI API token for publishing packages
+
+To create a PyPI token:
+1. Go to https://pypi.org/manage/account/token/
+2. Create a new token with "Upload packages" scope
+3. Add it to your GitHub repository secrets
+
+## License
+
+Apache-2.0

codex_sdk_py-0.0.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+codex_sdk/__init__.py,sha256=ITfGEiUSUFTwh-QP2m2pAnyxw-BYBreucm161frNI80,2442
+codex_sdk/codex.py,sha256=ZTfzyP0Af_mp_6tYk-nRm0hEXjFUnRJUrpIC0RXPaAs,2148
+codex_sdk/codex_options.py,sha256=j6VXVLqXFgfzgfi59uZFXadGSa_Quv3PMhHcY5FXkPs,1174
+codex_sdk/events.py,sha256=fThiDLn3F2osyOYy6X9NYDAlkhpDXBaBdX7j4lvF0nc,2453
+codex_sdk/exec.py,sha256=_LvstngtTbZcDfFdJ778TKrDvgndM1W7BJvYCFZFsAQ,13279
+codex_sdk/items.py,sha256=6Vdw_4_IhZWcimfFlH-NCvOZ8dj6T-ktQdPYb0oiVyk,4206
+codex_sdk/output_schema_file.py,sha256=YbMsIVJ6DE8a7XqMWYXZRVqRFhfPQ-bhu2mGI0zrOkk,1950
+codex_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codex_sdk/thread.py,sha256=njoS-ku6JXM_1jKMddaqk_4bFrj0z-hPGhVV4UYt0o8,7695
+codex_sdk/thread_options.py,sha256=gCfUS-CPcVK1mAgOPRMYW2tsf3F-vpaN6JF93pp8UqA,1742
+codex_sdk/turn_options.py,sha256=iGfg4Tlq5U9whxIOtuqmErRkrmwJXEfOa-fqcTFwoas,535
+codex_sdk_py-0.0.3.dist-info/METADATA,sha256=9rsofZr1TfaSDdLF0XEs-hIenm9txWb3KYhORtHxaEI,11311
+codex_sdk_py-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codex_sdk_py-0.0.3.dist-info/RECORD,,

codex_sdk_py-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any