# Local AI Box Price-per-Gigabyte Analyzer CLI

## PURPOSE
A Click + Pandas command-line tool that ingests a CSV of local AI machines and compares
them the way the video does: price per gigabyte of memory, memory-bandwidth per dollar,
and the generation-speed ceiling implied by the pipe math. It ships with the machines the
transcript names — the AMD 495 "Gorgon Halo" at $7,299 with 192 GB, the AMD 395 at
$3,999.99 with 128 GB, Nvidia DGX Spark at $6,950, the Mac Studio M5 Ultra, the GMK Tech
Evo X2, and the four-box Framework llama.cpp cluster.

## WHY THIS MATTERS
The video's punchline is that "the price is memory." DRAM contract prices near $10/GB
with a forecast ~80% jump put 192 GB of chips near $3,450 — almost half the box — before
the processor or case. Going from 128 to 192 GB costs $3,300, about $52 per extra
gigabyte, versus roughly $25/GB for Apple. This CLI makes that capacity economics
computable and reproducible instead of a throwaway slide.

## HOW TO BUILD
Load the catalog with Pandas, derive columns, then expose subcommands with Click:

```python
df["price_per_gb"] = df["price_usd"] / df["total_gb"]
df["gbps_per_dollar"] = df["bandwidth_gbps"] / df["price_usd"]
df["gen_ceiling_tps_142gb"] = df["bandwidth_gbps"] / 142  # Qwen 3 235B class
```

Commands: `list` (table), `compare --model-size 142` (which machines fit and at what
ceiling), `per-gb` (rank by $/GB), and `export --format csv`. Use `click.option` for
filters and rich-style tabulate-free formatting via `df.to_string`.

## WHEN TO USE IN PRODUCTION
Use it when a procurement or infra team must justify a purchase: it turns a spec sheet
into a ranked table with explicit assumptions. Use it to track the weekly price jumps the
video warns about by re-running on a fresh CSV. Do NOT use it for latency planning — the
ceiling ignores prefill, KV-cache, and network hops (the four-box cluster is bandwidth-
limited over the interconnect). Do NOT treat list prices as final; retailer markup is real.

## HOW IT HELPS STUDENTS
Students practice Pandas data wrangling (derived columns, groupby, sorting), Click CLI
design (options, subcommands, exit codes), and the habit of separating measured from
derived numbers. They learn to make a data-driven buy/skip call with an auditable CSV.

## STARTER CODE
See `starter/main.py` for a Click app with a bundled in-memory catalog (and CSV loader),
four subcommands, and `# TODO` markers for live price feeds and per-model fit columns.
