Skip to content

README.md

Latest commit

 

History

History
146 lines (110 loc) · 7.41 KB

README.md

File metadata and controls

146 lines (110 loc) · 7.41 KB
Raw
Status

CityPulse AI

Multi-Agent Decision Intelligence Platform for Urban Health Risk Management

Next.js FastAPI GCP NVIDIA OpenRouter LangChain LangGraph Turso Drizzle ORM

🏆 Hackathon Submission

  • Hackathon: Google Gen AI Academy - APAC Edition (Cohort 2)
  • Track: Challenge Track 2: Autonomous Multi-Agent System (NVIDIA Sponsored)
  • Problem Statement: Creating a resilient, multi-agent AI framework that ingests urban signals to intelligently forecast, triage, and resolve municipal health risks with human-in-the-loop oversight.

🧠 What is CityPulse AI?

CityPulse AI is a live, multi-agent oversight platform designed for municipal crisis management. It transforms raw, chaotic urban signals—such as live air quality fluctuations, weather changes, and localized citizen complaints—into prioritized, human-approved municipal actions.

Rather than just displaying numbers on a dashboard, CityPulse AI operates as a society of cooperating AI agents. These agents ingest data, run predictive GPU-accelerated simulations, triage incidents, debate mitigation strategies, and present a final, robust recommendation to human operators.

❓ Why This?

Modern cities generate massive amounts of data, but municipal decision-makers suffer from "alert fatigue." When an environmental crisis (like an industrial fire causing severe AQI spikes) occurs, operators don't need more data—they need actionable intelligence.

CityPulse AI bridges the gap between raw data and municipal action by automating the heavy lifting of data correlation, forecasting, and policy checking, while keeping a human firmly in the loop for final approval.

📊 Live GPU Dashboard

Dashboard showing GPU Performance

⚙️ How it Works

The system operates via a continuous, stateful pipeline (powered by LangGraph principles):

  1. Ingestion: Constantly monitors AQI, Weather, and citizen reports.
  2. GPU Forecasting & Triage: Uses NVIDIA GPU-accelerated DBSCAN clustering and Linear Regression to predict hazard spread and identify hotspots.
  3. Decision & Reflection: AI agents debate the best course of action based on historical precedents and municipal guidelines. If a decision is too risky, the Reflection Agent flags it.
  4. Human Oversight: The proposed action is queued in the "Mission Control" dashboard. A human operator approves or rejects it (with feedback to train the AI).
  5. Notification: Once approved, alerts are dispatched to relevant municipal departments or citizens.

⚡ Serverless GPU Infrastructure

All heavy numerical computations (clustering, linear regression) are offloaded to a Serverless NVIDIA T4 GPU hosted on Modal. The FastAPI backend utilizes the nvidia/cuda:12.2.2-devel image and the NVIDIA RAPIDS suite (cuDF and cuML). Modal's cold-start optimizations allow the GPU to wake up, execute the mathematical models, and spin down in milliseconds, ensuring highly cost-effective and scalable performance.

🏗️ Architecture

graph TD
    subgraph Data Sources
        AQ[AQI Sensors] --> IA[Ingestion Agent]
        WE[Weather API] --> IA
        CR[Citizen Complaints] --> IA
    end

    subgraph AI Orchestration Layer Next.js
        IA --> GPU[GPU Service FastAPI]
        GPU -->|Clustering & Forecast| TA[Triage Agent]
        TA --> DA[Decision Agent]
        DA --> RA[Reflection Agent]
    end

    subgraph Human-in-the-Loop
        RA -->|High Confidence| DB[(CityPulse DB)]
        RA -->|Low Confidence / High Risk| HQ[Human Approval Queue]
        HQ -->|Approve/Reject| DB
    end
    
    subgraph Action
        DB --> NA[Notification Agent]
        NA --> EMS[EMS / Fire Dept / Public]
    end
Loading

💻 Tech Stack

Component Technology Description
Frontend Next.js React App Router, Tailwind CSS, Recharts
Backend AI FastAPI Python backend for heavy numerical compute
GPU Compute NVIDIA cuDF, cuML for DBSCAN clustering & forecasting
AI Framework LangChain LangGraph Multi-agent orchestration, tools, and reflection loops
LLM Engine OpenRouter Agent reasoning and negotiation
Database Turso Serverless SQLite Database via Drizzle ORM
Deployment Vercel Modal Next.js Frontend on Vercel, Python GPU API on Modal (Serverless NVIDIA T4)

🚀 Quick Setup (Local Dev)

# 1. Clone & Install
git clone https://github.com/Tetra4ge/CityPulse-AI.git
cd CityPulse-AI
npm install

# 2. Setup Environment
cp .env.example .env.local
# Add your Gemini/OpenRouter API Keys

# 3. Deploy GPU Service to Modal
cd gpu-service
pip install -r requirements.txt
modal setup  # Authenticate with Modal
modal deploy main.py  # Deploys to a Serverless NVIDIA T4 GPU

# 4. Setup Frontend Environment
cd ..
cp .env.example .env

# --- LLM API Keys ---
# OPENROUTER_API_KEY="your-openrouter-key-here"
# GEMINI_API_KEY="your-gemini-api-key-here"
# TURSO_DATABASE_URL="libsql://your-database-url.turso.io"
# TURSO_AUTH_TOKEN="your-turso-auth-token"
# NEXT_PUBLIC_GPU_SERVICE_URL="https://your-app-name.modal.run"
# GPU_SERVICE_API_KEY="your-gpu-service-api-key"

# 5. Start Frontend
npm run dev

Built by Team TetraFourge

Tetra4ge GitHub