likithkumarmv/LIRA

# LIRA — Autonomous Crisis Intelligence Network ## 🏆 Hackathon Evaluation Guide This section maps **every LIRA feature** directly to the hackathon judging criteria so evaluators can quickly assess the project at each round. ### ⏱️ Round 1 — Idea Validation & Architecture Review *(Hour 4–6)* #### ❓ What Problem Does LIRA Solve? **The gap:** When a disaster strikes (flood, cyclone, earthquake), relief coordination fails because: - Information is fragmented across WhatsApp, radio, and government portals - No single system knows *where* resources are, *who* is available, and *what* the public is reporting — simultaneously - Field responders work offline with paper checklists - Government agencies and NGOs see completely different (and outdated) data **LIRA's answer:** A single autonomous coordination layer that ingests live satellite + sensor data, validates citizen reports with AI, dispatches resources in real-time, and gives every stakeholder their own tailored view — all within seconds, not hours. #### 🏗️ Technical Architecture (Plain English) [ Disaster Event & Telegram SOS ] │ ▼ ┌─────────────────────────────────────────────────────┐ │ SCOUT AGENT — watches live feeds every 60 seconds │ │ (GDACS global alerts, USGS earthquakes, weather) │ └──────────────────┬──────────────────────────────────┘ │ creates incident record ▼ ┌─────────────────────────────────────────────────────┐ │ ANALYST AGENT — Gemini AI reads the incident & │ │ Telegram inbound streams + cross-checks sensors │ │ → scores severity 1–10 │ │ → labels: VERIFIED / SUSPECTED_FAKE / UNVERIFIED │ └──────────────────┬──────────────────────────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ ┌──────────────┐ ┌─────────────────────────────────┐ │ COMMANDER │ │ HERALD AGENT │ │ AGENT │ │ Translates alerts into 5 Indian │ │ Calculates │ │ languages & sends Twilio SMS │ │ nearest NDRF,│ │ (Hindi, Tamil, Kannada, Bengali,│ │ ambulances, │ │ English) │ │ shelter camps│ └─────────────────────────────────┘ └──────┬───────┘ │ ▼ ┌─────────────────────────────────────────────────────┐ │ VOX AGENT — dials emergency coordinators via Vapi │ │ VoIP call, reads live incident data aloud, │ │ waits for verbal authorization, auto-resolves │ └─────────────────────────────────────────────────────┘ │ ▼ [ Supabase PostgreSQL + PostGIS + Realtime ] ← All agents read/write here. Dashboard updates live. **Why it's feasible:** - Every component uses a **live, running API** (not mocked) - Supabase handles real-time subscriptions without custom WebSocket logic - Gemini Flash is fast (<2s inference), cost-effective for hackathon scale - The entire stack runs locally in 3 terminal commands ### ⏱️ Round 2 — Prototype & Technical Evaluation *(Hour 14–16)* #### ✅ Working Features Checklist | Feature | Status | Where to See It | |---|---|---| | 5 cooperative AI agents | ✅ Live | Trigger demo → watch agent log stream | | Gemini NLP Telegram verification | ✅ Live | Telegram Inbound Stream / NLP badge on map | | MapLibre 3D severity towers | ✅ Live | Dashboard map | | Tactical Telemetry Header & Real-time GPS Resources | ✅ Live | Sleek map headers and dynamic GPS coordinates sidebar | | Multilingual SMS broadcast | ✅ Live | Comms Hub panel → Launch Multichain Dispatch | | VoIP authorization (Vapi) | ✅ Live | Modal Pipeline → Authorize Vox / Talk to Vox | | Vox multilingual voice dispatch | ✅ Live | Comms Hub → Vox Voice Config | | Volunteer auto-assignment | ✅ Live | Volunteer panel → Auto-Assign | | Role-based views (3 roles) | ✅ Live | DEV_MODE switcher in header | | Agency analytics + CSV export | ✅ Live | Switch to AGENCY_ADMIN role | | Field responder mobile view | ✅ Live | `/field` route | | PWA + offline capability | ✅ Live | Install prompt on `/field` | | Load stress test (100 concurrent) | ✅ Live | Telemetry panel → RUN STRESS TEST | | Live performance telemetry bar | ✅ Live | Top Header Bar | #### 🤖 AI / ML Integration | Agent | AI Model | What It Does | |---|---|---| | Analyst | Gemini 1.5 Flash | NLP disaster verification, severity scoring, false alarm detection | | Herald | Gemini 1.5 Flash | Multilingual translation (5 Indian languages) | | Commander | Pure Math (Haversine) | Geodesic distance calculation for resource dispatch | | Vox | Vapi.ai (voice AI) | Outbound VoIP calls with dynamic, regional language speech prompts | | Scout | OpenWeatherMap + GDACS | Real-world data ingestion, not synthetic data | #### 🗄️ Database Design incidents — core event records (PostGIS geometry, severity, NLP labels) resources — NDRF units, hospitals, food camps with availability counts volunteers — 15 seeded responders with skills, coords, language tasks — assignments linking volunteers ↔ incidents agent_logs — timestamped trail of every AI agent action citizen_reports — public SOS submissions with verification status citizen_feedback — post-response ratings (1–5 stars) and comments broadcasts — multilingual SMS dispatch logs user_roles — audit table for role changes (OPERATOR/FIELD_RESPONDER/AGENCY_ADMIN) **Key design decisions:** - `PostGIS` geometry column on `incidents` enables true geospatial queries - `agent_logs` gives a full audit trail of every AI decision (important for accountability in disaster response) - `tasks` table uses FK to both `incidents` and `volunteers` — one task = one volunteer = one incident, ensuring no double-assignment - All tables have `created_at` timestamps for the analytics engine #### 📊 Code Quality Highlights backend/ ├── agents/ # Each agent is a single-purpose Python module │ ├── scout.py # ~80 lines — clean, focused ingestion loop │ ├── analyst.py # Gemini call + structured JSON parsing │ ├── commander.py # Haversine dispatch logic │ ├── herald.py # Twilio + Gemini translation pipeline │ └── vox.py # Vapi webhook handler ├── routers/ # FastAPI routers, one per domain │ └── crisis.py # 5-stage SOS crisis management AI pipeline └── config/ # Singleton Supabase client frontend/ ├── src/ │ ├── app/ # Next.js App Router (dashboard, field routes) │ ├── components/ # IncidentMap, AgentRoom, RoleSwitcher, etc. │ └── lib/ # store.ts, api.ts, nasaLayers.ts └── public/ ├── field-sw.js # Dedicated field-responder Service Worker └── sw.js # next-pwa Workbox SW for main dashboard ### ⏱️ Round 3 — Final Demo & Presentation *(Hour 22–24)* #### 🎯 Recommended Live Demo Script (7 minutes) **Step 1 — Show the problem (30 sec)** **Step 2 — Trigger the Level 9 Demo (2 min)** - Click **💥 TRIGGER LEVEL 9 CYCLONE DEMO** in the dashboard header - Watch the countdown → incident appears on the 3D map → central interactive modal opens over a blurred background. - Left panel shows Cooperative Agent Sequence: Scout ingests → Analyst scores → Commander dispatches → Herald broadcasts - Right panel shows **VOX VoIP Interactive Live Control** with pulsing waveform. Click `AUTHORIZE DISPATCH` to auto-resolve the crisis. **Step 3 — Show the NASA satellite overlay (30 sec)** - Under **NASA / NOAA Imagery** on the right, click **FLOOD DETECT** - Watch how water bodies turn black on the infrared layer over the 3D MapLibre map. - "This is live NASA MODIS data from 2 days ago — no API key needed" **Step 4 — Show Telegram Crisis Gateway (1 min)** - Show the **Telegram Inbound Stream** panel on the left. - Explain the NLP Fake Detection Flow: Citizen submits panicked text -> Analyst checks against OpenWeatherMap -> verified badge turns solid green on the map. **Step 5 — Stress test (1 min)** - Click **⚡ STRESS TEST (100 REQS)** in the left telemetry panel. - Show 100 concurrent database writes completing and metrics like *Throughput* and *DB Latency* updating live on the circular gauges. - "This proves the system handles real disaster-scale traffic" **Step 6 — PWA / offline (30 sec)** - Open `/field` route on mobile or a separate browser - Go offline (browser DevTools → Network → Offline) - "The field responder can still see their task and mark it complete — it syncs when they reconnect" #### 🚀 Innovation Depth (What Makes LIRA Different) | Standard Hackathon Project | LIRA | |---|---| | One AI call to generate text | 5 cooperative agents, each with a distinct specialized role | | Static map with pins | Live 3D extruded severity towers + 5 NASA satellite overlays | | English-only alerts | Real-time Gemini translation into 5 Indian regional languages | | Manual resource assignment | Haversine-based geodesic auto-dispatch with inventory reduction | | Basic Web App | Immersive, high-performance dark aesthetic with dynamic telemetry overlays and micro-animations | | No offline support | Full PWA with dedicated field SW, IndexedDB sync queue, background sync | | No scalability proof | Live `/load/stress-test` endpoint — 100 concurrent inserts, measured ms/record | #### 📈 Future Scalability Roadmap Phase 2 — Production Hardening ├── Multi-tenant auth (Supabase Auth + RLS policies per agency) ├── Replace ngrok with a dedicated cloud deployment (Railway / Render) └── Vapi WebRTC → WhatsApp Business API integration Phase 3 — Intelligence Expansion ├── Fine-tuned Gemini model on Indian disaster corpora ├── Computer vision: satellite image change detection (flood extent mapping) └── Predictive routing: road-network-aware dispatch (OSRM integration) Phase 4 — Government Integration ├── NDMA API webhook ingestion ├── State disaster management authority data feeds └── SDMA dashboard embed (white-label support) ## 🌟 Key Features Summary ### 1. 🤖 Cooperative 5-Agent Neural Engine - **Scout** — polls GDACS + USGS + OpenWeatherMap every 60 seconds - **Analyst** — Gemini 1.5 Flash NLP verification, severity 1–10, fake detection - **Commander** — Haversine geodesic dispatch of nearest NDRF/medical/shelter - **Herald** — Gemini multilingual SMS (5 Indian languages via Twilio) - **Vox** — Vapi.ai outbound VoIP with verbal consent authorization and custom regional language routing (Hindi, Kannada, Tamil, English) via the Comms Hub dashboard ### 2. 🗺️ Live Intelligence Map & Real GPS Resources - MapLibre GL JS with 3D fill-extrusion severity towers pitched at 45 degrees - Tactical Telemetry Header — Sleek, responsive telemetry panel presenting hazard levels and real coordinates - Real GPS Resources — Fully integrated database resource cards showcasing exact latitude/longitude access and capacity ratios - Resource, volunteer, and NLP-verified citizen report pins with live popups ### 3. 📱 Integrated Telegram AI Gateway - Real-time **Telegram Inbound Stream** panel - NLP fake detection and cross-validation with active satellite overlays - Live badge transitions from "UNVERIFIED" to "VERIFIED (Gemini AI)" ### 4. ⚡ Proven Scalability & Telemetry - 100 concurrent async DB insertions via `asyncio.gather()` - Live throughput, DB latency, WebSocket connection, and queue depth metrics visualized via animated circular gauges and wave graphs ## 🚀 Quick Start ### Terminal 1 — Backend cd backend python -m venv venv .\venv\Scripts\Activate # Windows PowerShell pip install -r requirements.txt # Fill backend/.env with all API keys (see .env.example) python demo_seed.py # Seed database with realistic data uvicorn main:app --reload --port 8000 ### Terminal 2 — ngrok (for Vapi VoIP webhooks) ngrok http 8000 # Copy the https URL → paste into Vapi Dashboard under Server URL: # https://.ngrok-free.app/vox/webhook ### Terminal 3 — Telegram Ingestion Agent cd backend .\venv\Scripts\Activate python -m agents.telegram_bot ### Terminal 4 — Frontend cd frontend npm install # Fill frontend/.env.local with Supabase URL + Anon Key npm run dev - **Dashboard**: http://localhost:3000/dashboard - **Field Responder**: http://localhost:3000/field - **API Docs**: http://localhost:8000/docs ## 📱 How to Use the Telegram Integration ## 🔑 API Keys Required | Service | Used For | Free Tier | |---|---|---| | Supabase | Database + Realtime | ✅ Yes | | Google Gemini | NLP analysis + translation | ✅ Yes | | OpenWeatherMap | Live weather sensor data | ✅ Yes | | Twilio | SMS + WhatsApp broadcasting | ✅ Trial | | Vapi.ai | Outbound VoIP calls | ✅ Trial | | Telegram | Citizen Report Ingestion | ✅ Yes | | NASA GIBS / FIRMS | Satellite imagery | ✅ Always free, no key needed | *LIRA — Built for the disaster responders who don't have time to wait.*