penhin 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- penhin-0.1.1/AGENTS.md +11 -0
- penhin-0.1.1/CONTEXT.md +71 -0
- penhin-0.1.1/LICENSE +21 -0
- penhin-0.1.1/MANIFEST.in +2 -0
- penhin-0.1.1/PKG-INFO +407 -0
- penhin-0.1.1/README.md +373 -0
- penhin-0.1.1/examples/bounded_embedding.py +59 -0
- penhin-0.1.1/examples/checkpoint_benchmark.py +60 -0
- penhin-0.1.1/examples/context_management.py +143 -0
- penhin-0.1.1/examples/embedding.py +113 -0
- penhin-0.1.1/examples/session_benchmark.py +156 -0
- penhin-0.1.1/examples/shared_plugin.py +14 -0
- penhin-0.1.1/penhin.egg-info/PKG-INFO +407 -0
- penhin-0.1.1/penhin.egg-info/SOURCES.txt +87 -0
- penhin-0.1.1/penhin.egg-info/dependency_links.txt +1 -0
- penhin-0.1.1/penhin.egg-info/requires.txt +28 -0
- penhin-0.1.1/penhin.egg-info/top_level.txt +1 -0
- penhin-0.1.1/pyproject.toml +53 -0
- penhin-0.1.1/setup.cfg +4 -0
- penhin-0.1.1/src/__init__.py +61 -0
- penhin-0.1.1/src/_async.py +53 -0
- penhin-0.1.1/src/_atomic.py +41 -0
- penhin-0.1.1/src/_checkpoints.py +92 -0
- penhin-0.1.1/src/agent.py +497 -0
- penhin-0.1.1/src/auth/__init__.py +31 -0
- penhin-0.1.1/src/auth/browser.py +31 -0
- penhin-0.1.1/src/auth/interaction.py +8 -0
- penhin-0.1.1/src/auth/models.py +70 -0
- penhin-0.1.1/src/auth/oauth/__init__.py +5 -0
- penhin-0.1.1/src/auth/oauth/_flows.py +447 -0
- penhin-0.1.1/src/auth/providers.py +82 -0
- penhin-0.1.1/src/auth/resolver.py +45 -0
- penhin-0.1.1/src/auth/secrets.py +83 -0
- penhin-0.1.1/src/auth/service.py +70 -0
- penhin-0.1.1/src/auth/storage.py +261 -0
- penhin-0.1.1/src/budget.py +111 -0
- penhin-0.1.1/src/cancellation.py +95 -0
- penhin-0.1.1/src/context/__init__.py +13 -0
- penhin-0.1.1/src/context/_preparation.py +240 -0
- penhin-0.1.1/src/context/compaction.py +194 -0
- penhin-0.1.1/src/context/projection.py +31 -0
- penhin-0.1.1/src/context/tokens.py +111 -0
- penhin-0.1.1/src/events.py +165 -0
- penhin-0.1.1/src/execution.py +141 -0
- penhin-0.1.1/src/models/__init__.py +20 -0
- penhin-0.1.1/src/models/client.py +263 -0
- penhin-0.1.1/src/models/messages.py +128 -0
- penhin-0.1.1/src/models/profiles.py +86 -0
- penhin-0.1.1/src/models/retry.py +90 -0
- penhin-0.1.1/src/models/types.py +52 -0
- penhin-0.1.1/src/plugins.py +138 -0
- penhin-0.1.1/src/providers/__init__.py +13 -0
- penhin-0.1.1/src/providers/_payloads.py +120 -0
- penhin-0.1.1/src/providers/anthropic.py +182 -0
- penhin-0.1.1/src/providers/deepseek.py +248 -0
- penhin-0.1.1/src/providers/gemini.py +246 -0
- penhin-0.1.1/src/providers/openai.py +375 -0
- penhin-0.1.1/src/providers/registry.py +89 -0
- penhin-0.1.1/src/py.typed +0 -0
- penhin-0.1.1/src/session.py +408 -0
- penhin-0.1.1/src/tools.py +185 -0
- penhin-0.1.1/tests/test_agent.py +319 -0
- penhin-0.1.1/tests/test_auth.py +459 -0
- penhin-0.1.1/tests/test_auto_compaction.py +650 -0
- penhin-0.1.1/tests/test_budgets.py +151 -0
- penhin-0.1.1/tests/test_cancellation.py +131 -0
- penhin-0.1.1/tests/test_checkpoints.py +182 -0
- penhin-0.1.1/tests/test_client.py +96 -0
- penhin-0.1.1/tests/test_context_tokens.py +42 -0
- penhin-0.1.1/tests/test_custom_compaction.py +213 -0
- penhin-0.1.1/tests/test_deepseek_provider.py +214 -0
- penhin-0.1.1/tests/test_events.py +111 -0
- penhin-0.1.1/tests/test_execution.py +234 -0
- penhin-0.1.1/tests/test_gemini_provider.py +107 -0
- penhin-0.1.1/tests/test_messages.py +84 -0
- penhin-0.1.1/tests/test_model_connection.py +253 -0
- penhin-0.1.1/tests/test_model_profiles.py +308 -0
- penhin-0.1.1/tests/test_openai_provider.py +100 -0
- penhin-0.1.1/tests/test_plugins.py +93 -0
- penhin-0.1.1/tests/test_provider_contracts.py +115 -0
- penhin-0.1.1/tests/test_provider_metadata.py +443 -0
- penhin-0.1.1/tests/test_responses_providers.py +210 -0
- penhin-0.1.1/tests/test_revision_hint.py +100 -0
- penhin-0.1.1/tests/test_session_compatibility.py +82 -0
- penhin-0.1.1/tests/test_session_context.py +154 -0
- penhin-0.1.1/tests/test_session_metadata.py +111 -0
- penhin-0.1.1/tests/test_session_view.py +109 -0
- penhin-0.1.1/tests/test_streaming.py +98 -0
- penhin-0.1.1/tests/test_tools.py +89 -0
penhin-0.1.1/AGENTS.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Repository guide
|
|
2
|
+
|
|
3
|
+
Read `CONTEXT.md` for domain terms. Before changing execution or module boundaries, read the relevant contracts in `README.md`.
|
|
4
|
+
|
|
5
|
+
Source files live directly in `src/`; setuptools maps that directory to the `penhin` import package. Do not add a second `src/penhin/` layer. Keep business tools, prompts, UI and workspace discovery in hosts or examples.
|
|
6
|
+
|
|
7
|
+
Install in an isolated virtual environment using the commands in README's installation section; its strict editable mode keeps the `src/` mapping discoverable by static analysis. Refresh the editable install after adding or renaming modules. Current penhin-code uses the `penhin_code` namespace and embeds this core in both CLI entrypoints. Older releases occupying the `penhin` namespace require a separate environment.
|
|
8
|
+
|
|
9
|
+
Validate changes with `python -m pytest -q`, `python -m ruff check src tests examples`, `python -m ruff format --check src tests examples`, and `python examples/embedding.py`. Tests use fake providers and HTTP transports; do not require real credentials or paid requests. Build changes also need `python -m build` and a wheel import check outside this checkout.
|
|
10
|
+
|
|
11
|
+
Preserve store-before-publish ordering, invocation correlation, and refusal to replay uncertain side effects. Plugin code is trusted in-process code; do not describe permission hooks as a sandbox. Changes to the core execution contract need behavioral tests.
|
penhin-0.1.1/CONTEXT.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Penhin
|
|
2
|
+
|
|
3
|
+
Penhin 是供不同应用嵌入和扩展的 Agent 内核,负责复用执行机制,不预装业务能力。
|
|
4
|
+
|
|
5
|
+
## Host
|
|
6
|
+
|
|
7
|
+
嵌入 Penhin 的应用。Host 拥有业务状态、界面、身份提示、权限判断和依赖的生命周期。
|
|
8
|
+
|
|
9
|
+
## Agent
|
|
10
|
+
|
|
11
|
+
使用模型生成响应并依序执行工具的运行对象。一个 Agent 同时只运行一个 Session;运行策略由 Host 注入。
|
|
12
|
+
|
|
13
|
+
## Session
|
|
14
|
+
|
|
15
|
+
模型消息、待执行工具、等待请求与元数据的版本化执行状态。SessionStore 负责原子保存和历史读取,状态不等于业务数据库。
|
|
16
|
+
|
|
17
|
+
## SessionView
|
|
18
|
+
|
|
19
|
+
Host 可据以判断下一步操作的会话状态视图,区分可接收新消息、正在运行、可继续、等待回复与结果待核对。它描述当前 Session 拥有者看到的状态,不代表其他拥有者已经同步。
|
|
20
|
+
|
|
21
|
+
## Tool
|
|
22
|
+
|
|
23
|
+
模型可调用的命名能力,包含版本、描述、类型化参数和 handler。Schema 与执行校验来自同一参数模型;内核没有预装 Tool。
|
|
24
|
+
|
|
25
|
+
## Plugin
|
|
26
|
+
|
|
27
|
+
可复用的 Python 能力集合,通过工厂接收 Host 的依赖。它可以贡献 Tool、上下文变换、观察者与生命周期回调。
|
|
28
|
+
|
|
29
|
+
## PluginRuntime
|
|
30
|
+
|
|
31
|
+
持有当前显式启用 Plugin 的对象。它负责贡献注册、命名与生命周期,不是子进程管理器或安全隔离边界。
|
|
32
|
+
|
|
33
|
+
## Context
|
|
34
|
+
|
|
35
|
+
一次模型请求的系统提示与消息投影。Host 可以变换 Context,而不修改 Session 中的历史执行事实。
|
|
36
|
+
|
|
37
|
+
## WaitRequest
|
|
38
|
+
|
|
39
|
+
需要 Host 回复的关联请求。它可以表示执行许可或工具发出的业务问题,内核不规定展示方式。
|
|
40
|
+
|
|
41
|
+
## Provider
|
|
42
|
+
|
|
43
|
+
负责模型协议适配的对象,将 SDK 或 HTTP 响应归一化为 LLMResponse。
|
|
44
|
+
|
|
45
|
+
## AuthService
|
|
46
|
+
|
|
47
|
+
负责凭据解析、登录、刷新与存储的服务。登录交互和存储选择由 Host 决定。
|
|
48
|
+
|
|
49
|
+
## ModelClient
|
|
50
|
+
|
|
51
|
+
持有当前 Provider 连接,管理调用重试、可选熔断与对话续接状态。需要刷新凭据时调用 AuthService,再替换并关闭旧连接;也支持 Host 直接注入 Provider。
|
|
52
|
+
|
|
53
|
+
## ModelExecutor
|
|
54
|
+
|
|
55
|
+
Host 持有的模型调用容量与线程生命周期。多个独立 ModelClient 可共享同一事件循环内的执行器,限制运行数和排队数;取消不提前释放仍由工作线程使用的名额。它不拥有 Provider,也不替代网络超时。
|
|
56
|
+
|
|
57
|
+
## ResourceBudget
|
|
58
|
+
|
|
59
|
+
Host 为 Agent 显式配置的请求容量与工具结果大小约束。检查的是发送给模型的投影;如何摘要、存放外部结果和处理超限由 Host 决定。预算失败不允许遗失已完成的工具结果或倒退执行游标。
|
|
60
|
+
|
|
61
|
+
## Provider Metadata
|
|
62
|
+
|
|
63
|
+
模型服务返回的描述性信息,例如实际模型、用量细节、完成原因与安全评级。它供 Host 观察和记录,本身不是下一轮对话的输入。
|
|
64
|
+
|
|
65
|
+
## ModelProfile
|
|
66
|
+
|
|
67
|
+
某个 Provider 下已核对型号的上下文容量、输出上限与 thinking 设置。它是带核对日期的离线能力资料,不是账号可用模型清单;Host 仍选择模型,未知型号仍可调用。ModelClient 用它填充默认上下文容量,Provider 用它校验参数。
|
|
68
|
+
|
|
69
|
+
## Provider Replay Data
|
|
70
|
+
|
|
71
|
+
与一条模型消息绑定、供原 Provider 继续对话的协议数据,例如带签名的思考块或加密 reasoning。它属于会话历史,不能作为普通文本任意改写或交给其他 Provider 解释。
|
penhin-0.1.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 penhin 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.
|
penhin-0.1.1/MANIFEST.in
ADDED
penhin-0.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: penhin
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: A lightweight, embeddable agent core with composable capabilities and in-process plugins.
|
|
5
|
+
Author: penhin contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/penhin/penhin
|
|
8
|
+
Requires-Python: >=3.11
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: pydantic<3,>=2.11
|
|
12
|
+
Requires-Dist: httpx<1,>=0.28
|
|
13
|
+
Requires-Dist: filelock<4,>=3.16
|
|
14
|
+
Provides-Extra: anthropic
|
|
15
|
+
Requires-Dist: anthropic<3,>=2.1; extra == "anthropic"
|
|
16
|
+
Provides-Extra: openai
|
|
17
|
+
Requires-Dist: openai<4,>=3.37; extra == "openai"
|
|
18
|
+
Provides-Extra: gemini
|
|
19
|
+
Requires-Dist: google-genai<4,>=3.3; extra == "gemini"
|
|
20
|
+
Provides-Extra: keyring
|
|
21
|
+
Requires-Dist: keyring<26,>=25; extra == "keyring"
|
|
22
|
+
Provides-Extra: providers
|
|
23
|
+
Requires-Dist: anthropic<3,>=2.1; extra == "providers"
|
|
24
|
+
Requires-Dist: openai<4,>=3.37; extra == "providers"
|
|
25
|
+
Requires-Dist: google-genai<4,>=3.3; extra == "providers"
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest<10,>=8; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
|
|
29
|
+
Requires-Dist: ruff<1,>=0.11; extra == "dev"
|
|
30
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
31
|
+
Requires-Dist: mypy<3,>=1.11; extra == "dev"
|
|
32
|
+
Requires-Dist: twine<7,>=6; extra == "dev"
|
|
33
|
+
Dynamic: license-file
|
|
34
|
+
|
|
35
|
+
# Penhin
|
|
36
|
+
|
|
37
|
+
A lightweight, embeddable agent core with composable capabilities and in-process plugins.
|
|
38
|
+
|
|
39
|
+
Penhin 是可嵌入的 Python Agent 内核。宿主提供身份、界面、业务工具和权限策略;内核处理模型调用、工具执行、会话、等待恢复与插件组合。
|
|
40
|
+
|
|
41
|
+
业务工具、角色和交互流程由宿主直接注入,或封装为可复用的 Plugin。Plugin 在当前 Python 进程内运行。[penhin-code](https://github.com/penhin/penhin-code) 是基于这个内核的 coding CLI。
|
|
42
|
+
|
|
43
|
+
## 安装与体验
|
|
44
|
+
|
|
45
|
+
Python 3.11+,可以直接安装:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
python -m pip install penhin
|
|
49
|
+
# 需要三个模型 SDK 和系统钥匙串时:
|
|
50
|
+
python -m pip install "penhin[providers,keyring]"
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
应用可以在自己的 `pyproject.toml` 中声明标准依赖,由 pip 或 uv 自动下载安装:
|
|
54
|
+
|
|
55
|
+
```toml
|
|
56
|
+
[project]
|
|
57
|
+
dependencies = ["penhin[providers,keyring]>=0.1.1,<0.2"]
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
安装后使用 `from penhin import Agent, ModelClient, Session`,应用无需克隆本仓库。基础包只依赖 Pydantic、HTTPX 和 FileLock;按需增加 `openai`、`anthropic`、`gemini`、`keyring` extras,`providers` 同时安装三个模型 SDK。DeepSeek 使用 `openai` extra;实验性的 `openai-codex` HTTP 适配器无需模型 SDK。
|
|
61
|
+
|
|
62
|
+
### 从源码开发与运行示例
|
|
63
|
+
|
|
64
|
+
克隆本仓库并进入目录,在独立虚拟环境安装源码和开发依赖:
|
|
65
|
+
|
|
66
|
+
```sh
|
|
67
|
+
python -m venv .venv
|
|
68
|
+
# 激活环境后:
|
|
69
|
+
python -m pip install --config-settings editable_mode=strict -e ".[dev,providers,keyring]"
|
|
70
|
+
python examples/embedding.py
|
|
71
|
+
python -m pytest -q
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`embedding.py` 不调用网络,也不需要凭据。它用确定性的模型替身演示两种宿主:文档助手写入临时文件,跑团助手等待 KP 批准后修改人物卡。两者共享同一份 `notes` Plugin。示例代码位于 [examples/embedding.py](examples/embedding.py)。
|
|
75
|
+
|
|
76
|
+
仅开发基础包时可以使用 `pip install --config-settings editable_mode=strict -e .`。
|
|
77
|
+
|
|
78
|
+
### IDE 与源码导入
|
|
79
|
+
|
|
80
|
+
也可以运行 `uv sync --extra dev --extra providers --extra keyring`,创建本仓库的 `.venv`。VS Code 的仓库配置默认选择这个环境;如果之前选过其他解释器,执行 `Python: Select Interpreter` 选择当前仓库的 `.venv`,再执行 `Python: Restart Language Server`。
|
|
81
|
+
|
|
82
|
+
本项目将 `src/` 映射到 `penhin` 包名。setuptools 默认 editable 安装可能生成 Pylance/Pyright 无法解析的动态 import hook,因此 uv 已配置 `editable_mode=strict`,pip 安装时也应保留该选项。strict 模式生成可被静态分析器读取的路径和源码链接,编辑已有文件会立即生效。
|
|
83
|
+
|
|
84
|
+
新增或重命名模块后,运行 `uv sync --extra dev --extra providers --extra keyring --reinstall-package penhin`;使用 pip 时重新执行上面的 editable 安装命令。开发期间保留 `build/__editable__.*`,删除 `build/` 后也需要重新安装。
|
|
85
|
+
|
|
86
|
+
## 最小接入
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
import asyncio
|
|
90
|
+
import os
|
|
91
|
+
from typing import Annotated
|
|
92
|
+
from pydantic import Field
|
|
93
|
+
from penhin import Agent, ModelClient, Session, tool
|
|
94
|
+
|
|
95
|
+
@tool
|
|
96
|
+
def set_hp(name: str, hp: Annotated[int, Field(ge=0)]) -> dict:
|
|
97
|
+
"""Update a character through the host application."""
|
|
98
|
+
# 实际项目在这里调用自己的业务服务。
|
|
99
|
+
return {"name": name, "hp": hp}
|
|
100
|
+
|
|
101
|
+
async def main():
|
|
102
|
+
# OPENAI_API_KEY 由宿主提供;模型名称由调用者选择。
|
|
103
|
+
with ModelClient.connect("openai", os.environ["MODEL_ID"]) as model:
|
|
104
|
+
agent = Agent(model, system="Help the keeper run the game.", tools=[set_hp])
|
|
105
|
+
result = await agent.run(Session(), "Set Ada's HP to 7.")
|
|
106
|
+
print(result.text)
|
|
107
|
+
|
|
108
|
+
asyncio.run(main())
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`Agent.run()` 是异步接口;同步脚本可调用 `run_sync()`。默认每次模型调用使用独立工作线程,同步工具和观察者使用事件循环的默认线程池,异步工具直接等待。模型线程不会占用其流式观察者需要的线程池;工作线程沿用宿主的 contextvars。每个并发运行使用独立的 Agent、ModelClient 和 Session。Provider 可替换:实现 `penhin.providers.LLMProvider`,传给 `ModelClient(provider, model_name)` 即可。
|
|
112
|
+
|
|
113
|
+
## 多会话并发
|
|
114
|
+
|
|
115
|
+
宿主可以让多个 ModelClient 共用一个 `ModelExecutor`,限制同时运行和等待中的模型调用:
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
from penhin import ModelExecutor
|
|
119
|
+
|
|
120
|
+
# provider_a/provider_b 由宿主构造,每个并发会话使用自己的客户端。
|
|
121
|
+
with ModelClient(provider_a, model_name) as model_a, \
|
|
122
|
+
ModelClient(provider_b, model_name) as model_b:
|
|
123
|
+
async with ModelExecutor(max_concurrency=4, max_queue=32) as execution:
|
|
124
|
+
model_a.execution = model_b.execution = execution
|
|
125
|
+
results = await asyncio.gather(
|
|
126
|
+
Agent(model_a).run(Session(), "first task"),
|
|
127
|
+
Agent(model_b).run(Session(), "second task"),
|
|
128
|
+
)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
队列按先入先出分配名额;排队前不会提交线程工作。队列满时抛出 `ModelQueueFull`,排队取消不会向 Provider 发请求;Agent 已保存的用户输入仍可用 `run(session)` 继续。`active`、`queued` 可供宿主观察。重试与流式回调期间也占用名额,避免在下游故障时无限增加请求。
|
|
132
|
+
|
|
133
|
+
`aclose()` 或退出上下文后拒绝新请求,排队任务收到 `ModelExecutorClosed`,已开始的调用排空后再关闭线程池;宿主随后关闭仍在使用的 Provider/插件依赖。执行器属于首次使用它的事件循环,不能跨循环共享,也不能跨多次 `run_sync()` 复用。它没有全局实例,可按应用、模型服务或租户创建独立限制组。
|
|
134
|
+
|
|
135
|
+
Agent、`ModelClient.acall_with_retry()`、`acompact()` 与 `model_summarizer()` 都遵守这一限制。原同步 `call_with_retry()` / `call_compact_once()` 保持直接调用,不经过异步队列。离线接入示例 `python examples/bounded_embedding.py` 同时演示共享容量和下面的资源预算。
|
|
136
|
+
|
|
137
|
+
## 工具与 Schema
|
|
138
|
+
|
|
139
|
+
`@tool` 从 Python 注解生成 JSON Schema,并用相同的 Pydantic 模型进行严格执行校验:字符串 `"7"` 不会自动变成整数,未知顶层字段会被拒绝。支持 `Annotated[..., Field(...)]`、默认值、可空类型、枚举、Literal、列表和嵌套模型。复杂输入使用 `ToolInput` 子类与 `Tool.from_model(name, description, Parameters, handler)`;handler 接收 `(parameters, context)`。嵌套对象也继承 `ToolInput`,即可获得一致的未知字段检查。
|
|
140
|
+
|
|
141
|
+
参数注解为 `ToolContext` 时,内核自动注入会话 ID、调用 ID、取消信号和元数据,该参数不出现在模型 Schema 中。工具返回 JSON 值、Pydantic 模型、`ToolResult`,或者 `ToolWait(payload)`。未知工具、参数错误、拒绝和普通工具异常均作为关联到原调用的工具结果返回给模型。
|
|
142
|
+
|
|
143
|
+
Schema 是传输与本地校验的共同来源;各 Provider 的服务端 Schema 支持仍存在差异,本地严格校验始终执行。工具实现的行为发生不兼容变化时,必须提升 `version`。
|
|
144
|
+
|
|
145
|
+
## Plugin
|
|
146
|
+
|
|
147
|
+
```python
|
|
148
|
+
from penhin import Plugin, PluginRuntime, load_plugin
|
|
149
|
+
|
|
150
|
+
# 普通 Python 模块的工厂函数返回 Plugin;依赖由宿主注入。
|
|
151
|
+
plugin = load_plugin("my_plugin:create", world=my_world_service)
|
|
152
|
+
plugins = PluginRuntime()
|
|
153
|
+
await plugins.activate(plugin)
|
|
154
|
+
agent = Agent(model, plugins=plugins)
|
|
155
|
+
# …完成当前运行后:
|
|
156
|
+
await plugins.deactivate(plugin.name)
|
|
157
|
+
await plugins.close()
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Plugin 可以贡献工具、上下文变换、事件观察者以及 startup/shutdown 回调。工具自动命名为 `plugin__tool`;等待期间停用插件或改变版本后,旧调用不能继续执行。运行过程中拒绝激活/停用,避免在工具使用资源时拆除资源;使用 `async with PluginRuntime()` 可自动清理。
|
|
161
|
+
|
|
162
|
+
第三方包可以声明 `[project.entry-points."penhin.plugins"]`,例如 `notes = "my_plugin:create"`。`discover_plugins()` 仅列出已安装入口名称,`load_plugin("notes", ...)` 才导入代码,`activate()` 才将能力加入目录。包安装交给 pip,不包含独立安装器、子进程 Host、自动扫描激活或沙箱。插件是宿主信任的 Python 代码,与宿主共享进程权限。
|
|
163
|
+
|
|
164
|
+
## 许可、等待与恢复
|
|
165
|
+
|
|
166
|
+
宿主可传入 `permission(tool, arguments, context)`,返回 `Permission("allow")`、`Permission("deny", payload)` 或 `Permission("wait", payload)`。未提供策略时,显式注册的工具允许执行。内核不解释业务权限,也不实现批准 UI。
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
result = await agent.run(session, "Change the battlefield.")
|
|
170
|
+
if result.status == "waiting":
|
|
171
|
+
# 宿主展示 result.waiting.payload,并取得真实回复。
|
|
172
|
+
result = await agent.resume(session, result.waiting.id, host_answer)
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
许可等待的回复必须是 bool;工具自己返回的 `ToolWait` 接受 JSON 值或 `ToolResult` 作为最终结果,不重跑 handler。许可批准只对当前调用有效;恢复时重新检查工具契约和当前拒绝策略。
|
|
176
|
+
|
|
177
|
+
`Session()` 默认使用实例内存。持久化使用 `Session(FileSessionStore(path))`,然后通过 `Session.load(store, id)` 恢复。文件存储采用带版本号的 JSON 检查点、文件锁和原子替换;多个会话拥有者提交冲突时抛出 `SessionConflict`。支持 `store.list()`、`history()`、`load(id, revision)`、`session.fork()`、`restore(revision)`,恢复历史不会撤销外部副作用。自定义数据库实现 `SessionStore`,必须保留 `expected_revision` 的原子比较语义。
|
|
178
|
+
|
|
179
|
+
宿主用 `session.update_metadata(name="my task", workflow={"step": 2})` 保存自己的 JSON 数据,异步宿主使用 `await session.aupdate_metadata(...)`。每次更新整体替换指定的顶层键,保留其它键;`None` 保存为 JSON null,不表示删除,空更新不产生版本。内核统一加锁、校验数据、递增 revision 并在保存成功后发布本地状态;失败不会提前更改内存,运行中或过期的 Session 抛出 `SessionConflict`。异步取消会等待正在进行的提交完成,因此收到取消也应检查已提交状态。等待审批期间可以更新 metadata,但接口不修改消息、待执行工具、等待请求或执行游标。字段的业务含义始终由宿主定义。
|
|
180
|
+
|
|
181
|
+
内置 Memory/File Store 默认最多间隔 32 个版本保存一个完整快照,中间检查点记录相对该完整快照的消息尾部和字段变更;增量不比完整快照小时直接保存完整快照。读取任意版本最多访问两个检查点,仍保留全部 history/fork/restore 语义。`checkpoint_interval=1` 可选择后续全部写完整快照。
|
|
182
|
+
|
|
183
|
+
File Store 在检查点成功保存后更新可重建的 `.head` 版本提示。正常最新读取/保存无需枚举整个目录,指定历史版本直接定位文件;`history()` 仍枚举全部版本。提示缺失、损坏或落后时回退扫描,下次成功写入修复。提示写失败不改变已提交检查点的成功结果;检查点 JSON 始终是事实来源。内部版本文件按追加顺序保存,不支持手工删除或跳号插入;旧的无提示完整快照可直接加载。
|
|
184
|
+
|
|
185
|
+
会话状态仍为 `penhin.session/v1`,增量文件的外层标识为 `penhin.checkpoint/v1`。新实现可读取旧的完整快照并继续写入;旧实现不能读取增量文件。`checkpoint_interval=1` 不会转换已经存在的增量文件。不要手工删除完整快照,它可能被其他版本引用。
|
|
186
|
+
|
|
187
|
+
异步执行路径在工作线程中检查和提交存储,保存成功后才发布新的内存状态。自定义 Store 必须支持来自工作线程的访问,并自行保证不同 Session 之间的并发安全;线程绑定的数据库连接应由 Store 管理。异步宿主可通过 `await Session.acreate(store, metadata=...)` 创建,或 `await Session.aload(store, id)` 加载会话。取消会等待已经开始的存储操作结束;取消创建不保证回滚已经保存的新会话。同步创建、加载、分支、历史恢复接口仍会阻塞调用线程。
|
|
188
|
+
|
|
189
|
+
宿主通过 `session.inspect()` 获取 `SessionView`,不必复制完整对话或解释内部 pending 字段:
|
|
190
|
+
|
|
191
|
+
| `view.status` | 宿主操作 |
|
|
192
|
+
| --- | --- |
|
|
193
|
+
| `complete` | `can_accept_query=True`,可以传入新消息 |
|
|
194
|
+
| `running` | 当前 Session 实例正在被使用,等待操作结束 |
|
|
195
|
+
| `pending` | `can_continue=True`,用 `run(session)` 继续 |
|
|
196
|
+
| `waiting` | 查看 `view.waiting`,取得回复后调用 `resume()` |
|
|
197
|
+
| `interrupted` | 核对 `view.interrupted_call_id` 的业务结果,再记录核对结果 |
|
|
198
|
+
|
|
199
|
+
`inspect()` 是当前实例的状态视图,不刷新存储,也不是跨进程锁。`run_end` 回调发生在运行锁释放前,回调中的 inspect 仍可能显示 running;回调应使用其 RunResult。调用返回后再检查视图。遇到 `SessionConflict` 时先重新加载。视图中的等待载荷是独立副本,修改它不会更改已保存状态。
|
|
200
|
+
|
|
201
|
+
模型回复与待执行批次一次提交;工具执行前保存 `executing`,结果与游标一起提交。若进程退出或保存失败导致结果未知,再运行会抛出 `InterruptedTool`。宿主核对业务结果后调用 `agent.resolve_interrupted(session, call_id, result)`,再 `run(session)`。这避免盲目重跑,不承诺外部操作严格执行一次。
|
|
202
|
+
|
|
203
|
+
异步宿主使用 `await agent.resolve_interrupted_async(...)`,它在保存结果后交付 `tool_end`,也不自动调用模型或重跑工具。同步 `resolve_interrupted()` 只保存,不调用观察者。
|
|
204
|
+
|
|
205
|
+
`RunResult.status` 为 `complete`、`waiting`、`limit` 或 `cancelled`。达到轮次/工具次数限制后可 `run(session)` 继续。`CancellationToken.cancel()` 会唤醒当前异步运行,外部 `task.cancel()` 也会先设置同一个 token,再等待同步工作线程退出。工具可用 `ToolContext.cancellation.check()` 检查,或在同步循环中用 `wait(timeout)` 等待取消。ModelClient 的默认重试退避可被打断,不再开始下一次请求;宿主注入的自定义 `sleep` 自行负责及时返回。
|
|
206
|
+
|
|
207
|
+
正在运行的同步 Python 代码、阻塞 SDK 调用不能强制终止,宿主仍需配置传输超时。线程退出前不会释放 Session、插件租约或模型执行名额。外部任务取消发生在工具中途时,同样需要核对执行结果。直接取消异步 ModelClient 调用会传播 `CancelledError`;Agent 将运行取消转换为 `RunResult("cancelled")`。
|
|
208
|
+
|
|
209
|
+
## 上下文与事件
|
|
210
|
+
|
|
211
|
+
宿主/插件的 `transform_context(Context)` 在每次模型调用前运行,可以补充当前业务信息,返回新的 `Context`。会话记录与发送给模型的投影分离,内核不扫描 AGENTS.md、skills 或工作目录。
|
|
212
|
+
|
|
213
|
+
`Context.estimated_tokens` 提供启发式估算;不是精确 tokenizer,也不自动阻止超长请求。通过 `await agent.compact(session, Compactor(summarize, keep_recent_turns=2))` 显式压缩。`summarize(messages)` 可以由宿主提供,也可以使用 `model_summarizer(model)`。默认只在完整用户轮次处切分;设置 `keep_recent_exchanges=2` 可进一步切到最近两次完整模型交互之前,支持单个用户任务中的长工具循环。一次交互包括 assistant 消息及其整个工具结果批次,不拆开调用/结果配对;被切开的近期用户指令仍以原文保留。
|
|
214
|
+
|
|
215
|
+
Agent 的手动与自动压缩都先构造候选请求投影,摘要候选必须使完整输入估算严格变小,并通过请求预算后才能提交;手动压缩未配置预算时仍按模型容量校验。失败或仍超限都不提交,没有可压缩前缀也不创建新版本。旧版本保留在 SessionStore 中。单独调用 `Compactor.compact(messages)` 没有 Host 的投影信息,继续按消息正文估算判断缩减效果。
|
|
216
|
+
|
|
217
|
+
宿主可以继承 `Compactor`,覆写公开的异步 `compact(messages)`,例如在摘要前移除宿主已隐藏的完整轮次。手动和自动压缩都会调用这个覆写方法,即使内置切分规则找不到可压缩前缀。参数是独立的历史副本;返回候选消息列表,不直接修改 Session。候选必须保留完整的工具调用/结果配对;内核统一保留被移除的调用 ID、清理旧 usage、校验投影和预算,并在保存成功后发布状态、清除 continuation 和交付 `compact_end`。有调用 ID 需要归档时,候选至少保留一条承载内部元数据的消息。
|
|
218
|
+
|
|
219
|
+
仅清理已隐藏历史是允许等大提交的特例:候选必须是原消息的严格有序子集,且变换后的 system 和消息投影与原请求完全相同。摘要、改写或重排不能使用这个特例,硬预算仍然生效。自定义方法返回未变的历史时,`compact_end.changed` 为 false,不创建新版本。
|
|
220
|
+
|
|
221
|
+
需要请求前保护时,显式设置预算:
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
from penhin import ResourceBudget, ToolContext, ToolResult
|
|
225
|
+
|
|
226
|
+
def reduce_result(result: ToolResult, context: ToolContext) -> ToolResult:
|
|
227
|
+
# artifact_store 是宿主的存储;内核不规定摘要规则或文件位置。
|
|
228
|
+
key = artifact_store.save(context.session_id, context.invocation_id, result.value)
|
|
229
|
+
return ToolResult(value={"artifact": key})
|
|
230
|
+
|
|
231
|
+
agent = Agent(
|
|
232
|
+
model, tools=host_tools,
|
|
233
|
+
budget=ResourceBudget(context_tokens=32000, reserve_output_tokens=4096,
|
|
234
|
+
tool_result_bytes=64 * 1024),
|
|
235
|
+
reduce_tool_result=reduce_result,
|
|
236
|
+
)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
预算默认关闭。开启后,在宿主与插件的 Context 变换完成后,按 system、消息、工具 Schema、Provider 回传数据及输出预留估算请求大小。上下文上限不超过 `model.context_window`,输出预留不低于 `model.max_tokens`。这是启发式估算,不能代替 Provider 的精确 token 校验;它也不自动增加模型输出上限。超限抛出带 `resource/actual/limit/call_id` 的 `BudgetExceeded`,请求尚未发出,宿主可先压缩或改变投影,再继续运行。
|
|
240
|
+
|
|
241
|
+
工具结果按序列化后的 UTF-8 字节计量。超限时调用可选的同步/异步 `reduce_tool_result`,传入独立副本和 ToolContext,宿主可摘要或保存为外部引用。缩减结果仍超限、回调失败或未配置回调时,内核先保存完整的已完成结果并推进游标,再报告失败;不会重跑工具。重试前仍会检查投影中的工具结果,因此宿主需要调整投影或预算后继续。这是模型请求与结果投影的预算,不是进程内存或磁盘的硬上限;也不自动截断 JSON。显式摘要调用由宿主选择输入和输出配置,不套用 Agent 的请求预算。
|
|
242
|
+
|
|
243
|
+
需要自动压缩时,显式配置 `AutoCompaction`,复用结果外置与投影裁剪:
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
from penhin import AutoCompaction, Compactor, model_summarizer
|
|
247
|
+
|
|
248
|
+
agent = Agent(
|
|
249
|
+
model, tools=host_tools,
|
|
250
|
+
budget=ResourceBudget(tool_result_bytes=64 * 1024),
|
|
251
|
+
reduce_tool_result=reduce_result,
|
|
252
|
+
transform_context=prune_old_previews, # Host 的投影函数,保留调用关联、错误状态与 artifact 引用
|
|
253
|
+
auto_compaction=AutoCompaction(
|
|
254
|
+
Compactor(model_summarizer(model, max_tokens=2048), keep_recent_exchanges=2),
|
|
255
|
+
threshold=0.8,
|
|
256
|
+
),
|
|
257
|
+
)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
顺序是:工具结果外置并保存 → 完整工具批次结束 → Host/插件 Context 变换 → 检查 80% 水位 → 生成候选摘要 → 对候选执行 Context 变换和预算校验 → 保存有效候选 → 发送已校验的请求投影。候选校验时 Session 仍保持原状态;提交后不再重复调用投影函数,避免有状态的变换改变已校验请求。未提供 `budget` 时,启用自动压缩会采用 `ResourceBudget()`;未启用自动压缩时保持显式压缩入口。投影函数应基于传入的 Context 构造结果,并能重复调用,外置存储与检索工具由 Host 持有。离线示例 `python examples/context_management.py` 演示完整组合,不需要凭据。
|
|
261
|
+
|
|
262
|
+
水位按 `0.8 × max(0, min(模型容量, Host 配置上限〔如有〕) - max(model.max_tokens, 输出预留))` 计算,比较的是最终输入的启发式估算,包含 system、消息、工具 Schema 和 Provider 回传数据,不采用压缩前的旧 usage。每次请求读取当前 `ModelClient.context_window`,已知型号的容量由 ModelProfile 自动填充,Host 可显式覆盖;未知型号仍回退到 128,000,使用自定义部署时应显式提供容量。`ResourceBudget.estimate_request(...)` 可用于读取相同口径的输入估算、输出预留与有效上限。
|
|
263
|
+
|
|
264
|
+
每次请求前最多自动尝试一次。摘要生成失败、空摘要、候选投影未缩小、变换出错或仍超限时,保留原消息和已构造的原请求投影;原请求仍通过硬预算就继续,否则抛出 `BudgetExceeded`。拒绝候选不产生版本,也不清除 continuation。保存失败或版本冲突直接传播,不按摘要失败吞掉。摘要只处理 Session 历史,不把动态投影写回历史;`model_summarizer` 按摘要模型自己的容量与输出配置检查输入,并拒绝截断响应和工具调用。输入放不进摘要模型时报告失败,当前不做递归分块或 Provider overflow 重试。
|
|
265
|
+
|
|
266
|
+
同一 Agent 按 Session 记录最近一次失败或未改变历史的尝试,跨 `run()` / `resume()` 生效。内置 Compactor 的摘要前缀与相关配置未变时跳过后续自动尝试,不重复调用摘要器或发送 `compact_start`;仅追加保留尾部的工具结果、更新 usage、修改会话 metadata 或重新加载相同 Session 不会解除抑制。自定义 `compact()` 可以读取任意历史和消息元数据,因此按完整历史判断是否需要重试。相关输入改变、更换 Compactor/投影函数或修改模型容量、预算、system、工具 Schema 后可再次尝试。`agent.compact()` 始终允许显式重试,成功提交清除该会话的失败记录;取消和保存失败不记为可抑制的摘要失败。记录仅保存在 Agent 内存中,新建 Agent 不继承它,也不检测回调闭包内部的状态变化;宿主修复外部依赖后可显式压缩或更换 Compactor。
|
|
267
|
+
|
|
268
|
+
压缩提交成功后清除模型 continuation,并使保留消息中的旧 usage 失效;取消发生在保存期间时会等待提交结束,因此调用者应检查最终 Session 状态。被摘要掉的工具调用 ID 保存在内部消息元数据中,恢复后仍拒绝重复调用 ID,这些元数据不发送给模型。待许可、工具批次未完成或结果未知时不执行自动压缩。
|
|
269
|
+
|
|
270
|
+
`observe(AgentEvent)` 支持同步或异步回调。每个事件携带 `session_id`、`run_id`、可空的 `call_id` 和 `revision`;每次 `run()`、`resume()`、异步核对操作和显式 `compact()` 都有新的 `run_id`,自动压缩沿用当前运行的 `run_id`,工具的 `call_id` 跨等待和重启保持一致。`AgentEvent` 是按 kind 区分载荷的联合类型,wheel 包含 `py.typed`。原有 `Event` 构造器与 `isinstance(event, Event)` 仍可使用;宿主把观察者参数标注为 `AgentEvent` 可获得精确的载荷类型:
|
|
271
|
+
|
|
272
|
+
```python
|
|
273
|
+
from penhin import AgentEvent
|
|
274
|
+
|
|
275
|
+
def observe(event: AgentEvent) -> None:
|
|
276
|
+
if event.kind == "text_delta":
|
|
277
|
+
print(event.data.upper()) # str
|
|
278
|
+
elif event.kind == "tool_end":
|
|
279
|
+
print(event.data["result"].error) # ToolResult
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
流式交付采用背压:模型线程等待当前文本回调完成,随后才能交付下一段文本,因此不会因慢观察者堆积无界文本队列。慢回调会延长模型调用;观察者应尽快返回,UI 可自行消费宿主管理的有界队列。取消不会提前拆除仍被模型或回调使用的资源。
|
|
283
|
+
|
|
284
|
+
| 事件 | `data` | 含义 |
|
|
285
|
+
| --- | --- | --- |
|
|
286
|
+
| `run_start` | `None` | 开始一次运行或恢复 |
|
|
287
|
+
| `run_end` | `RunResult` | 返回 complete/waiting/limit/cancelled |
|
|
288
|
+
| `run_error` | `{error_type, message}` | 运行抛出异常,原异常仍向调用者传播 |
|
|
289
|
+
| `model_start` / `text_delta` | `None` / `str` | 模型轮次开始 / 暂态文本 |
|
|
290
|
+
| `model_end` | `LLMUsage` | 完整模型响应已保存 |
|
|
291
|
+
| `model_error` | `{error_type, message}` | 该轮未完成或保存失败 |
|
|
292
|
+
| `tool_start` | `{id, name}` | executing 检查点已保存,即将调用 handler |
|
|
293
|
+
| `tool_end` | `{id, name, result: ToolResult}` | 关联结果已保存,包括拒绝、参数错误、工具变更和等待恢复 |
|
|
294
|
+
| `waiting` | `WaitRequest` | 等待状态已保存,`call_id` 指向待回复调用 |
|
|
295
|
+
| `compact_start` | `None` | 开始一次手动或自动压缩尝试 |
|
|
296
|
+
| `compact_end` | `{changed, before_tokens, after_tokens}` | 压缩已保存;历史未变时 changed 为 false 且不产生版本。token 数是压缩前后完整请求输入的启发式估算,含 system、工具 Schema 和协议回传数据,不含输出预留;仅清理隐藏历史时可以相等 |
|
|
297
|
+
| `compact_error` | `{error_type, message}` | 摘要生成、候选投影校验或保存失败;自动候选失败后仍可在原请求的硬预算内继续 |
|
|
298
|
+
|
|
299
|
+
这些是尽力交付的运行事件,不是持久化事件总线;观察者的普通异常被隔离,重连界面应从 Session 重建状态。等待不是完成;结果未知的取消也不会发送 `tool_end`。`tool_end` 可能没有 `tool_start`,例如权限拒绝或参数校验失败。已经输出文本的流失败后不会自动重试。模型轮次失败会先发送 `model_error`,随后以 `run_error` 结束运行;协作取消以 `run_end(cancelled)` 结束。
|
|
300
|
+
|
|
301
|
+
## Provider 与认证
|
|
302
|
+
|
|
303
|
+
支持 Anthropic、OpenAI Responses、Gemini、DeepSeek,以及实验性的 OpenAI Codex 适配器。模型由宿主选择。`penhin.models.model_profiles()` 返回内置容量与 thinking 能力;具体型号和快照日期以 [src/models/profiles.py](src/models/profiles.py) 为准,SDK 依赖范围见 [pyproject.toml](pyproject.toml)。能力资料不表示账户可用性,未列出的型号仍可调用。
|
|
304
|
+
|
|
305
|
+
2026-11-22 的能力快照补入 GPT-6.2 Astra/Sol、GPT-6.1 Terra、Claude Fable 5.2 和 Gemini 4 Carbon/Neon/Hydrogen。来源分别为 [OpenAI 型号文档](https://developers.openai.com/api/docs/models)、[Claude 型号文档](https://platform.claude.com/docs/en/models/overview) 与 [Gemini 型号文档](https://aistudio.google.com/docs/models)。Gemini Neon/Hydrogen 默认 `high`,支持 `xhigh`;Carbon/Argon 默认 `medium`。Gemini 4 的输入、思考和输出共用 1,048,576 token,长输出由 SDK 续传,容量资料不会自动调高 `ModelClient.max_tokens`。
|
|
306
|
+
|
|
307
|
+
Gemini 使用 `google-genai>=3.3,<4`,该版本正式提供 [`xhigh` 枚举](https://github.com/googleapis/python-genai/releases/tag/v3.3.0)。适配器保留 Developer API 的 `v1beta` 路径;SDK 3 默认传输改为 `httpx2`,自定义 SDK transport 应按 [升级说明](https://github.com/googleapis/python-genai/releases/tag/v3.0.0) 配置。OpenAI 和 Anthropic SDK 范围保持不变。DeepSeek 的既有推理别名按[官方映射](https://api-docs.deepseek.com/guides/thinking_mode/)继续支持。
|
|
308
|
+
|
|
309
|
+
`openai` 与 `openai-codex` 分别标识 OpenAI API 和 ChatGPT/Codex 服务入口,同名模型不保证入口的认证、参数和额度相同。Host 可以把它们显示为“OpenAI · API key”和“OpenAI · ChatGPT 登录”。[`openai.py`](src/providers/openai.py) 完整负责这两个入口:`OpenAIProvider` 和 `OpenAICodexProvider` 处理各自的传输与端点要求,模块内部共用请求、工具、流事件汇总和响应转换。OpenAI SDK 仅在构造 API Provider 时加载,Codex 仍可使用基础依赖。凭据和原生续接数据继续使用各自的标识保存。
|
|
310
|
+
|
|
311
|
+
直接导入 Codex 类的宿主应使用 `from penhin.providers.openai import OpenAICodexProvider`;原 `openai_codex.py` 和私有 `_responses.py` 已合并到该模块。通过 `ModelClient.connect("openai-codex", ...)` 创建连接的方式不变。
|
|
312
|
+
|
|
313
|
+
`ModelClient.context_window` 默认取已知型号的容量,未知型号使用 128,000,宿主可显式覆盖。`max_tokens` 默认 10,000;已知型号会校验输出上限。Codex 没有独立的内置容量资料,宿主应按实际服务配置。
|
|
314
|
+
|
|
315
|
+
通过 `thinking_level` 选择推理强度,或用 `request_options` 提供所选 Provider 的原生生成参数。`provider_options` 用于连接参数,如 timeout/base_url。原生请求选项不能覆盖内核管理的 model、messages/input、tools、stream 等字段;不支持的已知型号参数会报错。
|
|
316
|
+
|
|
317
|
+
`LLMResponse.metadata[provider_id]` 保存观察信息;Agent 将其写入消息的 `_meta.provider_metadata`。`provider_data[provider_id]` 保存签名、reasoning 等续接数据,随消息和工具批次一起提交。下一轮请求只使用对应 Provider 的续接数据;宿主改写消息内容后,摘要不匹配的原始内容不会被重新回传。跨 Provider 切换不保证私有协议语义可迁移。
|
|
318
|
+
|
|
319
|
+
文本回调只交付普通输出。流必须正常结束才能执行其中的工具;响应元数据和协议续接数据不等同于完整 SSE 日志或 HTTP header 透传。当前接口主要服务文本和本地函数工具循环。
|
|
320
|
+
|
|
321
|
+
`penhin.models.messages` 为 text、reasoning、tool_use、tool_result 提供 `TypedDict` 类型和 `KnownContentBlock` 联合类型,并区分 `HistoryMessage` 与 `WireMessage`。公开传输接口仍接受字典,核心读取已知内容块前校验字段形状;模型响应和加载的会话中,结构无效的已知内容块会被拒绝。工具参数不符合工具 Schema 时仍产生关联的错误结果。未知内容块、扩展字段和 Provider 续接数据保留原有 JSON 形式;静态类型不替代持久化时的 JSON 校验。
|
|
322
|
+
|
|
323
|
+
```python
|
|
324
|
+
from penhin.auth import AuthService, FileCredentialStore
|
|
325
|
+
|
|
326
|
+
auth = AuthService(FileCredentialStore("state/auth.json"), environment={})
|
|
327
|
+
auth.save_api_key("openai", key_from_host)
|
|
328
|
+
model = ModelClient.connect("openai", chosen_model, auth=auth,
|
|
329
|
+
provider_options={"timeout": 60})
|
|
330
|
+
|
|
331
|
+
# interaction 实现 prompt(kind, message, options=()) 和 notify(kind, **payload)。
|
|
332
|
+
auth.login("openai-codex", "oauth", interaction, oauth_method="device_code")
|
|
333
|
+
auth.logout("openai-codex")
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
AuthService 默认内存存储;已保存凭据优先于环境变量。传 `environment={}` 可关闭环境凭据回退。文件存储需显式路径;系统钥匙串使用 `KeyringCredentialStore(lock_path, service="my-app")` 与 `keyring` extra。文件存储以明文 JSON 保存凭据,使用独立文件权限;宿主决定是否选择系统钥匙串。OAuth 支持浏览器/手动回填、Codex 设备码,以及带存储锁的令牌刷新。登录接口同步;异步宿主可在工作线程调用,交互回调也需适配宿主的 UI 线程。
|
|
337
|
+
|
|
338
|
+
`ModelClient.connect(...)` 通过 AuthService 解析凭据并创建连接,`model.provider` 直接持有实际 Provider。直接使用 `ModelClient(custom_provider, model_name)` 不创建 AuthService,也不读取凭据;原有的 `auth`、`auth_expires_at`、`provider_options` 构造参数和实例字段仍可使用。
|
|
339
|
+
|
|
340
|
+
ModelClient 在模型重试前检查凭据有效期,通过 AuthService 刷新并持久化凭据,再构建替换连接。刷新或构建失败时保留旧连接并传播异常,不发模型请求,也不由模型重试策略重试认证。替换成功后关闭旧连接;`ModelClient.close()` 通过 `provider.client.close()` 关闭当前 SDK 连接。同步、异步、流式和摘要路径遵守同一规则,异步调用中的刷新位于模型执行名额内。
|
|
341
|
+
|
|
342
|
+
模型网络重试和熔断属于 ModelClient,工具不会被这套重试机制重复调用。Anthropic/OpenAI/DeepSeek 关闭 SDK 内部重试,避免双重重试;Gemini 保留 SDK 重试,ModelClient 不叠加重试。凭据、Provider、界面与工具均可由宿主自行替换。
|
|
343
|
+
|
|
344
|
+
认证测试使用模拟 HTTP 与本地回调,不要求真实账户或付费模型调用;离线测试不代表实验性 OAuth/订阅接口的在线可用性。
|
|
345
|
+
|
|
346
|
+
## 仓库与边界
|
|
347
|
+
|
|
348
|
+
源文件直接位于 `src/`,由打包配置映射为 `penhin`:`agent.py`、`session.py`、`tools.py`、`plugins.py` 分别管理执行、持久化状态、工具与插件;`models/` 拥有统一模型契约、能力资料、连接生命周期和调用策略,`providers/` 拥有厂商协议转换,`context/` 拥有投影、压缩与估算,`auth/` 拥有凭据解析、存储与登录刷新流程。事件类型定义在 `events.py`;私有 `_async.py` 管理线程调用与取消排空,`_checkpoints.py` 管理检查点编码,`_atomic.py` 管理原子文件写入。扩展优先使用 `penhin`、`penhin.models`、`penhin.providers`、`penhin.auth` 和 `penhin.context` 的公开导出。
|
|
349
|
+
|
|
350
|
+
私有 `context/_preparation.py` 集中处理请求投影、预算、压缩候选与失败抑制,返回经过校验的投影和可选候选历史。Agent 持有会话锁,负责候选提交、continuation 清理和提交后的事件交付。请求准备本身不修改 Session。Session 提交通过模型序列化与重建生成独立候选,保留提交前的完整 JSON 校验和保存后发布顺序;当前仍会遍历完整状态,尚未采用不可变历史共享或局部状态校验。
|
|
351
|
+
|
|
352
|
+
`cancellation.py` 统一运行与线程间的取消通知,`execution.py` 提供宿主持有的模型并发队列,`budget.py` 检查可配置的请求/结果预算。业务数据如何缩减、依赖何时关闭、预算超限后如何交互仍由宿主决定。
|
|
353
|
+
|
|
354
|
+
领域术语见 [CONTEXT.md](CONTEXT.md)。源码最初从 [penhin-code 的固定提交](https://github.com/penhin/penhin-code/tree/cfed0ff20b035efcd4befea3f33812e495b5fbe1) 抽取,保留 [MIT 许可证与作者信息](LICENSE)。
|
|
355
|
+
|
|
356
|
+
penhin-code 的 `penhin` 和 `penhin-core` 入口均使用本内核,应用源码位于其 `src/`,安装后的导入名为 `penhin_code`。联调安装方式见 [penhin-code README](https://github.com/penhin/penhin-code#安装)。仍占用 `penhin` 导入名的旧应用版本需要单独环境;旧应用 JSONL 会话不会自动导入。内核采用独立的 0.1 接口,宿主应锁定已验证版本,并在工具或插件发生不兼容变化时提升版本。
|
|
357
|
+
|
|
358
|
+
## 开发与验证
|
|
359
|
+
|
|
360
|
+
```sh
|
|
361
|
+
python -m pytest -q
|
|
362
|
+
python -m ruff check src tests examples
|
|
363
|
+
python -m ruff format --check src tests examples
|
|
364
|
+
python -m mypy
|
|
365
|
+
python examples/embedding.py
|
|
366
|
+
python examples/bounded_embedding.py
|
|
367
|
+
python -m build
|
|
368
|
+
python -m twine check --strict dist/*
|
|
369
|
+
python tests/wheel_smoke.py
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
测试使用离线 Provider 和模拟 HTTP transport。`wheel_smoke.py` 在仓库外安装 wheel,验证公开接口、类型标记、持久化审批与实际工具调用,并用 mypy 检查宿主接口。旧会话兼容性由 [固定测试样本](tests/fixtures/session_v1/README.md) 覆盖。
|
|
373
|
+
|
|
374
|
+
CI 的 `host-compatibility` 使用候选 core wheel 跑固定提交的 penhin-code 接入契约测试,Host 基线与测试范围写在 [.github/workflows/ci.yml](.github/workflows/ci.yml) 中,不随其主分支漂移。更新基线需单独验证;这使核心修改在合入前接受真实宿主回归。测试覆盖隐藏历史压缩、持久化恢复、工具、插件、认证和模型配置,不需要模型凭据。完整终端 UI 测试由宿主自己的 CI 维护。
|
|
375
|
+
|
|
376
|
+
日常开发 penhin-code 时,使用已验证的 core 发布版本;升级 core 时重新联调并更新依赖锁。相邻目录的 editable 安装适合跨仓修复,会立即读取核心工作区变更。发布 core 前先通过上述 wheel 与宿主验证,发布后宿主按版本依赖安装。普通 CI 只验证代码;推送版本标签触发下面的发布流程。
|
|
377
|
+
|
|
378
|
+
`python -m mypy` 严格检查消息类型、模型契约、请求投影和请求准备模块;范围在 `pyproject.toml` 中显式列出,其余内部模块尚未纳入严格检查。wheel 类型检查另行验证宿主能按事件和内容块类型收窄载荷,并拒绝错误字段访问。
|
|
379
|
+
|
|
380
|
+
需要分析存储成本时,运行 `python examples/session_benchmark.py --turns 50 200` 或 `python examples/checkpoint_benchmark.py --versions 1000 10000`。前者测量增长中的对话,后者测量固定状态下的版本查找;输出是本机诊断数据,不作为 CI 耗时门槛。
|
|
381
|
+
|
|
382
|
+
`python examples/session_benchmark.py --turns 50 200 --profile` 额外在提交工作线程中采样深复制、模型序列化、Python/JSON 校验、检查点编码和原子写入,输出各阶段累计时间与每次提交的 P95。计时包含各自调用的子函数,彼此有重叠,不能相加;profiler 本身增加耗时和内存,性能对比应同时运行不带 `--profile` 的基准。
|
|
383
|
+
|
|
384
|
+
## 发布到 PyPI
|
|
385
|
+
|
|
386
|
+
[发布工作流](.github/workflows/publish.yml) 使用 PyPI Trusted Publishing。首次发布前,维护者登录自己的 PyPI 账号,在[发布设置](https://pypi.org/manage/account/publishing/)添加 GitHub pending publisher:
|
|
387
|
+
|
|
388
|
+
| 字段 | 值 |
|
|
389
|
+
| --- | --- |
|
|
390
|
+
| PyPI project name | `penhin` |
|
|
391
|
+
| Owner | `penhin` |
|
|
392
|
+
| Repository name | `penhin` |
|
|
393
|
+
| Workflow name | `publish.yml` |
|
|
394
|
+
| Environment name | `pypi` |
|
|
395
|
+
|
|
396
|
+
在 [GitHub 仓库 Environments](https://github.com/penhin/penhin/settings/environments) 创建同名的 `pypi` 环境,可设置发布审核者。工作流通过 GitHub OIDC 获取短期发布凭据,无需在仓库保存 PyPI API token。PyPI 会在第一次成功发布时创建项目;pending publisher 本身不会上传包。设置细节见 [PyPI 官方文档](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)。
|
|
397
|
+
|
|
398
|
+
每次发布先更新 `pyproject.toml` 中的版本,完成上述检查并将待发布代码提交、推送到远端,再创建同版本标签。例如当前版本 `0.1.1`:
|
|
399
|
+
|
|
400
|
+
```sh
|
|
401
|
+
git tag v0.1.1
|
|
402
|
+
git push origin v0.1.1
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
标签必须指向完整、已审核的发布提交,且与包版本一致。工作流先运行完整 CI,包括仓库外 wheel 检查和固定宿主兼容性测试,通过后构建、检查并上传 wheel 与 sdist。普通分支上手动运行此工作流只做验证和构建。PyPI 不允许覆盖已发布的同名版本文件;代码变化后发布新版本。
|
|
406
|
+
|
|
407
|
+
首次发布成功后,在新的虚拟环境验证 `python -m pip install 'penhin[providers,keyring]==0.1.1'`。随后 `penhin-code` 及其他项目就可仅依赖包名和版本范围安装,不再需要本地源码路径或 Git 来源配置。
|