paimon 0.2.2__tar.gz → 0.2.4__tar.gz

paimon-0.2.4/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: paimon
+Version: 0.2.4
+Summary: A minimal code agent built on pydantic-ai + textual
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic-ai-slim[anthropic,openai]>=2.31.0
+Requires-Dist: textual>=8.2.7
+Requires-Dist: textual-serve>=1.1.3
+Dynamic: license-file
+
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+English | [简体中文](README.zh-CN.md)
+
+Paimon is a coding agent that lives in your terminal. It reads and edits files in the current directory and runs commands. It also runs headless and imports as a library, so a stronger agent or a program of your own can drive it.
+
+## Install
+
+```bash
+uv tool install paimon   # or: pip install paimon
+```
+
+## Getting started
+
+```bash
+paimon
+```
+
+Or run it without installing anything:
+
+```bash
+uvx paimon
+```
+
+The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
+
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+
+## Using Paimon as a subagent
+
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
+
+```bash
+paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
+paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+```
+
+The bundled skill teaches the calling agent this workflow:
+
+```bash
+paimon install-skill                  # into Claude Code (~/.claude/skills/paimon)
+paimon install-skill --target codex   # into Codex; --dest DIR for anywhere else
+npx skills add aisk/paimon            # the same skill, via skills.sh
+```
+
+## Using Paimon as a library
+
+The agent loop is importable, so a Python program can drive it without going through the CLI. `Agent.open()` starts or resumes a session and `agent.run()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes:
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="edit")
+    async for event in agent.run("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`Agent.open()` also takes a working directory, an async `confirm` callback for permission prompts, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+
+## Sessions
+
+Every conversation is saved, and long ones are summarized in place near the context limit. Paimon prints the command that brings a session back when you leave:
+
+```bash
+paimon -r            # choose a session started in this directory
+paimon -r a1b2c3     # resume one by id
+paimon -c            # resume the most recent one
+paimon sessions      # list them (--json for machines)
+paimon log a1b2c3    # what a session did, one line per event
+```
+
+## Other ways to run it
+
+```bash
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
+paimon --strict                     # ask before every command, even read-only ones
+paimon --web                        # the same UI in a browser (--port, default 8000)
+paimon -p "what does cli.py do?"    # one answer on stdout, no UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # this model for this run only
+paimon --profile work               # a separately configured account
+```
+
+`-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
+
+## Configuration
+
+Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`. File changes render nicer if [delta](https://github.com/dandavison/delta) is installed.
+
+Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Telemetry
+
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

paimon-0.2.4/README.md

@@ -0,0 +1,104 @@
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+English | [简体中文](README.zh-CN.md)
+
+Paimon is a coding agent that lives in your terminal. It reads and edits files in the current directory and runs commands. It also runs headless and imports as a library, so a stronger agent or a program of your own can drive it.
+
+## Install
+
+```bash
+uv tool install paimon   # or: pip install paimon
+```
+
+## Getting started
+
+```bash
+paimon
+```
+
+Or run it without installing anything:
+
+```bash
+uvx paimon
+```
+
+The first launch asks for a provider, model, API base and key. Then just type what you want done. Write `@path/to/file` in a prompt to hand a file to the agent.
+
+While it runs: `Shift+Tab` switches how much the agent may do on its own (**read** asks before writing files or running commands, **edit** lets edits inside the working directory through, **yolo** never asks and is the default), `Esc` interrupts the current turn, `Ctrl+P` opens the command palette, `Ctrl+C` quits.
+
+`Ctrl+T` opens another session in a pane of its own, `Ctrl+W` closes one, `Ctrl+PageUp` and `Ctrl+PageDown` move between them, and `Ctrl+G` jumps to a pane waiting for permission. Paimon can open panes itself: ask for two independent things and it starts a second agent in its own tab. It can also leave a command running in a tab of its own, a dev server or a watcher, instead of holding up a turn.
+
+## Using Paimon as a subagent
+
+Frontier models are good at planning and reviewing; the steps in between are often mechanical. Point Paimon at a cheaper model and let Claude Code or Codex write the plan and check the result. A profile keeps that model's account separate:
+
+```bash
+paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
+paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+```
+
+The bundled skill teaches the calling agent this workflow:
+
+```bash
+paimon install-skill                  # into Claude Code (~/.claude/skills/paimon)
+paimon install-skill --target codex   # into Codex; --dest DIR for anywhere else
+npx skills add aisk/paimon            # the same skill, via skills.sh
+```
+
+## Using Paimon as a library
+
+The agent loop is importable, so a Python program can drive it without going through the CLI. `Agent.open()` starts or resumes a session and `agent.run()` yields typed events, one per text chunk, tool call and turn end, which the caller renders or filters however it likes:
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="edit")
+    async for event in agent.run("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`Agent.open()` also takes a working directory, an async `confirm` callback for permission prompts, and a `toolset` to hand the model fewer tools or tools of your own. An agent holds its session until it goes away; to give it back at a definite moment, call `close()` or use the agent as a context manager. It writes the same session files as the CLI, so a run started in code can be resumed later with `paimon -r`.
+
+## Sessions
+
+Every conversation is saved, and long ones are summarized in place near the context limit. Paimon prints the command that brings a session back when you leave:
+
+```bash
+paimon -r            # choose a session started in this directory
+paimon -r a1b2c3     # resume one by id
+paimon -c            # resume the most recent one
+paimon sessions      # list them (--json for machines)
+paimon log a1b2c3    # what a session did, one line per event
+```
+
+## Other ways to run it
+
+```bash
+paimon --mode read                  # start in a more cautious permission mode (yolo is the default)
+paimon --strict                     # ask before every command, even read-only ones
+paimon --web                        # the same UI in a browser (--port, default 8000)
+paimon -p "what does cli.py do?"    # one answer on stdout, no UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # this model for this run only
+paimon --profile work               # a separately configured account
+```
+
+`-p` never stops to ask, so with the default `yolo` mode it can already write files and run commands. Add `--output-format result` for a single JSON object with the outcome, which is what a calling program should read. `paimon --help` lists the rest.
+
+## Configuration
+
+Each profile keeps its model settings in `~/.config/paimon/<name>/config.json`, written by the first launch or by `paimon login`. Sessions live in `~/.local/share/paimon/sessions/`. File changes render nicer if [delta](https://github.com/dandavison/delta) is installed.
+
+Read and edit modes run a small set of clearly read-only commands (`ls`, `cat`, `git status`, …) without asking; `--strict` turns that off. **This is a guardrail against agent mistakes, not a security boundary.** For real isolation, run Paimon inside a container or VM.
+
+## Telemetry
+
+Each launch sends one anonymous event to Google Analytics: a random install id, the launch mode, the version, the OS name and the configured provider and model name. Nothing from your sessions, prompts, files or credentials is included. Set `PAIMON_NO_TELEMETRY=1` or `DO_NOT_TRACK=1` to turn it off.

paimon-0.2.4/README.zh-CN.md

@@ -0,0 +1,104 @@
+# Paimon
+
+![Paimon](https://automaton-media.com/wp-content/uploads/2020/10/20201019-140524-header.jpg)
+
+[English](README.md) | 简体中文
+
+Paimon 是一个终端里的 coding agent。它读写当前目录下的文件，执行命令。它也支持无头运行，还可以作为库导入，由更强的 agent 或者你自己的程序来驱动。
+
+## 安装
+
+```bash
+uv tool install paimon   # 或者：pip install paimon
+```
+
+## 快速开始
+
+```bash
+paimon
+```
+
+或者不安装直接运行：
+
+```bash
+uvx paimon
+```
+
+首次启动会询问 provider、模型、API base 和 key。之后输入要完成的任务即可。在提示中写 `@path/to/file` 可以把文件提供给 agent。
+
+运行时：`Shift+Tab` 切换 agent 的自主程度（**read** 写文件或执行命令前先询问，**edit** 放行工作目录内的编辑，**yolo** 从不询问，也是默认值），`Esc` 打断当前回合，`Ctrl+P` 打开命令面板，`Ctrl+C` 退出。
+
+`Ctrl+T` 在新 pane 里打开另一个会话，`Ctrl+W` 关闭当前 pane，`Ctrl+PageUp` 和 `Ctrl+PageDown` 在 pane 之间切换，`Ctrl+G` 跳到正在等待授权的 pane。Paimon 自己也能开 pane：让它同时做两件互不相干的事，它会在新 tab 里起第二个 agent。它也能把一条命令留在单独的 tab 里跑，比如开发服务器或者文件监视，不占着当前回合。
+
+## 当作 subagent 使用
+
+前沿模型擅长制定计划和验收结果，中间的执行步骤往往比较机械。让 Paimon 使用成本较低的模型执行，由 Claude Code 或 Codex 制定计划并检查结果。用一个 profile 单独保存该模型的账号：
+
+```bash
+paimon login --profile glm --model zai:glm-4.7 --api-key-env ZAI_API_KEY
+paimon --profile glm -p "apply the plan in PLAN.md" --mode edit --output-format result
+```
+
+自带的 skill 会向调用方 agent 说明这套流程：
+
+```bash
+paimon install-skill                  # 安装到 Claude Code（~/.claude/skills/paimon）
+paimon install-skill --target codex   # 安装到 Codex；--dest DIR 安装到任意目录
+npx skills add aisk/paimon            # 通过 skills.sh 安装同一个 skill
+```
+
+## 当作库使用
+
+agent 循环本身是可以导入的，Python 程序不必经过 CLI 就能驱动它。`Agent.open()` 新建或恢复一个会话，`agent.run()` 产出类型化的事件，每段文本、每次工具调用、每个回合结束各一个，调用方自己决定怎么渲染或过滤：
+
+```python
+import asyncio
+
+from paimon.agent import Agent, TextDelta
+
+async def main():
+    agent = Agent.open(mode="edit")
+    async for event in agent.run("summarize the tests in this directory"):
+        if isinstance(event, TextDelta):
+            print(event.text, end="", flush=True)
+
+asyncio.run(main())
+```
+
+`Agent.open()` 还接受工作目录、用于权限确认的异步 `confirm` 回调，以及 `toolset`，可以只给模型一部分工具，或者换成你自己的工具。agent 被回收时会交还会话，想在确定的时刻交还就调 `close()`，或者把它当上下文管理器用。它写的会话文件和 CLI 一样，所以代码里跑出来的会话之后可以用 `paimon -r` 恢复。
+
+## 会话
+
+每次对话都会保存，很长的对话在接近上下文上限时会被原地总结。退出时 Paimon 会打印恢复该会话的命令：
+
+```bash
+paimon -r            # 从当前目录的会话中选择
+paimon -r a1b2c3     # 按 id 恢复
+paimon -c            # 恢复最近一个会话
+paimon sessions      # 列出会话（--json 输出机器可读格式）
+paimon log a1b2c3    # 查看会话做了什么，每个事件一行
+```
+
+## 其他运行方式
+
+```bash
+paimon --mode read                  # 以更谨慎的权限模式启动（默认为 yolo）
+paimon --strict                     # 每条命令都先询问，包括只读命令
+paimon --web                        # 在浏览器中使用同一套 UI（--port，默认 8000）
+paimon -p "what does cli.py do?"    # 直接在 stdout 输出回答，不启动 UI
+cat log.txt | paimon -p "summarize this"
+paimon --model zai:glm-4.7          # 仅本次运行使用该模型
+paimon --profile work               # 单独配置的另一个账号
+```
+
+`-p` 不会停下来询问，配合默认的 `yolo` 模式，它已经可以修改文件和执行命令。加 `--output-format result` 会输出一个包含结果的 JSON 对象，调用方程序读这个就够了。其余选项见 `paimon --help`。
+
+## 配置
+
+每个 profile 的模型设置保存在 `~/.config/paimon/<name>/config.json`，由首次启动或 `paimon login` 写入。会话存放在 `~/.local/share/paimon/sessions/`。安装 [delta](https://github.com/dandavison/delta) 后文件改动的展示效果更好。
+
+read 和 edit 模式会不经询问执行一小组明确只读的命令（`ls`、`cat`、`git status` 等），`--strict` 可以关掉。**这是防止 agent 失误的护栏，不是安全边界。** 需要真正的隔离时，请在容器或虚拟机中运行 Paimon。
+
+## 遥测
+
+每次启动会向 Google Analytics 发送一条匿名事件：随机生成的安装 id、启动方式、版本号、操作系统名称，以及配置的 provider 和模型名。会话、提示词、文件和密钥一概不上报。设置 `PAIMON_NO_TELEMETRY=1` 或 `DO_NOT_TRACK=1` 可以关闭。

{paimon-0.2.2 → paimon-0.2.4}/paimon/__init__.py

@@ -1 +1,5 @@
 """Paimon, a minimal code agent built on pydantic-ai + textual."""
+
+from .errors import PaimonError
+
+__all__ = ["PaimonError"]