ET Hackathon 2025 · Final Submission · Pralhad Jadhav
Not a chatbot. Not a dashboard. A compliance-enforced reasoning engine that turns raw AQI data into actionable health decisions — for 300M+ Indians at risk.
Domain-Specialized AI Agents with Compliance Guardrails
Air quality data is everywhere — AQI dashboards, government portals, mobile apps. But none of them answer the question every person actually has:
"AQI is 185. What does that mean for ME, right now, today?"
VAYORA fills that gap. It is a domain-specialized AI agent built for Air Quality & Public Health, executing the full decision workflow from raw sensor data to personalized, compliance-enforced, auditable health guidance.
| Evaluation Criterion | VAYORA's Response |
|---|---|
| Domain Expertise | Specialized in AQI, pollution science, public health — curated RAG knowledge base |
| Compliance & Guardrails | Hard-coded AQI thresholds, mode-locking, tone enforcement, source grounding |
| Edge Case Handling | API fallbacks, city-not-found routing, hazardous AQI lockouts, Redis failover |
| Full Task Completion | End-to-end: query → intent → live data → health logic → RAG → LLM → response |
| Auditability | Every step logged: intent, data source, rule applied, RAG chunks, model used |
- Fetches real-time AQI for 200+ Indian cities via WAQI API
- Converts raw numbers into plain-language health guidance
- Personalized by user group: children, elderly, asthma patients
- Color-coded risk levels: Good → Moderate → Unhealthy → Hazardous
- Tells you what to DO — not just what the number is
- Ask anything: "What is PM2.5 and why is it dangerous?"
- FAISS vector search over curated health & environment knowledge
- Home remedies, indoor protection tips, mask guidance
- AQI scale explanation & pollution cause analysis
- Multilingual: English, Hindi, Hinglish, Marathi
- Short-term AQI trend prediction via OpenWeather 24h data
- Weather-linked insights: wind, humidity, pressure → pollution impact
- "Tomorrow will be worse — here's why"
- School / event / outdoor activity decision support
- Emergency mode auto-activated for hazardous conditions (AQI > 300)
User Query (Web / API)
│
▼
┌─────────────────────┐
│ Intent Router │ ← NLP keyword + regex city extraction
│ (6 categories) │ CITY_AQI_NOW | CITY_AQI_FORECAST |
└──────────┬──────────┘ ENVIRONMENT_KNOWLEDGE | CITY_REQUIRED |
│ GENERAL_CHAT | WEATHER_QUERY
▼
┌──────┴──────────────────────────────────────┐
│ │
▼ ▼
LIVE AQI FETCH RAG KNOWLEDGE
(WAQI API → cache) (FAISS + MiniLM similarity_search k=3)
│ │
▼ │
HEALTH LOGIC ENGINE ◄─────────────────────────────┘
(rule-based: AQI → risk category, urgency,
mask_needed, outdoor_activity, sensitive_groups)
│
▼
WEATHER LOGIC AQI FORECAST
(wind, humidity, pressure, (OpenWeather 24h →
temp → pollution insights) trend: worse/better/similar)
│ │
└────────────────┬───────────────────┘
▼
GEMINI LLM AGENT
(structured prompt with:
city, AQI, category, weather,
forecast, RAG chunks, mode, language)
│
▼
COMPLIANCE GUARDRAILS
(tone enforcement, urgency lock,
sensitive group flags, source grounding)
│
▼
JSON RESPONSE
{ reply, aqi, category, city }
VAYORA does not let the LLM decide health advice freely. Every response is constrained by deterministic domain rules.
| AQI Range | Category | Urgency | Enforced Behaviour |
|---|---|---|---|
| 0 – 50 | Good | low |
Outdoor freely permitted |
| 51 – 100 | Moderate | low |
Monitor sensitive groups |
| 101 – 150 | Unhealthy (Sensitive) | medium |
Restrict children & elderly outdoor |
| 151 – 200 | Unhealthy | high |
Minimize outdoor, N95 mask required |
| 201 – 300 | Very Unhealthy | critical |
Stay indoors, air filtration advised |
| 301+ | Hazardous | critical |
EMERGENCY MODE — outdoor prohibited |
- Mode Lock — Emergency mode overrides user-selected tone regardless of LLM output
- Tone Enforcement —
urgency: critical→ "urgent and direct";low→ "informative" - Fallback Chain — API fail → 15-min cache → graceful error message (never hallucinate data)
- Input Sanitization — City extraction validated against
BAD_CITY_WORDSblocklist - Source Grounding — All health claims must come from RAG k=3 retrieval, not LLM memory
- Sensitive Group Flags — AQI > 100 auto-flags children, elderly, asthma patients
| Edge Case | Trigger | VAYORA's Response |
|---|---|---|
| API Timeout | WAQI/OpenWeather returns nothing in 10s | Returns last cached result (15-min TTL) or clear error message — never fabricates AQI |
| City Not Found | No valid city in user query | Routes to CITY_REQUIRED intent → prompts user for city name |
| Ambiguous Query | "is it safe?" without city | Checks session memory for last_city, falls back to CITY_REQUIRED |
| Hazardous AQI (300+) | AQI exceeds very unhealthy | Locks to emergency mode, prohibits outdoor advice, overrides all balanced tones |
| Unknown Intent | No pattern match | Falls back to ENVIRONMENT_KNOWLEDGE path via RAG |
| Redis Unavailable | Session memory backend offline | Silently fails over to in-memory dict — user experience unaffected |
| Invalid City String | "today", "weather", "now" extracted as city | BAD_CITY_WORDS filter rejects it, returns CITY_REQUIRED |
| No Google API Key | Missing .env config |
Returns human-readable config error, never crashes |
A key hackathon evaluation criterion. VAYORA exposes reasoning at every agent step.
Step 1: INTENT CLASSIFICATION
→ Logs: intent=CITY_AQI_NOW, confidence=0.93, city="Delhi", time_query="now"
Step 2: DATA FETCH
→ Logs: aqi=187, station="Delhi US Embassy", _from_cache=false, timestamp="2025-01-15 14:30"
→ Pollutants: { pm25: 142, pm10: 198, no2: 67 }
Step 3: HEALTH ASSESSMENT (deterministic rules, not LLM)
→ Returns: category="Unhealthy", risk_level="High", urgency="high",
mask_needed=True, outdoor_activity="minimize",
sensitive_groups=["everyone"]
Step 4: RAG RETRIEVAL
→ Query: "AQI 187 health impact and precautions"
→ Returns: 3 chunks from health_guidelines.txt (exact text, traceable)
Step 5: LLM ADVISORY
→ Prompt: structured template with city, AQI, category, weather, forecast, RAG chunks
→ Model: gemini-2.5-flash-lite (versioned)
Step 6: RESPONSE DELIVERY
→ { reply: "...", aqi: 187, category: "Unhealthy", city: "Delhi" }
→ Every field traceable to its source
FAISS vector database over curated domain knowledge — 5 categories, verified sources.
🫁 Healthcare & Medical
- AQI health impact by category (0–500+)
- Organ-level effects: lungs, heart, brain, skin
- Vulnerable groups: asthma, COPD, heart disease, children, elderly
- Symptoms by pollutant type (PM2.5, NO2, O3)
- Emergency protocols & first-aid guidance
🌿 Environment & Ecology
- Seasonal AQI variation & monsoon patterns
- India NAQI vs US AQI scale comparison
- Urban vs rural pollution profiles
- Ecosystem impact on plants & water bodies
- Weather inversion trap conditions
🏭 Pollution Causes
- Vehicle & industrial emission sources
- Crop burning cycles (Punjab/Haryana → Delhi)
- Construction dust composition (PM10)
- Diwali / seasonal event AQI spikes
- Agricultural stubble burning cycles
🛡️ Control & Prevention
- Indoor air quality improvement (HEPA, ventilation)
- N95/KN95 mask usage guidelines
- Home remedy knowledge base (tulsi, ginger, steam)
- Dietary & lifestyle adjustments for high AQI
- Air-purifying plant recommendations
🔭 Future & Solutions
- EV adoption impact projections
- Green infrastructure & urban forests
- Government NCAP policy & targets
- Citizen science & community monitoring
- AI, sensors, satellite monitoring approaches
health_guidelines.txt
↓
RecursiveCharacterTextSplitter (chunk_size=600, overlap=80)
↓
HuggingFace MiniLM-L6-v2 Embeddings (normalized, CPU)
↓
FAISS Vector Store (saved locally, loaded on startup)
↓
similarity_search(query, k=3) → top 3 relevant chunks
↓
Injected into Gemini prompt as grounding context
| Layer | Technology | Why This Choice |
|---|---|---|
| Backend Framework | FastAPI (Python 3.11) | Async, high-performance, auto /docs |
| LLM Engine | Google Gemini 2.5 Flash Lite | Fast inference, long context, multilingual |
| Vector Store | FAISS + HuggingFace MiniLM-L6-v2 | Local, fast, no cloud dependency |
| AQI Data | WAQI API | 200+ Indian cities, real-time station data |
| Weather Data | OpenWeather API | 24h forecast, geo-coded, atmospheric data |
| Text Chunking | LangChain RecursiveCharacterTextSplitter | 600-token chunks, 80-token overlap |
| Session Memory | Redis + in-memory fallback | Persistent context with graceful degradation |
| Frontend | HTML5 / CSS3 / JavaScript | FastAPI-served SPA, Web Speech API, mobile UI |
VAYORA/
├── app/
│ ├── api.py # FastAPI main app, all endpoints
│ ├── agents/
│ │ ├── intent_router.py # NLP-based intent classification (6 categories)
│ │ └── vayora_agent.py # Gemini LLM agent with mode-aware prompting
│ ├── services/
│ │ ├── aqi_service.py # WAQI API + 15-min caching
│ │ ├── health_logic.py # Rule-based AQI → risk assessment
│ │ ├── weather_logic.py # Pollutant/weather impact analysis
│ │ ├── aqi_forecast.py # OpenWeather 24h AQI trend
│ │ └── weather_service.py # Current weather fetch
│ ├── rag/
│ │ └── ingest.py # FAISS build + similarity search
│ ├── data/
│ │ ├── health_guidelines.txt # Curated knowledge base
│ │ └── faiss_index/ # Saved vector store (auto-generated)
│ └── state.py # VayoraState TypedDict definition
├── frontend/
│ ├── index.html # Main UI (served by FastAPI)
│ ├── app.js # Chat logic, voice I/O, AQI strip
│ └── style.css # Dark theme, responsive
├── main.py # Terminal test runner
├── .env # API keys (WAQI, Gemini, OpenWeather)
└── requirements.txt
- Python 3.11+
- API Keys: WAQI Token, Google Gemini API Key, OpenWeather API Key
# Clone the repository
git clone https://github.com/parlhad/VAYORA
cd VAYORA
# Install dependencies
pip install -r requirements.txt
# Configure API keys
cp .env.example .env
# Edit .env with your keys:
# WAQI_TOKEN=your_token
# GOOGLE_API_KEY=your_key
# OPENWEATHER_API_KEY=your_key
# Start the server
uvicorn app.api:app --reload- Web UI: http://127.0.0.1:8000
- API Docs: http://127.0.0.1:8000/docs
- Chat Endpoint:
POST /vayora/chat - Advisory Endpoint:
GET /vayora/advisory?city=Delhi
python main.py| Query | Intent Routed | What VAYORA Does |
|---|---|---|
"AQI in Delhi" |
CITY_AQI_NOW |
Fetches live AQI, assesses health risk, gives personalized advisory |
"Is it safe to jog in Mumbai today?" |
CITY_AQI_NOW |
Fetches AQI, checks outdoor_activity rules, gives exercise guidance |
"What is PM2.5?" |
ENVIRONMENT_KNOWLEDGE |
RAG search, returns health science explanation |
"Tomorrow forecast for Pune" |
CITY_AQI_FORECAST |
OpenWeather 24h trend + atmospheric analysis |
"Home remedies for pollution relief" |
HEALTH_ADVICE |
RAG-grounded list of evidence-based home treatments |
"मुंबई का AQI क्या है?" |
CITY_AQI_NOW |
Same pipeline, Hindi response via language param |
"Should school have outdoor sports?" |
CITY_REQUIRED |
Prompts for city, then provides school-specific guidance |
Request:
{
"message": "AQI in Delhi today",
"mode": "balanced", // balanced | deep | emergency
"language": "en" // en | hi | hinglish | mr
}
Response:
{
"reply": "Delhi's AQI is 187 — Unhealthy...",
"aqi": 187,
"category": "Unhealthy",
"city": "Delhi"
}Response:
{
"reply": "...",
"aqi": 187,
"category": "Unhealthy",
"city": "Delhi"
}| User Group | How VAYORA Helps |
|---|---|
| Citizens (300M+ at risk) | Safe outdoor timing, personalized health-risk alerts, home remedy guidance |
| Healthcare / Hospitals | Proactive alerts for vulnerable patients, pollution-linked symptom correlation |
| Schools & Institutions | Informed outdoor sports decisions, AQI-safe event planning |
| Urban Authorities | Evidence-based policy interventions, hotspot identification, multi-agency support |
- It's a true AI agent — not a chatbot wrapping an API. Every step is reasoned, not retrieved.
- Compliance is built-in at every layer — rules override LLM when safety demands it.
- Fully auditable — every decision traceable from input to output.
- Production-grade resilience — handles API failures, bad inputs, missing data gracefully.
- Domain depth — curated knowledge across 5 domains, not generic health advice.
- Multi-modal I/O — text, voice in, voice out, multi-language, mobile-responsive.
Pralhad Jadhav
- GitHub: github.com/parlhad/VAYORA
- Hackathon: ET Hackathon 2025
- Domain: Environmental Intelligence / Public Health AI
VAYORA — Because 300 million people deserve more than a number.