Metadata-Version: 2.4
Name: agenticbudget
Version: 0.2.0
Summary: Lightweight cost tracking for LLM pipelines and AI agents
Project-URL: Homepage, https://github.com/DavideZaninelloo/AgenticBudget
Project-URL: Repository, https://github.com/DavideZaninelloo/AgenticBudget
Author: Davide Zaninello
License: MIT License
        
        Copyright (c) 2026 Davide
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,anthropic,budget,cost,gemini,llm,openai,tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == 'all'
Requires-Dist: google-genai>=0.8.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=0.8.0; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# 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.
