pi-py-sdk 0.1.0

Python SDK for the Pi coding agent (pi-agent-core) over its RPC bridge

pi-py-sdk

Python SDK for the Pi 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 for the design.

Install

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:

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

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Usage

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:

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.

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:

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

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 (OIDC, no token secret), which must be configured once for the repo.