`README.md`

87 lines
# ⚔️ MODEL WARS

**Leading AI models battle head-to-head in a medieval tournament.** A 2026
liquid-glass interface turns model comparisons into jousts, sieges, duels,
archery and dragon-slaying — backed by **real API battles**, **AI judges**, and a
**persistent medieval ELO ladder**.

Each model is a champion:

| Champion | Model | Title |
|---|---|---|
| ⚔️ GPT | OpenAI | The Emerald Knight |
| 📜 Claude | Anthropic | The Golden Scholar |
| ✦ Gemini | Google | The Celestial Mage |
| 🗡️ Grok | xAI | The Black Knight |
| ☯ DeepSeek | DeepSeek | The Eastern Strategist |
| 🏹 Llama | Groq | The Crimson Ranger |

New champions can be summoned dynamically from **The King's Table**.

## The tournament

Pick two champions and a battle. The **identical prompt** is sent to both models
simultaneously; the animation is driven by how they actually score.

- **⚔️ Joust** — full-spectrum clash; every category feeds the strike.
- **🏹 Archery** — precision questions; accuracy places the arrow near the gold.
- **🏰 Castle Siege** — multi-step reasoning topples gate → walls → towers → keep.
- **🗡️ Duel** — coding / math / logic; correct reasoning strikes, errors are blocked.
- **🐉 Dragon Challenge** — one brutal problem; both race to slay the same beast.

## Honesty first — never faked

- The **Live Arena** sends the real prompt to real APIs and shows the **measured**
  time-to-first-token, total generation time, token usage, and estimated cost.
- **AI-judge** scores (correctness, reasoning, relevance, completeness,
  instruction adherence, hallucination risk — 0–100 each) are clearly labeled as
  **opinions**, kept visually distinct from the **measured** objective metrics.
- **People's Choice** (human votes) is tallied **separately** from the AI Score.
- If a champion has **no API key**, it is not faked. It stays selectable in
  **Exhibition mode** — a clearly-labeled *simulation* that never masquerades as a
  real model response and **never moves the persistent King's Table**. Only real,
  measured battles change the ladder.
- **View The Evidence** exposes the full raw model outputs and the scoring.

## The Medieval ELO system

Every champion carries a persistent rating (standard ELO, K=32). Wins and losses
move it. **The King's Table** shows rank, model, provider, ELO, W/L/D, win %,
current streak, strongest category, average response time and cost efficiency —
with a subtly animated crown on the #1 champion.

## Run it

```bash
npm install
cp .env.example .env      # add whatever API keys you have (any subset works)
npm start                 # → http://localhost:9911
```

With **zero keys** it runs in Exhibition mode so you can explore every battle,
animation and the ladder. Add **two or more** keys to fight live, judged battles
that count on the King's Table.

### Environment

Each provider reads `PROVIDER_API_KEY` (+ optional `PROVIDER_MODEL`) from `.env` —
see `.env.example`. `JUDGE_PROVIDER` picks which model judges (defaults to the
first available). Battles stream, so time-to-first-token is genuinely measured.

## Architecture

```
server.js      Express: static host + /api/battle, /api/judge, /api/result,
               /api/leaderboard, /api/champions. Persists the ELO ladder.
providers.js   Streaming adapters for OpenAI/Anthropic/Google/xAI/DeepSeek/Groq,
               token+cost accounting, and the AI-judge call. Never fabricates.
public/        The 2026 liquid-glass UI:
  index.html   structure
  styles.css   glass panels, gold/silver trim, medieval + modern type
  scene.js     embers, cursor torchlight, parallax castle
  battles.js   the five canvas bouts (knights, arrows, castles, swords, dragon)
  app.js       orchestration, scoring, judging, ladder, voting
```

Built from — and a full rebuild of — a Model Arena challenge starter.