v0.2.3

Patch release: Pi 0.87.0 is the tested protocol baseline for the community Python SDK.

Changed

Tested Pi baseline 0.87.0

The offline compatibility constants and reviewed source fingerprints now match Pi 0.87.0 (#82). With this package version, Pi 0.87.0 reports compatibility="tested", and strict_version=True accepts it. The minimum remains 0.85.1; other recognized versions above the minimum remain untested unless reviewed separately.

The typed wire annotations now describe Pi's context_edit session entries and optional model image input limits. Context edits can omit or replace earlier content for future provider requests while preserving raw session history. Pi owns that behavior; the Python SDK passes the entry and model fields through. The RPC command and output event vocabulary is unchanged.

Compatibility → · API reference →

Compatibility

Requirement	Version
Python	3.11+
Pi protocol baseline (tested)	0.87.0
Pi protocol minimum	0.85.1

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

Import the package as pi_agent. No breaking Python API changes from 0.2.2.

Quick start · Compatibility · Changelog

v0.2.2

Patch release: record Pi 0.86.1 as the tested protocol baseline on top of 0.2.1.

Changed

Tested Pi baseline 0.86.1

The offline compatibility constants and reviewed source fingerprints now match Pi 0.86.1. The RPC command vocabulary, JSONL framing, and event serializer are unchanged from 0.86.0; upstream added a Meta Muse provider surface outside the RPC boundary (#76).

With this package version, Pi 0.86.1 reports compatibility="tested". Callers that set strict_version=True accept 0.86.1 and continue to reject other untested versions. The minimum remains 0.85.1.

Compatibility →

Compatibility

Requirement	Version
Python	3.11+
Pi protocol baseline (tested)	0.86.1
Pi protocol minimum	0.85.1

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

Import the package as pi_agent. No breaking API changes from 0.2.1.

Quick start · Compatibility · Changelog

v0.2.1

Patch release: more reliable blocking burst delivery, observation stop, and usability fixes on top of 0.2.0.

Fixed

Blocking finite-burst delivery

Ready blocking consumers now receive the full ready queue in each thread crossing instead of stopping at 64 records. Queue count and byte limits are unchanged; overflow for genuinely slow consumers remains explicit (#66, #36).

RPC backpressure →

Stream and input edge cases

• Sequential aiter / async for reuse on the same async stream no longer raises a busy error; concurrent readers and result-drain conflicts are still rejected (#62, #58).

• Locally rejected, unsent input leaves a healthy client reusable without weakening ownership for commands that may have reached Pi (#61, #57).

New Features

Stop observation without closing Pi

Call stop() on an observation context, drain remaining buffered records, then inspect status.end_reason for scoped stop, discard, overflow, or process termination (#69, #56).

Scoped observation example →

Documentation and compatibility

• Usage and API docs clarify interface choice for streaming, events, and settlement helpers (#70).

• README covers Python API use cases and thinking-level controls (#71).

• Tested Pi protocol baseline is 0.86.0; minimum remains 0.85.1 (#59).

Compatibility

Requirement	Version
Python	3.11+
Pi protocol baseline (tested)	0.86.0
Pi protocol minimum	0.85.1

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

Import the package as pi_agent. No breaking API changes from 0.2.0.

Quick start · Compatibility · Changelog

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

v0.1.0

First release of the community Python SDK for Pi.

Run Pi from Python while keeping its models, authentication, tools, extensions, and session storage.

New Features

Sync and async clients

Use PiClient in scripts or AsyncPiClient in asyncio applications, with the same commands and run behavior.

Choosing a client → · Async example →

Streaming and settled results

Stream text as it arrives or wait for the completed result, including session identity and observed token usage.

Streaming → · Streaming example → · Results →

Pi's RPC protocol from Python

Continue sessions, send images, steer a running conversation, switch models, and handle extension dialogs through explicit Python methods.

All 33 RPC commands → · RPC structure →

Added

• Typed command and event payloads, including preservation of unknown upstream fields and events (#7).

• Owned subprocess startup and shutdown, bounded queues, and cancellation cleanup (#8, #9, #10).

• Limits on retained run messages and protection against delayed events being attributed to a later run (#15).

• Nine runnable examples covering sync/async clients, streaming, sessions, images, steering, cancellation, events, and extension UI (#12).

Install

npm install -g @earendil-works/pi-coding-agent@0.85.1
python -m pip install pi-agent-python-sdk==0.1.0

Run pi once to configure your provider and model, then:

from pi_agent import PiClient

with PiClient() as pi:
    result = pi.run("Explain the current project without changing files.")
    print(result.text)

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 and communicates with Pi over stdio RPC.

CI covers Linux with Python 3.11–3.14, and macOS/Windows with Python 3.14. See the compatibility policy for the tested scope.

For source-checkout users

Replace the former distribution names pi-coding-agent-client or pi-coding-agent-python-sdk with pi-agent-python-sdk in installation commands. Change Python imports from pi_coding_agent_client to pi_agent (#17, #21).

---

Quick start · Examples · Changelog