petfishframework 0.2.0__tar.gz → 0.2.2__tar.gz

petfishframework-0.2.2/.sisyphus/plans/v0.2.0-plan.md

@@ -0,0 +1,167 @@
+# petfishFramework v0.2.0 开发计划
+
+> 基于 5 轮用户反馈 + 生产可用路线图 + v0.1.9 状态
+> 目标：从 Alpha runtime control skeleton 进入企业 PoC 可用阶段
+> 原则：**不堆 feature，聚焦企业 PoC 可信度闭环**
+
+## v0.2.0 使命
+
+> 让一个企业开发者能在 30 分钟内：安装 → 配置权限策略 → 运行一个受控 Agent → 导出审计报告。
+
+## 任务清单
+
+### Phase A: 企业 PoC Demo（证明差异化，非 calculator）
+
+#### A1: Enterprise Expense Approval Agent（端到端 demo）
+
+**目标**：一个完整可运行示例，展示全部 6 种 DecisionEffect + Budget + AuditReport。
+
+**文件**：`examples/05_enterprise_expense.py`
+
+**场景**：报销审批 Agent，处理员工报销请求。
+
+**覆盖**：
+- 报销金额 < $500 → ALLOW（auto-approve）
+- 报销金额 $500-$5000 → REQUIRE_APPROVAL
+- 报销金额 > $5000 → DEGRADE 到 dry-run（无 fallback → fail-closed）
+- 员工 SSN → MASK（input + output + event）
+- 非财务角色 → DENY 特定工具
+- Budget 限制总 token 消耗
+- AuditReport 导出 Markdown + JSON
+
+**TDD 测试先行**：
+
+```python
+# tests/test_enterprise_demo.py
+
+def test_expense_under_500_auto_approved():
+    """$350 team lunch → ALLOW, auto-approved."""
+
+def test_expense_500_to_5000_requires_approval():
+    """$2000 conference → REQUIRE_APPROVAL."""
+
+def test_expense_over_5000_degrade_fail_closed():
+    """$8000 equipment → DEGRADE, no fallback → blocked."""
+
+def test_ssn_masked_in_input_output_and_event():
+    """SSN masked before tool, in result, and in audit log."""
+
+def test_non_finance_role_denied():
+    """Non-finance role cannot call approve_payment."""
+
+def test_budget_enforced():
+    """Total token budget enforced."""
+
+def test_audit_report_generated():
+    """Markdown audit report contains all decisions."""
+```
+
+**实现**：
+- PolicyChecker tool（金额检查）
+- ApprovePayment tool（审批工具，side_effect=True）
+- ExpensePolicy（使用 tool metadata 做决策）
+- FakeModel 驱动（无需 API key）
+
+#### A2: Structured Audit Report 增强
+
+**目标**：AuditReport 从 MVP 升级为可读、可审计的完整报告。
+
+**新增字段**：
+- Budget section（used vs limit）
+- Event count by type
+- Permission count by effect
+- Masked fields summary
+- Degraded calls summary
+- Blocked calls summary
+- Model call count + token summary
+- Error section
+
+**TDD 测试先行**：
+
+```python
+# tests/test_audit_report_v2.py
+
+def test_report_contains_budget_section():
+    """Report has budget table with used/limit."""
+
+def test_report_counts_events_by_type():
+    """Report has event count breakdown."""
+
+def test_report_summarizes_permission_decisions():
+    """Report has permission summary by effect."""
+```
+
+### Phase B: 供应链可信度
+
+#### B1: SECURITY.md
+
+**文件**：`SECURITY.md`
+
+**内容**：
+- 支持的版本
+- 漏洞报告流程
+- 响应时间承诺
+- 安全联系人
+
+#### B2: GitHub Actions CI 增强
+
+**目标**：CI badge 可见 + 自动化质量门禁。
+
+**新增**：
+- pytest-cov 覆盖率报告
+- README badge 自动更新（test count）
+- Coverage badge
+
+#### B3: PyPI Trusted Publishing
+
+**目标**：从 twine 上传切换到 GitHub Actions OIDC Trusted Publishing。
+
+**步骤**：
+- PyPI 项目设置 → Trusted Publisher
+- GitHub Actions workflow `publish.yml`
+- Release trigger: tag push
+
+### Phase C: 文档最终同步
+
+#### C1: CHANGELOG 更新
+
+- v0.2.0 完整变更日志
+- 明确标注 Alpha → 企业 PoC 可用
+
+#### C2: README 企业 PoC 段落
+
+- 新增 "Enterprise PoC" section
+- 链接到 examples/05_enterprise_expense.py
+- 强调差异化：runtime control, not orchestration
+
+## 执行顺序与依赖
+
+```
+A1 (企业 demo) → A2 (审计报告增强)
+                     ↓
+B1 (SECURITY.md) → B2 (CI 增强) → B3 (Trusted Publishing)
+                                    ↓
+C1 (CHANGELOG) → C2 (README) → 发布 v0.2.0
+```
+
+## 验收标准
+
+| # | 标准 | 验证方法 |
+|---|---|---|
+| V1 | 企业 demo 可运行（FakeModel，零成本） | `python examples/05_enterprise_expense.py` |
+| V2 | 全部 6 种 DecisionEffect 在 demo 中展示 | 代码审查 + 运行输出 |
+| V3 | AuditReport 包含 budget/permission/mask 摘要 | TDD test |
+| V4 | SECURITY.md 存在 | 文件存在 |
+| V5 | CI badge 可见 | GitHub Actions 运行 |
+| V6 | Trusted Publishing 启用 | PyPI 元数据显示 |
+| V7 | 所有测试通过 + ruff clean | pytest + ruff |
+| V8 | CHANGELOG + README 同步 | 文档审查 |
+
+## 不做清单（v0.2.0 明确排除）
+
+- ❌ YAML Policy Engine（v0.3.0）
+- ❌ CredentialBroker（v0.3.0）
+- ❌ Deterministic rerun/resume（v0.4.0）
+- ❌ MCP server mode（v0.5.0）
+- ❌ 新 reasoning strategy
+- ❌ 新 model adapter

{petfishframework-0.2.0 → petfishframework-0.2.2}/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to petfishFramework will be documented in this file.
 
+## [0.2.0] — 2026-07-08
+
+### v0.2.0 Enterprise PoC Release
+
+Enterprise Expense Approval Agent demo:
+- 6 TDD tests covering ALL 6 DecisionEffects in enterprise scenario
+- PolicyChecker, ApprovePayment (side_effect=True), DryRunPayment tools
+- ExpensePolicy using tool metadata + amount thresholds
+- Zero-cost (FakeModel driven, no API key needed)
+
+AuditReport v2 enhancement:
+- Budget section (input/output/total tokens, cost, elapsed)
+- Event count by type table
+- Permission summary by effect table
+- Masked fields summary section
+- Errors section for failed tool calls
+- 5 new TDD tests
+
+Supply chain:
+- SECURITY.md (vulnerability reporting policy)
+- CI badge in README (Python 3.10-3.12, ruff + pytest)
+- Trusted Publishing: deferred (requires PyPI OIDC setup)
+
+### v0.1.6-v0.1.9 (merged into 0.2.0 baseline)
+
+Permission semantics:
+- DEGRADE: fallback tool switching + fail-closed when no fallback
+- MASK: input mask (pre-execution) + output mask (post) + event mask (audit log) + nested dot-path
+- PARTIAL_ALLOW: pre-execution arg filtering
+- REQUIRE_APPROVAL: pre-execution block
+- All 6 DecisionEffects enforced with side-effect verification tests
+
+Tool metadata:
+- BaseTool: side_effect, idempotent, external_egress, requires_credentials
+- SafeByDefaultPolicy example using metadata
+
+Audit infrastructure:
+- AuditReport with to_markdown() and to_json()
+- audit_report_from_session(session, result=None)
+- Event duration_ms + error capture
+- Granular event types: tool.blocked/approval_required/called/masked/partial_allowed/degraded/degrade_failed
+
 ## [0.1.0a1] — 2026-07-06 (Alpha)
 
 ### Added — Core Framework

{petfishframework-0.2.0 → petfishframework-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -33,7 +33,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: 223](https://img.shields.io/badge/tests-213-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 234](https://img.shields.io/badge/tests-234-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -208,6 +208,12 @@ print(result.summary())
 - [Benchmark Results](https://github.com/kylecui/petfishFramework/blob/master/docs/benchmark-results.md) — 3-tier strategy
 - [Examples](https://github.com/kylecui/petfishFramework/tree/master/examples/) — quickstart, tools+retrieval, multi-agent
 
+## Enterprise PoC
+
+See `examples/05_enterprise_expense.py` and `tests/test_enterprise_demo.py` for a complete enterprise expense approval scenario demonstrating all 6 DecisionEffects.
+
+Run: `python examples/05_enterprise_expense.py`
+
 ## Roadmap
 
 - **v0.1.x** (current): Core runtime, permission semantics, quickstart verified ✅
@@ -242,7 +248,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              # 223 tests
+uv run pytest              # 234 tests
 uv run ruff check src/ tests/
 ```
 

{petfishframework-0.2.0 → petfishframework-0.2.2}/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: 223](https://img.shields.io/badge/tests-213-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
+[![Tests: 234](https://img.shields.io/badge/tests-234-brightgreen.svg)](https://github.com/kylecui/petfishFramework/tree/master/tests/)
 
 **Status: Alpha** — API may change. Core runtime works; see [Roadmap](#roadmap).
 
@@ -179,6 +179,12 @@ print(result.summary())
 - [Benchmark Results](https://github.com/kylecui/petfishFramework/blob/master/docs/benchmark-results.md) — 3-tier strategy
 - [Examples](https://github.com/kylecui/petfishFramework/tree/master/examples/) — quickstart, tools+retrieval, multi-agent
 
+## Enterprise PoC
+
+See `examples/05_enterprise_expense.py` and `tests/test_enterprise_demo.py` for a complete enterprise expense approval scenario demonstrating all 6 DecisionEffects.
+
+Run: `python examples/05_enterprise_expense.py`
+
 ## Roadmap
 
 - **v0.1.x** (current): Core runtime, permission semantics, quickstart verified ✅
@@ -213,7 +219,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              # 223 tests
+uv run pytest              # 234 tests
 uv run ruff check src/ tests/
 ```
 

petfishframework-0.2.2/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+|---------|--------------------|
+| 0.2.x   | ✅ Active development |
+| < 0.2   | ❌ Not supported      |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in petfishFramework:
+
+1. **DO NOT** open a public GitHub issue.
+2. Email **security@kylecui.dev** with:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+3. You will receive an acknowledgment within **48 hours**.
+4. We will investigate and provide a fix timeline within **7 days**.
+
+## Security Features
+
+petfishFramework provides runtime access control for AI agents:
+
+- **6 DecisionEffects**: ALLOW, DENY, REQUIRE_APPROVAL, PARTIAL_ALLOW, MASK, DEGRADE
+- **Fail-closed DEGRADE**: no fallback → block, never execute original
+- **Input/Output/Event masking**: prevent sensitive data leakage at all layers
+- **Budget enforcement**: hard token/cost/steps limits
+- **Event-sourced audit**: every action recorded for compliance
+
+## Scope
+
+**In scope**: Runtime permission bypass, tool execution without authorization,
+audit log tampering, sensitive data leakage in events.
+
+**Out of scope**: LLM model vulnerabilities, prompt injection (mitigated by
+runtime controls but not eliminated), infrastructure security.
+
+## Disclosure Timeline
+
+- Day 0: Report received
+- Day 1-2: Acknowledgment + initial assessment
+- Day 3-7: Fix development
+- Day 7-14: Fix release + public disclosure (after fix is available)

{petfishframework-0.2.0 → petfishframework-0.2.2}/docs/api.md

@@ -1,6 +1,6 @@
 # petfishFramework API Reference
 
-This document is the authoritative reference for the public API of `petfishFramework` v0.1.9. 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.2.2. Every signature, field, and example below is derived from the source code and from the tests that exercise it.
 
 ## 1. Overview
 
@@ -327,7 +327,7 @@ class Session:
 
 `run` builds the `RuntimeEnvironment` and `RunContext`, emits `session.start`, executes the strategy, attaches accumulated `Usage` and `session_id`, and emits `session.end`.
 
-`replay` accepts an optional `ReplayMode` argument. In v0.1.9 all modes return the stored event log; full deterministic replay via `RecordingEnvironment` and `ReplayEnvironment` is available in `petfishframework.reliability.replay`.
+`replay` accepts an optional `ReplayMode` argument. In v0.2.2 all modes return the stored event log; full deterministic replay via `RecordingEnvironment` and `ReplayEnvironment` is available in `petfishframework.reliability.replay`.
 
 ```python
 agent = Agent(model=FakeModel(responses=(ModelResponse(content="ok"),)))

petfishframework-0.2.2/docs/enterprise-expense-demo.md

@@ -0,0 +1,92 @@
+# Enterprise Expense Approval Demo
+
+> Demonstrates ALL 6 DecisionEffects in a single enterprise scenario.
+
+## Overview
+
+This demo shows petfishFramework as a **runtime control framework** — not a calculator framework. An enterprise expense approval agent processes reimbursement requests with full permission gating, budget enforcement, and audit reporting.
+
+## Run
+
+```bash
+python examples/05_enterprise_expense.py
+```
+
+No API key required — uses FakeModel for deterministic, zero-cost execution.
+
+## Scenarios
+
+### 1. ALLOW + PARTIAL_ALLOW
+
+**Scenario**: Employee submits $350 team lunch expense.
+
+- `check_policy` tool executes (ALLOW)
+- Only `amount` field passed to tool; `secret` field filtered (PARTIAL_ALLOW)
+- Tool sees: `{"amount": 350}` — no sensitive data leaked
+
+### 2. MASK
+
+**Scenario**: Payment approval with recipient email.
+
+- `approve_payment` has `side_effect=True` → blocked by REQUIRE_APPROVAL first
+- When MASK policy is applied: `recipient` field masked in input args, tool result, and audit log
+- Tool sees: `{"recipient": "[MASKED]", "amount": 300}`
+
+### 3. REQUIRE_APPROVAL
+
+**Scenario**: $2000 conference expense.
+
+- `approve_payment` has `side_effect=True`
+- Policy returns REQUIRE_APPROVAL before execution
+- Tool does NOT execute — `approve_calls == 0`
+- Event: `tool.approval_required`
+
+### 4. DENY
+
+**Scenario**: Non-finance user attempts to approve payment.
+
+- Policy checks `subject.roles` for "finance"
+- Non-finance user → DENY
+- Tool does NOT execute
+- Event: `tool.blocked`
+
+### 5. DEGRADE with fallback
+
+**Scenario**: $8000 equipment expense.
+
+- Amount > $5000 → DEGRADE
+- `fallback_tool="dry_run_payment"` → original tool NOT executed
+- Fallback tool executes instead
+- Event: `tool.degraded` with `original_executed=False, fallback_executed=True`
+
+## AuditReport
+
+After each scenario, an AuditReport is generated with:
+
+- Summary (session ID, tokens, cost, steps)
+- Event Count by Type
+- Permission Summary (by effect)
+- Budget (input/output tokens, cost)
+- Timeline (tool events with duration)
+- Masked Fields summary
+- Permission Decisions
+- Errors (if any)
+- Final Output
+
+## Policy Design
+
+The `ExpensePolicy` uses tool metadata for decisions:
+
+| Condition | Effect | Reason |
+|---|---|---|
+| Non-finance + approve_payment | DENY | role-based access control |
+| Tool with side_effect=True | REQUIRE_APPROVAL | safety gate |
+| Amount > $5000 | DEGRADE → dry-run | risk threshold |
+| PII in args (recipient) | MASK | data protection |
+| check_policy | PARTIAL_ALLOW (amount only) | least privilege |
+| Otherwise | ALLOW | default |
+
+## Files
+
+- `examples/05_enterprise_expense.py` — runnable demo
+- `tests/test_enterprise_demo.py` — TDD tests (6 tests)