codex-python 0.1.1__tar.gz → 0.2.0__tar.gz

{codex_python-0.1.1 → codex_python-0.2.0}/.github/workflows/ci.yml

@@ -26,9 +26,19 @@ jobs:
         with:
           version: latest
 
+      - name: Set up Rust (for native extension)
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install maturin
+        run: |
+          python -m pip install --upgrade pip
+          pip install maturin
+
+      - name: Build native extension (editable)
+        run: make dev-native
+
       - name: Lint
         run: make lint
 
       - name: Test
         run: make test
-

codex_python-0.2.0/.github/workflows/native-wheels.yml

@@ -0,0 +1,68 @@
+name: Build Native Wheels (codex-native)
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    continue-on-error: ${{ matrix.allow-failure == true }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+        python-version: ['3.12', '3.13']
+        include:
+          - os: ubuntu-latest
+            python-version: '3.14'
+            allow-failure: true
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install maturin
+        run: |
+          python -m pip install --upgrade pip
+          pip install maturin
+
+      - name: Build wheels with maturin
+        env:
+          PYO3_USE_ABI3_FORWARD_COMPATIBILITY: '1'
+        run: |
+          maturin build -m crates/codex_native/Cargo.toml --release --interpreter python
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.python-version }}
+          path: crates/codex_native/target/wheels/*.whl
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download all wheels
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          skip-existing: true

{codex_python-0.1.1 → codex_python-0.2.0}/.gitignore

@@ -44,6 +44,30 @@ coverage.xml
 .uv/
 uv.lock
 
+# Generated artifacts
+# Generated artifacts
+.generated/
+codex-proj/
+.githooks/
+test/
+tests/
+
+# Ignore new markdown files by default
+*.md
+
+# Rust build outputs
+target/
+crates/**/target/
+crates/**/Cargo.lock
+
 # Local environment files
 .env
 .env.*
+/.idea/inspectionProfiles/profiles_settings.xml
+/.idea/inspectionProfiles/Project_Default.xml
+/.idea/.gitignore
+/.idea/codex-python.iml
+/.idea/misc.xml
+/.idea/modules.xml
+/.idea/ruff.xml
+/.idea/vcs.xml

{codex_python-0.1.1 → codex_python-0.2.0}/Makefile

@@ -7,6 +7,7 @@ help:
 	@echo "  make build    - Build sdist and wheel with uv"
 	@echo "  make publish  - Publish to PyPI via uv (uses PYPI_API_TOKEN)"
 	@echo "  make clean    - Remove build artifacts"
+	@echo "  make gen-protocol - Generate Python protocol bindings from codex-rs"
 
 venv:
 	uv venv --python 3.13
@@ -16,12 +17,12 @@ fmt:
 	uv run --group dev ruff format .
 
 lint:
-	uv run --group dev ruff format --check .
-	uv run --group dev ruff check .
+	uv run --group dev ruff format .
+	uv run --group dev ruff check --fix --unsafe-fixes .
 	uv run --group dev mypy codex
 
 test:
-	uv run --group dev pytest
+	@bash -lc 'uv run --group dev pytest -q; ec=$$?; if [ $$ec -eq 5 ]; then echo "No tests collected"; exit 0; else exit $$ec; fi'
 
 build:
 	uv build
@@ -49,3 +50,32 @@ publish: build
 
 clean:
 	rm -rf build dist *.egg-info .pytest_cache .mypy_cache .ruff_cache
+
+gen-protocol:
+	@echo "Generating TypeScript protocol types via codex-proj/codex-rs ..."
+	@mkdir -p .generated/ts
+	@if command -v codex >/dev/null 2>&1; then \
+		if codex --help | grep -q "generate-ts"; then \
+			echo "Using 'codex generate-ts'"; \
+			codex generate-ts --out .generated/ts; \
+		else \
+			echo "'codex' installed but no generate-ts; falling back"; \
+			cd codex-proj/codex-rs && cargo run -p codex-protocol-ts -- --out ../../.generated/ts; \
+		fi; \
+	else \
+		echo "Using cargo run -p codex-protocol-ts"; \
+		cd codex-proj/codex-rs && cargo run -p codex-protocol-ts -- --out ../../.generated/ts; \
+	fi
+	@echo "Generating Python bindings ..."
+	@python3 scripts/generate_protocol_py.py .generated/ts
+	@$(MAKE) fmt
+
+.PHONY: build-native dev-native
+
+build-native:
+	@echo "Building native extension with maturin..."
+	@maturin build -m crates/codex_native/Cargo.toml --release
+
+dev-native:
+	@echo "Installing native extension in dev mode..."
+	@maturin develop -m crates/codex_native/Cargo.toml

{codex_python-0.1.1 → codex_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-python
-Version: 0.1.1
+Version: 0.2.0
 Summary: A minimal Python library scaffold for codex-python
 Project-URL: Homepage, https://github.com/gersmann/codex-python
 Project-URL: Repository, https://github.com/gersmann/codex-python
@@ -36,15 +36,16 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.11.7
 Description-Content-Type: text/markdown
 
 # codex-python
 
-A minimal Python library scaffold using `uv` with Python 3.13+.
+Python interface to Codex, packaged as a single distribution (`codex-python`). Platform wheels include a native extension for in‑process execution. The library consolidates on native bindings (no subprocess wrapper).
 
 ## Quickstart
 
-- Requires Python 3.13+.
+- Requires Python 3.12+.
 - Package import name: `codex`.
 - Distribution name (PyPI): `codex-python`.
 
@@ -55,30 +56,39 @@ A minimal Python library scaffold using `uv` with Python 3.13+.
 
 ## Usage
 
-Basic non-interactive execution via Codex CLI:
+Native, non-interactive execution with Pydantic config:
 
 ```
-from codex import run_exec
+from codex.api import run_exec, CodexClient
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
 
-out = run_exec("explain this repo")
-print(out)
-```
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+)
 
-Options:
+events = run_exec("explain this repo", config=cfg)
 
-- Choose model: `run_exec("...", model="gpt-4.1")`
-- Full auto: `run_exec("scaffold a cli", full_auto=True)`
-- Run in another dir: `run_exec("...", cd="/path/to/project")`
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("add a smoke test"):
+    print(ev)
+```
 
-Using a client with defaults:
+To stream raw dict events directly from the native layer:
 
 ```
-from codex import CodexClient
+from codex.native import start_exec_stream
 
-client = CodexClient(model="gpt-4.1", full_auto=True)
-print(client.run("explain this repo"))
+for e in start_exec_stream("explain this repo", config_overrides=cfg.to_dict()):
+    # each `e` is a dict representing an event envelope
+    print(e)
 ```
 
+The event payload is typed: `Event.msg` is a union `EventMsg` from `codex.protocol.types`,
+and is also exported at `codex.EventMsg` for convenience.
+
 ### Install uv
 
 - macOS (Homebrew): `brew install uv`
@@ -125,6 +135,61 @@ uv publish --token "$PYPI_API_TOKEN"
 - Format: `make fmt` (ruff formatter)
  - Pre-commit: `uvx pre-commit install && uvx pre-commit run --all-files`
 
+### Protocol bindings (from codex-rs)
+
+- Prereq: Rust toolchain (`cargo`) installed.
+- Generate Python types from the upstream protocol with:
+
+```
+make gen-protocol
+```
+
+This will:
+- emit TypeScript types under `.generated/ts/`
+- convert them to Python Pydantic models + Literal unions at `codex/protocol/types.py`
+
+### Native bindings (PyO3)
+
+- Install path
+
+`pip install codex-python` installs a platform wheel that includes the native extension on supported platforms (Python 3.12/3.13; CI also attempts 3.14).
+
+- Build locally (requires Rust + maturin):
+
+```
+make dev-native
+```
+
+- Notes:
+  - The native path embeds Codex directly; no subprocess.
+  - A helper `codex.native.preview_config(...)` returns a compact snapshot of the effective configuration (selected fields) for tests and introspection.
+
+### Configuration (Pydantic)
+
+Use the `CodexConfig` Pydantic model to pass overrides which mirror the Rust `ConfigOverrides`:
+
+```
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+from codex.api import run_exec, CodexClient
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+    cwd="/path/to/project",
+    include_apply_patch_tool=True,
+)
+
+events = run_exec("Explain this project", config=cfg)
+
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("Add a test for feature X"):
+    print(ev)
+```
+
+`CodexConfig.to_dict()` emits only set (non‑None) fields and serializes enums to their kebab‑case strings to match the native Rust types.
+
 ## Project Layout
 
 ```
@@ -142,4 +207,4 @@ Version is managed via `codex/__init__.py` and exposed as `__version__`. The bui
 
 ## Python Compatibility
 
-- Requires Python `>=3.13`.
+- Supported: Python 3.12, 3.13. CI attempts 3.14 wheels when available.

codex_python-0.2.0/README.md

@@ -0,0 +1,169 @@
+# codex-python
+
+Python interface to Codex, packaged as a single distribution (`codex-python`). Platform wheels include a native extension for in‑process execution. The library consolidates on native bindings (no subprocess wrapper).
+
+## Quickstart
+
+- Requires Python 3.12+.
+- Package import name: `codex`.
+- Distribution name (PyPI): `codex-python`.
+
+### Repo
+
+- Git: `git@github.com:gersmann/codex-python.git`
+- URL: https://github.com/gersmann/codex-python
+
+## Usage
+
+Native, non-interactive execution with Pydantic config:
+
+```
+from codex.api import run_exec, CodexClient
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+)
+
+events = run_exec("explain this repo", config=cfg)
+
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("add a smoke test"):
+    print(ev)
+```
+
+To stream raw dict events directly from the native layer:
+
+```
+from codex.native import start_exec_stream
+
+for e in start_exec_stream("explain this repo", config_overrides=cfg.to_dict()):
+    # each `e` is a dict representing an event envelope
+    print(e)
+```
+
+The event payload is typed: `Event.msg` is a union `EventMsg` from `codex.protocol.types`,
+and is also exported at `codex.EventMsg` for convenience.
+
+### Install uv
+
+- macOS (Homebrew): `brew install uv`
+- Or via install script:
+  - Unix/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+  - Windows (PowerShell): `iwr https://astral.sh/uv/install.ps1 -UseBasicParsing | iex`
+
+See: https://docs.astral.sh/uv/
+
+### Create a virtual env (optional)
+
+```
+uv python install 3.13
+uv venv --python 3.13
+. .venv/bin/activate  # or .venv\Scripts\activate on Windows
+```
+
+### Build
+
+```
+uv build
+```
+
+Artifacts appear in `dist/` (`.whl` and `.tar.gz`).
+
+### Publish to PyPI
+
+- Manual:
+
+```
+export PYPI_API_TOKEN="pypi-XXXX"  # create at https://pypi.org/manage/account/token/
+uv publish --token "$PYPI_API_TOKEN"
+```
+
+- GitHub Actions (Trusted Publishing): enable PyPI Trusted Publishing for
+  `gersmann/codex-python` and push a tag like `v0.1.0`. No token is needed.
+  The workflow at `.github/workflows/publish.yml` requests an OIDC token and
+  runs `uv publish --trusted-publishing=always` on `v*` tags.
+
+### Dev tooling
+
+- Lint: `make lint` (ruff + mypy)
+- Tests: `make test` (pytest)
+- Format: `make fmt` (ruff formatter)
+ - Pre-commit: `uvx pre-commit install && uvx pre-commit run --all-files`
+
+### Protocol bindings (from codex-rs)
+
+- Prereq: Rust toolchain (`cargo`) installed.
+- Generate Python types from the upstream protocol with:
+
+```
+make gen-protocol
+```
+
+This will:
+- emit TypeScript types under `.generated/ts/`
+- convert them to Python Pydantic models + Literal unions at `codex/protocol/types.py`
+
+### Native bindings (PyO3)
+
+- Install path
+
+`pip install codex-python` installs a platform wheel that includes the native extension on supported platforms (Python 3.12/3.13; CI also attempts 3.14).
+
+- Build locally (requires Rust + maturin):
+
+```
+make dev-native
+```
+
+- Notes:
+  - The native path embeds Codex directly; no subprocess.
+  - A helper `codex.native.preview_config(...)` returns a compact snapshot of the effective configuration (selected fields) for tests and introspection.
+
+### Configuration (Pydantic)
+
+Use the `CodexConfig` Pydantic model to pass overrides which mirror the Rust `ConfigOverrides`:
+
+```
+from codex.config import CodexConfig, ApprovalPolicy, SandboxMode
+from codex.api import run_exec, CodexClient
+
+cfg = CodexConfig(
+    model="gpt-5",
+    model_provider="openai",
+    approval_policy=ApprovalPolicy.ON_REQUEST,
+    sandbox_mode=SandboxMode.WORKSPACE_WRITE,
+    cwd="/path/to/project",
+    include_apply_patch_tool=True,
+)
+
+events = run_exec("Explain this project", config=cfg)
+
+client = CodexClient(config=cfg)
+for ev in client.start_conversation("Add a test for feature X"):
+    print(ev)
+```
+
+`CodexConfig.to_dict()` emits only set (non‑None) fields and serializes enums to their kebab‑case strings to match the native Rust types.
+
+## Project Layout
+
+```
+.
+├── codex/              # package root (import name: codex)
+│   └── __init__.py     # version lives here
+├── pyproject.toml      # PEP 621 metadata, hatchling build backend
+├── README.md
+└── .gitignore
+```
+
+## Versioning
+
+Version is managed via `codex/__init__.py` and exposed as `__version__`. The build uses Hatch’s version source.
+
+## Python Compatibility
+
+- Supported: Python 3.12, 3.13. CI attempts 3.14 wheels when available.

{codex_python-0.1.1 → codex_python-0.2.0}/codex/__init__.py

@@ -4,27 +4,31 @@ Python interface for the Codex CLI.
 
 Usage:
     from codex import run_exec
-    output = run_exec("explain this codebase to me")
+    events = run_exec("explain this codebase to me")
 """
 
 from .api import (
     CodexClient,
     CodexError,
-    CodexNotFoundError,
-    CodexProcessError,
-    find_binary,
+    CodexNativeError,
+    Conversation,
     run_exec,
 )
+from .config import CodexConfig
+from .event import Event
+from .protocol.types import EventMsg
 
 __all__ = [
     "__version__",
     "CodexError",
-    "CodexNotFoundError",
-    "CodexProcessError",
+    "CodexNativeError",
     "CodexClient",
-    "find_binary",
+    "Conversation",
     "run_exec",
+    "Event",
+    "EventMsg",
+    "CodexConfig",
 ]
 
 # Managed by Hatch via pyproject.toml [tool.hatch.version]
-__version__ = "0.1.1"
+__version__ = "0.2.0"

codex_python-0.2.0/codex/api.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Mapping, Sequence
+from dataclasses import dataclass
+
+from .config import CodexConfig
+from .event import Event
+from .native import run_exec_collect as native_run_exec_collect
+from .native import start_exec_stream as native_start_exec_stream
+
+
+class CodexError(Exception):
+    """Base exception for codex-python."""
+
+
+class CodexNativeError(CodexError):
+    """Raised when the native extension is not available or fails."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "codex_native extension not installed or failed to run. "
+            "Run `make dev-native` or ensure native wheels are installed."
+        )
+
+
+@dataclass(slots=True)
+class Conversation:
+    """A stateful conversation with Codex, streaming events natively."""
+
+    _stream: Iterable[dict]
+
+    def __iter__(self) -> Iterator[Event]:
+        """Yield `Event` objects from the native stream."""
+        for item in self._stream:
+            yield Event.model_validate(item)
+
+
+@dataclass(slots=True)
+class CodexClient:
+    """Lightweight, synchronous client for the native Codex core.
+
+    Provides defaults for repeated invocations and conversation management.
+    """
+
+    config: CodexConfig | None = None
+    load_default_config: bool = True
+    env: Mapping[str, str] | None = None
+    extra_args: Sequence[str] | None = None
+
+    def start_conversation(
+        self,
+        prompt: str,
+        *,
+        config: CodexConfig | None = None,
+        load_default_config: bool | None = None,
+    ) -> Conversation:
+        """Start a new conversation and return a streaming iterator over events."""
+        eff_config = config if config is not None else self.config
+        eff_load_default_config = (
+            load_default_config if load_default_config is not None else self.load_default_config
+        )
+
+        try:
+            stream = native_start_exec_stream(
+                prompt,
+                config_overrides=eff_config.to_dict() if eff_config else None,
+                load_default_config=eff_load_default_config,
+            )
+            return Conversation(_stream=stream)
+        except RuntimeError as e:
+            raise CodexNativeError() from e
+
+
+def run_exec(
+    prompt: str,
+    *,
+    config: CodexConfig | None = None,
+    load_default_config: bool = True,
+) -> list[Event]:
+    """
+    Run a prompt through the native Codex engine and return a list of events.
+
+    - Raises CodexNativeError if the native extension is unavailable or fails.
+    """
+    try:
+        events = native_run_exec_collect(
+            prompt,
+            config_overrides=config.to_dict() if config else None,
+            load_default_config=load_default_config,
+        )
+        return [Event.model_validate(e) for e in events]
+    except RuntimeError as e:
+        raise CodexNativeError() from e