README.md

metadata

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

🌟 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 (optional but fastest)
• HuggingFace API token with access to the OpenAI-compatible inference endpoint (set as HF_TOKEN)

Environment Variables

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

# 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

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