likithkumarmv/LIRA

# LIRA — 自主危机情报网络 ## 🏆 黑客松评估指南 本节将 **LIRA 的每一项功能** 直接映射到黑客松的评审标准，以便评委能够在每一轮中快速评估项目。 ### ⏱️ 第一轮 — 创意验证与架构审查 *(第 4–6 小时)* #### ❓ LIRA 解决了什么问题？ **痛点：** 当灾难（洪水、气旋、地震）发生时，救援协调往往会失败，原因在于： - 信息碎片化地分散在 WhatsApp、无线电和政府门户网站中 - 没有一个系统能够同时知道资源在*哪里*、*谁*有空以及公众正在报告*什么* - 现场救援人员只能使用纸质清单进行离线工作 - 政府机构和非政府组织（NGO）看到的数据截然不同（且已过时） **LIRA 的答案：** 一个单一的自主协调层，可摄取实时的卫星和传感器数据，利用 AI 验证市民报告，实时调度资源，并为每个利益相关者提供量身定制的专属视图——所有这一切都在几秒钟内完成，而非几小时。 #### 🏗️ 技术架构（简明描述） ``` [ 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. ``` **为何具有可行性：** - 每个组件都使用了 **正在运行的 API**（非模拟） - Supabase 处理实时订阅，无需自定义 WebSocket 逻辑 - Gemini Flash 速度快（<2秒推理），对于黑客松规模而言极具成本效益 - 整个技术栈只需 3 条终端命令即可在本地运行 ### ⏱️ 第二轮 — 原型与技术评估 *(第 14–16 小时)* #### ✅ 功能实现清单 | 功能 | 状态 | 查看位置 | |---|---|---| | 5 个协作 AI agent | ✅ 实时 | 触发演示 → 观察 agent 日志流 | | Gemini NLP Telegram 验证 | ✅ 实时 | Telegram 接入流 / 地图上的 NLP 徽章 | | MapLibre 3D 严重性塔楼 | ✅ 实时 | 仪表盘地图 | | 战术遥测标头与实时 GPS 资源 | ✅ 实时 | 简洁的地图标头和动态 GPS 坐标侧边栏 | | 多语言 SMS 广播 | ✅ 实时 | 通讯枢纽面板 → 启动多链调度 | | VoIP 授权 (Vapi) | ✅ 实时 | 模态流水线 → 授权 Vox / 与 Vox 对话 | | Vox 多语言语音调度 | ✅ 实时 | 通讯枢纽 → Vox 语音配置 | | 志愿者自动分配 | ✅ 实时 | 志愿者面板 → 自动分配 | | 基于角色的视图（3 种角色） | ✅ 实时 | 标头中的 DEV_MODE 切换器 | | 机构分析 + CSV 导出 | ✅ 实时 | 切换至 AGENCY_ADMIN 角色 | | 现场救援人员移动端视图 | ✅ 实时 | `/field` 路由 | | PWA + 离线功能 | ✅ 实时 | `/field` 上的安装提示 | | 负载压力测试（100 并发） | ✅ 实时 | 遥测面板 → 运行压力测试 | | 实时性能遥测条 | ✅ 实时 | 顶部标头栏 | #### 🤖 AI / ML 集成 | Agent | AI 模型 | 功能描述 | |---|---|---| | Analyst | Gemini 1.5 Flash | NLP 灾难验证、严重性评分、误报检测 | | Herald | Gemini 1.5 Flash | 多语言翻译（5 种印度语言） | | Commander | 纯数学计算 (Haversine) | 用于资源调度的测地距离计算 | | Vox | Vapi.ai (语音 AI) | 具备动态、地区语言语音提示的外呼 VoIP 通话 | | Scout | OpenWeatherMap + GDACS | 真实世界数据摄取，非合成数据 | #### 🗄️ 数据库设计 ``` 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) ``` **核心设计决策：** - `incidents` 上的 `PostGIS` 几何列支持真正的地理空间查询 - `agent_logs` 提供了每项 AI 决策的完整审计追踪（对于灾难响应中的问责制至关重要） - `tasks` 表同时使用 FK 指向 `incidents` 和 `volunteers` — 一个任务 = 一个志愿者 = 一个事件，确保不会被重复分配 - 所有表都包含用于分析引擎的 `created_at` 时间戳 #### 📊 代码质量亮点 ``` 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 ``` ### ⏱️ 第三轮 — 最终演示与展示 *(第 22–24 小时)* #### 🎯 推荐的现场演示脚本（7 分钟） **第 1 步 — 展示问题（30 秒）** **第 2 步 — 触发 9 级演示（2 分钟）** - 点击仪表盘标头中的 **💥 触发 9 级气旋演示** - 观察倒计时 → 事件出现在 3D 地图上 → 中央交互模态框在模糊的背景上打开。 - 左侧面板显示协作 Agent 序列：Scout 摄取 → Analyst 评分 → Commander 调度 → Herald 广播 - 右侧面板显示带有脉冲波形的 **VOX VoIP 交互式实时控制**。点击 `AUTHORIZE DISPATCH` 以自动解决危机。 **第 3 步 — 展示 NASA 卫星叠加层（30 秒）** - 在右侧的 **NASA / NOAA 图像** 下，点击 **洪水检测** - 观察 3D MapLibre 地图上红外图层中的水体如何变黑。 - “这是 2 天前的实时 NASA MODIS 数据 — 无需 API key” **第 4 步 — 展示 Telegram 危机网关（1 分钟）** - 展示左侧的 **Telegram 接入流** 面板。 - 解释 NLP 虚假检测流程：市民提交恐慌文本 -> Analyst 对照 OpenWeatherMap 进行检查 -> 地图上的已验证徽章变为纯绿色。 **第 5 步 — 压力测试（1 分钟）** - 点击左侧遥测面板中的 **⚡ 压力测试 (100 个请求)**。 - 展示 100 个并发数据库写入完成，并且*吞吐量*和*数据库延迟*等指标在圆形仪表上实时更新。 - “这证明了该系统能够处理真实的灾难级流量” **第 6 步 — PWA / 离线（30 秒）** - 在移动设备或单独的浏览器上打开 `/field` 路由 - 转为离线状态（浏览器开发者工具 → 网络 → 离线） - “现场救援人员仍然可以查看其任务并将其标记为已完成 — 系统会在重新连接后同步” #### 🚀 创新深度（LIRA 的与众不同之处） | 标准黑客松项目 | LIRA | |---|---| | 单次 AI 调用生成文本 | 5 个协作 agent，每个都有独立的专业角色 | | 带有图钉的静态地图 | 实时 3D 挤出的严重性塔楼 + 5 种 NASA 卫星叠加层 | | 仅限英语的警报 | 实时 Gemini 翻译成 5 种印度地区语言 | | 手动资源分配 | 基于 Haversine 测地线的自动调度与库存扣减 | | 基础 Web 应用 | 沉浸式、高性能的暗黑美学，带有动态遥测叠加层和微动画 | | 无离线支持 | 完整的 PWA，配备专用的现场 Service Worker、IndexedDB 同步队列、后台同步 | | 无可扩展性证明 | 实时 `/load/stress-test` endpoint — 100 次并发插入，以 ms/record 为单位进行测量 | #### 📈 未来可扩展性路线图 ``` 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) ``` ## 🌟 核心功能摘要 ### 1. 🤖 协作式 5-Agent 神经引擎 - **Scout** — 每 60 秒轮询一次 GDACS + USGS + OpenWeatherMap - **Analyst** — Gemini 1.5 Flash NLP 验证、1–10 级严重性评分、虚假检测 - **Commander** — 基于 Haversine 测地线调度最近的 NDRF/医疗/避难所 - **Herald** — Gemini 多语言 SMS（通过 Twilio 支持 5 种印度语言） - **Vox** — 通过通讯枢纽仪表盘进行 Vapi.ai 外呼 VoIP，支持口头同意授权及自定义地区语言路由（印地语、卡纳达语、泰米尔语、英语） ### 2. 🗺️ 实时情报地图与真实 GPS 资源 - 使用 MapLibre GL JS，呈现倾斜 45 度的 3D 填充挤出严重性塔楼 - 战术遥测标头 — 简洁、响应式的遥测面板，展示危险级别和实时坐标 - 真实 GPS 资源 — 完全集成的数据库资源卡片，展示精确的纬度/经度访问及容量比例 - 带有实时弹窗的资源、志愿者以及经 NLP 验证的市民报告图钉 ### 3. 📱 集成的 Telegram AI 网关 - 实时 **Telegram 接入流** 面板 - NLP 虚假检测及与活跃卫星叠加层的交叉验证 - 实时徽章状态从“未验证”变为“已验证 (Gemini AI)” ### 4. ⚡ 经过验证的可扩展性与遥测 - 通过 `asyncio.gather()` 实现 100 个并发异步数据库插入 - 通过动画圆形仪表和波形图，可视化展示实时的吞吐量、数据库延迟、WebSocket 连接及队列深度指标 ## 🚀 快速开始 ### 终端 1 — 后端 ``` cd backend python -m venv venv .\venv\Scripts\Activate # Windows PowerShell pip install -r requirements.txt # 使用所有 API 密钥填充 backend/.env（参见 .env.example） python demo_seed.py # Seed database with realistic data uvicorn main:app --reload --port 8000 ``` ### 终端 2 — ngrok（用于 Vapi VoIP Webhook） ``` ngrok http 8000 # 复制 https URL → 粘贴到 Vapi Dashboard 的 Server URL 下： # https://.ngrok-free.app/vox/webhook ``` ### 终端 3 — Telegram 摄取 Agent ``` cd backend .\venv\Scripts\Activate python -m agents.telegram_bot ``` *(这将启动轮询机器人，读取 SOS 消息并将其传递给 Gemini Analyst)* ### 终端 4 — 前端 ``` cd frontend npm install # 使用 Supabase URL + Anon Key 填充 frontend/.env.local npm run dev ``` - **仪表盘**: http://localhost:3000/dashboard - **现场救援人员**: http://localhost:3000/field - **API 文档**: http://localhost:8000/docs ## 📱 如何使用 Telegram 集成 1. **创建机器人：** 在 Telegram 上向 [@BotFather](https://t.me/botfather) 发送消息，输入 `/newbot`，并按照步骤获取 API Token。 2. **添加至 `.env`：** 将您的 token 粘贴到 `backend/.env` 中的 `TELEGRAM_BOT_TOKEN` 下。 3. **启动 Agent：** 确保终端 3（`python -m agents.telegram_bot`）正在运行。 4. **触发工作流：** 在 Telegram 上向您的机器人发送消息。您可以粘贴如下恐慌消息： 5. **观察仪表盘：** 该消息将立即出现在“Telegram 接入流”面板上。Analyst Agent 将对其进行评估，检查卫星上下文，并生成一个活跃的突发事件！ ## 🔑 所需的 API 密钥 | 服务 | 用途 | 免费层级 | |---|---|---| | Supabase | 数据库 + 实时通信 | ✅ 是 | | Google Gemini | NLP 分析 + 翻译 | ✅ 是 | | OpenWeatherMap | 实时天气传感器数据 | ✅ 是 | | Twilio | SMS + WhatsApp 广播 | ✅ 试用 | | Vapi.ai | 外呼 VoIP 通话 | ✅ 试用 | | Telegram | 市民报告摄取 | ✅ 是 | | NASA GIBS / FIRMS | 卫星图像 | ✅ 永久免费，无需 key | *LIRA — 专为那些没有时间等待的灾难救援人员打造。*

标签：AI智能体, GIS地理信息系统, PWA应用, 实时数据处理, 测试用例, 灾害应急管理, 空间数据分析, 逆向工具