Metadata-Version: 2.4
Name: llm-spend-tracker
Version: 0.1.0
Summary: Track and limit LLM API spending in real-time. Drop-in middleware for OpenAI, Anthropic, Google, and any OpenAI-compatible API.
Author-email: Zach <zacharie@astera.org>
License: MIT
Project-URL: Homepage, https://github.com/zachbg/llm-spend
Project-URL: Issues, https://github.com/zachbg/llm-spend/issues
Keywords: llm,openai,anthropic,cost,budget,spending,ai,gpt,claude,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# llm-spend

**Track and limit LLM API spending in real-time.** Drop-in wrapper for OpenAI, Anthropic, Google, and any OpenAI-compatible API. Know exactly where your money goes. Set budgets. Get alerts before you go broke.

## The Pain

You're burning $50/day on LLM APIs and have no idea which feature, model, or prompt is responsible. You find out when the invoice arrives.

## Install

```bash
pip install llm-spend
```

## Quick Start

### Wrap your OpenAI client

```python
from llm_spend import track
import openai

client = openai.OpenAI()
tracked = track(client, budget=50.0)  # $50 budget

# Use exactly like normal - spending is tracked automatically
response = tracked.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

# Check spending anytime
print(tracked.spending.report())
# Total: $0.42 | gpt-4o: $0.38 (12 calls) | gpt-3.5-turbo: $0.04 (45 calls)
```

### Set budgets with alerts

```python
tracked = track(client,
    budget=100.0,           # Hard limit - raises BudgetExceeded at $100
    warn_at=0.8,            # Callback at 80%
    on_warn=lambda s: print(f"⚠️ {s.total_cost:.2f}/{s.budget}"),
    on_budget=lambda s: notify_slack(s),  # Custom handler
    reset="daily",          # Reset budget daily/weekly/monthly
)
```

### Track by label (know WHERE money goes)

```python
response = tracked.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    extra_headers={"X-LLM-Spend-Label": "summarizer"},  # tag this call
)

# Later:
for label, cost in tracked.spending.by_label().items():
    print(f"  {label}: ${cost:.2f}")
# summarizer: $12.50
# classifier: $3.20
# chatbot: $45.00
```

### CLI dashboard

```bash
# Show live spending from log file
llm-spend report --file spending.jsonl

# Set environment budget (works with any wrapped client)
export LLM_SPEND_BUDGET=50
export LLM_SPEND_WARN=0.8
export LLM_SPEND_RESET=daily
```

## Cost Database

Built-in pricing for 50+ models (updated regularly):

| Provider | Models |
|---|---|
| OpenAI | GPT-4o, GPT-4o-mini, GPT-4-Turbo, GPT-3.5-Turbo, o1, o1-mini, o3-mini |
| Anthropic | Claude 4 Opus/Sonnet, Claude 3.5 Sonnet/Haiku, Claude 3 Opus/Sonnet/Haiku |
| Google | Gemini 2.0/1.5 Pro/Flash |
| Meta | Llama 3.x (via API providers) |
| Mistral | Mistral Large/Medium/Small |

Custom model costs:
```python
tracked = track(client, custom_costs={
    "my-fine-tuned-model": (0.005, 0.015),  # (input_per_1k, output_per_1k)
})
```

## API Reference

```python
# Core
tracked = track(client, budget=None, warn_at=0.8, reset=None)
tracked.spending.total_cost        # float - total $ spent
tracked.spending.by_model()        # dict[str, float]
tracked.spending.by_label()        # dict[str, float]
tracked.spending.call_count         # int
tracked.spending.report()          # str - formatted report
tracked.spending.reset()           # manually reset counters
tracked.spending.to_jsonl(path)    # export log

# Exceptions
from llm_spend import BudgetExceeded
```

## Features

- **Zero config** — wrap client, get tracking
- **Accurate pricing** — 50+ models with per-token costs
- **Budget enforcement** — hard limits that prevent overspend
- **Labels** — attribute costs to features/teams/users
- **CLI** — terminal dashboard and reports
- **Async support** — works with async OpenAI client
- **No dependencies** — pure Python, no external packages
- **Thread-safe** — safe for concurrent use

## License

MIT
