pi-python-core 0.8.1__tar.gz

pi_python_core-0.8.1/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+build/
+dist/
+reference/pi/
+reference/node_modules/
+.wheelhouse/
+.pipilot/
+.provcheck/
+.claude/
+.codex/
+.agents/
+pi-python-core-design/

pi_python_core-0.8.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pi_python_core-0.8.1/NOTICE

@@ -0,0 +1,8 @@
+pi-python-core is an independent Python implementation, not an official Pi release.
+Agent execution and transcript behavior are adapted from earendil-works/pi:
+https://github.com/earendil-works/pi/tree/a13d35a742c6ef8462812a28fbe1d8c8b7431c32
+Copyright (c) 2025 Mario Zechner. MIT license; see LICENSE.
+The complete upstream source is fetched only for development under reference/pi.
+Provider request conversion (Claude Messages, OpenAI and Codex Responses), the cached
+WebSocket continuation, transcript replay helpers and the context estimate/shortHash in
+src/pi_python/estimate.py are adapted from packages/ai of the same commit.

pi_python_core-0.8.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: pi-python-core
+Version: 0.8.1
+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: jsonschema<5,>=4.18
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.10; extra == 'mcp'
+Provides-Extra: providers
+Requires-Dist: httpx<1,>=0.27; extra == 'providers'
+Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'providers'
+Requires-Dist: websockets>=14.2; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# pi-python-core
+
+一个可嵌入的 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。
+
+## 安装
+
+支持 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]'
+```
+
+安装名是 `pi-python-core`，导入名是 `pi_python`。
+
+| 安装选项 | 带来什么 |
+|---|---|
+| 不加选项 | 执行核心，只依赖 `jsonschema` |
+| `[providers]` | 真实模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
+| `[mcp]` | 把 MCP 服务器的工具交给 agent |
+
+依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
+
+## 五分钟上手
+
+```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` 从函数签名和文档字符串生成工具；普通函数和 `async` 函数都可以。在异步程序里用 `await agent.prompt(...)`。换成本地模型只改两行：
+
+```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])
+```
+
+不联网也能先跑起来：`python examples/quickstart.py`。
+
+## 能做什么
+
+| 需要 | 怎么做 | 示例 |
+|---|---|---|
+| 写工具 | `@tool` 装饰普通函数；pydantic 模型、dataclass、枚举、日期等参数自动转换；也接受手写或 MCP 生成的 JSON Schema | [quickstart](examples/quickstart.py) |
+| 接模型 | Claude 与 GPT 的 API key 或订阅登录；DeepSeek；任何 OpenAI 兼容服务 | [local_model](examples/local_model.py)，[provider_chat](examples/provider_chat.py) |
+| 用 MCP 工具 | `async with connect_stdio(...) as tools` | [mcp_tools](examples/mcp_tools.py) |
+| 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去 | [subagent](examples/subagent.py) |
+| 中途干预 | `steer` 插入指导，`follow_up` 排队后续任务，`abort` 随时取消（任何线程都可以调用） | |
+| 上下文满了、服务出错 | `is_context_overflow`、`is_retryable_error` 判断原因，`continue_run()` 重试，`transform_context` 压缩 | [recovery](examples/recovery.py) |
+| 保存与恢复对话 | `encode_messages` / `decode_messages`，应用决定存在哪里 | [save_restore](examples/save_restore.py) |
+| 观察与审计 | 订阅事件；执行前后的钩子可以阻止、改写工具调用 | |
+
+除 `provider_chat` 需要真实凭据外，示例都能离线运行，不需要 API key；测试会逐个运行它们。
+
+## 与 Pi 的关系
+
+执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。
+
+有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。本项目使用自己的版本号，并非 Pi 官方发行版。
+
+## 文档
+
+- [一页看懂：五个概念和一轮的流程](docs/CONCEPTS.md)
+- [公开 API](docs/API.md)
+- [模型接入、订阅登录与本地模型](docs/PROVIDERS.md)
+- [实施与验证结果](docs/IMPLEMENTATION.md)
+- [与 Pi 的逐项对照和有意差异](compat/COVERAGE.md)
+- [参照重建与候选版本验证](reference/README.md)
+
+## 开发
+
+```bash
+uv sync --locked --extra providers --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # 全部检查，含与上游的差分（需要 Node）
+```
+
+CI 配置在 `.github/workflows/ci.yml`，每次推送都在 GitHub Actions 上运行，覆盖 Linux 上的各个 Python 版本（含 3.14t 和 PyPy）以及 macOS 和 Windows。

pi_python_core-0.8.1/README.md

@@ -0,0 +1,90 @@
+# pi-python-core
+
+一个可嵌入的 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。
+
+## 安装
+
+支持 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]'
+```
+
+安装名是 `pi-python-core`，导入名是 `pi_python`。
+
+| 安装选项 | 带来什么 |
+|---|---|
+| 不加选项 | 执行核心，只依赖 `jsonschema` |
+| `[providers]` | 真实模型接入：Claude、OpenAI、Codex、DeepSeek，以及任何 OpenAI 兼容服务（Ollama、vLLM、llama.cpp 等） |
+| `[mcp]` | 把 MCP 服务器的工具交给 agent |
+
+依赖写的是版本范围而不是固定版本，能和大多数已有环境共存。
+
+## 五分钟上手
+
+```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` 从函数签名和文档字符串生成工具；普通函数和 `async` 函数都可以。在异步程序里用 `await agent.prompt(...)`。换成本地模型只改两行：
+
+```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])
+```
+
+不联网也能先跑起来：`python examples/quickstart.py`。
+
+## 能做什么
+
+| 需要 | 怎么做 | 示例 |
+|---|---|---|
+| 写工具 | `@tool` 装饰普通函数；pydantic 模型、dataclass、枚举、日期等参数自动转换；也接受手写或 MCP 生成的 JSON Schema | [quickstart](examples/quickstart.py) |
+| 接模型 | Claude 与 GPT 的 API key 或订阅登录；DeepSeek；任何 OpenAI 兼容服务 | [local_model](examples/local_model.py)，[provider_chat](examples/provider_chat.py) |
+| 用 MCP 工具 | `async with connect_stdio(...) as tools` | [mcp_tools](examples/mcp_tools.py) |
+| 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去 | [subagent](examples/subagent.py) |
+| 中途干预 | `steer` 插入指导，`follow_up` 排队后续任务，`abort` 随时取消（任何线程都可以调用） | |
+| 上下文满了、服务出错 | `is_context_overflow`、`is_retryable_error` 判断原因，`continue_run()` 重试，`transform_context` 压缩 | [recovery](examples/recovery.py) |
+| 保存与恢复对话 | `encode_messages` / `decode_messages`，应用决定存在哪里 | [save_restore](examples/save_restore.py) |
+| 观察与审计 | 订阅事件；执行前后的钩子可以阻止、改写工具调用 | |
+
+除 `provider_chat` 需要真实凭据外，示例都能离线运行，不需要 API key；测试会逐个运行它们。
+
+## 与 Pi 的关系
+
+执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。
+
+有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 `@tool`、同步调用、失败后直接 `continue_run()`。逐项记录见[验收映射](compat/COVERAGE.md)。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。本项目使用自己的版本号，并非 Pi 官方发行版。
+
+## 文档
+
+- [一页看懂：五个概念和一轮的流程](docs/CONCEPTS.md)
+- [公开 API](docs/API.md)
+- [模型接入、订阅登录与本地模型](docs/PROVIDERS.md)
+- [实施与验证结果](docs/IMPLEMENTATION.md)
+- [与 Pi 的逐项对照和有意差异](compat/COVERAGE.md)
+- [参照重建与候选版本验证](reference/README.md)
+
+## 开发
+
+```bash
+uv sync --locked --extra providers --extra mcp
+uv run pytest -q
+uv run python scripts/verify.py      # 全部检查，含与上游的差分（需要 Node）
+```
+
+CI 配置在 `.github/workflows/ci.yml`，每次推送都在 GitHub Actions 上运行，覆盖 Linux 上的各个 Python 版本（含 3.14t 和 PyPy）以及 macOS 和 Windows。

pi_python_core-0.8.1/compat/COVERAGE.md

@@ -0,0 +1,119 @@
+# 验收映射
+
+首期测试证明的是本文列出的文本和工具行为，不是完整 Pi 或模型智能。27 行是设计中的用例组，不是 27 个单独测试。具体测试总数与命令见 [验证记录](results/verification.json)，逐 fixture 结果见 [差分记录](results/conformance.json)。
+
+| 用例组 | Python 行为证据 | 上游证据 / 分类 |
+|---|---|---|
+| C01 文本与增量 | test_C01_stream_and_end | C01-text，mapped；增量一致性另作 D7 合同 |
+| C02 工具结果进入请求 | test_C02_result_in_next_request_and_private_details | C02-tool，mapped |
+| C03 串行顺序 | test_C03_C05_serial_batch | C03-sequential，mapped |
+| C04 并发结束与提交顺序 | 两个 test_C04 测试，分别屏障控制执行与后置钩子 | C04-parallel，mapped |
+| C05 任一串行影响整批 | test_C03_C05_serial_batch | C05-one-sequential，mapped |
+| C06 普通失败保留同批成功 | test_C06_failure_does_not_cancel_sibling | C06-one-failure，mapped |
+| C07 未知工具和非法参数 | test_C07_C08_D1_D2 与 schema 拒绝测试 | C07-unknown，mapped；严格验证为 D1 |
+| C08 先准备再验证 | test_C07_C08_D1_D2 | C08-prepare，mapped |
+| C09 阻止、替换和清除结构化结果 | test_C09_block_and_clear_structure；执行前钩子抛错见 test_failing_before_hook_is_a_tool_error_not_a_rejection | C09-block / C09-replace / C09-before-error，mapped；上游独立结构化替换测试通过 |
+| C10 长度截断零执行 | test_C10_truncation_all_tools_fail_without_execution | C10-length，mapped |
+| C11 transform 先于 convert | test_C11_transform_before_convert_defensive_copies | C11-transform，mapped；复制隔离为 D5 |
+| C12 系统与工具声明重放 | test_C12_system_replay / runtime_tool_declarations_track_config | C12-system，mapped；上游 transcript-tool-changes 测试通过 |
+| C13 指导的注入时点 | test_C13_C14_queues_and_modes | C13-steering，mapped |
+| C14 后续队列与消费模式 | test_C13_C14_queues_and_modes | C14-followup-one / all，mapped |
+| C15 准备钩子与配置持续 | 两个 test_C15 测试 | C15-prepare，mapped |
+| C16 停止与继续 | 参数化 test_C16 与错误结束测试 | C16-mixed / terminate / continue / end，mapped |
+| C17 重复请求和继续边界 | test_C17_busy_and_continue / continue_queued_final... | 上游 agent.test 中 prompt/continue 用例通过；Python API 映射测试 |
+| C18 订阅后空闲和故障 | 三个 test_C18、结束订阅取消测试 | 上游 agent.test 的异步 listener/idle 用例通过；故障诊断为 D7 |
+| C19 两种取消语义 | 参数化 test_C19、调度前取消测试、test_C20_abort_mid_stream_finishes_the_turn_with_partial_content | 显式 abort：C19-abort-stream / C19-abort-tools，mapped；外部 Task 取消为 D4 |
+| C20 已完成保留、取消不锁定、显式未知不重放 | test_C20_abort_running_tool_is_an_error_result_and_agent_stays_usable、test_C20_explicit_unknown_stops_current_run 和后置阶段取消测试 | 取消运行中工具：C19-abort-tools，mapped；显式未知为 D4 |
+| C21 超时、清理和上限 | 六个 test_C21（含默认不设上限）、延迟成功不得覆盖超时测试 | intentional_difference，D3/D4 |
+| C22 原始执行和整理失败 | 参数化 test_C22 | intentional_difference，D6/D7 |
+| C23 配置隔离和环境 | test_C15_C23 / test_C23_no_implicit_environment_configuration | intentional_difference，D5；运行更新持续另在 C15 差分 |
+| C24 损坏流和能力拒绝 | 参数化 test_C24、尾部异常测试、两组 Provider 中途失败测试 | 供应商中途出错：C24-provider-error，mapped；损坏流拒绝为 D7/D8 |
+| C25 JSON、版本、导入 | 两个 test_C25、事件编解码 | Python 合同；没有持久化或导入后自动执行 |
+| C26 release 候选 | test_C26_noop_duplicate_and_synthetic_upgrade 及参数化拒绝测试 | 合成接口演练；独立远端校验脚本另存实际记录 |
+| C27 wheel 安装 | Linux 容器内断网安装、示例、全部 pytest | 实际组合见 linux-3.11/3.12/3.13.json |
+
+## 有意差异与范围外行为
+
+D1–D8 保持原设计的含义。D1 严格输入；D2 执行前钩子不能通过原地修改参数改变调用；D3 资源预算；D4 Python 取消及未知结果；D5 状态复制；D6 输出检查；D7 诊断、原始结果和完整流校验；D8 文本与工具子集。每项有独立 Python 断言，不以 skip 代替验收。
+
+范围外项目：真实模型 SDK、图片/音频/专有推理、OAuth、MCP 客户端、TUI/CLI、持久化与崩溃恢复、子 agent 管理器、Slurm/PBS，以及真实 HPC/科研任务效果。模型侧不支持的内容显式拒绝。上游真实模型 e2e、代理和其他应用测试未运行；它们不计入通过数。
+
+## 已知验收边界
+
+共享对照是 25 个脚本输入（0.5 时为 21 个）。上游 97 项选定单元测试证明参照可运行；它们不等价于 97 个 Python 差分输入。完整上游 API 和未覆盖输入没有兼容保证。无待解释的共享 fixture 差异；后续增加行为时，应扩充 fixture 再扩大声明。
+
+## 0.2 范围修订
+
+上述“首期范围外”是 0.1 的历史边界。根据用户追加要求，0.2 已将图片、供应商推理、Claude/OpenAI Provider、OAuth、streamProxy、独立循环和便利 API 纳入实现，D8 相应扩大。D1–D7 保持。
+
+新增 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 保留为历史核心验收记录，新增能力单独记录，不修改固定上游提交。
+
+## 0.3 范围修订
+
+当前数据合同使用 schema 3，支持完整文本/推理/工具块事件、模型诊断与响应元数据、工具 details/usage/nested_calls、系统文本块和完整工具钩子上下文。新增测试见 `test_contract_v3.py`。D8 再次扩大；D1 严格校验、D5 状态副本、D4/D7 未知结果不重放继续保留，不能列为缺失功能。
+
+Provider 差分从 8 组扩大到 22 组，增加完整请求体、语义请求头和事件顺序/载荷，包含 Codex、签名重放、图片、工具 schema、缓存与推理参数。`test_models.py` 验证能力表，`test_recovery.py` 验证重试边界、取消、握手回退、账号隔离、连接复用和重复响应头。真实联调及未覆盖项以 [当前实施报告](../docs/IMPLEMENTATION.md) 为准；上面的 0.1/0.2 范围描述仅作历史记录。
+
+## 0.4 范围修订
+
+请求转换改为逐项移植上游 `buildParams`、`convertMessages`、`convertResponsesMessages` 和 Codex 请求体构造，并按模型表能力原位发送会话中途的系统指令、工具增删和推理强度。新增 12 组 Provider 差分使用真实模型记录和上游 `streamSimple` 入口，旧 22 组保持通过；新增 2 组 WebSocket 多轮差分对照增量请求和一次性重试。Python 合同见 `test_session_changes.py` 与 `test_websocket_continuation.py`。上游 `anthropic-mid-conversation-effort` 与 `openai-codex-stream` 测试加入参照验证。
+
+D1–D8 不变。本轮明确记录的差异：WebSocket 帧不带 `stream` 字段；请求发出后的 WebSocket 故障不回退 SSE；同一会话的并发请求排队而不是另开一次性连接；Claude 推理预算不足 1024 时报配置错误而不是发送 1024；直接 OpenAI API 的 WebSocket 不使用增量请求（上游无此路径）。
+
+## 0.5 结构修订
+
+0.5 不改变执行行为，只减少并存的写法：Provider 事件只保留与上游相同的一套（`done` 取代 `final`，工具参数增量按块位置），所有 Provider 的事件经同一个检查器；模型能力只来自 `ModelInfo`，表外模型名在真实 Provider 中报错。旧的 20 组 Provider 输入改走上游 `streamSimple` 入口并使用与运行器相同的 `test-model` 记录，与 Agent 的实际调用路径一致；两组重放输入的历史回答补上了上游必需的 `usage` 字段。`agent.py` 拆为会话（Agent）、一次运行（Run）和输入队列三部分。核心 21 组、Provider 34 组、WebSocket 2 组差分保持通过。
+
+## 0.6 修订：失败与取消对齐 Pi
+
+检查发现三处没有写进文档的偏差，现已按上游改正，并各补一组差分：
+
+| 情况 | 改正前 | 现在（与上游相同） | 差分 |
+|---|---|---|---|
+| 模型流中途出错 | 换成一条空的失败消息，供应商和模型名是 `mock`，已流出的内容和用量丢失 | 提交供应商给的失败消息，保留部分内容、身份和错误文字；`message_start` 只发一次 | C24-provider-error |
+| 模型流中途被取消 | 不调用 `finish_turn`、不发 `turn_end`、不留回答 | 记一条 aborted 回答，照常调用 `finish_turn` 并发出 `turn_end` | C19-abort-stream |
+| `before_tool_call` 抛异常 | 整个运行失败 | 该调用得到错误结果，模型继续 | C09-before-error |
+
+同时改了两项设计选择：
+- 取消运行中的工具按 Pi 处理：工具得到 `Operation aborted` 错误结果，批次收尾后再记一条不发请求的 aborted 回答，Agent 仍可使用（差分 C19-abort-tools）。工具超时同样记为错误结果，运行继续。只有工具主动抛 `ToolOutcomeUnknownError` 才停止运行并锁定实例。
+- `RunLimits` 的模型请求数、工具调用数和工具并发数默认都不设上限，由应用设置；同一批工具默认全部同时执行，与上游的 `Promise.all` 相同。
+
+为此扩展了两个运行器：响应可以先流出文本再失败或等待取消，操作可以是 `abort`，工具可以等到取消，执行前钩子可以抛错，`finish_turn` 调用被记录。比较规则新增一条映射：流式回答开始时的 `message_start` 不比较结束原因（上游此时为 `stop`，Python 为 `pending`）；流中的部分快照不比较，只比较提交的消息。旧的 21 组输入未改，只有两组带 `finish_turn` 的结果多记录了这个钩子。
+
+仍保留的取消差异，都在 Python 边界上：
+- 外部取消 `prompt` 的 Task 时立即退出并重新抛 `CancelledError`，不追加 aborted 回答。
+- 取消送达后最多等清理期限（默认 1 秒）；逾期仍在运行的工具得到 `not_stopped` 结果，运行立即停止，实例不可再用。上游会一直等待工具结束。
+- 串行批次或准备阶段被取消时，上游不给尚未准备的调用产生结果；本库为每个调用都产生 `Operation aborted` 结果，保持历史中没有悬空调用。
+- 被取消的工具不调用 `after_tool_call`；上游会带着错误结果调用它。
+
+## 0.7 修订：易用性与通用性
+
+这一轮的目标是好装、多版本可用、容易在上面搭完整的 agent。按与上游的关系分三类记录。
+
+与上游一致，并有对照证据：
+- **Chat Completions 接入**：逐项移植 `openai-completions.ts`，新增 16 组 Provider 差分（Provider 差分共 50 组），覆盖 Ollama、vLLM、llama.cpp、OpenRouter、DeepSeek 等兼容配置和全部 11 种推理参数格式。与上游的差异见 [PROVIDERS](../docs/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]`。
+
+Python 新增，上游核心没有对应：
+- `@tool` 从带类型标注的函数生成工具；普通函数在工作线程运行；工具返回值自动转换。
+- `prompt_sync`、`continue_run_sync`、`run_sync`：共享后台事件循环的阻塞调用。
+- 最后一条回答失败或被取消时，`continue_run()` 直接重试。上游核心在这种情况下拒绝继续，Pi 的应用层先删掉失败回答再继续；本库保留失败回答，重放时跳过它。
+- MCP 适配 `pi_python.mcp`。上游把 MCP 客户端放在独立包 pi-mcp，包装成工具的做法写在示例里；本库作为可选依赖 `[mcp]` 提供，内容转换规则与上游示例相同。
+- `abort()` 可在任何线程调用；超过清理期限仍在运行的工具结束后，实例自动恢复可用；没有配置 Provider 时直接报错。
+
+已知差异：
+- 准备钩子抛错时，事件里会出现一个没有对应 `turn_start` 的 `turn_end`。上游 `handleRunFailure` 也是这样，保持一致。
+- Python 和 JavaScript 的正则方言有细微差别，个别 `pattern` 的判断可能不同。
+
+验证（0.7.0 发布时）：Python 测试 308 项；核心差分 25 组、Provider 差分 50 组、WebSocket 差分 2 组、出错判断 44 条，全部与上游一致。Docker 内 Python 3.11–3.14 断网安装 wheel，各 304 项通过（4 项 MCP 测试因锁文件不含 MCP SDK 而跳过）；本机安装后 3.14t 308 项、PyPy 3.11 304 项通过。依赖取最低版本（jsonschema 4.18、httpx 0.27、websockets 14.2、PyJWT 2.8）和最新版本都通过；MCP 适配在 SDK 1.10（它要求 jsonschema 4.20 以上）和 2.3 上都测过。macOS 和 Windows 只写进了 CI 配置，还没有实际运行；本机也没有运行中的本地模型服务，Chat Completions 接入尚未连接真实服务器。
+
+## 0.8.1 跨平台修复
+
+CI 第一次在 GitHub 上运行，Linux 和 macOS 全部通过，另外发现两处只在特定平台出现的问题：
+
+- **Windows 读错文本文件。** Windows 默认按 cp1252 读文本，含中文的测试数据被读坏。库、compat、测试和示例里的文本读写现在都明确使用 UTF-8；库读取内置模型表时也一样（该文件目前全是 ASCII，以前没有出错）。凭据文件 `0o600` 权限的检查只在 POSIX 上进行，Windows 没有这种权限位。
+- **PyPy 在极深的 schema 上崩溃。** 以前靠 `RecursionError` 拒绝嵌套过深的工具 schema。CPython 上实际上限随 schema 写法变化（`anyOf` 嵌套 81 层，`items` 嵌套 122 层），PyPy 的 JIT 偶尔在报错之前就撑爆底层栈，进程段错误退出。现在注册时先用非递归方式计数，对象和数组嵌套超过 100 层就报 `ConfigurationError`，在所有解释器上相同。上游 Pi 没有这项限制，属于本库新增的差异。代价是：嵌套超过 100 层、以前在 CPython 上能通过的 schema 现在被拒绝。以前子 schema 的嵌套最多能到 197 层，`default`、`const` 等数据值里的嵌套能到约 1000 层。

pi_python_core-0.8.1/compat/__init__.py

@@ -0,0 +1 @@
+"""Development-only upstream verification. Not imported by the runtime package."""

pi_python_core-0.8.1/compat/baseline.json

@@ -0,0 +1,32 @@
+{
+  "schema_version": 1,
+  "status": "accepted",
+  "scope": "core-text-tools-v1",
+  "repository": "https://github.com/earendil-works/pi",
+  "release": {
+    "tag": "v1.0.0",
+    "commit": "a13d35a742c6ef8462812a28fbe1d8c8b7431c32"
+  },
+  "python_package_version": "0.1.0",
+  "qualification": "Acceptance covers declared fixtures and Python contracts; not complete Pi API compatibility.",
+  "evidence": {
+    "source": "results/source-verification.json",
+    "conformance": "results/conformance.json",
+    "checks": "results/verification.json",
+    "linux": [
+      "results/linux-3.11.json",
+      "results/linux-3.12.json",
+      "results/linux-3.13.json"
+    ]
+  },
+  "intentional_differences": [
+    "D1",
+    "D2",
+    "D3",
+    "D4",
+    "D5",
+    "D6",
+    "D7",
+    "D8"
+  ]
+}

pi_python_core-0.8.1/compat/contracts/release-candidate.example.json

@@ -0,0 +1,21 @@
+{
+  "schema_version": 1,
+  "candidate_id": "2729621761edb139a0fe2a185cb05b7e524e20338d759a79cd1c4404d995b271",
+  "repository": "https://github.com/earendil-works/pi",
+  "detected_at": "2026-10-02T00:00:00Z",
+  "base": {
+    "tag": "v1.0.0",
+    "commit": "a13d35a742c6ef8462812a28fbe1d8c8b7431c32"
+  },
+  "target": {
+    "tag": "v1.0.0",
+    "commit": "a13d35a742c6ef8462812a28fbe1d8c8b7431c32",
+    "published_at": "2026-10-01T19:20:55Z",
+    "release_url": "https://github.com/earendil-works/pi/releases/tag/v1.0.0",
+    "draft": false,
+    "prerelease": false
+  },
+  "changed_files": [],
+  "affected_areas": [],
+  "producer": "接口形状示例；目标等于基线，接收后应判为无需操作"
+}

pi_python_core-0.8.1/compat/contracts/release-candidate.schema.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Pi release 候选接口",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "candidate_id",
+    "repository",
+    "detected_at",
+    "base",
+    "target",
+    "changed_files",
+    "affected_areas"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "candidate_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "repository": {
+      "const": "https://github.com/earendil-works/pi"
+    },
+    "detected_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "base": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tag",
+        "commit"
+      ],
+      "properties": {
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tag",
+        "commit",
+        "published_at",
+        "release_url",
+        "draft",
+        "prerelease"
+      ],
+      "properties": {
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        },
+        "published_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "release_url": {
+          "type": "string",
+          "pattern": "^https://github\\.com/earendil-works/pi/releases/tag/[^/]+$"
+        },
+        "draft": {
+          "const": false
+        },
+        "prerelease": {
+          "const": false
+        }
+      }
+    },
+    "changed_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "change",
+          "sha256_before",
+          "sha256_after"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+          },
+          "previous_path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+          },
+          "change": {
+            "enum": [
+              "added",
+              "modified",
+              "deleted",
+              "renamed"
+            ]
+          },
+          "sha256_before": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "sha256_after": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^[0-9a-f]{64}$"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        }
+      }
+    },
+    "affected_areas": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "agent_core",
+          "message_types",
+          "transcript",
+          "validation",
+          "dependencies",
+          "out_of_scope",
+          "unknown"
+        ]
+      }
+    },
+    "release_notes": {
+      "type": "string"
+    },
+    "producer": {
+      "type": "string"
+    }
+  }
+}