token-cost-guard 0.1.0
Track AI API token costs locally. Know your costs before the bill arrives.
License: MIT
Requires Python: >=3.9
Keywords: ai, tokens, cost, tracking, openai, anthropic, monitoring

# 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**