pi-python-core 0.8.1__tar.gz → 0.8.2__tar.gz

pi_python_core-0.8.2/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: pi-python-core
+Version: 0.8.2
+Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading :: 2 - Beta
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.18
+Requires-Dist: websockets>=14.2
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: oauth
+Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'oauth'
+Provides-Extra: providers
+Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# pi-python-core
+
+**English** | [中文](README.zh-CN.md)
+
+An embeddable Python agent core, ported from [Pi](https://github.com/earendil-works/pi) (pinned to `v1.0.0`). It does one job: send the conversation to a model, run the tools the model asks for, hand the results back, and repeat until the model answers. Tools are plain Python functions; the model can be Claude, GPT, DeepSeek, or an open model running on your own machine or cluster.
+
+`pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
+
+## Install
+
+Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
+
+```bash
+pip install pi-python-core      # or: uv add pi-python-core
+```
+
+You install `pi-python-core` and import `pi_python`.
+
+| Option | What it adds |
+|---|---|
+| (none) | The agent core and the built-in model connectors: Claude, OpenAI, Codex, DeepSeek, and any OpenAI-compatible server (Ollama, vLLM, llama.cpp, …) |
+| `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
+| `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
+| `[mcp]` | Gives the agent the tools of MCP servers |
+
+Dependencies are version ranges rather than pins, so the package fits into most existing environments.
+
+## Five-minute start
+
+```python
+from pi_python import Agent, tool
+from pi_python.providers import AnthropicProvider
+
+@tool
+def word_count(text: str) -> int:
+    """Count the words in a text."""
+    return len(text.split())
+
+agent = Agent(provider=AnthropicProvider(api_key="..."), model="claude-sonnet-4-5", tools=[word_count])
+result = agent.prompt_sync("How many words are in 'to be or not to be'?")
+print(result.messages[-1].content[0].text)
+```
+
+`@tool` builds a tool from the function's signature and docstring; both plain and `async` functions work. In async code, use `await agent.prompt(...)`. Switching to a local model changes two lines:
+
+```python
+from pi_python.providers import OpenAICompletionsProvider
+
+llm = OpenAICompletionsProvider(base_url="http://localhost:11434/v1", name="ollama")
+agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), tools=[word_count])
+```
+
+To try it offline first: `python examples/quickstart.py`.
+
+## What it does
+
+| Need | How | Example |
+|---|---|---|
+| Write tools | Decorate a plain function with `@tool`; arguments such as pydantic models, dataclasses, enums and dates are converted automatically; hand-written or MCP-generated JSON Schema works too | [quickstart](examples/quickstart.py) |
+| Connect a model | Claude and GPT through an API key or subscription sign-in; DeepSeek; any OpenAI-compatible server | [local_model](examples/local_model.py), [provider_chat](examples/provider_chat.py) |
+| Use MCP tools | `async with connect_stdio(...) as tools` | [mcp_tools](examples/mcp_tools.py) |
+| Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down | [subagent](examples/subagent.py) |
+| Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
+| Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
+| Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
+| Observe and audit | Subscribe to events; hooks before and after tool execution can block or rewrite tool calls | |
+
+Apart from `provider_chat`, which needs real credentials, every example runs offline without an API key, and the tests run each one.
+
+## Relationship to Pi
+
+The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples.
+
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. This project uses its own version numbers and is not an official Pi release.
+
+## Documentation
+
+- [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
+- [Public API](docs/API.md)
+- [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
+- [Implementation and verification results](docs/IMPLEMENTATION.md) (Chinese)
+- [Item-by-item comparison with Pi, and deliberate differences](compat/COVERAGE.md) (Chinese)
+- [Rebuilding the reference and checking release candidates](reference/README.md) (Chinese)
+
+## Development
+
+```bash
+uv sync --locked --extra oauth --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
+```
+
+CI is defined in `.github/workflows/ci.yml` and runs on GitHub Actions for every push: each Python version on Linux (including 3.14t and PyPy), plus macOS and Windows.

pi_python_core-0.8.2/README.md

@@ -0,0 +1,93 @@
+# pi-python-core
+
+**English** | [中文](README.zh-CN.md)
+
+An embeddable Python agent core, ported from [Pi](https://github.com/earendil-works/pi) (pinned to `v1.0.0`). It does one job: send the conversation to a model, run the tools the model asks for, hand the results back, and repeat until the model answers. Tools are plain Python functions; the model can be Claude, GPT, DeepSeek, or an open model running on your own machine or cluster.
+
+`pi-agent-core` on PyPI is a separate project that ports an older version from pi-mono (early 2026). This library follows the behavior of Pi v1.0.0, compared case by case with the upstream code's actual output, and ships its own connectors for Claude, OpenAI, DeepSeek and local models, with no model SDK required.
+
+## Install
+
+Python 3.11–3.14 (including free-threaded 3.14t) and PyPy 3.11. No Node.js or model SDK needed.
+
+```bash
+pip install pi-python-core      # or: uv add pi-python-core
+```
+
+You install `pi-python-core` and import `pi_python`.
+
+| Option | What it adds |
+|---|---|
+| (none) | The agent core and the built-in model connectors: Claude, OpenAI, Codex, DeepSeek, and any OpenAI-compatible server (Ollama, vLLM, llama.cpp, …) |
+| `[oauth]` | Verifies the identity token when you sign in with a ChatGPT account (`openai-chatgpt`); it brings in the compiled `cryptography` package. Claude subscription and Codex sign-in do not need it |
+| `[providers]` | Same as `[oauth]`; keeps install commands from 0.8.1 and earlier working |
+| `[mcp]` | Gives the agent the tools of MCP servers |
+
+Dependencies are version ranges rather than pins, so the package fits into most existing environments.
+
+## Five-minute start
+
+```python
+from pi_python import Agent, tool
+from pi_python.providers import AnthropicProvider
+
+@tool
+def word_count(text: str) -> int:
+    """Count the words in a text."""
+    return len(text.split())
+
+agent = Agent(provider=AnthropicProvider(api_key="..."), model="claude-sonnet-4-5", tools=[word_count])
+result = agent.prompt_sync("How many words are in 'to be or not to be'?")
+print(result.messages[-1].content[0].text)
+```
+
+`@tool` builds a tool from the function's signature and docstring; both plain and `async` functions work. In async code, use `await agent.prompt(...)`. Switching to a local model changes two lines:
+
+```python
+from pi_python.providers import OpenAICompletionsProvider
+
+llm = OpenAICompletionsProvider(base_url="http://localhost:11434/v1", name="ollama")
+agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), tools=[word_count])
+```
+
+To try it offline first: `python examples/quickstart.py`.
+
+## What it does
+
+| Need | How | Example |
+|---|---|---|
+| Write tools | Decorate a plain function with `@tool`; arguments such as pydantic models, dataclasses, enums and dates are converted automatically; hand-written or MCP-generated JSON Schema works too | [quickstart](examples/quickstart.py) |
+| Connect a model | Claude and GPT through an API key or subscription sign-in; DeepSeek; any OpenAI-compatible server | [local_model](examples/local_model.py), [provider_chat](examples/provider_chat.py) |
+| Use MCP tools | `async with connect_stdio(...) as tools` | [mcp_tools](examples/mcp_tools.py) |
+| Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down | [subagent](examples/subagent.py) |
+| Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
+| Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
+| Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |
+| Observe and audit | Subscribe to events; hooks before and after tool execution can block or rewrite tool calls | |
+
+Apart from `provider_chat`, which needs real credentials, every example runs offline without an API key, and the tests run each one.
+
+## Relationship to Pi
+
+The run loop, event order, hooks, queues, and the handling of errors and cancellation all match Pi, and this is checked differentially: the same inputs go to the pinned upstream code and to this library, and the model requests, tool calls, events and final transcript are compared item by item. All cases currently agree: 25 for the core loop, 50 for model connectors, 2 for multi-turn WebSocket, and 44 error-classification samples.
+
+A few differences are deliberate, such as strict tool-argument validation without type coercion, and returning copies of state to callers. Others are additions for Python users, such as `@tool`, blocking calls, and calling `continue_run()` directly after a failure. Each one is recorded in the [coverage map](compat/COVERAGE.md) (Chinese). Features Pi keeps in its application layer (terminal UI, session file format, context compaction) are not in this core; compaction can be built with hooks, and an example shows the full approach. This project uses its own version numbers and is not an official Pi release.
+
+## Documentation
+
+- [Concepts on one page: five ideas and one turn](docs/CONCEPTS.md)
+- [Public API](docs/API.md)
+- [Model connectors, subscription sign-in and local models](docs/PROVIDERS.md)
+- [Implementation and verification results](docs/IMPLEMENTATION.md) (Chinese)
+- [Item-by-item comparison with Pi, and deliberate differences](compat/COVERAGE.md) (Chinese)
+- [Rebuilding the reference and checking release candidates](reference/README.md) (Chinese)
+
+## Development
+
+```bash
+uv sync --locked --extra oauth --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # every check, including the comparison with upstream (needs Node)
+```
+
+CI is defined in `.github/workflows/ci.yml` and runs on GitHub Actions for every push: each Python version on Linux (including 3.14t and PyPy), plus macOS and Windows.

pi_python_core-0.8.1/README.md → pi_python_core-0.8.2/README.zh-CN.md

@@ -1,5 +1,7 @@
 # pi-python-core
 
+[English](README.md) | **中文**
+
 一个可嵌入的 Python agent 核心，移植自 [Pi](https://github.com/earendil-works/pi)（固定参照 `v1.0.0`）。它负责一件事：把对话发给模型，执行模型要求的工具，把结果交回模型，直到得到回答。工具就是普通的 Python 函数；模型可以是 Claude、GPT、DeepSeek，也可以是本机或集群上的开源模型。
 
 PyPI 上的 `pi-agent-core` 是另一个独立项目，移植的是 2026 年初 pi-mono 中的旧版本。本库对照 Pi v1.0.0 的行为，与上游的实际运行结果逐组比较；并自带 Claude、OpenAI、DeepSeek 和本地模型的接入，不需要安装任何模型 SDK。
@@ -9,15 +11,16 @@ PyPI 上的 `pi-agent-core` 是另一个独立项目，移植的是 2026 年初
 支持 Python 3.11–3.14（包括无 GIL 的 3.14t）和 PyPy 3.11，不需要 Node 或任何模型 SDK。
 
 ```bash
-pip install 'pi-python-core[providers]'      # 或 uv add 'pi-python-core[providers]'
+pip install pi-python-core      # 或 uv add pi-python-core
 ```
 
 安装名是 `pi-python-core`，导入名是 `pi_python`。
 
 | 安装选项 | 带来什么 |
 |---|---|
-| 不加选项 | 执行核心，只依赖 `jsonschema` |
-| `[providers]` | 真实模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
+| 不加选项 | 执行核心和内置模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
+| `[oauth]` | 用 ChatGPT 账号登录（`openai-chatgpt`）时校验身份令牌，会带进需要编译的 `cryptography`。Claude 订阅和 Codex 登录不需要它 |
+| `[providers]` | 与 `[oauth]` 相同，让 0.8.1 及以前的安装命令仍然可用 |
 | `[mcp]` | 把 MCP 服务器的工具交给 agent |
 
 依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
@@ -72,9 +75,9 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 
 ## 文档
 
-- [一页看懂：五个概念和一轮的流程](docs/CONCEPTS.md)
-- [公开 API](docs/API.md)
-- [模型接入、订阅登录与本地模型](docs/PROVIDERS.md)
+- [一页看懂：五个概念和一轮的流程](docs/zh/CONCEPTS.md)
+- [公开 API](docs/zh/API.md)
+- [模型接入、订阅登录与本地模型](docs/zh/PROVIDERS.md)
 - [实施与验证结果](docs/IMPLEMENTATION.md)
 - [与 Pi 的逐项对照和有意差异](compat/COVERAGE.md)
 - [参照重建与候选版本验证](reference/README.md)
@@ -82,7 +85,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 ## 开发
 
 ```bash
-uv sync --locked --extra providers --extra mcp
+uv sync --locked --extra oauth --extra mcp
 uv run pytest -q
 uv run python scripts/verify.py      # 全部检查，含与上游的差分（需要 Node）
 ```

{pi_python_core-0.8.1 → pi_python_core-0.8.2}/compat/COVERAGE.md

@@ -48,7 +48,7 @@ D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通
 
 新增 Python 合同见 `test_extended_core.py`、`test_providers.py`、`test_oauth.py`。8 个共享网络流输入在 `provider-fixtures/`，实际上游解析器输出和 Python 输出保存在 [provider-conformance.json](results/provider-conformance.json)。它们对比最终内容、签名和停止原因，不等价于所有供应商请求选项或真实账号端到端兼容。
 
-当前边界与明确差异见 [PROVIDERS.md](../docs/PROVIDERS.md)。0.1 的 accepted baseline 保留为历史核心验收记录，新增能力单独记录，不修改固定上游提交。
+当前边界与明确差异见 [PROVIDERS.md](../docs/zh/PROVIDERS.md)。0.1 的 accepted baseline 保留为历史核心验收记录，新增能力单独记录，不修改固定上游提交。
 
 ## 0.3 范围修订
 
@@ -93,7 +93,7 @@ D1–D8 不变。本轮明确记录的差异：WebSocket 帧不带 `stream` 字
 这一轮的目标是好装、多版本可用、容易在上面搭完整的 agent。按与上游的关系分三类记录。
 
 与上游一致，并有对照证据：
-- **Chat Completions 接入**：逐项移植 `openai-completions.ts`，新增 16 组 Provider 差分（Provider 差分共 50 组），覆盖 Ollama、vLLM、llama.cpp、OpenRouter、DeepSeek 等兼容配置和全部 11 种推理参数格式。与上游的差异见 [PROVIDERS](../docs/PROVIDERS.md#本地模型与-openai-兼容服务)。
+- **Chat Completions 接入**：逐项移植 `openai-completions.ts`，新增 16 组 Provider 差分（Provider 差分共 50 组），覆盖 Ollama、vLLM、llama.cpp、OpenRouter、DeepSeek 等兼容配置和全部 11 种推理参数格式。与上游的差异见 [PROVIDERS](../docs/zh/PROVIDERS.md#本地模型与-openai-兼容服务)。
 - **出错判断**：`is_context_overflow`、`is_retryable_error`、`is_recoverable_length` 移植自 `overflow.ts` 和 `retry.ts`，44 条共享样例与上游函数的实际输出一致（`scripts/recovery_conformance.py`）。另外认识本库自己的错误格式：Python 网络错误名，以及按 HTTP 状态码判断本库的 HTTP 错误；上游格式的文字仍按上游规则判断。
 - **工具 schema**：不再只接受一个子集。与上游一样接受 draft-07 等标准 schema，并按 `format`、`pattern` 校验参数（已用上游校验器对同一 schema 实测）；仍只允许指向 schema 内部的引用。D1 的"不转换类型"不变。
 - **HTTP 错误正文**：与上游一样保留，最多 4000 字符；本库另外把请求所带的凭据替换为 `[redacted]`。

pi_python_core-0.8.2/docs/API.md

@@ -0,0 +1,200 @@
+# Python API
+
+**English** | [中文](zh/API.md)
+
+Import the public types from `pi_python`. The minimum Python version is 3.11, and only the `asyncio` backend is used. Read [the one-page concepts](CONCEPTS.md) first. `Agent` makes model requests through a Provider; it never reads keys implicitly and never closes a shared Provider that the caller passed in. Real model connections are covered in [model connectors](PROVIDERS.md).
+
+## Agent and run results
+
+`Agent(provider=..., model="mock" or ModelInfo(...), options={}, system_prompt="", tools=[], messages=[], hooks=Hooks(), limits=RunLimits(), execution_mode="parallel", steering_mode="one_at_a_time", follow_up_mode="one_at_a_time")`. If there is neither a `provider` nor a default stream set with `set_default_stream_fn`, `prompt` raises `ConfigurationError` immediately.
+
+| Method | Behavior |
+|---|---|
+| `await prompt(str_or_message_or_list)` | Appends the input and runs; returns a `RunResult` |
+| `await continue_run()` | Continues from a valid user/tool-result history, or consumes input queued after the final answer; if the last answer failed or was cancelled, retries that turn (see "Recovering from failures"); never replays past tools |
+| `prompt_sync(...)` / `continue_run_sync()` | Blocking versions for plain scripts; Ctrl+C cancels the current run; see "Using it from plain scripts" |
+| `steer(message)` | Accepts guidance at the next safe boundary; also takes a string |
+| `follow_up(message)` | Accepts follow-up input once tools and guidance no longer ask to continue |
+| `abort(reason="requested")` | Requests cancellation and returns immediately; the run then wraps up the way Pi does, see "Cancellation, timeouts and events" below |
+| `await wait_for_idle()` | Waits for local tasks and the critical end-of-run subscribers; raises if cleanup times out |
+| `subscribe(listener)` | Registers a sync or async critical subscriber; returns an unsubscribe function |
+| `update_config(AgentConfigUpdate(...))` | Replaces tools, model or options field by field; during a run, the change waits for the next turn boundary |
+| `clear_queues(steering=True, follow_up=True)` | Explicitly clears the given queues |
+| `await aclose()` | Requests cancellation and waits for this instance's cleanup; does not close a shared Provider |
+
+One instance does not accept overlapping `prompt` / `continue_run` calls; the second call raises `AgentBusyError` immediately. `async with Agent(...)` is supported. `state` returns a defensive copy; changing it does not change the history.
+
+`RunResult` contains `status` (`completed` / `failed` / `cancelled` / `limit_reached`), the `messages` added by this run, the accumulated numeric `usage`, `stop_reason`, `errors`, `tool_outcomes`, `reconciliation_required`, `cleanup_complete`, and the number of items left in each queue. Usage only sums the top-level numeric fields the Provider reports; it does not estimate cost.
+
+`tool_outcomes` records, in call order, the raw arguments, the prepared arguments, `raw_result` and the final `result`. `execution_status` is `not_started`, `running`, `succeeded`, `failed`, `cancelled` or `unknown`. `cancelled` means the tool was cancelled or timed out; `unknown` only comes from a `ToolOutcomeUnknownError` that the tool raised itself. If execution succeeded but the output check or the after-hook failed, the status is still `succeeded` and the final result is an error. No error triggers an automatic retry.
+
+## Provider
+
+```python
+class MyProvider:
+    async def stream(self, request, cancel):
+        cancel.raise_if_cancelled()
+        yield ModelEvent.boundary("start", 0, TextContent(""))
+        yield ModelEvent.text("hello")
+        yield ModelEvent.boundary("end", 0, TextContent("hello"))
+        yield ModelEvent.done(AssistantMessage.text("hello", provider="my-provider", model=request.model))
+```
+
+`stream` returns an async iterator; the caller does not await it first. `ModelRequest` contains `messages`, the replayed `tools`, `model` (the name), the caller-supplied `model_info` (may be None) and `options`. These are copies, isolated from the run configuration: a Provider may change its own copy but cannot change the history through it.
+
+There is a single event protocol, the same as upstream: an optional `start`; for each content block, in order, `*_start`, any number of `*_delta`, then `*_end` (block types are text, thinking and toolcall); and finally exactly one `done`, carrying the complete answer. The constructors are `ModelEvent.boundary("start"|"end", index, block)`, `ModelEvent.text(delta, index)`, `ModelEvent.thinking(delta, index)`, `ModelEvent.toolcall(json_fragment, index)` and `ModelEvent.done(message)`; `index` is the block's position in the final answer. A non-streaming Provider may emit only `done`. To fail, a Provider can raise an exception or emit an `error` event (all remote Providers do the latter). Either way, the Agent does what Pi does: it records the answer as a message with `stop_reason="error"`, keeping the partial content already streamed, the provider and model names and the error text, and then calls `finish_turn` and emits `turn_end` as usual.
+
+Every event passes the same check: blocks must pair up, deltas must land in an open block of the same type, `done` must be the last event and the iterator must end normally, and the final answer must match the finished blocks (the only allowed addition is upstream's completion of encrypted reasoning content). If the check fails, the turn fails and no tool runs. The usual stop reasons are `stop`, `tool_use`, `length`, `error` and `aborted`.
+
+Message data also allows `pending` and `deferred`. `pending` is only for in-stream snapshots and cannot be committed to history; `deferred` can hold a background handle, but the library does not yet poll background tasks. For `length`, every tool call gets a not-executed result, and the model may then handle the error. `error` / `aborted` messages cannot declare tool calls: before the message is committed, its tool calls are removed, the rest of the partial content is kept, and a `removed_tool_calls` entry is added to `diagnostics`.
+
+## Tool
+
+`Tool(name, description, input_schema, execute, output_schema=None, execution_mode="parallel", prepare_arguments=None)`.
+
+`execute(args, context)` can be an async function or a plain function. Plain functions run in a worker thread so they do not block the event loop. Threads cannot be interrupted: after cancellation, the library waits for the function until the cleanup deadline and uses its result if it finishes; past the deadline, it is treated as a tool that could not be stopped (see "Cancellation, timeouts and events"). Long-running tools are better written as async functions. `ToolContext` provides `run_id`, `call_id`, `cancel` and `await emit_update(json_value)`.
+
+A tool can return a `ToolResult` or a plain value: a string becomes a text result; `None` becomes empty content; dicts, lists and numbers become their JSON text and are also kept as `structured_content`.
+
+`ToolResult.text(text, details=None, structured_content=None, is_error=False, terminate=False)` creates a text result. `details` and `structured_content` are not sent to the model automatically. Content accepts `TextContent` and `ImageContent`. Input is strictly validated by default: types are not coerced and nulls are not dropped. `prepare_arguments(args)` can return new arguments, synchronously or asynchronously, which are then validated the same way; both the original and the converted arguments are kept.
+
+Standard JSON Schema is accepted: draft-04, 06, 07, 2019-09 or 2020-12 is chosen by `$schema`, and 2020-12 is used when `$schema` is absent. Schemas generated by pydantic and the schemas of common MCP tools work as they are. As in Pi, argument validation checks `pattern` and `format`. A `format` is checked only when jsonschema has a checker for it: `email`, `date`, `ipv4` and others work out of the box, while `uri`, `date-time` and others need `jsonschema[format-nongpl]` installed. Only a `$ref` pointing inside the schema is allowed; references to the network or to files are rejected at registration. Objects and arrays in a schema may nest at most 100 levels deep (each object or array counts as one level, so one level of `properties` nesting takes two); deeper schemas raise `ConfigurationError` at registration.
+
+### Tools from functions
+
+```python
+from pi_python import tool
+
+@tool
+def search_papers(query: str, year: int | None = None, limit: int = 10) -> list[dict]:
+    """Search the paper index.
+
+    Args:
+        query: Keywords.
+        year: Only papers from this year.
+        limit: Maximum number of results.
+    """
+    ...
+```
+
+`@tool` turns a function into a `Tool`: the function name is the tool name, the first paragraph of the docstring is the description, the parameter types generate the input schema, and argument descriptions in Google, NumPy or Sphinx style go into the schema. You can also write `@tool(name=..., description=..., execution_mode=..., output_schema=...)`, or call `tool(fn)` on an existing function.
+
+Supported parameter types: `str`, `int`, `float`, `bool`, `None`, `list`, `set`, `tuple`, `dict[str, T]`, `Literal`, `Enum`, `Optional` and other unions, `Annotated[T, "description"]`, `TypedDict`, dataclasses, `datetime`, `date`, `UUID`, `Path`, and pydantic models. Before the call, the JSON arguments are converted to the types the function asks for, such as enum members, dates, dataclasses or pydantic models. A parameter annotated as `ToolContext` receives the call context and does not appear in the schema. `*args`, `**kwargs` and types that cannot be represented as JSON raise `ConfigurationError` at registration.
+
+Concurrency is unlimited by default: a batch of tools all run at once, as in Pi; set `RunLimits(max_concurrency=...)` when you need a cap. If any tool requires `sequential`, the whole batch runs one at a time. When running concurrently, preparation completes in call order before execution starts; end events follow the order in which post-processing finishes, and results in history follow call order.
+
+A standalone program can call `await run_tool_call(tool, call, context, before_tool_call=..., after_tool_call=...)` to reuse the same validation and hook path. For standalone calls, the program manages lifetime, timeouts and cancellation itself; `Agent` adds batch management and `RunLimits`.
+
+## Hooks
+
+Every hook can be a sync or an async function. Contexts and arguments are passed as copies; the cancel token and the tool-update channel are shared control interfaces.
+
+| Hook | Arguments and return value |
+|---|---|
+| `prepare_request(context, cancel)` | Returns a `TurnUpdate` or None; called before every model request |
+| `prepare_next_turn(context, cancel)` | Returns a `TurnUpdate` or None; called from the second turn on |
+| `transform_context(messages, cancel)` | Returns the message list used for the model request; runs before convert |
+| `convert_to_llm(messages)` | Returns the message list that can be sent to the model; must handle or explicitly filter out `CustomMessage` |
+| `before_tool_call(call, args, context)` | True / None allows, False blocks, or return a `ToolResult` to use without executing; if the hook raises, that call gets an error result (`hook_error`) and the run continues, as in Pi |
+| `after_tool_call(call, result, context)` | Returns a full `ToolResult`, a partial `ToolResultUpdate`, or None |
+| `finish_turn(context, cancel)` | Returns `"continue"`, `"end"` or None |
+
+For the preparation and finish hooks, `context` is a `RunContext` containing `messages`, `model`, `options`, `tools`, the latest `message` and `tool_results`. `TurnUpdate(model=..., options=..., tools=..., context=..., messages=...)` affects the rest of this run without changing the Agent's defaults. `context` replaces this run's model context without rewriting committed history; `messages` are new inputs to append. Only an explicit `update_config` changes the defaults for the next run. Options are replaced field by field as whole values, not deep-merged.
+
+When an after-hook replaces the text with `ToolResultUpdate(content=[...])`, the old `structured_content` is cleared; to keep it, supply new structured content at the same time. Successful results are checked against the output schema both before and after the after-hook. `terminate=True` suppresses the next request triggered by tools only if it holds for every final result in the batch; queued input can still trigger continuation. `finish_turn="end"` does not consume pending queues.
+
+## Cancellation, timeouts and events
+
+By default, `RunLimits` does not limit model requests, tool calls or tool concurrency, as in Pi; applications set `max_model_requests`, `max_tool_calls` and `max_concurrency` when they need them. The cleanup deadline defaults to 1 second. `tool_timeout` and `run_timeout` default to None and are measured on a monotonic clock. When a tool-call cap is set, it is checked before a batch starts; if the remaining allowance is not enough, none of the batch runs.
+
+An explicit `abort` ends the run the way Pi does. `abort` can be called from any thread, for example from a GUI stop button or a watchdog thread:
+
+- Cancellation goes through asyncio task cancellation and reaches the running model stream, tools and hooks, much like Pi's AbortSignal. Each operation ends in its own way within the cleanup deadline.
+- When the model stream is cancelled, the partial content already streamed is recorded as an answer with `stop_reason="aborted"`, and `finish_turn` and `turn_end` happen as usual.
+- When a tool is cancelled, it gets an ordinary error result, `Operation aborted` (`execution_status="cancelled"`). A result the tool returns itself after catching the cancellation is used as usual, and completed results are kept. After the whole batch is committed, as in Pi, one more turn begins: it sends no model request, records an aborted answer and ends.
+- `prompt` returns `status="cancelled"`, and the Agent remains usable.
+
+When the caller cancels the Python Task running `prompt`, the flow above does not apply: the library performs bounded cleanup and re-raises `asyncio.CancelledError`.
+
+When a run fails or is cancelled outside the model answer (for example, a preparation hook raises), an `error` / `aborted` answer is appended and `turn_end` is emitted, like Pi's `handleRunFailure`. A subscriber failure is the exception: publishing stops and nothing more is appended.
+
+A tool timeout likewise cancels that tool; the result is the error `tool_timeout`, which goes to the model, and the run continues.
+
+When a tool cannot confirm whether an external commit succeeded, it can raise `ToolOutcomeUnknownError`. This is a guard this library adds beyond Pi: it stops the current run and refuses later prompts, continues and configuration updates, so that the application can reconcile externally and create a new instance with corrected history. Cancellation and timeouts do not trigger this guard.
+
+Python cannot forcibly stop an uncooperative coroutine or the thread running a plain function. If a tool still has not finished by the cleanup deadline after cancellation or a timeout, its result is the error `not_stopped`, the run stops at once, and no more model requests are sent. Until the tool actually finishes, the instance stays busy: `cleanup_complete=False`, and `prompt`, `wait_for_idle` and `aclose` raise `CleanupTimeoutError`. As soon as the tool finishes, the instance becomes usable again. Applications that need to force termination should manage subprocesses themselves. A timeout or cancellation result does not mean the external operation was rolled back.
+
+Events are `agent_start/end`, `turn_start/end`, `message_start/update/end`, `tool_execution_start/update/end`, and `config_update` for explicit configuration changes. The envelope carries `schema_version=1`, the run ID, the turn ID, a monotonic sequence number and an optional call ID. Each subscriber receives its own copy. Subscribers are awaited in order; if one fails, execution stops, and `state.diagnostics` records the failing subscriber and those not yet called. The failing subscriber is not called again recursively.
+
+A subscriber callback must not wait for this instance to become idle, or it will end up waiting on itself. A display layer can use a bounded `EventQueue(maxsize=128, drop_text_updates=True)`: only message deltas may be dropped, the count is kept in `dropped_updates`, and final tool events always apply backpressure. On the normal path, `prompt` returning means the critical subscribers have handled the end events.
+
+## Recovering from failures
+
+When the model errors or is cancelled, the answer stays in history with `stop_reason="error"` or `"aborted"`, and its `error` field holds the original error text. HTTP failures also carry the response body returned by the server (at most 4000 characters, with the key used for this request replaced by `[redacted]`). The functions below are ported from upstream pi-ai. They read that answer to tell why it failed, and on 44 shared samples their verdicts match upstream:
+
+| Function | Purpose |
+|---|---|
+| `is_context_overflow(message, context_window=None)` | Whether it failed because the context was too long. Given the window size, it also recognizes silent overflow (reported input larger than the window) and a length stop with zero output after truncation |
+| `is_retryable_error(message)` | Whether it looks transient: overload, rate limit, 5xx, network interruption, stream ended early. Quota and billing problems do not count |
+| `is_recoverable_length(message, desired_max_output)` | A length stop with less output than the desired limit, which may be caused by context pressure |
+| `retry_delay(attempt, base=2.0, max_delay=60.0)` | Seconds to wait before retry number `attempt`, with exponential backoff |
+
+`continue_run()` retries the turn when the last answer failed or was cancelled and there is no queued input. The failed answer stays in history and is skipped when the history is replayed to the model. This differs from Pi, whose application layer deletes the failed answer before continuing. [examples/recovery.py](../examples/recovery.py) shows the full approach: on overflow, use `transform_context` to replace the earliest turns with a summary and continue; on a transient error, back off with `retry_delay` and continue.
+
+## Using it from plain scripts
+
+`agent.prompt_sync(...)`, `agent.continue_run_sync()` and the general `run_sync(awaitable)` block and run in plain scripts, so you do not have to write `asyncio.run` yourself. They share one background event loop, so connections cached by a Provider stay usable across calls. On Ctrl+C, the current run wraps up the way `abort` does, and then `KeyboardInterrupt` is raised.
+
+Where an event loop is already running (async programs, top-level await in Jupyter), these functions raise an error suggesting `await agent.prompt(...)` instead. Use one style per Agent: either only the blocking versions, or only await in your own event loop.
+
+## MCP tools
+
+```python
+from pi_python.mcp import connect_stdio
+
+async with connect_stdio("uvx", ["mcp-server-fetch"], prefix="web") as tools:
+    agent = Agent(provider=..., tools=tools)
+    await agent.prompt("Summarize https://example.org")
+```
+
+Requires `pip install 'pi-python-core[mcp]'` and works with the official MCP SDK 1.10 and later, including 2.x. `connect_stdio` starts a stdio MCP server and closes it when the `async with` block exits. If you already have a `ClientSession`, wrap its tools with `await mcp_tools(session, prefix=None, names=None)`. Conversion follows Pi's MCP adapter: text and images convert directly; embedded text or image resources are unpacked; audio, resource links and binary resources become short text descriptions; a result with only structured content becomes JSON text and is also kept as `structured_content`; MCP's `isError` becomes a tool error; progress notifications become `tool_execution_update` events. After the prefix is added, tool names keep only letters, digits, `_` and `-`, up to 64 characters. A tool whose schema cannot be used is skipped with a warning, without affecting the server's other tools. A stdio server written with Python MCP SDK 2.3 cannot start on PyPy (`fcntl.F_DUPFD_CLOEXEC` is missing); this is a limitation of the SDK itself, and the client side is unaffected.
+
+## Messages and encoding
+
+The public message types are `SystemMessage`, `UserMessage`, `AssistantMessage`, `ToolResultMessage` and `CustomMessage`; the content blocks are `TextContent`, `ImageContent`, `ThinkingContent` and `ToolCall`. User messages and tool results can carry images; assistant messages can carry signed text, reasoning and tool calls. A `SystemMessage`'s text appends instructions, and `sections` replaces sections by name (None deletes one); tool declarations are replayed through `tools_added` / `tools_removed`.
+
+`encode_messages` / `decode_messages` and `encode_event` / `decode_event` are pure string conversions; they do not read or write files. The message schema version is 3 and the event envelope version is 1; any other version is rejected. NaN, Infinity, functions and file handles are not accepted, and dangling calls, duplicate results and unknown versions are rejected. Importing history only validates data; it never runs the model or tools. External adapters can use `current_tools`, `current_system_message` and `current_system_prompt` to replay state.
+
+## Standalone loop and convenience APIs
+
+`agent_loop(prompts, AgentContext(...), AgentLoopConfig(...), cancel=None)` and `agent_loop_continue(context, config, cancel=None)` return an `AgentEventStream`, which supports `async for` and `await stream.result()`. `run_agent_loop(..., emit=None, cancel=None)` / `run_agent_loop_continue(...)` return the new messages directly and accept a sync or async event callback. They reuse the Agent's execution engine. The continue versions write history back into the context passed in; the prompt versions leave the original context unchanged, matching upstream.
+
+The configuration includes `provider` or `stream_fn`, `model`, `options`, `hooks`, `limits`, `tool_execution`, and `get_steering_messages` / `get_follow_up_messages`. The queue callbacks are called at the same boundaries as upstream and can return message lists synchronously or asynchronously.
+
+The event stream uses a bounded queue. If you only wait for the result, `result()` consumes the events; if you use `async for`, consume to the end before reading the result. To give up midway, call `await stream.aclose()`. Do not just wait for the producer to finish while you have paused consuming, or backpressure will block it.
+
+`set_default_stream_fn(provider_or_function)` sets an explicit process-wide default stream; pass None to clear it. `Agent` can then omit the provider, or use `stream_fn=`. `reset()` clears the conversation and queues but keeps the replayed system prompt and tool declarations; it is refused during a run. An instance whose tool reported an unknown outcome still has to be rebuilt after reconciliation; reset does not clear that guard.
+
+`has_queued_messages()`, `peek_queued_messages()`, `clear_steering_queue()`, `clear_follow_up_queue()` and `clear_all_queues()` correspond to upstream's convenience methods. Peeking prefers steering and previews follow-up only when steering is empty; it returns copies. `signal` returns the active `CancelToken` during a run and None when idle. `prompt(text, images=[...])` is a shortcut for sending images.
+
+An Agent can also be constructed with `thinking_level`, `thinking_budgets`, `transport`, `session_id`, `get_api_key`, `on_payload`, `on_response` and `on_provider_stream_event`. The last four can also go in Hooks; explicit constructor arguments take precedence. Their protocols, and the Provider parameters, are described in [the connector guide](PROVIDERS.md).
+
+## Fields of messages, tool results and events
+
+`SystemMessage.content` accepts a string or a list of text blocks. `AssistantMessage` also contains `response_model`, `response_id`, `thinking_level`, `diagnostics`, `raw_stop_reason`, `end_turn` and `deferred`. `provider_thinking_level` is the provider's native effort; `thinking_level` is the requested level. Fields whose value is null in arbitrary user JSON are preserved intact.
+
+`ToolResult`, `ToolResultUpdate` and the history's `ToolResultMessage` support `usage` and `nested_calls`; history also stores `details`. Nested-call records have the form `{complete: bool, calls: [{id, name, status, ...}]}`, where status is ok/error/unfinished. details, usage and nested_calls are stripped before anything is sent to the main model. Tool execution and after-hooks get assistant_message, agent_context, tool_call, args, result and is_error through `ToolContext`; `RunContext.new_messages` collects the messages added by this run. All of these contexts are copies.
+
+Among checked events, non-terminal events carry `partial` (an independent snapshot that does not change with the next event); block boundaries carry `block`, text/reasoning ends carry `content`, tool deltas carry that block's `call_id` and `name`, and terminal events carry `message` and `reason`. Tool-argument previews may be incomplete, but execution uses the strictly parsed final arguments. The data of the Agent's `message_update` event is `delta_type`, `block_index`, `delta`, `content`, `tool_call_id` and `partial`.
+
+OpenAI may add encrypted_content back in the final response. If the visible reasoning and the other signature fields are identical and only the missing encrypted content is added, the terminal message may carry that one extra field compared with the block-end snapshot. Text, arguments and tool identity must still match.
+
+## Mid-session changes and context estimation
+
+`render_system_update(message)` returns the text sent when a later system message is delivered in place: after the body, each section is written as `Updated system prompt section "name":` followed by the new content, or `Removed system prompt section "name".`. When a system message consists of several text blocks, the blocks are joined with a single newline, the same as upstream's `contentText`. How each Provider sends mid-session changes to tools, instructions and reasoning effort is described in [the connector guide](PROVIDERS.md#mid-session-changes).
+
+`estimate_context_tokens(messages)` ports upstream's character-based estimate: the latest valid usage record plus an estimate of the messages after it, at about 1 token per 4 UTF-16 characters, with each image counted as 4800 characters. It is not a tokenizer. `clamp_max_tokens_to_context(context_window, messages, max_tokens)` uses it to reserve 4096 safety tokens, with a result of at least 1; Providers use it to shorten the output limit of known models.
+
+`AssistantMessage.provider_thinking_level` matches upstream: it records this answer's effort only for Claude models that use effort markers, so later requests can rebuild the markers in history. Read `thinking_level` when you need the requested level.
+
+When replaying history, Providers skip `error` / `aborted` answers following upstream's rules; reasoning from a different model is converted to plain text and its signature is dropped; a system message that sits between a tool call and its result is moved after the result. The session history itself is unchanged.

pi_python_core-0.8.2/docs/CONCEPTS.md

@@ -0,0 +1,75 @@
+# pi-python on one page
+
+**English** | [中文](zh/CONCEPTS.md)
+
+This library does one thing: it repeatedly sends the conversation to a model, runs the tools the model asks for, and hands the results back to the model, until the model gives an answer. Understand the five concepts below and you can read all of the code.
+
+## Five concepts
+
+| Concept | What it is | Where |
+|---|---|---|
+| **Transcript** | An append-only list of messages: user input, model answers, tool results, and system messages. System instructions and tool declarations are written as system messages too, so every change made mid-conversation stays in the record | `messages.py`, `transcript.py` |
+| **Agent** | One conversation. It holds the transcript, the default configuration (model, options, tools), two input queues and the event subscribers. It runs one prompt at a time | `agent.py`, `queues.py` |
+| **Run** | One execution of `prompt` or `continue_run`. It holds that run's cancel token, background tasks and tool-execution records, and packages them as a `RunResult` at the end | `run.py`, `loop.py` |
+| **Provider** | A function that takes a request and produces a stream of model events, the last of which is the complete answer. The Agent does not know whether HTTP, WebSocket or a script is behind it | `provider.py`, `providers/` |
+| **Tool** | A name, a description, an argument schema and an execute function (async or plain). Usually generated with `@tool` from a type-annotated function. Arguments are strictly validated before execution, and the result is written back to the transcript | `tools.py`, `function_tools.py` |
+
+Model capabilities are not a sixth concept but an input to the Provider: `ModelInfo` records the context length, output limit, reasoning levels and server-side features. When you give a real Provider a model name, it looks the name up in the built-in model table; if the name is missing, it raises an error, and you pass a `ModelInfo` instead. The scripted `ScriptedProvider` needs no model table.
+
+## What happens in one turn
+
+```text
+prompt("…")
+  │
+  ▼
+Accept input (queued guidance; tool changes are written as system messages)
+  │
+  ▼
+pre-request hooks ─► transform_context ─► convert_to_llm
+  │
+  ▼
+Provider stream: start → for each content block start/delta/end → done
+  │            (events are checked first: blocks must pair up, deltas must land in an open block,
+  │             and the final answer must match the finished blocks; otherwise the turn fails and no tool runs)
+  ▼
+Answer written to the transcript
+  │
+  ├─ no tool calls ──► check the follow-up queue ──► end if it is empty
+  │
+  └─ tool calls ──► validate arguments → before_tool_call → execute → after_tool_call
+                     │
+                     ▼
+                  results written in call order ──► finish_turn ──► next turn
+```
+
+All hooks are optional. When the model errors or is cancelled, the answer (with whatever was already generated) is recorded in history as usual, just as in Pi; `finish_turn` and `turn_end` run, and then the run ends. The run also ends when it reaches a limit the application has set. `RunResult.status` says why it ended.
+
+## Minimal example
+
+```python
+from pi_python import Agent, AssistantMessage, ScriptedProvider, Tool, ToolCall, ToolResult
+
+async def add(args, context):
+    return ToolResult.text(str(args["a"] + args["b"]))
+
+provider = ScriptedProvider([
+    AssistantMessage([ToolCall("c1", "add", {"a": 2, "b": 3})], "tool_use"),
+    AssistantMessage.text("5"),
+])
+schema = {"type": "object", "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}},
+          "required": ["a", "b"], "additionalProperties": False}
+result = await Agent(provider=provider, tools=[Tool("add", "Add", schema, add)]).prompt("2+3?")
+```
+
+To use a real model, change only the Provider and the model name: `Agent(provider=AnthropicProvider(api_key=...), model="claude-sonnet-5-5", ...)`.
+
+## What goes beyond Pi
+
+Pi leaves the following to applications; this library puts them in the core for research and HPC use. Read about them when you need them:
+
+- Strict argument validation, with no automatic conversion of strings to numbers (write `prepare_arguments` if you need it);
+- `RunLimits`: the cleanup deadline after cancellation, plus optional caps on model requests, tool calls and tool concurrency, a tool timeout and a total run time (none of these caps is set by default; as in Pi, the application decides);
+- When a tool reports that its outcome is "unknown" (for example, the connection dropped after a job was submitted), the run stops and waits for the application to reconcile, with no automatic retry. Cancelling a tool, or a tool timing out, does not trigger this guard; it is recorded as an ordinary error result;
+- State returned to callers is always a copy, and configuration updates made during a run take effect at the next turn.
+
+Details are in the [API](API.md); model connectors (including local models) are in [PROVIDERS](PROVIDERS.md); the item-by-item comparison with Pi is in the [coverage map](../compat/COVERAGE.md) (Chinese). Common patterns for building fuller agents all have runnable examples: [sub-agents](../examples/subagent.py), [saving and restoring conversations](../examples/save_restore.py), [compaction on overflow and retry on errors](../examples/recovery.py), [MCP tools](../examples/mcp_tools.py), [local models](../examples/local_model.py).

{pi_python_core-0.8.1 → pi_python_core-0.8.2}/docs/IMPLEMENTATION.md

@@ -28,9 +28,11 @@
 
 0.8.0 发布时 macOS 和 Windows 还没有实际运行过。之后 CI 在 GitHub 上首次运行，发现了 Windows 和 PyPy 上的问题；0.8.1 只包含这些修复，见[验收映射](../compat/COVERAGE.md#081-跨平台修复)。
 
+0.8.2 调整了安装选项，执行行为没有变化：`httpx` 和 `websockets` 成为默认依赖，`pip install pi-python-core` 装完即可连接模型；只有 ChatGPT 账号登录需要的 PyJWT 放进 `[oauth]`，`[providers]` 保留为它的别名，缺少时报错会写明要装哪个选项。用户文档改为中英双语：英文是默认版本，中文在 `README.zh-CN.md` 和 `docs/zh/`；验证记录仍只有中文。
+
 ## 复现与验证附录
 
-- 说明文档：[一页概念](CONCEPTS.md)、[API](API.md)、[模型接入与本地模型](PROVIDERS.md)、[验收映射](../compat/COVERAGE.md)
+- 说明文档：[一页概念](zh/CONCEPTS.md)、[API](zh/API.md)、[模型接入与本地模型](zh/PROVIDERS.md)、[验收映射](../compat/COVERAGE.md)
 - 全部检查命令与输出：[verification.json](../compat/results/verification.json)，命令 `uv run python scripts/verify.py`
 - 差分结果：[核心](../compat/results/conformance.json)、[Provider](../compat/results/provider-conformance.json)、[WebSocket 多轮](../compat/results/websocket-conformance.json)、[出错判断](../compat/results/recovery-conformance.upstream.json)
 - Linux 安装：[3.11](../compat/results/linux-3.11.json)、[3.12](../compat/results/linux-3.12.json)、[3.13](../compat/results/linux-3.13.json)、[3.14](../compat/results/linux-3.14.json)，命令 `uv run python scripts/linux_verify.py`