Update docs/hf-mini-blog-ev-grid-oracle.md

docs/hf-mini-blog-ev-grid-oracle.md

@@ -1,94 +1,833 @@
----
-title: "EV Grid Oracle — verifiable GRPO on a Bangalore EV dispatch world"
-emoji: ⚡
-colorFrom: indigo
-colorTo: green
-sdk: docker
-app_port: 8000
-pinned: false
----
-
-# EV Grid Oracle — verifiable GRPO on a Bangalore EV dispatch world
-
-**TL;DR:** We built an **OpenEnv**-style environment that simulates EV charging stress on a city graph, exposed it on **Hugging Face Spaces**, and trained a small **Qwen2.5‑3B** policy with **TRL GRPO** using **verifier-style rewards** (strict action schema + reward breakdown + anti-cheat flags). Judges can replay **paired** baseline vs oracle episodes on the **same seeds** and read **Wilson + McNemar** summaries from `training/fair_eval.py`.
-
----
-
-## OpenEnv Hackathon themes (how we fit)
-
-| Theme | Claim |
-|------|--------|
-| **#3 World modeling** | **Primary:** LLM acts in a **partially observable** world (queues, grid %, renewables) with **tool-like** actions verified by the simulator. |
-| **#2 Long horizon** | **Primary:** Many `step` calls, **scheduled** shocks, mistakes compound; replay shows recovery or failure modes. |
-| **#1 Multi-agent** | **Secondary / narrative:** Stakeholder **tensions** in the reward (urgency vs grid vs wait); explicit multi-LLM negotiation is **not** required to tell a credible “incentives + coordination” story. |
-| **#4 Self-improvement** | **Stretch:** Scenario / trap catalog supports **adaptive curricula**; hook for future self-play or difficulty ramps. |
-| **#5 Wild card** | **Differentiator:** City graph + operator UI + **statistical** paired eval. |
-
----
-
-## Judging rubric (where we spend reviewer attention)
-
-- **Innovation (40%):** verifier-first rewards, anti-cheat, deterministic stress scenarios—not a toy yes/no grid.  
-- **Storytelling (30%):** this post + README + Space demo = **problem → env → training → evidence → why Bangalore / grid ops**.  
-- **Learning evidence (20%):** paired baseline vs oracle, **committed PNGs** in `artifacts/`, JSON from `fair_eval`.  
-- **Reward / pipeline (10%):** `reward_fn` in Colab calls **`EVGridCore.step`**, not a static label dataset.
-
----
-
-## The problem
-
-Operators route EVs to stations under **queues**, **feeder stress**, and **renewable variability**. A language model should output **structured actions** that the simulator can check—not hand-wavy prose.
-
----
-
-## What we shipped
-
-| Piece | Where |
-|--------|--------|
-| Environment + FastAPI Space | Repo `server/`, Space linked from `README.md` |
-| Deterministic stress scenarios | `ev_grid_oracle/scenarios.py` |
-| Verifier rewards + anti-cheat | `ev_grid_oracle/reward.py`, flags on `EVGridObservation` |
-| Phaser “City Ops” demo + replay | `web/` |
-| Paired eval + Wilson + McNemar | `training/evaluate.py`, `training/fair_eval.py` |
-| Trap catalog (for judges) | `docs/judge-kit/trap-catalog.md` |
-
----
-
-## Training (Colab + TRL + Unsloth)
-
-- **Runnable notebook:** open from GitHub or Colab:  
-  [training/train_grpo.ipynb](https://github.com/NITISH-R-G/ev-grid-oracle/blob/main/training/train_grpo.ipynb)  
-  [Open in Colab](https://colab.research.google.com/github/NITISH-R-G/ev-grid-oracle/blob/main/training/train_grpo.ipynb)
-
-The first notebook cell **clones this repository** and runs `pip install -e .` so `import ev_grid_oracle` works on a clean Colab VM. Use **GPU runtime (T4+)** before running Unsloth / GRPO cells.
-
----
-
-## Evidence judges can trust
-
-1. Run `python training/evaluate.py` → JSON includes **`paired_same_world`** and **`per_episode`** rows.  
-2. Run `python training/fair_eval.py` → **`artifacts/fair_eval_results.json`** includes **`binary_rates_wilson`** and **`paired_mcnemar`**.  
-3. **Judge-facing figure pack** (commit to repo): run `python training/make_plots.py --eval-json training/eval_results.json --fair-json artifacts/fair_eval_results.json --out-dir artifacts` to emit KPI bars, paired trajectories, Δ-histograms, reward breakdown bars, boxplots, win-rate bars, paired scatter, binary timeline, Wilson/McNemar panels, and a **six-panel dashboard** (`eval_dashboard_summary.png`). Also run `training/fair_eval.py` for `fair_eval_chart.png`.
-
-**Why it matters:** dispatch policies that **survive verification** under stress are closer to deployable co-pilots than chat-only “plans.”
-
----
-
-## LoRA / QLoRA warning (verbatim)
-
-> If you're using LoRA/QLoRA, don't naively upcast a 4-bit base to 16-bit and "merge" at the end without the correct path — it can badly degrade quality. Save adapters cleanly and test post-training inference immediately.
-
----
-
-## Links (canonical)
-
-- **GitHub:** `https://github.com/NITISH-R-G/ev-grid-oracle`  
-- **Space / live URL:** see root `README.md` → Quick links (keep in sync with your HF account).
-
-## Official hackathon materials
-
-See **[`hackathon-official-resources.md`](hackathon-official-resources.md)** (OpenEnv Core, HF `openenv` hub, tutorials, YouTube series, reward-engineering papers).
-
----
-
-*This file lives in the environment repository so you can **copy it into a Hugging Face Space blog post**, **link the raw GitHub file** from your model card, or **mirror** it on `huggingface.co/blog` with minimal edits.*
+<!-- ============================================================
+     EV GRID ORACLE  ·  HF Mini Blog
+     Team Codestreak  ·  Nitish R.G., Padmanabhan, Prithic
+     ============================================================ -->
+
+<div align="center">
+
+```
+███████╗██╗   ██╗     ██████╗ ██████╗ ██╗██████╗
+██╔════╝██║   ██║    ██╔════╝ ██╔══██╗██║██╔══██╗
+█████╗  ██║   ██║    ██║  ███╗██████╔╝██║██║  ██║
+██╔══╝  ╚██╗ ██╔╝    ██║   ██║██╔══██╗██║██║  ██║
+███████╗ ╚████╔╝     ╚██████╔╝██║  ██║██║██████╔╝
+╚══════╝  ╚═══╝       ╚═════╝ ╚═╝  ╚═╝╚═╝╚═════╝
+
+  ██████╗ ██████╗  █████╗  ██████╗██╗     ███████╗
+ ██╔═══██╗██╔══██╗██╔══██╗██╔════╝██║     ██╔════╝
+ ██║   ██║██████╔╝███████║██║     ██║     █████╗
+ ██║   ██║██╔══██╗██╔══██║██║     ██║     ██╔══╝
+ ╚██████╔╝██║  ██║██║  ██║╚██████╗███████╗███████╗
+  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚══════╝
+```
+
+### ⚡ *A Verifiable GRPO Dispatch Oracle for Bangalore's EV Charging Grid* ⚡
+
+<br/>
+
+[![OpenEnv](https://img.shields.io/badge/OpenEnv-openenv--core%200.2.3-0ea5e9?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/openenv-core/)
+[![HF Space](https://img.shields.io/badge/🤗%20HF%20Space-ev--grid--oracle-f97316?style=for-the-badge)](https://huggingface.co/spaces/NITISHRG15102007/ev-grid-oracle)
+[![Colab](https://img.shields.io/badge/Colab-Train%20GRPO-facc15?style=for-the-badge&logo=googlecolab&logoColor=black)](https://colab.research.google.com/github/NITISH-R-G/ev-grid-oracle/blob/main/training/train_grpo.ipynb)
+[![GitHub](https://img.shields.io/badge/GitHub-ev--grid--oracle-22c55e?style=for-the-badge&logo=github)](https://github.com/NITISH-R-G/ev-grid-oracle)
+[![License](https://img.shields.io/badge/License-MIT-a855f7?style=for-the-badge)](LICENSE)
+
+<br/>
+
+> **"Don't explain. Don't hallucinate. Execute — and prove it."**
+
+<br/>
+
+---
+
+</div>
+
+## 🌆 The City That Never Stops Charging
+
+Picture Bangalore at 6:47 PM on a Tuesday.
+
+The IT corridors of Whitefield are emptying. Thousands of EVs — cabs, bikes, BMTC feeders — converge on 25 charging stations simultaneously. Feeder substations creak toward their thermal limits. Clean solar energy is being wasted because nobody knows where to send it. Critical vehicles with 4% battery are sitting in queues behind someone's leisurely overnight top-up.
+
+**The grid operator has maybe 90 seconds to reroute, defer, and load-shift before the cascade starts.**
+
+Today, that decision is made by gut feel, spreadsheets, or rule-of-thumb heuristics. **EV Grid Oracle changes that.** We built a reinforcement-learning agent that takes the real-time grid snapshot, outputs structured executable actions, and improves *by actually running in a verified simulator* — not by reading papers about it.
+
+This is not a chatbot that talks about EV routing. This is an agent that *does it*, *proves it*, and *gets better*.
+
+---
+
+<div align="center">
+
+## 👥 Team Codestreak
+
+</div>
+
+| | Builder | Role |
+|---|---|---|
+| ⚡ | **Nitish R.G.** — [LinkedIn](https://www.linkedin.com/in/nitish-r-g-15-10-2007-rgn/) | Team Leader · Architecture · GRPO training |
+| 🔌 | **Padmanabhan Suresh Babu** | Environment design · Reward engineering |
+| 🗺️ | **Prithic** | Road-graph routing · Evaluation harness |
+
+---
+
+<div align="center">
+
+## 🔥 The 3-Second Hook
+
+### *What makes this different from every other "AI + EV" project?*
+
+</div>
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                                                                     │
+│   Most projects:  Prompt → LLM → Text → 👍 vibes                   │
+│                                                                     │
+│   EV Grid Oracle: Prompt → LLM → Action → Parse → Validate →       │
+│                   Simulate → Reward Breakdown → GRPO Update → 🔄    │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+| Dimension | Typical "AI + EV" Demo | **EV Grid Oracle** |
+|---|---|---|
+| Output type | Natural language explanation | Structured, executable action schema |
+| Verification | LLM-as-judge / vibes | Deterministic simulator + reward verifier |
+| Training signal | None or SFT | GRPO with multi-component verifiable rewards |
+| Anti-cheat | None | Hard constraint flags (teleport detection, etc.) |
+| Reproducibility | "Trust us" | Paired seeds, committed artifacts, auditable JSON |
+| Evidence | Screenshots | PNG plots + JSON stats + TensorBoard logs |
+
+**Three things no other team can fake:**
+1. 🧪 **Verifiable world** — every action is parsed → validated → stepped in a simulator → scored with a full reward breakdown
+2. 🔁 **Replayable evidence** — baseline vs oracle evaluated on the *same deterministic seeds*
+3. 📦 **Engineer-grade artifacts** — plots, stats, and logs committed to the repo so judges audit without rerunning anything
+
+---
+
+## 🖥️ Live Command Center
+
+> *This is what a judge sees the moment they open the Space.*
+
+![EV Grid Oracle Command Center](images/command-center.png)
+
+The Command Center gives you:
+- **Real-time grid snapshot** — queue lengths, feeder stress levels, renewable availability
+- **Agent action trace** — what the model decided and why, in structured format
+- **Reward component breakdown** — every scalar contribution, live
+- **Episode replay controls** — step forward/back through any decision point
+
+---
+
+<div align="center">
+
+## 🏙️ The Problem: Bangalore's Grid Under Siege
+
+</div>
+
+Bangalore's charging infrastructure is growing faster than the grid that feeds it. Here's what dispatchers face *every peak window*:
+
+```
+  ┌──────────────────────────────────────────────────────────────┐
+  │  6:00 PM  ████████████████████░░░░  QUEUE: 847 EVs waiting  │
+  │  6:15 PM  ████████████████████████  STRESS: BLR-07 at 94%   │
+  │  6:30 PM  ████████████████████████  PEAK VIOLATION: -₹12k   │
+  │  6:45 PM  ██████████████░░░░░░░░░░  SOLAR WINDOW: wasted    │
+  │  7:00 PM  ████████████████████████  CRITICAL EV: 3% battery │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+The constraints are real and they **stack**:
+
+- 🚗 **Queue pressure** — every minute of wait degrades user trust and SLA scores
+- ⚡ **Feeder thermal limits** — exceeding them risks hardware damage and grid events
+- 🌿 **Renewable windows** — solar/wind availability is time-varying; miss it and you pay the carbon cost
+- 🚨 **Critical EVs** — deferring a 3%-battery vehicle is a safety failure, not a scheduling choice
+- 🔒 **No cheating** — you cannot teleport vehicles, you cannot route to non-adjacent nodes, physics applies
+
+A human dispatcher watching five dashboards makes 200+ micro-decisions per hour. **We trained an LLM to make them faster, verifiably.**
+
+---
+
+<div align="center">
+
+## 🏗️ Architecture: The Full Loop
+
+*From prompt to policy update — nothing hidden.*
+
+</div>
+
+```mermaid
+flowchart LR
+  subgraph HF["🤗 Hugging Face Space: EV Grid Oracle"]
+    API["FastAPI server\nserver/app.py"]
+    ENV["EVGridEnvironment\nOpenEnv API"]
+    CORE["Simulator core\nEVGridCore / RoadCore"]
+    REW["Verifier + Reward\nbreakdown + anti-hack"]
+    API --> ENV --> CORE --> REW
+  end
+
+  subgraph TRAIN["⚙️ Colab Training"]
+    NB["training/train_grpo.ipynb"]
+    TRL["TRL GRPOTrainer"]
+    UNS["Unsloth runtime\nQLoRA adapters"]
+    TB["TensorBoard\nev_oracle_grpo_road"]
+    NB --> TRL --> UNS --> TB
+  end
+
+  MODEL["🧠 Qwen2.5-3B + LoRA\nSmall LLM policy"]
+  USER["👤 Judge / Operator"]
+
+  USER -->|"POST /reset, /step"| API
+  REW -->|"reward + next obs"| USER
+  TRL -->|"sample completions"| MODEL
+  MODEL -->|"action text"| TRL
+  TRL -->|"reward_funcs → RoadCore.step"| CORE
+  CORE -->|"reward breakdown"| TRL
+  TRL -->|"update adapters"| MODEL
+```
+
+### How the data flows
+
+```
+ [Grid Snapshot]
+      │
+      ▼
+ ┌─────────────┐     ┌──────────────┐     ┌─���─────────────┐
+ │  LLM Policy │────▶│ Action Parser│────▶│ Constraint    │
+ │  Qwen2.5-3B │     │ (strict regex│     │ Validator     │
+ │  + LoRA     │     │  + schema)   │     │ (no teleport, │
+ └─────────────┘     └──────────────┘     │  valid edges) │
+                                          └───────┬───────┘
+                                                  │
+                                                  ▼
+                                         ┌────────────────┐
+                                         │  EVGridCore    │
+                                         │  Simulator     │
+                                         │  (tick advance)│
+                                         └───────┬────────┘
+                                                 │
+                              ┌──────────────────┼──────────────────┐
+                              ▼                  ▼                  ▼
+                        [wait reward]    [grid_stress reward]  [renewable reward]
+                              │                  │                  │
+                              └──────────────────┴──────────────────┘
+                                                 │
+                                                 ▼
+                                      [GRPO policy update]
+```
+
+---
+
+<div align="center">
+
+## 🎯 What the Agent Can Do
+
+### *Two action schemas. Both verifiable. No hallucination tolerated.*
+
+</div>
+
+### Schema A — Station Routing & Load Shifting
+
+> *"Which station? At what rate? Defer by how long?"*
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  EVGridAction Schema                                         ║
+╠══════════════════════════════════════════════════════════════╣
+║  ACTION:        route | defer | load_shift                   ║
+║  STATION:       BLR-01 … BLR-25   (or NONE)                 ║
+║  CHARGE_RATE:   slow | fast | ultra_fast                     ║
+║  DEFER_MINUTES: integer  (0 = don't defer)                   ║
+║  REASON:        ≤ 20 words                                   ║
+║  CONFIDENCE:    0.0 – 1.0                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+**Example valid action:**
+```
+ACTION: load_shift
+STATION: BLR-07
+CHARGE_RATE: slow
+DEFER_MINUTES: 15
+REASON: Feeder stress at 92%; shift to renewable window at T+15.
+CONFIDENCE: 0.87
+```
+
+**Example rejected action (anti-cheat catches this):**
+```
+ACTION: route
+STATION: BLR-99          ← ❌ Station doesn't exist
+CHARGE_RATE: warp_speed  ← ❌ Invalid rate enum
+CONFIDENCE: 1.5          ← ❌ Out of range
+→ anti_cheat_flag=True, reward penalty applied
+```
+
+---
+
+### Schema B — Road-Graph Routing (Bangalore OSM)
+
+> *"Where do I send this vehicle next? And I can't teleport it."*
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  RoadAction Schema                                           ║
+╠══════════════════════════════════════════════════════════════╣
+║  CURRENT_NODE:  <int>  (real OSM node in BLR graph)          ║
+║  NEXT_NODE:     <int>  (must be adjacent — no teleporting)   ║
+║  REASON:        ≤ 20 words                                   ║
+║  CONFIDENCE:    0.0 – 1.0                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+The road graph constraint is **the hardest part**. An LLM that has never seen Bangalore's road topology must learn, through RL, to only propose valid neighbor hops. Every teleport attempt is caught and penalized. Over training, the oracle learns to *stay on the map*.
+
+```
+  Bangalore Road Graph (simplified):
+
+  [Whitefield] ──── [Marathahalli] ──── [Sarjapur]
+       │                  │                  │
+  [Varthur]          [Bellandur]       [HSR Layout]
+       │                  │                  │
+  [KR Puram] ──── [Indiranagar] ──── [Koramangala]
+
+  ✅ Marathahalli → Bellandur     (adjacent, valid)
+  ✅ Indiranagar  → Koramangala   (adjacent, valid)
+  ❌ Whitefield   → Koramangala   (not adjacent, TELEPORT FLAG)
+```
+
+---
+
+<div align="center">
+
+## 🌍 Environment Design: OpenEnv-First
+
+### *The environment is a first-class citizen, not an afterthought.*
+
+</div>
+
+### What the model sees (Observation space)
+
+Every step, the agent receives a structured text prompt + JSON state:
+
+```json
+{
+  "tick": 47,
+  "stations": {
+    "BLR-07": { "queue_length": 14, "feeder_stress": 0.92, "active_chargers": 8 },
+    "BLR-12": { "queue_length": 3,  "feeder_stress": 0.41, "active_chargers": 2 },
+    "..."
+  },
+  "renewable_score": 0.73,
+  "critical_evs": [
+    { "vehicle_id": "KA01AB1234", "battery_pct": 3, "station": "BLR-07" }
+  ],
+  "road_graph": { "current_node": 1042, "neighbors": [1043, 1101, 998] }
+}
+```
+
+### Episode lifecycle
+
+```
+  RESET  ──▶  tick=0, random seed, grid initialized
+    │
+    ▼
+  STEP 1  ──▶  agent acts  ──▶  simulator ticks  ──▶  reward computed
+    │
+    ▼
+  STEP 2 … STEP N  (long-horizon, mistakes compound)
+    │
+    ▼
+  DONE  ──▶  episode summary, KPI aggregation, artifacts written
+```
+
+The key design insight: **this is not single-shot**. The agent must maintain strategy across many steps. A greedy "always route to the closest station" policy looks fine early and catastrophically fails at peak. The oracle learns to plan.
+
+### Core API (OpenEnv-compatible)
+
+```
+POST /reset   →  initial observation + episode seed
+POST /step    →  action → next obs + reward breakdown + done flag
+GET  /state   →  current full simulator state (JSON)
+GET  /schema  →  action schema definition
+GET  /health  →  liveness probe
+```
+
+---
+
+<div align="center">
+
+## 💰 Reward Design: Verifiable, Multi-Component, Anti-Hack
+
+### *The reward is where RL wins or loses. We built it to win.*
+
+</div>
+
+> **If your reward is fuzzy, your agent learns to game it. If it's crisp and hard to fake, RL works.**
+
+```
+  Total Reward = Σ weighted components (computed by verifier, not LLM)
+
+  ┌──────────────────────────────────────────────────────────┐
+  │ Component        │ Signal Direction │ What it measures   │
+  ├──────────────────┼──────────────────┼────────────────────┤
+  │ wait             │ ⬇ penalize       │ queue wait time    │
+  │ grid_stress      │ ⬇ penalize       │ feeder overload    │
+  │ peak             │ ⬇ penalize       │ peak violations    │
+  │ renewable        │ ⬆ reward         │ clean window usage │
+  │ urgency          │ ⬇ penalize       │ critical EV defers │
+  │ format_valid     │ ⬆ shaping        │ parseable output   │
+  │ anti_cheat       │ ⬇ hard penalty   │ impossible actions │
+  └──────────────────────────────────────────────────────────┘
+```
+
+### Anti-hack flags (the hard constraints)
+
+| Flag | Trigger | Penalty |
+|---|---|---|
+| `teleport_detected` | NEXT_NODE not adjacent to CURRENT_NODE | Hard negative |
+| `invalid_station` | STATION not in BLR-01..BLR-25 | Hard negative |
+| `critical_deferred` | Critical EV (≤5% battery) given DEFER > 0 | Hard negative |
+| `rate_enum_invalid` | CHARGE_RATE outside enum | Format penalty |
+| `confidence_oob` | CONFIDENCE outside [0.0, 1.0] | Format penalty |
+
+The anti-hack layer is what separates *learning the task* from *gaming the reward*. Every flag is logged per step, per episode, so you can audit exactly where the agent was trying to cheat.
+
+---
+
+<div align="center">
+
+## 🧠 Training Pipeline
+
+### *GRPO + Unsloth + QLoRA on Qwen2.5-3B*
+
+</div>
+
+### Why GRPO?
+
+Standard PPO requires a value network — an entire extra model to estimate baselines. **GRPO (Group Relative Policy Optimization)** computes baselines *within a group of rollouts from the same prompt*. This means:
+- ✅ No separate critic network
+- ✅ Lower memory footprint
+- ✅ Works beautifully with verifiable reward functions
+- ✅ More rollouts per GPU-hour → faster iteration
+
+```
+  GRPO Training Loop (per prompt batch):
+
+  Prompt P  ──▶  sample K completions  ──▶  [A₁, A₂, A₃, A₄]
+                                              │    │    │    │
+                                           r=0.8 r=0.2 r=0.9 r=0.1   (verifier rewards)
+                                              │
+                                              ▼
+                                    relative_reward_i = r_i − mean(r)
+                                              │
+                                              ▼
+                                    policy gradient update
+                                    (push A₁, A₃ up; push A₂, A₄ down)
+```
+
+### Model + adapter stack
+
+```
+  Base model:  Qwen2.5-3B  (3 billion params, fits in Colab T4)
+  Adapter:     QLoRA  (4-bit quantized base + 16-bit LoRA)
+  Runtime:     Unsloth  (2×+ throughput vs vanilla HF)
+  Trainer:     TRL GRPOTrainer
+  Logging:     TensorBoard  (ev_oracle_grpo_road/)
+```
+
+### The winning tip (from hard experience)
+
+```
+  ❌ Wrong approach:  one 12-hour mega-run, pray it converges
+  ✅ Right approach:  many 45-min runs with reward component iteration
+
+  What to iterate:
+    1. reward component weights
+    2. anti-hack thresholds
+    3. scenario curriculum (easy → hard seeds)
+    4. rollout batch size (throughput dominates RL wall-clock time)
+```
+
+### Training in 3 commands
+
+```bash
+# 1. Clone and set up
+git clone https://github.com/NITISH-R-G/ev-grid-oracle
+pip install openenv-core trl unsloth
+
+# 2. Open the notebook
+jupyter notebook training/train_grpo.ipynb
+
+# 3. Export evidence plots after training
+python tools/export_grpo_tensorboard_plots.py \
+  --logdir ev_oracle_grpo_road \
+  --out-dir artifacts
+```
+
+---
+
+<div align="center">
+
+## 📊 Evidence: Results That Judges Can Audit
+
+### *Every number is committed. Every plot is reproducible.*
+
+</div>
+
+### Paired evaluation results
+
+> `paired_same_world=true, episodes=72` — baseline and oracle ran on *identical seeds*. No cherry-picking.
+
+```
+  ┌───────────────────────────┬──────────────┬──────────────┐
+  │ KPI                       │   Baseline   │   Oracle     │
+  ├───────────────────────────┼──────────────┼──────────────┤
+  │ avg_wait_minutes          │    ---       │   0.2939     │
+  │ grid_stress_events        │    ---       │  10.3194     │
+  │ peak_violations           │    ---       │   5.6528     │
+  │ renewable_mean            │    ---       │   0.3625     │
+  │ critical_deferred         │    ---       │   0 ✅       │
+  │ anti_cheat_steps          │    ---       │   2.6389     │
+  └───────────────────────────┴──────────────┴──────────────┘
+  
+  Key: critical_deferred = 0 means no safety failures across 72 episodes.
+```
+
+### Fair eval (n=25 episodes, Wilson + McNemar)
+
+From `artifacts/fair_eval_results.json`:
+- Wilson confidence intervals computed for all binary outcomes
+- McNemar paired test p-values committed for auditable significance testing
+
+---
+
+<div align="center">
+
+## 🖼️ Visualization Gallery
+
+*Everything below is auto-generated, committed, and auditable.*
+
+</div>
+
+---
+
+### 📋 One-Page Dashboard — The Full Picture
+
+> *Six panels. One glance. All the signal you need.*
+
+![Six-panel evaluation dashboard](../artifacts/eval_dashboard_summary.png)
+
+---
+
+### 📊 Aggregate KPI Comparison — Baseline vs Oracle
+
+> *Mean KPIs across all 72 paired episodes.*
+
+![Baseline vs Oracle — mean KPIs](../artifacts/kpi_comparison.png)
+
+---
+
+### 📈 Per-Episode Trajectories — Wait, Peaks, Stress Over Time
+
+> *Each line is one episode. Same seeds, both policies.*
+
+![Wait, peak ticks, stress ticks vs episode index](../artifacts/eval_episode_trajectories.png)
+
+---
+
+### 📉 Paired Deltas — Oracle Minus Baseline
+
+> *Negative delta on wait/stress = oracle wins. Positive on renewable = oracle wins.*
+
+![Per-episode delta histograms](../artifacts/eval_delta_histograms.png)
+
+---
+
+### 🧩 Reward Component Breakdown
+
+> *Where is the reward coming from? Not a black box.*
+
+![Reward breakdown bars](../artifacts/eval_reward_breakdown_bars.png)
+
+```
+  Interpreting this chart:
+  ┌──────────────────────────────────────────────────────┐
+  │  wait bar:        lower = oracle reduced queues      │
+  │  grid_stress bar: lower = fewer overload events      │
+  │  renewable bar:   higher = more clean energy used    │
+  │  urgency bar:     near-zero = no critical deferrals  │
+  │  anti_cheat bar:  near-zero = agent learned physics  │
+  └──────────────────────────────────────────────────────┘
+```
+
+---
+
+### 📦 Distribution Boxplots — Variance Matters
+
+> *Medians and spreads, not just means. Robust policies have tight boxes.*
+
+![Boxplots by policy](../artifacts/eval_boxplots_by_policy.png)
+
+---
+
+### 🥊 Head-to-Head Win Rates
+
+> *On what fraction of episodes does oracle beat baseline on each KPI?*
+
+![Oracle win rates](../artifacts/eval_oracle_win_rates.png)
+
+---
+
+### 🎯 Paired Scatter — Oracle vs Baseline Wait Time
+
+> *Points above the diagonal = oracle is worse. Points below = oracle wins.*
+
+![Paired scatter wait](../artifacts/eval_paired_scatter_wait.png)
+
+---
+
+### 🗓️ Binary Timeline — When Is Baseline Struggling?
+
+> *Where on the timeline does baseline fail most? That's where oracle improves the most.*
+
+![Binary timeline baseline](../artifacts/eval_binary_timeline_baseline.png)
+
+---
+
+### 📐 Wilson Intervals — Uncertainty-Aware Binary Rates
+
+> *Not just point estimates. Confidence intervals for every binary outcome.*
+
+![Binary rates with Wilson intervals](../artifacts/eval_fair_binary_rates.png)
+
+---
+
+### 🔬 McNemar p-values — Statistical Significance
+
+> *Paired hypothesis testing. If p < 0.05, the difference is real, not noise.*
+
+![McNemar p-values](../artifacts/eval_mcnemar_pvalues.png)
+
+---
+
+### 📉 GRPO Training Curves
+
+> *The two plots every judge looks for: reward goes up, loss goes down.*
+
+![GRPO loss](../artifacts/grpo_loss.png)
+
+![GRPO reward](../artifacts/grpo_reward.png)
+
+---
+
+### ✅ Fair Eval Summary Chart
+
+![Wilson chart](../artifacts/fair_eval_chart.png)
+
+---
+
+<div align="center">
+
+## 💥 Business Impact
+
+### *This is not a toy. This is operational AI.*
+
+</div>
+
+```
+  Every 1 minute of average wait reduced across 847 peak-hour EVs
+  = 847 minutes of human time saved per peak window
+  = ~14 hours of productive time returned to Bangalore, daily.
+
+  Every peak violation avoided
+  = avoided SLA penalty + avoided feeder hardware stress.
+
+  Every renewable window captured
+  = direct carbon savings + lower marginal electricity cost.
+```
+
+| Impact Vector | Mechanism | Who benefits |
+|---|---|---|
+| **Lower wait time** | Load-shift to uncongested stations during demand spikes | EV drivers, fleet operators |
+| **Fewer peak violations** | Proactive deferral before thermal limits hit | Grid operators, BESCOM |
+| **More renewable usage** | Route slow-charging EVs into solar/wind windows | Environment, cost-payers |
+| **Zero critical deferrals** | Hard constraint: never defer ≤5% battery | Safety, drivers |
+| **Auditable decisions** | Structured actions + reward breakdown logged | Regulators, operators |
+
+---
+
+<div align="center">
+
+## 🔬 Research Foundation
+
+### *We read the papers. Then we implemented them.*
+
+</div>
+
+```
+  ┌─────────────────────────────────────────────────────────────────┐
+  │  Paper                    │ What we took                        │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  DeepSeekMath (GRPO)      │ Group-relative baseline, no critic  │
+  │  arXiv:2402.03300         │ Memory-lean PPO variant for verif.  │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  QLoRA (Dettmers et al.)  │ 4-bit quantized base + 16-bit LoRA  │
+  │  arXiv:2305.14314         │ Fast iteration on Colab T4          │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  RLVR direction           │ Verifiable rewards reduce judge      │
+  │  arXiv:2601.18533         │ hacking, improve signal quality     │
+  ├─────────────────────────────────────────────────────────────────┤
+  │  OpenEnv RFC-004          │ Composable reward rubrics,          │
+  │  (meta-pytorch/OpenEnv)   │ trajectory scoring, delayed rewards │
+  └─────────────────────────────────────────────────────────────────┘
+```
+
+**The core insight we borrowed from all of them:**
+
+> Sample multiple completions per prompt → score them with a verifiable function → update the policy to prefer what actually worked. Don't let the LLM grade its own homework.
+
+---
+
+<div align="center">
+
+## 🛠️ Tech Stack Deep Dive
+
+</div>
+
+```
+  ┌───────────────────────────────────────────────────────────────┐
+  │                    EV GRID ORACLE STACK                       │
+  ├────────────────┬──────────────────────────────────────────────┤
+  │  Layer         │  Technology                                  │
+  ├────────────────┼──────────────────────────────────────────────┤
+  │  Interface     │  OpenEnv 0.2.3  (reset/step/state/schema)   │
+  │  API server    │  FastAPI  (async, auto-docs, Pydantic)       │
+  │  Hosting       │  Hugging Face Spaces  (Docker, port 8000)   │
+  │  Simulator     │  EVGridCore + RoadCore  (pure Python)        │
+  │  Training      │  TRL GRPOTrainer + GRPOConfig               │
+  │  Base model    │  Qwen2.5-3B  (instruction-tuned)            │
+  │  Adapters      │  QLoRA  (4-bit base, 16-bit adapters)       │
+  │  Runtime       │  Unsloth  (2×+ throughput on T4)            │
+  │  Deep learning │  PyTorch + Transformers                      │
+  │  Logging       │  TensorBoard  (ev_oracle_grpo_road/)        │
+  │  Evaluation    │  scipy.stats (Wilson, McNemar)               │
+  │  Viz           │  matplotlib + seaborn  (committed PNGs)     │
+  └────────────────┴──────────────────────────────────────────────┘
+```
+
+### Why each choice matters
+
+**OpenEnv** — standardizes the environment interface so any judge can `POST /reset` and `POST /step` from their own machine without touching training code.
+
+**TRL GRPO** — purpose-built for reinforcement learning with verifiable reward functions. The multi-sample-per-prompt structure is exactly what we need for reward comparison.
+
+**Unsloth** — doubles throughput on the same GPU. More rollouts per hour = more RL iterations = better policy. Simple math.
+
+**Paired evaluation** — using identical seeds for baseline and oracle means any difference in KPIs is attributable to the policy, not random episode variation.
+
+---
+
+<div align="center">
+
+## ⚠️ Critical Warning: LoRA Merging
+
+</div>
+
+> **Read this before you copy our training setup.**
+
+```
+  ┌──────────────────────────────────────────────────────────────┐
+  │                    ⚠️  LoRA/QLoRA WARNING                    │
+  │                                                              │
+  │  DO NOT naively upcast a 4-bit base to 16-bit and "merge"   │
+  │  at the end without the correct Unsloth path.               │
+  │                                                              │
+  │  What happens if you do it wrong:                           │
+  │  → Adapter weights applied to wrong quantization scale      │
+  │  → Model quality degrades silently (hard to detect)         │
+  │  → Your eval results are meaningless                        │
+  │                                                             │
+  │  What to do instead:                                        │
+  │  → Save adapters cleanly with Unsloth's save_pretrained     │
+  │  → Test post-training inference IMMEDIATELY after saving    │
+  │  → Verify on held-out prompts before running eval harness   │
+  └──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+<div align="center">
+
+## 📁 Submission Bundle
+
+### *Everything a judge needs, in one place.*
+
+</div>
+
+```
+  ev-grid-oracle/
+  ├── 📄 README.md                    ← Start here. Judges table, quick links.
+  ├── 📄 openenv.yaml                 ← OpenEnv descriptor (discoverable)
+  ├── 🖥️  server/
+  │   └── app.py                      ← FastAPI entrypoint (OpenEnv endpoints)
+  ├── 🧠 training/
+  │   ├── train_grpo.ipynb            ← Full GRPO training notebook (Colab-ready)
+  │   ├── evaluate.py                 ← Paired evaluation script
+  │   ├── fair_eval.py                ← Wilson + McNemar evaluation
+  │   └── make_plots.py               ← Artifact plot generation
+  ├── 📊 artifacts/
+  │   ├── eval_dashboard_summary.png  ← Six-panel overview
+  │   ├── kpi_comparison.png          ← Baseline vs oracle KPIs
+  │   ├── eval_*.png                  ← Full plot suite
+  │   ├── grpo_loss.png               ← Training evidence
+  │   ├── grpo_reward.png             ← Training evidence
+  │   ├── eval_results.json           ← Raw numbers (auditable)
+  │   └── fair_eval_results.json      ← Wilson + McNemar results
+  ├── 🛠️  tools/
+  │   └── export_grpo_tensorboard_plots.py
+  └── 📝 docs/
+      ├── hf-mini-blog-ev-grid-oracle.md   ← This file
+      ├── submission/
+      │   ├── training-artifacts-and-logs.md
+      │   └── youtube-under-2min-outline.md
+      └── hackathon-official-resources.md
+```
+
+### Non-negotiables checklist (judges — look for these)
+
+| Item | Where | Status |
+|---|---|---|
+| Live HF Space (env runs) | `README.md` → Quick links | ✅ |
+| OpenEnv descriptor | `openenv.yaml` | ✅ |
+| Training notebook (Colab) | `training/train_grpo.ipynb` | ✅ |
+| GRPO reward curve (PNG) | `artifacts/grpo_reward.png` | ✅ |
+| GRPO loss curve (PNG) | `artifacts/grpo_loss.png` | ✅ |
+| Paired eval results (JSON) | `artifacts/eval_results.json` | ✅ |
+| Wilson + McNemar (JSON) | `artifacts/fair_eval_results.json` | ✅ |
+| Full plot suite (PNG) | `artifacts/*.png` | ✅ |
+| Written submission | This file | ✅ |
+| Demo video (< 2 min) | `docs/submission/youtube-*` | ✅ |
+
+---
+
+<div align="center">
+
+## 🔗 Quick Links
+
+| Resource | URL |
+|---|---|
+| 🤗 HF Space (live env) | [NITISHRG15102007/ev-grid-oracle](https://huggingface.co/spaces/NITISHRG15102007/ev-grid-oracle) |
+| 📓 Training Notebook | [train_grpo.ipynb (Colab)](https://colab.research.google.com/github/NITISH-R-G/ev-grid-oracle/blob/main/training/train_grpo.ipynb) |
+| 💻 GitHub Repo | [NITISH-R-G/ev-grid-oracle](https://github.com/NITISH-R-G/ev-grid-oracle) |
+| 📋 This Blog (shareable) | [docs/hf-mini-blog-ev-grid-oracle.md](https://github.com/NITISH-R-G/ev-grid-oracle/blob/main/docs/hf-mini-blog-ev-grid-oracle.md) |
+| 📧 Team Lead | [Nitish R.G. on LinkedIn](https://www.linkedin.com/in/nitish-r-g-15-10-2007-rgn/) |
+
+---
+
+<br/>
+
+*Built by **Team Codestreak** · Bangalore, India · 2025*
+
+*"The grid doesn't wait. Neither should your model."* ⚡
+
+</div>