Metadata-Version: 2.4
Name: powerailabs-tokenguard
Version: 0.3.0
Summary: Budget: pre-flight cost caps, spend attribution, and circuit-breakers for LLM calls.
Author: Raghav Mishra
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: powerailabs-core<0.2,>=0.1.1
Description-Content-Type: text/markdown

# powerailabs-tokenguard

Stop runaway LLM bills, and get per-feature / per-user cost attribution for free. One decorator,
one context manager. No dashboard, no account, no infra.

**Caught a $40 runaway loop before it ran away — and told you which feature spent the rest.**

![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)

🚧 building · `pip install powerailabs-tokenguard` · `from powerailabs.tokenguard import budget, track`

```python
from powerailabs.core import instrument
from powerailabs.tokenguard import budget, track, report

client = instrument(openai_client)              # wrap once; tokenguard subscribes, never patches

@budget(usd=0.50, on_exceed="raise")            # trips the breaker, stopping a looping agent
def answer(q: str) -> str:
    with track(feature="support_bot", user_id="alice"):   # ambient attribution, zero bookkeeping
        resp = client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": q}])
        return resp.choices[0].message.content

# Where did the money go? Grouped spend, tokens, and call counts per tag:
for row in report(group_by=["feature", "user_id"]):
    print(row["tags"], row["usd"], row["calls"])
```

**Wrap-around:** it rides the call you already make — `@budget` records actual spend post-flight
and trips when an active cap is breached; `estimate(model, messages)` projects cost pre-flight
for proactive checks. `on_exceed` can also `truncate` (degrade gracefully) or call your own
function. Offline and standalone — bundled prices mean no network and no account.

See [`docs/tokenguard.md`](../../docs/tokenguard.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*
