---
title: Fire Rescue Simulator Game
emoji: 🔥
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: true
license: mit
short_description: Multi-stage MCP-driven advisor fights fires autonomously
tags:
- mcp-1st-birthday
- mcp-in-action-track-creative
- agent
- mcp
- game
---

# 🔥 Fire Rescue Simulator Game
[![Demo Video](https://img.shields.io/badge/▶️_Watch_Demo-YouTube-red?style=for-the-badge&logo=youtube)](https://youtu.be/D9_PqUR-v_o)
[![Share on X](https://img.shields.io/badge/Share_on_X-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/Arkai9/status/1994846294012281062?s=20)
![Fire Rescue Simulator thumbnail](./fire-rescue-simulator-thumbnail.png)
---

## 🌟 Project Overview

*Watch a multi-stage LLM advisor assess, plan, execute, summarize, and debrief every fire-fight cycle while you collaborate or take over manually.*

### Key Highlights

- **Multi-stage advisor (Assess → Plan → Execute → Cycle Summary → After-Action)**
- **10 FastMCP tools** cover scenario control, deployment, repositioning, removal, and analytics (idle units, coverage, building threats).
- **Real-time Gradio 6 UI**: 10×10 emoji grid, animated status HUD, AI chat timeline, event logs, and clickable placement controls.
- **Auto-execute toggle** lets players hand full control to the AI or approve every deployment manually—including adding new fires for stress tests.
- **Advisor model switcher** directly in the control panel lets you hop between GPT-OSS 120B/20B, Llama-3.1 8B, and OpenAI GPT-5.1 backends.
- **AI Battle Report Overlay**: After each victory/defeat the agent compiles charts, highlights, risks, and next actions before you rerun.
- **Submission-ready metadata**: README + prompts + PRD/dev plan + Space tags prepared for the hackathon checklist.

---

## 🛠️ MCP Toolbelt

`fire_rescue_mcp/mcp_server.py` spins up a **FastMCP** server that any agent can call (Gradio app, CLI clients, or external copilots). Tools are grouped below:

### Scenario + Control

| Tool | Purpose |
|------|---------|
| `reset_scenario` | Build a fresh grid with configurable fire/building/unit caps plus optional seed |
| `get_world_state` | Snapshot tick, fires, units, buildings, metrics, and emoji map |
| `step_simulation` | Advance the simulation loop a given number of ticks |
| `deploy_unit` | Spawn 🚒 / 🚁 at legal coordinates (never on fire/buildings) |
| `move_unit` | Remove + redeploy a specific unit in a single call |
| `remove_unit` | Free a deployment slot when a unit is idle or poorly placed |

### Analysis + Planning

| Tool | Purpose |
|------|---------|
| `find_idle_units` | Report units whose coverage radius misses every fire |
| `find_uncovered_fires` | Fires lacking coverage plus their building-threat status |
| `find_building_threats` | Fires within 2 cells of buildings + who, if anyone, covers them |
| `analyze_coverage` | Aggregates idle units, uncovered fires, building threats, and high-intensity hotspots for the planner |

---

## 🤖 AI Workflow (Assess → Debrief)

1. **Assess (Stage 1)** – Calls the analytic MCP tools to classify intensity, coverage, building threats, idle units, and threat level.
2. **Plan (Stage 2)** – Chooses a strategy (`deploy_new`, `optimize_existing`, `balanced`, etc.) and determines how many actions are justified.
3. **Execute (Stage 3)** – Emits JSON recommendations (deploy/move/remove) that the service can auto-execute or queue for the player.
4. **Cycle Summary (Stage 4)** – Condenses every loop into a headline, highlights, risks, and next-focus bullets for the Gradio timeline.
5. **After-Action Report** – Once the scenario ends, the agent merges all summaries + metrics into a “battle report” overlay with charts and actionable follow-ups.
6. **Human-in-the-loop** – Players can pause, inspect reasoning, toggle auto-execute, or manually override/augment deployments at any point.

Prompts for every stage live in `prompts.yaml`, making it easy to retune instructions without touching Python.

---

## 🎮 Gameplay Loop & UI Experience

- Start/reset from the control bar or open the accordion to tweak **fire count**, **intensity**, **building cluster size**, **max unit slots**, and **seed**.
- The advisor refreshes roughly every 10 ticks. When it is “thinking,” the HUD animates, and the chat timeline streams stage-by-stage logs.
- **Auto-Execute** default = ON. Turn it off to require manual approvals (or to stress-test AI reasoning while you handle deployments yourself).
- Click any grid cell to deploy trucks/helis, remove an existing unit, or even **ignite a new fire** (`🔥 Fire` option) in sandbox mode.
- Event log + player action chips record everything the human does (deploy, remove, ignite) for inclusion inside the after-action report.
- When success/failure triggers, the overlay shows the outcome, AI battle report, charts (threat trend, coverage, advisor cadence), and manual action summary.

---

## 🔄 Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Gradio 6 Web UI                          │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Control Panel│  │ 10×10 Grid   │  │  AI Advisor Timeline  │  │
│  │ Start/Pause  │  │ 🌲🔥🚒🏢🚁   │  │  • Stage 1-3 logs      │  │
│  │ Reset/Config │  │ Click Deploy │  │  • Cycle summaries     │  │
│  │ Auto-Execute │  │ Ignite Fires │  │  • After-action report │  │
│  └──────────────┘  └──────────────┘  └───────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Background Service                          │
│  ┌──────────────────┐    ┌────────────────────────────────────┐ │
│  │ Simulation Engine │◄──►│         AI Advisor Agent          │ │
│  │ • Fire spread     │    │ • HuggingFace Inference Provider  │ │
│  │ • Unit behavior   │    │ • MCP Tool Invocation             │ │
│  │ • Win/Lose logic  │    │ • Stage 1-4 orchestration         │ │
│  └──────────────────┘    └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      MCP Server (FastMCP)                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐  │
│  │reset_scenario│ │get_world_   │ │deploy_unit  │ │move_unit  │  │
│  └─────────────┘ │state        │ └─────────────┘ └───────────┘  │
│  ┌─────────────┐ └─────────────┘ ┌─────────────┐ ┌───────────┐  │
│  │step_        │ ┌─────────────┐ │find_uncov-  │ │find_build-│  │
│  │simulation   │ │find_idle_   │ │ered_fires   │ │ing_threats│  │
│  └─────────────┘ │units        │ └─────────────┘ └───────────┘  │
│                  └─────────────┘ ┌─────────────────────────────┐ │
│                                  │     analyze_coverage        │ │
│                                  └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

---

## 🧩 Core Components

- **`app.py`** – Gradio 6 Blocks UI, CSS-heavy HUD, timers, and event handlers for start/pause/reset, auto-execute toggles, and grid interactions.
- **`service.py`** – Threaded simulation service with 1s ticks, 10-tick advisor cadence, change-tracked UI diffing, player action tracking, and after-action orchestration.
- **`agent.py`** – Multi-stage LLM pipeline that bridges HuggingFace’s OpenAI-compatible endpoint and native OpenAI APIs, alongside JSON-repair helpers and retry/backoff logic.
- **`simulation.py`** – 10×10 grid-based simulation (fire spread, win/lose rules, unit power/range, building cluster generator, seedable randomness).
- **`models.py`** – Dataclasses for world/units/fires/events and serialization helpers used by both Gradio and MCP servers.
- **`prompts.yaml`** – Configuration for every stage (Assess/Plan/Execute/Summary/After-Action) and model defaults (`max_completion_tokens=10000`).
- **`fire_rescue_mcp/mcp_server.py`** – FastMCP server exposing the shared `SimulationEngine` as tools plus helper functions for emoji maps and coverage math.
- **Product docs** – `fire_rescue_mcp_prd_v3.md` (goal/flow) + `fire_rescue_mcp_dev_plan_v3.md` (implementation milestones) keep the hackathon deliverables aligned.

---

## 🎯 Game Rules

- **Grid**: 10×10 (Chebyshev distance for coverage). Building clusters are procedurally generated but always contiguous.
- **Units**:
  | Unit | Icon | Range | Power | Notes |
  |------|------|-------|-------|-------|
  | Fire Truck | 🚒 | 1 tile (8 neighbors) | 40% intensity cut | Fastest building-defense option |
  | Helicopter | 🚁 | 2 tiles | 25% per tick | Reaches tucked-away or multiple fires |
- **Win**: Every fire < 10% intensity (or gone) before 200 ticks.
- **Lose**: Building integrity < 50% **or** tick limit hits 200 (time out).
- **Map legend**: 🌲 Forest · 🏢 Building · 🔥 Fire ≥10% · 💨 Smoke <10% · 🚒 Truck · 🚁 Heli.
- **Manual testing**: Use the grid radio to ignite fires mid-run and watch how the AI responds.

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (optional but fastest)
- HuggingFace API token with access to the OpenAI-compatible inference endpoint (set as `HF_TOKEN`)

### Environment Variables

```bash
export HF_TOKEN=your-huggingface-token-here
# Optional: enable OpenAI GPT-5 models via the new dropdown
export OPENAI_API_KEY=your-openai-key-here
```

Or create `.env` next to `agent.py`:

```
HF_TOKEN=hf_xxx
OPENAI_API_KEY=sk-...
```

### Launch the Gradio app

```bash
# Run with uv (auto activates .venv/.venv)
uv run python app.py

# Or plain Python
python -m app

# Or use the helper restart script for local runs
./restart.sh
```

Visit http://localhost:7860 to start simulating.

### Run the FastMCP server by itself

```bash
# Expose MCP tools locally
uv run fire-rescue-mcp
# or explicitly
uv run python -m fire_rescue_mcp.mcp_server
```

Point your MCP-compatible client at the printed address; all tools described above will be available immediately.

---

## 📁 Project Structure

```
fire-rescue-mcp/
├── app.py                         # Gradio Blocks UI + timers + CSS
├── service.py                     # Simulation loop, advisor cadence, change tracking
├── simulation.py                  # Grid-based fire/units logic & win/lose checks
├── agent.py                       # Multi-stage HuggingFace LLM advisor + after-action writer
├── models.py                      # Dataclasses for world, units, fires, events
├── prompts.yaml                   # Stage prompts + model config
├── fire_rescue_mcp/
│   └── mcp_server.py              # FastMCP tool definitions (10 total)
├── fire_rescue_mcp_prd_v3.md      # Product requirements / success criteria
├── fire_rescue_mcp_dev_plan_v3.md # Development plan & milestones
├── pyproject.toml                 # Project + script definitions
├── requirements.txt               # Minimal dependency pin list
└── README.md                      # You are here
```

---

## 🛠️ Technologies Used

| Technology | Purpose |
|------------|---------|
| **Gradio 6** | Responsive Blocks UI, timers, and theming |
| **FastMCP** | Lightweight MCP server for exposing tools |
| **HuggingFace Inference (OpenAI-compatible)** | Runs the GPT-OSS 120B/20B and Llama-3.1 8B lineup without vendor lock-in |
| **OpenAI Python SDK** | Native client for the GPT-5.1 advisor option plus JSON-mode retries |
| **UV** | Dependency + virtualenv manager |
| **Python 3.10+ / dataclasses** | Core simulation + service logic |

---

## 🌍 Real-World Impact / Extensions

- **Live wildfire training feed** – Connect real incident telemetry so agencies can rehearse, monitor, or replay responses using the simulator as a digital twin.
- **Fire academy decision sandbox** – Turn the UI into a classroom “decision sand table” that logs cadet choices and feeds them back through the LLM for coaching.
- **Crisis-planning wargames** – Adapt the scenario generator for municipal tabletop drills, letting planners stress-test evacuations or inter-agency resource sharing.