Content
# 🔥 MASs Firefighter – Multi-Agent Wildfire Decision-Support Platform
> This repository contains a prototype web platform for wildfire response decision support.
> It combines a map-based operational workflow, **React**, **FastAPI**, **PostgreSQL**, an optional **MCP server**, and a **LangGraph multi-agent system** for interpreting incident updates and producing structured operational guidance.
## 📚 Table of Contents
- [🔥 MASs Firefighter – Multi-Agent Wildfire Decision-Support Platform](#-mass-firefighter--multi-agent-wildfire-decision-support-platform)
- [📚 Table of Contents](#-table-of-contents)
- [🚀 Overview](#-overview)
- [🏗️ Architecture](#️-architecture)
- [⚙️ Technologies](#️-technologies)
- [🧩 Project Structure](#-project-structure)
- [🧭 How to Run (Manual Setup)](#-how-to-run-manual-setup)
- [🔍 Healthcheck](#-healthcheck)
- [🧠 Multi-Agent Workflow](#-multi-agent-workflow)
- [📸 Screenshots](#-screenshots)
- [🧰 Useful Commands](#-useful-commands)
- [🔒 Security Checklist](#-security-checklist)
- [👤 Authors](#-authors)
## 🚀 Overview
**MASs Firefighter** is a research prototype that explores how a human operator can build a structured wildfire incident context before asking an AI-based system for operational support.
The system includes:
- Interactive operational map built with **React + MapLibre GL**
- Backend API implemented with **FastAPI**
- Operational database using **PostgreSQL**
- Database migrations with **Alembic**
- Multi-agent decision-support workflow built with **LangGraph**
- Entity resolution against selected stations, teams, resources, and locations
- Optional **Model Context Protocol (MCP)** server for auxiliary tools such as weather lookup
Instead of relying only on free-text chat, the platform lets the user define the incident area, fire point, stations, teams, resources, and support entities first. That confirmed context is then sent to the multi-agent system together with the user's message.
## 🏗️ Architecture
The current prototype is organized into four main layers:
| Layer | Responsibility |
|-------|----------------|
| **Frontend** | Provides the map, workflow panels, operational forms, context review, and chat interface |
| **Backend** | Serves locations and operational data, validates requests, and triggers the multi-agent runner |
| **Database** | Stores locations, geometries, stations, teams, resources, and assignments |
| **Multi-Agent System** | Normalizes messages, resolves entities, coordinates agents, and synthesizes the final answer |
| **MCP Server** | Optional extension layer for external tools such as weather data |
**Main flow:**
```text
User
|
v
React + MapLibre Frontend
|
v
FastAPI Backend
|
+--> PostgreSQL Operational Database
|
v
LangGraph Multi-Agent Pipeline
|
v
Final response shown in the operational chat
```
## ⚙️ Technologies
| Layer | Technology | Description |
|-------|------------|-------------|
| Frontend | **React + TypeScript + Vite** | Web interface and operational workflow |
| Map | **MapLibre GL** | Interactive map rendering |
| Backend | **FastAPI** | REST API for frontend and incident chat |
| Database | **PostgreSQL** | Operational data persistence |
| ORM / Migrations | **SQLAlchemy + Alembic** | Database models and schema evolution |
| Multi-Agent Runtime | **LangGraph + LangChain** | Agent graph orchestration |
| Validation | **Pydantic** | Structured data validation |
| MCP Tools | **Python MCP SDK** | Optional external tool server |
| Package Management | **uv + npm** | Python and frontend dependency management |
## 🧩 Project Structure
```text
MASs-firefighter/
|-- backend/ # FastAPI API used by the frontend
| |-- src/backend_api/
| `-- pyproject.toml
|
|-- frontend/ # React + Vite operational interface
| |-- src/
| |-- public/
| `-- package.json
|
|-- mcp-server/ # Optional MCP server with auxiliary tools
| |-- app/
| `-- server.py
|
|-- multi-agent/ # LangGraph multi-agent system and database setup
| |-- app/
| |-- alembic/
| |-- data/
| |-- tests/
| `-- docker-compose.yml
|
|-- docs/
`-- README.md
```
## 🧭 How to Run (Manual Setup)
### 1. Prepare the multi-agent service and database
```bash
cd multi-agent
cp .env.example .env
cp app/config/.env.example app/config/.env
uv sync
docker compose up -d
uv run alembic upgrade head
uv run python -m app.db.operational.seed
```
This starts PostgreSQL, applies migrations, and seeds the operational database.
### 2. Start the backend API
```bash
cd ../backend
cp .env.example .env
uv sync
uv run uvicorn src.backend_api.main:app --reload
```
Backend URL:
```text
http://127.0.0.1:8000
```
### 3. Start the MCP server
```bash
cd ../mcp-server
uv sync
uv run python server.py
```
Default MCP endpoint:
```text
http://127.0.0.1:8001/mcp
```
### 4. Start the frontend
```bash
cd ../frontend
npm install
npm run dev
```
Frontend URL:
```text
http://localhost:5173
```
## 🔍 Healthcheck
- Endpoint: `GET /health`
- Expected purpose: verify that the FastAPI backend is running
Example:
```bash
curl -i http://127.0.0.1:8000/health
```
Main API endpoints:
| Method | Endpoint | Purpose |
|--------|----------|---------|
| `GET` | `/health` | Backend healthcheck |
| `GET` | `/api/locations/map` | GeoJSON locations for the map |
| `GET` | `/api/locations/unmapped` | Locations without geometry |
| `POST` | `/api/locations/{location_id}/geometry` | Save location geometry |
| `GET` | `/api/operational/stations/compositions` | Stations, teams, and resources |
| `POST` | `/api/incident/chat` | Run the incident chat workflow |
## 🧠 Multi-Agent Workflow
The multi-agent system receives two inputs from the backend:
- The user's natural-language message
- The structured incident context confirmed in the frontend
The workflow includes:
| Step | Description |
|------|-------------|
| **Normalization** | Converts the user's message into a structured internal representation |
| **Entity Resolution** | Links mentioned teams, resources, stations, and locations to the selected context |
| **Coordination** | Builds an execution plan and decides which agents should run |
| **Specialized Agents** | Runs situation, resource, risk, and decision-support agents |
| **Synthesis** | Produces the final operational response shown in the chat |
Current specialized agents include:
- Situation assessment agent
- Resource analysis agent
- Risk analysis agent
- Decision-support agent
- Final synthesis agent
## 📸 Screenshots
| Map Layout | Operational Chat |
|--------------|------------------|
|  |  |
| Node Graph | MCP Server |
|----------------|------------------|
|  |  |
## 🧰 Useful Commands
```bash
# Start PostgreSQL from the multi-agent module
cd multi-agent
docker compose up -d
# Apply database migrations
uv run alembic upgrade head
# Seed operational data
uv run python -m app.db.operational.seed
# Run multi-agent tests
uv run pytest
# Start the backend API
cd ../backend
uv run uvicorn src.backend_api.main:app --reload
# Start the frontend
cd ../frontend
npm run dev
# Build the frontend
npm run build
# Run frontend linting
npm run lint
```
## 🔒 Security Checklist
- `.env` files are ignored and should not be committed
- Example environment files are provided for local setup
- PostgreSQL runs locally through Docker Compose by default
- The frontend only communicates with the configured backend API
- API CORS is limited to the local development frontend origins
- Do not store real emergency, personal, or sensitive operational data in the repository
- This is a prototype and must not be used as a real emergency response system
## 👤 Authors
- **Daniel Serrano Segura**
- **Eduardo Peralta**
