Metadata-Version: 2.4
Name: local-agent-cost-tracker
Version: 0.1.0
Summary: Real-time AI agent cost monitoring and budget alerting for local development
Project-URL: Homepage, https://github.com/yourusername/local-agent-cost-tracker
Project-URL: Repository, https://github.com/yourusername/local-agent-cost-tracker
Project-URL: Issues, https://github.com/yourusername/local-agent-cost-tracker/issues
Author-email: Your Name <you@example.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,cost-tracking,llm,monitoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: black>=24.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# local-agent-cost-tracker

Real-time cost tracking for AI agents—know exactly what you're spending before the bill arrives.

## What is this?

A lightweight desktop application that monitors your AI agent traffic in real-time, calculates token costs across OpenAI, Anthropic, and local models, and alerts you before you exceed your budget. Built to solve the #1 pain point from production agent deployments: "I don't know how much this is costing me until the invoice arrives." Runs entirely offline with zero telemetry, backed by SQLite, and complements observability tools by focusing purely on cost tracking.

## Features

- **Real-time cost tracking** – Monitor token consumption and costs as they happen
- **Multi-model support** – OpenAI, Anthropic, and local LLM pricing built-in
- **Budget alerts** – Get notified before you exceed spending thresholds
- **Offline-first** – Zero telemetry, no cloud dependencies, runs on your machine
- **SQLite backend** – Simple, fast, portable cost history
- **CLI + Server** – Command-line tool or HTTP server for integration
- **Docker ready** – Includes Dockerfile and docker-compose for easy deployment
- **Zero dependencies on external services** – Works with air-gapped deployments

## Quick Start

### Installation

```bash
# Clone and install
git clone <repo-url>
cd local-agent-cost-tracker
pip install -e .
```

### Configuration

Copy `.env.example` to `.env` and configure your settings:

```bash
cp .env.example .env
```

Key variables:
- `OPENAI_API_KEY` – For OpenAI model pricing (optional)
- `ANTHROPIC_API_KEY` – For Anthropic model pricing (optional)
- `BUDGET_LIMIT` – Monthly spending cap in USD
- `ALERT_THRESHOLD` – Alert when spending reaches X% of budget

### Run the Server

```bash
# Start the tracking server
python -m local_agent_cost_tracker.server

# Server runs at http://localhost:8000
```

### Command-line Usage

```bash
# Track a single API call
local-agent-cost-tracker log --model gpt-4 --tokens 150 --cost 0.0045

# View cost summary
local-agent-cost-tracker summary --period month

# Export cost history
local-agent-cost-tracker export --format csv --output costs.csv

# Check remaining budget
local-agent-cost-tracker budget
```

### Docker

```bash
docker-compose up -d
```

## Usage Example

```python
from local_agent_cost_tracker import CostTracker

tracker = CostTracker()

# Log a request
tracker.log_request(
    model="gpt-4",
    input_tokens=120,
    output_tokens=85,
    timestamp="2025-03-29T10:30:00Z"
)

# Get cost summary
summary = tracker.get_summary(period="week")
print(f"Weekly spend: ${summary['total_cost']:.2f}")
print(f"Budget remaining: ${summary['remaining_budget']:.2f}")

# Check if over budget
if tracker.is_over_budget():
    print("⚠️ Budget exceeded!")
```

## Tech Stack

- **Language**: Python 3.10+
- **HTTP Server**: FastAPI
- **Database**: SQLite
- **Pricing Engine**: Custom model pricing resolver
- **Token Counting**: tiktoken (OpenAI), built-in counters
- **Testing**: pytest
- **Deployment**: Docker, docker-compose
- **CI/CD**: GitHub Actions

## License

MIT – See [LICENSE](LICENSE) for details.

---

**Get started tracking costs in 5 minutes.** No signup, no telemetry, no surprises.