figuard-core

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.svg">
  <img src="docs/logo.svg" alt="FiGuard" height="44" />
</picture>

[![CI](https://github.com/figuard/figuard-core/actions/workflows/ci.yml/badge.svg)](https://github.com/figuard/figuard-core/actions/workflows/ci.yml)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-0A5C38.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-620%20passing-0A5C38)](#)
[![PyPI](https://img.shields.io/pypi/v/figuard?color=0A5C38)](https://pypi.org/project/figuard/)
[![npm](https://img.shields.io/npm/v/figuard?label=npm%20(ts-sdk)&color=0A5C38)](https://www.npmjs.com/package/figuard)
[![npm](https://img.shields.io/npm/v/figuard-mcp?label=figuard-mcp&color=0A5C38)](https://www.npmjs.com/package/figuard-mcp)

---

A travel-booking agent hit a Stripe timeout and retried twice. The customer's card was charged **three times for the same flight** before anyone noticed — 40 minutes later.

No alert fired. No limit existed. The agent had a valid API key and no concept of "I already did this."

FiGuard gives agents **bounded resources** — money, tokens, API calls, GPU hours, any unit you define — and they ask permission before consuming them. You set the ceiling, the retry rules, and the idempotency policy once. Every attempt, authorized or denied, lands in an append-only audit log.

That exact failure is in the stress harness: a retried charge produces **0 double-charges**, and 100 agents racing one budget produce **0 overspends** — verified against the ledger, reproducibly (`make bench`).

Your framework decides what to do next. FiGuard decides whether the resource-consuming action is allowed.

```
  Your agent code  (LangChain · LangGraph · CrewAI · any runtime)
  orchestrates — decides what to do next
          ↓  agent wants to spend / call / execute
  figuard.authorize()
  checks: limit · category · velocity · dedup
          ↓  AUTHORIZED — action proceeds
  Stripe · OpenAI · any API or service
  executes — real money or resource consumed
          ↓  action completes
  figuard.confirm()
  settles reservation — ledger updated
```

**LangChain / LangGraph** — FiGuard authorizes each tool call before it executes. A budget-exhausted agent stops cleanly instead of running up cost — even across parallel nodes in a LangGraph.

**CrewAI** — Each crew member gets a delegation token with its own cap. A runaway specialist is stopped at its limit without affecting the rest of the crew.

**OpenAI Agents SDK / MCP** — Wrap tools with `@guarded_function_tool` or add the FiGuard MCP server — every tool call is pre-flight authorized before it reaches the API.

**Not using a framework?** — The raw SDK works anywhere — a Python script, a background job, a serverless function. If it calls an API that costs money or consumes a bounded resource, FiGuard fits.

![FiGuard demo](https://github.com/user-attachments/assets/e953a132-c379-45fe-9796-644a4ec84c5d)

**Try it now — no setup, no signup:**  
→ `pip install figuard` — runs locally on your machine, nothing hosted ([Quickstart](#quickstart))  
→ [Run in Colab](https://colab.research.google.com/github/figuard/figuard-notebooks/blob/main/agent-incidents/01_infinite_loop.ipynb) — or try it in the browser  
→ [Live dashboard](https://figuard-sandbox-g1ha.onrender.com/ui)

> FiGuard is the authorization and ledger layer — not a payment processor, not a policy DSL, not an adversarial-agent firewall. [Full scope →](#what-figuard-is-not)

---

## Quickstart

**Tested with:**

| Framework | Versions | Python |
|---|---|---|
| LangChain | ≥ 0.3.0 | 3.9 – 3.12 |
| LangGraph | ≥ 0.2.0 | 3.10 – 3.12 |
| CrewAI | ≥ 0.102 | 3.10 – 3.12 |
| OpenAI Agents SDK | ≥ 0.0.5 | 3.10 – 3.12 |
| TypeScript SDK | Node ≥ 18 | — |
| MCP server | Claude Code, Cursor, Claude Desktop | — |

```bash
pip install figuard
```

```python
from figuard import FiGuardClient

# Zero-config, zero-infra — runs enforcement locally (embedded SQLite, no server).
# To share one budget across agents/processes, point at a server:
#   FiGuardClient(api_key="fg_live_...", base_url="https://figuard.mycompany.internal")
client = FiGuardClient()

budget = client.create_budget(
    user_id="agent_001",
    total_limit=500.00,
    currency="USD",
    intent_context="travel booking session",
)

auth = client.authorize(budget=budget, amount=270.00)
print(auth.decision)          # AUTHORIZED
print(auth.approved_quantity) # 270.0

# Confirm with actual charged amount — may differ from requested (taxes, FX, discounts)
client.confirm(auth, 267.00)

# Second spend — exceeds what's left ($500 - $267 = $233 remaining)
auth2 = client.authorize(budget=budget, amount=350.00)
print(auth2.decision)       # DENIED
print(auth2.denial_reason)  # INSUFFICIENT_FUNDS
```

Same calls run against a self-hosted server — and there, every authorization, denial, and
confirmation shows up in the live spend-tree dashboard. (Embedded keeps the same ledger in
your local SQLite; the live dashboard is a server feature.)

Not sure what limits to set? Add `trust_mode="SHADOW"` to `create_budget` — all checks run, nothing is blocked, and `auth.would_have_been` tells you what would have happened. When the limits look right, switch to enforcement without recreating the budget: `client.update_budget(budget.id, trust_mode="FULL_ENFORCEMENT")`.

---

## How It Works

> **Embedded and server run the same engine.** These four operations — and all **29 structured
> denial codes** — behave identically whether you `pip install figuard` and run **embedded**
> (in-process, against a local SQLite file) or point the client at a **self-hosted server**.
> Session tokens, delegation tokens, and the live spend-tree *dashboard* shown below are
> **server-mode** features; embedded keeps the same append-only ledger in your local file and
> exposes the tree programmatically via `get_spend_tree()`.

Four operations. Everything else is detail.

| Operation | What it does |
|---|---|
| `authorize()` | Agent asks permission — capacity reserved, nothing moved yet |
| `confirm()` | Report what actually moved — releases the reservation |
| `void()` | Cancel a pending authorization — reservation released |
| `fail()` | Record a failed action — reservation released |

`authorize()` reserves capacity; `confirm()` / `fail()` / `void()` then settles or releases it — every transition lands in the append-only ledger, and execution happens externally (FiGuard never sees the data or proxies the call). **In embedded mode you call `authorize`/`confirm` directly on the budget; in server mode the budget issues session tokens — and delegation tokens for fleets — but the four operations are otherwise identical.** The full lifecycle (budget → tokens → fleet delegation → ledger) is diagrammed in the [API Reference](docs/api-reference.md).

The spend tree shows the full causal chain across an orchestrator and its sub-agents:

![FiGuard Spend Tree — orchestrator with confirmed and denied sub-agent events](docs/spend-tree.png)

---

## How the Hard Parts Are Solved

The authorize endpoint looks simple — check the balance, write a record. The parts that matter aren't obvious until you've hit them in production:

**Concurrent authorization** — two agents sharing a budget can both read the same available balance, both see enough funds, and both get approved. By the time the second write lands, you're over limit. The fix is a pessimistic write lock on the budget row during authorization. Easy to know, easy to forget.

**Dangling reservations** — a network timeout between the authorization write and the HTTP response leaves the agent with no event ID and the budget with a reserved amount it can't release. You need idempotency keyed to the request, not the response, so a retry finds the original authorization instead of creating a second one.

**The reservation/confirmation split** — if you use a single `amountSpent` field and deduct at authorization time, two concurrent authorizations both read the same balance before either writes. The correct model is two fields: `amountReserved` (deducted at authorization) and `amountSpent` (moved from reserved at confirmation). This is the two-phase reserve-then-capture pattern that payment processors use. It's not novel — it's just usually hidden inside Stripe.

**Session token security** — you need a token that scopes to exactly one budget, is returned exactly once, and is never stored in plaintext. If you store the raw token and your database is breached, every active agent session is compromised. Hash at write time, never store the raw value.

**Append-only ledger** — a mutable status field on an authorization record loses history. When you need to reconstruct what happened and why a budget hit its limit — or when a finance team asks why $40K of agent spend happened last Tuesday — you want every state transition as a separate row, not an update to the previous one.

These are the same problems payment infrastructure teams solved 20 years ago. The reserve-then-confirm pattern, idempotency keyed to the request, append-only ledger — none of it is novel. FiGuard is that infrastructure applied to agent systems.

---

## Failure Scenarios

These are failure modes that logging and observability tools can't catch — they require enforcement at authorization time. Each has a Colab to run with no API keys needed.

Notebooks live in [figuard-notebooks](https://github.com/figuard/figuard-notebooks); each runs in Colab with no API keys required.

| Scenario | Framework | Failure mode | FiGuard stops it at | Colab |
|---|---|---|---|---|
| **Payment retry storm** | LangChain | Tool times out after Stripe charges. Retry = double charge. | Idempotency key — retry returns the same event, Stripe never called twice | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/figuard/figuard-notebooks/blob/main/framework-scenarios/01_langchain_payme