Metadata-Version: 2.4
Name: litellm-cost-tracker
Version: 0.1.0
Summary: A lightweight Python library for tracking LLM API costs via litellm's callback system
Author-email: Paawan Purdhani <paawanpurdhani@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Paawan13/litellm-cost-tracker
Project-URL: Repository, https://github.com/Paawan13/litellm-cost-tracker
Project-URL: Bug Tracker, https://github.com/Paawan13/litellm-cost-tracker/issues
Keywords: llm,cost,tracking,litellm,budget,openai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# LLM Cost Tracker

A lightweight Python library for tracking LLM API costs via litellm's callback system, with budget alerts and spending limits.

## Installation

```bash
pip install litellm-cost-tracker
```

## Quick Start

```python
import litellm
from llm_cost import CostTracker, BudgetExceededError

# Create a tracker with a $5 budget
def alert(tracker):
    print(f"Budget exceeded! Spent ${tracker.total_cost:.2f}")

tracker = CostTracker(
    budget=5.00,
    on_budget_exceeded=alert,
    raise_on_budget=True
)

# Register with litellm
litellm.callbacks = [tracker]

# Make LLM calls as usual
try:
    response = litellm.completion(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except BudgetExceededError as e:
    print(f"Stopped at ${e.total_cost:.2f} (budget: ${e.budget:.2f})")

# Check usage
print(f"Total: ${tracker.total_cost:.4f} across {tracker.request_count} requests")
```

## Features

- **Real-time cost tracking** during LLM calls
- **Budget alerts** via callback and/or exception
- **In-memory storage** (no persistence needed)
- **Uses litellm's pricing data** for accurate costs

## API Reference

### CostTracker

```python
CostTracker(
    budget: float | None = None,           # Spending limit in USD
    on_budget_exceeded: Callable | None = None,  # Callback when exceeded
    raise_on_budget: bool = False          # Raise exception when exceeded
)
```

**Properties:**

- `total_cost: float` — Running total in USD
- `request_count: int` — Number of successful requests
- `history: list[dict]` — All logged requests
- `budget: float | None` — Configured budget
- `budget_exceeded: bool` — Whether budget has been exceeded

**Methods:**

- `reset()` — Clear all tracked data

### BudgetExceededError

Raised when budget is exceeded (if `raise_on_budget=True`).

```python
class BudgetExceededError(Exception):
    budget: float       # Configured budget
    total_cost: float   # Actual spend when exceeded
```

## History Entry Format

Each request is logged with:

```python
{
    "model": "gpt-4",
    "prompt_tokens": 150,
    "completion_tokens": 50,
    "cost": 0.0123,
    "timestamp": "2026-02-22T10:30:00Z"
}
```

## Development

```bash
git clone https://github.com/Paawan13/litellm-cost-tracker.git
cd litellm-cost-tracker
pip install -e ".[dev]"
pytest
```

## License

MIT
