Metadata-Version: 2.4
Name: llmstat
Version: 0.1.0
Summary: CLI-first, local LLM cost tracker for indie devs — drop it in front of any OpenAI-compatible API and watch token usage and spend in real time. No cloud, no signup.
Project-URL: Homepage, https://github.com/camelyello-88/llmstat
Project-URL: Repository, https://github.com/camelyello-88/llmstat
Author: camelyello
License: MIT
License-File: LICENSE
Keywords: cost,llm,observability,openai,proxy,tokens,tui
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: starlette>=0.37
Requires-Dist: textual>=0.80
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

<div align="center">

# 👁️ llmstat

### See what your LLM calls *actually* cost — in real time.

A modern, playful terminal dashboard that sits in front of **any OpenAI-compatible API**
(OpenAI, DeepSeek, OpenRouter, LiteLLM, vLLM, Ollama, your own gateway…) and shows you
live token usage, cost, and latency. No SDK changes. No cloud. No account.

`pip install llmstat` → point your base URL at it → watch the numbers move.

<table>
<tr>
<td align="center"><b>Light</b><br><img src="docs/light.svg" alt="llmstat light theme" width="420"></td>
<td align="center"><b>Dark</b><br><img src="docs/dark.svg" alt="llmstat dark theme" width="420"></td>
</tr>
</table>

<sub>Two pastel themes — toggle with <code>d</code>. Today / all-time with <code>t</code>.</sub>

</div>

---

## Why

You're an indie dev shipping with LLMs — self-hosted models, a personal gateway, a couple of
pay-as-you-go API keys — and you have no idea what you're spending until the invoice lands.
The big observability platforms (Helicone, Langfuse…) are built for enterprise: hosted,
signup-walled, dashboard-heavy, and hungry for your data. **llmstat** is the opposite — for
the dev who just wants *the number*: one tiny local proxy, one SQLite file, one good-looking TUI.

- 🪶 **Zero code changes** — it's a drop-in proxy. Change one base URL.
- 🔌 **Provider-agnostic** — anything that speaks the OpenAI API works.
- 🌊 **Streaming-aware** — reads usage from SSE chunks, not just plain responses.
- 💸 **Cost, not just tokens** — built-in pricing table, override your own rates.
- 🔒 **Local-first** — your prompts never touch our anything. There is no "our anything".

## Install

```bash
pip install llmstat
```

## 60-second tour (no API key needed)

```bash
llmstat demo      # seed some realistic sample traffic
llmstat dash      # open the dashboard
```

Press `t` to flip between **today** and **all-time**, `r` to refresh, `q` to quit.

## Real usage

**1. Start the proxy** in front of your provider:

```bash
llmstat serve --upstream https://api.openai.com
# llmstat proxy -> https://api.openai.com
# point your client base_url at: http://127.0.0.1:8787/v1
```

**2. Point your client at it** — only the base URL changes:

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8787/v1")  # was: the real URL
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hi"}],
)
```

**3. Watch it live** in another terminal:

```bash
llmstat dash
```

That's it. Every call your app makes now shows up with tokens, cost, and latency.

### Tag your traffic (optional)

Send an `X-Llmstat-Project` header and llmstat will group spend by project —
handy when one machine drives several apps.

### Fix or add pricing

Models change prices constantly. Drop a `~/.llmstat/pricing.json` to override:

```json
{ "my-self-hosted-llama": [0.0, 0.0], "gpt-4o": [2.50, 10.00] }
```

Values are USD per **1M** tokens: `[input, output]`.

## How it works

```
your app ──▶ llmstat proxy ──▶ real LLM API
                  │
                  └─▶ SQLite (~/.llmstat/usage.db) ──▶ TUI dashboard
```

The proxy forwards requests untouched and reads the standard `usage` block out of the
response (for streams, it tees the SSE and grabs the final usage chunk). Nothing is
buffered to disk except the counts you see.

## Roadmap

- [ ] Budgets & alerts (warn at $X/day)
- [ ] Export to CSV / Prometheus
- [ ] Per-project & per-key breakdown views
- [ ] `llmstat top` — a one-line live status bar

Ideas and PRs welcome — see an issue you'd like? Open one.

## License

MIT © llmstat contributors
