petfishframework 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: petfishframework
-Version: 0.2.1
+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: 234](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).
 
@@ -210,7 +210,9 @@ print(result.summary())
 
 ## Enterprise PoC
 
-See `examples/05_enterprise_expense.py` (coming in v0.2.0 release) and `tests/test_enterprise_demo.py` for a complete enterprise expense approval scenario demonstrating all 6 DecisionEffects.
+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
 

{petfishframework-0.2.1 → 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: 234](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).
 
@@ -181,7 +181,9 @@ print(result.summary())
 
 ## Enterprise PoC
 
-See `examples/05_enterprise_expense.py` (coming in v0.2.0 release) and `tests/test_enterprise_demo.py` for a complete enterprise expense approval scenario demonstrating all 6 DecisionEffects.
+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
 

{petfishframework-0.2.1 → 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)