FloodPulse: Motor Autônomo de Resiliência para Bacias Hidrográficas
Mitchell-Odili/floodpulse-nairobi
Orquestração de agentes para resiliência a inundações em cenários offline
Ver no GitHubUm servidor MCP que implementa um pipeline de agentes autônomos para navegação e resposta a crises de inundação na Bacia do Mbagathi, em Nairobi. Orquestra agentes especializados (Weather Gatherer, Vision Analyst) através do Google Agent Development Kit, com arquitetura edge-first e redundância offline para funcionar durante falhas de infraestrutura crítica.
Instalação
npx convez-ai Mitchell-Odili/floodpulse-nairobi1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Resposta autônoma a crises de inundação em áreas sem conectividade
- Navegação e coordenação multiagente durante falhas de infraestrutura
- Análise geoespacial e meteorológica integrada para previsão de desastres
Veredito

Projeto ambicioso e bem estruturado de orquestração de agentes para resiliência climática. Implementação madura com arquitetura em níveis (Gallery/Sandbox/Studio) e protocolos robustos de retry e persistência de estado, adequado para cenários críticos de infraestrutura.
README
A tradução para o português deste README ainda está na fila.
🌊 FloodPulse: Edge-to-Cloud Studio
Autonomous Multi-Agent Resilience for the Mbagathi River Basin
Mission: FloodPulse is an autonomous agentic pipeline designed to navigate the Mbagathi Basin during infrastructure failure. We are building the bridge between AI that assists and AI that acts, ensuring Nairobi's residents have a Digital Guardian when the grid goes dark.
View the full Specification: Read the PRD Spec
🏗 System Architecture: The "Studio" Pattern
We have transitioned from a multi-level sequential model to a unified Agentic Studio architecture.
- The Gallery (Level 0): A persistent registry for personas (Sarah, Juma, Kamau) and finalized mission assets.
- The Sandbox: Our experimental laboratory. This is where we stress-test new MCP tool-calling logic and authenticate secure connections via Application Default Credentials (ADC) before they graduate to the Studio.
- The Studio (Level 1 ): The core Agentic Synthesis engine. It utilizes the Google Agent Development Kit (ADK) to orchestrate specialized sub-agents (Weather Gatherer, Vision Analyst) through a sequential delegation loop, ensuring atomic state management and session-scoped reliability.
- Graph Orchestration (Level 2): Google Cloud Spanner backbone for persistent node-based navigation.
Visualizing the Workflow:
See how the Director manages the Sequential Agentic Loop in our Level 1 Architecture Visualization.

📂 Project Structure
floodpulse-nairobi/
├── docs/ # Architecture visuals, PRDs, & lab reports
├── levels/
│ ├── level_0/ # The Gallery: Identity & Asset Seeds
│ ├── level_1/ # The Studio: ADK Sequential Orchestration
│ └── level_2/ # Graph Orchestration: Spanner/GQL
├── sandbox/ # Experimental MCP rigs & diagnostic lab
├── tools/ # Shared spatial (map), weather & context tools
├── utils.py # Global Resilience Layer (Retry logic, shared helpers)
├── config.json # Global application settings
├── config.py # Configuration handler & validation
├── pyproject.toml # Dependency management (uv)
├── uv.lock # Deterministic lockfile
└── __init__.py # Package namespace initialization
📊 Evolutionary Roadmap
| Phase | Milestone | Status |
|---|---|---|
| Level 0 | Identity Factory: Parametric persona generation | ✅ Done |
| Sandbox | MCP Lab: Secure Vision/Tool Diagnostics | ✅ Done |
| Level 1 | The Studio: Agentic Synthesis & Telemetry Integration | ✅ Done |
| Level 2 | Graph Orchestration: Spanner/GQL Navigation | 🟡 Ongoing |
| Edge | Android 17 Parity: Local Gemma 4 inference | 🔜 Planned |
🛡️ Resilience & State Protocol
- Resilience Layer (
utils.py): We use@http/genai_retrydecorators across all API-bound tools (Maps, Weather, GenAI). They utilizes exponential backoff with jitter to gracefully recover from429 (Resource Exhausted)and503 (Unavailable) errors. - Context-Setter Pattern: The Director agent uses the
update_mission_contexttool to persist mission parameters (Name, Lat, Lon) intotool_context.session.state. This ensures that downstream agents have reliable access to validated mission data. -Asset Caching: To preserve daily API quotas, all map and terrain assets are checked against the local/assets/directory before triggering remote API calls.
⚙️ Setup & Execution
- Install Dependencies:
uv sync - Environment Variables: Create a
.envfile in the project root:
# API Keys (For Sandbox / Prototyping)
GEMINI_API_KEY=
MAPS_API_KEY=
OPENWEATHER_API_KEY=
# ADC / Vertex AI (For Production Studio)
USE_VERTEX_AI=true
PROJECT_ID=your-project-id
LOCATION=us-central1
- Authentication Protocol
The system supports two execution modes via config.py:
- Sandbox Mode (
USE_VERTEX_AI=false): Uses standard API keys. Ideal for rapid iteration, testing, and debugging. - Studio Production Mode (
USE_VERTEX_AI=true): Uses Application Default Credentials (ADC). This leverages your project's IAM identity for secure, enterprise-grade access.- Note: Ensure you have authenticated locally via
gcloud auth application-default loginbefore running in Studio mode.
- Note: Ensure you have authenticated locally via
- Run Missions: Execute from the root directory using the module flag:
uv run python -m levels.level_1.agent
adk web levels/level_1
🎯 Technical Validation: "The Mbagathi Truth"
- Baseline: Validated spatial reasoning for topographical analysis (
Gemma 4 (31B),Gemini-2.5-Flash,Gemini-3.5-Flash). - MCP Diagnostics: Validated tool-calling reliability via the MCP Inspector, ensuring our agents can "see" map assets locally even when cloud-disconnected.
- Safe Ridge Logic: The model autonomously identifies high-ground zones based on spectral terrain analysis (elevation vs. drainage).
- Graph Verification: Confirmed directed pathing from Sarah (Resident) at high-risk sump coordinates to Juma (Responder).
Status: ✅ Feasibility Confirmed. Our hybrid Edge-to-Cloud Studio pattern provides the necessary spatial intuition for urban flood navigation.
🧠 Gemma 4
We conducted a zero-shot analysis using Gemma 4 (31B) on high-resolution satellite imagery to validate:.
- River Path: Successfully identified the riparian corridor despite urban canopy cover.
- Critical Nodes: Pinpointed three high-risk intersections:
- Lang'ata Road/ICC Crossing: Identified as a primary arterial bottleneck.
- South B/C Border: Identified as a "low-water" neighborhood split-point.
- Lower Basin Sumps: Corrected identified as high-risk vehicle entrapment zones.
- Safe Ridge Logic: The model autonomously identified the South B Plateau as a primary evacuation zone based on spectral terrain analysis (elevation vs. drainage).
Status: ✅ Feasibility Confirmed. The model demonstrates the required spatial intuition for urban flood navigation.
🛠️ The Tech Stack: The Path to Production
We leverage a hybrid stack that moves from rapid AI prototyping to high-scale cloud infrastructure.
| Environment | Purpose | Core Technologies |
|---|---|---|
| AI Studio | Prototyping | Gemma 4 31B (Multimodal Reasoning) |
| Sandbox | MCP Validation | FastMCP, Inspector, ADC Authentication |
| Vertex AI | Orchestration | Google ADK (SequentialAgent), Gemini 2.5/3.5 Flash, Gemini 3.1 Flash Image (Visual Asset Generation) |
| Google Cloud | Production Scale | Cloud Spanner Graph(Live/Seeded), FastAPI, Cloud Run, WKT (Well-Known Text) Spatial Modeling |