pi-py-sdk 0.1.0__tar.gz

pi_py_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: unit (py${{ 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
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - name: Run unit tests
+        run: pytest -q
+
+  build:
+    name: build wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  integration:
+    name: integration (live pi, best-effort)
+    runs-on: ubuntu-latest
+    # Best-effort: spins up a real `pi` to smoke the bridge. Never blocks merges,
+    # since it depends on the upstream npm package and default-model availability.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install -g @earendil-works/pi-coding-agent
+      - run: pip install -e ".[dev]"
+      - name: Run integration tests (non-LLM)
+        run: pytest -m integration -q

pi_py_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+# Builds the distribution on every release and publishes it to PyPI.
+#
+# Setup required once: configure a PyPI Trusted Publisher for this repo/workflow
+# (https://docs.pypi.org/trusted-publishers/) so no API token secret is needed.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC token for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pi_py_sdk-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

pi_py_sdk-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## What this is
+
+`pi-py-sdk` is a Python SDK that drives **Pi**'s agent runtime (`pi-agent-core`, written
+in TypeScript) over Pi's **RPC mode** (`pi --mode rpc`, strict JSONL over stdin/stdout),
+plus a terminal coding agent (`pi-py`) built on that SDK.
+
+**Core principle: no agent logic is reimplemented in Python.** The agent loop, tool
+calling, sessions, compaction, retries, and provider auth all run inside the `pi`
+subprocess. This package is a transport + protocol + ergonomics layer over that
+subprocess. When extending it, prefer exposing an existing Pi RPC command/event over
+adding behavior here.
+
+## Layout
+
+```
+src/pi_py_sdk/        # the SDK (the bridge)
+  jsonl.py            # strict LF-only JSONL framing (mirrors Pi's jsonl.ts)
+  transport.py        # async subprocess lifecycle, stdout framing, stderr ring buffer
+  protocol.py         # Pydantic models: commands, responses, events, messages
+  client.py           # PiAgent — async API, id-correlated requests, prompt streaming
+  sync.py             # PiAgentSync — blocking facade over a background-thread loop
+  config.py           # PiConfig (CLI args + env)
+  _discovery.py       # resolve `pi`: PATH -> npx fallback (pinned version)
+  errors.py           # PiError hierarchy
+src/pi_py_agent/      # the terminal coding agent (consumes the SDK only)
+  render.py           # stream events -> terminal (text/thinking/tool/queue)
+  app.py              # async REPL + one-shot runner, mid-turn steering, approvals
+  cli.py              # `pi-py` console entry point
+tests/                # pytest; unit tests need no Node (fake transports)
+docs/python-sdk-plan.md   # full design + roadmap
+```
+
+## Non-obvious invariants — read before editing the protocol
+
+- **JSONL framing is LF-only.** Split stdout on `\n` only; never on U+2028/U+2029 (valid
+  inside JSON strings). Strip a single trailing `\r`. See `jsonl.py`; this must stay
+  byte-compatible with Pi's `packages/coding-agent/src/modes/rpc/jsonl.ts`.
+- **A `prompt` response means preflight succeeded, not that the turn finished.**
+  Completion is the `agent_end` event — and only when `agent_end.willRetry == False`.
+  `willRetry == True` is followed by an `auto_retry_*` cycle and another `agent_end`.
+  `prompt_stream`/`wait_for_idle` depend on this.
+- **Wire field names are camelCase** (`assistantMessageEvent`, `toolCallId`, `willRetry`,
+  `modelId`). Models keep those names verbatim. All models use `extra="allow"` so new Pi
+  fields/events degrade gracefully — don't tighten this.
+- **Auth lives in Pi, not here.** The transport forwards `os.environ`; Pi resolves all
+  provider keys/OAuth. Never add key handling in Python.
+- **`bash` command vs the bash tool:** the `bash` RPC command stores a
+  BashExecutionMessage that is only sent to the LLM on the *next* prompt.
+- **`extension_ui_response` is not id-correlated** — it's written directly to stdin, not
+  via the request/response (`_send`) path.
+
+## Dev commands
+
+```bash
+pip install -e ".[dev]"
+pytest                       # unit tests (no Node; integration deselected via addopts)
+pytest -m integration        # live tests; needs `pi` on PATH (no key needed)
+PI_LIVE_LLM=1 pytest -m integration   # also runs the prompt-completion test (needs a model)
+python -m build              # build wheel + sdist
+```
+
+There is no linter/formatter configured. Match the surrounding style: 4-space indent,
+type hints, `from __future__ import annotations`, Google-ish docstrings.
+
+## Testing approach
+
+Unit tests inject a **fake transport** (see `tests/test_client_fake.py`,
+`test_ui_and_events.py`, `test_commands.py`) or a fake agent (`test_sync.py`) so nothing
+spawns Node. Pure helpers (framing, event/message parsing, REPL routing, rendering) are
+tested directly. Live behavior goes in `tests/test_integration.py` behind the
+`integration` marker (skipped automatically when `pi` is absent).
+
+## Release
+
+Version lives in `pyproject.toml` and `src/pi_py_sdk/__init__.py` (keep them in sync).
+CI (`.github/workflows/ci.yml`) runs the unit matrix (3.10–3.13), builds the wheel, and
+best-effort-smokes a real `pi`. Publishing to PyPI happens on a GitHub Release via
+`.github/workflows/publish.yml` using Trusted Publishing (OIDC, no token). To cut a
+release: bump the version, then `gh release create vX.Y.Z --generate-notes`.
+
+## Git
+
+Work on a feature branch and fast-forward into `main`; `main` tracks
+`origin` (github.com/noclaw/pi-py). End commit messages with the
+`Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>` trailer.

pi_py_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoClaw.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pi_py_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: pi-py-sdk
+Version: 0.1.0
+Summary: Python SDK for the Pi coding agent (pi-agent-core) over its RPC bridge
+Project-URL: Homepage, https://github.com/earendil-works/pi
+Author: Jeff Jacobsen
+License: MIT
+License-File: LICENSE
+Keywords: agent,coding-agent,llm,pi,rpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: pydantic<3,>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pi-py-sdk
+
+[![CI](https://github.com/noclaw/pi-py/actions/workflows/ci.yml/badge.svg)](https://github.com/noclaw/pi-py/actions/workflows/ci.yml)
+
+Python SDK for the [Pi](https://pi.dev) coding agent. It drives `pi-agent-core` — the
+well-tested TypeScript agent runtime — over Pi's **RPC mode** (`pi --mode rpc`, strict
+JSONL over stdin/stdout), so the agent loop, tool calling, sessions, compaction,
+retries, and provider auth all run inside Pi. No agent logic is reimplemented in Python.
+
+It includes the bridge core (transport, strict JSONL framing, id-correlated commands,
+streaming), the full RPC command surface, typed events and message models, the
+interactive **extension-UI sub-protocol** (tool approvals/dialogs), and a synchronous
+facade (`PiAgentSync`). A terminal coding agent (`pi-py`) ships on top. See
+[`docs/python-sdk-plan.md`](docs/python-sdk-plan.md) for the design.
+
+## Install
+
+```bash
+pip install pi-py-sdk
+```
+
+This installs the `pi_py_sdk` library and the `pi-py` agent CLI. You also need the Pi
+runtime for live use:
+
+```bash
+npm i -g @earendil-works/pi-coding-agent   # provides the `pi` binary
+export ANTHROPIC_API_KEY=...               # or another supported provider key
+```
+
+If `pi` isn't on `PATH`, the SDK falls back to `npx --yes @earendil-works/pi-coding-agent@<pinned>`.
+
+### Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import asyncio
+from pi_py_sdk import PiAgent, MessageUpdateEvent
+
+async def main():
+    async with PiAgent(model="anthropic/claude-sonnet-4-20250514", cwd=".") as agent:
+        async for ev in agent.prompt_stream("List the Python files here"):
+            if isinstance(ev, MessageUpdateEvent) and ev.assistantMessageEvent:
+                ame = ev.assistantMessageEvent
+                if ame.type == "text_delta" and ame.delta:
+                    print(ame.delta, end="", flush=True)
+
+asyncio.run(main())
+```
+
+A prompt completes on an `agent_end` event with `willRetry == False` (an `agent_end`
+with `willRetry == True` is followed by an automatic retry).
+
+### Synchronous use
+
+For non-async code, `PiAgentSync` runs the agent on a background loop and blocks:
+
+```python
+from pi_py_sdk import PiAgentSync, message_text
+
+with PiAgentSync(model="anthropic/claude-sonnet-4-20250514") as agent:
+    for event in agent.prompt_stream("hello"):
+        ...
+    for msg in agent.get_messages():        # typed messages
+        print(msg.role, message_text(msg))
+```
+
+### Tool approvals
+
+Extensions request decisions (allow this tool? pick an option? enter a value?) via the
+extension-UI sub-protocol. Install a handler with `on_ui_request`; without one, the SDK
+safely denies confirmations and cancels other dialogs so the agent never hangs.
+
+```python
+def approve(req):
+    if req.method == "confirm":
+        return True                 # allow
+    if req.method == "select":
+        return (req.options or [None])[0]
+    return None                     # cancel input/editor
+
+agent.on_ui_request(approve)        # see examples/with_approvals.py
+```
+
+The full command surface (`set_model`, `bash`, `compact`, `fork`, `get_session_stats`,
+steering/follow-up modes, …) is available as async methods on `PiAgent`.
+
+## The `pi-py` coding agent
+
+The repo also ships `pi_py_agent`, a small terminal coding agent built entirely on the
+SDK (the agent loop, tools, and model calls all run inside Pi). Installing the package
+provides a `pi-py` command:
+
+```bash
+pi-py                                   # interactive REPL
+pi-py --print "Run the tests and summarize failures"   # one-shot
+pi-py --model anthropic/claude-sonnet-4-20250514 --no-session
+```
+
+It streams assistant text, thinking, and tool activity (with result previews) to the
+terminal, answers approval dialogs interactively, and supports slash commands (`/help`,
+`/model`, `/models`, `/new`, `/state`, `/compact`, `/clone`, `/fork`, `/exit`). While
+the agent is responding you can **steer** it by typing (or `+text` to queue a
+follow-up). Ctrl-C aborts the current turn; Ctrl-D exits.
+
+## Tests
+
+```bash
+pytest                 # unit tests (no Node required); integration is deselected by default
+pytest -m integration  # live tests against a real `pi` (needs the binary on PATH)
+```
+
+The integration tests avoid LLM calls (state, models, bash), so they don't need a
+provider key. The one prompt-completion test additionally needs a working model and is
+skipped unless `PI_LIVE_LLM=1` is set.
+
+## Releasing
+
+CI (`.github/workflows/ci.yml`) runs the unit suite across Python 3.10–3.13, builds the
+wheel, and best-effort-smokes a real `pi` on every push/PR. Publishing
+(`.github/workflows/publish.yml`) builds and uploads to PyPI when a GitHub Release is
+published — it uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC, no token secret), which must be configured once for the repo.

pi_py_sdk-0.1.0/README.md

@@ -0,0 +1,129 @@
+# pi-py-sdk
+
+[![CI](https://github.com/noclaw/pi-py/actions/workflows/ci.yml/badge.svg)](https://github.com/noclaw/pi-py/actions/workflows/ci.yml)
+
+Python SDK for the [Pi](https://pi.dev) coding agent. It drives `pi-agent-core` — the
+well-tested TypeScript agent runtime — over Pi's **RPC mode** (`pi --mode rpc`, strict
+JSONL over stdin/stdout), so the agent loop, tool calling, sessions, compaction,
+retries, and provider auth all run inside Pi. No agent logic is reimplemented in Python.
+
+It includes the bridge core (transport, strict JSONL framing, id-correlated commands,
+streaming), the full RPC command surface, typed events and message models, the
+interactive **extension-UI sub-protocol** (tool approvals/dialogs), and a synchronous
+facade (`PiAgentSync`). A terminal coding agent (`pi-py`) ships on top. See
+[`docs/python-sdk-plan.md`](docs/python-sdk-plan.md) for the design.
+
+## Install
+
+```bash
+pip install pi-py-sdk
+```
+
+This installs the `pi_py_sdk` library and the `pi-py` agent CLI. You also need the Pi
+runtime for live use:
+
+```bash
+npm i -g @earendil-works/pi-coding-agent   # provides the `pi` binary
+export ANTHROPIC_API_KEY=...               # or another supported provider key
+```
+
+If `pi` isn't on `PATH`, the SDK falls back to `npx --yes @earendil-works/pi-coding-agent@<pinned>`.
+
+### Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Usage
+
+```python
+import asyncio
+from pi_py_sdk import PiAgent, MessageUpdateEvent
+
+async def main():
+    async with PiAgent(model="anthropic/claude-sonnet-4-20250514", cwd=".") as agent:
+        async for ev in agent.prompt_stream("List the Python files here"):
+            if isinstance(ev, MessageUpdateEvent) and ev.assistantMessageEvent:
+                ame = ev.assistantMessageEvent
+                if ame.type == "text_delta" and ame.delta:
+                    print(ame.delta, end="", flush=True)
+
+asyncio.run(main())
+```
+
+A prompt completes on an `agent_end` event with `willRetry == False` (an `agent_end`
+with `willRetry == True` is followed by an automatic retry).
+
+### Synchronous use
+
+For non-async code, `PiAgentSync` runs the agent on a background loop and blocks:
+
+```python
+from pi_py_sdk import PiAgentSync, message_text
+
+with PiAgentSync(model="anthropic/claude-sonnet-4-20250514") as agent:
+    for event in agent.prompt_stream("hello"):
+        ...
+    for msg in agent.get_messages():        # typed messages
+        print(msg.role, message_text(msg))
+```
+
+### Tool approvals
+
+Extensions request decisions (allow this tool? pick an option? enter a value?) via the
+extension-UI sub-protocol. Install a handler with `on_ui_request`; without one, the SDK
+safely denies confirmations and cancels other dialogs so the agent never hangs.
+
+```python
+def approve(req):
+    if req.method == "confirm":
+        return True                 # allow
+    if req.method == "select":
+        return (req.options or [None])[0]
+    return None                     # cancel input/editor
+
+agent.on_ui_request(approve)        # see examples/with_approvals.py
+```
+
+The full command surface (`set_model`, `bash`, `compact`, `fork`, `get_session_stats`,
+steering/follow-up modes, …) is available as async methods on `PiAgent`.
+
+## The `pi-py` coding agent
+
+The repo also ships `pi_py_agent`, a small terminal coding agent built entirely on the
+SDK (the agent loop, tools, and model calls all run inside Pi). Installing the package
+provides a `pi-py` command:
+
+```bash
+pi-py                                   # interactive REPL
+pi-py --print "Run the tests and summarize failures"   # one-shot
+pi-py --model anthropic/claude-sonnet-4-20250514 --no-session
+```
+
+It streams assistant text, thinking, and tool activity (with result previews) to the
+terminal, answers approval dialogs interactively, and supports slash commands (`/help`,
+`/model`, `/models`, `/new`, `/state`, `/compact`, `/clone`, `/fork`, `/exit`). While
+the agent is responding you can **steer** it by typing (or `+text` to queue a
+follow-up). Ctrl-C aborts the current turn; Ctrl-D exits.
+
+## Tests
+
+```bash
+pytest                 # unit tests (no Node required); integration is deselected by default
+pytest -m integration  # live tests against a real `pi` (needs the binary on PATH)
+```
+
+The integration tests avoid LLM calls (state, models, bash), so they don't need a
+provider key. The one prompt-completion test additionally needs a working model and is
+skipped unless `PI_LIVE_LLM=1` is set.
+
+## Releasing
+
+CI (`.github/workflows/ci.yml`) runs the unit suite across Python 3.10–3.13, builds the
+wheel, and best-effort-smokes a real `pi` on every push/PR. Publishing
+(`.github/workflows/publish.yml`) builds and uploads to PyPI when a GitHub Release is
+published — it uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC, no token secret), which must be configured once for the repo.