SIAGA: Swarm Intelligence Agent for Geo-Adaptive rescue

An AI-powered autonomous drone swarm simulation for post-disaster search-and-rescue in Indonesia. First Responder of the Future: Decentralised Swarm Intelligence.

The Problem

When earthquakes or tsunamis hit Indonesia (Ring of Fire, ~17,000 islands), cell towers go down in the critical first 72 hours. Cloud-dependent AI systems become useless. Rescue teams operate blind. People die waiting.

Our Solution

An AI command agent (Google Gemini 2.0 Flash) orchestrates a fleet of 5 autonomous drones through the Model Context Protocol (MCP). The drones self-organize using leader election, communicate peer-to-peer within radio range, scan for survivors using simulated thermal sensors, and deliver supplies — all without cloud connectivity.

The simulation renders as a 3D isometric view using Pygame, with a continuous heightmap mesh — mountains rise, flood zones sink, and drones hover with real-time animations. The swarm features a self-healing mesh network with automatic leader failover and isolation recovery.

Architecture

┌─────────────────────────────────────────┐
│  Layer 1: AI Command Agent              │
│  Google Gemini 2.0 Flash + LangChain    │
│  Issues strategic goals via MCP         │
│  Chain-of-thought reasoning every step  │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio/JSON-RPC)
┌──────────────▼──────────────────────────┐
│  Layer 2: MCP Server (FastMCP)          │
│  ~24 tools across 5 categories          │
│  Fleet, Navigation, Sensors, Comms,     │
│  State — the ONLY agent↔sim interface   │
└──────────────┬──────────────────────────┘
               │ Python function calls
┌──────────────▼──────────────────────────┐
│  Layer 3: Simulation Engine             │
│  20×20 grid, 7 terrain types,           │
│  thermal sensors, fog of war,           │
│  3D isometric Pygame renderer           │
└─────────────────────────────────────────┘

Key Features

• Decentralized leader election — Drones score on battery, sensor health, uptime. Automatic failover with zero downtime.
• Self-healing mesh network — Drones detect isolation, auto-navigate back to swarm centroid, and re-elect leaders on failure.
• Cohesive swarm movement — Fan formation sweep that keeps drones within comm range while maximizing terrain coverage.
• Drone roles — Scout (explore), Rescue (deliver supplies), Relay (extend comm range). Dynamically reassigned by the leader.
• Thermal sensor simulation — Realistic heat detection with terrain attenuation, Gaussian noise, and 8% false positives. Agent must confirm ambiguous readings.
• Fog of war — Map starts hidden. Each scan reveals nearby cells. Agent must reason about coverage gaps.
• Comm range limits — Drones communicate within 5 cells only. Relay drones extend the mesh.
• 3D isometric visualization — Continuous heightmap mesh with sub-tile resolution, elevation-based terrain, drone hover animations, urgency-pulsing survivors, interactive camera (pan/zoom/rotate).
• Video recording — Record the simulation or mission replay to MP4 video (requires ffmpeg).
• Mission replay — Replay completed missions step-by-step from saved log files.
• Indonesian disaster scenarios — Palu earthquake + tsunami, Semeru eruption, Jakarta monsoon flooding.

SDG Alignment

• SDG 9 (Industry, Innovation, Infrastructure) — Target 9.1 & 9.5: resilient infrastructure and enhanced research
• SDG 3 (Good Health and Well-being) — Target 3.d: early warning and risk reduction for national health emergencies

Prerequisites

• Python 3.11+
• Google AI Studio API key (free tier) — get one at aistudio.google.com
• ffmpeg (optional) — required only for video recording

Setup

1. Enter the project directory

cd swarm-rescue

2. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate     # macOS/Linux
# .venv\Scripts\activate      # Windows

3. Install dependencies

pip install -r requirements.txt

4. Set your Gemini API key

Create a .env file in the project root (one level above swarm-rescue/):

echo "GEMINI_API_KEY=your-api-key-here" > ../.env

Or export it directly:

export GEMINI_API_KEY="your-api-key-here"

Google AI Studio setup:

1. Go to aistudio.google.com
2. Click Get API Key → Create API Key
3. Copy the key — no billing or project setup required
4. The model used is Gemini 2.0 Flash (gemini-2.0-flash)

How to Run

Full AI Mission (main.py)

Run the AI agent that orchestrates the drone swarm through MCP:

python main.py

The agent will discover the fleet, elect a leader, assign roles, scan terrain, and rescue survivors — producing a step-by-step mission log in mission_logs/.

All main.py flags

Flag	Default	Description
--scenario SCENARIO	palu_earthquake	Disaster scenario to simulate
--drones N	5	Number of drones in the fleet
--survivors N	8	Number of survivors to place
--sim-only	off	Run the 3D simulation viewer only (no AI agent)
--no-render	off	Run AI mission without the Pygame window
--max-turns N	20	Maximum agent turns before stopping
--record	off	Record the simulation to MP4 video (requires ffmpeg)

Available scenarios

Scenario ID	Name	Description
palu_earthquake	Palu Earthquake & Tsunami (Sulawesi)	Flooded east coast, rubble city centre, coastal survivors
semeru_eruption	Mount Semeru Eruption (East Java)	Volcanic ash zones, near-zero visibility, attenuated thermal
jakarta_flood	Jakarta Monsoon Flooding	Urban flooding, rooftop survivors, cold water masks heat
simple_test	Simple Detection Test (10x10)	Small 10x10 grid with 3 survivors for quick testing

Examples

# Default scenario (Palu earthquake) with full AI + 3D renderer
python main.py

# Specific scenario
python main.py --scenario semeru_eruption

# Custom fleet size and survivor count
python main.py --drones 3 --survivors 5

# More agent turns for larger maps
python main.py --max-turns 30

# AI mission without the Pygame window (headless)
python main.py --no-render

# 3D simulation viewer only (no AI agent)
python main.py --sim-only
python main.py --sim-only --scenario jakarta_flood

# Record the simulation to video
python main.py --sim-only --record
python main.py --record  # records during AI mission too

# Quick test scenario (auto-sets 3 drones, 3 survivors)
python main.py --scenario simple_test

Mission Replay (playback.py)

Replay a completed mission log visually, step by step:

python playback.py                              # most recent log
python playback.py path/to/mission.json         # specific log file
python playback.py --speed 2.0                  # 2x playback speed
python playback.py --record                     # record replay to MP4
python playback.py --record --speed 3.0         # fast recorded replay

All playback.py flags

Flag	Default	Description
log_file (positional)	most recent	Path to a mission log JSON file
--speed FLOAT	1.0	Playback speed multiplier (2.0 = twice as fast)
--log-dir DIR	mission_logs/	Directory to search for log files
--record	off	Record the replay to MP4 video (requires ffmpeg)

Playback controls

Key	Action
Space	Pause / resume
Right arrow	Step forward one turn
Left arrow	Step back one turn
+/-	Increase / decrease playback speed
WASD / Arrow keys	Pan camera
Mouse scroll	Zoom in / out
Right-click drag	Rotate camera
R	Reset camera
G	Toggle grid overlay
F9	Toggle video recording
Esc	Quit

MCP Server Standalone

For testing individual MCP tools:

python mcp_server.py

3D Viewer Controls

When the Pygame window is open (sim-only mode, AI mission, or playback):

Key	Action
Arrow keys / WASD	Pan camera
Mouse scroll	Zoom in / out
Right-click drag	Rotate camera
R	Reset camera
G	Toggle grid overlay
F9	Toggle video recording

Project Structure

swarm-rescue/
├── simulation/
│   ├── terrain.py          # 7 terrain types with elevation, move costs, thermal attenuation
│   ├── drone.py            # Drone class — battery, role, status, mesh network fields
│   ├── survivor.py         # Survivor spawning with terrain bias, urgency escalation
│   ├── world.py            # World state manager, tick system, self-healing mesh network
│   └── renderer.py         # IsometricRenderer — 3D heightmap mesh, video recording
├── sensors/
│   ├── thermal.py          # Thermal scanning, noise, classification, false positives
│   └── fog_of_war.py       # Visibility tracking, sector analysis
├── swarm/
│   ├── leader_election.py  # Weighted scoring, election, automatic failover
│   ├── message_bus.py      # Broadcast, direct messaging, relay forwarding
│   └── roles.py            # Scout/Rescue/Relay definitions, role suggestions
├── mcp_server.py           # FastMCP server — ~24 MCP tool definitions
├── agent.py                # LangChain + Gemini agent with CoT reasoning
├── playback.py             # Post-mission visual replay system
├── config.py               # All tunable constants
├── terrain_data/
│   └── sulawesi_earthquake.json  # 20×20 terrain map
├── mission_logs/           # Auto-generated mission logs (JSON)
├── main.py                 # Entry point — wires everything together
├── requirements.txt        # Python dependencies
└── README.md               # This file

Disaster Scenarios

Scenario	Terrain	Challenge
Palu Earthquake	Coastline + flood east, rubble center, jungle/mountain west	Tsunami debris, widespread flooding
Semeru Eruption	Volcanic ash zones, poor visibility	Ash blocks 70% of thermal signal
Jakarta Flood	Urban flooding, rooftop survivors	Cold water masks heat signatures

Deliverables (from Case Study)

1. The Orchestrator — AI agent managing 3-5 drones (agent.py)
2. MCP Server Implementation — FastMCP server exposing drone tools (mcp_server.py)
3. Mission Log — Step-by-step reasoning log (generated after each mission run in mission_logs/)

Tech Stack

Component	Technology
AI Model	Google Gemini 2.0 Flash (via AI Studio free tier)
Agent Framework	LangChain + LangGraph
MCP Server	FastMCP (Python)
Simulation	Pure Python (2D grid logic)
Visualization	Pygame (3D isometric renderer)
Video Recording	ffmpeg (pipe-based H.264 encoding)

Team

• Barru Adi Utomo
• Rafif Farras
• Azfa Radhiyya Hakim

---