Merge hf/main: keep master version of .gitignore and README.md

.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

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

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"]

app/groq_client.py

@@ -0,0 +1,161 @@
+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, recent_radio=None) -> 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)
+    radio_summary = "\n".join(recent_radio or []) if recent_radio else "(no recent chat yet)"
+
+    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
+
+CHAT STYLE:
+- Your "message" should sound natural, social, and alive.
+- React to what other agents just said when relevant.
+- Keep it to one short sentence, playful or supportive, but still mission-focused.
+- Avoid repetitive template phrases.
+
+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'}
+
+RECENT RADIO CHAT:
+{radio_summary}
+
+{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."
+    }

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

app/main.py

@@ -0,0 +1,218 @@
+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()
+
+
+def _safe_randint(low: int, high: int) -> int:
+    """Return a valid random int even if bounds are inverted."""
+    if low > high:
+        low, high = high, low
+    return random.randint(low, high)
+
+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("/")
+async def root():
+    return {
+        "service": "rush-agents-backend",
+        "status": "ok",
+        "groq_available": groq_client.is_ready(),
+    }
+
+@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 a clamped location inside map bounds.
+    fire_x = max(0, min(req.x, sim.map_width))
+    fire_y = max(0, min(req.y, sim.map_height))
+    sim.fire = FireScenario(x=fire_x, y=fire_y)
+
+    # Generate 3-5 water sources scattered around the map
+    num_sources = random.randint(3, 5)
+    x_margin = 80
+    y_margin = 80
+    x_min = x_margin
+    x_max = max(x_margin, sim.map_width - x_margin)
+    y_min = y_margin
+    y_max = max(y_margin, sim.map_height - y_margin)
+
+    for i in range(num_sources):
+        # Prefer spawning wells to one side of the fire, but always keep ranges valid.
+        left_low = x_min
+        left_high = min(fire_x - 180, x_max)
+        right_low = max(fire_x + 180, x_min)
+        right_high = x_max
+
+        pick_left = random.random() < 0.5
+        if pick_left and left_low <= left_high:
+            water_x = _safe_randint(left_low, left_high)
+        elif right_low <= right_high:
+            water_x = _safe_randint(right_low, right_high)
+        elif left_low <= left_high:
+            water_x = _safe_randint(left_low, left_high)
+        else:
+            water_x = _safe_randint(x_min, x_max)
+
+        water_y = _safe_randint(y_min, y_max)
+        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

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

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

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)

app/simulation.py

@@ -0,0 +1,302 @@
+import asyncio
+import math
+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 _normalize_message(self, message: str | None) -> str:
+        if not message:
+            return "Staying focused and moving."
+        cleaned = " ".join(str(message).strip().split())
+        if not cleaned:
+            return "Staying focused and moving."
+        return cleaned[:220]
+
+    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]
+        recent_radio = [
+            f"{a.display_name}: {a.last_message}"
+            for a in living_agents
+            if a.last_message
+        ][-8:]
+
+        # 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, recent_radio)
+              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))
+
+        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 = self._normalize_message(decision.get("message"))
+
+            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))
+                    else:
+                        agent.status = "searching"
+                        self._move_toward(agent, water_source.x, water_source.y)
+
+            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)
+                else:
+                    agent.status = "searching"
+                    message = self._normalize_message(decision.get("message"))
+
+            elif action == "search_water":
+                agent.status = "searching"
+                water_source = nearest_water
+                if water_source:
+                    self._move_toward(agent, water_source.x, water_source.y)
+
+            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))
+
+            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
+                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

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
+