Metadata-Version: 2.5
Name: llmburn
Version: 0.1.0
Summary: See who's burning your AI budget: per-user LLM cost tracking and caps.
Author: Ian Abu
License-Expression: MIT
License-File: LICENSE
Keywords: ai,billing,budget,cost,gemini,llm,openai,token,tracking,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == 'anthropic'
Provides-Extra: gemini
Requires-Dist: google-genai; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai; extra == 'openai'
Description-Content-Type: text/markdown

# llmburn

Track what each of your users costs you in Gemini calls, and cut them off before they cost too much.

```bash
pip install "llmburn[gemini]"
```

```python
import llmburn

llmburn.init()        # writes to ./llmburn.db
llmburn.instrument()  # from here on, every Gemini call is recorded
```

Then tag the calls with the user who made them:

```python
with llmburn.track(user_id=user.id, plan=user.plan, feature="summarize"):
    resp = client.models.generate_content(model="gemini-3.5-flash-lite", contents=prompt)
```

And see who's spending what:

```console
$ llmburn report --by user --last 30d
LLM spend by user, the last 30 days

USER    CALLS  INPUT TOK  OUTPUT TOK    COST
--------------------------------------------
u_4821  9,412  9,412,000   3,100,000  $41.20
u_0193  2,201  2,201,000     600,000   $6.75
u_7730    310    150,000      40,000   $0.42
--------------------------------------------
TOTAL  11,923                         $48.37
```

(Example data.) If you charge a flat monthly price, the top row is the one to look at.

## How it works

`instrument()` wraps the `google-genai` SDK's `generate_content` methods. Each call goes to Google exactly as before; when the response comes back, llmburn reads the token counts Google already includes in it (`usage_metadata`), prices them, and writes one row to SQLite. Your code and the response are untouched.

The token counts are Google's own numbers, not an estimate. Prices come from a bundled table (`prices.json`) that handles thinking tokens, cached input, the >200k-token tier on Pro models, and price changes Google has announced with a date.

If anything inside llmburn fails (unknown model, locked database), it logs a warning and your request carries on. The one exception is a budget you set to `block`, below.

## Tagging

`track()` works as a `with` block or a decorator, and tags nest:

```python
with llmburn.track(user_id=user.id, plan="pro"):
    write_cover_letter(job)            # inherits user_id and plan

@llmburn.track(feature="cover_letter")
def write_cover_letter(job): ...       # adds feature
```

Tags are per thread and per async task, so concurrent requests in Flask or FastAPI don't mix up users. Calls with no tags are still recorded, as `(untagged)`.

A Flask route looks like this:

```python
@app.post("/rewrite")
def rewrite():
    with llmburn.track(user_id=g.user.id, plan=g.user.plan, feature="rewrite"):
        resp = client.models.generate_content(model="gemini-3.5-flash-lite", contents=...)
    return {"text": resp.text}
```

## Budgets

You can cap spending per user, for the whole app, or both. The check runs before the request is sent, so a blocked call never reaches Google and isn't billed.

```python
llmburn.init(
    budget_per_user="$2/day",
    budget_total="$50/day",
    on_limit="block",
)
```

```python
try:
    with llmburn.track(user_id=g.user.id):
        resp = client.models.generate_content(...)
except llmburn.BudgetExceeded as e:
    if e.is_total:
        return {"error": "AI features are paused for today."}, 503
    return {"error": "You've reached today's limit."}, 429
```

`on_limit` can be:

- `"block"`: raise `llmburn.BudgetExceeded`
- `"downgrade"`: send the call to a cheaper model instead (`downgrade_to="gemini-3.5-flash-lite"`)
- `"warn"`: log it and let the call through

Periods are `/hour`, `/day`, `/week` or `/month` (30 days), measured as a rolling window, so `$2/day` means the last 24 hours. Untagged calls only count toward `budget_total`.

## Reports

```bash
llmburn report                           # by user, last 7 days
llmburn report --by feature --last 30d
llmburn report --by model --last 24h
llmburn report --by plan --last all
llmburn report --db sqlite:///path/to/llmburn.db --limit 50
```

Or from Python:

```python
store = llmburn.init()
for row in store.totals(by="user_id"):
    print(row.key, row.calls, row.cost_usd)
```

## What's stored

One row per call: timestamp (UTC), `user_id`, `plan`, `feature`, model, input/output/cached tokens, and cost in USD. Prompts and responses are never stored.

## Supported

| `google-genai` method | |
| --- | --- |
| `client.models.generate_content` | yes |
| `client.models.generate_content_stream` | yes, one row when the stream ends |
| `client.aio.models.generate_content` | yes |
| `client.aio.models.generate_content_stream` | yes |

## Limitations

- Gemini only for now. OpenAI and Anthropic are next.
- Prices ship with the package. When Google changes them, you need a new llmburn release until automatic updates land.
- Budgets can overshoot by a call or two when several requests for the same user arrive at once.
- Text models only. Image, audio, TTS and live models aren't priced yet; their calls are skipped with a warning.

## Planned

- OpenAI and Anthropic SDKs
- Flask, FastAPI and Django middleware that sets `user_id` for you
- Automatic price-table updates
- A hosted dashboard with revenue per customer next to cost

Python 3.9+. No required dependencies. MIT license.
