# agenticbudget

[![PyPI version](https://img.shields.io/pypi/v/agenticbudget.svg)](https://pypi.org/project/agenticbudget/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![CI](https://github.com/DavideZaninelloo/AgenticBudget/actions/workflows/ci.yml/badge.svg)](https://github.com/DavideZaninelloo/AgenticBudget/actions/workflows/ci.yml)

**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

```python
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

```bash
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:

```bash
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

```python
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

```python
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

```python
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:

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

### Decorator

```python
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

```python
from agentbudget import CostTracker

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

## API Reference

### `CostSession`

```python
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`

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

### `@track`

```python
@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.

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

## License

MIT — see [LICENSE](LICENSE) for details.
