v0.2.0

The community Python SDK for Pi now follows more of the TypeScript RPC client, with Python run and streaming conveniences retained.

Breaking Changes

Command results now follow the pinned TypeScript client. run(), stream(), and RunResult keep their existing interfaces (#47, #51).

In 0.1.0	In 0.2.0
receipt = pi.prompt(text)	pi.prompt(text) returns None after checked acknowledgement; use pi.request("prompt", message=text) for the envelope
level = pi.cycle_thinking_level()	Read result["level"] when the result is not None
path = pi.export_html()	Read result["path"]; unknown metadata remains available
Read cached identity after a session mutation	Call pi.get_state() explicitly to refresh it

AcceptanceReceipt is removed. Prompt acknowledgement does not mean the agent started or completed. Await the equivalent methods on AsyncPiClient.

Migration guide →

New Features

Listeners and settlement helpers

Use on_event(), collect_events(), wait_for_idle(), and prompt_and_wait() when your application handles protocol events. Both Python clients preserve the original wire dictionaries. Completed results remain available through run() and context-managed streaming (#42).

Listener and helper contracts →

Process output from startup through cleanup

Subscribe before startup to receive extension events, or use observe() to capture selected stderr/stdout bytes and parsed RPC records, including late and failed responses. Storage and forwarding are caller-controlled, with explicit bounds and completeness status (#35, #37, #38, #39).

Process-output example →

Fixed

• Extension runs can stream before acknowledgement, while successful completion still requires acknowledgement and settlement (#33).

• UI callback failures preserve their causes, and dialog expiry cancels the dialog without failing unrelated work (#28, #32).

• Finite event bursts yield to consumers and blocking reads transfer bounded batches. Result-only runs avoid retaining progress events; slow consumers still receive explicit overflow (#40).

• Outbound escaped surrogates are preserved, and invalid deadline values consistently raise ValueError (#46, #51).

Compatibility

Requirement	Version
Python	3.11+
Pi protocol baseline	0.85.1
Node.js for Pi 0.85.1	22.19.0+

Pi must be installed separately. The SDK has no third-party Python runtime dependencies. CI compares all 33 shared commands and event payloads against the pinned TypeScript client, including installed-wheel checks (#48, #52).

python -m pip install pi-agent-python-sdk==0.2.0

Import the package as pi_agent. Pi continues to own models, authentication, tools, extensions, and session storage through the RPC subprocess boundary. Extensions and application-specific tracing stay outside this package.

Quick start · Compatibility · Changelog