Shekel¶

Hard Budget Caps

Wrap any agent in a context manager. Shekel intercepts every LLM call, tracks exact spend, and raises BudgetExceededError the moment you cross the limit. No SDK changes. No config.

with budget(max_usd=5.00, warn_at=0.8) as b:
    run_my_agent()
# warns at $4.00, hard stops at $5.00

Automatic Model Fallback

Don't crash — switch. Define a cheaper fallback model and shekel transparently rewrites the model parameter when the threshold is hit.

with budget(max_usd=1.00, fallback={"at_pct": 0.8, "model": "gpt-4o-mini"}):
    run_my_agent()
# gpt-4o → gpt-4o-mini at $0.80, hard stop at $1.00

Nested Budgets

Break multi-stage pipelines into per-stage budgets. Children auto-cap to the parent's remaining balance. b.tree() gives you a live visual breakdown.

with budget(max_usd=10.00, name="pipeline") as pipeline:
    with budget(max_usd=2.00, name="research"):
        search_and_analyze()
    with budget(max_usd=5.00, name="synthesis"):
        write_report()

print(pipeline.tree())
# pipeline: $4.80 / $10.00
#   research:  $1.20 / $2.00
#   synthesis: $3.60 / $5.00

Tool Call Budgets

Cap agent tool dispatches before they spiral. Auto-intercepted for LangChain, MCP, CrewAI, and OpenAI Agents SDK. One decorator for plain Python.

@tool(price=0.01)
def web_search(query: str) -> str: ...

with budget(max_usd=5.00, max_tool_calls=20) as b:
    run_my_agent()
# ToolBudgetExceededError on call 21 — before the tool runs

Loop Guard

Catches stuck agents before they drain your budget. A per-tool rolling-window counter fires AgentLoopError when the same tool repeats too many times — no matter what the total spend is.

with budget(max_usd=5.00, loop_guard=True) as b:
    run_my_agent()
# AgentLoopError if any tool repeats 5x in 60s

Velocity Circuit Breaker

Cap how fast you burn money, not just how much. A bursty agent can blow through max_usd before you can react — max_velocity stops it in seconds.

with budget(max_usd=50.00, max_velocity="$1/min") as b:
    run_my_agent()
# SpendVelocityExceededError if burn rate > $1/min

Temporal (Rolling-Window) Budgets

Enforce $5/hr per user, per API tier, or per agent. The string DSL handles multi-cap windows. BudgetExceededError carries retry_after so callers know when the window resets.

api_budget = budget("$5/hr + 100 calls/hr", name="api-tier")
async with api_budget:
    response = await client.chat.completions.create(...)

Distributed Budgets

Enforce shared limits atomically across multiple processes, workers, or containers. One Lua script per call — no race conditions.

from shekel.backends.redis import RedisBackend

backend = RedisBackend()  # reads REDIS_URL from env
with budget("$5/hr", name="api-tier", backend=backend):
    client.chat.completions.create(...)

Framework Circuit Breakers

Per-node, per-chain, per-agent, and per-task caps. Shekel patches your framework transparently — zero changes to your LangGraph graphs, CrewAI crews, or LangChain chains.

with budget(max_usd=10.00) as b:
    b.node("fetch_data", max_usd=0.50)   # LangGraph
    b.chain("retriever", max_usd=0.20)   # LangChain
    b.agent("researcher", max_usd=2.00)  # CrewAI / OAI Agents
    b.task("summarize", max_usd=0.50)    # CrewAI

CLI — Zero Code Changes

Run any Python agent under a budget from the command line. CI-friendly exit codes. Works with Docker, GitHub Actions, and shell scripts.

shekel run agent.py --budget 5
AGENT_BUDGET_USD=5 shekel run agent.py

OpenTelemetry Metrics

9 OTel instruments covering cost, utilization, spend rate, fallback activations, and loop events. Compatible with Prometheus, Grafana, Datadog, and any OTel backend.

from shekel.otel import ShekelMeter
meter = ShekelMeter()  # silent no-op if OTel is absent

Langfuse Integration

Per-call cost streaming, circuit-break events, and budget hierarchy in Langfuse spans — see exactly where your budget breaks.

from shekel.integrations.langfuse import LangfuseAdapter
AdapterRegistry.register(LangfuseAdapter(client=lf))

Quick Start Guide

Step-by-step examples — tracking, enforcement, fallback, nested budgets, async, streaming.

Usage Guide

Deep-dives into every feature: enforcement modes, tool budgets, loop guard, velocity, temporal budgets.

Integrations

Framework-specific guides for LangGraph, CrewAI, LangChain, OpenAI Agents SDK, Gemini, and more.

API Reference

Complete documentation of all parameters, properties, methods, and exceptions.