Skip to content

Commit f860cdb

Browse files
Ariasu123Ariasu123
Ariasu123
authored and
Ariasu123
committed
init:Pion
0 parents  commit f860cdb

39 files changed

Lines changed: 7703 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
jobs:
9+
test:
10+
runs-on: ubuntu-latest
11+
strategy:
12+
fail-fast: false
13+
matrix:
14+
python-version: ["3.11", "3.12", "3.13"]
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Install uv
19+
uses: astral-sh/setup-uv@v5
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: ${{ matrix.python-version }}
25+
26+
- name: Install dependencies
27+
run: uv sync --extra dev
28+
29+
- name: Run tests
30+
run: uv run pytest -q
31+
32+
- name: Run offline end-to-end demo
33+
run: uv run python demos/mock_e2e.py

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
.venv/
5+
dist/
6+
build/
7+
.pytest_cache/
8+
.ruff_cache/
9+
.coverage
10+
.DS_Store

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Pion contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Pion
2+
3+
**A minimal, hackable coding agent harness in Python** — a from-scratch reimplementation of the core architecture of [pi](https://github.com/earendil-works/pi) (TypeScript, by Mario Zechner), rebuilt for the Python ecosystem.
4+
5+
[中文文档](README.zh-CN.md)
6+
7+
> primitives, not features — the kernel stays tiny; everything else is an extension.
8+
9+
## Why pion
10+
11+
pi proved that a coding agent needs no bloat: a <1000-token system prompt, four tools (`read`/`write`/`edit`/`bash`), and a powerful extension system. pion ports that philosophy to Python (~3.5k lines of core):
12+
13+
- **Two API shapes, every model** — OpenAI-compatible endpoints (DeepSeek, Kimi/Moonshot, Qwen, Zhipu, OpenAI, vLLM/Ollama…) and Anthropic Messages (Claude), unified behind one streaming event protocol.
14+
- **A real agent loop** — streamed turns, parallel/sequential tool execution, steering & follow-up queues, truncated-tool-call protection, graceful abort.
15+
- **Tree-structured sessions** — append-only JSONL with branches, plus auto-compaction (structured summarization when the context fills up).
16+
- **Hooks, not features** — drop a `.py` file into `~/.pion/extensions/` to intercept tool calls, rewrite context, register tools/commands. Hot-reloadable.
17+
18+
## Install
19+
20+
Requires Python ≥ 3.11.
21+
22+
```bash
23+
# from GitHub
24+
pip install git+https://github.com/your-name/pion.git
25+
26+
# or with uv
27+
uv tool install git+https://github.com/your-name/pion.git
28+
29+
# from source (development)
30+
git clone https://github.com/your-name/pion.git
31+
cd pion && uv sync --extra dev
32+
```
33+
34+
## Quickstart
35+
36+
```bash
37+
# 1. set a provider key (DeepSeek shown; see table below for others)
38+
export DEEPSEEK_API_KEY=sk-...
39+
40+
# 2. start the agent
41+
pion # interactive REPL
42+
pion -p "create hello.txt with hello world, then cat it" # single-shot
43+
pion -m kimi-k2-0905-preview # pick another model
44+
pion --session my.jsonl # resume a session
45+
```
46+
47+
REPL slash commands: `/help` `/model <id>` `/compact` `/stats` `/exit`. Ctrl-C aborts the current run gracefully.
48+
49+
No key? Run the fully offline end-to-end demo (scripted provider, real agent + tools):
50+
51+
```bash
52+
uv run python demos/mock_e2e.py
53+
```
54+
55+
## Built-in models
56+
57+
| Model id | Provider | API | Env var |
58+
|---|---|---|---|
59+
| `deepseek-chat` / `deepseek-reasoner` | DeepSeek | openai-completions | `DEEPSEEK_API_KEY` |
60+
| `kimi-k2-0905-preview` | Moonshot | openai-completions | `MOONSHOT_API_KEY` |
61+
| `glm-4.6` | Zhipu | openai-completions | `ZHIPU_API_KEY` |
62+
| `qwen3-max` | Alibaba | openai-completions | `DASHSCOPE_API_KEY` |
63+
| `claude-sonnet-4-5` / `claude-opus-4-1` | Anthropic | anthropic-messages | `ANTHROPIC_API_KEY` |
64+
65+
Any OpenAI-compatible/self-hosted endpoint works via `--base-url` + `--api-key`, or `register_model()` in code. `<PROVIDER>_BASE_URL` env vars override endpoints.
66+
67+
## Extensions
68+
69+
Drop a file at `~/.pion/extensions/my_ext.py` (or `.pion/extensions/` in a project):
70+
71+
```python
72+
def setup(api):
73+
# block dangerous commands
74+
@api.on("tool_call")
75+
def guard(event):
76+
if event.tool_name == "bash" and "rm -rf /" in str(event.args):
77+
return {"block": True, "reason": "dangerous command blocked"}
78+
79+
# inject context before every LLM call (RAG, memory, …)
80+
@api.on("context")
81+
def inject(messages):
82+
return messages # or a transformed copy
83+
```
84+
85+
Events: `before_agent_start`, `context`, `tool_call` (blockable), `tool_result` (overridable), `agent_start`, `agent_end`, `session_before_compact`. Extensions can also `api.register_tool(...)` and `api.register_command(...)`.
86+
87+
## Architecture
88+
89+
| pion module | pi counterpart | what it does |
90+
|---|---|---|
91+
| `pion/llm/` | `packages/ai` | unified streaming LLM API, 2 provider shapes, usage/cost |
92+
| `pion/agent/` | `packages/agent` | agent loop, event stream, tool orchestration |
93+
| `pion/tools/` | `packages/coding-agent` tools | read / write / edit / bash |
94+
| `pion/session/` | session-manager + compaction | JSONL session tree, auto-compaction |
95+
| `pion/hooks.py` | extension system | lifecycle hooks, dynamic tools/commands, hot reload |
96+
| `pion/cli.py` | `packages/coding-agent` CLI | REPL, slash commands, sessions |
97+
98+
Intentionally **not** ported: pi's custom TUI (differential rendering), themes, keybindings — pion keeps a simple rich-based REPL.
99+
100+
## Development
101+
102+
```bash
103+
uv sync --extra dev
104+
uv run pytest -q # 95+ tests, no network needed
105+
uv run python demos/mock_e2e.py # offline e2e
106+
uv run python demos/real_e2e.py # live DeepSeek e2e (needs DEEPSEEK_API_KEY; exits 2 = honest skip without it)
107+
```
108+
109+
## Roadmap
110+
111+
- [ ] Long-term memory / RAG extension (built on the `context` + `session_before_compact` hooks)
112+
- [ ] MCP client extension + multi-agent orchestration
113+
- [ ] Agent trajectory export & LLM-as-a-Judge evaluation
114+
115+
## Credit & License
116+
117+
Architecture and design philosophy credit goes to [pi](https://github.com/earendil-works/pi) by Mario Zechner and Earendil Inc. pion is an independent Python reimplementation. MIT License.

‎README.zh-CN.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Pion
2+
3+
**极简、可扩展的 Python coding agent harness**——从零重写了 TypeScript 项目 [pi](https://github.com/earendil-works/pi)（作者 Mario Zechner）的核心架构，面向 Python 生态。
4+
5+
[English README](README.md)
6+
7+
> primitives, not features——内核极小，一切能力靠扩展。
8+
9+
## 为什么是 pion
10+
11+
pi 证明了 coding agent 不需要臃肿：系统提示词不到 1000 token、默认只有四个工具（`read`/`write`/`edit`/`bash`）、强大的扩展系统。pion 将这套哲学移植到 Python（核心约 3.5k 行）：
12+
13+
- **两种 API 形状接入所有模型**——OpenAI 兼容接口（DeepSeek、Kimi/月之暗面、通义、智谱、OpenAI、vLLM/Ollama…）与 Anthropic Messages（Claude），统一为一套流式事件协议。
14+
- **真正的 agent loop**——流式回合、串/并行工具执行、steering 与 follow-up 队列、截断工具调用保护、优雅中断。
15+
- **树状会话**——append-only JSONL、支持分支，外加 auto-compaction（上下文将满时结构化摘要压缩）。
16+
- **钩子而非功能**——往 `~/.pion/extensions/` 丢一个 `.py` 文件即可拦截工具调用、改写上下文、注册工具/命令，支持热加载。
17+
18+
## 安装
19+
20+
需要 Python ≥ 3.11。
21+
22+
```bash
23+
# 从 GitHub 安装
24+
pip install git+https://github.com/your-name/pion.git
25+
26+
# 或用 uv
27+
uv tool install git+https://github.com/your-name/pion.git
28+
29+
# 源码安装（开发）
30+
git clone https://github.com/your-name/pion.git
31+
cd pion && uv sync --extra dev
32+
```
33+
34+
## 快速上手
35+
36+
```bash
37+
# 1. 配置 provider key（以 DeepSeek 为例，其他见下表）
38+
export DEEPSEEK_API_KEY=sk-...
39+
40+
# 2. 启动 agent
41+
pion # 交互式 REPL
42+
pion -p "创建 hello.txt 写入 hello world，然后 cat 出来" # 单发模式
43+
pion -m kimi-k2-0905-preview # 切换模型
44+
pion --session my.jsonl # 恢复会话
45+
```
46+
47+
REPL 斜杠命令：`/help` `/model <id>` `/compact` `/stats` `/exit`。运行中 Ctrl-C 优雅中断当前任务。
48+
49+
没有 key？可以先跑完全离线的端到端 demo（脚本化 provider + 真实 agent 与工具）：
50+
51+
```bash
52+
uv run python demos/mock_e2e.py
53+
```
54+
55+
## 内置模型
56+
57+
| 模型 id | 厂商 | API | 环境变量 |
58+
|---|---|---|---|
59+
| `deepseek-chat` / `deepseek-reasoner` | DeepSeek | openai-completions | `DEEPSEEK_API_KEY` |
60+
| `kimi-k2-0905-preview` | 月之暗面 | openai-completions | `MOONSHOT_API_KEY` |
61+
| `glm-4.6` | 智谱 | openai-completions | `ZHIPU_API_KEY` |
62+
| `qwen3-max` | 阿里 | openai-completions | `DASHSCOPE_API_KEY` |
63+
| `claude-sonnet-4-5` / `claude-opus-4-1` | Anthropic | anthropic-messages | `ANTHROPIC_API_KEY` |
64+
65+
任意 OpenAI 兼容/自托管端点都可用 `--base-url` + `--api-key` 接入，或在代码里 `register_model()`。`<PROVIDER>_BASE_URL` 环境变量可覆盖端点。
66+
67+
## 扩展
68+
69+
在 `~/.pion/extensions/my_ext.py`（或项目内 `.pion/extensions/`）新建文件：
70+
71+
```python
72+
def setup(api):
73+
# 拦截危险命令
74+
@api.on("tool_call")
75+
def guard(event):
76+
if event.tool_name == "bash" and "rm -rf /" in str(event.args):
77+
return {"block": True, "reason": "dangerous command blocked"}
78+
79+
# 每次 LLM 调用前改写上下文（RAG、记忆……）
80+
@api.on("context")
81+
def inject(messages):
82+
return messages # 或返回改写后的列表
83+
```
84+
85+
事件：`before_agent_start`、`context`、`tool_call`（可阻断）、`tool_result`（可改写）、`agent_start`、`agent_end`、`session_before_compact`。扩展还可以 `api.register_tool(...)` 和 `api.register_command(...)`。
86+
87+
## 架构对照
88+
89+
| pion 模块 | pi 对应物 | 职责 |
90+
|---|---|---|
91+
| `pion/llm/` | `packages/ai` | 统一流式 LLM API，两种 provider 形状，usage/成本 |
92+
| `pion/agent/` | `packages/agent` | agent loop、事件流、工具编排 |
93+
| `pion/tools/` | `packages/coding-agent` 工具 | read / write / edit / bash |
94+
| `pion/session/` | session-manager + compaction | JSONL 会话树、auto-compaction |
95+
| `pion/hooks.py` | 扩展系统 | 生命周期钩子、动态工具/命令、热加载 |
96+
| `pion/cli.py` | `packages/coding-agent` CLI | REPL、斜杠命令、会话 |
97+
98+
刻意**未移植**：pi 的自研 TUI（差分渲染）、主题、键位绑定——pion 只保留基于 rich 的简洁 REPL。
99+
100+
## 开发
101+
102+
```bash
103+
uv sync --extra dev
104+
uv run pytest -q # 95+ 测试，无需联网
105+
uv run python demos/mock_e2e.py # 离线 e2e
106+
uv run python demos/real_e2e.py # 真实 DeepSeek e2e（需 DEEPSEEK_API_KEY；无 key 时如实跳过，退出码 2）
107+
```
108+
109+
## 路线图
110+
111+
- [ ] 长期记忆 / RAG 扩展（基于 `context` 与 `session_before_compact` 钩子）
112+
- [ ] MCP client 扩展 + 多 agent 编排
113+
- [ ] agent 轨迹导出 + LLM-as-a-Judge 评测
114+
115+
## 致谢与协议
116+
117+
架构与设计哲学致谢 [pi](https://github.com/earendil-works/pi)（Mario Zechner 与 Earendil Inc.）。pion 是独立的 Python 重实现。MIT License。

0 commit comments

Comments
 (0)