pi-python-core 0.8.1__py3-none-any.whl

pi_python/transcript.py

@@ -0,0 +1,167 @@
+"""System replay adapted from Pi a13d35a (MIT); see NOTICE."""
+
+from copy import deepcopy
+from .messages import Message, SystemMessage, TextContent, ToolDeclaration
+
+
+def system_text(content: str | list[TextContent]) -> str:
+    """Pi's contentText: text blocks of one message joined by a single newline."""
+    return content if isinstance(content, str) else "\n".join(b.text for b in content)
+
+
+def system_message_text(message: SystemMessage) -> str:
+    """A complete prompt: content followed by the sections that are set."""
+    parts = [system_text(message.content), *(v for v in message.sections.values() if v is not None)]
+    return "\n\n".join(p for p in parts if p)
+
+
+def render_system_update(message: SystemMessage) -> str:
+    """A later system message as sent in place; section changes are framed by name."""
+    parts = [system_text(message.content)] if system_text(message.content) else []
+    for name, value in message.sections.items():
+        parts.append(
+            f'Removed system prompt section "{name}".'
+            if value is None
+            else f'Updated system prompt section "{name}":\n\n{value}'
+        )
+    return "\n\n".join(parts)
+
+
+def current_tools(messages: list[Message]) -> list[ToolDeclaration]:
+    tools: dict[str, ToolDeclaration] = {}
+    for m in messages:
+        if isinstance(m, SystemMessage):
+            for name in m.tools_removed:
+                tools.pop(name, None)
+            for tool in m.tools_added:
+                tools[tool.name] = tool
+    return deepcopy(list(tools.values()))
+
+
+def current_system_message(messages: list[Message]) -> SystemMessage | None:
+    systems = [m for m in messages if isinstance(m, SystemMessage)]
+    if not systems:
+        return None
+    sections: dict[str, str | None] = {}
+    for m in systems:
+        for name, text in m.sections.items():
+            if text is None:
+                sections.pop(name, None)
+            else:
+                sections[name] = text
+    return SystemMessage(
+        "\n\n".join(system_text(m.content) for m in systems if system_text(m.content)),
+        sections,
+        current_tools(messages),
+        timestamp=systems[0].timestamp,
+    )
+
+
+def current_system_prompt(messages: list[Message]) -> str:
+    m = current_system_message(messages)
+    return system_message_text(m) if m else ""
+
+
+def initial_system_message(messages: list[Message]) -> SystemMessage | None:
+    return messages[0] if messages and isinstance(messages[0], SystemMessage) else None
+
+
+def collapse_system_messages(messages: list[Message]) -> list[Message]:
+    """For APIs without mid-conversation system messages: one replayed leading message."""
+    head = current_system_message(messages)
+    rest: list[Message] = [deepcopy(m) for m in messages if not isinstance(m, SystemMessage)]
+    return [head, *rest] if head else rest
+
+
+def resolve_transcript(messages: list[Message], mid_conversation: bool) -> list[Message]:
+    return deepcopy(messages) if mid_conversation else collapse_system_messages(messages)
+
+
+def declared_tools(messages: list[Message]) -> list[ToolDeclaration]:
+    """Every definition referenced by transcript tool state, in first-declaration order."""
+    tools: dict[str, ToolDeclaration] = {}
+    for m in messages:
+        if isinstance(m, SystemMessage):
+            for tool in m.tools_added:
+                tools[tool.name] = tool
+    return deepcopy(list(tools.values()))
+
+
+def has_tool_redefinitions(messages: list[Message]) -> bool:
+    """A name declared twice with different definitions cannot be referenced by name."""
+    seen: dict[str, ToolDeclaration] = {}
+    for m in messages:
+        if isinstance(m, SystemMessage):
+            for tool in m.tools_added:
+                if tool.name in seen and seen[tool.name] != tool:
+                    return True
+                seen[tool.name] = tool
+    return False
+
+
+def has_non_additive_tool_changes(messages: list[Message]) -> bool:
+    """A removal or same-name redeclaration that an addition-only transport cannot replay."""
+    seen: set[str] = set()
+    for m in messages:
+        if isinstance(m, SystemMessage):
+            if m.tools_removed:
+                return True
+            for tool in m.tools_added:
+                if tool.name in seen:
+                    return True
+                seen.add(tool.name)
+    return False
+
+
+def resolve_transcript_tools(
+    messages: list[Message], supports_additions: bool
+) -> tuple[list[ToolDeclaration], bool]:
+    """Top-level request tools, and whether later additions are anchored in place."""
+    anchors = supports_additions and not has_non_additive_tool_changes(messages)
+    initial = initial_system_message(messages)
+    tools = (
+        (deepcopy(initial.tools_added) if initial else []) if anchors else current_tools(messages)
+    )
+    return tools, anchors
+
+
+def with_request_tools(messages: list[Message], tools: list[ToolDeclaration]) -> list[Message]:
+    """Pi's normalizeContext: fold request-level tools into the leading system message.
+
+    Requests built by Agent already carry their tools in the transcript; this covers a
+    direct Provider call that passes `tools` without declaring them in system messages.
+    """
+    if not tools or any(isinstance(m, SystemMessage) and m.tools_added for m in messages):
+        return deepcopy(messages)
+    messages = deepcopy(messages)
+    head = initial_system_message(messages)
+    if head is None:
+        return [SystemMessage(tools_added=deepcopy(tools), timestamp=0), *messages]
+    head.tools_added = deepcopy(tools)
+    return messages
+
+
+def declare_tool_changes(
+    history: list[Message], pending: list[Message], tools: list[ToolDeclaration]
+) -> list[Message]:
+    pending = deepcopy(pending)
+    systems = [i for i, m in enumerate(pending) if isinstance(m, SystemMessage)]
+    index = systems[-1] if systems else None
+    if index is not None:
+        m = pending[index]
+        assert isinstance(m, SystemMessage)
+        m.tools_added, m.tools_removed = [], []
+    previous = {t.name: t for t in current_tools(history + pending)}
+    current = {t.name: t for t in tools}
+    added = [t for t in tools if previous.get(t.name) != t]
+    removed = [name for name, t in previous.items() if current.get(name) != t]
+    if index is not None:
+        m = pending[index]
+        assert isinstance(m, SystemMessage)
+        m.tools_added, m.tools_removed = deepcopy(added), removed
+    elif added or removed:
+        index = next(
+            (i for i, m in enumerate(pending) if not isinstance(m, SystemMessage)), len(pending)
+        )
+        pending.insert(index, SystemMessage(tools_added=deepcopy(added), tools_removed=removed))
+    return pending

pi_python_core-0.8.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,39 @@
+pi_python/__init__.py,sha256=jmQw2LTIjdt9Sn3lTAaAUAvgDrNqfZ1rDGvccAAuPOY,3751
+pi_python/_version.py,sha256=Ocl79hbbH8_jdr5dGC90VR1cAvZc05Rc0tkZttUnMjo,22
+pi_python/agent.py,sha256=eFbmkO5prBbWssaIycgTRWd4VRJ6I3FJMDU414kpL1w,15264
+pi_python/cancellation.py,sha256=DoQVdX7DcQdVLkl4OvhcpMhKZJEW0Kscl2-xxF6i6Y0,608
+pi_python/errors.py,sha256=65lT0nYfzqxRfUlFG-Y9vgYxfDHEuFiBfgqmFnX9_O8,675
+pi_python/estimate.py,sha256=dQQJ9UEGp57F3wO_CcU2oubgPe841ttgpUseK3Fu_0w,5048
+pi_python/events.py,sha256=t05VE-km2ZcsdIXCviVzNFQCob4xBghDfNeBRWpLrCA,4594
+pi_python/function_tools.py,sha256=MQgNwz6PgT2gnbXRe0-SNVLnedkui4jaclL9dGOZa1s,17633
+pi_python/hooks.py,sha256=jm6ep78NjdHxIPZvcOXTZIPxkfBMkffVTNzLvnHS9mM,1321
+pi_python/limits.py,sha256=K1aP1cFH4fVhtWIXqpWMmpkB9AI0wK-bz3Xd2hxnOs4,1157
+pi_python/loop.py,sha256=H9UK8XqvnTFC8JgKoziqqD4s7xOZy-xPciTqaSiP_9c,17622
+pi_python/lowlevel.py,sha256=56wtwqD0Ur1AGAXGa7zclb1IpmRPFpSEss_nspkAdrI,5514
+pi_python/mcp.py,sha256=Nn0cDdNswsCFP-HXvDXiudMYtQvWEyt9bh6kFR028EQ,8084
+pi_python/messages.py,sha256=w5e-lc9DLW_4vYZ73Wj32RXfNYzDHdp4HCYsF5qkfHY,15665
+pi_python/models.py,sha256=IejtaWvbURM9vv_2kkoDzfto2TR0OSLjuQeOh3IJZ1k,6094
+pi_python/provider.py,sha256=k_VfJu5WOQla_LkglTDAq5s-77ejCj4YRTyhJ8onZBo,4259
+pi_python/proxy.py,sha256=kpEUoE1oDkJW7VVaV72slN3uJUFgYR4Q6jtYOEe8LmQ,12159
+pi_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pi_python/queues.py,sha256=nQ5xRSA3MMOHMs_ZJnG9sT3-d_yKn72oSnxXqiKPrcI,3032
+pi_python/recovery.py,sha256=z5ht-6FoKtC5BPEaSgXiRE2KVf94mZDiKMSxV0mkZ-4,8138
+pi_python/run.py,sha256=gR4udFeg1oFSh8CNkS5O-DCoOHrn6vTnaMsGH3nWbSs,17702
+pi_python/stream.py,sha256=R3v-qjCHFQJhHQk83qATz7lC3yr8paJguaHwk8RoHow,10729
+pi_python/sync.py,sha256=HXr6sh9fkom6SD3rSfBzM-jg2IKkim-QifCUP9nJMW0,2557
+pi_python/testing.py,sha256=XfTSOkEv0CenqrBILI_T205jOhyitW53YQZ9yiMXir4,1046
+pi_python/tools.py,sha256=7hpquuOoVeRAhVxlYOXsooFvTcXEgfVkVBrTjvMbqa8,20503
+pi_python/transcript.py,sha256=g6Tg8eiyMCAK43iLpcBv220MHBq8kO7Ty-6OYLCzw2A,6685
+pi_python/data/models.json,sha256=oa_LGv7vaRrS-l7_Z7iu8f7WTyoJJLPhUQyptUz7OmE,77549
+pi_python/providers/__init__.py,sha256=6oB-gHkWn5o_01sLRKUnss-uTMcuyyzie-uSF1cPRdk,673
+pi_python/providers/anthropic.py,sha256=35ZwPGh2VUg-86iNROyHz5MAv1bYZB2XGLR-DHYELAY,30204
+pi_python/providers/common.py,sha256=z8dB2pIc-dRscPAppnA3ZwF_wJygunQb9pI9Wl4CvaA,8051
+pi_python/providers/completions.py,sha256=7tFrS_j2u6mV90mSE8uZYZDfj6DqRVxJXbIrUDay3mg,50289
+pi_python/providers/oauth.py,sha256=_xRiqxG3PIhxgrUYDoI9iKDEnXA12DQS6fPFBwSn8rQ,22822
+pi_python/providers/openai.py,sha256=36KBHaFUgM_QGKBSTxVxAfroCzmcoh5DPKuX667WmLs,30112
+pi_python/providers/transport.py,sha256=R9AbUmlTXwuGXJEv9Q1joZrTJAd1shxnz7Uxwuzl0nA,21990
+pi_python_core-0.8.1.dist-info/METADATA,sha256=SEo2GGTCg7wTUWqDc95QtzmQQqEKKwlNNuLE76ujxow,6437
+pi_python_core-0.8.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pi_python_core-0.8.1.dist-info/licenses/LICENSE,sha256=BFf1vOw7OyEWBd-10aSQQv1jjzaGpBD-CZwkolrxPEg,1069
+pi_python_core-0.8.1.dist-info/licenses/NOTICE,sha256=fJna16fm1ECHN7zVZhtyNmjLw8KGxGp8mL9blISF1K0,633
+pi_python_core-0.8.1.dist-info/RECORD,,

pi_python_core-0.8.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pi_python_core-0.8.1.dist-info/licenses/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.dist-info/licenses/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.