Metadata-Version: 2.4
Name: tracellm
Version: 0.2.2
Summary: Local-first observability for LLM applications
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# tracellm

Lightweight tracing for LLM applications. One decorator —
every API interaction logged locally, queryable from your terminal.

No backend. No signup. Nothing leaves your machine.

## Install
```bash
pip install tracellm
```

## Usage
```python
from tracellm import trace
import groq

client = groq.Groq(api_key="your-key")

@trace
def ask(model, messages):
    return client.chat.completions.create(model=model, messages=messages)

ask(
    model="llama-3.1-8b-instant",
    messages=[{"role": "user", "content": "Explain black holes in one line"}]
)
```

Every call is traced automatically. No try/except. No setup.

## Query traces
```bash
python -m tracellm.cli --Status failed
python -m tracellm.cli --Latency 2.0
python -m tracellm.cli --Model llama-3.1-8b-instant
python -m tracellm.cli --Status failed --Latency 1.5
python -m tracellm.cli --Time "2026-04-03"
```

## Cost tracking
```bash
# cost per trace
python -m tracellm.cli --Cost

# full summary by model
python -m tracellm.cli --Cost Summary
```

Output:
=== Cost Summary ===
llama-3.1-8b-instant
Calls  : 8
Tokens : 405
Cost   : $0.000020

Total calls made : 8
Total tokens used: 405
Total cost       : $0.000020

## What gets captured
- Model, prompt, response
- Tokens used, latency, finish reason
- Error type and message on failures
- Timestamp for every call

## Pricing
Default pricing is bundled. To override, create `~/.tracellm/pricing.json`:
```json
{
  "my-custom-model": 0.05
}
```
Values are per million tokens.

## Limitations
Storage is append-only JSON lines. Latency filter supports `>=`,
exact match for everything else. Early days.

## Roadmap
- Binary storage for faster querying at scale
- Async tracing support
- Terminal dashboard
