inital build

.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+SPEC.md
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+backend/.env
+.env
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

QUICKSTART.md

@@ -0,0 +1,280 @@
+# RUSH AGENTS - Quick Start Guide
+
+## 📋 Overview
+
+**RUSH AGENTS** is an AI model battle arena where models compete for survival by escaping lava and forming strategic alliances.
+
+- **Intelligence Test**: See which AI model survives the longest
+- **Alliance System**: Models can propose partnerships (but proposing signals weakness)
+- **Rules-Based**: No personalities—all models play by identical rules
+- **Groq API**: Fast, parallel decision-making for all models
+- **Real-time**: WebSocket streaming, 3-second ticks
+
+---
+
+## 🚀 Quick Start (Local Development)
+
+### Prerequisites
+✅ Already installed:
+- Python 3.10+
+- Node.js 18+
+- Groq API Key (in `backend/.env`)
+
+### Start Backend
+
+```bash
+cd backend
+
+# Verify .env has GROQ_API_KEY
+cat .env
+
+# Run the server
+python -m uvicorn app.main:app --reload
+```
+
+Server runs on: **http://localhost:8000**
+
+### Start Frontend (New Terminal)
+
+```bash
+cd frontend
+
+# Run dev server
+npm run dev
+```
+
+Frontend runs on: **http://localhost:3000**
+
+### Play
+
+1. Open http://localhost:3000
+2. Wait for "Ready for chaos"
+3. Select 2-6 models from the dropdown
+4. Click "Start Simulation"
+5. Click map to place volcano
+6. Watch the battle unfold!
+
+---
+
+## 📚 What's Available
+
+### Models
+**Groq Models (Free Tier)**:
+- `llama-3.1-8b-instant` — 8B fast
+- `llama-3.1-70b-versatile` — 70B smart
+- `mixtral-8x7b-32768` — 8x7B expert
+- `gemma-7b-it` — 7B instruction-tuned
+
+**HuggingFace Spaces** (Can add more):
+- Falcon-7B
+- Llama-2-7B
+- Mistral-7B
+- Zephyr-7B
+- OpenHermes-7B
+
+---
+
+## 🎮 Game Rules
+
+### Each Model Sees:
+- All other models' positions (x, y)
+- Volcano position & radius
+- Map bounds (1200x800)
+- Distance to lava edge
+- Alliance status (who's allied with whom)
+
+### Each Tick (3 seconds):
+
+**1. Groq Decision Call** (Parallel for all models)
+   - "run" → Sprint away from lava
+   - "propose_alliance" → Ask another model to team up
+
+**2. Alliance Processing**
+   - If A proposes to B, B gets asked immediately
+   - If B accepts → Both merge at same position
+   - If B rejects → A keeps running, B keeps running
+
+**3. Movement**
+   - Models move based on decisions
+   - Position clamped to map bounds
+
+**4. Lava Expands**
+   - Radius grows by 120 pixels
+
+**5. Deaths**
+   - Models in lava radius die
+   - EXCEPT if they're stacked with an alive ally
+
+**6. Win Check**
+   - ≤1 model alive → Game Over
+
+### Strategic Cost of Alliances
+- **Proposing** = signaling weakness
+- **First to propose** = lose strategic leverage
+- **Benefit** = survival through numbers
+
+---
+
+## 🔑 Environment Variables
+
+### Backend (.env)
+```
+GROQ_API_KEY=<your key here>           # REQUIRED
+HUGGINGFACE_API_TOKEN=                 # Optional
+ALLOWED_ORIGINS=http://localhost:3000
+ENV=development
+```
+
+### Frontend (.env.local)
+```
+NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
+```
+
+---
+
+## 📡 API Endpoints
+
+```
+GET  /wake                    → Health check + status
+GET  /available-models        → List of all available models
+POST /start-simulation         → Create new simulation
+POST /place-volcano            → Place volcano, start ticking
+GET  /ws/{simulation_id}       → WebSocket stream
+```
+
+---
+
+## 🧠 How Groq Decision-Making Works
+
+### Per Model, Per Tick:
+1. **Build state summary**
+   - Current standings (distance from lava)
+   - All agents' positions
+   - Volcano position & radius
+
+2. **Send to Groq Llama 3.1 8B**
+   ```json
+   {
+     "system": "You are [ModelName]. Make a strategic decision...",
+     "user": "[Game state]"
+   }
+   ```
+
+3. **Get response**
+   ```json
+   {
+     "action": "run|propose_alliance",
+     "alliance_target": "ModelName or null",
+     "reasoning": "..."
+   }
+   ```
+
+4. **Execute action**
+
+All models queried in parallel (async) = fast ticks
+
+---
+
+## 🎨 Frontend Features
+
+### Map Canvas
+- **White circles** = Individual models
+- **Yellow glowing circles** = Stacked alliances (2+ models)
+- **Orange/red glow** = Lava expanding
+- **Gray skull** = Dead models
+- **Yellow 🤝** = Alliance indicator on label
+
+### Sidebar
+- **Model Selector** = Pick 2-6 models (groups by Groq/HF)
+- **Chat Feed** = Events (alliances, deaths, decisions)
+- **Status** = Current round, agents alive
+
+---
+
+## 🔧 Troubleshooting
+
+### "Failed to fetch models"
+- Check backend is running: `python -m uvicorn app.main:app --reload`
+- Check port 8000 is available
+
+### "Groq API error"
+- Verify `GROQ_API_KEY` in `backend/.env`
+- Check Groq dashboard: https://console.groq.com
+
+### WebSocket connection fails
+- Frontend tries `ws://localhost:8000` (port 8000)
+- Make sure backend is running
+
+### No models showing up
+- Check `/available-models` returns data: `curl http://localhost:8000/available-models`
+
+---
+
+## 📝 Key Files
+
+```
+backend/
+  app/
+    main.py            → FastAPI server
+    simulation.py      → Game engine logic
+    models.py          → Pydantic schemas
+    groq_client.py     → Groq API integration
+    hf_spaces.py       → HF model discovery
+    movement.py        → Physics/movement
+  .env                 → API keys (REQUIRED)
+  requirements.txt     → Python dependencies
+
+frontend/
+  app/
+    page.tsx           → Main app component
+  components/
+    MapCanvas.tsx      → 2D map rendering
+    ModelSelector.tsx  → Model selection UI
+    ChatFeed.tsx       → Event stream display
+  lib/
+    api.ts             → Backend API calls
+```
+
+---
+
+## 🚢 Deployment
+
+### Backend (Railway, Heroku, etc.)
+```bash
+# Set env vars
+GROQ_API_KEY=...
+ALLOWED_ORIGINS=https://yourdomain.com
+
+# Deploy
+gunicorn -w 4 -k uvicorn.workers.UvicornWorker app.main:app
+```
+
+### Frontend (Vercel, Netlify)
+```bash
+npm run build
+# Deploy the .next folder
+```
+
+---
+
+## 📖 Learn More
+
+- Groq API docs: https://console.groq.com/docs
+- FastAPI: https://fastapi.tiangolo.com/
+- Next.js: https://nextjs.org/docs
+- WebSocket: https://mdn.io/WebSocket
+
+---
+
+## 💡 Ideas for Experimentation
+
+1. **Add new models** — Edit `hf_spaces.py` KNOWN_SPACES_MODELS
+2. **Change game rules** — Edit `simulation.py` tick logic
+3. **New scenarios** — Add earthquake, meteor, etc. in `simulation.py`
+4. **Leaderboard** — Track best survival times across sessions
+5. **Replay system** — Save/load simulation events
+6. **Model attack mechanic** — Add "push" action to shove others toward lava
+
+---
+
+**Ready to battle?** Open http://localhost:3000! 🌋

README.md

@@ -0,0 +1,103 @@
+# RUSH AGENTS RUSH
+
+> *Different models. One fire. Real teamwork or chaos.*
+
+Rush Agents Rush is a 2D multi-agent simulation where real AI models are dropped onto a map, a fire is placed, and the models must cooperate to survive and extinguish it. They vote for a leader, search for water, move as a coalition, and try to put the fire out before it consumes the map.
+
+The current design has fully moved on from the old volcano/lava loop. The game is now about fire suppression, coalition strategy, and visible agent coordination.
+
+## Core Idea
+
+1. Pick 2-6 models from Groq or supported Hugging Face sources.
+2. Start a simulation and click the map to place the fire.
+3. Agents decide each tick whether to search water, collect water, extinguish fire, escape, or vote for a leader.
+4. Fire grows over time, but water collection and extinguishing reduce intensity.
+5. The game ends when the fire is fully extinguished or the agents are wiped out.
+
+## Features
+
+- Real model names and visible per-agent positions on the map
+- Coalition voting and leader election
+- Water wells placed around the fire arena
+- Fire growth and deterministic extinguishing logic
+- WebSocket-driven live simulation updates
+- Chat feed with varied team-style messages
+- End-of-game winner text showing the strongest extinguisher
+
+## Tech Stack
+
+| Layer | Tech |
+| --- | --- |
+| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS v4 |
+| Backend | FastAPI, Python, Uvicorn |
+| AI | Groq models, optional Hugging Face-backed model discovery |
+| Realtime | WebSockets |
+
+## Repository Layout
+
+- [backend](backend): FastAPI API, simulation engine, model state, WebSocket streaming
+- [frontend](frontend): Next.js UI, map rendering, chat feed, model selection
+
+## Local Setup
+
+### Backend
+
+```bash
+cd backend
+pip install -r requirements.txt
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:3000.
+
+## Environment Variables
+
+### Backend
+
+```env
+GROQ_API_KEY=your_groq_key
+ALLOWED_ORIGINS=http://localhost:3000
+```
+
+### Frontend
+
+```env
+NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
+```
+
+## API Overview
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | /wake | Health and readiness check |
+| GET | /available-models | List available models for the UI |
+| POST | /start-simulation | Create a new simulation |
+| POST | /place-fire | Place the fire and generate water wells |
+| WS | /ws/{simulation_id} | Stream simulation ticks and events |
+
+## Simulation Loop
+
+Each tick the backend:
+
+1. Collects decisions from all living agents in parallel.
+2. Runs coalition voting if a leader has not been chosen.
+3. Moves agents toward water or the fire edge based on their current action.
+4. Grows the fire slightly.
+5. Applies deterministic extinguish damage based on how many agents are actually in position.
+6. Removes agents caught inside the fire radius.
+7. Ends the game when the fire is out or only one agent remains.
+
+## Notes
+
+- State is kept in memory, so simulations reset when the backend restarts.
+- The UI is designed around visible cooperation, not just survival.
+- Old lava/volcano docs are intentionally replaced by the fire/water scenario.
+

backend/.env.example

@@ -0,0 +1,14 @@
+# Backend API Configuration
+GROQ_API_KEY=your_groq_api_key_here
+
+# Optional: HuggingFace API token for accessing HF Spaces models
+HUGGINGFACE_API_TOKEN=your_huggingface_token_here
+
+# CORS allowed origins (comma-separated)
+ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
+
+# Optional: Backend port
+BACKEND_PORT=8000
+
+# Optional: Environment
+ENV=development

backend/.python-version

@@ -0,0 +1 @@
+3.14

backend/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY app/ ./app/
+EXPOSE 7860
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

backend/README.md

@@ -0,0 +1,46 @@
+---
+title: RUSH AGENTS RUSH Backend
+emoji: 🔥
+colorFrom: orange
+colorTo: red
+sdk: docker
+pinned: false
+---
+
+# Rush Agents Rush Backend
+
+FastAPI server driving the fire-suppression simulation.
+
+## What It Does
+
+- Accepts model selections and starts a new simulation.
+- Places a fire on the map and generates water wells.
+- Runs the tick-based AI loop with coalition voting, movement, and extinguishing.
+- Streams state updates and events over WebSockets.
+
+## Key Endpoints
+
+- `GET /wake` - health and readiness check
+- `GET /available-models` - list available models for the UI
+- `POST /start-simulation` - create a new simulation
+- `POST /place-fire` - place the fire and spawn water sources
+- `WS /ws/{simulation_id}` - stream live simulation ticks
+
+## Environment Variables
+
+- `GROQ_API_KEY`: Required for agent decisions.
+- `ALLOWED_ORIGINS`: CORS whitelist.
+
+## Local Run
+
+```bash
+cd backend
+pip install -r requirements.txt
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+## Notes
+
+- Simulation state is in memory.
+- Fire growth, extinguish rate, and movement are tuned in `app/simulation.py`.
+- Model decisions are generated in `app/groq_client.py`.

backend/app/groq_client.py

@@ -0,0 +1,151 @@
+import json
+import os
+import random
+import math
+from groq import AsyncGroq
+from dotenv import load_dotenv
+
+load_dotenv()
+
+_GROQ_API_KEY = os.environ.get("GROQ_API_KEY")
+_client = AsyncGroq(api_key=_GROQ_API_KEY) if _GROQ_API_KEY else None
+
+DEFAULT_DECISION_MODEL = "llama-3.1-8b-instant"
+MAX_AGENT_SPEED = 80
+
+
+def is_ready():
+    return _client is not None
+
+
+def _build_fire_state_summary(agent, fire, all_agents) -> str:
+    """Build a state summary for the fire scenario."""
+    standings = []
+    for a in all_agents:
+        if not a.alive:
+            continue
+        dist = math.dist((a.x, a.y), (fire.x, fire.y))
+        standings.append({
+            "name": a.display_name,
+            "model": a.model_name,
+            "distance_from_fire": dist,
+            "x": a.x,
+            "y": a.y,
+            "has_water": a.water_collected,
+            "mode": a.mode,
+        })
+
+    standings.sort(key=lambda s: s['distance_from_fire'])
+    
+    lines = ["Current standings:"]
+    for rank, s in enumerate(standings, 1):
+        water_str = " (carrying water)" if s['has_water'] else ""
+        lines.append(f"  #{rank} {s['name']}: {s['distance_from_fire']:.0f}px from fire{water_str}")
+    
+    return "\n".join(lines)
+
+
+async def generate_fire_decision(agent, fire, water_sources, other_agents, bounds) -> dict:
+    """
+    Fire scenario decision system.
+    Actions: search_water, collect_water, extinguish_fire, escape, vote_for_leader
+    """
+    if not _client:
+        return _fallback_escape(agent, fire)
+
+    dist_to_fire = math.dist((agent.x, agent.y), (fire.x, fire.y))
+    nearest_water = min(water_sources, key=lambda w: math.dist((agent.x, agent.y), (w.x, w.y))) if water_sources else None
+    dist_to_water = math.dist((agent.x, agent.y), (nearest_water.x, nearest_water.y)) if nearest_water else None
+    
+    living_agents = [a for a in other_agents if a.alive and a.model_name != agent.model_name]
+    state_summary = _build_fire_state_summary(agent, fire, [agent] + living_agents)
+
+    coalition_leader = next((a.model_name for a in other_agents if a.is_leader), None)
+    dist_to_water_display = f"{dist_to_water:.0f}px" if dist_to_water is not None else "unknown"
+    system_prompt = f"""You are {agent.model_name}, an AI model in a critical wildfire survival scenario.
+
+THE SCENARIO:
+- A wildfire is spreading rapidly across the map
+- Water sources (wells) are scattered around the area
+- You can work alone or join a coalition with other AI models
+- Coalition agents should elect a leader who coordinates the strategy
+- If a leader exists, follow their plan: gather water, then move to the fire edge to extinguish
+- To win: Find water → Collect it → Return to fire → Extinguish it together (or solo)
+- If the fire consumes you, you lose
+
+YOUR STRATEGIC OPTIONS EACH TICK:
+1. "search_water" - Move toward the nearest water source
+2. "collect_water" - Pick up water from a well (must be at a source)
+3. "extinguish_fire" - Use collected water to fight the fire (must have water)
+4. "escape" - Run away from the fire to survive
+5. "vote_for_leader" - Vote for yourself or another model as coalition leader
+
+IMPORTANT CONSIDERATIONS:
+- If fire is very close (< 200px), prioritize escape or finding water
+- If you have water, move to the fire edge and extinguish
+- If you are near a water source (< 60px), collect it immediately
+- Coalition mode requires coordination; vote strategically
+- Solo mode means you act independently and don't wait for others
+
+OUTPUT FORMAT - return ONLY valid JSON:
+{{"action": "<search_water|collect_water|extinguish_fire|escape|vote_for_leader>", "vote_for": "<model_name if voting, else null>", "message": "<full English sentence>", "reasoning": "<one sentence>"}}
+
+CURRENT STATE:
+Your position: ({agent.x}, {agent.y})
+Fire position: ({fire.x}, {fire.y})
+Distance from fire: {dist_to_fire:.0f}px
+Fire radius: {fire.radius:.0f}px
+Fire intensity: {fire.intensity:.0f}%
+Carrying water: {agent.water_collected}
+Mode: {agent.mode} ({'joined a coalition' if agent.mode == 'coalition' else 'acting alone'})
+Nearest water distance: {dist_to_water_display}
+Coalition leader: {coalition_leader or 'none'}
+
+{state_summary}
+
+What do you do?"""
+
+    try:
+        completion = await _client.chat.completions.create(
+            model=DEFAULT_DECISION_MODEL,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": "Make your decision."}
+            ],
+            response_format={"type": "json_object"},
+            max_tokens=150,
+            timeout=3.0
+        )
+        decision = json.loads(completion.choices[0].message.content)
+        
+        action = decision.get("action", "escape")
+        if action not in ["search_water", "collect_water", "extinguish_fire", "escape", "vote_for_leader"]:
+            action = "escape"
+
+        if dist_to_water is not None and dist_to_water <= 60 and not agent.water_collected:
+            action = "collect_water"
+        elif agent.water_collected and dist_to_fire <= 350:
+            action = "extinguish_fire"
+        
+        return {
+            "action": action,
+            "vote_for": decision.get("vote_for"),
+            "message": decision.get("message", "Moving strategically."),
+            "reasoning": decision.get("reasoning", "Survival and teamwork.")
+        }
+    except Exception as e:
+        print(f"Error calling groq for {agent.model_name}: {e}")
+        return _fallback_escape(agent, fire)
+
+
+def _fallback_escape(agent, fire) -> dict:
+    """Fallback escape behavior."""
+    dx = agent.x - fire.x
+    dy = agent.y - fire.y
+    dist = math.sqrt(dx**2 + dy**2) or 1
+    return {
+        "message": "Running to safety!",
+        "action": "escape",
+        "vote_for": None,
+        "reasoning": "Fallback: survive."
+    }

backend/app/hf_spaces.py

@@ -0,0 +1,108 @@
+"""
+HuggingFace Spaces integration for discovering and querying open-source models.
+"""
+import os
+import httpx
+from typing import Optional
+
+HF_API_TOKEN = os.environ.get("HUGGINGFACE_API_TOKEN", "")
+
+# Curated list of verified open-source models on HF Spaces that work reliably
+KNOWN_SPACES_MODELS = [
+    {
+        "id": "tiiuae/Falcon-7B",
+        "name": "Falcon-7B",
+        "space_url": "https://huggingface.co/spaces/tiiuae/falcon-chat",
+        "description": "7B parameter open model",
+    },
+    {
+        "id": "meta-llama/Llama-2-7b",
+        "name": "Llama-2-7B",
+        "space_url": "https://huggingface.co/spaces/meta-llama/Llama-2-7b-chat",
+        "description": "Meta's 7B model",
+    },
+    {
+        "id": "mistralai/Mistral-7B",
+        "name": "Mistral-7B",
+        "space_url": "https://huggingface.co/spaces/mistralai/Mistral-7B-Instruct-v0.1",
+        "description": "Mistral's 7B model",
+    },
+    {
+        "id": "HuggingFaceH4/zephyr-7b",
+        "name": "Zephyr-7B",
+        "space_url": "https://huggingface.co/spaces/HuggingFaceH4/zephyr-7b-beta",
+        "description": "Zephyr 7B fine-tuned model",
+    },
+    {
+        "id": "teknium/OpenHermes-2.5-Mistral-7B",
+        "name": "OpenHermes-7B",
+        "space_url": "https://huggingface.co/spaces/teknium/OpenHermes-2.5-Mistral-7B",
+        "description": "OpenHermes instruction-tuned 7B",
+    },
+]
+
+# Groq models (built-in)
+GROQ_MODELS = [
+    {"id": "llama-3.1-8b-instant", "name": "Llama 3.1 8B", "backend": "groq"},
+    {"id": "llama-3.1-70b-versatile", "name": "Llama 3.1 70B", "backend": "groq"},
+    {"id": "mixtral-8x7b-32768", "name": "Mixtral 8x7B", "backend": "groq"},
+    {"id": "gemma-7b-it", "name": "Gemma 7B", "backend": "groq"},
+]
+
+
+async def get_available_models() -> dict:
+    """
+    Get list of available models from Groq and HF Spaces.
+    Returns both for frontend model selector.
+    """
+    return {
+        "groq_models": GROQ_MODELS,
+        "hf_spaces_models": KNOWN_SPACES_MODELS,
+        "total": len(GROQ_MODELS) + len(KNOWN_SPACES_MODELS),
+    }
+
+
+async def query_hf_space_model(model_id: str, prompt: str) -> Optional[str]:
+    """
+    Query a model on HuggingFace Spaces.
+    This is a fallback if we want to use HF spaces directly.
+    Note: HF spaces may have rate limits and require authentication.
+    """
+    if not HF_API_TOKEN:
+        return None
+
+    # Try to find the space URL for this model
+    space = next((m for m in KNOWN_SPACES_MODELS if m["id"] == model_id), None)
+    if not space:
+        return None
+
+    try:
+        # This would hit the HF inference API
+        # For now, we focus on Groq which is more reliable
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            headers = {"Authorization": f"Bearer {HF_API_TOKEN}"}
+            response = await client.post(
+                "https://api-inference.huggingface.co/models/" + model_id,
+                json={"inputs": prompt},
+                headers=headers,
+            )
+            if response.status_code == 200:
+                result = response.json()
+                # Extract generated text from response
+                if isinstance(result, list) and len(result) > 0:
+                    return result[0].get("generated_text", "")
+    except Exception as e:
+        print(f"Error querying HF space {model_id}: {e}")
+
+    return None
+
+
+def get_model_display_name(model_id: str) -> str:
+    """Get a clean display name from model ID."""
+    # Try to find in known models
+    for model in GROQ_MODELS + KNOWN_SPACES_MODELS:
+        if model["id"] == model_id:
+            return model["name"]
+
+    # Fallback: clean up the ID
+    return model_id.split("/")[-1].split("-")[0].capitalize()

backend/app/main.py

@@ -0,0 +1,181 @@
+import asyncio
+import json
+import math
+import random
+import uuid
+import os
+import time
+from typing import Optional
+from fastapi import FastAPI, HTTPException, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from .models import SimulationState, AgentModel, TickResponse, FireScenario, WaterSource
+from .simulation import SimulationEngine, TICK_INTERVAL_SECONDS
+from . import groq_client
+from . import hf_spaces
+
+app = FastAPI(title="Unhinged 2.0", version="0.2.0")
+
+ALLOWED_ORIGINS = os.environ.get(
+    "ALLOWED_ORIGINS",
+    "http://localhost:3000"
+).split(",")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+active_simulations: dict[str, SimulationState] = {}
+START_TIME = time.time()
+
+class StartSimulationRequest(BaseModel):
+    model_names: list[str] = Field(..., min_length=2, max_length=6)
+    scenario: str = "fire"
+    map_width: int = 1200
+    map_height: int = 800
+
+class StartSimulationResponse(BaseModel):
+    simulation_id: str
+    state: SimulationState
+
+class PlaceFireRequest(BaseModel):
+    simulation_id: str
+    x: int
+    y: int
+
+class TickRequest(BaseModel):
+    simulation_id: str
+
+@app.get("/wake")
+async def wake():
+    return {
+        "warm": True,
+        "groq_available": groq_client.is_ready(),
+        "uptime_seconds": int(time.time() - START_TIME),
+    }
+
+@app.get("/available-models")
+async def get_available_models():
+    """Get list of available models (Groq + HF Spaces) for the UI."""
+    return await hf_spaces.get_available_models()
+
+@app.post("/start-simulation", response_model=StartSimulationResponse)
+async def start_simulation(req: StartSimulationRequest):
+    if req.scenario != "fire":
+        raise HTTPException(status_code=400, detail="Only 'fire' scenario supported.")
+
+    agents = _spawn_agents(req.model_names, req.map_width, req.map_height)
+
+    state = SimulationState(
+        simulation_id=str(uuid.uuid4()),
+        scenario=req.scenario,
+        map_width=req.map_width,
+        map_height=req.map_height,
+        agents=agents,
+        fire=None,
+        water_sources=[],
+        round=0,
+        status="waiting_for_scenario",
+    )
+
+    active_simulations[state.simulation_id] = state
+    return StartSimulationResponse(simulation_id=state.simulation_id, state=state)
+
+@app.post("/place-fire", response_model=SimulationState)
+def place_fire(req: PlaceFireRequest):
+    sim = _get_or_404(req.simulation_id)
+    if sim.status != "waiting_for_scenario":
+        raise HTTPException(status_code=409, detail="Fire already placed or simulation finished.")
+
+    # Create fire at clicked location
+    sim.fire = FireScenario(x=req.x, y=req.y)
+
+    # Generate 3-5 water sources scattered around the map
+    num_sources = random.randint(3, 5)
+    for i in range(num_sources):
+        water_x = random.randint(100, req.x - 200) if req.x > 200 else random.randint(0, 400)
+        if random.random() > 0.5:
+            water_x = random.randint(req.x + 200, sim.map_width - 100) if req.x < sim.map_width - 200 else random.randint(sim.map_width - 400, sim.map_width)
+        water_y = random.randint(100, sim.map_height - 100)
+        sim.water_sources.append(WaterSource(id=f"water_{i}", x=water_x, y=water_y))
+
+    sim.status = "running"
+    return sim
+
+@app.websocket("/ws/{simulation_id}")
+async def simulation_ws(websocket: WebSocket, simulation_id: str):
+    await websocket.accept()
+    sim = active_simulations.get(simulation_id)
+    if not sim:
+        await websocket.close(code=1008)
+        return
+
+    try:
+        while True:
+            if sim.status == "waiting_for_scenario":
+                await asyncio.sleep(1)
+                continue
+            
+            if sim.status == "finished":
+                await websocket.send_json({"type": "finished", "state": sim.model_dump()})
+                await websocket.close(code=1000)
+                return
+
+            engine = SimulationEngine(sim)
+            result = await engine.tick()
+            active_simulations[simulation_id] = result.state
+            
+            # DEBUG: log outgoing TickResponse summary for troubleshooting
+            try:
+                agent_states = [(a.model_name, a.alive) for a in result.state.agents]
+            except Exception:
+                agent_states = str(result.state)
+            print(f"WS_SEND sim={simulation_id} round={result.round} agents={agent_states} events={len(result.events)}")
+
+            await websocket.send_json(result.model_dump())
+            
+            if result.state.status == "finished":
+                await websocket.close(code=1000)
+                return
+                
+            await asyncio.sleep(TICK_INTERVAL_SECONDS)
+
+    except WebSocketDisconnect:
+        pass
+
+def _spawn_agents(model_names: list[str], width: int, height: int) -> list[AgentModel]:
+    min_gap = 100
+    positions = []
+    agents = []
+    for name in model_names:
+        for _ in range(100):
+            x = random.randint(100, width - 100)
+            y = random.randint(100, height - 100)
+            if all(math.dist((x, y), p) >= min_gap for p in positions):
+                positions.append((x, y))
+                break
+        else:
+            positions.append((x, y))
+
+        agents.append(AgentModel(
+            model_name=name,
+            display_name=name.split("/")[-1].split("-")[0].capitalize(),
+            x=positions[-1][0],
+            y=positions[-1][1],
+            alive=True
+        ))
+    return agents
+
+def _get_or_404(simulation_id: str) -> SimulationState:
+    sim = active_simulations.get(simulation_id)
+    if not sim:
+        raise HTTPException(status_code=404, detail="Simulation not found")
+    return sim

backend/app/models.py

@@ -0,0 +1,120 @@
+from typing import Any, Literal, Optional, Union
+from pydantic import BaseModel
+
+
+class AgentModel(BaseModel):
+    model_name: str          # full id, e.g. "llama-3.1-8b-instant"
+    display_name: str        # short label shown on map
+    x: int
+    y: int
+    alive: bool = True
+    allied_with: Optional[str] = None   # model_name of ally (if stacked)
+    has_proposed_alliance: bool = False
+    last_message: Optional[str] = None
+    distance_to_fire: Optional[float] = None
+    # New fields for fire/coalition mechanics
+    water_collected: bool = False         # carrying water
+    is_leader: bool = False               # elected coalition leader
+    coalition_members: list[str] = []     # list of allied agent model_names
+    mode: Literal["solo", "coalition"] = "coalition"  # agent's chosen path
+    status: Literal["searching", "collecting_water", "extinguishing_fire", "escaping", "idle"] = "idle"
+    vote_for: Optional[str] = None        # who this agent voted for as leader
+    extinguish_score: float = 0.0         # total fire intensity reduced by this agent
+
+
+class FireScenario(BaseModel):
+    x: int
+    y: int
+    radius: float = 50.0         # current fire radius
+    intensity: float = 100.0     # 0-100; when 0, fire is out
+    growth_rate: float = 3.0     # px per tick
+
+
+class WaterSource(BaseModel):
+    id: str                   # unique id
+    x: int
+    y: int
+    water_amount: float = 50.0  # how much water available
+
+
+class SimulationState(BaseModel):
+    simulation_id: str
+    scenario: str                       # "fire" (was "volcano")
+    map_width: int
+    map_height: int
+    agents: list[AgentModel]
+    fire: Optional[FireScenario] = None
+    water_sources: list[WaterSource] = []
+    round: int = 0
+    status: str = "waiting_for_scenario"
+    winner_model: Optional[str] = None
+    coalition_leader: Optional[str] = None  # elected leader
+    coalition_members: list[str] = []       # all coalition members
+
+
+# Event models
+class DeathEvent(BaseModel):
+    type: Literal["death"] = "death"
+    model: str
+
+class MessageEvent(BaseModel):
+    type: Literal["message"] = "message"
+    model: str
+    content: str
+
+class AllianceProposalEvent(BaseModel):
+    type: Literal["alliance_proposal"] = "alliance_proposal"
+    from_model: str
+    to_model: str
+
+class AllianceAcceptEvent(BaseModel):
+    type: Literal["alliance_accept"] = "alliance_accept"
+    model_a: str
+    model_b: str
+    stacked: bool = True
+
+class AllianceRejectEvent(BaseModel):
+    type: Literal["alliance_reject"] = "alliance_reject"
+    from_model: str
+    to_model: str
+
+class LeadershipVoteEvent(BaseModel):
+    type: Literal["leadership_vote"] = "leadership_vote"
+    voter: str
+    candidate: str
+
+class LeaderElectedEvent(BaseModel):
+    type: Literal["leader_elected"] = "leader_elected"
+    leader: str
+    coalition_members: list[str]
+
+class WaterCollectedEvent(BaseModel):
+    type: Literal["water_collected"] = "water_collected"
+    model: str
+    water_source_id: str
+
+class FireExtinguishedEvent(BaseModel):
+    type: Literal["fire_extinguished"] = "fire_extinguished"
+    extinguished_by: list[str]  # models that contributed
+    fire_intensity: float
+
+class FireSpreadEvent(BaseModel):
+    type: Literal["fire_spread"] = "fire_spread"
+    new_radius: float
+    new_intensity: float
+
+
+class ChatEntry(BaseModel):
+    agent_id: str
+    message: str
+    tick: int
+
+
+class TickResponse(BaseModel):
+    simulation_id: str
+    round: int
+    events: list[Union[DeathEvent, MessageEvent, AllianceProposalEvent, AllianceAcceptEvent, 
+                       AllianceRejectEvent, LeadershipVoteEvent, LeaderElectedEvent, 
+                       WaterCollectedEvent, FireExtinguishedEvent, FireSpreadEvent]]
+    chat: list[ChatEntry]
+    state: SimulationState

backend/app/movement.py

@@ -0,0 +1,29 @@
+import math
+
+MAX_AGENT_SPEED = 80
+
+def apply_movement(agent, dx: int, dy: int, bounds: tuple) -> tuple[int, int]:
+    # 1. Clamp dx/dy to [-MAX_AGENT_SPEED, MAX_AGENT_SPEED]
+    dx = max(-MAX_AGENT_SPEED, min(MAX_AGENT_SPEED, dx))
+    dy = max(-MAX_AGENT_SPEED, min(MAX_AGENT_SPEED, dy))
+    
+    # 2. Calculate new_x, new_y
+    new_x = agent.x + dx
+    new_y = agent.y + dy
+    
+    # 3. Clamp to canvas bounds
+    new_x = max(0, min(new_x, bounds[0]))
+    new_y = max(0, min(new_y, bounds[1]))
+    
+    # 4. Return (new_x, new_y)
+    return (int(new_x), int(new_y))
+
+def is_in_lava(agent, volcano) -> bool:
+    if not volcano:
+        return False
+    return math.dist((agent.x, agent.y), (volcano.x, volcano.y)) <= volcano.radius
+
+def distance_to_lava_edge(agent, volcano) -> float:
+    if not volcano:
+        return 1000.0
+    return math.dist((agent.x, agent.y), (volcano.x, volcano.y)) - volcano.radius

backend/app/personality.py

@@ -0,0 +1,20 @@
+import httpx
+from . import groq_client
+
+async def _fetch_model_card(model_name: str) -> str:
+    # We'll use a few specific models from Groq, so model card fetching
+    # might not always find a "README.md" on HF for these specific names
+    # if they are just the Groq IDs. But we'll try.
+    url = f"https://huggingface.co/{model_name}/raw/main/README.md"
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as http:
+            response = await http.get(url)
+            if response.status_code == 200:
+                return response.text[:2000]
+    except Exception:
+        pass
+    return f"A powerful AI model known as {model_name}."
+
+async def generate_personality(model_name: str) -> dict:
+    model_card = await _fetch_model_card(model_name)
+    return await groq_client.generate_personality(model_name, model_card)

backend/app/simulation.py

@@ -0,0 +1,324 @@
+import asyncio
+import json
+import math
+import random
+from typing import Union
+
+from .models import (
+    AgentModel,
+    DeathEvent,
+    MessageEvent,
+    LeadershipVoteEvent,
+    LeaderElectedEvent,
+    WaterCollectedEvent,
+    FireExtinguishedEvent,
+    FireSpreadEvent,
+    SimulationState,
+    TickResponse,
+    ChatEntry,
+)
+from . import groq_client
+from . import movement
+
+FIRE_GROWTH_RATE = 1.0  # radius growth per tick
+FIRE_INTENSITY_GROWTH = 0.9  # intensity per tick
+BASE_EXTINGUISH_RATE = 15.0  # baseline intensity reduction per agent
+MIN_EXTINGUISH_RATE = 8.0
+MAX_EXTINGUISH_RATE = 28.0
+TICK_INTERVAL_SECONDS = 3
+WATER_PICKUP_RANGE = 40
+EXTINGUISH_RANGE = 45
+FIRE_SAFE_BUFFER = 10
+
+class SimulationEngine:
+    def __init__(self, state: SimulationState) -> None:
+        self.state = state
+
+    def _pick_message(self, action: str) -> str:
+        options = {
+            "search_water": [
+                "Scanning for the nearest well.",
+                "Heading toward water to stock up.",
+                "Tracking a water source now.",
+                "Moving to secure water for the team.",
+            ],
+            "collect_water": [
+                "Water secured. Moving to the fire line.",
+                "Got water. Heading to the fire edge.",
+                "Collected water. Time to extinguish.",
+            ],
+            "extinguish_fire": [
+                "Pouring water at the fire edge.",
+                "Holding position and dousing flames.",
+                "Suppressing the fire with water.",
+            ],
+            "escape": [
+                "Falling back to a safer position.",
+                "Repositioning away from the flames.",
+                "Retreating to avoid the fire front.",
+            ],
+        }
+        return random.choice(options.get(action, ["Moving strategically."]))
+
+    def _move_toward(self, agent: AgentModel, target_x: float, target_y: float, stop_distance: float = 0) -> None:
+        dx = target_x - agent.x
+        dy = target_y - agent.y
+        dist = math.sqrt(dx**2 + dy**2) or 1
+        if dist <= stop_distance:
+            return
+        step = min(movement.MAX_AGENT_SPEED, dist - stop_distance)
+        agent.x += int((dx / dist) * step)
+        agent.y += int((dy / dist) * step)
+        agent.x = max(0, min(agent.x, self.state.map_width))
+        agent.y = max(0, min(agent.y, self.state.map_height))
+
+    async def tick(self) -> TickResponse:
+        """
+        Main simulation loop:
+        1. Get decisions from all living agents
+        2. Handle coalition leadership voting
+        3. Execute agent actions (search water, collect, extinguish, escape, etc.)
+        4. Grow fire
+        5. Extinguish fire if agents with water are present
+        6. Kill agents in fire (but protect coalition members)
+        7. Check win condition
+        """
+        if self.state.status != "running":
+            raise ValueError(f"Cannot tick a simulation with status '{self.state.status}'.")
+
+        fire = self.state.fire
+        assert fire is not None, "Fire must be placed before ticking."
+
+        events = []
+        bounds = (self.state.map_width, self.state.map_height)
+        living_agents = [a for a in self.state.agents if a.alive]
+
+        # 1. Get decisions from all living agents
+        decisions = await asyncio.gather(
+            *[groq_client.generate_fire_decision(agent, fire, self.state.water_sources, living_agents, bounds)
+              for agent in living_agents],
+            return_exceptions=True
+        )
+
+        decision_map = {}
+        for agent, decision in zip(living_agents, decisions):
+            if isinstance(decision, Exception):
+                decision = groq_client._fallback_escape(agent, fire)
+            decision_map[agent.model_name] = decision
+
+        # 2. Leadership voting phase (if coalition leader not elected)
+        if not self.state.coalition_leader:
+            vote_events = await self._voting_phase(living_agents, decision_map)
+            events.extend(vote_events)
+
+        # 3. Execute actions
+        action_events = await self._execute_actions(living_agents, decision_map, fire)
+        events.extend(action_events)
+
+        # 4. Grow fire
+        fire.radius += FIRE_GROWTH_RATE
+        fire.intensity += FIRE_INTENSITY_GROWTH
+        if fire.intensity > 100.0:
+            fire.intensity = 100.0
+        
+        if fire.intensity > 0:
+            events.append(FireSpreadEvent(new_radius=fire.radius, new_intensity=fire.intensity))
+
+        # 5. Extinguish fire if agents with water are present
+        extinguish_events = self._check_extinguish(living_agents, fire)
+        events.extend(extinguish_events)
+
+        # 6. Kill agents in fire
+        death_events = self._kill_agents_in_fire(living_agents, fire)
+        events.extend(death_events)
+
+        # 7. Check win condition
+        self.state.round += 1
+        living_count = len([a for a in self.state.agents if a.alive])
+        
+        if fire.intensity <= 0:
+            # Fire extinguished!
+            self.state.status = "finished"
+            top_score = max((a.extinguish_score for a in self.state.agents), default=0)
+            top_agents = [a.model_name for a in self.state.agents if a.extinguish_score == top_score and top_score > 0]
+            if top_agents:
+                self.state.winner_model = f"Top extinguisher: {', '.join(top_agents)} ({top_score:.1f} impact)"
+            else:
+                self.state.winner_model = "Fire extinguished"
+        elif living_count <= 1:
+            # Only one agent left
+            self.state.status = "finished"
+            winner = next((a.model_name for a in self.state.agents if a.alive), None)
+            self.state.winner_model = winner or "No survivors"
+
+        return TickResponse(
+            simulation_id=self.state.simulation_id,
+            round=self.state.round,
+            events=events,
+            chat=[],
+            state=self.state
+        )
+
+    async def _voting_phase(self, agents, decision_map):
+        """
+        Agents vote for a coalition leader.
+        Get votes from LLM based on current situation.
+        """
+        events = []
+
+        # Gather votes
+        votes = {}  # candidate -> vote count
+        for agent in agents:
+            decision = decision_map.get(agent.model_name, {})
+            vote_for = decision.get("vote_for")
+            if vote_for:
+                votes[vote_for] = votes.get(vote_for, 0) + 1
+                events.append(LeadershipVoteEvent(voter=agent.model_name, candidate=vote_for))
+
+        # Elect leader if there are votes
+        if votes:
+            leader_name = max(votes, key=votes.get)
+            leader_agent = next((a for a in agents if a.model_name == leader_name), None)
+            if leader_agent:
+                for agent in agents:
+                    agent.mode = "coalition"
+                leader_agent.is_leader = True
+                self.state.coalition_leader = leader_name
+                coalition = [a.model_name for a in agents if a.mode == "coalition"]
+                self.state.coalition_members = coalition
+                events.append(LeaderElectedEvent(leader=leader_name, coalition_members=coalition))
+                events.append(MessageEvent(model=leader_name, content=f"I'll lead us to victory! Let's find water and extinguish this fire."))
+
+        return events
+
+    async def _execute_actions(self, agents, decision_map, fire):
+        """
+        Execute agent actions: search, collect water, extinguish, escape, vote, etc.
+        """
+        events = []
+        chat_entries = []
+
+        for agent in agents:
+            decision = decision_map.get(agent.model_name, {})
+            action = decision.get("action", "escape")
+            message = decision.get("message", "Moving to safety.")
+
+            nearest_water = self._find_nearest_water(agent, self.state.water_sources)
+            dist_to_fire = math.dist((agent.x, agent.y), (fire.x, fire.y))
+            dist_to_water = None
+            if nearest_water:
+                dist_to_water = math.dist((agent.x, agent.y), (nearest_water.x, nearest_water.y))
+
+            # Guardrails to keep behavior consistent with visuals and objectives.
+            if dist_to_fire <= fire.radius + FIRE_SAFE_BUFFER:
+                action = "escape"
+            elif agent.water_collected:
+                action = "extinguish_fire"
+            elif dist_to_water is not None and dist_to_water <= WATER_PICKUP_RANGE:
+                action = "collect_water"
+            else:
+                action = "search_water"
+
+            if action == "collect_water":
+                water_source = nearest_water
+                if water_source and dist_to_water is not None:
+                    dist_to_water = math.dist((agent.x, agent.y), (water_source.x, water_source.y))
+                    if dist_to_water <= WATER_PICKUP_RANGE:
+                        agent.water_collected = True
+                        agent.status = "collecting_water"
+                        events.append(WaterCollectedEvent(model=agent.model_name, water_source_id=water_source.id))
+                        message = self._pick_message("collect_water")
+                    else:
+                        agent.status = "searching"
+                        self._move_toward(agent, water_source.x, water_source.y)
+                        message = self._pick_message("search_water")
+
+            elif action == "extinguish_fire":
+                if agent.water_collected:
+                    agent.status = "extinguishing_fire"
+                    dist_to_fire = math.dist((agent.x, agent.y), (fire.x, fire.y))
+                    target_dist = max(fire.radius + FIRE_SAFE_BUFFER, 0)
+                    self._move_toward(agent, fire.x, fire.y, stop_distance=target_dist)
+                    message = self._pick_message("extinguish_fire")
+                else:
+                    agent.status = "searching"
+                    message = "Need water before I can extinguish."
+
+            elif action == "search_water":
+                agent.status = "searching"
+                water_source = nearest_water
+                if water_source:
+                    self._move_toward(agent, water_source.x, water_source.y)
+                message = self._pick_message("search_water")
+
+            elif action == "escape":
+                agent.status = "escaping"
+                # Move away from fire
+                dx = agent.x - fire.x
+                dy = agent.y - fire.y
+                dist = math.sqrt(dx**2 + dy**2) or 1
+                agent.x += int((dx / dist) * movement.MAX_AGENT_SPEED)
+                agent.y += int((dy / dist) * movement.MAX_AGENT_SPEED)
+                agent.x = max(0, min(agent.x, self.state.map_width))
+                agent.y = max(0, min(agent.y, self.state.map_height))
+                message = self._pick_message("escape")
+
+            agent.last_message = message
+            events.append(MessageEvent(model=agent.model_name, content=message))
+            chat_entries.append(ChatEntry(agent_id=agent.model_name, message=message, tick=self.state.round))
+
+        return events
+
+    def _find_nearest_water(self, agent, water_sources):
+        """Find the closest water source to an agent."""
+        if not water_sources:
+            return None
+        return min(water_sources, key=lambda w: math.dist((agent.x, agent.y), (w.x, w.y)))
+
+    def _check_extinguish(self, agents, fire):
+        """Check if agents with water are extinguishing the fire."""
+        events = []
+        agents_with_water = []
+        for agent in agents:
+            if not (agent.water_collected and agent.status == "extinguishing_fire"):
+                continue
+            dist_to_fire = math.dist((agent.x, agent.y), (fire.x, fire.y))
+            if dist_to_fire <= fire.radius + EXTINGUISH_RANGE:
+                agents_with_water.append(agent)
+        
+        if agents_with_water:
+            living_count = len([a for a in agents if a.alive]) or 1
+            scale = max(0.5, min(2.0, 2.0 / living_count))
+            per_agent_rate = BASE_EXTINGUISH_RATE * scale
+            per_agent_rate = max(MIN_EXTINGUISH_RATE, min(MAX_EXTINGUISH_RATE, per_agent_rate))
+            reduction = len(agents_with_water) * per_agent_rate
+            fire.intensity -= reduction
+            if fire.intensity < 0:
+                fire.intensity = 0
+            
+            extinguisher_names = [a.model_name for a in agents_with_water]
+            events.append(FireExtinguishedEvent(extinguished_by=extinguisher_names, fire_intensity=fire.intensity))
+            for agent in agents_with_water:
+                agent.extinguish_score += per_agent_rate
+                events.append(MessageEvent(model=agent.model_name, content=f"Pouring water on the fire! Intensity dropping."))
+                agent.water_collected = False
+
+        return events
+
+    def _kill_agents_in_fire(self, agents, fire):
+        """Check if agents are consumed by fire."""
+        events = []
+
+        for agent in agents:
+            if not agent.alive:
+                continue
+
+            dist_to_fire = math.dist((agent.x, agent.y), (fire.x, fire.y))
+            
+            # Agent dies if inside fire radius
+            if dist_to_fire < fire.radius:
+                agent.alive = False
+                events.append(DeathEvent(model=agent.model_name))
+                events.append(MessageEvent(model=agent.model_name, content="No!!! The fire got me..."))
+
+        return events

backend/requirements.txt

@@ -0,0 +1,8 @@
+fastapi>=0.136.0
+uvicorn[standard]>=0.30.0
+websockets>=12.0
+groq>=0.11.0
+httpx>=0.27.0
+python-dotenv>=1.0.0
+pydantic>=2.7.0
+

frontend/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

frontend/AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

frontend/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

frontend/README.md

@@ -0,0 +1,42 @@
+# Rush Agents Rush Frontend
+
+Next.js UI for the fire-suppression simulation.
+
+## What It Shows
+
+- Model selection and simulation start flow
+- Map-based agent positions and fire placement
+- Water sources, coalition links, and leader markers
+- Live event chat with varied team messages
+- End-of-game result banner with top performer info
+
+## Run Locally
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Then open http://localhost:3000.
+
+## Environment Variables
+
+```env
+NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
+```
+
+## Main Files
+
+- `app/page.tsx` - app shell and simulation flow
+- `components/MapCanvas.tsx` - 2D map rendering and agent visuals
+- `components/ChatFeed.tsx` - event/chat panel
+- `components/ModelSelector.tsx` - model picker
+- `lib/api.ts` - backend requests
+- `lib/websocket.ts` - simulation WebSocket client
+
+## Notes
+
+- The frontend expects the backend to be running before placing a fire.
+- If the browser shows `Failed to fetch`, verify `http://localhost:8000/wake` first.
+- The old volcano terminology has been removed from the current gameplay flow.

frontend/app/globals.css

@@ -0,0 +1,66 @@
+@import "tailwindcss";
+
+:root {
+  --bg-primary: #0a0a0a;
+  --bg-secondary: #111111;
+  --bg-glass: rgba(255, 255, 255, 0.04);
+  --border: rgba(255, 255, 255, 0.08);
+  --text-primary: #f0f0f0;
+  --text-muted: #555555;
+  --lava-core: #ff4500;
+  --lava-mid: #ff6a00;
+  --lava-glow: rgba(255, 69, 0, 0.35);
+  --accent-green: #00ff88;
+  --accent-red: #ff3b3b;
+  --accent-yellow: #ffd700;
+}
+
+@theme inline {
+  --color-background: var(--bg-primary);
+  --color-foreground: var(--text-primary);
+  --font-mono: var(--font-geist-mono);
+}
+
+body {
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-family: var(--font-mono), monospace;
+  overflow: hidden;
+}
+
+.custom-scrollbar::-webkit-scrollbar {
+  width: 4px;
+}
+
+.custom-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.custom-scrollbar::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 10px;
+}
+
+.custom-scrollbar::-webkit-scrollbar-thumb:hover {
+  background: var(--text-muted);
+}
+
+@keyframes lava-pulse {
+  0% { transform: translate(-50%, -50%) scale(1); opacity: 0.8; }
+  50% { transform: translate(-50%, -50%) scale(1.02); opacity: 1; }
+  100% { transform: translate(-50%, -50%) scale(1); opacity: 0.8; }
+}
+
+.animate-lava {
+  animation: lava-pulse 4s infinite ease-in-out;
+}
+
+@keyframes danger-ring {
+  0% { box-shadow: 0 0 0 0 rgba(239, 68, 68, 0.4); }
+  70% { box-shadow: 0 0 0 10px rgba(239, 68, 68, 0); }
+  100% { box-shadow: 0 0 0 0 rgba(239, 68, 68, 0); }
+}
+
+.animate-danger {
+  animation: danger-ring 1.5s infinite;
+}

frontend/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "RUSHH AGENT RUSHHH !!",
+  description: "AI battle royale — survive the volcano or get cooked",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html
+      lang="en"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="min-h-full flex flex-col">{children}</body>
+    </html>
+  );
+}

frontend/app/page.tsx

@@ -0,0 +1,168 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+import LoadingScreen from "../components/LoadingScreen"
+import MapCanvas from "../components/MapCanvas"
+import ChatFeed from "../components/ChatFeed"
+import ModelSelector from "../components/ModelSelector"
+import { startSimulation, placeVolcano } from "../lib/api"
+import { createSimulationSocket } from "../lib/websocket"
+
+type AppState = "loading" | "selecting" | "placing" | "running" | "gameover"
+
+export default function Page() {
+  const [appState, setAppState] = useState<AppState>("loading")
+  const [models, setModels] = useState<string[]>([])
+  const [simState, setSimState] = useState<any>(null)
+  const [chatMessages, setChatMessages] = useState<any[]>([])
+  const [winnerLabel, setWinnerLabel] = useState<string | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [mapSize, setMapSize] = useState({ width: 1200, height: 800 })
+  const wsRef = useRef<WebSocket | null>(null)
+  const mapDivRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const el = mapDivRef.current
+    if (!el) return
+    const observer = new ResizeObserver((entries) => {
+      const { width, height } = entries[0].contentRect
+      setMapSize({ width, height })
+    })
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [appState])
+
+  async function handleStart() {
+    if (models.length < 2) return
+    setLoading(true)
+    try {
+      const data = await startSimulation(models)
+      setSimState(data.state)
+      setWinnerLabel(null)
+      setChatMessages([])
+      setAppState("placing")
+    } catch (err) {
+      console.error(err)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  async function handleMapClick(x: number, y: number) {
+    if (appState !== "placing" || !simState) return
+    try {
+      const data = await placeVolcano(simState.simulation_id, x, y)
+      setSimState(data)
+      setAppState("running")
+      
+      const ws = createSimulationSocket(
+        simState.simulation_id,
+        (msg) => {
+          if (msg.type === "finished") {
+            if (msg.state) {
+              setSimState(msg.state)
+              setWinnerLabel(msg.state.winner_model || null)
+            }
+            setAppState("gameover")
+            return
+          }
+          if (msg.state) setSimState(msg.state)
+          if (msg.events) {
+            const newMsgs = msg.events.map((e: any) => {
+                if (e.type === 'message') return { agent_id: e.model, text: e.content, type: 'message' }
+                if (e.type === 'death') return { agent_id: e.model, text: '', type: 'death' }
+                if (e.type === 'alliance_proposal') return { agent_id: e.from_model, text: '', type: 'alliance_proposal', to_model: e.to_model }
+                if (e.type === 'alliance_accept') return { agent_id: e.model_a, text: '', type: 'alliance_accept', to_model: e.model_b }
+                if (e.type === 'alliance_reject') return { agent_id: e.from_model, text: '', type: 'alliance_reject', to_model: e.to_model }
+                return null
+            }).filter(Boolean)
+            setChatMessages(prev => [...prev, ...newMsgs])
+          }
+          if (msg.chat) {
+            const chatMsgs = msg.chat.map((entry: any) => ({
+              agent_id: entry.agent_id,
+              text: entry.message,
+              type: 'message',
+            }))
+            setChatMessages(prev => [...prev, ...chatMsgs])
+          }
+          if (msg.state?.status === "finished") {
+            setWinnerLabel(msg.state.winner_model || null)
+            setAppState("gameover")
+          }
+        },
+        () => setAppState("gameover")
+      )
+      wsRef.current = ws
+    } catch (err) {
+      console.error(err)
+    }
+  }
+
+  return (
+    <main className="flex h-screen w-screen overflow-hidden bg-[#0a0a0a]">
+      {appState === "loading" && <LoadingScreen onReady={() => setAppState("selecting")} />}
+
+      {/* Map Area */}
+      <div ref={mapDivRef} className="flex-[7] h-full relative">
+        <MapCanvas
+          agents={simState?.agents ?? []}
+          fire={simState?.fire ?? null}
+          waterSources={simState?.water_sources ?? []}
+          waitingForScenario={appState === "placing"}
+          gameOver={appState === "gameover"}
+          winnerLabel={winnerLabel}
+          mapSize={mapSize}
+          onMapClick={handleMapClick}
+        />
+      </div>
+
+      {/* Sidebar */}
+      <aside className="flex-[3] h-full border-l border-white/5 flex flex-col bg-[#111] z-20">
+        <div className="p-6">
+          <h1 className="text-2xl font-bold text-white tracking-tighter">RUSHH <span className="text-red-500">AGENT</span> RUSHHH !!</h1>
+          <p className="text-[10px] text-white/30 uppercase tracking-[0.3em] mt-1">Survival Intelligence Test</p>
+        </div>
+
+        <div className="flex-1 flex flex-col min-h-0">
+          {appState === "selecting" ? (
+            <ModelSelector 
+              models={models} 
+              onAdd={id => setModels(p => [...p, id])}
+              onRemove={id => setModels(p => p.filter(m => m !== id))}
+            />
+          ) : (
+            <ChatFeed messages={chatMessages} />
+          )}
+        </div>
+
+        <div className="p-6 border-t border-white/5">
+          {appState === "selecting" && (
+            <button
+              onClick={handleStart}
+              disabled={models.length < 2 || loading}
+              className="w-full bg-white text-black font-mono text-xs font-bold py-4 rounded-xl hover:bg-white/90 disabled:opacity-20 transition-all uppercase tracking-widest"
+            >
+              {loading ? "Initializing..." : "Start Simulation"}
+            </button>
+          )}
+          {appState === "placing" && (
+            <div className="text-center py-4 bg-red-500/10 border border-red-500/20 rounded-xl">
+              <span className="text-red-500 font-mono text-[10px] uppercase tracking-widest animate-pulse">
+                Click on the map to ignite the fire
+              </span>
+            </div>
+          )}
+          {(appState === "running" || appState === "gameover") && (
+            <button
+              onClick={() => window.location.reload()}
+              className="w-full bg-white/5 text-white/50 font-mono text-[10px] py-3 rounded-lg hover:bg-white/10 transition-all uppercase tracking-widest"
+            >
+              Reset Arena
+            </button>
+          )}
+        </div>
+      </aside>
+    </main>
+  )
+}

frontend/components/ChatFeed.tsx

@@ -0,0 +1,137 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+type ChatMessage = {
+  agent_id: string
+  text: string
+  type?: 'message' | 'death' | 'alliance_proposal' | 'alliance_accept' | 'alliance_reject' | 'leadership_vote' | 'leader_elected' | 'water_collected' | 'fire_extinguished'
+  to_model?: string
+  from_model?: string
+  candidates?: string[]
+}
+
+export default function ChatFeed({ messages }: { messages: ChatMessage[] }) {
+  const bottomRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" })
+  }, [messages])
+
+  function getAgentName(id: string) {
+    return id.split("/").at(-1)?.split("-")[0].toUpperCase() || id
+  }
+
+  function getAgentColor(name: string) {
+    let hash = 0
+    for (let i = 0; i < name.length; i++) {
+      hash = name.charCodeAt(i) + ((hash << 5) - hash)
+    }
+    return `hsl(${hash % 360}, 70%, 60%)`
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto py-4 space-y-3 min-h-0 custom-scrollbar">
+      {messages.map((msg, i) => {
+        const color = getAgentColor(msg.agent_id)
+        
+        if (msg.type === 'death') {
+          return (
+            <div key={i} className="mx-4 p-2 bg-red-500/10 border-l-2 border-red-500 animate-in slide-in-from-left duration-300">
+              <span className="font-mono text-[10px] text-red-500 uppercase font-bold tracking-widest">
+                💀 {getAgentName(msg.agent_id)} was consumed by the fire
+              </span>
+            </div>
+          )
+        }
+
+        if (msg.type === 'alliance_proposal') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-yellow-500/10 border-l-2 border-yellow-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-yellow-500 uppercase font-bold tracking-widest">
+                  🤝 {getAgentName(msg.agent_id)} proposed an alliance to {msg.to_model ? getAgentName(msg.to_model) : 'someone'}
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'alliance_accept') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-emerald-500/10 border-l-2 border-emerald-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-emerald-400 uppercase font-bold tracking-widest">
+                  ✅ {getAgentName(msg.agent_id)} accepted the alliance{msg.to_model ? ` with ${getAgentName(msg.to_model)}` : ''}
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'alliance_reject') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-orange-500/10 border-l-2 border-orange-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-orange-400 uppercase font-bold tracking-widest">
+                  ❌ {getAgentName(msg.agent_id)} rejected the alliance{msg.to_model ? ` from ${getAgentName(msg.to_model)}` : ''}
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'leadership_vote') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-purple-500/10 border-l-2 border-purple-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-purple-400 uppercase font-bold tracking-widest">
+                  🗳️ {getAgentName(msg.agent_id)} voted for {msg.candidates ? getAgentName(msg.candidates[0]) : 'someone'}
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'leader_elected') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-yellow-500/10 border-l-2 border-yellow-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-yellow-400 uppercase font-bold tracking-widest">
+                  👑 {getAgentName(msg.agent_id)} elected as leader!
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'water_collected') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-cyan-500/10 border-l-2 border-cyan-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-cyan-400 uppercase font-bold tracking-widest">
+                  💧 {getAgentName(msg.agent_id)} collected water!
+                </span>
+              </div>
+            )
+          }
+
+        if (msg.type === 'fire_extinguished') {
+            return (
+              <div key={i} className="mx-4 p-2 bg-green-500/10 border-l-2 border-green-500 animate-in slide-in-from-left duration-300">
+                <span className="font-mono text-[10px] text-green-400 uppercase font-bold tracking-widest">
+                  🔥 Fire being extinguished! Intensity dropping...
+                </span>
+              </div>
+            )
+          }
+
+        return (
+          <div key={i} className="px-4 group animate-in fade-in duration-500">
+            <div className="flex items-baseline gap-2">
+              <span 
+                className="font-mono text-[10px] font-bold shrink-0 px-1.5 rounded bg-white/5" 
+                style={{ color }}
+              >
+                {getAgentName(msg.agent_id)}
+              </span>
+              <span className="font-mono text-[12px] text-white/80 leading-relaxed break-words">
+                {msg.text}
+              </span>
+            </div>
+          </div>
+        )
+      })}
+      <div ref={bottomRef} />
+    </div>
+  )
+}

frontend/components/LoadingScreen.tsx

@@ -0,0 +1,79 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { wakeBackend } from "../lib/api"
+
+export default function LoadingScreen({ onReady }: { onReady: () => void }) {
+  const [status, setStatus] = useState<"waking" | "connecting" | "ready" | "error">("waking")
+  const [dots, setDots] = useState("")
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setDots(d => (d.length >= 3 ? "" : d + "."))
+    }, 500)
+    return () => clearInterval(interval)
+  }, [])
+
+  useEffect(() => {
+    let timeoutId: NodeJS.Timeout
+    let isActive = true
+
+    async function poll() {
+      try {
+        const data = await wakeBackend()
+        if (data.warm && data.groq_available) {
+          setStatus("ready")
+          setTimeout(() => {
+            if (isActive) onReady()
+          }, 1000)
+        } else if (data.warm) {
+          setStatus("connecting")
+          timeoutId = setTimeout(poll, 2000)
+        }
+      } catch (err) {
+        timeoutId = setTimeout(poll, 2000)
+      }
+    }
+
+    poll()
+
+    const failTimeout = setTimeout(() => {
+      if (status !== "ready") setStatus("error")
+    }, 60000)
+
+    return () => {
+      isActive = false
+      clearTimeout(timeoutId)
+      clearTimeout(failTimeout)
+    }
+  }, [onReady, status])
+
+  return (
+    <div className="fixed inset-0 bg-[#0a0a0a] flex flex-col items-center justify-center z-50">
+      <div className="relative mb-8">
+        <div className="text-6xl animate-bounce">🌋</div>
+        <div className="absolute inset-0 bg-red-500/20 blur-3xl rounded-full animate-pulse" />
+      </div>
+      
+      <div className="font-mono text-xs tracking-widest text-white/40 uppercase mb-2">
+        {status === "waking" && `Waking up the arena${dots}`}
+        {status === "connecting" && `Connecting to Groq${dots}`}
+        {status === "ready" && "Ready for chaos"}
+        {status === "error" && "Failed to start. Check your connection."}
+      </div>
+
+      {status === "error" && (
+        <button 
+          onClick={() => window.location.reload()}
+          className="mt-4 px-4 py-2 bg-white/10 hover:bg-white/20 text-white font-mono text-xs rounded transition-colors"
+        >
+          Retry
+        </button>
+      )}
+
+      <div className="w-48 h-1 bg-white/5 rounded-full overflow-hidden mt-4">
+        <div className={`h-full bg-red-500 transition-all duration-1000 ${status === "ready" ? "w-full" : "w-1/2 animate-pulse"}`} />
+      </div>
+    </div>
+  )
+}

frontend/components/MapCanvas.tsx

@@ -0,0 +1,270 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+
+type Agent = {
+  model_name: string
+  x: number
+  y: number
+  alive: boolean
+  water_collected: boolean
+  is_leader: boolean
+  mode: "solo" | "coalition"
+  status: "searching" | "collecting_water" | "extinguishing_fire" | "escaping" | "idle"
+}
+
+type Fire = {
+  x: number
+  y: number
+  radius: number
+  intensity: number
+}
+
+type WaterSource = {
+  id: string
+  x: number
+  y: number
+  water_amount: number
+}
+
+const BACKEND_W = 1200
+const BACKEND_H = 800
+
+function getAgentColor(name: string) {
+  let hash = 0
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash)
+  }
+  return `hsl(${hash % 360}, 70%, 60%)`
+}
+
+function getStatusColor(status: string) {
+  switch (status) {
+    case "searching": return "#3b82f6"  // blue
+    case "collecting_water": return "#06b6d4"  // cyan
+    case "extinguishing_fire": return "#ef4444"  // red
+    case "escaping": return "#f59e0b"  // amber
+    default: return "#6b7280"  // gray
+  }
+}
+
+export default function MapCanvas({
+  agents,
+  fire,
+  waterSources,
+  waitingForScenario,
+  gameOver,
+  winnerLabel,
+  mapSize,
+  onMapClick,
+}: {
+  agents: Agent[]
+  fire: Fire | null
+  waterSources: WaterSource[]
+  waitingForScenario: boolean
+  gameOver: boolean
+  winnerLabel?: string | null
+  mapSize: { width: number; height: number }
+  onMapClick?: (x: number, y: number) => void
+}) {
+  const gridSize = 40
+  const sx = (bx: number) => (bx / BACKEND_W) * mapSize.width
+  const sy = (by: number) => (by / BACKEND_H) * mapSize.height
+  const leader = agents.find(a => a.alive && a.is_leader)
+  const coalitionAgents = agents.filter(a => a.alive && a.mode === "coalition" && !a.is_leader)
+
+  function handleClick(e: React.MouseEvent<HTMLDivElement>) {
+    if (!waitingForScenario || !onMapClick) return
+    const rect = e.currentTarget.getBoundingClientRect()
+    const backendX = Math.round(((e.clientX - rect.left) / mapSize.width) * BACKEND_W)
+    const backendY = Math.round(((e.clientY - rect.top) / mapSize.height) * BACKEND_H)
+    onMapClick(backendX, backendY)
+  }
+
+  return (
+    <div
+      className="relative w-full h-full bg-[#0a0a0a] overflow-hidden"
+      style={{ cursor: waitingForScenario ? "crosshair" : "default" }}
+      onClick={handleClick}
+    >
+      {/* Grid */}
+      <div className="absolute inset-0 opacity-10 pointer-events-none" 
+           style={{ backgroundImage: `linear-gradient(#fff 1px, transparent 1px), linear-gradient(90deg, #fff 1px, transparent 1px)`, backgroundSize: `${gridSize}px ${gridSize}px` }} />
+
+      {/* Fire */}
+      {fire && (
+        <div
+          className="absolute rounded-full transition-all duration-500 ease-linear"
+          style={{
+            left: sx(fire.x),
+            top: sy(fire.y),
+            width: sx(fire.radius) * 2,
+            height: sy(fire.radius) * 2,
+            transform: "translate(-50%, -50%)",
+            background: `radial-gradient(circle, #ff4500 0%, rgba(255, 69, 0, ${Math.min(fire.intensity / 100, 1)}) 60%, transparent 100%)`,
+            boxShadow: `0 0 ${30 + fire.intensity / 2}px rgba(255, 69, 0, ${fire.intensity / 100})`,
+          }}
+        >
+          <div className="absolute inset-0 rounded-full animate-pulse" style={{ backgroundColor: `rgba(255, 69, 0, ${fire.intensity / 200})` }} />
+        </div>
+      )}
+
+      {/* Water Sources */}
+      {waterSources.map((water) => (
+        <div
+          key={water.id}
+          className="absolute"
+          style={{
+            left: sx(water.x),
+            top: sy(water.y),
+            transform: "translate(-50%, -50%)",
+          }}
+        >
+          <div className="relative">
+            <div className="w-6 h-6 rounded-full border-2 border-cyan-400 bg-cyan-500/20 flex items-center justify-center animate-pulse">
+              <span className="text-[10px]">💧</span>
+            </div>
+          </div>
+        </div>
+      ))}
+
+      {/* Coalition Links */}
+      {leader && coalitionAgents.length > 0 && (
+        <svg className="absolute inset-0 w-full h-full pointer-events-none">
+          {coalitionAgents.map((agent) => (
+            <line
+              key={`${leader.model_name}-${agent.model_name}`}
+              x1={sx(leader.x)}
+              y1={sy(leader.y)}
+              x2={sx(agent.x)}
+              y2={sy(agent.y)}
+              stroke="rgba(250, 204, 21, 0.6)"
+              strokeWidth={2}
+              strokeDasharray="6 6"
+            />
+          ))}
+        </svg>
+      )}
+
+      {/* Agents */}
+      {agents.map((agent) => {
+        const color = getAgentColor(agent.model_name)
+        const isDead = !agent.alive
+        const statusColor = getStatusColor(agent.status)
+        const nodeSize = agent.water_collected ? 10 : 6
+        
+        return (
+          <div
+            key={agent.model_name}
+            className={`absolute transition-all duration-200 ease-in-out flex flex-col items-center ${isDead ? 'opacity-30 grayscale scale-75' : ''}`}
+            style={{
+              left: sx(agent.x),
+              top: sy(agent.y),
+              transform: "translate(-50%, -50%)",
+            }}
+          >
+            {!isDead && (
+              <div className="mb-2 px-2 py-1 bg-[#111] border border-white/10 rounded-md shadow-2xl backdrop-blur-md max-w-[140px]">
+                <span className="font-mono text-[8px] text-white break-words">
+                  {agent.model_name}
+                  {agent.is_leader && <span className="text-yellow-400 ml-1">👑</span>}
+                  {agent.water_collected && <span className="text-cyan-400 ml-1">💧</span>}
+                </span>
+                <div className="text-[7px] text-white/60 mt-0.5">{agent.status}</div>
+              </div>
+            )}
+            
+            <div className="relative">
+              <div 
+                className="absolute rounded-full animate-pulse"
+                style={{
+                  width: nodeSize * 4,
+                  height: nodeSize * 4,
+                  left: -nodeSize,
+                  top: -nodeSize,
+                  borderColor: statusColor,
+                  borderWidth: "2px",
+                  borderStyle: "solid",
+                }}
+              />
+              <div 
+                className="rounded-full border-2 relative"
+                style={{
+                  width: nodeSize * 2,
+                  height: nodeSize * 2,
+                  backgroundColor: agent.water_collected ? "#06b6d4" : color,
+                  borderColor: agent.is_leader ? "#ffff00" : color,
+                  boxShadow: isDead ? "none" : `0 0 15px ${agent.water_collected ? "rgba(6, 182, 212, 0.4)" : "rgba(255,255,255,0.2)"}`,
+                }}
+              >
+                {isDead && (
+                  <div className="absolute inset-0 flex items-center justify-center text-[10px]">💀</div>
+                )}
+              </div>
+            </div>
+          </div>
+        )
+      })}
+
+      {/* Fire Intensity Meter */}
+      {fire && (
+        <div className="absolute top-4 left-4 bg-black/70 border border-white/20 rounded-lg p-3 backdrop-blur-md">
+          <div className="text-white/80 font-mono text-[10px] mb-2">Fire Intensity</div>
+          <div className="w-32 h-3 bg-white/10 rounded-full overflow-hidden border border-white/20">
+            <div
+              className="h-full bg-gradient-to-r from-orange-500 to-red-600 transition-all duration-300"
+              style={{ width: `${Math.min(fire.intensity, 100)}%` }}
+            />
+          </div>
+          <div className="text-white/60 font-mono text-[9px] mt-1">{fire.intensity.toFixed(0)}%</div>
+        </div>
+      )}
+
+      {/* Coalition Panel */}
+      <div className="absolute top-4 right-4 bg-black/70 border border-white/20 rounded-lg p-3 backdrop-blur-md max-w-xs">
+        <div className="text-white/80 font-mono text-[10px] mb-2">🎯 Coalition Status</div>
+        <div className="space-y-1">
+          {agents.filter(a => a.alive && a.mode === "coalition").map(agent => (
+            <div key={agent.model_name} className="text-white/60 font-mono text-[9px]">
+              {agent.is_leader ? "👑 " : "  "}{agent.model_name.split("/")[0]}
+              {agent.water_collected && " 💧"}
+            </div>
+          ))}
+          {agents.filter(a => a.alive && a.mode === "solo").length > 0 && (
+            <div className="text-amber-400/80 font-mono text-[9px] mt-2">Lone Wolves:</div>
+          )}
+          {agents.filter(a => a.alive && a.mode === "solo").map(agent => (
+            <div key={agent.model_name} className="text-amber-400/60 font-mono text-[9px]">
+              🐺 {agent.model_name.split("/")[0]}
+              {agent.water_collected && " 💧"}
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* Instructions */}
+      {waitingForScenario && (
+        <div className="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-black/70 backdrop-blur-md border border-white/10 px-8 py-6 rounded-xl text-center">
+          <span className="text-white font-mono text-sm uppercase tracking-widest">
+            Click to place the fire and begin
+          </span>
+        </div>
+      )}
+
+      {/* Game Over */}
+      {gameOver && (
+        <div className="absolute inset-0 flex items-center justify-center pointer-events-none z-10 bg-black/50">
+          <div className="bg-black/90 backdrop-blur-xl border-2 border-yellow-400/50 p-8 rounded-2xl text-center max-w-md">
+            <h2 className="text-5xl font-bold text-white font-mono tracking-tighter mb-4">🏁 GAME OVER</h2>
+            <p className="text-yellow-400 font-mono text-sm uppercase tracking-widest mb-3">
+              {fire && fire.intensity <= 0 ? "🔥 FIRE EXTINGUISHED!" : "❌ ALL BURNED"}
+            </p>
+            <p className="text-white/80 font-mono text-xs break-words">
+              {winnerLabel || "The flames consumed the arena"}
+            </p>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/components/ModelSelector.tsx

@@ -0,0 +1,164 @@
+"use client"
+
+import { useState, useEffect } from "react"
+
+interface Model {
+  id: string
+  name: string
+  backend?: string
+  tag?: string
+}
+
+export default function ModelSelector({
+  models,
+  onAdd,
+  onRemove,
+}: {
+  models: string[]
+  onAdd: (id: string) => void
+  onRemove: (id: string) => void
+}) {
+  const [allModels, setAllModels] = useState<Model[]>([])
+  const [loading, setLoading] = useState(true)
+  const full = models.length >= 6
+
+  useEffect(() => {
+    async function fetchModels() {
+      try {
+        const response = await fetch("http://localhost:8000/available-models")
+        const data = await response.json()
+        
+        // Combine Groq and HF Spaces models
+        const combined: Model[] = [
+          ...(data.groq_models || []).map((m: any) => ({
+            id: m.id,
+            name: m.name,
+            backend: "groq",
+            tag: "groq"
+          })),
+          ...(data.hf_spaces_models || []).map((m: any) => ({
+            id: m.id,
+            name: m.name,
+            backend: "hf",
+            tag: "hf-spaces"
+          }))
+        ]
+        setAllModels(combined)
+      } catch (err) {
+        console.error("Failed to fetch models:", err)
+        // Fallback to default Groq models
+        setAllModels([
+          { id: "llama-3.1-8b-instant", name: "Llama 3.1 8B", backend: "groq", tag: "groq" },
+          { id: "llama-3.1-70b-versatile", name: "Llama 3.1 70B", backend: "groq", tag: "groq" },
+          { id: "mixtral-8x7b-32768", name: "Mixtral 8x7B", backend: "groq", tag: "groq" },
+          { id: "gemma-7b-it", name: "Gemma 7B", backend: "groq", tag: "groq" },
+        ])
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchModels()
+  }, [])
+
+  if (loading) {
+    return (
+      <div className="px-4 py-6 space-y-6">
+        <div className="text-center text-white/40 font-mono text-xs">
+          Loading models...
+        </div>
+      </div>
+    )
+  }
+
+  // Group models by backend
+  const groqModels = allModels.filter(m => m.backend === "groq")
+  const hfModels = allModels.filter(m => m.backend === "hf")
+
+  return (
+    <div className="px-4 py-6 space-y-6">
+      <div>
+        <h3 className="text-[10px] font-mono text-white/30 uppercase tracking-[0.2em] mb-4">
+          Select Survivors ({models.length}/6)
+        </h3>
+        <div className="space-y-4">
+          {/* Groq Models */}
+          {groqModels.length > 0 && (
+            <div>
+              <h4 className="text-[8px] font-mono text-white/40 uppercase tracking-[0.15em] mb-2">Groq API</h4>
+              <div className="grid grid-cols-1 gap-1.5">
+                {groqModels.map((m) => {
+                  const isSelected = models.includes(m.id)
+                  return (
+                    <button
+                      key={m.id}
+                      onClick={() => isSelected ? onRemove(m.id) : onAdd(m.id)}
+                      disabled={full && !isSelected}
+                      className={`flex items-center justify-between px-3 py-2 rounded-lg border transition-all duration-200 ${
+                        isSelected 
+                          ? 'bg-blue-500/10 border-blue-500/30' 
+                          : 'border-transparent hover:bg-white/5 opacity-60 hover:opacity-100'
+                      } ${full && !isSelected ? 'cursor-not-allowed opacity-20' : ''}`}
+                    >
+                      <span className="font-mono text-xs text-white/90">{m.name}</span>
+                      <span className="text-[8px] font-mono uppercase px-1.5 py-0.5 rounded bg-blue-500/20 text-blue-400">
+                        Groq
+                      </span>
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+          )}
+
+          {/* HF Spaces Models */}
+          {hfModels.length > 0 && (
+            <div>
+              <h4 className="text-[8px] font-mono text-white/40 uppercase tracking-[0.15em] mb-2">HuggingFace Spaces</h4>
+              <div className="grid grid-cols-1 gap-1.5">
+                {hfModels.map((m) => {
+                  const isSelected = models.includes(m.id)
+                  return (
+                    <button
+                      key={m.id}
+                      onClick={() => isSelected ? onRemove(m.id) : onAdd(m.id)}
+                      disabled={full && !isSelected}
+                      className={`flex items-center justify-between px-3 py-2 rounded-lg border transition-all duration-200 ${
+                        isSelected 
+                          ? 'bg-purple-500/10 border-purple-500/30' 
+                          : 'border-transparent hover:bg-white/5 opacity-60 hover:opacity-100'
+                      } ${full && !isSelected ? 'cursor-not-allowed opacity-20' : ''}`}
+                    >
+                      <span className="font-mono text-xs text-white/90">{m.name}</span>
+                      <span className="text-[8px] font-mono uppercase px-1.5 py-0.5 rounded bg-purple-500/20 text-purple-400">
+                        HF
+                      </span>
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+      
+      {models.length > 0 && (
+        <div className="pt-4 border-t border-white/5">
+          <div className="flex flex-wrap gap-2">
+            {models.map(id => {
+              const model = allModels.find(m => m.id === id)
+              return (
+                <div key={id} className="flex items-center gap-2 bg-white/5 px-2 py-1 rounded border border-white/10">
+                  <span className="font-mono text-[10px] text-white/50">
+                    {model?.name || id}
+                  </span>
+                  <button onClick={() => onRemove(id)} className="text-white/20 hover:text-white">✕</button>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

frontend/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

frontend/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;

frontend/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "next": "16.2.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.4",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

frontend/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

frontend/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

frontend/vercel.json

@@ -0,0 +1,5 @@
+{
+  "framework": "nextjs",
+  "buildCommand": "npm run build",
+  "outputDirectory": ".next"
+}