MarwanEA/reservoir-flood-agents

Six-agent AI decision-support pipeline for reservoir flood operations, evaluated against the 2026 Oued El Makhazine dam crisis, Morocco. Companion code for our CAISN'26 paper. # reservoir-flood-agents Code for "A Multi-Agent AI Decision-Support Framework for Reservoir Flood Operations: The 2026 Oued El Makhazine Crisis, Morocco," submitted to CAISN 2026. The paper proposes a six-agent pipeline for reservoir flood-release decisions and evaluates it against the January-February 2026 crisis at the Oued El Makhazine dam in Morocco's Loukkos basin. This repository has the pipeline code, the archived weather data it runs on, three standalone sensitivity checks, and the pipeline's own output for the case-study window. ## What's here - `agents/` - the six agents (perception and data QA, inflow forecasting, reservoir routing, downstream risk, regulatory constraints, decision synthesis) and shared config. Agents 1-5 are plain rule-based Python; only Agent 6 calls an LLM. - `orchestrator.py`, `run_case_study.py` - LangGraph orchestration and the script that runs the full case study and writes `outputs/run_log.json`. - `evaluate_vs_dgm.py` - builds the comparison between the pipeline's risk flags and the regional weather-alert timeline (Figure 2 in the paper). - `backfill_agent6.py` - regenerates Agent 6's rationale text without re-running Agents 1-5. - `analysis/` - three standalone checks, kept separate from the evaluated pipeline: a basin-average-rainfall forcing check, a rate-of-rise threshold sensitivity check, and a single-shot-vs-agentic prompt comparison. - `data/public/` - archived GFS forecast and ERA5-based observed precipitation at the dam's coordinates, pulled from Open-Meteo, and the script that fetched them. - `data/reference/` - dam parameters, the regional weather-alert bulletin timeline, and a dated timeline of confirmed crisis milestones. - `outputs/` - the pipeline's own log for the case-study run and the comparison figure. ## Running it Needs Python 3.11 or newer (developed on 3.13) and, for Agent 6 only, a Claude Code subscription. Agents 1-5 need neither an API key nor Claude Code. ``` pip install -r requirements.txt p …