Make ready agent cog pip-installable via maturin bin bindings

.github/workflows/python.yml

@@ -0,0 +1,105 @@
+name: Python
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test-rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test
+
+  test-python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m venv .venv
+      - run: .venv/bin/pip install "maturin[patchelf]" pytest
+      - run: .venv/bin/maturin develop
+      - run: .venv/bin/pytest python/tests/ -v
+
+  build-wheels:
+    needs: [test-rust, test-python]
+    if: github.event_name == 'release'
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+          - os: ubuntu-latest
+            target: aarch64
+          - os: macos-latest
+            target: x86_64
+          - os: macos-latest
+            target: aarch64
+          - os: windows-latest
+            target: x86_64
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist --strip
+          manylinux: auto
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: dist/
+
+  build-sdist:
+    needs: [test-rust, test-python]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/
+
+  publish:
+    needs: [build-wheels, build-sdist]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist/
+      - uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist/
+      - uses: astral-sh/setup-uv@v4
+      - run: uv publish --trusted-publishing always

.gitignore

@@ -12,6 +12,14 @@
 .DS_Store
 Thumbs.db
 
+# Python
+__pycache__/
+*.egg-info/
+dist/
+*.whl
+*.so
+*.pyd
+
 # Test / temp
 .coverage
 temp/

README.md

@@ -74,10 +74,28 @@ When the planner emits [`collect_user_input`](src/workflow/planner.rs:53), it wr
 
 ## Installation
 
+### From PyPI (recommended)
+
+```sh
+pip install ready-agent
+```
+
+This installs a prebuilt binary — no Rust toolchain needed.
+
+### From source
+
 ```sh
 cargo install --path .
 ```
 
+### Development build
+
+```sh
+pip install "maturin[patchelf]"
+maturin develop          # builds and installs into current venv
+maturin build --release  # builds a wheel in target/wheels/
+```
+
 Requires an OpenAI-compatible API:
 
 ```sh

pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["maturin>=1.9,<2"]
+build-backend = "maturin"
+
+[project]
+name = "ready-agent"
+description = "A plan-based agent execution engine for parsing, validating, and running deterministic workflows from plain-English SOPs."
+dynamic = ["version"]
+requires-python = ">=3.10"
+license = "GPL-3.0-or-later"
+keywords = ["agent", "llm", "workflow", "sop", "plan"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[tool.maturin]
+bindings = "bin"
+manifest-path = "Cargo.toml"
+module-name = "ready_agent"
+python-source = "python"
+
+[tool.pytest.ini_options]
+testpaths = ["python/tests"]

python/ready_agent/__init__.py

@@ -0,0 +1,67 @@
+"""Ready Agent -- A plan-based agent execution engine."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+
+
+def find_ready_bin() -> str:
+    """Find the ``ready`` binary bundled with this package.
+
+    Searches the standard script/bin directories where pip, uv, and other
+    installers place console-script executables.
+    """
+    exe = "ready.exe" if sys.platform == "win32" else "ready"
+
+    # 1. scripts dir (standard pip / uv install)
+    scripts = sysconfig.get_path("scripts")
+    if scripts:
+        path = Path(scripts) / exe
+        if path.is_file():
+            return str(path)
+
+    # 2. Same directory as the running Python interpreter
+    path = Path(sys.executable).parent / exe
+    if path.is_file():
+        return str(path)
+
+    # 3. User-scheme scripts (pip install --user)
+    try:
+        user_scripts = sysconfig.get_path("scripts", scheme="posix_user")
+    except KeyError:
+        user_scripts = None
+    if user_scripts:
+        path = Path(user_scripts) / exe
+        if path.is_file():
+            return str(path)
+
+    # 4. PATH fallback
+    from shutil import which
+
+    found = which("ready")
+    if found:
+        return found
+
+    raise FileNotFoundError(
+        f"Could not find the '{exe}' binary. "
+        "Make sure ready-agent is installed correctly: pip install ready-agent"
+    )
+
+
+def main() -> None:
+    """Entry point that forwards all arguments to the ``ready`` binary."""
+    try:
+        ready = find_ready_bin()
+    except FileNotFoundError as exc:
+        print(str(exc), file=sys.stderr)
+        sys.exit(1)
+
+    if sys.platform == "win32":
+        result = subprocess.run([ready, *sys.argv[1:]])
+        sys.exit(result.returncode)
+    else:
+        os.execvp(ready, [ready, *sys.argv[1:]])

python/ready_agent/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m ready_agent``."""
+
+from ready_agent import main
+
+main()