Skip to main content

llmburn

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

pip install "llmburn[gemini]"
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:

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:

$ 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:

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:

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

llmburn.init(
    budget_per_user="$2/day",
    budget_total="$50/day",
    on_limit="block",
)
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

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:

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.

Metadata

Release files for llmburn 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for llmburn 0.1.0
File Size Uploaded Provenance Actions
llmburn-0.1.0.tar.gz 18.0 kB Without provenance Details for llmburn-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for llmburn 0.1.0
File Interpreter ABI Platform Actions
llmburn-0.1.0-py3-none-any.whl Python 3 none any Details for llmburn-0.1.0-py3-none-any.whl

Total release size: 33.1 kB

Release files / llmburn-0.1.0.tar.gz

Download URL llmburn-0.1.0.tar.gz
Size 18.0 kB
Tags Source
SHA-256 checksum
How to use checksums
506547530e81878aa198d1cb6cbeb44cd290131a513bdd893ac8dae08ea1c7a6
BLAKE2b-256 checksum
How to use checksums
e2ed54ca3c5ea157def0900990dcbecd2fd0d9679e07063728140f9168f4507d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Release files / llmburn-0.1.0-py3-none-any.whl

Download URL llmburn-0.1.0-py3-none-any.whl
Size 15.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
20335bb8a53f3637e6fcb56855c5b6df4b5a38e87fe8751499fb42d0f67bce94
BLAKE2b-256 checksum
How to use checksums
6e641dd61197d8cad9ee58465af822eaae7e895ce605c35b27b5efd520a839c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Security for llmburn 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page