pi-python-core 0.10.0__tar.gz → 0.10.1__tar.gz

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pi-python-core
-Version: 0.10.0
+Version: 0.10.1
 Summary: An embeddable asyncio agent core with opt-in Claude and OpenAI providers
 License-Expression: MIT
 License-File: LICENSE
@@ -99,6 +99,7 @@ To try it offline first: `python examples/quickstart.py`.
 | Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
 | Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
 | Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Remember across conversations | Not built in, as in Pi's core; an example plugin saves facts to a file and puts them in the system prompt, ready to copy and adapt | [memory_demo](examples/memory_demo.py) |
 | Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
 | Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
 | Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/README.md

@@ -65,6 +65,7 @@ To try it offline first: `python examples/quickstart.py`.
 | Use MCP tools | `async with connect_stdio(...) as tools`, or `connect_http(url)` for a remote server | [mcp_tools](examples/mcp_tools.py) |
 | Let one agent call another | Wrap the sub-agent as a tool; cancellation propagates down. Plugins can also define subagents in Markdown | [subagent](examples/subagent.py) |
 | Package and share capabilities | A plugin bundles tools, instructions, hooks, skills, prompt templates, subagents and MCP servers; load it by name or path with `load_plugins` and build the agent with `plugins.agent(...)` | [plugin_demo](examples/plugin_demo.py) |
+| Remember across conversations | Not built in, as in Pi's core; an example plugin saves facts to a file and puts them in the system prompt, ready to copy and adapt | [memory_demo](examples/memory_demo.py) |
 | Intervene mid-run | `steer` injects guidance, `follow_up` queues the next task, `abort` cancels at any time (callable from any thread) | |
 | Context full, service errors | `is_context_overflow` and `is_retryable_error` tell you why, `continue_run()` retries, `transform_context` compacts | [recovery](examples/recovery.py) |
 | Save and restore conversations | `encode_messages` / `decode_messages`; your application decides where to store them | [save_restore](examples/save_restore.py) |

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/README.zh-CN.md

@@ -65,6 +65,7 @@ agent = Agent(provider=llm, model=llm.model("qwen3:8b", context_window=40960), t
 | 用 MCP 工具 | `async with connect_stdio(...) as tools`；远程服务器用 `connect_http(url)` | [mcp_tools](examples/mcp_tools.py) |
 | 让一个 agent 调用另一个 | 把子 agent 包成工具，取消会一路传下去；插件也可以用 Markdown 定义子 agent | [subagent](examples/subagent.py) |
 | 打包和分享能力 | 插件把工具、说明、钩子、技能、提示模板、子 agent 和 MCP 服务器打成一组；用 `load_plugins` 按名字或路径加载，再用 `plugins.agent(...)` 构造 agent | [plugin_demo](examples/plugin_demo.py) |
+| 跨对话记住信息 | 与 Pi 的核心一样不内置；示例插件把事实存进文件，再放进系统提示，可以复制后修改 | [memory_demo](examples/memory_demo.py) |
 | 中途干预 | `steer` 插入指导，`follow_up` 排队后续任务，`abort` 随时取消（任何线程都可以调用） | |
 | 上下文满了、服务出错 | `is_context_overflow`、`is_retryable_error` 判断原因，`continue_run()` 重试，`transform_context` 压缩 | [recovery](examples/recovery.py) |
 | 保存与恢复对话 | `encode_messages` / `decode_messages`，应用决定存在哪里 | [save_restore](examples/save_restore.py) |

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/compat/COVERAGE.md

@@ -133,6 +133,7 @@ CI 第一次在 GitHub 上运行，Linux 和 macOS 全部通过，另外发现
 - 上游由命令行程序发现和加载 package（`pi install`、`settings.json`、项目信任）。本库没有应用程序，由应用代码指定加载哪些插件，不自动发现。已安装的插件通过 entry point 组 `pi_python.plugins` 注册，对应 `pi install npm:...`。
 - 插件代码是 Python 的 `setup(api)`，对应 Pi 扩展的工厂函数。`PluginAPI` 只保留与界面无关的部分（工具、系统提示、钩子、事件、MCP），没有命令、快捷键、渲染器等终端界面接口；另加了 `service`（应用提供的对象）、`options`（按插件分开的设置）、`add_check`（自检）和 `on_close`。
 - 插件处理函数出错时交给 `on_error`，默认写日志；上游交给 `emitError`，显示在界面上。`before_tool_call` 与上游一样，出错时让这次调用失败。应用自己的钩子保持核心行为，不做隔离。
+- 插件注册处理函数时检查它能否接收该钩子传入的位置参数（`subscribe` 为事件一个参数，`add_check` 和 `on_close` 没有参数），不能就报 `ConfigurationError`，加载停止（0.10.1 加入）。上游没有这一步：TypeScript 在编译时检查类型，JavaScript 调用时多出的参数会被忽略。Python 会在每次调用时抛出 `TypeError`，插件处理函数的错误又只写日志，不检查的话这样的处理函数会悄悄失效。应用自己的钩子不做这项检查。
 - 模型用 `read_skill` 工具读取技能（上游让模型用通用的 `read` 工具）。它只能读技能目录里的文件，单个文件不超过 256 KiB。
 - 子 agent 在同一进程、同一事件循环里运行（上游为每个子 agent 启动一个 pi 子进程），使用主 agent 的 Provider 和合并后的全部钩子。上游的子进程会加载同样的扩展，所以插件的处理函数同样作用于子 agent，这一点与上游一致。不指定模型时，子 agent 用调用那一刻主 agent 的模型（上游从设置里取默认模型）。没有上游的 `agentScope`、`cwd` 参数和项目级 agent 的确认步骤。
 - MCP：工具名为 `mcp__<服务器>__<工具>`，但工具名里的 `-` 保留（上游换成 `_`）。字符串里只展开 `${PLUGIN_ROOT}`、`${PYTHON}` 和环境变量，前两个是本库新增；不支持 `!命令`。不支持 OAuth、`exposure` / `toolExposure` 和单次请求超时，这些设置会被忽略并给出警告。新增 `pi_python.mcp.connect_http`，连接 streamable HTTP 服务器；在 MCP SDK 1.10、1.30 和 2.3 上测过。

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/compat/results/verification.json

@@ -15,12 +15,12 @@
         "--extra",
         "providers",
         "--extra",
-        "mcp"
+        "mcp-interactive"
       ],
       "exit_code": 0,
-      "seconds": 0.021038709091953933,
+      "seconds": 0.02251266618259251,
       "stdout": "",
-      "stderr": "Resolved 47 packages in 3ms\nAudited 44 packages in 3ms\n"
+      "stderr": "Resolved 60 packages in 2ms\nAudited 57 packages in 8ms\n"
     },
     {
       "command": [
@@ -35,7 +35,7 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.06494950002525002,
+      "seconds": 0.0649345419369638,
       "stdout": "All checks passed!\n",
       "stderr": ""
     },
@@ -53,8 +53,8 @@
         "scripts"
       ],
       "exit_code": 0,
-      "seconds": 0.02588170801755041,
-      "stdout": "89 files already formatted\n",
+      "seconds": 0.024958166992291808,
+      "stdout": "110 files already formatted\n",
       "stderr": ""
     },
     {
@@ -65,8 +65,8 @@
         "src/pi_python"
       ],
       "exit_code": 0,
-      "seconds": 0.35578474996145815,
-      "stdout": "Success: no issues found in 37 source files\n",
+      "seconds": 0.5702685830183327,
+      "stdout": "Success: no issues found in 43 source files\n",
       "stderr": ""
     },
     {
@@ -77,8 +77,8 @@
         "-q"
       ],
       "exit_code": 0,
-      "seconds": 11.12525479204487,
-      "stdout": "........................................................................ [ 18%]\n........................................................................ [ 36%]\n........................................................................ [ 54%]\n........................................................................ [ 72%]\n........................................................................ [ 90%]\n......................................                                   [100%]\n398 passed in 10.69s\n",
+      "seconds": 149.19938791706227,
+      "stdout": "........................................................................ [  9%]\n........................................................................ [ 19%]\n........................................................................ [ 28%]\n........................................................................ [ 38%]\n........................................................................ [ 47%]\n........................................................................ [ 57%]\n........................................................................ [ 67%]\n...............................................ss....................... [ 76%]\n........................................................................ [ 86%]\n........................................................................ [ 95%]\n................................                                         [100%]\n750 passed, 2 skipped in 148.30s (0:02:28)\n",
       "stderr": ""
     },
     {
@@ -89,7 +89,7 @@
         "examples/in_memory.py"
       ],
       "exit_code": 0,
-      "seconds": 0.10870087496004999,
+      "seconds": 0.6022720420733094,
       "stdout": "The telemetry contains 3 complete records.\n",
       "stderr": ""
     },
@@ -104,8 +104,8 @@
         "test/agent.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.1702424169052392,
-      "stdout": "\n> @earendil-works/pi-agent-core@1.0.0 test\n> vitest --run test/agent-loop.test.ts test/agent.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/agent\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  2 passed (2)\n      Tests  77 passed (77)\n   Start at  00:19:15\n   Duration  758ms (transform 566ms, setup 0ms, import 1.06s, tests 171ms, environment 0ms)\n\n",
+      "seconds": 1.9349422920495272,
+      "stdout": "\n> @earendil-works/pi-agent-core@1.0.0 test\n> vitest --run test/agent-loop.test.ts test/agent.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/agent\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  2 passed (2)\n      Tests  77 passed (77)\n   Start at  12:01:38\n   Duration  1.40s (transform 916ms, setup 0ms, import 2.00s, tests 281ms, environment 0ms)\n\n",
       "stderr": ""
     },
     {
@@ -121,8 +121,8 @@
         "test/openai-codex-stream.test.ts"
       ],
       "exit_code": 0,
-      "seconds": 1.1117059160023928,
-      "stdout": "\n> @earendil-works/pi-ai@1.0.0 test\n> vitest --run test/transcript-tool-changes.test.ts test/validation.test.ts test/anthropic-mid-conversation-effort.test.ts test/openai-codex-stream.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/ai\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  4 passed (4)\n      Tests  70 passed (70)\n   Start at  00:19:16\n   Duration  816ms (transform 907ms, setup 0ms, import 1.59s, tests 244ms, environment 0ms)\n\n",
+      "seconds": 1.3067305411677808,
+      "stdout": "\n> @earendil-works/pi-ai@1.0.0 test\n> vitest --run test/transcript-tool-changes.test.ts test/validation.test.ts test/anthropic-mid-conversation-effort.test.ts test/openai-codex-stream.test.ts\n\n\n RUN  v4.1.11 /Users/daidong/Documents/gitrepos/pi-python/reference/pi/packages/ai\n\n\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\u00b7\n\n Test Files  4 passed (4)\n      Tests  70 passed (70)\n   Start at  12:01:39\n   Duration  992ms (transform 1.03s, setup 0ms, import 1.86s, tests 252ms, environment 0ms)\n\n",
       "stderr": ""
     },
     {
@@ -133,7 +133,7 @@
         "scripts/conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 4.8161368750734255,
+      "seconds": 5.7676790410187095,
       "stdout": "C01-text: passed []\nC02-tool: passed []\nC03-sequential: passed []\nC04-parallel: passed []\nC05-one-sequential: passed []\nC06-one-failure: passed []\nC07-unknown: passed []\nC08-prepare: passed []\nC09-before-error: passed []\nC09-block: passed []\nC09-replace: passed []\nC10-length: passed []\nC11-transform: passed []\nC12-system: passed []\nC13-steering: passed []\nC14-followup-all: passed []\nC14-followup-one: passed []\nC15-prepare: passed []\nC16-continue: passed []\nC16-end: passed []\nC16-mixed: passed []\nC16-terminate: passed []\nC19-abort-stream: passed []\nC19-abort-tools: passed []\nC24-provider-error: passed []\n",
       "stderr": ""
     },
@@ -145,7 +145,7 @@
         "scripts/provider_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 13.814684083103202,
+      "seconds": 15.009326208150014,
       "stdout": "anthropic-oauth.json passed\nanthropic-request-cache-long.json passed\nanthropic-request-cache-none.json passed\nanthropic-request-replay.json passed\nanthropic-request-tools-image.json passed\nanthropic-text.json passed\nanthropic-thinking.json passed\nanthropic-tool.json passed\ncodex-request-tools-image.json passed\ncodex-text.json passed\ncompletions-compat-strict.json passed\ncompletions-deepseek.json passed\ncompletions-format-ant-ling.json passed\ncompletions-format-baseten.json passed\ncompletions-format-string-thinking.json passed\ncompletions-format-together.json passed\ncompletions-format-zai.json passed\ncompletions-midconvo-tools.json passed\ncompletions-moonshot-usage.json passed\ncompletions-openai-off.json passed\ncompletions-openrouter.json passed\ncompletions-qwen-length.json passed\ncompletions-reasoning-content.json passed\ncompletions-request-replay.json passed\ncompletions-text.json passed\ncompletions-tool-stream.json passed\nopenai-incomplete.json passed\nopenai-request-cache-long.json passed\nopenai-request-cache-none.json passed\nopenai-request-reasoning.json passed\nopenai-request-replay.json passed\nopenai-request-tools-image.json passed\nopenai-text.json passed\nopenai-thinking-backfill.json passed\nopenai-thinking.json passed\nopenai-tool.json passed\nproxy-text.json passed\nproxy-thinking-tool.json passed\nsession-anthropic-collapse-budget.json passed\nsession-anthropic-native-tools.json passed\nsession-anthropic-oauth-effort.json passed\nsession-anthropic-redefinition.json passed\nsession-anthropic-server-fallback.json passed\nsession-anthropic-thinking-off.json passed\nsession-codex-tool-search.json passed\nsession-openai-additional-tools.json passed\nsession-openai-collapse.json passed\nsession-openai-explicit-cache-long.json passed\nsession-openai-explicit-cache-none.json passed\nsession-openai-removal.json passed\n",
       "stderr": ""
     },
@@ -157,7 +157,7 @@
         "scripts/websocket_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.42606441595125943,
+      "seconds": 0.9335567080415785,
       "stdout": "codex-continuation-lost-state.json passed\ncodex-continuation-tool-loop.json passed\n",
       "stderr": ""
     },
@@ -169,7 +169,7 @@
         "scripts/recovery_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.1813259170157835,
+      "seconds": 0.628341041970998,
       "stdout": "recovery classifiers: 44/44 match upstream \n",
       "stderr": ""
     },
@@ -181,8 +181,8 @@
         "scripts/plugin_conformance.py"
       ],
       "exit_code": 0,
-      "seconds": 0.39384091598913074,
-      "stdout": ".......                                                                  [100%]\n7 passed in 0.05s\n",
+      "seconds": 1.306608916958794,
+      "stdout": ".......                                                                  [100%]\n7 passed in 0.74s\n",
       "stderr": ""
     },
     {
@@ -193,10 +193,22 @@
         "examples/plugin_demo.py"
       ],
       "exit_code": 0,
-      "seconds": 0.11929479194805026,
+      "seconds": 0.576676958007738,
       "stdout": "loaded: lab_tools 0.1.0\ncheck: counts_duplicates passed\nprompt: Find duplicate events in events.csv using a 30 second window. Read the dedup-window skill first.\ntools used: ['read_skill', 'subagent']\nanswer: The reviewer found 2 duplicate rows.\n",
       "stderr": ""
     },
+    {
+      "command": [
+        "uv",
+        "run",
+        "python",
+        "examples/mcp_interactive.py"
+      ],
+      "exit_code": 0,
+      "seconds": 1.8445827078539878,
+      "stdout": "Model task=demo-run request=1 profile=default attempt=1 usage=None\nModel task=demo-run request=2 profile=default attempt=1 usage=None\nModel task=demo-run request=3 profile=json attempt=1 usage={'input': 4, 'output': 3, 'cacheRead': 1}\nModel task=demo-run request=4 profile=text attempt=1 usage={'input': 4, 'output': 3, 'cacheRead': 1}\nForm from business: Choose output for report\nDemo user chooses: short, confirmed\n{\"label\": \"report\", \"model_reply\": \"[report] [ready]\", \"action\": \"accept\", \"selection\": {\"style\": \"short\", \"confirmed\": true}, \"auxiliary\": {\"json\": {\"ok\": true}, \"text\": \"Ready\"}}\n",
+      "stderr": ""
+    },
     {
       "command": [
         "uv",
@@ -206,7 +218,7 @@
         "--help"
       ],
       "exit_code": 0,
-      "seconds": 0.10245537490118295,
+      "seconds": 0.6522026660386473,
       "stdout": "usage: provider_chat.py [-h]\n                        --provider {anthropic,openai,openai-codex,openai-chatgpt,deepseek}\n                        --model MODEL [--prompt PROMPT]\n                        [--credential-file CREDENTIAL_FILE] [--login]\n                        [--device]\n                        [--thinking {off,minimal,low,medium,high,xhigh,max}]\n                        [--transport {sse,websocket,websocket-cached,auto}]\n                        [--session-id SESSION_ID]\n\nExplicit API/OAuth example. Invoke --help; never imported by the core.\n\noptions:\n  -h, --help            show this help message and exit\n  --provider {anthropic,openai,openai-codex,openai-chatgpt,deepseek}\n  --model MODEL         Model ID enabled for this account\n  --prompt PROMPT\n  --credential-file CREDENTIAL_FILE\n                        App-owned OAuth file (never reuse another client file)\n  --login\n  --device              Codex device authorization instead of browser callback\n  --thinking {off,minimal,low,medium,high,xhigh,max}\n  --transport {sse,websocket,websocket-cached,auto}\n  --session-id SESSION_ID\n                        Required for websocket-cached\n",
       "stderr": ""
     },
@@ -216,9 +228,9 @@
         "build"
       ],
       "exit_code": 0,
-      "seconds": 1.1796516249887645,
+      "seconds": 1.0952744169626385,
       "stdout": "",
-      "stderr": "Building source distribution...\nBuilding wheel from source distribution...\nSuccessfully built dist/pi_python_core-0.9.0.tar.gz\nSuccessfully built dist/pi_python_core-0.9.0-py3-none-any.whl\n"
+      "stderr": "Building source distribution...\nBuilding wheel from source distribution...\nSuccessfully built dist/pi_python_core-0.10.1.tar.gz\nSuccessfully built dist/pi_python_core-0.10.1-py3-none-any.whl\n"
     }
   ],
   "status": "passed"

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/docs/PLUGINS.md

@@ -311,6 +311,62 @@ Several plugins can handle the same hook. Handlers run in this order: your own h
 
 When a plugin's handler raises an exception or returns the wrong type, a `PluginFailure` report goes to the `on_error` callback of `load_plugins`, which may be sync or async and logs the failure by default. That handler's contribution is skipped and the other handlers still run, so one faulty plugin does not stop the agent. The exception is `before_tool_call`, where an error fails that tool call, as in Pi. Your own hooks keep the core behavior described in the [API](API.md#hooks).
 
+A handler that cannot accept the arguments its hook passes, such as a `transform_context` handler written as `def inject(messages)` instead of `def inject(messages, cancel)`, is rejected when it is registered: `api.on` raises `ConfigurationError` naming the expected arguments, and loading stops. The same check applies to `subscribe` (one argument, the event), `add_check` and `on_close` (no arguments). Otherwise such a handler would fail on every call and only be logged.
+
+## Calling a model from a plugin
+
+The application owns providers and credentials, so a plugin has no model of its own. A plugin that needs a model call, for example to summarize or to merge notes, asks for the Provider as the `"provider"` service and reads the model name from its options:
+
+```python
+from pi_python import Agent, ToolContext
+
+
+def setup(api):
+    provider = api.service("provider")
+
+    async def summarize(text: str, context: ToolContext) -> str:
+        """Summarize a text in three sentences.
+
+        Args:
+            text: The text to summarize.
+        """
+        writer = Agent(
+            provider=provider,
+            model=api.options.get("model") or context.agent_context.model,
+            system_prompt="Summarize the text in three sentences.",
+        )
+        result = await context.run_agent(writer, text)  # aborting the run aborts this call
+        reply = "".join(getattr(block, "text", "") for block in result.messages[-1].content)
+        if result.status != "completed" or not reply:
+            raise RuntimeError(f"The summary failed: {result.status}")
+        return reply
+
+    api.add_tool(summarize)
+```
+
+The application passes `services={"provider": provider}`, and `options={"summary": {"model": "claude-haiku-4-5"}}` to use a cheaper model for the plugin named `summary`. Without the option, the call uses the model of the agent that called the tool. Inside a tool, run the call with `context.run_agent`, so that aborting the main run also aborts it. When the model call is optional, use `api.service("provider", default=None)` and say in the plugin's documentation what happens without it.
+
+## Memory across conversations
+
+Neither this library nor Pi's core has built-in memory. Pi's application remembers through instruction files it reads into the system prompt (`AGENTS.md`), saved sessions and compaction. What is worth remembering, and where to keep it, differs between applications. A plugin can add memory with two parts: tools that save facts to storage the application chooses, and a `transform_context` handler that puts the saved facts into every request.
+
+[examples/plugins/memory](../examples/plugins/memory) does this in one file, and [examples/memory_demo.py](../examples/memory_demo.py) runs it offline:
+
+```python
+async with load_plugins(
+    ["./examples/plugins/memory"],
+    services={"provider": provider},  # optional: merges facts when the list is full
+    options={"memory": {"path": "memory.json", "max_facts": 50}},
+) as plugins:
+    agent = plugins.agent(provider=provider, model="claude-sonnet-5-5")
+```
+
+- The model saves a fact with `remember` and removes one with `forget`. The facts are kept in the JSON file.
+- Before every request, the facts become the `memory` section of the system prompt (`SystemMessage.sections`). The stored conversation does not change. The section changes only when the facts do, so the cached prompt prefix stays valid in between.
+- When a new fact would make the list longer than `max_facts`, the plugin asks a model to merge the list, as in [Calling a model from a plugin](#calling-a-model-from-a-plugin). Without a provider, the oldest facts are dropped.
+
+Copy the directory and change what your application needs: what is worth saving, retrieval when there are too many facts to list, or a database in place of the file. The example assumes that one process writes the file at a time.
+
 ## Differences from Pi
 
 Pi's command-line application finds and loads packages; this library has no application, so your code names the plugins to load. The other differences:

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/docs/PLUGIN_DEVELOPMENT.md

@@ -258,6 +258,7 @@ install. Do not claim packaging is verified merely because directory loading wor
 | Async work tied to plugin lifetime | Create `scope = api.task_scope()` after registering resources it uses. Await `scope.run(client.fetch(...), cancel=context.cancel)` in an async tool with a `ToolContext` parameter. Declare `task-scope-v1` if using it. |
 | Worker thread needs a loop-bound connection | Host creates a `LoopPortal` on the connection's loop and passes it as a service. The synchronous tool uses `portal.call(async_function, ...)`. See [API](API.md#owned-tasks-and-calls-from-worker-threads). |
 | A hook | Register `@api.on("before_tool_call")`; return `False` to block. Use [documented hook signatures](API.md#hooks), and test the blocked path. |
+| Model call inside the plugin | Ask for `provider = api.service("provider")`; take the model from `api.options.get("model")`, else `context.agent_context.model`. In an async tool, run `await context.run_agent(Agent(provider=provider, model=...), text)`. See [Calling a model from a plugin](PLUGINS.md#calling-a-model-from-a-plugin). |
 | Subagent | Add `agents/reviewer.md` with `name`, `description`, optional `tools`/`model`, and a system-prompt body. See the [lab_tools example](../examples/plugins/lab_tools). |
 | MCP server | Add `mcp.json` or call `api.add_mcp_server`. Install `[mcp]`; specify required servers/tools in readiness. Use the [interactive workflow](MCP_INTERACTION.md) for host model/form callbacks. |
 

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/docs/zh/PLUGINS.md

@@ -300,6 +300,62 @@ async with load_plugins(["sandbox-plugin"], options=options, strict=True) as plu
 
 插件的处理函数抛出异常或返回了错误的类型时，一份 `PluginFailure` 报告交给 `load_plugins` 的 `on_error` 回调；回调可以是普通函数或 async 函数，默认写进日志。这个处理函数的结果被跳过，其他处理函数照常运行，所以一个有问题的插件不会让 agent 停下。`before_tool_call` 例外：和 Pi 一样，那里的错误会让这次工具调用失败。你自己的钩子保持核心原来的行为，见 [API](API.md#钩子)。
 
+处理函数接收不了钩子传入的参数时，注册那一刻就会被拒绝。例如把 `transform_context` 的处理函数写成 `def inject(messages)`，少了 `cancel`：`api.on` 抛出 `ConfigurationError`，写明应接收哪些参数，加载随之停止。`subscribe`（一个参数，即事件）、`add_check` 和 `on_close`（没有参数）也做同样的检查。如果不在注册时检查，这样的处理函数每次调用都会失败，却只留下一行日志。
+
+## 在插件里调用模型
+
+Provider 和凭据归应用所有，插件自己没有模型。插件需要调用模型时，比如做摘要或合并笔记，通过 `"provider"` 服务取得 Provider，从自己的 options 里读模型名：
+
+```python
+from pi_python import Agent, ToolContext
+
+
+def setup(api):
+    provider = api.service("provider")
+
+    async def summarize(text: str, context: ToolContext) -> str:
+        """Summarize a text in three sentences.
+
+        Args:
+            text: The text to summarize.
+        """
+        writer = Agent(
+            provider=provider,
+            model=api.options.get("model") or context.agent_context.model,
+            system_prompt="Summarize the text in three sentences.",
+        )
+        result = await context.run_agent(writer, text)  # 中止主运行时，这次调用一起中止
+        reply = "".join(getattr(block, "text", "") for block in result.messages[-1].content)
+        if result.status != "completed" or not reply:
+            raise RuntimeError(f"The summary failed: {result.status}")
+        return reply
+
+    api.add_tool(summarize)
+```
+
+应用传入 `services={"provider": provider}`；想让名为 `summary` 的插件用便宜一些的模型，再传 `options={"summary": {"model": "claude-haiku-4-5"}}`。不给这个选项时，用调用这个工具的 agent 的模型。在工具里用 `context.run_agent` 运行这次调用，这样中止主运行时它也会中止。模型调用可有可无时，用 `api.service("provider", default=None)`，并在插件文档里写明没有 provider 时会怎样。
+
+## 跨对话的记忆
+
+本库和 Pi 的核心都没有内置记忆。Pi 的应用靠三样东西记住信息：读进系统提示的说明文件（`AGENTS.md`）、保存的会话和上下文压缩。哪些信息值得记、存在哪里，各个应用差别很大。插件可以用两部分加上记忆：把事实存进应用指定位置的工具，以及一个 `transform_context` 处理函数，在每次请求时把已存的事实放进去。
+
+[examples/plugins/memory](../../examples/plugins/memory) 用一个文件实现了这种做法，[examples/memory_demo.py](../../examples/memory_demo.py) 离线运行它：
+
+```python
+async with load_plugins(
+    ["./examples/plugins/memory"],
+    services={"provider": provider},  # 可选：列表满了时用来合并事实
+    options={"memory": {"path": "memory.json", "max_facts": 50}},
+) as plugins:
+    agent = plugins.agent(provider=provider, model="claude-sonnet-5-5")
+```
+
+- 模型用 `remember` 保存一条事实，用 `forget` 删除一条。事实保存在 JSON 文件里。
+- 每次请求之前，这些事实成为系统提示里名为 `memory` 的一段（`SystemMessage.sections`）。保存的对话不变。只有事实变化时这一段才变，所以两次变化之间，提示缓存的前缀一直有效。
+- 新事实会让列表超过 `max_facts` 时，插件请模型合并列表，做法见[在插件里调用模型](#在插件里调用模型)。没有 provider 时，删掉最早的事实。
+
+复制这个目录，再按应用的需要修改：哪些信息值得存，事实太多、无法全部列出时怎样检索，或者用数据库代替文件。这个示例假定同一时间只有一个进程写这个文件。
+
 ## 与 Pi 的差别
 
 Pi 的命令行程序负责查找和加载 package；本库没有应用程序，所以要加载哪些插件由你的代码指定。其他差别：

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/docs/zh/PLUGIN_DEVELOPMENT.md

@@ -222,6 +222,7 @@ Windows 下把 `.venv-installed/bin/python` 换成 `.venv-installed/Scripts/pyth
 | 与插件生命周期绑定的异步工作 | 先注册所用资源的清理，再创建 `scope = api.task_scope()`。带 `ToolContext` 参数的异步工具中，用 `await scope.run(client.fetch(...), cancel=context.cancel)` 调用。使用时声明 `task-scope-v1`。 |
 | 工作线程访问绑定事件循环的连接 | 宿主在连接所属循环创建 `LoopPortal`，通过 service 传入。同步工具用 `portal.call(async_function, ...)`。见 [API](API.md)。 |
 | 钩子 | 注册 `@api.on("before_tool_call")`，返回 `False` 阻止调用。按[文档签名](API.md)实现，并验证被阻止的路径。 |
+| 插件内调用模型 | 用 `provider = api.service("provider")` 取得 Provider；模型取 `api.options.get("model")`，没有时用 `context.agent_context.model`。在异步工具里执行 `await context.run_agent(Agent(provider=provider, model=...), text)`。见[在插件里调用模型](PLUGINS.md#在插件里调用模型)。 |
 | 子 Agent | 添加 `agents/reviewer.md`，包含 `name`、`description`、可选 `tools`/`model` 和系统提示正文。见 [lab_tools 示例](../../examples/plugins/lab_tools)。 |
 | MCP 服务 | 添加 `mcp.json` 或调用 `api.add_mcp_server`。安装 `[mcp]`，并在 readiness 中要求对应服务和工具。宿主模型或表单回调按 [MCP 交互流程](MCP_INTERACTION.md)配置。 |
 

pi_python_core-0.10.1/examples/memory_demo.py

@@ -0,0 +1,62 @@
+"""Long-term memory with a plugin: a fact saved in one conversation is used in the next.
+
+The plugin in examples/plugins/memory keeps facts in a JSON file and puts them in the
+system prompt of every request. Each conversation below opens its own plugin set, as a
+new process would. The model is scripted so this runs offline.
+
+    python examples/memory_demo.py
+"""
+
+import asyncio
+import json
+import tempfile
+from pathlib import Path
+
+from pi_python import AssistantMessage, ScriptedProvider, ToolCall
+from pi_python.plugins import load_plugins
+
+PLUGIN = Path(__file__).parent / "plugins" / "memory"
+
+
+def call(tool: str, **args) -> AssistantMessage:
+    return AssistantMessage([ToolCall(f"call-{tool}", tool, args)], "tool_use")
+
+
+async def conversation(provider: ScriptedProvider, options: dict, text: str) -> None:
+    # The plugin merges facts with a model call when its list is full; it gets the
+    # Provider as a service, so the application decides which models plugins may use.
+    async with load_plugins([PLUGIN], services={"provider": provider}, options=options) as plugins:
+        agent = plugins.agent(provider=provider, system_prompt="You are a project assistant.")
+        result = await agent.prompt(text)
+        assert result.status == "completed", result.errors
+
+
+async def main() -> None:
+    path = Path(tempfile.mkdtemp()) / "memory.json"
+    options = {"memory": {"path": str(path), "max_facts": 2}}
+
+    first = ScriptedProvider(
+        [call("remember", fact="The paper deadline is Friday."), AssistantMessage.text("Noted.")]
+    )
+    await conversation(first, options, "Remember: the paper deadline is Friday.")
+    print("saved:", json.loads(path.read_text(encoding="utf-8"))["facts"])
+
+    second = ScriptedProvider(
+        [
+            call("remember", fact="The paper deadline moved to Monday."),
+            call("remember", fact="Use the ACM template."),
+            # The list would hold 3 facts, more than max_facts, so the plugin asks the
+            # model to merge them; this reply is that merge.
+            AssistantMessage.text("The paper deadline is Monday.\nUse the ACM template."),
+            AssistantMessage.text("Noted: Monday, ACM template."),
+        ]
+    )
+    await conversation(second, options, "The deadline moved to Monday. Also use the ACM template.")
+    system = second.requests[0].messages[0]
+    print("memory in the next conversation's system prompt:")
+    print("  " + system.sections["memory"].replace("\n", "\n  "))
+    print("after merging:", json.loads(path.read_text(encoding="utf-8"))["facts"])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pi_python_core-0.10.1/examples/plugins/memory/plugin.py

@@ -0,0 +1,138 @@
+"""An example plugin: facts saved in one conversation are known in the next.
+
+The facts live in the JSON file named by the `path` option. The model saves a fact with
+`remember` and removes a wrong or outdated one with `forget`. Before every model request,
+the facts become the "memory" section of the system prompt; the stored conversation is
+not changed. The section changes only when the facts do, so the cached prompt prefix
+stays valid between changes.
+
+When a new fact would make the list longer than `max_facts` (default 50), `remember`
+asks a model to merge the list. That call uses the Provider the application passes as
+the "provider" service, with the model named by the `model` option, or else the calling
+agent's model. Without a provider, or when merging does not shorten the list, the oldest
+facts are dropped.
+
+The plugin does not decide what is worth remembering beyond what the model saves, and
+it assumes one process writes the file at a time. Adapt both to your application.
+"""
+
+import asyncio
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from pi_python import Agent, ConfigurationError, SystemMessage, ToolContext
+
+__version__ = "0.1.0"
+
+MERGE_PROMPT = (
+    "You maintain a list of saved facts. Merge facts that say the same thing and drop"
+    " facts that a later fact makes outdated. Reply with the remaining facts, one per"
+    " line, and nothing else."
+)
+
+
+def setup(api):
+    if "path" not in api.options:
+        raise ConfigurationError(
+            f"The memory plugin needs a file: options={{{api.name!r}: {{'path': ...}}}}"
+        )
+    path = Path(api.options["path"]).expanduser()
+    max_facts = api.options.get("max_facts", 50)
+    if type(max_facts) is not int or max_facts < 1:
+        raise ConfigurationError("max_facts must be a positive integer")
+    provider = api.service("provider", default=None)
+    facts: list[str] = load(path)
+    lock = asyncio.Lock()  # tool calls can run in parallel
+
+    async def shorten(updated: list[str], context: ToolContext) -> list[str]:
+        if provider is not None:
+            merger = Agent(
+                provider=provider,
+                model=api.options.get("model") or context.agent_context.model,
+                system_prompt=MERGE_PROMPT,
+            )
+            # run_agent ties the call to this tool call: aborting the run aborts it.
+            result = await context.run_agent(merger, "\n".join(updated))
+            reply = "".join(getattr(b, "text", "") for b in result.messages[-1].content)
+            merged = [re.sub(r"^\s*(?:[-*]|\d+[.)])\s*", "", line) for line in reply.splitlines()]
+            merged = [line for line in merged if line]
+            if result.status == "completed" and 0 < len(merged) < len(updated):
+                updated = merged
+        return updated[-max_facts:]
+
+    async def remember(fact: str, context: ToolContext) -> str:
+        """Save a fact that should still be known in later conversations.
+
+        Args:
+            fact: One short, self-contained statement, such as "The paper deadline is Friday".
+        """
+        fact = " ".join(fact.split())
+        if not fact:
+            return "Nothing saved: the fact is empty."
+        async with lock:
+            if fact in facts:
+                return f"Already saved as fact {facts.index(fact) + 1}."
+            updated = [*facts, fact]
+            if len(updated) > max_facts:
+                updated = await shorten(updated, context)
+            save(path, updated)
+            facts[:] = updated
+        return f"Saved. Facts in memory: {len(facts)}."
+
+    async def forget(number: int) -> str:
+        """Remove a saved fact that is wrong or outdated.
+
+        Args:
+            number: The fact's number in the memory section of the system prompt.
+        """
+        async with lock:
+            if not 1 <= number <= len(facts):
+                return f"There is no fact {number}. Facts in memory: {len(facts)}."
+            removed = facts[number - 1]
+            updated = facts[: number - 1] + facts[number:]
+            save(path, updated)  # change the list only after the file is written
+            facts[:] = updated
+        return f"Removed: {removed}"
+
+    api.add_tool(remember)
+    api.add_tool(forget)
+    api.add_system_prompt(
+        "When the user states a fact or preference that should be known in later"
+        " conversations, save it with remember. Remove saved facts that turn out wrong"
+        " with forget."
+    )
+
+    @api.on("transform_context")
+    def show_memory(messages, cancel):
+        # The messages are a copy for this request; changing them changes only what the
+        # model receives. Agents from a plugin set have a leading system message.
+        if not facts or not messages or not isinstance(messages[0], SystemMessage):
+            return None
+        listed = "\n".join(f"{i}. {fact}" for i, fact in enumerate(facts, 1))
+        messages[0].sections["memory"] = (
+            "Facts saved in earlier conversations, numbered for forget:\n" + listed
+        )
+        return messages
+
+    api.add_check(lambda: path.parent.is_dir(), "directory_exists")
+
+
+def load(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    data = json.loads(path.read_text(encoding="utf-8"))
+    facts = data.get("facts") if isinstance(data, dict) else None
+    if not isinstance(facts, list) or not all(isinstance(f, str) for f in facts):
+        raise ConfigurationError(f"{path}: facts must be a list of strings")
+    return facts
+
+
+def save(path: Path, facts: list[str]) -> None:
+    """Write atomically, so a crash never leaves half a file."""
+    fd, temporary = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    with os.fdopen(fd, "w", encoding="utf-8") as file:
+        json.dump({"facts": facts}, file, ensure_ascii=False, indent=2)
+    os.replace(temporary, path)

{pi_python_core-0.10.0 → pi_python_core-0.10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pi-python-core"
-version = "0.10.0"
+version = "0.10.1"
 description = "An embeddable asyncio agent core with opt-in Claude and OpenAI providers"
 readme = "README.md"
 requires-python = ">=3.11"

pi_python_core-0.10.1/src/pi_python/_version.py

@@ -0,0 +1 @@
+__version__ = "0.10.1"