Metadata-Version: 2.4
Name: token-usage-visualizer
Version: 0.1.0
Summary: A Python package to track, log, and visualize LLM token usage
Author-email: Developer <developer@example.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: fastapi>=0.95.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.20.0; extra == "dashboard"
Requires-Dist: plotly>=5.10.0; extra == "dashboard"
Dynamic: license-file

# Token Usage Visualizer

[![PyPI Version](https://img.shields.io/pypi/v/token-usage-visualizer.svg)](https://pypi.org/project/token-usage-visualizer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Versions](https://img.shields.io/pypi/pyversions/token-usage-visualizer.svg)](https://pypi.org/project/token-usage-visualizer/)

**`token-usage-visualizer`** is a zero-friction, multi-provider Python package designed to track, log, audit, and visually analyze LLM token usage and expenditures. Whether you are using OpenAI, Anthropic, Google Gemini, or custom model endpoints, this tool automatically parses client responses, persists expenditures to a lightweight local SQLite database, and presents insights via an intuitive Streamlit dashboard.

---

## Key Features

1. **Zero-Friction Decorator**: Wrap your LLM-calling functions with `@track_usage` to automatically capture and log input, output, and total tokens.
2. **Multi-Provider Support**: Built-in, robust normalizers for **OpenAI**, **Anthropic**, and **Google Gemini** API response objects/dictionaries, with an overridable generic schema.
3. **Storage Abstraction**: Persists logs locally to SQLite by default with index-accelerated query capabilities.
4. **Interactive Dashboard**: High-fidelity Streamlit + Plotly visual interface displaying daily spending trends, token breakdowns, and model efficiency tables.
5. **Session-Level Rollups & Anomaly Detection**: Evaluates conversation logs using statistical **Z-score anomaly checks** to identify high-volume token spikes.
6. **Cost & Budget Intelligence**: Custom model rate configuration via a local `token_viz.yaml` file, complete with end-of-month budget alarms and spending forecasts.
7. **Robust CLI**: Complete command-line management (`token-viz`) to import JSONL files, print aggregated summaries, export data to CSV/JSON, and launch the dashboard.

---

## Installation

Install the core package (tracking, CLI, storage):
```bash
pip install token-usage-visualizer
```

To install with Streamlit dashboard and plotting capabilities:
```bash
pip install token-usage-visualizer[dashboard]
```

---

## 3-Line Quickstart

```python
from token_visualizer.core.tracker import TokenTracker
from token_visualizer.core.storage import SQLiteBackend
from token_visualizer.middleware import track_usage

# 1. Initialize tracker
tracker = TokenTracker(SQLiteBackend())

# 2. Decorate LLM function (automatically tracks, calculates cost, and logs)
@track_usage(tracker, provider="openai")
def ask_gpt(prompt):
    # Returns standard OpenAI chat completion dict or response object
    return openai_client.chat.completions.create(model="gpt-4o", messages=[{"role": "user", "content": prompt}])
```

---

## Command Line Interface (`token-viz`)

The package registers a global `token-viz` command-line executable.

### 1. Initialize Configuration
Scaffold a default `token_viz.yaml` to specify custom $/1k-token model rates:
```bash
token-viz init
```

### 2. Log Raw Payloads
Import historical token usage records from a JSON Lines (`.jsonl`) file:
```bash
token-viz log --file records.jsonl
```

### 3. Display Aggregated Summaries
Display quick terminal tables aggregated by `day`, `model`, or `session`:
```bash
token-viz summary --by model
token-viz summary --by day --since 7d
```

### 4. Export Records
Export raw usage records to CSV or JSON format:
```bash
token-viz export --format csv --out ./token_logs.csv
```

### 5. Launch the Dashboard
Open the interactive Streamlit analytics panel:
```bash
token-viz dashboard --port 8501
```
> **Tip**: Use the `--demo` flag to seed the database with 30 days of realistic multi-provider mock data to explore the visual features instantly!
> ```bash
> token-viz dashboard --demo
> ```

---

## Streamlit Dashboard Analytics

The dashboard exposes an exceptional, professional-grade analytics view:
- **Alert Banner**: Highlights if spending has exceeded your monthly budget limit, and forecasts end-of-month costs based on historical daily burn rates.
- **Anomaly Detection Expander**: Lists and flags conversation sessions with unusually high token intake (Z-score > 2.0).
- **Core Metrics**: Real-time display of total API calls, tokens consumed, expenditures (USD), and average cost per query.
- **Charts**: Interactive spending line graphs, provider token distributions, and cost-share pie charts.
- **Rollups**: Fully filterable session tables showing aggregates, record counts, and custom metadata tags.

---

## Development & Contribution

### Editable Local Setup
To scaffold and work on the project locally:
```bash
git clone https://github.com/your-username/token-usage-visualizer.git
cd token-usage-visualizer
pip install -e .[dashboard] --break-system-packages
```

### Running Tests
Execute the full unit test suite covering parsers, database schemas, Click CLI, and tracker decorators:
```bash
python -m pytest
```

---

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
