Metadata-Version: 2.4
Name: token-cost-guard
Version: 0.1.0
Summary: Track AI API token costs locally. Know your costs before the bill arrives.
Home-page: https://github.com/alexcalderado/token-cost-guard
Author: Alex Calder
Author-email: Alex Calder <alex@osolobo.com>
License: MIT
Project-URL: Homepage, https://github.com/alexcalderado/token-cost-guard
Project-URL: Repository, https://github.com/alexcalderado/token-cost-guard
Project-URL: Issues, https://github.com/alexcalderado/token-cost-guard/issues
Keywords: ai,tokens,cost,tracking,openai,anthropic,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: flask>=2.3.0
Requires-Dist: requests>=2.31.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.7.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.7.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: openai>=1.0.0; extra == "dev"
Requires-Dist: anthropic>=0.7.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Token Cost Guard

**Know your AI costs before the bill arrives.**

Track OpenAI and Anthropic API token costs locally. Never be surprised by runaway costs again.

## The Problem

Building with AI APIs is amazing until you get the bill.

- No visibility into token consumption until charges appear
- Experiments cost money (sometimes thousands)
- No circuit breakers or alerts
- Manual tracking is tedious

Token Cost Guard solves this with **local-first cost tracking** that never sends data to the cloud.

## Features

✅ **Local SQLite** - Your token data never leaves your machine  
✅ **One-line setup** - `client = track(OpenAI())`  
✅ **Real-time tracking** - Logs every API call automatically  
✅ **Cost breakdown** - View costs by model, day, and session  
✅ **Threshold alerts** - Slack/Discord webhooks when you hit limits  
✅ **CSV export** - Share reports with your team  

## Installation

```bash
pip install git+https://github.com/alexcalderado/token-cost-guard.git
```

**Note:** If the `token-guard` command is not found after installation, add Python scripts to your PATH:

```bash
export PATH="$HOME/Library/Python/3.9/bin:$PATH"  # macOS
# or 
export PATH="$HOME/.local/bin:$PATH"  # Linux
```

Add this line to your shell profile (`.zshrc`, `.bashrc`, etc.) to make it permanent.

## Quick Start

**1. Initialize configuration:**

```bash
token-guard init
```

**2. Set your API keys:**

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
```

**3. Wrap your client (one-line change):**

```python
from token_guard import track
from openai import OpenAI

# Before: client = OpenAI()
# After:
client = track(OpenAI())

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)
# Automatically logged to ~/.token-guard/guard.db
```

**4. Check your costs:**

```bash
token-guard report
```

## Usage

### View Cost Summary

```bash
token-guard report

╭──────────────────────────────╮
│  Token Cost Guard — Report   │
╰──────────────────────────────╯

Today's Cost:    $2.14
Last 30 Days:    $47.82

Top Models:
  gpt-4...................... $35.20
  claude-opus-4-5............. $12.62
```

### Export to CSV

```bash
token-guard export --days 7
# Creates: token-cost-guard-export-2026-02-15.csv
```

### Set Cost Alerts

```bash
token-guard alerts add --type daily_cost --threshold 10 \
  --webhook https://hooks.slack.com/services/YOUR/WEBHOOK
```

When daily costs exceed $10, you'll get a Slack notification.

### View Model Pricing

```bash
token-guard config --pricing

Model Pricing (per 1M tokens):
  claude-sonnet-4-5................. $3.00 input, $15.00 output
  gpt-4o............................ $2.50 input, $10.00 output
  gpt-5.2........................... $1.75 input, $14.00 output
```

## How It Works

Token Cost Guard wraps your AI client with a function that:

1. Calls the original API (no proxying, same latency)
2. Logs input/output tokens to local SQLite
3. Calculates cost based on model pricing
4. Returns the response unchanged

If logging fails, the API call still succeeds (graceful degradation).

## Supported Models

- **Anthropic:** claude-opus-4-5, claude-sonnet-4-5, claude-haiku-4-5
- **OpenAI:** gpt-5.2, gpt-5-mini, gpt-4.1, gpt-4.1-mini, gpt-4o

## Privacy

✅ **No cloud sync**  
✅ **No accounts**  
✅ **No third-party services**  

Your API cost data stays on your machine. Pricing is hardcoded and can be customized in `~/.token-guard/pricing.json`.

## v2 Roadmap

- Async/streaming support
- Local web dashboard
- Cost forecasting
- Optimization suggestions

## Support

- GitHub: https://github.com/AlexCalderAI/token-cost-guard
- Issues: Report bugs or request features

---

**Made by [@AlexCalderAI](https://x.com/AlexCalderAI) · MIT License**
