QUICKSTART.md

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

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)

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

   {
     "system": "You are [ModelName]. Make a strategic decision...",
     "user": "[Game state]"
   }
   

3. Get response

   {
     "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.)

# 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)

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! 🌋