agenticbudget 0.2.0

Lightweight cost tracking for LLM pipelines and AI agents

agenticbudget

Lightweight cost tracking for LLM pipelines and AI agents.

---

The Problem

When building AI applications with multiple LLM calls, it's hard to know where your budget is going. Provider dashboards show total spend, but not which step in your pipeline is burning money. You don't know if it's the summarization step, the scoring step, or the rewrite step — until you add tracking yourself.

agentbudget solves this in 2 lines.

Quickstart

from agentbudget import CostSession

with CostSession(name="my-pipeline", budget=0.05) as session:
    response = openai_client.chat.completions.create(model="gpt-4o", messages=[...])
    session.track(response, label="generate")
    response = openai_client.chat.completions.create(model="gpt-4o-mini", messages=[...])
    session.track(response, label="rewrite")
# Summary printed automatically

Output:

─────────────────────────────────────────────────────
 Session: my-pipeline
─────────────────────────────────────────────────────
 generate │ gpt-4o      │  1,243 tok │ $0.0064  │ 95%
 rewrite  │ gpt-4o-mini │    891 tok │ $0.0003  │  5%
─────────────────────────────────────────────────────
 TOTAL    │             │  2,134 tok │ $0.0067
 Budget   │ $0.05        │ ✓ Within budget
─────────────────────────────────────────────────────

Features

• Zero required dependencies — openai and anthropic are optional extras
• Auto-detection — no need to specify the provider; it's detected from the response object
• Supported providers — OpenAI, Anthropic, and Google Gemini
• Budget enforcement — set a spending cap; get a warning or exception when exceeded
• Session summary — formatted table showing cost per step and total
• Persistent history — sessions stored locally in ~/.agentbudget/sessions.json
• Aggregate reports — see total spend, most expensive step, most used model
• Decorator support — wrap any function with @track for automatic tracking
• Python 3.9+ — no modern Python required

Installation

pip install agenticbudget

That's it. If you already have openai, anthropic, or google-genai installed in your project, agentbudget will work automatically — no extra configuration needed.

The optional extras are only needed if you want to install the SDK at the same time:

pip install agenticbudget[openai]     # agentbudget + OpenAI SDK
pip install agenticbudget[anthropic]  # agentbudget + Anthropic SDK
pip install agenticbudget[gemini]     # agentbudget + Google Gemini SDK
pip install agenticbudget[all]        # agentbudget + all SDKs

Examples

OpenAI

from agentbudget import CostSession

with CostSession(name="content-pipeline", budget=0.10) as session:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Generate 5 blog post ideas"}]
    )
    session.track(response, label="generate")

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Rewrite the best idea"}]
    )
    session.track(response, label="rewrite")

Anthropic

from agentbudget import CostSession

with CostSession(name="research-agent", budget=0.05) as session:
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Research quantum computing"}]
    )
    session.track(response, label="research")

Google Gemini

from agentbudget import CostSession
import google.generativeai as genai

with CostSession(name="gemini-pipeline", budget=0.05) as session:
    model = genai.GenerativeModel("gemini-2.0-flash")
    response = model.generate_content("Summarize quantum computing in 3 points")
    session.track(response, label="summarize")

If you use the newer google-genai SDK, the model is detected automatically from response.model_version. If you use the older google-generativeai SDK (which doesn't include the model in the response), pass it explicitly:

session.track(response, label="summarize", model="gemini-2.0-flash")

Decorator

from agentbudget import track

@track(label="summarize", budget=0.02)
def summarize(text: str):
    return openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"Summarize: {text}"}]
    )

result = summarize("Long article text...")

Aggregate Report

from agentbudget import CostTracker

tracker = CostTracker()
tracker.report(last=7)   # last 7 days
tracker.clear()          # reset history

API Reference

CostSession

CostSession(
    name: str,
    budget: Optional[float] = None,
    strict: bool = False,
    verbose: bool = True,
    provider: str = "auto"   # "openai", "anthropic", "gemini", or "auto"
)

Parameter	Description
name	Session name shown in the summary
budget	Max spend in USD. Triggers warning (or exception if strict=True) when exceeded
strict	If True, raise BudgetExceededError instead of warning
verbose	If False, suppress console output
provider	Force a provider or use "auto" for auto-detection

Methods:

• session.track(response, label="", model=None) — track an LLM response. model overrides the model name (useful for older Gemini SDK)
• session.summary() — return the summary as a string
• session.total_cost — total cost in USD (float)
• session.total_tokens — total token count (int)

CostTracker

tracker = CostTracker()
tracker.report()          # all-time report
tracker.report(last=7)    # last 7 days
tracker.clear()           # delete history

@track

@track(label="...", budget=0.02, strict=False, verbose=True)
def my_function(...):
    return llm_client.call(...)

Exceptions

• BudgetExceededWarning — emitted when budget is exceeded and strict=False
• BudgetExceededError — raised when budget is exceeded and strict=True

Roadmap

v0.3:

• CLI command: agentbudget report
• HTML/graphical reports
• Streaming support
• Web dashboard

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

git clone https://github.com/DavideZaninelloo/AgenticBudget
cd AgenticBudget
pip install -e ".[all,dev]"
pytest

License

MIT — see LICENSE for details.