Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+*.egg-info/
+dist/
+build/
+.DS_Store
+01-environments.md
+02-deployment.md
+03-scaling.md
+04-training.md
+GRIDOPS_SPEC.md
+gemini31.py

Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md openenv.yaml ./
+COPY gridops/ gridops/
+COPY server/ server/
+COPY inference.py scripts/ ./
+
+RUN pip install --no-cache-dir .
+
+EXPOSE 8000
+
+ENV WORKERS=1
+ENV MAX_CONCURRENT_ENVS=10
+
+CMD ["uvicorn", "gridops.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,128 @@
----
-title: Gridops
-emoji: 🔥
-colorFrom: indigo
-colorTo: green
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GridOps — Community Microgrid Bridge Operator
+
+An OpenEnv reinforcement learning environment where an AI agent operates a **100-home community microgrid** in an Indian city during summer. The agent must balance solar generation, battery storage, diesel backup, and grid trade to keep the lights on while minimizing cost and emissions.
+
+## Why This Matters
+
+Community microgrid operation is a real job in India under the RDSS (Revamped Distribution Sector Scheme). IEX prosumer bidding is live. The tension between local energy independence and national grid economics creates genuine multi-day planning challenges that simple heuristics cannot solve.
+
+## Action Space (3 continuous dimensions)
+
+| Action | Range | Description |
+|--------|-------|-------------|
+| `battery_dispatch` | -1.0 to +1.0 | Charge (-100 kW) or discharge (+100 kW) the community battery |
+| `diesel_dispatch` | 0.0 to 1.0 | Diesel generator output (0-100 kW). Rs 100 startup cost. |
+| `demand_shedding` | 0.0 to 1.0 | Request residents reduce usage (0-20%). 50% rebounds next hour. |
+
+**The grid is NOT an action** — it automatically absorbs the residual (capped at ±200 kW). If demand exceeds all supply sources, that's a blackout.
+
+## Observation Space
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `hour` | float | Current hour in episode (0-72) |
+| `demand_kw` | float | Current aggregate demand (kW) |
+| `solar_kw` | float | Current solar generation (kW) |
+| `battery_soc` | float | Battery state-of-charge (0-1) |
+| `grid_price` | float | Current IEX price (Rs/kWh) |
+| `diesel_fuel_remaining` | float | Diesel fuel level (0-1) |
+| `diesel_is_on` | bool | Whether diesel was running last step |
+| `demand_forecast_4h` | list[4] | Noisy demand forecast (±15%) |
+| `solar_forecast_4h` | list[4] | Noisy solar forecast |
+| `price_forecast_4h` | list[4] | Noisy price forecast |
+| `cumulative_blackout_kwh` | float | Total unmet demand |
+| `cumulative_cost` | float | Net cost so far (Rs) |
+| `day_of_episode` | int | Current day (1-3) |
+
+## Episode Structure
+
+- **Duration**: 3 days (72 hours, 1-hour steps)
+- **Why 3 days**: Day 1 = learn the cycle. Day 2 = heatwave hits. Day 3 = multi-day planning tested.
+- **Determinism**: Seeded RNG → identical episodes per seed.
+
+## Tasks (Easy → Medium → Hard)
+
+| Task | Conditions | Challenge |
+|------|-----------|-----------|
+| **Task 1: Normal Summer** | Clear skies, ~100 kW avg demand, Rs 3-12 prices | Battery arbitrage + evening peak management |
+| **Task 2: Heatwave + Clouds** | Day 2-3 heatwave (+30% demand), intermittent clouds, price spikes Rs 18 | Multi-day battery planning under uncertainty |
+| **Task 3: Extreme Crisis** | Full 3-day heatwave, -30% solar, +50% demand, Rs 8-20, limited diesel | Survival mode — all resources constrained |
+
+## Grading (0.0 - 1.0)
+
+```
+score = 0.50 × cost_efficiency + 0.25 × reliability + 0.25 × green_score
+```
+
+- **Cost efficiency**: How much cheaper than a dumb "max grid import, no intelligence" baseline
+- **Reliability**: Fraction of demand met (blackouts penalized via Rs 150/kWh VoLL)
+- **Green score**: 1 - (diesel_used / total_demand)
+
+## Baseline Scores
+
+| Strategy | Task 1 | Task 2 | Task 3 |
+|----------|--------|--------|--------|
+| **Oracle** | 0.81 | 0.82 | 0.77 |
+| Do-Nothing | 0.58 | 0.51 | 0.46 |
+| Always-Discharge | 0.58 | 0.51 | 0.47 |
+| Always-Diesel | 0.42 | 0.42 | 0.45 |
+
+## Key Physics
+
+- **Battery**: 500 kWh, 100 kW max, 90% round-trip efficiency, **Rs 2.5/kWh degradation cost**
+- **Diesel**: 100 kW, Rs 25/kWh, **Rs 100 startup cost** (penalizes on-off cycling)
+- **Demand shedding**: Up to 20%, but **50% rebounds next hour** (no free lunch)
+- **VoLL**: Rs 150/kWh blackout penalty (smooth gradient, no hard gate)
+
+## Setup
+
+```bash
+# Install
+pip install -e .
+
+# Run server
+uvicorn gridops.server.app:app --port 8000
+
+# Dashboard
+open http://localhost:8000/dashboard/
+
+# Oracle test
+python scripts/oracle_test.py
+
+# Inference
+export API_BASE_URL="https://router.huggingface.co/v1"
+export HF_TOKEN="your-token"
+export MODEL_NAME="meta-llama/Llama-3.3-70B-Instruct"
+python inference.py
+```
+
+## Docker
+
+```bash
+docker build -t gridops .
+docker run -p 8000:8000 gridops
+```
+
+## Project Structure
+
+```
+gridops/
+├── inference.py                # LLM baseline (uses OpenAI client)
+├── openenv.yaml                # OpenEnv manifest
+├── Dockerfile
+├── server/app.py               # Root entry point (OpenEnv validate)
+├── gridops/
+│   ├── models.py               # GridOpsAction, GridOpsObservation (Pydantic)
+│   ├── simulation/
+│   │   ├── physics.py          # Energy balance, battery, VoLL, degradation
+│   │   └── scenarios.py        # Demand/solar/price curve generators
+│   ├── tasks/
+│   │   ├── definitions.py      # 3 task configs
+│   │   └── graders.py          # 0-1 grading with cost/reliability/green
+│   └── server/
+│       ├── app.py              # FastAPI + OpenEnv create_app
+│       ├── environment.py      # OpenEnv Environment class
+│       └── static/index.html   # Interactive dashboard
+└── scripts/
+    └── oracle_test.py          # Oracle validation + determinism check
+```

gridops/models.py

@@ -0,0 +1,70 @@
+"""
+Data models for the GridOps Microgrid Environment.
+
+Action:  3 continuous controls (battery_dispatch, diesel_dispatch, demand_shedding)
+         Grid is the SLACK variable — absorbs the residual up to ±200 kW.
+Observation: partial observation of the microgrid state + forecasts.
+"""
+
+from typing import List
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class GridOpsAction(Action):
+    """Agent action — three continuous knobs each step.
+
+    The grid connection is NOT an action. It passively absorbs whatever
+    the community needs after solar + battery + diesel - demand, clamped
+    to the ±200 kW transformer limit. If the grid can't cover the
+    residual, that's a blackout (or curtailment).
+    """
+
+    battery_dispatch: float = Field(
+        default=0.0,
+        ge=-1.0,
+        le=1.0,
+        description="Battery: -1 (charge 100 kW) to +1 (discharge 100 kW)",
+    )
+    diesel_dispatch: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Diesel generator: 0 (off) to 1 (100 kW). Rs 100 startup cost if was off.",
+    )
+    demand_shedding: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Demand response: 0 (none) to 1 (shed 20%). 50% rebounds next hour.",
+    )
+
+
+class GridOpsObservation(Observation):
+    """What the agent sees each hour."""
+
+    # Current state
+    hour: float = Field(default=0.0, description="Hour in episode (0-72)")
+    demand_kw: float = Field(default=0.0, description="Current aggregate demand (kW)")
+    solar_kw: float = Field(default=0.0, description="Current solar generation (kW)")
+    battery_soc: float = Field(default=0.0, description="Battery state-of-charge (0-1)")
+    grid_price: float = Field(default=0.0, description="Current IEX price (Rs/kWh)")
+    diesel_fuel_remaining: float = Field(default=1.0, description="Diesel fuel level (0-1)")
+    diesel_is_on: bool = Field(default=False, description="Whether diesel was running last step")
+
+    # Noisy 4-hour forecasts
+    demand_forecast_4h: List[float] = Field(default_factory=list, description="Demand forecast next 4h")
+    solar_forecast_4h: List[float] = Field(default_factory=list, description="Solar forecast next 4h")
+    price_forecast_4h: List[float] = Field(default_factory=list, description="Price forecast next 4h")
+
+    # Cumulative metrics
+    cumulative_blackout_kwh: float = Field(default=0.0, description="Total unmet demand (kWh)")
+    cumulative_cost: float = Field(default=0.0, description="Net cost so far (Rs)")
+    day_of_episode: int = Field(default=1, description="Current day (1-3)")
+
+    # Step-level feedback
+    blackout_this_step: float = Field(default=0.0, description="Blackout kWh this step")
+    cost_this_step: float = Field(default=0.0, description="Cost incurred this step (Rs)")
+    grid_kw_this_step: float = Field(default=0.0, description="Grid import(+)/export(-) this step")
+    narration: str = Field(default="", description="Human-readable situation summary")

gridops/server/app.py

@@ -0,0 +1,117 @@
+"""
+FastAPI application for the GridOps Microgrid Environment.
+
+Uses OpenEnv's create_app for standard /ws, /health, /schema, /web endpoints.
+Adds custom STATEFUL /reset and /step endpoints for the dashboard (HTTP).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from openenv.core.env_server.http_server import create_app
+
+from gridops.models import GridOpsAction, GridOpsObservation
+from gridops.server.environment import GridOpsEnvironment
+from gridops.tasks.definitions import TASKS
+
+# Create the OpenEnv app (provides /ws, /health, /schema, /web, /docs)
+app = create_app(
+    GridOpsEnvironment,
+    GridOpsAction,
+    GridOpsObservation,
+    env_name="gridops",
+    max_concurrent_envs=int(os.environ.get("MAX_CONCURRENT_ENVS", "10")),
+)
+
+# ── Shared stateful environment for HTTP dashboard ───────────────────────
+# OpenEnv HTTP /reset and /step are stateless (new env per request).
+# The dashboard needs persistent state between reset → step → step...
+# We maintain a single shared environment instance for HTTP usage.
+
+_dashboard_env = GridOpsEnvironment()
+
+
+class ResetBody(BaseModel):
+    seed: int | None = 42
+    task_id: str = "task_1_normal"
+
+
+class StepBody(BaseModel):
+    action: dict[str, Any]
+
+
+@app.post("/api/reset")
+def dashboard_reset(body: ResetBody):
+    """Reset the shared dashboard environment."""
+    obs = _dashboard_env.reset(seed=body.seed, task_id=body.task_id)
+    return {"observation": obs.model_dump()}
+
+
+@app.post("/api/step")
+def dashboard_step(body: StepBody):
+    """Execute one step in the shared dashboard environment."""
+    action = GridOpsAction(**body.action)
+    obs = _dashboard_env.step(action)
+    return {"observation": obs.model_dump()}
+
+
+@app.get("/api/state")
+def dashboard_state():
+    """Get current state of the shared dashboard environment."""
+    return _dashboard_env.state.model_dump()
+
+
+# ── Custom endpoints ─────────────────────────────────────────────────────
+
+@app.get("/tasks")
+def list_tasks():
+    """List available tasks with their descriptions."""
+    return {
+        "tasks": [
+            {
+                "id": "task_1_normal",
+                "name": "Normal Summer",
+                "difficulty": "Easy",
+                "description": "Clear skies, standard demand, Rs 3-12 price range.",
+            },
+            {
+                "id": "task_2_heatwave",
+                "name": "Heatwave + Clouds",
+                "difficulty": "Medium",
+                "description": "Day 2-3 heatwave, +30% demand, price spikes to Rs 18.",
+            },
+            {
+                "id": "task_3_crisis",
+                "name": "Extreme Crisis",
+                "difficulty": "Hard",
+                "description": "Full 3-day heatwave, -30% solar, prices Rs 8-20, limited diesel.",
+            },
+        ]
+    }
+
+
+# ── Serve dashboard static files ────────────────────────────────────────
+
+STATIC_DIR = Path(__file__).parent / "static"
+if STATIC_DIR.exists():
+    app.mount("/dashboard", StaticFiles(directory=str(STATIC_DIR), html=True), name="dashboard")
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=8000)
+    args = parser.parse_args()
+    main(port=args.port)

gridops/server/environment.py

@@ -0,0 +1,180 @@
+"""
+GridOps OpenEnv Environment — wires physics + scenarios + grading together.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+from uuid import uuid4
+
+import numpy as np
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import EnvironmentMetadata, State
+
+from gridops.models import GridOpsAction, GridOpsObservation
+from gridops.simulation import physics, scenarios
+from gridops.simulation.physics import (
+    BATTERY_CAPACITY_KWH,
+    DIESEL_TANK_KWH,
+    MicrogridState,
+)
+from gridops.simulation.scenarios import ScenarioConfig, make_forecast
+from gridops.tasks.definitions import TASKS
+from gridops.tasks.graders import grade_episode
+
+
+class GridOpsState(State):
+    """Extended state exposed via GET /state."""
+
+    task_id: str = "task_1_normal"
+    hour: int = 0
+    done: bool = False
+    grade: dict | None = None
+    history: list[dict] = []
+
+
+class GridOpsEnvironment(Environment):
+    """Community microgrid RL environment."""
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        super().__init__()
+        self._task_id = "task_1_normal"
+        self._cfg: ScenarioConfig = TASKS[self._task_id]
+        self._rng = np.random.default_rng(42)
+        self._demand = np.zeros(72)
+        self._solar = np.zeros(72)
+        self._price = np.zeros(72)
+        self._micro = MicrogridState()
+        self._episode_id = str(uuid4())
+        self._history: list[dict] = []
+        self._grade: dict | None = None
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> GridOpsObservation:
+        task_id = kwargs.get("task_id", "task_1_normal")
+        if task_id not in TASKS:
+            task_id = "task_1_normal"
+
+        self._task_id = task_id
+        self._cfg = TASKS[task_id]
+        self._episode_id = episode_id or str(uuid4())
+
+        s = seed if seed is not None else 42
+        self._rng = np.random.default_rng(s)
+
+        self._demand = scenarios.generate_demand(self._cfg, self._rng)
+        self._solar = scenarios.generate_solar(self._cfg, self._rng)
+        self._price = scenarios.generate_price(self._cfg, self._rng)
+
+        self._micro = MicrogridState(
+            diesel_fuel_kwh=self._cfg.diesel_fuel_capacity * DIESEL_TANK_KWH,
+        )
+        self._history = []
+        self._grade = None
+
+        return self._make_observation(reward=0.0, done=False, narration="Episode started. Day 1 begins.")
+
+    def step(
+        self,
+        action: GridOpsAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> GridOpsObservation:
+        if self._micro.hour >= 72:
+            return self._make_observation(
+                reward=0.0, done=True,
+                narration="Episode already finished.",
+            )
+
+        h = self._micro.hour
+        result = physics.step(
+            self._micro,
+            battery_dispatch_norm=action.battery_dispatch,
+            diesel_norm=action.diesel_dispatch,
+            shed_norm=action.demand_shedding,
+            solar_kw=float(self._solar[h]),
+            demand_kw=float(self._demand[h]),
+            grid_price=float(self._price[h]),
+            diesel_fuel_cap=self._cfg.diesel_fuel_capacity * DIESEL_TANK_KWH,
+        )
+
+        self._history.append({
+            "hour": h,
+            "demand": float(self._demand[h]),
+            "solar": float(self._solar[h]),
+            "price": float(self._price[h]),
+            "battery_soc": self._micro.battery_soc_kwh / BATTERY_CAPACITY_KWH,
+            "blackout": result.state.last_blackout_kwh,
+            "cost": result.state.last_cost,
+            "reward": result.reward,
+            "grid_kw": result.state.last_grid_kw,
+            "battery_dispatch": action.battery_dispatch,
+            "diesel": action.diesel_dispatch,
+            "shedding": action.demand_shedding,
+        })
+
+        if result.done:
+            self._grade = grade_episode(
+                self._micro, self._demand, self._solar, self._price
+            )
+
+        obs = self._make_observation(
+            reward=result.reward,
+            done=result.done,
+            narration=result.narration,
+        )
+        if result.done and self._grade:
+            obs.metadata["grade"] = self._grade
+        return obs
+
+    @property
+    def state(self) -> GridOpsState:
+        return GridOpsState(
+            episode_id=self._episode_id,
+            step_count=self._micro.hour,
+            task_id=self._task_id,
+            hour=self._micro.hour,
+            done=self._micro.hour >= 72,
+            grade=self._grade,
+            history=self._history,
+        )
+
+    def get_metadata(self) -> EnvironmentMetadata:
+        return EnvironmentMetadata(
+            name="GridOps",
+            description="Community microgrid bridge operator — balance solar, battery, diesel, and grid across 3-day episodes.",
+            version="0.2.0",
+        )
+
+    def _make_observation(self, reward: float, done: bool, narration: str) -> GridOpsObservation:
+        h = min(self._micro.hour, 71)
+        rng = self._rng
+
+        return GridOpsObservation(
+            hour=float(self._micro.hour),
+            demand_kw=float(self._demand[h]),
+            solar_kw=float(self._solar[h]),
+            battery_soc=self._micro.battery_soc_kwh / BATTERY_CAPACITY_KWH,
+            grid_price=float(self._price[h]),
+            diesel_fuel_remaining=self._micro.diesel_fuel_kwh / DIESEL_TANK_KWH,
+            diesel_is_on=self._micro.diesel_was_on,
+            demand_forecast_4h=make_forecast(self._demand, h, 4, self._cfg.forecast_noise, rng),
+            solar_forecast_4h=make_forecast(self._solar, h, 4, self._cfg.forecast_noise, rng),
+            price_forecast_4h=make_forecast(self._price, h, 4, self._cfg.forecast_noise, rng),
+            cumulative_blackout_kwh=self._micro.cumulative_blackout_kwh,
+            cumulative_cost=self._micro.cumulative_cost,
+            day_of_episode=(self._micro.hour // 24) + 1,
+            blackout_this_step=self._micro.last_blackout_kwh,
+            cost_this_step=self._micro.last_cost,
+            grid_kw_this_step=self._micro.last_grid_kw,
+            narration=narration,
+            done=done,
+            reward=reward,
+        )

gridops/server/static/index.html

@@ -0,0 +1,847 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>GridOps — Microgrid Operator</title>
+<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
+<style>
+  /* ── Reset & Base ─────────────────────────────────────────── */
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  :root {
+    --bg:       #0a0e17;
+    --panel:    #111827;
+    --border:   #1e293b;
+    --cyan:     #06b6d4;
+    --cyan-dim: #0891b2;
+    --red:      #ef4444;
+    --yellow:   #eab308;
+    --green:    #22c55e;
+    --blue:     #3b82f6;
+    --orange:   #f97316;
+    --text:     #e2e8f0;
+    --text-dim: #94a3b8;
+    --grid-bg:  rgba(6,182,212,0.03);
+  }
+  body {
+    font-family: 'JetBrains Mono', 'Fira Code', 'SF Mono', monospace;
+    background: var(--bg);
+    color: var(--text);
+    min-height: 100vh;
+    background-image:
+      linear-gradient(rgba(6,182,212,0.04) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(6,182,212,0.04) 1px, transparent 1px);
+    background-size: 40px 40px;
+  }
+
+  /* ── Header ───────────────────────────────────────────────── */
+  header {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 12px 24px;
+    border-bottom: 1px solid var(--border);
+    background: rgba(17,24,39,0.9);
+    backdrop-filter: blur(8px);
+  }
+  .logo { display: flex; align-items: center; gap: 10px; }
+  .logo svg { width: 28px; height: 28px; }
+  .logo h1 { font-size: 18px; font-weight: 600; letter-spacing: 1px; }
+  .logo h1 span { color: var(--cyan); }
+  .header-info { display: flex; gap: 20px; font-size: 12px; color: var(--text-dim); }
+  .header-info .tag {
+    padding: 3px 10px; border-radius: 4px;
+    border: 1px solid var(--border);
+    background: rgba(6,182,212,0.08);
+  }
+  .tag.easy { border-color: var(--green); color: var(--green); }
+  .tag.medium { border-color: var(--yellow); color: var(--yellow); }
+  .tag.hard { border-color: var(--red); color: var(--red); }
+
+  /* ── Layout ───────────────────────────────────────────────── */
+  .app { display: grid; grid-template-columns: 280px 1fr 260px; gap: 0; height: calc(100vh - 52px); }
+
+  /* ── Left Panel (Controls) ────────────────────────────────── */
+  .panel-left {
+    padding: 16px;
+    border-right: 1px solid var(--border);
+    background: var(--panel);
+    display: flex; flex-direction: column; gap: 14px;
+    overflow-y: auto;
+  }
+  .section-title {
+    font-size: 10px; text-transform: uppercase; letter-spacing: 2px;
+    color: var(--cyan); margin-bottom: 4px;
+  }
+  .control-group { display: flex; flex-direction: column; gap: 6px; }
+  .control-group label {
+    font-size: 11px; color: var(--text-dim);
+    display: flex; justify-content: space-between;
+  }
+  .control-group label .val { color: var(--cyan); font-weight: 600; }
+  input[type="range"] {
+    -webkit-appearance: none; width: 100%; height: 6px;
+    background: var(--border); border-radius: 3px; outline: none;
+  }
+  input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none; width: 16px; height: 16px;
+    border-radius: 50%; background: var(--cyan); cursor: pointer;
+    box-shadow: 0 0 8px rgba(6,182,212,0.5);
+  }
+  .btn-step {
+    width: 100%; padding: 12px; margin-top: 8px;
+    background: linear-gradient(135deg, var(--cyan-dim), var(--cyan));
+    color: #000; border: none; border-radius: 6px;
+    font-family: inherit; font-size: 13px; font-weight: 700;
+    cursor: pointer; letter-spacing: 1px;
+    transition: all 0.15s;
+  }
+  .btn-step:hover { transform: translateY(-1px); box-shadow: 0 4px 20px rgba(6,182,212,0.4); }
+  .btn-step:active { transform: translateY(0); }
+  .btn-step:disabled { opacity: 0.4; cursor: not-allowed; transform: none; }
+  .btn-reset {
+    width: 100%; padding: 8px;
+    background: transparent; color: var(--text-dim);
+    border: 1px solid var(--border); border-radius: 6px;
+    font-family: inherit; font-size: 11px; cursor: pointer;
+  }
+  .btn-reset:hover { border-color: var(--cyan); color: var(--cyan); }
+  select {
+    width: 100%; padding: 8px; background: var(--bg); color: var(--text);
+    border: 1px solid var(--border); border-radius: 4px;
+    font-family: inherit; font-size: 12px;
+  }
+  .info-row {
+    display: flex; justify-content: space-between;
+    font-size: 11px; padding: 4px 0;
+    border-bottom: 1px solid rgba(30,41,59,0.5);
+  }
+  .info-row .label { color: var(--text-dim); }
+
+  /* ── Center Panel (Visualization) ─────────────────────────── */
+  .panel-center {
+    display: flex; flex-direction: column; gap: 0;
+    overflow: hidden;
+  }
+  .chart-container {
+    flex: 1; padding: 12px; min-height: 0;
+    position: relative;
+  }
+  .chart-container canvas { width: 100% !important; height: 100% !important; }
+
+  /* Energy flow diagram */
+  .flow-section {
+    height: 180px; padding: 12px 20px;
+    border-top: 1px solid var(--border);
+    display: flex; align-items: center; justify-content: center;
+    position: relative;
+  }
+  .flow-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr 1fr;
+    grid-template-rows: auto auto auto;
+    gap: 8px; width: 100%; max-width: 600px;
+    text-align: center; font-size: 11px;
+  }
+  .flow-node {
+    padding: 10px 6px; border-radius: 6px;
+    border: 1px solid var(--border);
+    background: rgba(17,24,39,0.8);
+    position: relative;
+  }
+  .flow-node .node-icon { font-size: 20px; display: block; margin-bottom: 2px; }
+  .flow-node .node-val { color: var(--cyan); font-weight: 600; font-size: 13px; }
+  .flow-node .node-label { color: var(--text-dim); font-size: 9px; text-transform: uppercase; letter-spacing: 1px; }
+  .flow-node.solar { border-color: var(--yellow); }
+  .flow-node.battery { border-color: var(--blue); }
+  .flow-node.grid { border-color: var(--green); }
+  .flow-node.diesel { border-color: var(--orange); }
+  .flow-node.community { border-color: var(--cyan); background: rgba(6,182,212,0.08); grid-column: 2; }
+  .flow-node.blackout { border-color: var(--red); animation: pulse-red 1s infinite; }
+  @keyframes pulse-red { 0%,100% { box-shadow: 0 0 0 rgba(239,68,68,0); } 50% { box-shadow: 0 0 16px rgba(239,68,68,0.4); } }
+  .flow-arrow { color: var(--text-dim); font-size: 14px; display: flex; align-items: center; justify-content: center; }
+
+  /* Narration bar */
+  .narration {
+    padding: 10px 20px; font-size: 12px;
+    border-top: 1px solid var(--border);
+    background: rgba(6,182,212,0.04);
+    color: var(--text-dim);
+    min-height: 36px;
+  }
+  .narration strong { color: var(--cyan); }
+
+  /* ── Right Panel (Scores) ─────────────────────────────────── */
+  .panel-right {
+    padding: 16px;
+    border-left: 1px solid var(--border);
+    background: var(--panel);
+    display: flex; flex-direction: column; gap: 12px;
+    overflow-y: auto;
+  }
+  .score-card {
+    padding: 12px; border-radius: 6px;
+    border: 1px solid var(--border);
+    background: rgba(10,14,23,0.6);
+  }
+  .score-card .sc-label {
+    font-size: 9px; text-transform: uppercase; letter-spacing: 2px;
+    color: var(--text-dim); margin-bottom: 4px;
+  }
+  .score-card .sc-value {
+    font-size: 24px; font-weight: 700;
+  }
+  .score-card .sc-bar {
+    height: 4px; border-radius: 2px; margin-top: 6px;
+    background: var(--border);
+    overflow: hidden;
+  }
+  .score-card .sc-bar-fill {
+    height: 100%; border-radius: 2px;
+    transition: width 0.3s;
+  }
+  .sc-value.good { color: var(--green); }
+  .sc-value.warn { color: var(--yellow); }
+  .sc-value.bad  { color: var(--red); }
+  .sc-value.cyan { color: var(--cyan); }
+
+  .grade-box {
+    padding: 16px; border-radius: 8px;
+    border: 2px solid var(--cyan);
+    background: rgba(6,182,212,0.06);
+    text-align: center;
+  }
+  .grade-box .grade-label { font-size: 10px; text-transform: uppercase; letter-spacing: 2px; color: var(--text-dim); }
+  .grade-box .grade-value { font-size: 42px; font-weight: 800; color: var(--cyan); margin: 4px 0; }
+  .grade-box .grade-sub { font-size: 11px; color: var(--text-dim); }
+  .grade-box.hidden { display: none; }
+
+  /* ── Intro Modal ───────────────────────────────────────────── */
+  .intro-overlay {
+    position: fixed; inset: 0; z-index: 1000;
+    background: rgba(10,14,23,0.92);
+    backdrop-filter: blur(12px);
+    display: flex; align-items: center; justify-content: center;
+    animation: fadeIn 0.4s ease;
+  }
+  @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
+  .intro-overlay.hidden { display: none; }
+
+  .intro-card {
+    max-width: 720px; width: 90%; max-height: 90vh;
+    overflow-y: auto;
+    padding: 40px 44px;
+    border-radius: 16px;
+    border: 1px solid var(--cyan);
+    background: linear-gradient(160deg, rgba(17,24,39,0.98), rgba(10,14,23,0.99));
+    box-shadow: 0 0 60px rgba(6,182,212,0.15), 0 0 120px rgba(6,182,212,0.05);
+    animation: cardIn 0.5s ease;
+  }
+  @keyframes cardIn { from { transform: scale(0.95) translateY(20px); opacity: 0; } to { transform: scale(1) translateY(0); opacity: 1; } }
+
+  .intro-card .intro-bolt {
+    display: flex; align-items: center; gap: 14px;
+    margin-bottom: 24px;
+  }
+  .intro-card .intro-bolt svg { width: 42px; height: 42px; filter: drop-shadow(0 0 12px rgba(6,182,212,0.6)); }
+  .intro-card .intro-bolt h1 { font-size: 32px; font-weight: 800; letter-spacing: 2px; }
+  .intro-card .intro-bolt h1 span { color: var(--cyan); }
+
+  .intro-card .tagline {
+    font-size: 15px; color: var(--cyan); font-weight: 600;
+    margin-bottom: 20px; letter-spacing: 0.5px;
+  }
+
+  .intro-card .story {
+    font-size: 14px; line-height: 1.75; color: var(--text);
+    margin-bottom: 20px;
+  }
+  .intro-card .story p { margin-bottom: 12px; }
+  .intro-card .story strong { color: var(--cyan); font-weight: 600; }
+  .intro-card .story .highlight {
+    color: var(--yellow);
+  }
+  .intro-card .story .danger {
+    color: var(--red);
+  }
+
+  .intro-card .the-catch {
+    background: rgba(239,68,68,0.08);
+    border: 1px solid rgba(239,68,68,0.25);
+    border-radius: 8px;
+    padding: 14px 18px;
+    margin-bottom: 20px;
+    font-size: 13px; line-height: 1.7;
+    color: var(--text);
+  }
+  .intro-card .the-catch .catch-title {
+    color: var(--red); font-weight: 700; font-size: 12px;
+    text-transform: uppercase; letter-spacing: 2px;
+    margin-bottom: 6px;
+  }
+
+  .intro-card .controls-preview {
+    display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 10px;
+    margin-bottom: 22px;
+  }
+  .intro-card .cp-item {
+    background: rgba(6,182,212,0.06);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px;
+    text-align: center;
+  }
+  .cp-item .cp-icon { font-size: 22px; display: block; margin-bottom: 4px; }
+  .cp-item .cp-name { font-size: 11px; font-weight: 700; color: var(--cyan); text-transform: uppercase; letter-spacing: 1px; }
+  .cp-item .cp-desc { font-size: 10px; color: var(--text-dim); margin-top: 3px; }
+
+  .intro-card .scoring {
+    display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px;
+    margin-bottom: 24px;
+  }
+  .intro-card .sc-item {
+    text-align: center; padding: 10px;
+    border-radius: 6px;
+    border: 1px solid var(--border);
+  }
+  .sc-item .sc-pct { font-size: 22px; font-weight: 800; }
+  .sc-item .sc-what { font-size: 10px; color: var(--text-dim); text-transform: uppercase; letter-spacing: 1px; }
+
+  .intro-card .tasks-preview {
+    display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px;
+    margin-bottom: 24px;
+  }
+  .intro-card .tp-item {
+    padding: 10px 12px; border-radius: 6px;
+    border: 1px solid var(--border);
+    font-size: 11px;
+  }
+  .tp-item .tp-name { font-weight: 700; margin-bottom: 3px; }
+  .tp-item .tp-desc { color: var(--text-dim); font-size: 10px; line-height: 1.5; }
+  .tp-easy .tp-name { color: var(--green); }
+  .tp-med .tp-name { color: var(--yellow); }
+  .tp-hard .tp-name { color: var(--red); }
+
+  .intro-card .btn-start {
+    width: 100%; padding: 16px;
+    background: linear-gradient(135deg, var(--cyan-dim), var(--cyan));
+    color: #000; border: none; border-radius: 8px;
+    font-family: inherit; font-size: 15px; font-weight: 800;
+    cursor: pointer; letter-spacing: 2px;
+    text-transform: uppercase;
+    transition: all 0.2s;
+  }
+  .btn-start:hover { transform: translateY(-2px); box-shadow: 0 8px 30px rgba(6,182,212,0.4); }
+
+  .intro-card .shortcut-hint {
+    text-align: center; margin-top: 10px;
+    font-size: 10px; color: var(--text-dim);
+  }
+
+  /* ── Responsive ───────────────────────────────────────────── */
+  @media (max-width: 960px) {
+    .app { grid-template-columns: 1fr; grid-template-rows: auto 1fr auto; }
+    .panel-left, .panel-right { flex-direction: row; flex-wrap: wrap; border: none; border-bottom: 1px solid var(--border); }
+    .intro-card { padding: 24px; }
+    .controls-preview, .scoring, .tasks-preview { grid-template-columns: 1fr; }
+  }
+</style>
+</head>
+<body>
+
+<!-- ── Intro Overlay ───────────────────────────────────────────── -->
+<div class="intro-overlay" id="introOverlay">
+  <div class="intro-card">
+    <div class="intro-bolt">
+      <svg viewBox="0 0 24 24" fill="none" stroke="var(--cyan)" stroke-width="2.5">
+        <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/>
+      </svg>
+      <h1>GRID<span>OPS</span></h1>
+    </div>
+
+    <div class="tagline">Community Microgrid Bridge Operator</div>
+
+    <div class="story">
+      <p>
+        Imagine you're in charge of keeping the lights on for <strong>100 homes</strong> in an Indian city during a brutal summer.
+      </p>
+      <p>
+        You have <span class="highlight">rooftop solar panels</span> (free energy from the sun!),
+        a big <strong>community battery</strong> (stores energy for later),
+        an expensive <span class="danger">diesel backup generator</span> (costs a fortune),
+        and a connection to the <strong>national power grid</strong> (prices change every hour).
+      </p>
+      <p>
+        Every hour, you make 3 decisions: How much power to <strong>buy or sell</strong> from the grid.
+        Whether to turn on the <span class="danger">diesel generator</span>.
+        And whether to ask residents to <strong>use less power</strong> for a bit.
+      </p>
+      <p>
+        The battery? You don't control it directly. It <strong>automatically absorbs</strong> whatever energy is left over (or fills the gap when there's not enough).
+      </p>
+    </div>
+
+    <div class="the-catch">
+      <div class="catch-title">The catch</div>
+      At <strong>8 PM every evening</strong>, everyone turns on their AC. Demand hits <strong>250 kW</strong>.
+      But the grid connection maxes out at <strong>200 kW</strong>. That's a <strong>50 kW gap</strong>.
+      Your battery can cover it &mdash; <em>if you charged it during the day</em>.
+      If it's empty because you discharged it for profit?
+      <span style="color:var(--red);font-weight:700">Blackout. Rs 150/kWh penalty.</span>
+      On a heatwave day, demand spikes to <strong>375 kW</strong> and you'll need <em>everything</em>
+      &mdash; battery, diesel, shedding &mdash; just to survive.
+    </div>
+
+    <div class="controls-preview">
+      <div class="cp-item">
+        <span class="cp-icon">&#128267;</span>
+        <div class="cp-name">Battery</div>
+        <div class="cp-desc">Charge or discharge. -100 to +100 kW. Rs 2.5/kWh degradation.</div>
+      </div>
+      <div class="cp-item">
+        <span class="cp-icon">&#9981;</span>
+        <div class="cp-name">Diesel</div>
+        <div class="cp-desc">Emergency backup. Rs 25/kWh + Rs 100 startup cost.</div>
+      </div>
+      <div class="cp-item">
+        <span class="cp-icon">&#127968;</span>
+        <div class="cp-name">Demand Shed</div>
+        <div class="cp-desc">Ask residents to cut usage. Up to 20%. 50% rebounds next hour.</div>
+      </div>
+    </div>
+
+    <div class="the-catch" style="border-color: rgba(6,182,212,0.3); background: rgba(6,182,212,0.05); margin-bottom: 20px;">
+      <div class="catch-title" style="color: var(--cyan);">The grid is your safety net</div>
+      The national grid <strong>automatically</strong> absorbs whatever is left over &mdash;
+      importing when you're short, exporting when you have surplus. But it's capped at
+      <strong>200 kW</strong>. If your community needs more than that, you'd better have
+      battery charge, diesel, or demand shedding ready.
+    </div>
+
+    <div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:2px;margin-bottom:8px;">Your score is graded on</div>
+    <div class="scoring">
+      <div class="sc-item">
+        <div class="sc-pct" style="color:var(--cyan)">60%</div>
+        <div class="sc-what">Cost Savings</div>
+      </div>
+      <div class="sc-item">
+        <div class="sc-pct" style="color:var(--green)">20%</div>
+        <div class="sc-what">Reliability</div>
+      </div>
+      <div class="sc-item">
+        <div class="sc-pct" style="color:#22d3ee">20%</div>
+        <div class="sc-what">Green Score</div>
+      </div>
+    </div>
+
+    <div style="font-size:11px;color:var(--text-dim);text-transform:uppercase;letter-spacing:2px;margin-bottom:8px;">3 escalating tasks</div>
+    <div class="tasks-preview">
+      <div class="tp-item tp-easy">
+        <div class="tp-name">Task 1: Normal Summer</div>
+        <div class="tp-desc">Clear skies. Smooth prices. Learn the daily cycle.</div>
+      </div>
+      <div class="tp-item tp-med">
+        <div class="tp-name">Task 2: Heatwave</div>
+        <div class="tp-desc">Day 2 heatwave. +30% demand. Price spikes. Battery decisions from Day 1 matter.</div>
+      </div>
+      <div class="tp-item tp-hard">
+        <div class="tp-name">Task 3: Crisis</div>
+        <div class="tp-desc">3-day heatwave. Solar drops 30%. Limited diesel. Survival mode.</div>
+      </div>
+    </div>
+
+    <button class="btn-start" id="btnStart">Start Operating</button>
+    <div class="shortcut-hint">Press <strong>Space</strong> or <strong>Enter</strong> to advance each hour &middot; <strong>R</strong> to reset</div>
+  </div>
+</div>
+
+<!-- ── Header ──────────────────────────────────────────────────── -->
+<header>
+  <div class="logo">
+    <svg viewBox="0 0 24 24" fill="none" stroke="var(--cyan)" stroke-width="2">
+      <path d="M13 2L3 14h9l-1 8 10-12h-9l1-8z"/>
+    </svg>
+    <h1>GRID<span>OPS</span></h1>
+  </div>
+  <div class="header-info">
+    <span id="taskTag" class="tag easy">Task 1: Normal</span>
+    <span>Hour <strong id="hourDisp">0</strong>/72</span>
+    <span>Day <strong id="dayDisp">1</strong></span>
+  </div>
+</header>
+
+<div class="app">
+  <!-- ── Left Panel ──────────────────────────────────────────── -->
+  <div class="panel-left">
+    <div>
+      <div class="section-title">Task Selection</div>
+      <select id="taskSelect">
+        <option value="task_1_normal">Task 1 — Normal Summer (Easy)</option>
+        <option value="task_2_heatwave">Task 2 — Heatwave + Clouds (Medium)</option>
+        <option value="task_3_crisis">Task 3 — Extreme Crisis (Hard)</option>
+      </select>
+    </div>
+
+    <div>
+      <div class="section-title">Agent Controls</div>
+      <div class="control-group">
+        <label>Battery <span class="val" id="batteryVal">0 kW</span></label>
+        <input type="range" id="batterySlider" min="-100" max="100" value="0" step="1">
+        <div style="display:flex;justify-content:space-between;font-size:9px;color:var(--text-dim)">
+          <span>Charge 100kW</span><span>Discharge 100kW</span>
+        </div>
+      </div>
+      <div class="control-group">
+        <label>Diesel Output <span class="val" id="dieselVal">0 kW</span></label>
+        <input type="range" id="dieselSlider" min="0" max="100" value="0" step="1">
+        <div style="font-size:9px;color:var(--text-dim)">Rs 25/kWh + Rs 100 startup</div>
+      </div>
+      <div class="control-group">
+        <label>Demand Shedding <span class="val" id="shedVal">0%</span></label>
+        <input type="range" id="shedSlider" min="0" max="100" value="0" step="1">
+        <div style="font-size:9px;color:var(--text-dim)">50% rebounds next hour</div>
+      </div>
+    </div>
+
+    <button class="btn-step" id="stepBtn">NEXT HOUR →</button>
+    <button class="btn-reset" id="resetBtn">Reset Episode</button>
+
+    <div>
+      <div class="section-title">Current Conditions</div>
+      <div class="info-row"><span class="label">Grid Price</span><span id="priceInfo">—</span></div>
+      <div class="info-row"><span class="label">Demand</span><span id="demandInfo">—</span></div>
+      <div class="info-row"><span class="label">Solar</span><span id="solarInfo">—</span></div>
+      <div class="info-row"><span class="label">Battery SOC</span><span id="socInfo">—</span></div>
+      <div class="info-row"><span class="label">Diesel Fuel</span><span id="fuelInfo">—</span></div>
+    </div>
+
+    <div>
+      <div class="section-title">4-Hour Forecast</div>
+      <div class="info-row"><span class="label">Demand</span><span id="fcDemand">—</span></div>
+      <div class="info-row"><span class="label">Solar</span><span id="fcSolar">—</span></div>
+      <div class="info-row"><span class="label">Price</span><span id="fcPrice">—</span></div>
+    </div>
+  </div>
+
+  <!-- ── Center Panel ────────────────────────────────────────── -->
+  <div class="panel-center">
+    <div class="chart-container">
+      <canvas id="mainChart"></canvas>
+    </div>
+    <div class="flow-section">
+      <div class="flow-grid">
+        <div class="flow-node solar">
+          <span class="node-icon">☀️</span>
+          <span class="node-val" id="flowSolar">0</span>
+          <span class="node-label">Solar kW</span>
+        </div>
+        <div class="flow-node community" id="flowCommunity">
+          <span class="node-icon">🏘️</span>
+          <span class="node-val" id="flowDemand">0</span>
+          <span class="node-label">Demand kW</span>
+        </div>
+        <div class="flow-node grid">
+          <span class="node-icon">⚡</span>
+          <span class="node-val" id="flowGrid">0</span>
+          <span class="node-label">Grid kW</span>
+        </div>
+        <div class="flow-node battery">
+          <span class="node-icon">🔋</span>
+          <span class="node-val" id="flowBattery">50%</span>
+          <span class="node-label">Battery</span>
+        </div>
+        <div class="flow-node diesel">
+          <span class="node-icon">⛽</span>
+          <span class="node-val" id="flowDiesel">0</span>
+          <span class="node-label">Diesel kW</span>
+        </div>
+        <div class="flow-node" id="flowStatus" style="border-color:var(--green)">
+          <span class="node-icon" id="statusIcon">✅</span>
+          <span class="node-val" id="statusText" style="color:var(--green)">OK</span>
+          <span class="node-label">Status</span>
+        </div>
+      </div>
+    </div>
+    <div class="narration" id="narration">
+      <strong>Ready.</strong> Select a task and click "Next Hour" to begin.
+    </div>
+  </div>
+
+  <!-- ── Right Panel ─────────────────────────────────────────── -->
+  <div class="panel-right">
+    <div class="grade-box hidden" id="gradeBox">
+      <div class="grade-label">Episode Score</div>
+      <div class="grade-value" id="gradeValue">—</div>
+      <div class="grade-sub" id="gradeSub"></div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Reliability</div>
+      <div class="sc-value good" id="relValue">100%</div>
+      <div class="sc-bar"><div class="sc-bar-fill" id="relBar" style="width:100%;background:var(--green)"></div></div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Net Cost</div>
+      <div class="sc-value cyan" id="costValue">Rs 0</div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Diesel Used</div>
+      <div class="sc-value" id="dieselUsed" style="color:var(--orange)">0 kWh</div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Battery SOC</div>
+      <div class="sc-value cyan" id="socValue">50%</div>
+      <div class="sc-bar"><div class="sc-bar-fill" id="socBar" style="width:50%;background:var(--blue)"></div></div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Total Blackout</div>
+      <div class="sc-value good" id="blackoutValue">0 kWh</div>
+    </div>
+
+    <div class="score-card">
+      <div class="sc-label">Step Reward</div>
+      <div class="sc-value cyan" id="rewardValue">—</div>
+    </div>
+  </div>
+</div>
+
+<script>
+// ── Config ──────────────────────────────────────────────────────
+const API = window.location.origin + '/api';
+let obs = null;
+let running = false;
+
+// ── Chart setup ─────────────────────────────────────────────────
+const chartData = {
+  demand: [], solar: [], price: [], soc: [], hours: [], blackout: []
+};
+
+const ctx = document.getElementById('mainChart').getContext('2d');
+const chart = new Chart(ctx, {
+  type: 'line',
+  data: {
+    labels: chartData.hours,
+    datasets: [
+      { label: 'Demand (kW)', data: chartData.demand, borderColor: '#ef4444', backgroundColor: 'rgba(239,68,68,0.1)', borderWidth: 1.5, pointRadius: 0, tension: 0.3, yAxisID: 'y' },
+      { label: 'Solar (kW)', data: chartData.solar, borderColor: '#eab308', backgroundColor: 'rgba(234,179,8,0.1)', borderWidth: 1.5, pointRadius: 0, tension: 0.3, yAxisID: 'y' },
+      { label: 'Price (Rs/kWh)', data: chartData.price, borderColor: '#22c55e', borderDash: [4,2], borderWidth: 1.5, pointRadius: 0, tension: 0.3, yAxisID: 'y1' },
+      { label: 'Battery SOC', data: chartData.soc, borderColor: '#3b82f6', backgroundColor: 'rgba(59,130,246,0.15)', borderWidth: 1.5, pointRadius: 0, tension: 0.3, fill: true, yAxisID: 'y2' },
+    ]
+  },
+  options: {
+    responsive: true, maintainAspectRatio: false,
+    animation: { duration: 150 },
+    interaction: { intersect: false, mode: 'index' },
+    plugins: {
+      legend: { position: 'top', labels: { color: '#94a3b8', font: { size: 10, family: 'monospace' }, boxWidth: 12, padding: 8 } }
+    },
+    scales: {
+      x: { grid: { color: 'rgba(30,41,59,0.5)' }, ticks: { color: '#64748b', font: { size: 9 }, maxTicksLimit: 24 } },
+      y:  { position: 'left', grid: { color: 'rgba(30,41,59,0.3)' }, ticks: { color: '#94a3b8', font: { size: 9 } }, title: { display: true, text: 'kW', color: '#64748b' }, min: 0 },
+      y1: { position: 'right', grid: { display: false }, ticks: { color: '#22c55e', font: { size: 9 } }, title: { display: true, text: 'Rs/kWh', color: '#22c55e' }, min: 0, max: 25 },
+      y2: { display: false, min: 0, max: 1 },
+    }
+  }
+});
+
+// ── Slider labels ───────────────────────────────────────────────
+const batterySlider = document.getElementById('batterySlider');
+const dieselSlider = document.getElementById('dieselSlider');
+const shedSlider = document.getElementById('shedSlider');
+
+batterySlider.oninput = () => {
+  const v = batterySlider.value;
+  const kw = (v / 100 * 100).toFixed(0);
+  const label = v < 0 ? `Charge ${Math.abs(kw)} kW` : v > 0 ? `Discharge ${kw} kW` : '0 kW';
+  document.getElementById('batteryVal').textContent = label;
+};
+dieselSlider.oninput = () => {
+  document.getElementById('dieselVal').textContent = (dieselSlider.value / 100 * 100).toFixed(0) + ' kW';
+};
+shedSlider.oninput = () => {
+  document.getElementById('shedVal').textContent = (shedSlider.value / 100 * 20).toFixed(0) + '%';
+};
+
+// ── API calls ───────────────────────────────────────────────────
+async function apiPost(path, body) {
+  const res = await fetch(API + path, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body)
+  });
+  return res.json();
+}
+
+async function resetEnv() {
+  const taskId = document.getElementById('taskSelect').value;
+  const body = { seed: 42, task_id: taskId };
+  const resp = await apiPost('/reset', body);
+  obs = resp.observation || resp;
+  chartData.demand.length = 0;
+  chartData.solar.length = 0;
+  chartData.price.length = 0;
+  chartData.soc.length = 0;
+  chartData.hours.length = 0;
+  chartData.blackout.length = 0;
+  chart.update();
+  updateUI();
+  document.getElementById('gradeBox').classList.add('hidden');
+  document.getElementById('stepBtn').disabled = false;
+  running = true;
+  updateTaskTag();
+}
+
+async function stepEnv() {
+  if (!running) return;
+  const action = {
+    battery_dispatch: batterySlider.value / 100,
+    diesel_dispatch: dieselSlider.value / 100,
+    demand_shedding: shedSlider.value / 100,
+  };
+  const resp = await apiPost('/step', { action });
+  obs = resp.observation || resp;
+
+  // Update chart
+  chartData.hours.push(obs.hour);
+  chartData.demand.push(obs.demand_kw);
+  chartData.solar.push(obs.solar_kw);
+  chartData.price.push(obs.grid_price);
+  chartData.soc.push(obs.battery_soc);
+  chartData.blackout.push(obs.blackout_this_step || 0);
+  chart.update();
+
+  updateUI();
+
+  if (obs.done) {
+    running = false;
+    document.getElementById('stepBtn').disabled = true;
+    // Fetch final state for grade
+    try {
+      const stateResp = await fetch(API + '/state');
+      const stateData = await stateResp.json();
+      if (stateData.grade) showGrade(stateData.grade);
+      else if (obs.metadata && obs.metadata.grade) showGrade(obs.metadata.grade);
+    } catch(e) {
+      if (obs.metadata && obs.metadata.grade) showGrade(obs.metadata.grade);
+    }
+  }
+}
+
+// ── UI update ───────────────────────────────────────────────────
+function updateUI() {
+  if (!obs) return;
+  document.getElementById('hourDisp').textContent = Math.floor(obs.hour);
+  document.getElementById('dayDisp').textContent = obs.day_of_episode || Math.floor(obs.hour / 24) + 1;
+
+  // Info panel
+  document.getElementById('priceInfo').textContent = 'Rs ' + (obs.grid_price || 0).toFixed(1) + '/kWh';
+  document.getElementById('demandInfo').textContent = (obs.demand_kw || 0).toFixed(0) + ' kW';
+  document.getElementById('solarInfo').textContent = (obs.solar_kw || 0).toFixed(0) + ' kW';
+  document.getElementById('socInfo').textContent = ((obs.battery_soc || 0) * 100).toFixed(0) + '%';
+  document.getElementById('fuelInfo').textContent = ((obs.diesel_fuel_remaining || 0) * 100).toFixed(0) + '%';
+
+  // Forecasts
+  const fmt = arr => arr ? arr.map(v => v.toFixed(0)).join(' → ') : '—';
+  document.getElementById('fcDemand').textContent = fmt(obs.demand_forecast_4h);
+  document.getElementById('fcSolar').textContent = fmt(obs.solar_forecast_4h);
+  document.getElementById('fcPrice').textContent = obs.price_forecast_4h ? obs.price_forecast_4h.map(v => v.toFixed(1)).join(' → ') : '—';
+
+  // Flow diagram
+  document.getElementById('flowSolar').textContent = (obs.solar_kw || 0).toFixed(0);
+  document.getElementById('flowDemand').textContent = (obs.demand_kw || 0).toFixed(0);
+  const gridKw = obs.grid_kw_this_step || 0;
+  document.getElementById('flowGrid').textContent = (gridKw >= 0 ? '+' : '') + gridKw.toFixed(0) + ' (slack)';
+  document.getElementById('flowBattery').textContent = ((obs.battery_soc || 0) * 100).toFixed(0) + '%';
+  document.getElementById('flowDiesel').textContent = (dieselSlider.value / 100 * 100).toFixed(0);
+
+  // Status
+  const blackout = obs.blackout_this_step || 0;
+  const statusNode = document.getElementById('flowStatus');
+  const statusIcon = document.getElementById('statusIcon');
+  const statusText = document.getElementById('statusText');
+  if (blackout > 0) {
+    statusNode.className = 'flow-node blackout';
+    statusIcon.textContent = '🚨';
+    statusText.textContent = 'BLACKOUT';
+    statusText.style.color = 'var(--red)';
+  } else {
+    statusNode.className = 'flow-node';
+    statusNode.style.borderColor = 'var(--green)';
+    statusIcon.textContent = '✅';
+    statusText.textContent = 'OK';
+    statusText.style.color = 'var(--green)';
+  }
+
+  // Narration
+  document.getElementById('narration').innerHTML = '<strong>System:</strong> ' + (obs.narration || '');
+
+  // Right panel scores
+  const totalDemandApprox = Math.max(obs.hour * 300, 1);
+  const reliability = totalDemandApprox > 0 ? Math.max(0, 1 - (obs.cumulative_blackout_kwh || 0) / totalDemandApprox) : 1;
+  const relPct = (reliability * 100).toFixed(1);
+  const relEl = document.getElementById('relValue');
+  relEl.textContent = relPct + '%';
+  relEl.className = 'sc-value ' + (reliability > 0.95 ? 'good' : reliability > 0.9 ? 'warn' : 'bad');
+  document.getElementById('relBar').style.width = relPct + '%';
+  document.getElementById('relBar').style.background = reliability > 0.95 ? 'var(--green)' : reliability > 0.9 ? 'var(--yellow)' : 'var(--red)';
+
+  document.getElementById('costValue').textContent = 'Rs ' + (obs.cumulative_cost || 0).toFixed(0);
+  document.getElementById('blackoutValue').textContent = (obs.cumulative_blackout_kwh || 0).toFixed(1) + ' kWh';
+  const bvEl = document.getElementById('blackoutValue');
+  bvEl.className = 'sc-value ' + ((obs.cumulative_blackout_kwh || 0) < 1 ? 'good' : 'bad');
+
+  const socPct = ((obs.battery_soc || 0) * 100).toFixed(0);
+  document.getElementById('socValue').textContent = socPct + '%';
+  document.getElementById('socBar').style.width = socPct + '%';
+
+  document.getElementById('rewardValue').textContent = (obs.reward != null ? obs.reward.toFixed(3) : '—');
+}
+
+function showGrade(g) {
+  const box = document.getElementById('gradeBox');
+  box.classList.remove('hidden');
+  document.getElementById('gradeValue').textContent = g.score.toFixed(3);
+  document.getElementById('gradeSub').innerHTML =
+    `Reliability: ${(g.reliability*100).toFixed(1)}% · Cost savings: ${(g.cost_savings*100).toFixed(1)}% · Green: ${(g.green_score*100).toFixed(1)}%`;
+}
+
+function updateTaskTag() {
+  const sel = document.getElementById('taskSelect');
+  const tag = document.getElementById('taskTag');
+  const i = sel.selectedIndex;
+  const labels = ['Task 1: Normal', 'Task 2: Heatwave', 'Task 3: Crisis'];
+  const classes = ['easy', 'medium', 'hard'];
+  tag.textContent = labels[i];
+  tag.className = 'tag ' + classes[i];
+}
+
+// ── Event handlers ──────────────────────────────────────────────
+document.getElementById('stepBtn').addEventListener('click', stepEnv);
+document.getElementById('resetBtn').addEventListener('click', resetEnv);
+document.getElementById('taskSelect').addEventListener('change', () => { updateTaskTag(); resetEnv(); });
+
+// Keyboard shortcuts (only when intro is dismissed)
+document.addEventListener('keydown', e => {
+  if (!document.getElementById('introOverlay').classList.contains('hidden')) return;
+  if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); stepEnv(); }
+  if (e.key === 'r' && !e.metaKey && !e.ctrlKey) resetEnv();
+});
+
+// ── Intro dismiss ───────────────────────────────────────────────
+document.getElementById('btnStart').addEventListener('click', () => {
+  document.getElementById('introOverlay').classList.add('hidden');
+  resetEnv();
+});
+// Also dismiss on Enter/Space while intro is visible
+document.getElementById('introOverlay').addEventListener('keydown', e => {
+  if (e.key === 'Enter' || e.key === ' ') {
+    e.preventDefault();
+    document.getElementById('introOverlay').classList.add('hidden');
+    resetEnv();
+  }
+});
+document.getElementById('btnStart').focus();
+</script>
+</body>
+</html>

gridops/simulation/physics.py

@@ -0,0 +1,252 @@
+"""
+Energy balance engine — the core physics of the microgrid.
+
+KEY DESIGN (per Gemini review):
+  - Agent controls: battery dispatch, diesel, demand shedding
+  - Grid is the SLACK variable (absorbs residual, capped at ±200 kW)
+  - VoLL penalty (Rs 150/kWh) replaces hard reliability gate
+  - Battery degradation cost (Rs 2.5/kWh throughput)
+  - Diesel startup cost (Rs 100 if was off last step)
+  - Demand shedding rebound (50% of shed kWh added to next hour)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+# ── Constants ────────────────────────────────────────────────────────────
+
+BATTERY_CAPACITY_KWH = 500.0
+BATTERY_MAX_POWER_KW = 100.0
+BATTERY_EFFICIENCY = 0.90          # round-trip (applied as √0.9 each way)
+BATTERY_CHARGE_EFF = 0.949         # √0.90 ≈ 0.949
+BATTERY_DISCHARGE_EFF = 0.949      # agent gets 94.9% of what battery releases
+BATTERY_DEGRADATION_RS = 2.5       # Rs per kWh of throughput (charge or discharge)
+GRID_MAX_KW = 200.0
+DIESEL_MAX_KW = 100.0
+DIESEL_COST_PER_KWH = 25.0
+DIESEL_STARTUP_COST = 100.0        # Rs, one-time when turning on from off
+DEMAND_SHED_MAX_FRAC = 0.20
+SHED_REBOUND_FRAC = 0.50           # 50% of shed energy rebounds next hour
+DIESEL_TANK_KWH = 2400.0           # total fuel capacity
+VOLL = 150.0                       # Value of Lost Load (Rs/kWh)
+DT = 1.0                           # 1 hour per step
+
+
+@dataclass
+class MicrogridState:
+    """Mutable internal state of the microgrid."""
+
+    hour: int = 0
+    battery_soc_kwh: float = 250.0   # start half-charged
+    diesel_fuel_kwh: float = 2400.0
+    diesel_was_on: bool = False       # for startup cost
+    shed_rebound_kwh: float = 0.0     # deferred load from previous shedding
+    cumulative_cost: float = 0.0
+    cumulative_blackout_kwh: float = 0.0
+    cumulative_diesel_kwh: float = 0.0
+    cumulative_battery_throughput_kwh: float = 0.0
+    total_demand_kwh: float = 0.0
+
+    # Per-step bookkeeping
+    last_blackout_kwh: float = 0.0
+    last_cost: float = 0.0
+    last_reward: float = 0.0
+    last_grid_kw: float = 0.0
+
+
+@dataclass
+class StepResult:
+    """What physics.step() returns to the environment."""
+
+    state: MicrogridState
+    reward: float
+    done: bool
+    narration: str
+
+
+def step(
+    state: MicrogridState,
+    battery_dispatch_norm: float,
+    diesel_norm: float,
+    shed_norm: float,
+    solar_kw: float,
+    demand_kw: float,
+    grid_price: float,
+    diesel_fuel_cap: float = DIESEL_TANK_KWH,
+) -> StepResult:
+    """
+    Advance the microgrid by one hour.
+
+    Actions (agent controls):
+      battery_dispatch_norm: -1 (charge 100kW) to +1 (discharge 100kW)
+      diesel_norm:           0 (off) to 1 (100kW)
+      shed_norm:             0 (none) to 1 (shed 20%)
+
+    Grid is the SLACK — absorbs residual up to ±200 kW.
+    """
+    # ── Scale actions ────────────────────────────────────────────────
+    battery_cmd_kw = float(np.clip(battery_dispatch_norm, -1, 1)) * BATTERY_MAX_POWER_KW
+    diesel_kw = float(np.clip(diesel_norm, 0, 1)) * DIESEL_MAX_KW
+    shed_frac = float(np.clip(shed_norm, 0, 1)) * DEMAND_SHED_MAX_FRAC
+
+    # ── Demand (with shedding rebound from last step) ────────────────
+    actual_demand = demand_kw + state.shed_rebound_kwh
+    effective_demand = actual_demand * (1.0 - shed_frac)
+    shed_kwh = actual_demand * shed_frac * DT
+    state.shed_rebound_kwh = shed_kwh * SHED_REBOUND_FRAC  # 50% rebounds next hour
+
+    # ── Diesel fuel constraint ───────────────────────────────────────
+    available_diesel_kwh = state.diesel_fuel_kwh
+    diesel_kw = min(diesel_kw, available_diesel_kwh / DT)
+    diesel_kw = max(0.0, diesel_kw)
+
+    # ── Battery physics ──────────────────────────────────────────────
+    if battery_cmd_kw > 0:
+        # Discharge: agent wants power FROM battery
+        max_discharge = min(battery_cmd_kw, state.battery_soc_kwh / DT)
+        battery_kw = max(0.0, max_discharge)
+        delivered_kw = battery_kw * BATTERY_DISCHARGE_EFF
+        state.battery_soc_kwh -= battery_kw * DT
+    else:
+        # Charge: agent wants to push power INTO battery
+        charge_cmd = abs(battery_cmd_kw)
+        headroom = (BATTERY_CAPACITY_KWH - state.battery_soc_kwh) / BATTERY_CHARGE_EFF
+        max_charge = min(charge_cmd, headroom / DT)
+        battery_kw = -max(0.0, max_charge)  # negative = charging
+        delivered_kw = battery_kw  # charging consumes power (negative delivery)
+        state.battery_soc_kwh += abs(battery_kw) * BATTERY_CHARGE_EFF * DT
+
+    state.battery_soc_kwh = float(np.clip(state.battery_soc_kwh, 0, BATTERY_CAPACITY_KWH))
+    battery_throughput = abs(battery_kw) * DT
+    state.cumulative_battery_throughput_kwh += battery_throughput
+
+    # ── Grid as slack variable ───────────────────────────────────────
+    # grid_kw > 0 = import, < 0 = export
+    # grid_kw = what the community still needs after solar + battery + diesel
+    residual = effective_demand - solar_kw - delivered_kw - diesel_kw
+    grid_kw = float(np.clip(residual, -GRID_MAX_KW, GRID_MAX_KW))
+
+    # ── Blackout detection ───────────────────────────────────────────
+    # If residual exceeds grid capacity, we have unmet demand
+    blackout_kwh = 0.0
+    if residual > GRID_MAX_KW:
+        blackout_kwh = (residual - GRID_MAX_KW) * DT
+
+    # ── Cost accounting ──────────────────────────────────────────────
+    step_cost = 0.0
+
+    # Grid cost (import costs money, export earns revenue)
+    if grid_kw > 0:
+        step_cost += grid_price * grid_kw * DT
+    else:
+        step_cost -= grid_price * abs(grid_kw) * DT  # revenue
+
+    # Diesel cost
+    step_cost += DIESEL_COST_PER_KWH * diesel_kw * DT
+
+    # Diesel startup cost
+    if diesel_kw > 0 and not state.diesel_was_on:
+        step_cost += DIESEL_STARTUP_COST
+    state.diesel_was_on = (diesel_kw > 0)
+
+    # Battery degradation cost
+    step_cost += BATTERY_DEGRADATION_RS * battery_throughput
+
+    # VoLL penalty (replaces hard reliability gate)
+    step_cost += VOLL * blackout_kwh
+
+    # Shedding penalty (small comfort cost — Rs 5/kWh shed)
+    step_cost += 5.0 * shed_kwh
+
+    # ── Fuel accounting ──────────────────────────────────────────────
+    state.diesel_fuel_kwh -= diesel_kw * DT
+    state.diesel_fuel_kwh = max(0.0, state.diesel_fuel_kwh)
+
+    # ── Cumulative tracking ──────────────────────────────────────────
+    state.cumulative_cost += step_cost
+    state.cumulative_blackout_kwh += blackout_kwh
+    state.cumulative_diesel_kwh += diesel_kw * DT
+    state.total_demand_kwh += effective_demand * DT
+    state.last_blackout_kwh = blackout_kwh
+    state.last_cost = step_cost
+    state.last_grid_kw = grid_kw
+
+    # ── Per-step reward (negative cost, normalized) ──────────────────
+    # Simple: reward = -cost / normalization. Agent minimizes total cost.
+    reward = -step_cost / 500.0  # normalize to roughly [-2, 0] range
+    state.last_reward = reward
+
+    # ── Advance clock ────────────────────────────────────────────────
+    state.hour += 1
+    done = state.hour >= 72
+
+    # ── Narration ────────────────────────────────────────────────────
+    narration = _narrate(state, solar_kw, actual_demand, grid_price, blackout_kwh,
+                         diesel_kw, shed_frac, grid_kw, delivered_kw)
+
+    return StepResult(state=state, reward=reward, done=done, narration=narration)
+
+
+def _narrate(
+    s: MicrogridState,
+    solar: float,
+    demand: float,
+    price: float,
+    blackout: float,
+    diesel: float,
+    shed: float,
+    grid_kw: float,
+    battery_kw: float,
+) -> str:
+    """Generate a short human-readable situation summary."""
+    hour_of_day = (s.hour - 1) % 24
+    day = (s.hour - 1) // 24 + 1
+    soc_pct = s.battery_soc_kwh / BATTERY_CAPACITY_KWH * 100
+
+    parts = [f"Day {day}, {hour_of_day:02d}:00."]
+
+    if blackout > 0:
+        parts.append(f"BLACKOUT: {blackout:.0f} kWh unmet!")
+    elif demand > 200:
+        parts.append("Peak demand period.")
+    elif solar > 150:
+        parts.append("Strong solar generation.")
+    elif hour_of_day >= 18:
+        parts.append("Evening approaching — solar fading.")
+    elif hour_of_day < 6:
+        parts.append("Night — low demand, no solar.")
+
+    if grid_kw > 150:
+        parts.append(f"Grid import near limit ({grid_kw:.0f}/{GRID_MAX_KW:.0f} kW).")
+    elif grid_kw < -50:
+        parts.append(f"Exporting {abs(grid_kw):.0f} kW to grid at Rs {price:.1f}.")
+
+    if price > 12:
+        parts.append(f"Grid price high (Rs {price:.1f}/kWh).")
+    elif price < 5:
+        parts.append(f"Grid price low (Rs {price:.1f}/kWh).")
+
+    if soc_pct < 20:
+        parts.append(f"Battery low ({soc_pct:.0f}%).")
+    elif soc_pct > 80:
+        parts.append(f"Battery well-charged ({soc_pct:.0f}%).")
+
+    if battery_kw > 10:
+        parts.append(f"Battery discharging {battery_kw:.0f} kW.")
+    elif battery_kw < -10:
+        parts.append(f"Battery charging {abs(battery_kw):.0f} kW.")
+
+    if diesel > 0:
+        fuel_pct = s.diesel_fuel_kwh / DIESEL_TANK_KWH * 100
+        parts.append(f"Diesel running ({fuel_pct:.0f}% fuel left).")
+
+    if shed > 0:
+        parts.append(f"Demand response active ({shed * 100:.0f}% shed).")
+        if s.shed_rebound_kwh > 1:
+            parts.append(f"Rebound: +{s.shed_rebound_kwh:.0f} kW next hour.")
+
+    return " ".join(parts)

gridops/simulation/scenarios.py

@@ -0,0 +1,153 @@
+"""
+Scenario generators — demand, solar, and price curves for 72-hour episodes.
+
+Each generator returns a numpy array of length 72 (one value per hour).
+Scenarios are seeded for deterministic replay.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class ScenarioConfig:
+    """Knobs that define a task's difficulty."""
+
+    demand_multiplier: float = 1.0      # 1.0 = normal, 1.3 = heatwave
+    solar_multiplier: float = 1.0       # 1.0 = clear, 0.7 = haze
+    price_floor: float = 4.0            # Rs/kWh
+    price_ceiling: float = 8.0          # Rs/kWh
+    price_spike_hour: int | None = None # hour at which an evening spike occurs
+    price_spike_value: float = 15.0     # Rs/kWh at spike
+    heatwave_start_hour: int = 24       # when heatwave kicks in (0 = Day 1 start)
+    cloud_hours: list[int] | None = None  # hours with intermittent clouds
+    diesel_fuel_capacity: float = 1.0   # 1.0 = full tank (800 kWh worth)
+    forecast_noise: float = 0.15        # ±15 % Gaussian noise on forecasts
+
+
+# ── Demand ───────────────────────────────────────────────────────────────
+
+def _base_demand_curve() -> np.ndarray:
+    """24-hour demand template for a 100-home Indian summer community.
+
+    Realistic Indian residential: ~15-20 kWh/home/day → ~100 kW avg, 250 kW peak.
+    Grid (200 kW) covers off-peak easily. Solar creates midday surplus.
+    Evening 18-22h is THE bottleneck: demand > grid cap → need battery + diesel.
+    """
+    hourly = np.array([
+         50,  45,  40,  40,  45,  55,   # 0-5   night (deep trough, grid surplus)
+         70,  85, 100, 110, 115, 120,   # 6-11  morning ramp (solar kicks in)
+        125, 130, 130, 120, 115, 140,   # 12-17 afternoon (solar covers, charge battery)
+        200, 220, 250, 230, 180, 100,   # 18-23 evening peak → 250 kW at 20:00
+    ], dtype=np.float64)
+    return hourly
+
+
+def generate_demand(cfg: ScenarioConfig, rng: np.random.Generator) -> np.ndarray:
+    """72-hour demand with heatwave multiplier and stochastic noise."""
+    base = np.tile(_base_demand_curve(), 3)  # 3 days
+    demand = base.copy()
+
+    # Apply heatwave multiplier after start hour
+    hw = cfg.heatwave_start_hour
+    if cfg.demand_multiplier != 1.0 and hw < 72:
+        demand[hw:] *= cfg.demand_multiplier
+
+    # ±10 % base noise
+    noise = 1.0 + rng.normal(0, 0.05, size=72)
+    demand *= noise
+    return np.clip(demand, 20, 500)
+
+
+# ── Solar ────────────────────────────────────────────────────────────────
+
+def _base_solar_curve() -> np.ndarray:
+    """24-hour solar bell curve peaking at noon, 250 kW capacity."""
+    hours = np.arange(24)
+    solar = np.maximum(0, 250 * np.sin(np.pi * (hours - 6) / 12))
+    solar[:6] = 0
+    solar[18:] = 0
+    return solar
+
+
+def generate_solar(cfg: ScenarioConfig, rng: np.random.Generator) -> np.ndarray:
+    """72-hour solar with optional haze reduction and cloud dips."""
+    base = np.tile(_base_solar_curve(), 3)
+    solar = base * cfg.solar_multiplier
+
+    # Cloud cover — 50 % drop during listed hours
+    if cfg.cloud_hours:
+        for h in cfg.cloud_hours:
+            if 0 <= h < 72:
+                solar[h] *= 0.5
+
+    # Small stochastic variation
+    noise = 1.0 + rng.normal(0, 0.03, size=72)
+    solar *= noise
+    return np.clip(solar, 0, 200)
+
+
+# ── Grid price ───────────────────────────────────────────────────────────
+
+def _base_price_curve(floor: float, ceiling: float) -> np.ndarray:
+    """24-hour IEX-like price curve with clear cheap/expensive periods.
+
+    Night (0-6): near floor (cheap — battery charging window)
+    Morning (7-11): moderate
+    Afternoon (12-16): moderate-high (solar competes)
+    Evening (17-22): near ceiling (peak demand, solar gone — sell window)
+    Late night (23): dropping back
+    """
+    hours = np.arange(24)
+    mid = (floor + ceiling) / 2
+    amp = (ceiling - floor) / 2
+    # Strong evening peak, cheap night
+    price = mid + amp * (
+        0.6 * np.sin(np.pi * (hours - 4) / 20)       # base daily shape
+        + 0.4 * np.exp(-0.5 * ((hours - 20) / 2.5)**2) # evening spike
+        - 0.3 * np.exp(-0.5 * ((hours - 3) / 2)**2)    # night trough
+    )
+    return np.clip(price, floor, ceiling)
+
+
+def generate_price(cfg: ScenarioConfig, rng: np.random.Generator) -> np.ndarray:
+    """72-hour grid price with optional spikes."""
+    base = np.tile(_base_price_curve(cfg.price_floor, cfg.price_ceiling), 3)
+    price = base.copy()
+
+    # Evening spike
+    if cfg.price_spike_hour is not None:
+        spike_h = cfg.price_spike_hour
+        # Spread spike over 3 hours centered on spike_h
+        for offset in range(-1, 2):
+            h = spike_h + offset
+            if 0 <= h < 72:
+                price[h] = max(price[h], cfg.price_spike_value * (1.0 - 0.2 * abs(offset)))
+
+    # Small noise
+    noise = 1.0 + rng.normal(0, 0.02, size=72)
+    price *= noise
+    return np.clip(price, 3, 20)
+
+
+# ── Forecasts ────────────────────────────────────────────────────────────
+
+def make_forecast(
+    true_values: np.ndarray,
+    current_hour: int,
+    horizon: int,
+    noise_frac: float,
+    rng: np.random.Generator,
+) -> list[float]:
+    """Return a noisy forecast for the next `horizon` hours."""
+    forecasts = []
+    for i in range(1, horizon + 1):
+        h = current_hour + i
+        if h < len(true_values):
+            val = true_values[h]
+        else:
+            val = true_values[-1]
+        noisy = val * (1.0 + rng.normal(0, noise_frac))
+        forecasts.append(max(0.0, float(noisy)))
+    return forecasts

gridops/tasks/definitions.py

@@ -0,0 +1,54 @@
+"""
+Three task configurations with escalating difficulty.
+
+Task 1: Normal Summer (easy)
+Task 2: Heatwave + Clouds (medium)
+Task 3: Extreme Crisis (hard)
+"""
+
+from gridops.simulation.scenarios import ScenarioConfig
+
+TASK_1_NORMAL = ScenarioConfig(
+    demand_multiplier=1.0,
+    solar_multiplier=1.0,
+    price_floor=3.0,
+    price_ceiling=12.0,
+    price_spike_hour=None,
+    price_spike_value=12.0,
+    heatwave_start_hour=72,      # no heatwave
+    cloud_hours=None,
+    diesel_fuel_capacity=1.0,
+    forecast_noise=0.15,
+)
+
+TASK_2_HEATWAVE = ScenarioConfig(
+    demand_multiplier=1.3,
+    solar_multiplier=1.0,
+    price_floor=5.0,
+    price_ceiling=15.0,
+    price_spike_hour=44,         # Day 2, 20:00 (hour 44)
+    price_spike_value=18.0,
+    heatwave_start_hour=24,      # Day 2 start
+    cloud_hours=[30, 31, 36, 37, 54, 55],  # intermittent Day 2-3
+    diesel_fuel_capacity=1.0,
+    forecast_noise=0.15,
+)
+
+TASK_3_CRISIS = ScenarioConfig(
+    demand_multiplier=1.5,
+    solar_multiplier=0.7,
+    price_floor=8.0,
+    price_ceiling=20.0,
+    price_spike_hour=44,
+    price_spike_value=20.0,
+    heatwave_start_hour=0,       # heatwave from the start
+    cloud_hours=list(range(8, 16)) + list(range(32, 40)) + list(range(56, 64)),
+    diesel_fuel_capacity=0.33,   # 800 kWh ≈ 8 hrs at 100 kW
+    forecast_noise=0.15,
+)
+
+TASKS = {
+    "task_1_normal": TASK_1_NORMAL,
+    "task_2_heatwave": TASK_2_HEATWAVE,
+    "task_3_crisis": TASK_3_CRISIS,
+}

gridops/tasks/graders.py

@@ -0,0 +1,101 @@
+"""
+Episode graders — deterministic 0.0-1.0 score at end of episode.
+
+Scoring (post-Gemini review):
+  - No hard reliability gate. VoLL (Rs 150/kWh) in the physics makes
+    blackouts extremely expensive, creating a smooth gradient.
+  - Score = how much better than a dumb heuristic baseline.
+  - Baseline: "import max grid every hour, no battery/diesel/shedding"
+  - score = clip(1 - agent_cost / baseline_cost, 0, 1)
+  - Weighted: 50% cost efficiency + 25% reliability + 25% green score
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from gridops.simulation.physics import (
+    BATTERY_CAPACITY_KWH,
+    DIESEL_COST_PER_KWH,
+    DIESEL_TANK_KWH,
+    GRID_MAX_KW,
+    VOLL,
+    MicrogridState,
+)
+
+
+def compute_dumb_baseline_cost(
+    demand_curve: np.ndarray,
+    solar_curve: np.ndarray,
+    price_curve: np.ndarray,
+) -> float:
+    """Cost of a dumb baseline: import max grid, no battery/diesel/shedding.
+
+    Where demand > grid + solar, apply VoLL for the blackout.
+    This is a realistic "no-intelligence" baseline.
+    """
+    total_cost = 0.0
+    for h in range(len(demand_curve)):
+        demand = demand_curve[h]
+        solar = solar_curve[h]
+        price = price_curve[h]
+
+        # Grid covers what it can (up to 200 kW)
+        needed_from_grid = max(0.0, demand - solar)
+        grid_import = min(needed_from_grid, GRID_MAX_KW)
+        total_cost += price * grid_import  # grid cost
+
+        # Any excess demand is a blackout
+        unmet = max(0.0, needed_from_grid - GRID_MAX_KW)
+        total_cost += VOLL * unmet  # VoLL penalty
+
+    return float(total_cost)
+
+
+def grade_episode(
+    state: MicrogridState,
+    demand_curve: np.ndarray,
+    solar_curve: np.ndarray,
+    price_curve: np.ndarray,
+) -> dict:
+    """
+    Grade a completed episode. Returns dict with score 0.0-1.0.
+
+    score = 0.50 × cost_efficiency + 0.25 × reliability + 0.25 × green_score
+    """
+    total_demand = max(state.total_demand_kwh, 1.0)
+    total_blackout = state.cumulative_blackout_kwh
+
+    # Reliability: fraction of demand met (0-1)
+    reliability = (total_demand - total_blackout) / total_demand
+    reliability = float(np.clip(reliability, 0, 1))
+
+    # Cost efficiency: how much better than dumb baseline
+    baseline_cost = compute_dumb_baseline_cost(demand_curve, solar_curve, price_curve)
+    actual_cost = state.cumulative_cost
+    if baseline_cost > 0:
+        cost_efficiency = 1.0 - (actual_cost / baseline_cost)
+    else:
+        cost_efficiency = 0.0
+    cost_efficiency = float(np.clip(cost_efficiency, 0, 1))
+
+    # Green score: 1 - diesel fraction of total energy
+    green_score = 1.0 - (state.cumulative_diesel_kwh / max(total_demand, 1.0))
+    green_score = float(np.clip(green_score, 0, 1))
+
+    # Composite score (smooth, no gate)
+    score = 0.50 * cost_efficiency + 0.25 * reliability + 0.25 * green_score
+    score = float(np.clip(score, 0, 1))
+
+    return {
+        "score": round(score, 4),
+        "reliability": round(reliability, 4),
+        "cost_efficiency": round(cost_efficiency, 4),
+        "green_score": round(green_score, 4),
+        "baseline_cost": round(baseline_cost, 2),
+        "actual_cost": round(actual_cost, 2),
+        "total_blackout_kwh": round(total_blackout, 2),
+        "total_diesel_kwh": round(state.cumulative_diesel_kwh, 2),
+        "total_demand_kwh": round(total_demand, 2),
+        "battery_throughput_kwh": round(state.cumulative_battery_throughput_kwh, 2),
+    }

inference.py

@@ -0,0 +1,179 @@
+"""
+Inference Script — GridOps Microgrid Environment
+===================================
+MANDATORY
+- Before submitting, ensure the following variables are defined in your environment configuration:
+    API_BASE_URL   The API endpoint for the LLM.
+    MODEL_NAME     The model identifier to use for inference.
+    HF_TOKEN       Your Hugging Face / API key.
+
+- The inference script must be named `inference.py` and placed in the root directory of the project
+- Participants must use OpenAI Client for all LLM calls using above variables
+"""
+
+import json
+import os
+import sys
+
+from openai import OpenAI
+
+# ── Env vars (as required by hackathon) ──────────────────────────────────
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+MODEL_NAME = os.getenv("MODEL_NAME", "meta-llama/Llama-3.3-70B-Instruct")
+
+# ── Environment import (runs in-process, no server needed) ──────────────
+sys.path.insert(0, os.path.dirname(__file__))
+from gridops.server.environment import GridOpsEnvironment
+from gridops.models import GridOpsAction
+
+TASKS = ["task_1_normal", "task_2_heatwave", "task_3_crisis"]
+MAX_STEPS = 72
+TEMPERATURE = 0.1
+MAX_TOKENS = 150
+
+SYSTEM_PROMPT = """\
+You are an expert microgrid operator managing a 100-home community in India during summer.
+
+You control three actions each hour:
+- battery_dispatch: -1 (charge 100 kW from grid) to +1 (discharge 100 kW to community)
+- diesel_dispatch: 0 (off) to 1 (100 kW). Costs Rs 25/kWh + Rs 100 startup if was off.
+- demand_shedding: 0 (none) to 1 (shed 20% of demand). WARNING: 50% rebounds next hour.
+
+The GRID automatically absorbs the residual (capped at ±200 kW).
+If demand exceeds grid + solar + battery + diesel → BLACKOUT (Rs 150/kWh penalty!).
+
+Key economics:
+- Grid prices vary Rs 3-20/kWh. Cheap at night, expensive evening.
+- Battery: 500 kWh, 100 kW max, 90% round-trip efficiency, Rs 2.5/kWh degradation.
+- Solar: 250 kW peak (free!), bell curve 6AM-6PM, zero at night.
+- Demand: ~100 kW avg, 250 kW evening peak. Grid cap = 200 kW → need battery for gap.
+
+Strategy:
+1. Night (0-6h): charge battery (cheap grid, low demand)
+2. Solar (6-15h): surplus charges battery or exports
+3. Pre-peak (15-17h): ensure battery > 70%
+4. Evening peak (18-22h): discharge battery to cover gap above grid 200 kW cap
+5. Diesel: only when battery empty AND peak demand. Avoid startup costs.
+
+Respond ONLY with valid JSON: {"battery_dispatch": float, "diesel_dispatch": float, "demand_shedding": float}"""
+
+
+def format_observation(obs: dict) -> str:
+    """Format observation into a readable prompt for the LLM."""
+    return (
+        f"Hour {obs['hour']:.0f}/72 (Day {obs.get('day_of_episode', '?')})\n"
+        f"Demand: {obs['demand_kw']:.0f} kW | Solar: {obs['solar_kw']:.0f} kW\n"
+        f"Battery SOC: {obs['battery_soc']*100:.0f}% | Grid Price: Rs {obs['grid_price']:.1f}/kWh\n"
+        f"Diesel Fuel: {obs['diesel_fuel_remaining']*100:.0f}% | Diesel On: {obs.get('diesel_is_on', False)}\n"
+        f"Grid import last step: {obs.get('grid_kw_this_step', 0):.0f} kW\n"
+        f"Forecasts (next 4h):\n"
+        f"  Demand: {[f'{v:.0f}' for v in obs.get('demand_forecast_4h', [])]}\n"
+        f"  Solar:  {[f'{v:.0f}' for v in obs.get('solar_forecast_4h', [])]}\n"
+        f"  Price:  {[f'{v:.1f}' for v in obs.get('price_forecast_4h', [])]}\n"
+        f"Cumulative: blackout={obs['cumulative_blackout_kwh']:.1f} kWh, cost=Rs {obs['cumulative_cost']:.0f}\n"
+        f"{obs.get('narration', '')}\n"
+        f"\nWhat action? Reply with JSON only."
+    )
+
+
+def parse_action(text: str) -> dict:
+    """Extract action JSON from LLM response."""
+    text = text.strip()
+    for start, end in [("{", "}"), ("```json", "```")]:
+        idx = text.find(start)
+        if idx >= 0:
+            if end == "}":
+                eidx = text.rfind("}") + 1
+            else:
+                eidx = text.find(end, idx + len(start))
+            try:
+                return json.loads(text[idx:eidx])
+            except json.JSONDecodeError:
+                continue
+    return {"battery_dispatch": 0.0, "diesel_dispatch": 0.0, "demand_shedding": 0.0}
+
+
+def run_task(client: OpenAI, env: GridOpsEnvironment, task_id: str, seed: int = 42) -> dict:
+    """Run one full episode on a task, return grade."""
+    obs = env.reset(seed=seed, task_id=task_id)
+    obs_dict = obs.model_dump()
+
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+
+    for step_idx in range(MAX_STEPS):
+        user_msg = format_observation(obs_dict)
+        messages.append({"role": "user", "content": user_msg})
+
+        # Keep context manageable
+        if len(messages) > 21:
+            messages = [messages[0]] + messages[-20:]
+
+        try:
+            completion = client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=TEMPERATURE,
+                max_tokens=MAX_TOKENS,
+            )
+            reply = completion.choices[0].message.content or ""
+        except Exception as e:
+            print(f"    LLM error at step {step_idx}: {e}")
+            reply = "{}"
+
+        messages.append({"role": "assistant", "content": reply})
+
+        action_dict = parse_action(reply)
+        action = GridOpsAction(
+            battery_dispatch=float(action_dict.get("battery_dispatch", 0.0)),
+            diesel_dispatch=float(action_dict.get("diesel_dispatch", 0.0)),
+            demand_shedding=float(action_dict.get("demand_shedding", 0.0)),
+        )
+        obs = env.step(action)
+        obs_dict = obs.model_dump()
+
+        if step_idx % 24 == 0:
+            print(f"    Hour {obs_dict['hour']:.0f}: SOC={obs_dict['battery_soc']*100:.0f}% "
+                  f"cost=Rs {obs_dict['cumulative_cost']:.0f} "
+                  f"blackout={obs_dict['cumulative_blackout_kwh']:.1f}")
+
+        if obs_dict.get("done", False):
+            break
+
+    grade = env.state.grade
+    return grade
+
+
+def main():
+    print("=" * 60)
+    print("  GridOps — LLM Baseline Inference")
+    print(f"  Model: {MODEL_NAME}")
+    print(f"  API:   {API_BASE_URL}")
+    print("=" * 60)
+
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env = GridOpsEnvironment()
+
+    results = {}
+    for task_id in TASKS:
+        print(f"\n--- {task_id} ---")
+        grade = run_task(client, env, task_id)
+        results[task_id] = grade
+        if grade:
+            print(f"  Score:       {grade['score']}")
+            print(f"  Reliability: {grade['reliability']}")
+            print(f"  Cost Eff:    {grade['cost_efficiency']}")
+            print(f"  Green:       {grade['green_score']}")
+            print(f"  Cost:        Rs {grade['actual_cost']:.0f} (baseline Rs {grade['baseline_cost']:.0f})")
+
+    print("\n" + "=" * 60)
+    print("  SUMMARY")
+    print("=" * 60)
+    for task_id, grade in results.items():
+        score = grade["score"] if grade else "ERROR"
+        print(f"  {task_id}: {score}")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

openenv.yaml

@@ -0,0 +1,39 @@
+name: gridops
+description: "Community microgrid bridge operator — balance solar, battery, diesel, and grid trade across 3-day summer episodes in India."
+version: "0.1.0"
+
+environment:
+  module: gridops.server.app
+  class: GridOpsEnvironment
+  action: GridOpsAction
+  observation: GridOpsObservation
+
+server:
+  module: gridops.server.app
+  app: app
+  host: "0.0.0.0"
+  port: 8000
+  workers: 1
+
+tasks:
+  - id: task_1_normal
+    name: "Normal Summer"
+    difficulty: easy
+    description: "Clear skies, standard demand curve, smooth IEX prices Rs 4-8."
+
+  - id: task_2_heatwave
+    name: "Heatwave + Clouds"
+    difficulty: medium
+    description: "Day 2-3 heatwave (+30% demand), intermittent clouds, price spikes to Rs 18."
+
+  - id: task_3_crisis
+    name: "Extreme Crisis"
+    difficulty: hard
+    description: "Full 3-day heatwave, -30% solar, Rs 8-20 prices, limited diesel fuel."
+
+metadata:
+  action_space: "3D continuous: grid_trade [-1,1], diesel_dispatch [0,1], demand_shedding [0,1]"
+  observation_space: "12 fields: hour, demand, solar, battery_soc, price, fuel, 3×4h forecasts, cumulative metrics"
+  episode_length: 72
+  step_duration: "1 hour"
+  grading: "Reliability-gated composite: 60% cost savings + 20% reliability + 20% green score"

pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "gridops"
+version = "0.1.0"
+description = "Community Microgrid RL Environment — OpenEnv Hackathon"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core>=0.2.0",
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.0",
+    "numpy>=1.24.0",
+    "websockets>=12.0",
+    "openai>=1.0.0",
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "httpx"]
+inference = ["openai"]
+
+[project.scripts]
+server = "server.app:main"
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"

scripts/oracle_test.py

@@ -0,0 +1,191 @@
+"""
+Oracle strategy test — validates physics + grader + strategy gaps.
+
+New action space: battery_dispatch, diesel_dispatch, demand_shedding.
+Grid is the slack variable (absorbs residual up to ±200 kW).
+"""
+
+import sys
+sys.path.insert(0, ".")
+
+import numpy as np
+from gridops.server.environment import GridOpsEnvironment
+from gridops.models import GridOpsAction
+from gridops.tasks.definitions import TASKS
+
+
+def oracle_policy(obs: dict) -> GridOpsAction:
+    """
+    Smart oracle: manages battery for arbitrage + evening peak coverage.
+
+    Strategy:
+      - Night (cheap grid): charge battery
+      - Solar midday: let solar cover demand, charge battery from surplus
+      - Pre-peak (15-17h): top up battery
+      - Evening peak (18-22h): discharge battery to reduce expensive grid import
+      - Use diesel only when grid is at capacity AND battery is depleted
+      - Shed demand only as last resort during extreme peaks
+    """
+    hour_of_day = int(obs["hour"]) % 24
+    soc = obs["battery_soc"]
+    price = obs["grid_price"]
+    demand = obs["demand_kw"]
+    solar = obs["solar_kw"]
+    fuel = obs["diesel_fuel_remaining"]
+
+    battery = 0.0   # -1=charge, +1=discharge
+    diesel = 0.0
+    shedding = 0.0
+
+    # Net demand after solar
+    net = demand - solar
+
+    if hour_of_day < 6:
+        # Night: cheap power, charge battery aggressively
+        if soc < 0.9:
+            battery = -0.8  # charge
+        else:
+            battery = 0.0
+
+    elif 6 <= hour_of_day < 15:
+        # Solar hours: if solar > demand, charge battery from surplus
+        if solar > demand:
+            # Surplus — charge battery (grid absorbs the rest as export)
+            if soc < 0.95:
+                battery = -min(1.0, (solar - demand) / 100.0)
+            else:
+                battery = 0.0  # battery full, surplus exports to grid
+        else:
+            # Deficit — grid covers it. Charge battery if cheap.
+            if soc < 0.7 and price < 6:
+                battery = -0.5
+            else:
+                battery = 0.0
+
+    elif 15 <= hour_of_day < 18:
+        # Pre-peak: ensure battery is charged for evening
+        if soc < 0.8:
+            battery = -0.8  # charge hard
+        else:
+            battery = 0.0
+
+    elif 18 <= hour_of_day < 23:
+        # Evening peak: discharge battery to cover demand beyond grid cap
+        if net > GRID_MAX_KW and soc > 0.1:
+            # Need battery to cover the gap
+            gap = net - GRID_MAX_KW
+            battery = min(1.0, gap / 100.0)
+
+            # If battery can't cover full gap, use diesel
+            remaining = gap - battery * 100
+            if remaining > 0 and fuel > 0.05:
+                diesel = min(1.0, remaining / 100.0)
+
+            # If still short, shed demand
+            remaining2 = remaining - diesel * 100
+            if remaining2 > 0:
+                shedding = min(1.0, remaining2 / (demand * 0.20 + 1))
+        elif price > 10 and soc > 0.5:
+            # Expensive grid: discharge battery to save money
+            battery = min(0.6, (price - 8) / 10.0)
+        else:
+            battery = 0.0
+
+    else:
+        # Hour 23: low demand, recharge if depleted
+        if soc < 0.4:
+            battery = -0.5
+        else:
+            battery = 0.0
+
+    return GridOpsAction(
+        battery_dispatch=float(np.clip(battery, -1, 1)),
+        diesel_dispatch=float(np.clip(diesel, 0, 1)),
+        demand_shedding=float(np.clip(shedding, 0, 1)),
+    )
+
+
+GRID_MAX_KW = 200.0  # for oracle calculations
+
+
+def heuristic_do_nothing(obs: dict) -> GridOpsAction:
+    """Baseline: do nothing. Grid handles everything as slack."""
+    return GridOpsAction(battery_dispatch=0.0, diesel_dispatch=0.0, demand_shedding=0.0)
+
+
+def heuristic_always_discharge(obs: dict) -> GridOpsAction:
+    """Bad: always discharge battery → empty for evening → blackout."""
+    return GridOpsAction(battery_dispatch=1.0, diesel_dispatch=0.0, demand_shedding=0.0)
+
+
+def heuristic_always_diesel(obs: dict) -> GridOpsAction:
+    """Wasteful: always run diesel → hemorrhages money at Rs 25/kWh."""
+    return GridOpsAction(battery_dispatch=0.0, diesel_dispatch=1.0, demand_shedding=0.0)
+
+
+def run_episode(env, policy_fn, task_id="task_1_normal", seed=42):
+    """Run a full 72-step episode, return grade dict."""
+    obs = env.reset(seed=seed, task_id=task_id)
+    obs_dict = obs.model_dump()
+
+    for _ in range(72):
+        action = policy_fn(obs_dict)
+        obs = env.step(action)
+        obs_dict = obs.model_dump()
+        if obs.done:
+            break
+
+    state = env.state
+    return state.grade
+
+
+def main():
+    env = GridOpsEnvironment()
+    policies = {
+        "Oracle": oracle_policy,
+        "Do-Nothing": heuristic_do_nothing,
+        "Always-Discharge": heuristic_always_discharge,
+        "Always-Diesel": heuristic_always_diesel,
+    }
+
+    print("=" * 70)
+    print("  GridOps Oracle Test v2 — New Action Space (Battery/Diesel/Shed)")
+    print("  Grid is slack. VoLL = Rs 150/kWh. Degradation = Rs 2.5/kWh.")
+    print("=" * 70)
+
+    for task_id in TASKS:
+        print(f"\n--- {task_id} ---")
+        for name, fn in policies.items():
+            grade = run_episode(env, fn, task_id)
+            if grade:
+                print(f"  {name:22s}  score={grade['score']:.4f}  "
+                      f"reliability={grade['reliability']:.4f}  "
+                      f"cost=Rs {grade['actual_cost']:.0f}  "
+                      f"baseline=Rs {grade['baseline_cost']:.0f}")
+            else:
+                print(f"  {name:22s}  NO GRADE")
+
+    # Determinism check
+    print("\n--- Determinism Check (3 runs of Oracle on Task 1) ---")
+    scores = []
+    for i in range(3):
+        grade = run_episode(env, oracle_policy, "task_1_normal", seed=42)
+        scores.append(grade["score"])
+        print(f"  Run {i+1}: score={grade['score']:.4f}")
+
+    if len(set(f"{s:.6f}" for s in scores)) == 1:
+        print("  Deterministic: identical scores across runs")
+    else:
+        print("  NON-DETERMINISTIC: scores differ!")
+
+    # Detailed oracle breakdown
+    print("\n--- Oracle Detailed Breakdown (Task 1) ---")
+    grade = run_episode(env, oracle_policy, "task_1_normal", seed=42)
+    for k, v in grade.items():
+        print(f"  {k}: {v}")
+
+    print("\n" + "=" * 70)
+
+
+if __name__ == "__main__":
+    main()

server/app.py

@@ -0,0 +1,15 @@
+"""
+Root-level server/app.py — required by OpenEnv validate.
+Delegates to gridops.server.app for all functionality.
+"""
+
+from gridops.server.app import app  # noqa: F401
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run("gridops.server.app:app", host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()