CAIN Budget

Hard spending limits enforced before every AI action executes. Reserve, authorize, execute, and account — with evidence.

Quick Start

# 1. Create a budget
curl -X POST https://cainstudio.online/fabric/budgets \
  -H "X-Tenant-ID: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{"name":"$100/month limit","scope":"tenant","limit_cents":10000,"period":"monthly","hard_limit":true}'

# 2. Reserve before an action (enforcement point)
curl -X POST https://cainstudio.online/fabric/budgets/{budget_id}/reserve \
  -H "X-Tenant-ID: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":150,"action":"model_inference"}'

# 3. Commit after execution (record actual cost)
curl -X POST https://cainstudio.online/fabric/budgets/{budget_id}/commit/{reservation_id} \
  -H "X-Tenant-ID: your-tenant" \
  -H "Content-Type: application/json" \
  -d '{"actual_cost_cents":142}'

# 4. Release if action was not executed
curl -X POST https://cainstudio.online/fabric/budgets/{budget_id}/release/{reservation_id} \
  -H "X-Tenant-ID: your-tenant"

How Enforcement Works

Step 1

Estimate

Agent requests action cost

Step 2

Authorize

Identity + Policy + Budget check

Step 3

Reserve

Lock funds before execution

Step 4

Execute

Only if ALLOW

Step 5

Commit

Record actual cost

API Endpoints

Method	Path	Description
GET	/fabric/budgets	List all budgets for tenant
POST	/fabric/budgets	Create a new budget
GET	/fabric/budgets/{id}	Get budget details
PATCH	/fabric/budgets/{id}	Update budget limits
POST	/fabric/budgets/{id}/reserve	Reserve funds (enforcement point)
POST	/fabric/budgets/{id}/commit/{res_id}	Commit actual cost
POST	/fabric/budgets/{id}/release/{res_id}	Release unused reservation
GET	/fabric/budgets/{id}/usage	Get spending usage
GET	/fabric/budgets/{id}/transactions	Get transaction history
POST	/fabric/budgets/{id}/freeze	Freeze budget (deny all)
POST	/fabric/budgets/{id}/unfreeze	Unfreeze budget

Security Model

Tenant isolation: Every operation requires X-Tenant-ID. Cross-tenant access returns 404.
Fail-closed: Unknown budgets, service errors, and malformed requests return DENY.
Atomic reservations: BEGIN IMMEDIATE transactions prevent concurrent overspend.
Idempotency: Duplicate reservations with same idempotency_key return the original.
Evidence: Every decision is recorded with tenant, amount, verdict, and timestamp.

CLI

cain budget list
cain budget get {budget_id}
cain budget create --name "My Budget" --limit-cents 5000 --period monthly
cain budget reserve {budget_id} --amount 100 --action model_inference
cain budget commit {budget_id} {reservation_id} --actual-cost 95
cain budget release {budget_id} {reservation_id}
cain budget usage {budget_id}
cain budget freeze {budget_id}
cain budget unfreeze {budget_id}

Quick Start

How Enforcement Works

API Endpoints

Security Model

CLI

Public Demonstration