ReliefAI — Post-Disaster Relief Orchestrator

ReliefAI is a multi-agent AI system that coordinates disaster relief operations in real time. It solves the fragmented coordination problem where volunteer schedules, supply tracking, and community communications are scattered across WhatsApp groups and spreadsheets. A single natural-language command dispatches a network of specialist AI agents — volunteer scheduler, supply chain manager, multilingual communications agent, shift coverage detector, and report generator — all coordinated by a central orchestrator running on Groq's Llama 3.3 70B. Built with FastAPI, async SQLite, and FastMCP tool servers, deployed on Google Cloud Run for a total infrastructure cost of $0.

Architecture

User / Dashboard
      │
      ▼
┌─────────────────────────────┐
│     Orchestrator Agent      │  ← Groq Llama 3.3 70B
│   (Primary Coordinator)     │
└────────────┬────────────────┘
             │ delegates to
   ┌─────────┼──────────┬──────────────┬──────────────┐
   ▼         ▼          ▼              ▼              ▼
Volunteer  Supply    Comms Agent   Shift Agent   Report Agent
  Agent    Agent    (Translations) (Gap Detect)  (Reports)
   └─────────┴──────────┴──────────────┴──────────────┘
                         │
              ┌──────────▼──────────────┐
              │     MCP Tool Server     │
              │  Calendar | Tasks |     │
              │  Notes | Supplies |     │
              │  Broadcasts             │
              └──────────┬──────────────┘
                         │
                ┌────────▼────────┐
                │   SQLite DB     │
                │  (8 tables)     │
                └─────────────────┘

Tech Stack

Prerequisites

• Python 3.11+
• Free Groq API key from console.groq.com
• Docker (for Cloud Run deployment only)
• Google Cloud account (for Cloud Run deployment only)

Local Development

1. Clone the repository

git clone YOUR_GITHUB_REPO_URL
cd reliefai

2. Get your free Groq API key

1. Go to https://console.groq.com
2. Sign up (no credit card needed — takes 30 seconds)
3. Navigate to API Keys → Create API Key
4. Copy the key (starts with gsk_)

3. Start the server

bash run_local.sh

The script will:

• Create a virtual environment
• Install all dependencies
• Prompt you to add your GROQ_API_KEY to .env
• Start the server at http://localhost:8000

4. Open in browser

5. Seed demo data

Open a new terminal (keep the server running):

source venv/bin/activate
python seed_demo.py

This creates the full Typhoon Carina scenario and runs 5 live AI commands.

6. Test the main endpoint

curl -X POST http://localhost:8000/disasters/1/command \
  -H "X-API-Key: reliefai-demo-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "Assess current situation and identify critical issues"}'

API Endpoints

Demo Walkthrough (5 commands)

Run these in order after seeding. All use POST /disasters/1/command with X-API-Key: reliefai-demo-key.

Command 1 — Situation Assessment

{"command": "Assess current situation and identify top 3 critical issues"}

Expected: Orchestrator calls supply_agent + shift_agent, flags water/baby food critical shortage and 3 cancelled shifts.

Command 2 — Shift Gap Recovery

{"command": "3 volunteers cancelled their shifts today. Find replacements immediately."}

Expected: shift_agent detects 3 open slots, volunteer_agent matches available volunteers by skill and schedules replacements.

Command 3 — Multilingual Broadcast

{"command": "Draft emergency broadcast in Filipino and English about Rizal High School evacuation center"}

Expected: comms_agent translates into 6 languages (EN/HI/TA/ID/TL/JA), enforces SMS character limits, saves broadcast.

Command 4 — Donor Report

{"command": "Generate a donor status report"}

Expected: report_agent aggregates all DB data and generates an impact-focused Markdown report.

Command 5 — Procurement Task

{"command": "Create procurement task for emergency water — 500L available, need 2000L"}

Expected: supply_agent flags critical shortage, creates procurement task with high priority in the DB.

Project Structure

reliefai/
│
├── agents/                    # AI agent layer
│   ├── __init__.py
│   ├── _groq_client.py        # Shared Groq API helper
│   ├── orchestrator.py        # Primary coordinator
│   ├── volunteer_agent.py     # Scheduling & assignments
│   ├── supply_agent.py        # Inventory & procurement
│   ├── comms_agent.py         # Multilingual broadcasts
│   ├── shift_agent.py         # Coverage gap detection
│   └── report_agent.py        # Report generation
│
├── database/                  # Data layer
│   ├── __init__.py            # Async engine + get_db
│   ├── models.py              # SQLAlchemy ORM (8 tables)
│   └── crud.py                # All async CRUD functions
│
├── mcp_server/                # MCP tool server
│   ├── __init__.py
│   └── tools.py               # FastMCP tool definitions
│
├── schemas/                   # Pydantic v2 schemas
│   ├── __init__.py
│   └── models.py              # Request + response models
│
├── static/                    # Frontend
│   └── index.html             # Single-file ops dashboard
│
├── main.py                    # FastAPI application
├── seed_demo.py               # Demo data seeder
├── run_local.sh               # One-command local setup
├── Dockerfile                 # Container definition
├── requirements.txt           # Python dependencies
├── .env.example               # Environment template
├── .gitignore
└── .dockerignore

GitHub Setup

git init
git add .
git commit -m "Initial commit — ReliefAI Post-Disaster Relief Orchestrator"
git branch -M main
git remote add origin YOUR_GITHUB_REPO_URL
git push -u origin main

Cloud Run Deployment

Step 1 — Authenticate and configure

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable run.googleapis.com artifactregistry.googleapis.com

Step 2 — Create artifact repository

gcloud artifacts repositories create reliefai \
  --repository-format=docker \
  --location=asia-southeast1

Step 3 — Build and push Docker image

docker build -t asia-southeast1-docker.pkg.dev/YOUR_PROJECT_ID/reliefai/app:latest .
docker push asia-southeast1-docker.pkg.dev/YOUR_PROJECT_ID/reliefai/app:latest

Step 4 — Deploy to Cloud Run

gcloud run deploy reliefai \
  --image asia-southeast1-docker.pkg.dev/YOUR_PROJECT_ID/reliefai/app:latest \
  --platform managed \
  --region asia-southeast1 \
  --allow-unauthenticated \
  --set-env-vars GROQ_API_KEY=your_groq_key_here,API_KEY=reliefai-demo-key \
  --memory 1Gi \
  --cpu 1 \
  --timeout 300

Step 5 — Seed demo data after deploy

Run this once after every deployment:

curl -X POST https://YOUR-CLOUD-RUN-URL.run.app/demo/seed \
  -H "X-API-Key: reliefai-demo-key"

Step 6 — Verify deployment

curl https://YOUR-CLOUD-RUN-URL.run.app/health

Important: SQLite database resets on every redeploy because it lives inside the container. Always run the seed command after deploying. For a production upgrade, migrate to Google Cloud Firestore (no schema management, scales automatically, persistent across deploys).

Environment Variables

License

MIT