15838328874 / pi

# pi-py
**English** | 中文
 · 
> **实测战绩**：真实模型企业测评 **5/5** ✅ · 安全回归 **40/40** ✅ · SandboxFS 组合 **11/11** ✅ · Python 3.12 · CubeSandbox 会话级沙箱
A **self-hostable, extensible AI agent platform**: sandboxed tool execution, multi-tenant
governance (JWT/quotas/rate limits/audit), a canonical trajectory log, an eval harness with
scoring and A/B, an RL data flywheel (rollout→reward→SFT/RLVR JSONL), and protocol-level
tool extensibility via MCP + Skills. Coding is the first fully-developed scenario, not the
boundary. Python reimplementation of the pi coding agent
harness, shipped as a multi-user HTTP service: streaming LLM layer, asyncio agent loop, coding
tools, and sandboxing (CubeSandbox microVMs in production, Docker locally). Mirrors pi's package layering:
| pi (TypeScript) | pi-py (Python) |
| ----------------- | ----------------------------------------------------- |
| `pi-ai` | `pi.llm` (openai / anthropic / fake) |
| `pi-agent-core` | `pi.agent` (asyncio loop + events) |
| `pi-coding-agent` | `pi.tools` + `pi.prompt` |
| daemon / server | `pi.server` (FastAPI + SSE), `pi.cli` (serve/migrate) |
## 架构总览
 [code] 
> 完整架构、Agent Loop 状态机、Memory Judge 决策树见 ARCHITECTURE.md §3。
## Highlights
精选亮点（完整叙事、设计取舍与踩坑实录都在 ARCHITECTURE.md）：
| 亮点 | 一句话 | 详情 |
|---|---|---|
| 🏜️ **会话级沙箱** | 懒加载 + 会话级复用池：纯聊天回合**零 VM**，首次 `bash` 才现场建 VM（毫秒级冷启），跨回合延续状态，空闲超时 / 内存压力自适应回收；崩溃隔离、内存模型 = 并发**活跃**回合 × 256Mi 而非会话数 | 架构总览 · 设计笔记 |
| 🛡️ **SSRF 防线** | 进程内抓取工具（web_fetch/web_search）已**移除**，抓取一律降级到沙箱内执行——宿主内网（MySQL/Redis/云元数据）对模型不可达 | 坑 20（已解决） |
| 🗂️ **工作区闭环归档** | 每回合基线快照 → 结束 tar.gz + 差异元数据（added/modified/deleted），MinIO 惰性接口就绪 | 实测数据 |
| 🧪 **自治验证** | 真实模型跑企业任务：数据分析/日志解析/GitHub 情报/文档摘要/数据清洗 **5/5 PASS**；安全回归 **40/40**；沙箱组合 **11/11** | 测试体系 |
| ☁️ **生产就绪** | 部署手册（10 节）+ 生产就绪审计（7 项修复、剩余清单全部闭环） | 部署手册 · 审计 |
| 🔐 **多租户治理** | JWT / 配额 / 限流 / 审计 / 会话级分布式锁（同会话并发直接拒绝，跨会话独立沙箱并行） | 架构总览 · 架构手册 |
> **文档地图**（三个文档各管一段，知识点不重复）：
>
> | 文档 | 定位 | 什么问题看它 |
> |---|---|---|
> | `README.md` | 门面 | 这是什么、怎么装、怎么跑（快速上手入口） |
> | `ARCHITECTURE.md` | 技术手册 + 叙事 | 每个模块每个函数、配置全表（§13）、坑清单（§17）、差距清单（§19）；设计取舍、测试样例、术语表、实测数据 |
> | `ROADMAP.md` | 状态与路线图 | 什么做完了、什么没做、下一步做什么（含环境区分表） |
> | `docs/adr.md` | 设计取舍索引 | 关键决策一页扫读：每条「选了 A · 没选 B · 为什么 · 代价」，收敛自各设计笔记 |
> | `docs/`（三件） | CubeSandbox 专项 | 沙箱设计笔记 / 生产部署手册 / 生产就绪审计——专项文档，不重复核心文档内容 |
>
> **推荐阅读路径**：先看本页 `## Highlights` 建立全局印象 → 想深入了解设计取舍、踩坑故事、实测细节 → 直接读 **ARCHITECTURE.md**（技术手册 + 叙事）；对照代码逐模块也看它；做没做、下一步 → ROADMAP.md。
Linux only. The former single-user CLI/TUI mode, the local SQLite session store, and
all Windows/WSL support have been removed — this package is the service and nothing else.
## Install
 [code] 
## Configure
Environment variables, or a `.env` file (project root `./.env`, or `~/.pi-py/.env`;
the first file found wins, and existing environment variables always override it):
 [code] 
Notes:
- `PI_DATABASE_URL` is **required**. MySQL (`mysql+aiomysql://`) or PostgreSQL
 (`postgresql+asyncpg://`); the server raises at startup without it. There is no
 local-file fal