petfishframework 0.2.5__tar.gz → 0.3.1__tar.gz

petfishframework-0.3.1/.sisyphus/plans/v0.3.0-plan.md

@@ -0,0 +1,340 @@
+# petfishFramework v0.3.0 开发计划
+
+> 基于 v0.2.5 状态 + 6 轮用户反馈 + 生产可用路线图
+> 目标：从代码策略进入配置化策略 + 凭证治理 MVP
+> 原则：**TDD 先行，YAML-first，向后兼容**
+
+## v0.3.0 使命
+
+> 让安全/运维团队通过 YAML 文件配置 Agent 权限策略，无需写 Python 代码。
+> 让 Agent 永不持有真实凭证——通过 CredentialBroker 签发 scoped 短期令牌。
+
+## v0.2.5 → v0.3.0 状态跃迁
+
+| 维度 | v0.2.5（当前） | v0.3.0（目标） |
+|---|---|---|
+| 策略定义 | Python class (PermissionPolicy) | **YAML 文件 + Python fallback** |
+| 策略测试 | 手写 pytest | **YAML test suite + pytest runner** |
+| 策略版本 | 无 | **policy_version 字段 + 审计追踪** |
+| 凭证 | Agent 持有 API key | **CredentialBroker scoped 令牌** |
+| 策略组合 | 单一 policy | **多规则 deny-overrides 合并** |
+
+---
+
+## Phase A: YAML Policy Engine
+
+### A1: YAML 策略解析器 + 匹配引擎
+
+**目标**：从 YAML 文件加载策略规则，按优先级匹配，生成 Decision。
+
+**文件**：`src/petfishframework/policies/` (新模块)
+
+**YAML 格式**：
+
+```yaml
+version: "1.0"
+name: "enterprise-expense-policy"
+
+rules:
+  - name: deny-non-finance-approval
+    priority: 100
+    when:
+      action.tool_name: approve_payment
+      subject.role_not_in: [finance, admin]
+    effect: DENY
+    reason: "only finance/admin can approve payments"
+
+  - name: require-approval-for-side-effects
+    priority: 90
+    when:
+      tool.side_effect: true
+    effect: REQUIRE_APPROVAL
+    reason: "side-effect tool requires approval"
+
+  - name: degrade-large-payments
+    priority: 80
+    when:
+      action.tool_name: approve_payment
+      action.args.amount_gt: 5000
+    effect: DEGRADE
+    reason: "large payment degraded to dry-run"
+    fallback_tool: dry_run_payment
+
+  - name: mask-pii-in-payments
+    priority: 70
+    when:
+      action.tool_name: approve_payment
+    effect: MASK
+    reason: "mask PII"
+    input_mask_fields: [recipient]
+    output_mask_fields: [recipient]
+    event_mask_fields: [recipient]
+
+  - name: partial-allow-policy-check
+    priority: 60
+    when:
+      action.tool_name: check_policy
+    effect: PARTIAL_ALLOW
+    reason: "only amount needed"
+    allowed_fields: [amount]
+
+  - name: default-allow
+    priority: 0
+    when: {}
+    effect: ALLOW
+    reason: "default allow"
+```
+
+#### TDD 测试先行
+
+```python
+# tests/test_yaml_policy.py
+
+def test_yaml_policy_loads_from_file():
+    """YAML 文件成功加载为 PolicyEngine。"""
+
+def test_yaml_policy_deny_rule_blocks():
+    """deny-non-finance 规则阻断非 finance 用户。"""
+
+def test_yaml_policy_priority_ordering():
+    """高 priority 规则先匹配。"""
+
+def test_yaml_policy_deny_overrides_allow():
+    """deny 规则覆盖 default-allow。"""
+
+def test_yaml_policy_mask_rule_sets_fields():
+    """mask 规则正确设置 input/output/event mask fields。"""
+
+def test_yaml_policy_degrade_rule_sets_fallback():
+    """degrade 规则正确设置 fallback_tool。"""
+
+def test_yaml_policy_partial_allow_sets_allowed_fields():
+    """partial_allow 规则正确设置 allowed_fields。"""
+
+def test_yaml_policy_no_match_returns_default():
+    """无规则匹配时返回默认 Decision。"""
+
+def test_yaml_policy_condition_amount_gt():
+    """amount_gt 条件正确比较数值。"""
+
+def test_yaml_policy_condition_role_not_in():
+    """role_not_in 条件正确检查角色。"""
+
+def test_yaml_policy_condition_tool_side_effect():
+    """tool.side_effect 条件匹配工具元数据。"""
+```
+
+#### 实现
+
+1. `policies/__init__.py` — 导出
+2. `policies/rule.py` — `PolicyRule` dataclass (name, priority, when, effect, reason, mask_fields, fallback_tool, allowed_fields)
+3. `policies/conditions.py` — 条件匹配器：
+   - `action.tool_name` — 精确匹配
+   - `action.args.amount_gt` — 数值大于
+   - `action.args.amount_lt` — 数值小于
+   - `subject.role_in` — 角色在列表中
+   - `subject.role_not_in` — 角色不在列表中
+   - `tool.side_effect` — 工具元数据匹配
+   - `tool.external_egress` — 工具元数据匹配
+4. `policies/engine.py` — `YamlPolicy` class：
+   - `from_file(path) -> YamlPolicy`
+   - `from_string(yaml_str) -> YamlPolicy`
+   - `evaluate(subject, action, resource, context) -> Decision`
+   - 按 priority 降序遍历规则，deny-overrides 语义
+   - 需要工具元数据 → 接受 `tool_registry` 或在 evaluate 时接收 tool 对象
+
+### A2: YAML 策略测试套件
+
+**目标**：在 YAML 中定义测试用例，pytest 自动运行。
+
+**YAML 格式**：
+
+```yaml
+# tests/policies/enterprise-expense.tests.yaml
+policy_file: enterprise-expense.yaml
+
+tests:
+  - name: analyst-cannot-approve
+    input:
+      subject.roles: [analyst]
+      action.tool_name: approve_payment
+      action.args.amount: 300
+    expect:
+      effect: DENY
+
+  - name: finance-small-payment-partial-allow
+    input:
+      subject.roles: [finance]
+      action.tool_name: check_policy
+      action.args.amount: 350
+    expect:
+      effect: PARTIAL_ALLOW
+
+  - name: large-payment-degrades
+    input:
+      subject.roles: [finance]
+      action.tool_name: approve_payment
+      action.args.amount: 8000
+    expect:
+      effect: REQUIRE_APPROVAL  # side_effect 先匹配
+
+  - name: unknown-tool-default-allow
+    input:
+      subject.roles: [analyst]
+      action.tool_name: unknown_tool
+    expect:
+      effect: ALLOW
+```
+
+#### TDD 测试先行
+
+```python
+# tests/test_yaml_policy_suite.py
+
+def test_policy_suite_runs_all_tests():
+    """YAML 测试套件中所有用例通过。"""
+
+def test_policy_suite_reports_failures():
+    """测试套件中失败的用例被报告。"""
+```
+
+#### 实现
+
+- `policies/test_runner.py` — 加载 `.tests.yaml`，构造 Subject/Action/Resource/Context，调用 policy.evaluate，比较 effect
+- pytest fixture 自动发现 `tests/policies/*.tests.yaml`
+
+### A3: 策略版本 + 审计元数据
+
+**目标**：策略带版本号，决策事件记录策略版本。
+
+#### TDD 测试先行
+
+```python
+def test_policy_has_version():
+    """YAML policy 有 version 字段。"""
+
+def test_decision_records_policy_version():
+    """Decision 记录 policy_version。"""
+```
+
+#### 实现
+
+- `PolicyRule` 增加 `version: str` 字段
+- `YamlPolicy` 从 YAML `version` 读取
+- `Decision` 增加 `policy_version: str | None = None` 字段
+- `YamlPolicy.evaluate()` 在返回 Decision 时填充 policy_version
+- Environment 事件记录 policy_version
+
+---
+
+## Phase B: CredentialBroker MVP
+
+### B1: Scoped 令牌签发 + 过期
+
+**目标**：Agent 永不持有真实 API key。CredentialBroker 签发短期限时令牌。
+
+**文件**：`src/petfishframework/credentials/` (新模块)
+
+#### TDD 测试先行
+
+```python
+# tests/test_credential_broker.py
+
+def test_broker_issues_scoped_token():
+    """Broker 发放 scoped 令牌（限 tool + scope）。"""
+
+def test_broker_token_has_ttl():
+    """令牌有 TTL，过期后失效。"""
+
+def test_broker_token_not_in_event_log():
+    """令牌不出现在事件日志中。"""
+
+def test_broker_revokes_token():
+    """Broker 可以撤销令牌。"""
+
+def test_broker_token_scoped_to_tool():
+    """令牌限定了可调用的工具。"""
+```
+
+#### 实现
+
+1. `credentials/__init__.py` — 导出
+2. `credentials/broker.py` — `CredentialBroker`：
+   - `register_credential(name, secret, scope)` — 注册真实凭证
+   - `issue_token(name, tool_name, ttl_s) -> ScopedToken` — 签发限时令牌
+   - `validate_token(token) -> bool` — 验证令牌有效性
+   - `revoke_token(token_id)` — 撤销令牌
+3. `credentials/token.py` — `ScopedToken` dataclass：
+   - `token_id: str` — 唯一 ID
+   - `tool_name: str` — 限定的工具
+   - `expires_at: float` — 过期时间戳
+   - `_secret: str` — 内部引用（不暴露在事件日志中）
+   - `is_valid() -> bool`
+   - `__repr__` 脱敏（显示 `[REDACTED]`）
+
+### B2: 与 Environment 集成
+
+**目标**：工具通过 Broker 获取凭证，不直接持有 API key。
+
+#### 实现
+
+- `Environment` 增加 `credential_broker: CredentialBroker | None`
+- 工具的 `requires_credentials: True` 时，Environment 在 `call()` 前通过 Broker 签发令牌
+- 令牌传递给工具 `execute()` 的 args 中（字段名 `_credential_token`）
+- 事件日志中令牌值脱敏
+
+---
+
+## Phase C: 企业 PoC 集成 + 文档
+
+### C1: 企业报销审批 YAML 策略
+
+**目标**：用 YAML 文件替代 v0.2.x 的 Python ExpensePolicy。
+
+**文件**：`examples/policies/enterprise-expense.yaml`
+
+### C2: 企业 demo 升级
+
+**目标**：`examples/05_enterprise_expense.py` 升级为 YAML 策略驱动。
+
+### C3: 文档更新
+
+- `docs/api.md` 增加 YAML Policy + CredentialBroker 章节
+- `docs/usage-guide.md` 增加「YAML 策略配置」+「凭证治理」段落
+- `CHANGELOG.md` v0.3.0
+- `README.md` 更新 Current Limitations
+
+---
+
+## 执行顺序与依赖
+
+```
+A1 (YAML engine) → A2 (test suite) → A3 (version metadata)
+                                        ↓
+B1 (Broker MVP) → B2 (Environment integration)
+                     ↓
+C1 (YAML policy file) → C2 (demo upgrade) → C3 (docs)
+```
+
+## 不做清单
+
+- ❌ OpenTelemetry（v0.4.0）
+- ❌ 确定性回放 RESUME/RERUN（v0.4.0）
+- ❌ MCP server mode（v0.5.0）
+- ❌ Vault 集成（v0.4.0+）
+- ❌ Policy 热重载（v0.4.0+）
+
+## 验收标准
+
+| # | 标准 | 验证方法 |
+|---|---|---|
+| V1 | YAML policy 从文件加载并正确匹配 | `test_yaml_policy.py` 全通过 |
+| V2 | 6 种 DecisionEffect 全部可从 YAML 配置 | YAML 规则覆盖全部 effect |
+| V3 | deny-overrides 语义正确 | `test_yaml_policy_deny_overrides` |
+| V4 | YAML test suite 自动运行 | `pytest tests/policies/` |
+| V5 | CredentialBroker 签发 scoped 令牌 | `test_credential_broker.py` |
+| V6 | 令牌不出现在事件日志 | `test_broker_token_not_in_event_log` |
+| V7 | 企业 demo 使用 YAML 策略 | `python examples/05_enterprise_expense.py` |
+| V8 | 所有 234+ 现有测试仍通过 | pytest |
+| V9 | ruff clean | ruff check |
+| V10 | Trusted Publishing 发布成功 | git tag v0.3.0 |

{petfishframework-0.2.5 → petfishframework-0.3.1}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.3.0] — 2026-07-08
+
+### v0.3.0 Policy Engine + Credential Broker Integration
+
+- YAML Policy Engine (Phase A1): load authorization rules from YAML via `YamlPolicy.from_file` / `from_string`
+- Condition matchers: `action.tool_name`, `subject.role_in`, `subject.role_not_in`, `action.args.amount_gt`, `action.args.amount_lt`, `tool.side_effect`, `tool.external_egress`
+- Enterprise expense YAML policy example (`examples/policies/enterprise-expense.yaml`)
+- `CredentialBroker` + `ScopedToken`: issue scoped, time-limited tokens that hide secrets in `repr` / `str`
+- `RuntimeEnvironment` integration: tools with `requires_credentials=True` receive a scoped token via `_credential_token` before execution
+- 3 new TDD tests covering credential injection, non-credential tools, and event-log safety
+
 ## [0.2.0] — 2026-07-08
 
 ### v0.2.0 Enterprise PoC Release

{petfishframework-0.2.5 → petfishframework-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.2.5
+Version: 0.3.1
 Summary: A lightweight runtime framework for reliable, auditable, budget-aware, and permission-aware AI agents.
 Project-URL: Homepage, https://github.com/kylecui/petfishFramework
 Project-URL: Documentation, https://github.com/kylecui/petfishFramework/tree/master/docs
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.40; extra == 'anthropic'
 Provides-Extra: mcp
@@ -33,7 +34,7 @@ Description-Content-Type: text/markdown
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 234](https://img.shields.io/badge/tests-234-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 259](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -214,11 +215,39 @@ See `examples/05_enterprise_expense.py` and `tests/test_enterprise_demo.py` for
 
 Run: `python examples/05_enterprise_expense.py`
 
+## YAML Policy Engine
+
+Configure permissions via YAML instead of Python:
+
+```python
+from petfishframework.policies import YamlPolicy
+
+policy = YamlPolicy.from_file("examples/policies/enterprise-expense.yaml")
+policy.register_tools(tools)
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, permission_policy=policy)
+```
+
+Supported conditions: `action.tool_name`, `subject.role_in`, `subject.role_not_in`, `action.args.amount_gt/lt`, `tool.side_effect`, `tool.external_egress`.
+
+## CredentialBroker
+
+Tools never hold raw API keys — they receive scoped, time-limited tokens:
+
+```python
+from petfishframework.credentials import CredentialBroker
+
+broker = CredentialBroker()
+broker.register_credential("github_tool", os.environ["GITHUB_TOKEN"])
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=broker)
+# Tools with requires_credentials=True receive a ScopedToken (repr-safe, auto-expiring)
+```
+
 ## Roadmap
 
-- **v0.2.x** (current): Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.2.x**: Enterprise agent examples, structured audit reports
-- **v0.3.x**: Policy engine (YAML), credential broker
+- **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
+- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
 - **v0.4.x**: Production hardening, deployment guides
 
 ## Current Limitations
@@ -239,6 +268,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
+| YAML Policy Engine | ✅ Available |
+| Credential Broker | ✅ Available |
 | LATS / LLM+P | ⚠️ Lightweight implementations |
 | CRAG / Adaptive-RAG | ⚠️ Lightweight reference implementations |
 
@@ -248,7 +279,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 234 tests
+uv run pytest              # 259 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.2.5 → petfishframework-0.3.1}/README.md

@@ -4,7 +4,7 @@
 
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kylecui/petfishFramework/blob/master/LICENSE)
-[![Tests: 234](https://img.shields.io/badge/tests-234-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 259](https://img.shields.io/badge/tests-259-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -185,11 +185,39 @@ See `examples/05_enterprise_expense.py` and `tests/test_enterprise_demo.py` for
 
 Run: `python examples/05_enterprise_expense.py`
 
+## YAML Policy Engine
+
+Configure permissions via YAML instead of Python:
+
+```python
+from petfishframework.policies import YamlPolicy
+
+policy = YamlPolicy.from_file("examples/policies/enterprise-expense.yaml")
+policy.register_tools(tools)
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, permission_policy=policy)
+```
+
+Supported conditions: `action.tool_name`, `subject.role_in`, `subject.role_not_in`, `action.args.amount_gt/lt`, `tool.side_effect`, `tool.external_egress`.
+
+## CredentialBroker
+
+Tools never hold raw API keys — they receive scoped, time-limited tokens:
+
+```python
+from petfishframework.credentials import CredentialBroker
+
+broker = CredentialBroker()
+broker.register_credential("github_tool", os.environ["GITHUB_TOKEN"])
+
+agent = Agent(model=model, reasoning=ReAct(), tools=tools, credential_broker=broker)
+# Tools with requires_credentials=True receive a ScopedToken (repr-safe, auto-expiring)
+```
+
 ## Roadmap
 
-- **v0.2.x** (current): Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
-- **v0.2.x**: Enterprise agent examples, structured audit reports
-- **v0.3.x**: Policy engine (YAML), credential broker
+- **v0.2.x**: Core runtime, permission semantics, enterprise PoC, Trusted Publishing ✅
+- **v0.3.x** (current): YAML Policy Engine, CredentialBroker ✅
 - **v0.4.x**: Production hardening, deployment guides
 
 ## Current Limitations
@@ -210,6 +238,8 @@ petfishFramework is **Alpha**. API may change before v1.0.
 | MCP client stdio | ✅ Available |
 | MCP server mode | 📋 Planned |
 | Structured output / conversation memory | ✅ Available |
+| YAML Policy Engine | ✅ Available |
+| Credential Broker | ✅ Available |
 | LATS / LLM+P | ⚠️ Lightweight implementations |
 | CRAG / Adaptive-RAG | ⚠️ Lightweight reference implementations |
 
@@ -219,7 +249,7 @@ petfishFramework is **Alpha**. API may change before v1.0.
 git clone https://github.com/kylecui/petfishFramework.git
 cd petfishFramework
 uv sync --all-extras
-uv run pytest              # 234 tests
+uv run pytest              # 259 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.2.5 → petfishframework-0.3.1}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.2.5. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
+This document is the authoritative reference for the public API of `petfishFramework` v0.3.1. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -1212,3 +1212,85 @@ Tool functions that raise internally are caught by `BaseTool` and `MCPToolWrappe
 ### Replay divergence
 
 `ReplayEnvironment` raises `RuntimeError` when a replayed strategy makes more calls than were recorded. This detects when the execution path has diverged from the original run. `ResumableEnvironment` switches to the live environment after the checkpoint; calling it beyond the checkpoint continues live execution and may produce a different answer.
+
+## 15. YAML Policy Engine
+
+Authorization rules can be loaded from YAML and evaluated through `YamlPolicy`, which implements the same `PermissionPolicy` protocol as custom Python policies.
+
+```python
+from petfishframework import YamlPolicy
+
+policy = YamlPolicy.from_file("policies/enterprise-expense.yaml")
+policy.register_tools(tools)
+
+decision = policy.evaluate(subject, action, resource, context)
+print(decision.effect, decision.reason)
+```
+
+### Loading policies
+
+```python
+from petfishframework import YamlPolicy
+
+policy = YamlPolicy.from_file("path/to/policy.yaml")
+policy = YamlPolicy.from_string(yaml_text)
+```
+
+`YamlPolicy.from_file` reads UTF-8 YAML and returns a policy instance. `register_tools(tools)` must be called if rules reference tool metadata such as `side_effect` or `external_egress`.
+
+### Policy file format
+
+```yaml
+version: "1.0"
+name: "enterprise-expense-policy"
+rules:
+  - name: deny-non-finance-approval
+    priority: 100
+    when:
+      action.tool_name: approve_payment
+      subject.role_not_in: [finance, admin]
+    effect: DENY
+    reason: "only finance/admin can approve payments"
+
+  - name: require-approval-for-side-effects
+    priority: 90
+    when:
+      tool.side_effect: true
+    effect: REQUIRE_APPROVAL
+    reason: "side-effect tool requires approval"
+
+  - name: default-allow
+    priority: 0
+    when: {}
+    effect: ALLOW
+    reason: "default allow"
+```
+
+Rules are evaluated in descending `priority` order. The first fully matching rule wins. `version` and `name` are optional metadata carried on the resulting `Decision`.
+
+### Condition matchers
+
+Each key under `when:` selects a matcher. Matchers are fail-closed: an unknown key never matches.
+
+| Condition key | Meaning | Example value |
+|---|---|---|
+| `action.tool_name` | Exact tool name match | `"approve_payment"` |
+| `subject.role_in` | Subject has any listed role | `[finance, admin]` |
+| `subject.role_not_in` | Subject has none of the listed roles | `[finance, admin]` |
+| `action.args.amount_gt` | `action.args["amount"] > value` | `5000` |
+| `action.args.amount_lt` | `action.args["amount"] < value` | `100` |
+| `tool.side_effect` | Match tool metadata flag | `true` |
+| `tool.external_egress` | Match tool metadata flag | `true` |
+
+Compound conditions use AND semantics: every key in a `when:` block must match for the rule to apply.
+
+### Policy version
+
+The `version` field in YAML is exposed on every `Decision` produced by the policy:
+
+```python
+decision.policy_version  # "1.0"
+decision.policy_name     # "enterprise-expense-policy"
+```
+
+This lets audit logs trace each decision back to the policy file version that produced it.