codex-sdk-py 0.0.3__tar.gz

codex_sdk_py-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff mypy
+
+      - name: Run Ruff (linter)
+        run: ruff check codex_sdk/
+
+      - name: Run Ruff (formatter check)
+        run: ruff format --check codex_sdk/
+
+      - name: Run mypy (type check)
+        run: mypy codex_sdk/ --ignore-missing-imports
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

codex_sdk_py-0.0.3/.github/workflows/release.yml

@@ -0,0 +1,85 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/codex-sdk-py/
+
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Get version from tag
+        id: get_version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: v${{ steps.get_version.outputs.VERSION }}
+          draft: false
+          prerelease: ${{ contains(github.ref, 'alpha') || contains(github.ref, 'beta') || contains(github.ref, 'rc') }}
+          generate_release_notes: true
+          files: |
+            dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

codex_sdk_py-0.0.3/.gitignore

@@ -0,0 +1,107 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Codex SDK vendor binaries (bundled separately)
+codex_sdk/vendor/
+
+.claude/
+
+docs/private/

codex_sdk_py-0.0.3/PKG-INFO

@@ -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