feat: native bidings

Author: gersmann

.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

.github/workflows/publish.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: read
+  id-token: write
 
 jobs:
   build-and-publish:
@@ -28,7 +29,5 @@ jobs:
       - name: Build distribution
         run: uv build
 
-      - name: Publish to PyPI
-        env:
-          PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
-        run: uv publish --token "$PYPI_API_TOKEN"
+      - name: Publish to PyPI (Trusted Publishing)
+        run: uv publish --trusted-publishing=always

.gitignore

@@ -42,4 +42,24 @@ coverage.xml
 
 # uv
 .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.*

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
 
+## [0.1.1] - 2025-09-10
+### Added
+- CodexClient synchronous wrapper with defaults
+- Python API `run_exec` with robust error handling
+
+### Changed
+- Switch publish workflow to PyPI Trusted Publishing (OIDC)
+- Docs and Makefile updates
+
 ## [0.1.0] - 2025-09-10
 ### Added
 - Initial project scaffold with Python 3.13+
@@ -15,3 +24,4 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 - MIT License
 
 [0.1.0]: https://github.com/gersmann/codex-python/releases/tag/v0.1.0
+[0.1.1]: https://github.com/gersmann/codex-python/releases/tag/v0.1.1

CONTRIBUTING.md

@@ -36,7 +36,7 @@ This project is typed and ships a `py.typed` marker. Please keep public APIs typ
 2. Update `CHANGELOG.md`.
 3. Merge to `main`.
 4. Tag the release: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push --tags`.
-5. GitHub Actions (publish workflow) will build and publish to PyPI on `v*` tags.
+5. GitHub Actions (publish workflow) will build and publish to PyPI on `v*` tags using Trusted Publishing (OIDC). No token is required.
 
 ## Pre-commit (optional but recommended)
 ```
@@ -51,4 +51,3 @@ Please open an issue with reproduction steps, expected vs actual behavior, and e
 
 ## Code of Conduct
 By participating, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
-

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,22 +17,60 @@ 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
 
 publish: build
-	@if [ -z "$${PYPI_API_TOKEN}" ]; then \
-		echo "PYPI_API_TOKEN is not set"; \
+	@# Load local environment if present
+	@set -e; \
+	if [ -f .env ]; then set -a; . ./.env; set +a; fi; \
+	if [ -n "$${UV_PUBLISH_TOKEN:-}" ]; then \
+		echo "Publishing with token (UV_PUBLISH_TOKEN)"; \
+		uv publish --token "$${UV_PUBLISH_TOKEN}"; \
+	elif [ -n "$${PYPI_API_TOKEN:-}" ]; then \
+		echo "Publishing with token (PYPI_API_TOKEN)"; \
+		uv publish --token "$${PYPI_API_TOKEN}"; \
+	elif [ -n "$${UV_PUBLISH_USERNAME:-}" ] && [ -n "$${UV_PUBLISH_PASSWORD:-}" ]; then \
+		echo "Publishing with username/password (UV_PUBLISH_USERNAME)"; \
+		uv publish --username "$${UV_PUBLISH_USERNAME}" --password "$${UV_PUBLISH_PASSWORD}"; \
+	elif [ -n "$${PYPI_USERNAME:-}" ] && [ -n "$${PYPI_PASSWORD:-}" ]; then \
+		echo "Publishing with username/password (PYPI_USERNAME)"; \
+		uv publish --username "$${PYPI_USERNAME}" --password "$${PYPI_PASSWORD}"; \
+	else \
+		echo "No credentials found. Set UV_PUBLISH_TOKEN or PYPI_API_TOKEN, or UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD (or PYPI_USERNAME/PYPI_PASSWORD)."; \
 		exit 1; \
 	fi
-	uv publish --token "$$PYPI_API_TOKEN"
 
 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 \
+		echo "Using 'codex generate-types'"; \
+		codex generate-types --out .generated/ts; \
+	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

README.md

@@ -1,10 +1,10 @@
 # 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; pure‑Python installs fall back to the CLI JSON mode.
 
 ## Quickstart
 
-- Requires Python 3.13+.
+- Requires Python 3.12+.
 - Package import name: `codex`.
 - Distribution name (PyPI): `codex-python`.
 
@@ -30,6 +30,27 @@ Options:
 - Full auto: `run_exec("scaffold a cli", full_auto=True)`
 - Run in another dir: `run_exec("...", cd="/path/to/project")`
 
+Streaming JSON events (CLI; no native required):
+
+```
+from codex.protocol.runtime import stream_exec_events
+
+for event in stream_exec_events("explain this repo", full_auto=True):
+    # event is a dict with shape {"id": str, "msg": {...}}
+    print(event)
+```
+
+The event payload matches the Pydantic models in `codex.protocol.types` (e.g., `EventMsg`).
+
+Using a client with defaults:
+
+```
+from codex import CodexClient
+
+client = CodexClient(model="gpt-4.1", full_auto=True)
+print(client.run("explain this repo"))
+```
+
 ### Install uv
 
 - macOS (Homebrew): `brew install uv`
@@ -64,8 +85,10 @@ export PYPI_API_TOKEN="pypi-XXXX"  # create at https://pypi.org/manage/account/t
 uv publish --token "$PYPI_API_TOKEN"
 ```
 
-- GitHub Actions: add a repository secret `PYPI_API_TOKEN` and push a tag like `v0.1.0`.
-  The workflow at `.github/workflows/publish.yml` builds and publishes with `uv` on `v*` tags.
+- 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
 
@@ -74,6 +97,54 @@ 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). If a platform wheel isn’t available, pip installs a pure‑Python build and CLI JSON streaming still works.
+
+- Build locally (requires Rust + maturin):
+
+```
+make dev-native
+```
+
+- Use (collect all events):
+
+```
+from codex.native import run_exec_collect
+
+events = run_exec_collect("say hello", full_auto=True)
+for e in events:
+    print(e)
+```
+
+- Use (streaming iterator):
+
+```
+from codex.native import start_exec_stream
+
+for e in start_exec_stream("say hello", full_auto=True):
+    print(e)
+```
+
+- Notes:
+  - The native path embeds Codex directly; no subprocess.
+  - Native is optional; when not present, use the CLI JSON streaming helpers.
+
 ## Project Layout
 
 ```
@@ -91,4 +162,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/__init__.py

@@ -4,19 +4,29 @@
 
 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 CodexError, CodexNotFoundError, CodexProcessError, find_binary, run_exec
+from .api import (
+    CodexClient,
+    CodexError,
+    CodexNativeError,
+    Conversation,
+    run_exec,
+)
+from .config import CodexConfig
+from .event import Event
 
 __all__ = [
     "__version__",
     "CodexError",
-    "CodexNotFoundError",
-    "CodexProcessError",
-    "find_binary",
+    "CodexNativeError",
+    "CodexClient",
+    "Conversation",
     "run_exec",
+    "Event",
+    "CodexConfig",
 ]
 
 # Managed by Hatch via pyproject.toml [tool.hatch.version]
-__version__ = "0.1.0"
+__version__ = "0.1.2"