convez.ai
MCP ServerAutomaçãoAvançado
Mitchell-Odili

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 GitHub
InicialPluginScore · de 0 a 100

Um 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-nairobi

1 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

Estrelas
0
Forks
1
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

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. FloodPulse Studio Workflow


📂 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

PhaseMilestoneStatus
Level 0Identity Factory: Parametric persona generation✅ Done
SandboxMCP Lab: Secure Vision/Tool Diagnostics✅ Done
Level 1The Studio: Agentic Synthesis & Telemetry Integration✅ Done
Level 2Graph Orchestration: Spanner/GQL Navigation🟡 Ongoing
EdgeAndroid 17 Parity: Local Gemma 4 inference🔜 Planned

🛡️ Resilience & State Protocol

  • Resilience Layer (utils.py): We use @http/genai_retry decorators across all API-bound tools (Maps, Weather, GenAI). They utilizes exponential backoff with jitter to gracefully recover from 429 (Resource Exhausted) and 503 (Unavailable) errors.
  • Context-Setter Pattern: The Director agent uses the update_mission_context tool to persist mission parameters (Name, Lat, Lon) into tool_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

  1. Install Dependencies: uv sync
  2. Environment Variables: Create a .env file 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
  1. 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 login before running in Studio mode.
  1. 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:
    1. Lang'ata Road/ICC Crossing: Identified as a primary arterial bottleneck.
    2. South B/C Border: Identified as a "low-water" neighborhood split-point.
    3. 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.

EnvironmentPurposeCore Technologies
AI StudioPrototypingGemma 4 31B (Multimodal Reasoning)
SandboxMCP ValidationFastMCP, Inspector, ADC Authentication
Vertex AIOrchestrationGoogle ADK (SequentialAgent), Gemini 2.5/3.5 Flash, Gemini 3.1 Flash Image (Visual Asset Generation)
Google CloudProduction ScaleCloud Spanner Graph(Live/Seeded), FastAPI, Cloud Run, WKT (Well-Known Text) Spatial Modeling

Ver o original no GitHub

Bom para

Relacionados