Metadata-Version: 2.4
Name: agentshield-spend
Version: 1.0.0
Summary: A firewall for AI agent spending. 9 composable rules evaluated per-transaction in <1ms. Pure Python stdlib — zero dependencies.
Author-email: Maryan Kondratyuk <sales@sipiteno.com>
License: MIT
Project-URL: Homepage, https://agentshield.fly.dev
Project-URL: Repository, https://github.com/kindrat86/agentshield
Project-URL: Documentation, https://agentshield.fly.dev/eval-gym-spec
Project-URL: Bug Tracker, https://github.com/kindrat86/agentshield/issues
Keywords: ai,agent,cost,budget,firewall,spend,openai,anthropic,langchain,llm,api-costs,spend-control,cost-management,rate-limit,token
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking :: Firewalls
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AgentShield — Firewall for AI Agent Spending

Stop runaway AI agents before they burn your budget. 9 composable rules evaluated per-transaction in <1ms. Pure Python stdlib — zero dependencies.

## Install

```bash
pip install agentshield
```

## Quick Start

```python
from agentshield import SpendControlEngine

engine = SpendControlEngine()

# A transaction your agent wants to make
transaction = {
    "amount": 500.00,
    "merchant": "openai-api",
    "category": "llm_inference",
    "agent_id": "my-agent",
    "timestamp": "2026-08-10T10:00:00Z",
}

# Your spend-control rules
rules = [
    {"id": "r1", "type": "transaction_limit", "priority": 1,
     "params": {"max_amount": 250}, "action": "BLOCK"},
    {"id": "r2", "type": "daily_total", "priority": 2,
     "params": {"max_daily": 2000}, "action": "BLOCK"},
    {"id": "r3", "type": "velocity", "priority": 3,
     "params": {"window_minutes": 60, "max_count": 10}, "action": "FLAGGED"},
]

# Prior transactions today (for daily_total and velocity checks)
prior_transactions = []

# Evaluate — returns in <1ms
result = engine.evaluate(transaction, rules, prior_transactions)
print(result["decision"])  # BLOCKED
print(result["reason"])    # Transaction amount $500.00 exceeds limit of $250.00
```

## Rule Types (9)

| Rule | Description | Example Params |
|------|-------------|----------------|
| `transaction_limit` | Block single calls over $X | `{"max_amount": 500}` |
| `daily_total` | Cap cumulative daily spend | `{"max_daily": 2000}` |
| `velocity` | Detect burst patterns | `{"window_minutes": 60, "max_count": 10}` |
| `merchant_allowlist` | Only approved API providers | `{"allowed": ["openai-api", "anthropic-api"]}` |
| `category_block` | Block spend categories | `{"blocked": ["crypto_exchange"]}` |
| `session_budget` | Per-session spend cap with decay | `{"max_session": 100, "decay_factor": 0.3}` |
| `cascade_cost` | Expected value with retry cost | `{"max_cascade_cost": 100, "fail_probability": 0.3, "reversal_cost": 200}` |

## Eval Gym (56 scenarios)

```python
from agentshield import run_eval

results = run_eval()
print(f"{results['passed']}/{results['total']} passed")  # 56/56
```

All 56 test scenarios are MIT licensed. Use them as test fixtures for your own spend-control implementation.

## Key Design Decisions

- **Pure Python 3.11 stdlib** — no pip install required (except for the package wrapper itself)
- **Decimal for money** — never float, always `decimal.Decimal`
- **Stateless** — no file I/O, no network, no global state
- **Deterministic** — same inputs always produce the same output
- **<1ms per evaluation**

## Links

- [Live Demo](https://agentshield.fly.dev)
- [Eval Gym Spec](https://agentshield.fly.dev/eval-gym-spec)
- [Risk Calculator](https://agentshield.fly.dev/tools/risk-calculator/)
- [GitHub](https://github.com/kindrat86/agentshield)

## License

MIT
