🚨 CrisisSim: AI-Powered Emergency Response Simulation

Advanced multi-agent simulation platform combining Mesa ABM with LLM-driven reasoning strategies for optimized crisis response planning

🎯 Overview

CrisisSim is a comprehensive emergency response simulation that models crisis scenarios with intelligent AI agents. The platform integrates multiple Large Language Model (LLM) reasoning strategies including ReAct, Reflexion, Plan-Execute, Chain-of-Thought, and Tree-of-Thought to optimize rescue operations, resource allocation, and emergency response coordination.

✨ Key Features

🤖 Multi-Strategy AI Planning

• ReAct: Reasoning and Acting in iterative cycles
• Reflexion: Self-reflection and memory-driven improvements
• Plan-Execute: Hierarchical planning with tactical execution
• Chain-of-Thought (CoT): Sequential reasoning chains
• Tree-of-Thought (ToT): Branched reasoning exploration

🌍 Realistic Crisis Environment

• Dynamic Fire Spread: Realistic fire propagation mechanics
• Aftershock Events: Earthquake aftermath simulations
• Resource Constraints: Battery, water, and tool limitations
• Hospital Triage: FIFO and priority-based patient management
• Multi-Agent Coordination: Drones, medics, and trucks working together

📊 Comprehensive Evaluation Framework

• Performance Metrics: Rescue efficiency, response time, resource utilization
• Batch Evaluation: Multi-seed statistical analysis
• Visualization: Real-time web UI and detailed performance plots
• Comparative Analysis: Strategy performance across different scenarios

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/aliyanz85/crisis-sim.git
cd crisis-sim

# Setup environment
python -m venv .venv && source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Basic Usage

🎮 Interactive Web Interface

python server.py
# Open http://127.0.0.1:8522 in your browser

🔄 Command Line Simulation

# Quick demo with mock LLM (no API keys required)
python main.py --map configs/map_small.yaml --provider mock --strategy react --seed 42 --ticks 150

# Advanced run with Groq API
export LLM_PROVIDER=groq
export GROQ_API_KEY=your_api_key_here
python main.py --map configs/map_medium.yaml --provider groq --strategy plan_execute --ticks 200

📈 Batch Evaluation & Analysis

# Run comprehensive evaluation
python eval/harness.py --n_seeds 5 --maps configs/map_small.yaml configs/map_medium.yaml configs/map_hard.yaml --strategies react reflexion plan_execute --ticks 200

# Generate performance plots
python eval/plots.py --summary results/agg/summary.csv --out results/plots

🏗️ Architecture

CrisisSim/
├── 🧠 reasoning/          # LLM strategy implementations
│   ├── react.py          # ReAct reasoning loops
│   ├── reflexion.py      # Memory-driven self-improvement
│   ├── plan_execute.py   # Hierarchical planning
│   ├── cot.py           # Chain-of-thought reasoning
│   └── tot.py           # Tree-of-thought exploration
├── 🌍 env/               # Simulation environment
│   ├── world.py         # Mesa model & crisis dynamics
│   ├── agents.py        # Agent behaviors (drones, medics, trucks)
│   ├── dynamics.py      # Fire spread, aftershocks
│   └── sensors.py       # State observation system
├── 🛠️ tools/            # Agent capabilities
│   ├── hospital.py      # Medical facility management
│   ├── resources.py     # Resource tracking & constraints
│   └── routing.py       # Pathfinding & navigation
├── 📊 eval/              # Performance evaluation
│   ├── harness.py       # Batch experiment runner
│   └── plots.py         # Visualization generation
└── 📋 configs/           # Scenario configurations
    ├── map_small.yaml   # Training scenarios
    ├── map_medium.yaml  # Standard benchmarks
    └── map_hard.yaml    # Challenge scenarios

🎯 Supported Scenarios

📊 Performance Metrics

• 🏥 Rescue Efficiency: Survivors saved vs. casualties
• ⏱️ Response Time: Average rescue completion time
• 🔋 Resource Utilization: Energy and tool consumption
• 🚒 Crisis Mitigation: Fires extinguished, roads cleared
• 🏥 Hospital Management: Triage efficiency, overflow events
• 🤖 AI Performance: JSON validity, replanning frequency

🔌 LLM Provider Support

🎨 Visualization Features

Real-time Web Interface

• 🗺️ Interactive crisis map visualization
• 📊 Live performance dashboards
• 📈 Real-time metrics tracking
• 🎮 Manual control override capabilities

Performance Analytics

• 📊 Strategy comparison charts
• 📈 Rescue efficiency trends
• 🎯 Resource utilization heatmaps
• 📉 Statistical significance testing

🛡️ Safety & Ethics

This simulation is designed for:

• 📚 Research: Emergency response optimization
• 🎓 Education: Crisis management training
• 🏢 Planning: Resource allocation strategies
• 🧪 Development: AI reasoning system testing

🤝 Contributing

We welcome contributions! Areas of focus:

• 🧠 New LLM reasoning strategies
• 🌍 Additional crisis scenarios
• 📊 Advanced evaluation metrics
• 🎨 Visualization improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Mesa Project: Agent-based modeling framework
• OpenAI: LLM reasoning methodologies
• Crisis Response Community: Domain expertise and validation

Built with ❤️ for emergency response optimization and AI reasoning research