Metadata-Version: 2.4
Name: agentwallet-gov
Version: 0.3.0
Summary: Financial governance infrastructure for AI agents — spend controls, rules engine, kill switch, and audit trail.
Project-URL: Homepage, https://github.com/JackD720/agentwallet-quickstart
Project-URL: Documentation, https://github.com/JackD720/agentwallet-quickstart#readme
Project-URL: Repository, https://github.com/JackD720/agentwallet-quickstart
Project-URL: Issues, https://github.com/JackD720/agentwallet-quickstart/issues
Author: Jack Davis
License-Expression: MIT
Keywords: ai-agents,audit-trail,crewai,fintech,governance,kill-switch,langchain,spend-controls
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.100.0; extra == 'dashboard'
Requires-Dist: uvicorn>=0.23.0; extra == 'dashboard'
Description-Content-Type: text/markdown

# AgentWallet

**Financial governance infrastructure for AI agents.**

Spend controls, rules engine, kill switch, and audit trail — every financial action an agent takes flows through governance before a dollar moves.

## Install

```bash
pip install agentwallet
```

## Quick Start

```python
from agentwallet import AgentWallet, SpendRule, RuleVerdict

# Create a governed wallet
wallet = AgentWallet("trading-agent", budget_cents=5000)  # $50 budget

# Add custom governance rules
wallet.add_rule(SpendRule(
    rule_id="block-expensive-models",
    name="Block calls over $5",
    condition=lambda ctx: ctx["amount_cents"] > 500
        and "gpt-4" in ctx.get("metadata", {}).get("model", ""),
    verdict=RuleVerdict.DENY,
))

# Every spend goes through governance
result = wallet.spend(200, "llm-inference", metadata={"model": "gpt-4"})
# {'approved': True, 'tx_id': '...', 'remaining_cents': 4800}

result = wallet.spend(800, "llm-inference", metadata={"model": "gpt-4"})
# {'approved': False, 'reason': 'Blocked by rule: block-expensive-models'}
```

## Persistence (NEW in 0.2.0)

Add `persist=True` and wallet state survives process restarts. Zero config — uses SQLite under the hood.

```python
# First run
wallet = AgentWallet("my-agent", budget_cents=5000, persist=True)
wallet.spend(200, "api-call")
wallet.spend(300, "web-search")
print(wallet.balance_cents)  # 4500

# ... restart your process ...

# Second run — state is restored automatically
wallet = AgentWallet("my-agent", persist=True)
print(wallet.balance_cents)  # 4500 — it remembered!
print(len(wallet.transactions))  # 2 — transactions restored too
```

Everything persists: balance, transactions, audit log, kill switch state. Multiple agents can share the same database file.

```python
# Custom database path
wallet = AgentWallet("agent-1", persist=True, db_path="/data/governance.db")

# Query spend analytics (with persistence)
summary = wallet._storage.get_spend_summary("agent-1")
by_category = wallet._storage.get_spend_by_category("agent-1")
all_wallets = wallet._storage.list_wallets()
```

## What's Included

- **AgentWallet** — Per-agent wallets with configurable budgets
- **GovernanceEngine** — Rules engine that evaluates every transaction
- **SpendRule** — Custom rules with priority-based evaluation
- **Kill Switch** — Instant shutdown of all agent spending
- **AuditLog** — Append-only JSONL audit trail for compliance
- **SQLite Persistence** — `persist=True` and state survives restarts
- **Spend Analytics** — Query spend by category, get summaries
- **Event Callbacks** — `wallet.on("deny", callback)` for webhooks/alerts
- **Dashboard API** — FastAPI server for real-time monitoring
- **CLI** — `agentwallet demo` and `agentwallet dashboard`

## Built-in Safety Rules

Every wallet ships with four default rules (highest priority first):

1. **Kill Switch** (priority 1000) — blocks everything when activated
2. **Max Per Transaction** (priority 900) — caps individual spend
3. **Daily Limit** (priority 800) — caps rolling 24-hour spend
4. **Balance Check** (priority 700) — prevents overdraft

## Event Callbacks

Get notified when governance events fire:

```python
import requests

# Webhook on denied transactions
wallet.on("deny", lambda data: requests.post(
    "https://hooks.slack.com/your-webhook",
    json={"text": f"🚫 Agent blocked: {data['reason']}"}
))

# Log all approved spend
wallet.on("approve", lambda data: print(f"✅ ${data['amount_cents']/100:.2f} approved"))

# Kill switch alerts
wallet.on("kill_switch", lambda data: print(f"🛑 Kill switch: {data}"))
```

## Dashboard

```bash
pip install agentwallet[dashboard]
agentwallet dashboard
```

Or programmatically:

```python
from agentwallet import AgentWallet, register_wallet, start_dashboard_server

wallet = AgentWallet("my-agent", budget_cents=10000)
register_wallet(wallet)
start_dashboard_server(port=8100)  # API at http://localhost:8100/docs
```

## CLI

```bash
agentwallet demo        # Run a quick demo with sample transactions
agentwallet dashboard   # Start the governance API server
agentwallet version     # Show version
```

## Zero Dependencies

The core SDK has **zero external dependencies**. Just Python 3.9+. The dashboard server optionally uses FastAPI + uvicorn.

## Links

- **Quickstart Repo**: [github.com/JackD720/agentwallet-quickstart](https://github.com/JackD720/agentwallet-quickstart)
- **Examples**: 3 working examples (simple agent, LangChain, CrewAI)
- **Reference**: arXiv:2501.10114 "Infrastructure for AI Agents"

## License

MIT
