pi-agent-python-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

{pi_agent_python_sdk-0.2.0 → pi_agent_python_sdk-0.2.2}/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.2.2
+
+### Changed
+
+- Update the tested Pi runtime to 0.86.1, retaining 0.85.1 as the minimum.
+
+## 0.2.1
+
+### Added
+
+- Stop process observations without closing Pi, then drain buffered records;
+  report scoped stop, discard, overflow, and process termination separately.
+
+### Fixed
+
+- Drain the ready queue in each blocking iterator transfer to avoid finite-burst
+  overflow caused by repeated partial transfers. Queue limits remain unchanged;
+  the additional batch is bounded by the same count and byte budgets.
+- Allow sequential async stream iterator reuse while retaining concurrent-reader
+  and result-drain protections.
+- Keep a healthy client usable after locally rejected, unsent input, without
+  relaxing ownership or cleanup for commands that may have reached Pi.
+
+### Changed
+
+- Update the tested Pi runtime to 0.86.0, retaining 0.85.1 as the minimum.
+- Clarify Python interface choice, async event consumption, and structured-output
+  boundaries; demonstrate thinking, tool events, and unknown metadata.
+- Describe system transcript messages, session usage entries, compaction system
+  snapshots, and model prompt-cache metadata in the wire annotations. Preserve
+  legacy optional fields and raw metadata; Pi still owns transcript and cache behavior.
+
 ## 0.2.0
 
 ### Breaking changes

{pi_agent_python_sdk-0.2.0 → pi_agent_python_sdk-0.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: pi-agent-python-sdk
-Version: 0.2.0
+Version: 0.2.2
 Summary: Typed async and synchronous Python clients for Pi's agent RPC runtime
 Project-URL: Homepage, https://github.com/cheenulabs/pi-agent-python-sdk
-Project-URL: Documentation, https://github.com/cheenulabs/pi-agent-python-sdk/tree/v0.2.0/docs
+Project-URL: Documentation, https://github.com/cheenulabs/pi-agent-python-sdk/tree/v0.2.2/docs
 Project-URL: Issues, https://github.com/cheenulabs/pi-agent-python-sdk/issues
-Project-URL: Changelog, https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/CHANGELOG.md
+Project-URL: Changelog, https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/CHANGELOG.md
 Author: cheenulabs
 License-Expression: MIT
 License-File: LICENSE
@@ -23,40 +23,69 @@ Description-Content-Type: text/markdown
 
 # Pi Agent Python SDK
 
-[![PyPI](https://img.shields.io/pypi/v/pi-agent-python-sdk?style=flat-square)][pypi]
+[![PyPI](https://img.shields.io/pypi/v/pi-agent-python-sdk.svg?style=flat-square)][pypi]
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square)][metadata]
 [![MIT license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)][license]
 
-**Run Pi from Python. Stream responses, continue conversations, and control sessions.**
+**Use your installed Pi coding agent as a Python API. Stream responses,
+continue conversations, and control sessions from Python.**
 
-A community Python SDK for [Pi coding agent](https://github.com/earendil-works/pi).
-Use synchronous or asynchronous clients with typed access to Pi's RPC commands
-and no third-party Python runtime dependencies. Pi runs as a subprocess and keeps
-its usual models, authentication, tools, extensions, skills, and configuration.
+[Pi](https://github.com/earendil-works/pi) is an open-source coding agent that
+runs in your terminal. This unofficial community SDK launches the Pi CLI in RPC
+mode and exposes prompts, streaming events, and sessions through typed
+synchronous and asynchronous Python APIs.
 
-> Requires Python **3.11+** and a separate Pi installation. The tested protocol
-> baseline is **Pi 0.85.1**; see [compatibility][compatibility] for version and
-> platform scope.
+```python
+from pi_agent import PiClient
+
+with PiClient() as pi:
+    print(pi.run("Explain the current project without changing files.").text)
+```
+
+Requires an installed, configured Pi CLI — see [Prerequisites](#prerequisites).
+
+[Prerequisites](#prerequisites) · [Quick start](#quick-start) ·
+[Streaming](#streaming) · [Async](#async-usage) ·
+[Configuration](#configuration) · [Thinking](#models-and-thinking) ·
+[RPC](#rpc-access) · [Documentation](#documentation) ·
+[Troubleshooting](#troubleshooting) · [Support](#support)
+
+## What you can do
 
-[Quick start](#quick-start) · [Streaming](#streaming) · [Async](#async-usage) ·
-[Configuration](#configuration) · [RPC](#rpc-access) · [Documentation](#documentation)
+- **Run prompts from Python** — get a final answer, or stream text, thinking, and
+  tool events as they happen.
+- **Keep conversations going** — send follow-ups on the same client, or resume,
+  fork, and clone sessions.
+- **Control the agent** — switch models, set thinking level, steer mid-run, and
+  compact context.
+- **Reuse your Pi setup** — same configuration, tools, and extensions as the CLI,
+  with sync or async clients.
+
+## Prerequisites
+
+| Requirement | Notes |
+| --- | --- |
+| Python **3.11+** | Package metadata requires 3.11 or newer |
+| Node.js **22.19.0+** | Required by Pi 0.86.1 |
+| Pi **0.85.1+** | Minimum accepted version; **0.86.1** is the tested baseline |
+| Model provider | Required; configure with the Pi CLI (see Quick start) |
 
 ## Quick start
 
-Install Pi with Node.js **22.19.0 or newer**:
+Install Pi with Node.js **22.19.0 or newer** (pin matches the tested baseline):
 
 ```sh
-npm install -g @earendil-works/pi-coding-agent@0.85.1
+npm install -g @earendil-works/pi-coding-agent@0.86.1
 pi --version
 ```
 
-Run `pi` once to configure your provider and model using Pi's normal setup.
-The SDK uses that configuration when it starts Pi.
+Run `pi` once to configure your provider and model. The SDK uses that
+configuration when it starts Pi.
 
 Install the Python package from [PyPI][pypi]:
 
 ```sh
-python -m pip install pi-agent-python-sdk==0.2.0
+python -m pip install pi-agent-python-sdk
 ```
 
 The distribution is named `pi-agent-python-sdk`; import it as
@@ -71,8 +100,8 @@ with PiClient() as pi:
 ```
 
 The context manager starts and closes Pi. `run()` waits for the conversation to
-settle, including retries and queued follow-ups. The result includes finalized
-messages, session identity, elapsed time, and observed assistant usage.
+settle. The result includes finalized messages, session identity, elapsed time,
+and observed assistant usage.
 
 Continue the conversation with another call on the same client:
 
@@ -87,15 +116,6 @@ with PiClient() as pi:
 Pi keeps the conversation context. Each result contains only the messages and
 answer from that call; a call with no assistant output has empty text.
 
-## What you can do
-
-- **Run and stream:** get a final answer or consume text, thinking, and tool events.
-- **Keep a conversation:** send follow-up prompts, resume sessions, fork, or clone.
-- **Control Pi:** select models, adjust thinking, steer work, compact context, and
-  call all 33 RPC commands in the pinned baseline.
-- **Integrate with your application:** use sync or async clients, typed results,
-  raw event dictionaries, and extension UI callbacks.
-
 ## Streaming
 
 ```python
@@ -110,9 +130,15 @@ with PiClient() as pi:
     print(f"\nStop reason: {result.stop_reason}")
 ```
 
+<details>
+<summary>Streaming details</summary>
+
 `event.raw` contains the full Pi event, including fields the SDK does not yet
-recognize. Keep the stream inside its context: leaving early cleans up unfinished work. See [errors and cancellation][errors] for
-handling timeouts and partial results.
+recognize. Keep the stream inside its context: leaving early cleans up unfinished
+work. See [errors and cancellation][errors] for handling timeouts and partial
+results.
+
+</details>
 
 ## Async usage
 
@@ -135,8 +161,13 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Async streaming uses `async with pi.stream(...)`, `async for event in stream`,
-and `await stream.result()`. See the [complete streaming example][stream-example].
+<details>
+<summary>Async streaming</summary>
+
+Use `async with pi.stream(...)`, `async for event in stream`, and
+`await stream.result()`. See the [complete streaming example][stream-example].
+
+</details>
 
 ## Configuration
 
@@ -150,14 +181,70 @@ with PiClient(cwd=".", no_session=True) as pi:
 ```
 
 Leave `no_session` unset to preserve Pi's normal session persistence. Use
-`provider=` and `model=` to override Pi's configured model, or `session=` to open
-an existing session. See [constructor options][constructor-options]
-for environment overrides, executable paths, and deadlines.
+`session=` to open an existing session. For model overrides, see
+[Models and thinking](#models-and-thinking).
+
+<details>
+<summary>More configuration</summary>
+
+See [constructor options][constructor-options] for environment overrides,
+executable paths, and deadlines.
 
 Extensions are installed and configured through Pi. To load your own extension,
-pass `extra_args=["--extension", "/absolute/path/to/your-extension.ts"]` to either
-client. See [using your own extensions][extensions]
-for details and [extension UI][ui-example] for an interactive example.
+pass `extra_args=["--extension", "/absolute/path/to/your-extension.ts"]` to
+either client. See [using your own extensions][extensions] for details and
+[extension UI][ui-example] for an interactive example.
+
+</details>
+
+## Models and thinking
+
+By default the SDK uses whatever model you already configured in the Pi CLI.
+Override it when you construct the client, or switch later on the same client.
+Set the model and thinking level **before** `run()` or `stream()`.
+
+Select a model at construction:
+
+```python
+from pi_agent import PiClient
+
+with PiClient(provider="openai", model="gpt-5") as pi:
+    print(pi.run("Summarise this repo without changing files.").text)
+```
+
+Thinking levels depend on the current model. Query them, set one, then confirm
+what Pi actually applied:
+
+```python
+from pi_agent import PiClient
+
+with PiClient() as pi:
+    levels = pi.get_available_thinking_levels()
+    print("available:", levels)
+    if "high" in levels:
+        pi.set_thinking_level("high")
+    print("effective:", pi.get_state()["thinkingLevel"])
+    print(pi.run("Analyse this project's architecture without changing files.").text)
+```
+
+Replace the example provider/model ids with ones from your Pi install
+(`pi --list-models` or `get_available_models()`).
+
+<details>
+<summary>List models and switch after start</summary>
+
+```python
+from pi_agent import PiClient
+
+with PiClient() as pi:
+    for model in pi.get_available_models():
+        print(model["provider"], model["id"])
+    selected = pi.set_model("openai", "gpt-5")
+    print("using", selected["provider"], selected["id"])
+    print(pi.run("Summarise this repo without changing files.").text)
+```
+
+</details>
 
 ## RPC access
 
@@ -170,7 +257,18 @@ Your Python application
             Models · tools · extensions · sessions
 ```
 
-Choose the interface that fits the work:
+Inspect session state without starting a model run:
+
+```python
+from pi_agent import PiClient
+
+with PiClient() as pi:
+    state = pi.get_state()
+    print(state["sessionId"])
+```
+
+<details>
+<summary>Which interface to use</summary>
 
 | You need | Use |
 | --- | --- |
@@ -182,29 +280,20 @@ Choose the interface that fits the work:
 | A specific Pi operation | `get_state()`, `set_model()`, `fork()`, and other command methods |
 | A raw command response envelope | `request()` |
 
-For example, inspect session state without starting a model run:
-
-```python
-from pi_agent import PiClient
-
-with PiClient() as pi:
-    state = pi.get_state()
-    print(state["sessionId"])
-```
-
 Python arguments use `snake_case`; wire dictionaries retain Pi's `camelCase`
 fields. `prompt()` acknowledges submission, which may be handled entirely by an
 extension. It does not wait for a completed answer.
 
-Use one client per conversation and wait for each `run()` or stream to finish
-before starting the next. After using `prompt()` for your own event handling,
-use a fresh client for `run()` or `stream()` so results cannot include delayed
-events from earlier work. The SDK launches a new process and cannot attach to an existing
-Pi terminal session.
+Each client starts its own Pi subprocess. Use one client per conversation and
+wait for each `run()` or stream to finish before starting the next. After using
+`prompt()` for your own event handling, use a fresh client for `run()` or
+`stream()` so results cannot include delayed events from earlier work.
 
 See [RPC structure][rpc] for the protocol mapping and module layout, and
 the [command reference][commands] for every method.
 
+</details>
+
 ## Documentation
 
 | Guide | Contents |
@@ -215,35 +304,46 @@ the [command reference][commands] for every method.
 | [RPC structure][rpc] | How the Python client maps to Pi's protocol |
 | [Compatibility][compatibility] | Runtime versions and platform validation |
 | [Examples][examples] | Runnable sync, async, streaming, sessions, steering, and UI examples |
-| [Release notes][release] | Changes included in 0.2.0 |
+| [Release notes][release] | Changes included in 0.2.2 |
 
 Examples use your configured Pi and may make provider calls. Development checks
 use an isolated local test provider; see [CONTRIBUTING.md][contributing] for
 setup and validation commands.
 
-Maintainers: [protocol discovery][discovery] ·
-[maintenance][maintenance] · [release checklist][releasing].
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `pi` not found / launch fails | Ensure the Pi CLI is on `PATH`, or pass `executable=` to the client |
+| Version rejected | Upgrade to Pi **0.85.1+**; prefer the tested baseline **0.86.1** |
+| No model / auth errors | Run `pi` once and complete provider setup |
+| Unexpected file or command changes | Review Pi tool/extension settings before automation |
+
+## Support
+
+- [Open an issue][issues] for bugs, questions, or compatibility reports.
+- See [CONTRIBUTING.md][contributing] for local setup and pull requests.
+- For security reports, open a [private security advisory][security].
 
 ## License
 
 [MIT][license]
 
 [pypi]: https://pypi.org/project/pi-agent-python-sdk/
-[release]: https://github.com/cheenulabs/pi-agent-python-sdk/releases/tag/v0.2.0
-[metadata]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/pyproject.toml
-[license]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/LICENSE
-[compatibility]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/compatibility.md
-[errors]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/errors.md
-[stream-example]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/examples/stream.py
-[constructor-options]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/api.md#constructor-options
-[extensions]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/usage.md#using-your-own-extensions
-[ui-example]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/examples/ui.py
-[rpc]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/rpc.md
-[commands]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/api.md#all-33-rpc-commands
-[usage]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/usage.md
-[api]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/api.md
-[examples]: https://github.com/cheenulabs/pi-agent-python-sdk/tree/v0.2.0/examples
-[contributing]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/CONTRIBUTING.md
-[discovery]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/discovery.md
-[maintenance]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/maintenance.md
-[releasing]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.0/docs/releasing.md
+[release]: https://github.com/cheenulabs/pi-agent-python-sdk/releases/tag/v0.2.2
+[metadata]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/pyproject.toml
+[license]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/LICENSE
+[compatibility]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/compatibility.md
+[errors]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/errors.md
+[stream-example]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/examples/stream.py
+[constructor-options]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/api.md#constructor-options
+[extensions]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/usage.md#using-your-own-extensions
+[ui-example]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/examples/ui.py
+[rpc]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/rpc.md
+[commands]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/api.md#all-33-rpc-commands
+[usage]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/usage.md
+[api]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/docs/api.md
+[examples]: https://github.com/cheenulabs/pi-agent-python-sdk/tree/v0.2.2/examples
+[contributing]: https://github.com/cheenulabs/pi-agent-python-sdk/blob/v0.2.2/CONTRIBUTING.md
+[issues]: https://github.com/cheenulabs/pi-agent-python-sdk/issues
+[security]: https://github.com/cheenulabs/pi-agent-python-sdk/security/advisories/new