# UrjaGridIQ (All-India Power Grid Intelligence & BESS Platform)

> UrjaGridIQ is India's autonomous power grid telemetry, machine learning forecasting, and commercial battery storage (BESS) optimization platform covering the All-India synchronous grid (~250 GW peak demand).

## API Endpoints for AI Agents & Crawlers

### 1. Live National Grid Telemetry & Stress Scoring
- **Endpoint:** `GET /api/grid-stress`
- **Description:** Scores the latest 15-minute telemetry using LightGBM decision tree ensembles for Frequency Violation Risk (<49.7 Hz / >50.2 Hz) and Demand Ramp-Shock (>3500 MW/slot).
- **Latency:** <2 ms pure JS tree traversal.

### 2. Next-Day National Peak Demand Forecaster
- **Endpoint:** `GET /api/demand-forecast`
- **Description:** Returns the next-day national peak demand forecast (MW), day-ahead delta, seasonal feature importances, and historical validation MAPE (4.43%).

### 3. State-Level SLDC & Regional RLDC Telemetry
- **Endpoint:** `GET /api/state-live?state=<Name>`
- **Supported Entities:**
  - 5 Regional Despatch Centres: `NRLDC (Northern Region)`, `WRLDC (Western Region)`, `SRLDC (Southern Region)`, `ERLDC (Eastern Region)`, `NERLDC (North-Eastern Region)`
  - 34 State SLDCs: `Gujarat`, `Andhra Pradesh`, `Rajasthan`, `Maharashtra`, `Tamil Nadu`, `Karnataka`, `Uttar Pradesh`, `Madhya Pradesh`, `Telangana`, `Punjab`, `Delhi`, `West Bengal`, etc.
- **Returns:** Real-time Demand Now (MW), Peak Today (MW), Renewable Share (%), Carbon Intensity (gCO2/kWh), IEX Clearing Price (INR/kWh), System Frequency (Hz), Net Grid Interchange (MW), 24-hour 96-slot intraday actual/forecast curve, and generation mix (Solar, Wind, Thermal, Hydro).

### 4. AI-Native Live Summary (Markdown)
- **Endpoint:** `GET /api/live-summary`
- **Description:** Clean high-density text and markdown report for LLM ingestion.

### 5. Model Context Protocol (MCP) Server
- **Endpoint:** `POST /api/mcp`
- **Description:** Standard MCP JSON-RPC 2.0 interface exposing grid query tools and BESS simulation capabilities.

## Database & Historical Archive
- **Backend:** Supabase Postgres Database.
- **Archive Span:** Continuous 7.6 years (December 31, 2018 to August 20, 2026).
- **Total Records:** 103,182 State Daily PSP rows (`power_state_daily_summary`), 2,721 All-India daily PSP rows (`power_daily_summary`), 8,810 SCADA snapshots (`power_snapshot_summary`), and 30,094 15-minute intraday slots (`power_intraday`).