Skip to content

README.md

Latest commit

 

History

History
88 lines (65 loc) · 2.91 KB

README.md

File metadata and controls

88 lines (65 loc) · 2.91 KB
Raw

AgentShield, Firewall for AI Agent Spending

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

Install

pip install agentshield-spend

(The import name is agentshield, the PyPI name agentshield belongs to an unrelated project.)

Quick Start

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)

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

License

MIT