WeatherGPT

SIH26068 — Ministry of Earth Sciences / IMD · Disaster Management

A conversational, multilingual, voice-enabled weather assistant that turns forecast data into plain-language, actionable guidance for farmers, fishermen, travellers and flood-prone communities across India.

        Open-Meteo (live)                    Anthropic (claude-sonnet-4-6)
               │                                          │
               ▼                                          ▼
        ┌──────────────┐                       ┌────────────────────┐
        │  Weather     │                       │  Structured        │
        │  provider    │                       │  extraction +      │
        └──────┬───────┘                       │  grounded writing  │
               │                               └─────────┬──────────┘
               ▼                                         │
     ╔═══════════════════════╗                           │
     ║  WEATHER RISK ENGINE  ║ ◄─────────────────────────┘
     ║  the only place risk  ║
     ║  is ever computed     ║
     ╚═══════╤═══════════════╝
             │  { risk_score, risk_level, detected_hazard }
   ┌─────────┼───────────┬──────────────┬───────────────┐
   ▼         ▼           ▼              ▼               ▼
 /chat    /alerts   24h timeline   India risk map   emergency mode

---

Why it is built this way

One risk engine. Every feature that mentions risk calls app/services/risk_engine.py. Nothing else computes a score. That is what makes it impossible for the map to say Moderate while the alert says Severe for the same place — there is no second implementation to drift.

Answers cannot invent numbers. Generated prose is scanned for measurement claims and each one is checked against the values the provider actually returned. A claim that matches nothing causes the whole answer to be discarded in favour of a template built from real values. The fallback for a hallucination is a correct answer, not an apology.

Degradation is designed, not accidental. No API key, no network, a failed translation, a dead TTS service — each has a defined path. Quality drops; availability does not. Whatever degraded is reported in the response's degraded object rather than hidden.

Multilingual all the way down. Six languages end to end. Language detection runs offline on the Unicode script, which is exact for Telugu and separates Assamese from Bengali by two letters Bengali does not use. When the LLM is unavailable the assistant answers from localised templates — it never silently falls back to English.

---

Deploying

vercel.json in the repo root declares both services and the routing, so the repo imports into Vercel as-is. Read docs/DEPLOYMENT.md first — three components (the alert scheduler, the /ws/alerts WebSocket and the SQLite store) need a long-lived process, which serverless does not provide.

The app detects a serverless runtime and adapts rather than failing: the in-process scheduler is disabled in favour of a platform cron, the database moves to /tmp, the API is served at both /chat and /api/chat so it works whether or not the platform strips the prefix, and the client switches the alert feed from WebSocket to polling — reporting "Alerts updating periodically" rather than pretending to be live. That guide covers what is degraded and the split deploy (Vercel frontend, Render backend) that avoids all of it.

Quick start

Two terminals. Neither step needs an API key to run.

# ── Backend ───────────────────────────────────────────────
cd backend
pip install -r requirements.txt
cp ../.env.example ../.env          # optional; every value has a default
python run.py                       # http://127.0.0.1:8000  ·  docs at /docs

# ── Frontend ──────────────────────────────────────────────
cd frontend
npm install
npm run dev                         # http://127.0.0.1:5173

The Vite dev server proxies /api (WebSockets included) to FastAPI, so local development never depends on CORS configuration.

Configuration

Everything is environment-driven; see .env.example. The values that change behaviour most:

Variable	Default	Effect
LLM_PROVIDER	auto	gemini, anthropic, or auto (prefers Gemini when its key is set)
GEMINI_API_KEY	(unset)	Unset ⇒ rule-based understanding and templated answers
GEMINI_MODEL	gemini-3.5-flash-lite	Answers in about a second; larger flash models return 503 under load
ANTHROPIC_API_KEY	(unset)	The alternative provider; same pipeline, same guardrails
ANTHROPIC_MODEL	claude-sonnet-4-6	Model used for extraction and writing
ELEVENLABS_API_KEY	(unset)	Hosted speech-to-text; needs no model download, so voice works on serverless
WEATHER_DATA_MODE	live	fixture serves deterministic offline data for dev/CI
ALERT_INTERVAL_MINUTES	30	Scan cadence for the single alert scheduler
ALERT_MIN_RISK_SCORE	61	The "High" band; the floor for raising an alert
TWILIO_*	(unset)	Unset ⇒ alerts log to the console instead of texting

WEATHER_DATA_MODE=fixture is for offline development and tests. Fixture responses are tagged data_source: "fixture" and the UI shows a SIMULATED DATA badge at every breakpoint. Simulated data cannot appear in live mode.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗