# Frontier Model Cost Auditor

## PURPOSE
The video quotes a specific, checkable number: Gemini 4 Argon's API ships with
introductory pricing of "$10 per million of tokens output," and calls it cost-effective
against other frontier models. That sentence is a procurement decision waiting to happen.
This CLI turns a workload description into a cost table: how many requests, how many
input and output tokens each, and what that costs per model under different rate cards —
so a student can see for themselves when the cheap-looking model actually wins.

## WHY THIS MATTERS
Agents spend far more on output tokens than people assume, because reasoning and tool
loops are generated text. A "$10 / 1M output" headline is meaningless without a workload
shape. This project teaches the single most neglected production skill in LLM work: cost
modelling with real token accounting, not vibes.

## HOW TO BUILD
1. `pip install -r requirements.txt`.
2. Load a rates CSV (`model,input_per_m,output_per_m,source`) and a workload JSON
   (`requests,avg_input_tokens,avg_output_tokens`).
3. With Pandas, compute `cost = (in_tokens*input_per_m + out_tokens*output_per_m) / 1e6`
   per row, then rank and print with Click's table renderer.
4. Optional `--retries` and `--cached-pct` flags model retry inflation and prompt caching,
   the two levers that actually move the bill.

```python
import click, pandas as pd
df = pd.read_csv(rates)
df["cost_usd"] = (req * df["avg_input_tokens"] * df["input_per_m"]
                  + req * df["avg_output_tokens"] * df["output_per_m"]) / 1e6
click.echo(df.sort_values("cost_usd")[["model", "cost_usd"]].to_string(index=False))
```

Ship the rates file with the one figure the video actually gives (Argon output = $10 / 1M)
and leave other rows blank with a `source` column so students must find and cite their own.

## WHEN TO USE IN PRODUCTION
Use it before every model migration, to size a pilot budget, or as a CI gate that fails a
PR adding a workload whose projected monthly cost blows the cap. Do NOT use it for latency
or quality decisions — cost is one axis and the cheapest model is often not fit for the
task. Skip the CLI when you already have provider-side billing dashboards for a single
model; it earns its keep only for cross-model comparison.

## HOW IT HELPS STUDENTS
Teaches token economics, Pandas aggregation, Click argument design, and honest sourcing of
price data. They leave with a habit: quote a rate, model the workload, cite the source.

## STARTER CODE
See `starter/main.py` — `audit` command, sample rates and workload, deterministic output,
with `# TODO` markers for live pricing fetches.
