# Code Arena Rank Tracker CLI

## PURPOSE
A Click + Pandas command-line tool that ingests arena leaderboard exports and answers the one question the video keeps circling: where does a model actually sit, and how far did it move? In the transcript the non-full Muse Wonder ranked 17th on the code arena (just below Muse Spark 3 1.3), while the full max-reasoning version climbed to 6th. This CLI treats each of those snapshots as a row, tracks rank deltas, and lets you compare variants, reasoning levels and vendors from the terminal.

## WHY THIS MATTERS
The reviewer's whole argument depends on numbers changing: an "original release" that "didn't do that well" versus a full version that is "so much better". Reproducing that requires structured leaderboard data, not screenshots. Rank deltas, not absolute rank, are what surface a release mistake — the CLI makes that delta a first-class output.

## HOW TO BUILD
1. Define a Click group with `ingest`, `rank`, `delta` and `compare` subcommands.
2. Load CSVs into Pandas with an explicit schema: `model, vendor, reasoning_level, rank, arena, captured_at`.
3. `delta` sorts by `captured_at`, groups by `model`, and computes `rank.shift()` differences.
4. Render with `to_string` for clean terminal output; keep a `--json` flag for piping.

```python
@cli.command()
@click.option("--arena", default="code", help="code | vision | 3d")
@click.argument("csv_path", type=click.Path(exists=True))
def delta(arena: str, csv_path: str) -> None:
    df = load_leaderboard(csv_path)
    df = df[df["arena"] == arena].sort_values("captured_at")
    df["rank_change"] = df.groupby("model")["rank"].diff()
    click.echo(df.tail(20).to_string(index=False))
```

## WHEN TO USE IN PRODUCTION
Use it in model-evaluation pipelines to diff leaderboards nightly, flag regressions after a provider update, or feed a release decision. Avoid it for real-time scoring (it is a batch/export tool) and for judging anything a benchmark does not cover — the video is explicit that "these are not the end of the testing experience".

## HOW IT HELPS STUDENTS
Students practise Click command design, typed Pandas schemas, groupby diffs and time-series handling. It is a small tool that mirrors the analysis every ML platform team does, and it teaches the difference between a raw benchmark number and the trend a person should act on.

## STARTER CODE
`starter/main.py` ships the full Click group with sample rows matching the transcript (rank 17 then rank 6) and TODO markers for a live arena fetch.
