InfraAlert

AI-powered multi-agent system for infrastructure issue reporting and response coordination in Nigeria.

Overview

InfraAlert uses advanced AI to transform citizen reports into coordinated responses. The system:

• Receives reports through multiple channels (web, mobile, voice)
• Analyzes using Vision API, Speech-to-Text, NLP, and Gemini AI
• Detects infrastructure issues with machine learning
• Prioritizes based on severity, urgency, and impact
• Coordinates real-time resource matching and dispatch
• Sends notifications via Africa's Talking SMS (cost-effective Nigerian coverage)

Live Services

All services are deployed on Google Cloud Run:

Service	URL	Purpose
Web Application	https://infraalert-webapp-wuqtulo2va-uc.a.run.app	Citizen-facing report submission and tracking
Report Webhook	https://report-webhook-wuqtulo2va-uc.a.run.app	Cloud Function for report intake
Orchestrator Agent	https://orchestrator-agent-wuqtulo2va-uc.a.run.app	Workflow coordinator
Issue Detection Agent	https://issue-detection-agent-wuqtulo2va-uc.a.run.app	Issue analysis and classification
Priority Analysis Agent	https://priority-analysis-agent-wuqtulo2va-uc.a.run.app	Priority scoring
Resource Coordination Agent	https://resource-coordination-agent-wuqtulo2va-uc.a.run.app	Team and equipment matching
Platform Integration Agent	https://platform-integration-agent-wuqtulo2va-uc.a.run.app	External integrations and notifications
MCP Server	https://mcp-server-wuqtulo2va-uc.a.run.app	Model Context Protocol tools

Architecture

The system consists of specialized agents:

• Orchestrator Agent: Central workflow coordinator that orchestrates the complete infrastructure issue workflow
• Issue Detection Agent: Analyzes and classifies infrastructure issues using Vision API, NLP, Speech-to-Text, and Gemini AI
• Priority Analysis Agent: Evaluates severity and urgency to determine priority scores
• Resource Coordination Agent: Matches and dispatches resources based on issue type and location
• Platform Integration Agent: Executes platform actions including notifications and external integrations
• MCP Server: Provides external system integration tools (SMS, ticketing, dashboard updates)

ADK Multi-Agent Implementation

InfraAlert uses Google ADK in a microservice-oriented architecture with HTTP-based coordination:

• Each specialized agent is deployed as its own Cloud Run service and exposes an ADK root_agent from its agent.py
• The orchestrator coordinates these services via HTTP calls to each agent's /task endpoint
• Shared workflow state (session_id, issue_id, priority scores, assignments) is stored in ADK session state using SessionKeys defined in agents/session_config.py
• Session IDs propagate across agents via HTTP headers (X-ADK-Session-Id) for distributed tracing
• The general ADK multi-agent patterns (coordinator + specialists, sequential workflows, shared state) are followed while preserving independent Cloud Run scaling

Prerequisites

• Python 3.12+ (3.11+ also supported)
• uv package manager (install)
• gcloud CLI (Google Cloud SDK) - install
• Docker Desktop (for local development)
• Google Cloud Account (for deployment)

Install uv

Recommended: Use the setup script (ensures persistence)

# Run the setup script (installs and configures PATH)
./scripts/setup-uv.sh

Manual installation:

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip (less recommended)
pip install uv

Ensure persistence:

After installation, uv should be automatically added to your PATH. If not available in new terminals:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/.cargo/bin:$PATH"

# Then reload your shell
source ~/.bashrc  # or source ~/.zshrc

Verify installation:

# Quick check
make verify-uv

# Or manually
uv --version

Install gcloud CLI

Recommended: Use the setup script (ensures persistence)

# Run the setup script (installs latest version and configures PATH)
./scripts/setup-gcloud.sh

# Or via Makefile
make setup-gcloud

Manual installation:

# Linux/macOS
curl https://sdk.cloud.google.com | bash

# macOS (via Homebrew)
brew install --cask google-cloud-sdk

# Windows
# Download installer: https://cloud.google.com/sdk/docs/install

Ensure persistence:

After installation, gcloud should be automatically added to your PATH. If not available in new terminals:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$HOME/google-cloud-sdk/bin:$PATH"

# Enable completion (optional but recommended)
source "$HOME/google-cloud-sdk/path.bash.inc"  # or path.zsh.inc
source "$HOME/google-cloud-sdk/completion.bash.inc"  # or completion.zsh.inc

# Then reload your shell
source ~/.bashrc  # or source ~/.zshrc

Initialize gcloud:

# Authenticate
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Update to latest version
gcloud components update

Verify installation:

# Quick check
make verify-gcloud

# Or manually
gcloud --version
gcloud config get-value project

Install all tools at once:

# Install both uv and gcloud CLI
make setup-tools

Getting Started

1. Clone and Setup

git clone <repository-url>
cd InfraAlert

# Install and configure all required tools (uv + gcloud)
make setup-tools

# Or install individually
make setup-uv      # Install uv package manager
make setup-gcloud  # Install gcloud CLI

Environment Setup

Important: .env files are gitignored for security. You need to create them from the example files.

Run the setup script to create .env files from templates:

./scripts/setup-env.sh

Or manually copy the example files:

# Root .env file (used by most agents)
cp .env.example .env

# Agent-specific .env files (optional, agents fall back to root .env)
cp agents/issue_detection/.env.example agents/issue_detection/.env
cp agents/resource_coordination/.env.example agents/resource_coordination/.env

Required Environment Variables:

• GEMINI_API_KEY - Your Google Gemini API key (required for all agents)
• PROJECT_ID or GOOGLE_CLOUD_PROJECT - Your GCP project ID
• Other GCP credentials as needed (service accounts, buckets, etc.)

Optional - Africa's Talking (SMS Notifications):

• AFRICASTALKING_USERNAME - Your Africa's Talking username (or sandbox for testing)
• AFRICASTALKING_API_KEY - Your Africa's Talking API key
• AFRICASTALKING_SENDER_ID - Custom sender ID (optional, default: "InfraAlert")

Note: Africa's Talking is optional. Without it, the system runs in "mock mode" (no actual SMS sent). See docs/africastalking-setup.md for complete setup instructions.

Edit the .env files and add your actual credentials. Never commit .env files to git!

2. Install Dependencies

# Install all dependencies (production + development)
make install-dev

# Or manually
uv pip install -r requirements.txt
uv pip install -r requirements-test.txt

3. Verify Setup

# Run tests
make test

# Run linting
make lint

# Run both (recommended before committing)
make check

4. Start Local Development

# Start all services via Docker Compose
docker-compose up

# Or run individual agents (see agent-specific READMEs)
cd agents/issue_detection
python app.py

5. Optional: Setup SMS Notifications (Africa's Talking)

Africa's Talking provides cost-effective SMS notifications for InfraAlert (40-90% cheaper than alternatives).

# Quick setup (creates secrets in Secret Manager)
./scripts/setup-africastalking.ps1  # Windows PowerShell
# or
./scripts/setup-africastalking.sh   # Linux/Mac/WSL

# For detailed setup instructions, see:
# docs/africastalking-setup.md

Benefits:

• 💰 Cost-effective: ~$0.003-0.005 per SMS to Nigeria (vs $0.035-0.09 with Twilio)
• 🇳🇬 Better coverage: Local presence in Nigeria with excellent deliverability
• 🆓 Free sandbox: Test for free before going live

Not required: System works without SMS (notifications disabled in mock mode).

6. Quick Commands

make help          # Show all available commands
make install       # Install production dependencies only
make install-dev   # Install all dependencies
make lint          # Check code quality
make lint-fix      # Auto-fix linting issues
make test          # Run test suite
make check         # Run lint + tests
make clean         # Remove caches and temporary files

Build & Deployment

Local Development

Start all services with hot-reload:

# Use development override for auto-reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Or via Makefile
make docker-up

Build all Docker images locally:

make build-all

Build single service:

make build-service SERVICE=issue-detection
make build-service SERVICE=orchestrator

Deploy to Cloud Run

Deploy all services:

make deploy-all

Deploy single service:

make deploy-service SERVICE=priority-analysis

Test deployed service:

# Test health and readiness endpoints
./scripts/test-service.sh issue-detection-agent

# Or via Makefile
make test-service SERVICE=issue-detection-agent

Configuration Management

Validate build config:

make validate-config  # Validate main cloudbuild.yaml
./scripts/validate-all-builds.sh  # Validate all cloudbuild files

View available make commands:

make help

Quick development workflow:

# 1. Make changes
# 2. Run quality checks
make check

# 3. Test locally
make docker-up

# 4. Build image
make build-service SERVICE=issue-detection

# 5. Deploy (when ready)
make deploy-service SERVICE=issue-detection

For detailed build and deployment documentation, see docs/build-deploy.md.

Cost Management

Monitoring Costs

Track your Google Cloud costs to stay within budget:

./scripts/setup-cost-monitoring.sh

Current Optimization Status

All services are configured for cost-efficient operation:

• ✓ Scale to zero when not in use (min-instances=0)
• ✓ Optimized CPU and memory allocations
• ✓ Automatic scaling based on demand

Development

Package Management with uv

This project uses uv for fast, reliable package management:

# Install packages (replaces: pip install)
uv pip install <package>

# Install from requirements.txt
uv pip install -r requirements.txt

# Install in development mode
uv pip install -e .

# List installed packages
uv pip list

Code Quality

make lint          # Check code (Ruff + MyPy)
make lint-fix      # Auto-fix issues
make format        # Format code
make format-check  # Check formatting

Testing

make test          # Run all tests
make check         # Lint + test (use before committing)

Pre-commit Hooks

# Install pre-commit hooks
pre-commit install

# Run manually
make pre-commit

Tools Used:

• Ruff - Linting and formatting
• MyPy - Type checking
• Pytest - Testing
• uv - Package management

CI/CD

Automated builds and deployments via:

• Cloud Build for image building and deployment
• Cloud Run for hosting services
• Artifact Registry for image storage

Test locally before pushing:

make test-cloudbuild

Deploy manually:

gcloud builds submit --config=cloudbuild.yaml --substitutions=_TAG=$(git rev-parse --short HEAD)

Documentation

Core Documentation

• AGENTS.md - Agent development and deployment guidelines
• docs/build-deploy.md - Build and deployment guide with troubleshooting
• Ora Artifacts - Organized Ora-generated reports and guides by phase

Setup Guides

Tech Stack

• Platform: Google Cloud Platform
• AI/ML: Google Generative AI (Gemini), Vision API, Speech-to-Text, Natural Language API
• Framework: Google ADK (Agent Development Kit)
• Databases: Firestore, BigQuery
• Storage: Cloud Storage
• Compute: Cloud Run
• Messaging: Pub/Sub
• Monitoring: Cloud Monitoring, Cloud Logging
• SMS Provider: Africa's Talking (optional, for cost-effective Nigerian SMS)
• Package Manager: uv (fast, reliable Python package management)

Project Structure

InfraAlert/
├── .cloudbuild/                # Build configuration and shared scripts
│   ├── templates/              # Shared Cloud Build templates
│   └── scripts/                # Shared build and deployment scripts
├── agents/
│   ├── orchestrator/           # Orchestrator agent (workflow coordinator)
│   ├── issue_detection/        # Issue detection agent
│   ├── priority_analysis/      # Priority analysis agent
│   ├── resource_coordination/  # Resource coordination agent
│   ├── platform_integration/   # Platform integration agent
│   ├── policy_rag/             # Policy RAG agent
│   ├── session_config.py       # Shared session state configuration
│   └── observability.py        # Observability and logging utilities
├── webapp/                     # Web application (Flask backend + React frontend)
│   ├── app.py                  # Flask server
│   ├── frontend/               # React/Vite frontend
│   └── static/                 # Static assets
├── mcp_server/                 # MCP server implementation (observability tools)
├── bigquery/                   # BigQuery schemas
├── config/                     # Configuration files
├── docs/                       # Documentation
│   └── build-deploy.md         # Build and deployment guide
├── scripts/                    # Utility scripts (setup, deployment, testing)
├── terraform/                  # Infrastructure as Code
├── monitoring/                 # Monitoring and alerting configs
├── tools/                      # Utility tools
├── functions/                  # Cloud Functions
├── deploy/                     # Deployment configurations
├── tests/                      # Test suite
├── cloudbuild.yaml             # Cloud Build configuration
├── docker-compose.yml          # Local development setup
├── docker-compose.dev.yml      # Development overrides (hot-reload)
├── Dockerfile                  # Root Dockerfile
├── Makefile                    # Development commands
└── pyproject.toml              # Python project configuration

License

See LICENSE file for details.