pi-py

Pi 的 Python SDK 复刻 —— AI agent 工具集：统一 LLM API、agent 运行时、编码 agent 工具集。

Pi（原名 badlogic/pi-mono，作者 Mario Zechner 于 2026 年加入 Earendil Works 后项目迁至现址）是一套 TypeScript 的 AI agent 工具集。本仓库将其核心能力移植到 Python，以 SDK 库形式提供，不含 CLI/TUI。

同步状态

• 当前对齐版本：v0.84.1（2026-08-12，破例同步 patch）
• 同步策略：仅在上游发布 0.x.0（minor）时集中同步，详见 SYNC.md

包	上游对应	状态	说明
pi-ai	@earendil-works/pi-ai	✅	统一 LLM API（OpenAI + Anthropic + retry）
pi-agent-core	@earendil-works/pi-agent-core	✅	agent 循环引擎 + harness（技能/会话/压缩）
pi-storage-sqlite	@earendil-works/pi-storage-sqlite-node	✅	SQLite 会话存储后端
pi-coding-agent	@earendil-works/pi-coding-agent	✅	编码 agent SDK（bash/read/edit/write/grep/find/ls）
pi-server	@earendil-works/pi-server	✅	agent 服务化（Unix socket + JSONL + supervisor）

安装

所有包均已发布到 PyPI（Python ≥ 3.11），可按需安装单个包，内部依赖会自动解析：

pip install pi-py-agent-core # agent 运行时（含 pi-py-ai）
pip install pi-py-coding-agent # 编码 agent SDK

发行名带 pi-py- 前缀（pi-agent-core 等短名在 PyPI 已被他人占用），导入名不带前缀，如 from pi_agent_core import Agent。

PyPI 包	用途
pi-py-ai	统一 LLM API（OpenAI + Anthropic + retry）
pi-py-agent-core	agent 循环引擎 + harness
pi-py-storage-sqlite	SQLite 会话存储后端
pi-py-coding-agent	编码 agent SDK
pi-py-server	agent 服务化（Unix socket + JSONL）

发布流程：打 tag 并创建 GitHub Release 后，publish.yml 自动构建并发布全部 5 个包到 PyPI。发布记录见 Releases 与 CHANGELOG.md。

快速上手

也可以直接从源码运行：

git clone https://github.com/encyc/pi-py.git
cd pi-py
uv sync

基础 LLM 调用

importasynciofrompi_aiimportstream, Context, UserMessage, Model, StreamOptionsmodel=Model(
id="deepseek-chat", api="openai-completions", provider="deepseek",
base_url="https://api.deepseek.com/v1", input=["text"],
context_window=64000, max_tokens=8192,
)
asyncdefmain():
ctx=Context(messages=[UserMessage(content="你好")])
es=stream(model, ctx, StreamOptions(api_key="sk-..."))
asyncforeventines:
ifevent.type=="text_delta":
print(event.delta, end="")
print()
msg=awaites.result()
print(f"usage: {msg.usage.input} in / {msg.usage.output} out")
asyncio.run(main())

Agent + 工具调用

importasynciofrompi_aiimportModel, TextContent, UserMessagefrompi_agent_coreimportAgent, AgentOptions, AgentToolResultclassWeatherTool:
name="get_weather"description="查询天气"label="Weather"parameters= {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
asyncdefexecute(self, tool_call_id, params, cancel_event=None, on_update=None):
returnAgentToolResult(content=[TextContent(text=f"{params['city']} 晴天 25°C")])
asyncdefmain():
agent=Agent(AgentOptions(
initial_state={"system_prompt": "你是助手", "model": model, "tools": [WeatherTool()]},
get_api_key=lambdap: "sk-...",
))
agent.subscribe(lambdaev, sig: print(ev.type), )
awaitagent.prompt("北京天气怎么样？")
asyncio.run(main())

编码 Agent

importasynciofrompi_aiimportModelfrompi_coding_agentimportCodingAgentasyncdefmain():
agent=CodingAgent(
model=model,
api_key="sk-...",
cwd=".", # 工作目录
)
awaitagent.prompt("读取 README.md 并总结")
asyncio.run(main())

包结构与依赖

packages/
├── pi-ai/ # 叶子 — 统一 LLM API
├── pi-agent-core/ # → pi-ai — agent 运行时
├── pi-storage-sqlite/ # → pi-ai + pi-agent-core — SQLite 后端
├── pi-coding-agent/ # → pi-agent-core + pi-ai — 编码 agent SDK
└── pi-server/ # → pi-coding-agent — RPC 服务

依赖方向自底向上，与上游一致。每个有意偏离上游的地方，记录在对应包的 PORTING.md 中。

技术选型

领域	选型	对应上游
类型/校验	Pydantic v2	typebox
异步	asyncio + AsyncGenerator	Promise + ReadableStream
LLM provider	各厂原生 Python SDK	各厂原生 TS SDK
存储	stdlib sqlite3	node:sqlite
包管理	uv workspace	npm workspaces

开发

uv sync # 安装全部依赖（含 dev）
uv run pytest # 跑测试（默认跳过 integration）
uv run pytest -m integration # 真实 LLM 调用测试（需 API key + 消耗额度）
uv run ruff check # lint
uv run ruff format # 格式化
uv run mypy # 类型检查（strict）

集成测试需要设置环境变量（参考 .env）：

• OPENAI_API_KEY — OpenAI 测试
• DEEPSEEK_API_KEY — DeepSeek 测试（OpenAI 兼容协议）
• ANTHROPIC_API_KEY — Anthropic 测试

贡献指南详见 CONTRIBUTING.md。

路线图

• 5 包基线完成（对齐上游 v0.84.1）
• OpenAI/DeepSeek provider 真实验证
• Anthropic provider（纯逻辑测试，待真实 API 验证）
• Google / Mistral / Bedrock provider
• OAuth 鉴权（auth/*）
• 扩展系统（extensions/）

许可证

MIT，与上游保持一致。详见 LICENSE。