# Code Arena Elo Battle Simulator

## PURPOSE
A discrete-event simulation of the "code arena" the video keeps returning to. The transcript names concrete ranks (17th for the non-full Muse Wonder, 6th for the full max-reasoning version) but never explains how a leaderboard is earned. This project reconstructs that mechanism: prompts queue up, two models are drawn as a pair, a simulated judge picks a winner weighted by an intrinsic skill parameter, and an Elo rating plus rank is emitted over time. SimPy drives the matchmaking queue; NumPy supplies the probabilistic judging and rating math.

## WHY THIS MATTERS
It teaches that a rank is a noisy estimate, not a property. The reviewer notes the non-full model "didn't do that well" and later says rankings are "hard to be very precise" about — Elo convergence, match counts and variance explain exactly why sibling variants can appear a generation apart even when the underlying skill gap is modest.

## HOW TO BUILD
1. Model prompts as arrivals on a SimPy `Environment`.
2. Keep a battle `Store`; worker processes pull pairs and score them.
3. Judge with a logistic win probability derived from skill: `P(a) = 1 / (1 + 10 ** ((r_b - r_a) / 400))`.
4. Update ratings with the standard Elo delta `K * (outcome - expected)`.
5. Sort by rating to recover a leaderboard and compare against the transcript ranks.

```python
def battle(env, arena, battles, ratings, skill, k=16):
    while True:
        a, b = yield battles.get()
        expected = 1 / (1 + 10 ** ((ratings[b] - ratings[a]) / 400))
        outcome = 1.0 if rng.random() < judge_prob(skill[a], skill[b]) else 0.0
        ratings[a] += k * (outcome - expected)
        ratings[b] += k * ((1 - outcome) - (1 - expected))
        yield env.timeout(1)
```

## WHEN TO USE IN PRODUCTION
Use it to design and stress-test ranking systems: how many battles are needed before rank stabilises, how much K-factor noise looks like a real regression, and how a new variant should be seeded. Do NOT use it as a substitute for real evaluation — the whole point of the video is that only hands-on testing on the arena settles the question.

## HOW IT HELPS STUDENTS
Students learn SimPy process/resource modelling, NumPy vectorisation, probabilistic judging, and the Elo/Bradley-Terry idea that powers every leaderboard. It bridges "I saw a rank" to "I understand the generator behind the rank".

## STARTER CODE
`starter/main.py` runs a fixed-seed simulation with two Meta variants (non-full skill vs full skill) and prints the converged leaderboard. TODO markers show where to add more models and a Bradley-Terry MLE fit.
