pi-python-core

一个可嵌入的 Python agent 核心，移植自 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。

pip install 'pi-python-core[providers]'      # 或 uv add 'pi-python-core[providers]'

安装名是 pi-python-core，导入名是 pi_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(...)。换成本地模型只改两行：

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。

能做什么

除 provider_chat 需要真实凭据外，示例都能离线运行，不需要 API key；测试会逐个运行它们。

与 Pi 的关系

执行循环、事件顺序、钩子、队列、出错与取消的处理都与 Pi 一致，并用差分验证：同一组输入分别交给固定版本的上游代码和本库运行，逐项比较模型请求、工具调用、事件和最终记录。目前核心循环 25 组、模型接入 50 组、WebSocket 多轮 2 组、出错判断 44 条样例全部一致。

有几处是有意的差异，例如工具参数严格校验、不自动转换类型，返回给调用者的状态是副本；另一些是为 Python 用户加的，例如 @tool、同步调用、失败后直接 continue_run()。逐项记录见验收映射。Pi 放在应用层的功能（终端界面、会话文件格式、上下文压缩）不在本库核心里；压缩可以用钩子实现，示例里有完整做法。本项目使用自己的版本号，并非 Pi 官方发行版。

文档

• 一页看懂：五个概念和一轮的流程
• 公开 API
• 模型接入、订阅登录与本地模型
• 实施与验证结果
• 与 Pi 的逐项对照和有意差异
• 参照重建与候选版本验证

开发

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。