# 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= # 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! ๐ŸŒ‹