fix: dropdown and frontend

api/main.py

@@ -53,7 +53,12 @@ from fastapi.responses import FileResponse
 
 from api.model_registry import registry, registry_v1, registry_v2, registry_v3
 from api.schemas import HealthResponse
-from scripts.download_models import select_top_models, DEFAULT_STARTUP_TOP_MODELS
+from scripts.download_models import (
+    select_top_models,
+    DEFAULT_STARTUP_TOP_MODELS,
+    ensure_metadata_first,
+    write_datamap,
+)
 from src.utils.logger import get_logger
 
 log = get_logger(__name__)
@@ -70,6 +75,11 @@ _FRONTEND_DIST = _HERE.parent / "frontend" / "dist"
 async def lifespan(app: FastAPI):
     """Start API immediately; bootstrap top v3 models in background."""
     log.info("Loading model registries …")
+    # Hard requirement: metadata must exist first for all versions.
+    await asyncio.to_thread(ensure_metadata_first, ["v1", "v2", "v3"])
+    for reg in _REGISTRIES.values():
+        reg.refresh_metadata()
+
     _version_status["v3"] = "downloading"
     app.state.v3_bootstrap_task = asyncio.create_task(_bg_bootstrap_v3())
     log.info("v3 bootstrap started in background — API is available immediately")
@@ -147,6 +157,7 @@ async def list_versions():
     out = []
     for v in ["v3", "v2", "v1"]:
         reg = _REGISTRIES[v]
+        reg.ensure_metadata_loaded()
         on_disk = _version_loaded(v)
         in_memory = reg.model_count > 0
         meta = reg._version_meta  # from models.json (loaded in __init__)
@@ -177,6 +188,7 @@ async def _bg_load_version(version: str) -> None:
         )
         await proc.wait()
         if proc.returncode == 0:
+            _REGISTRIES[version].refresh_metadata()
             _REGISTRIES[version].load_all()
             _version_status[version] = "ready"
             log.info("Version %s loaded on demand — %d models", version,
@@ -208,6 +220,7 @@ async def _bg_bootstrap_v3() -> None:
 
         startup_models = select_top_models("v3")
         if startup_models:
+            registry_v3.refresh_metadata()
             registry_v3.load_all(only_models=set(startup_models))
             log.info(
                 "v3 registry ready — %d models loaded (startup top-%d set: %s)",
@@ -228,7 +241,7 @@ async def _bg_bootstrap_v3() -> None:
         log.error("Failed during v3 bootstrap: %s", exc)
 
 
-async def _bg_load_model(version: str, model_name: str) -> None:
+async def _bg_download_model(version: str, model_name: str) -> None:
     import sys as _sys
 
     key = _model_status_key(version, model_name)
@@ -244,15 +257,16 @@ async def _bg_load_model(version: str, model_name: str) -> None:
             stderr=asyncio.subprocess.STDOUT,
         )
         await proc.wait()
-        if proc.returncode == 0 and _REGISTRIES[version].load_model(model_name):
-            _model_status[key] = "ready"
-            log.info("Model %s/%s loaded on demand", version, model_name)
+        _REGISTRIES[version].refresh_metadata()
+        if proc.returncode == 0 and _REGISTRIES[version].model_on_disk(model_name):
+            _model_status[key] = "on_disk"
+            log.info("Model %s/%s downloaded on demand", version, model_name)
         else:
             _model_status[key] = "error"
-            log.error("Failed to download/load model %s/%s", version, model_name)
+            log.error("Failed to download model %s/%s", version, model_name)
     except Exception as exc:
         _model_status[key] = "error"
-        log.error("Failed to load model %s/%s: %s", version, model_name, exc)
+        log.error("Failed to download model %s/%s: %s", version, model_name, exc)
 
 
 @app.post("/api/versions/{version}/load", tags=["meta"])
@@ -260,6 +274,8 @@ async def load_version(version: str, background_tasks: BackgroundTasks):
     """Download + activate a model version from HF Hub (runs in background)."""
     if version not in _REGISTRIES:
         raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+    await asyncio.to_thread(ensure_metadata_first, [version])
+    _REGISTRIES[version].refresh_metadata()
     if _version_status.get(version) == "downloading":
         return {"status": "downloading", "version": version}
     # If artifacts exist on disk but not loaded, just load without downloading
@@ -282,10 +298,30 @@ async def get_version_models_meta(version: str):
     """Return models.json metadata for a specific version."""
     if version not in _REGISTRIES:
         raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+    await asyncio.to_thread(ensure_metadata_first, [version])
+    _REGISTRIES[version].refresh_metadata()
     meta_path = _artifacts_dir() / version / "models.json"
     if not meta_path.exists():
         raise HTTPException(status_code=404, detail=f"models.json not found for {version}")
-    return _json.loads(meta_path.read_text(encoding="utf-8"))
+    datamap_path = _artifacts_dir() / version / "datamap.json"
+    if not datamap_path.exists():
+        await asyncio.to_thread(write_datamap, version)
+    return {
+        "models_meta": _json.loads(meta_path.read_text(encoding="utf-8")),
+        "datamap": _json.loads(datamap_path.read_text(encoding="utf-8")) if datamap_path.exists() else {},
+    }
+
+
+@app.get("/api/versions/{version}/datamap", tags=["meta"])
+async def get_version_datamap(version: str):
+    """Return datamap.json for a specific version; generate if missing."""
+    if version not in _REGISTRIES:
+        raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+    await asyncio.to_thread(ensure_metadata_first, [version])
+    datamap_path = _artifacts_dir() / version / "datamap.json"
+    if not datamap_path.exists():
+        await asyncio.to_thread(write_datamap, version)
+    return _json.loads(datamap_path.read_text(encoding="utf-8"))
 
 
 @app.get("/api/versions/{version}/models", tags=["meta"])
@@ -294,7 +330,9 @@ async def list_version_models(version: str):
     if version not in _REGISTRIES:
         raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
 
+    await asyncio.to_thread(ensure_metadata_first, [version])
     reg = _REGISTRIES[version]
+    reg.refresh_metadata()
     rows = []
     for model_name, info in reg._catalog.items():
         key = _model_status_key(version, model_name)
@@ -317,11 +355,13 @@ async def list_version_models(version: str):
 
 @app.post("/api/versions/{version}/models/{model_name}/load", tags=["meta"])
 async def load_single_model(version: str, model_name: str, background_tasks: BackgroundTasks):
-    """Download + activate one model without loading an entire version."""
+    """Two-step per-model action: download first, then load into memory."""
     if version not in _REGISTRIES:
         raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
 
+    await asyncio.to_thread(ensure_metadata_first, [version])
     reg = _REGISTRIES[version]
+    reg.refresh_metadata()
     if model_name not in reg._catalog:
         raise HTTPException(status_code=404, detail=f"Unknown model '{model_name}' in {version}")
 
@@ -343,7 +383,7 @@ async def load_single_model(version: str, model_name: str, background_tasks: Bac
         raise HTTPException(status_code=500, detail=f"Model '{model_name}' exists on disk but failed to load")
 
     _model_status[key] = "downloading"
-    background_tasks.add_task(_bg_load_model, version, model_name)
+    background_tasks.add_task(_bg_download_model, version, model_name)
     return {"status": "downloading", "version": version, "model": model_name}
 
 

api/model_registry.py

@@ -99,7 +99,7 @@ def _load_version_meta(version: str) -> dict[str, Any]:
     """
     json_path = _ARTIFACTS / version / "models.json"
     if not json_path.exists():
-        log.warning("models.json not found for %s — catalog will be empty", version)
+        log.info("models.json not found for %s yet — catalog will refresh after metadata bootstrap", version)
         return {}
     try:
         with open(json_path, encoding="utf-8") as fh:
@@ -197,6 +197,34 @@ class ModelRegistry:
             return False
         return (self._artifacts / rel).exists()
 
+    def refresh_metadata(self) -> None:
+        """Reload models.json metadata and refresh catalog-derived settings."""
+        self._version_meta = _load_version_meta(self.version)
+        self._catalog = self._version_meta.get("models", {})
+
+        json_features = self._version_meta.get("feature_set")
+        if json_features:
+            self.feature_cols = list(json_features)
+        elif self.version == "v3":
+            self.feature_cols = list(V3_FEATURE_COLS)
+        else:
+            self.feature_cols = list(FEATURE_COLS_SCALAR)
+
+        ensemble_info = self._catalog.get("best_ensemble", {})
+        self._ensemble_components = ensemble_info.get("components", [])
+        self._ensemble_weights = {}
+        for cname in self._ensemble_components:
+            cinfo = self._catalog.get(cname, {})
+            self._ensemble_weights[cname] = cinfo.get("r2", 1.0)
+
+    def ensure_metadata_loaded(self) -> None:
+        """Refresh metadata lazily if catalog is empty and models.json exists now."""
+        if self._catalog:
+            return
+        json_path = _ARTIFACTS / self.version / "models.json"
+        if json_path.exists():
+            self.refresh_metadata()
+
     def load_model(self, model_name: str) -> bool:
         """Load one model (and ensemble dependencies when applicable).
 
@@ -222,6 +250,7 @@ class ModelRegistry:
         if only_models is None and self.models:
             log.debug("Registry already populated — skipping load_all()")
             return
+        self.ensure_metadata_loaded()
         self._detect_device()
         self._load_scaler()
         self.feature_cols = self._load_feature_cols()
@@ -939,6 +968,7 @@ class ModelRegistry:
 
     def list_models(self) -> list[dict[str, Any]]:
         """Return full model listing with versioning, metrics, and load status."""
+        self.ensure_metadata_loaded()
         all_metrics = self.get_metrics()
         # Registry version prefix: "v1" -> "1", "v2" -> "2", "v3" -> "3"
         reg_major = self.version.lstrip("v")

api/routers/simulate.py

@@ -315,17 +315,30 @@ async def simulate_batteries(req: SimulateRequest):
     eol_thr  = req.eol_threshold
     N        = req.steps
 
-    model_name = req.model_name or registry_v2.default_model or "best_ensemble"
+    requested_model = req.model_name or registry_v2.default_model or "best_ensemble"
+
+    # Resolve to a batchable loaded model once (to avoid per-battery fallback spam).
+    # Priority: requested -> registry default -> first loaded classical model.
+    model_name = requested_model
+    if requested_model == "best_ensemble":
+        ensemble_components = registry_v2.model_meta.get("best_ensemble", {}).get("components", [])
+        if not ensemble_components:
+            model_name = registry_v2.default_model or ""
 
-    # Deep sequence models need per-sample tensors and are not used in this endpoint.
-    # Classical + ensemble models use batch predict_array().
     family = registry_v2.model_meta.get(model_name, {}).get("family", "classical")
     is_deep = family in ("deep_pytorch", "deep_keras")
-    ml_batchable = (
-        req.use_ml
-        and not is_deep
-        and (model_name == "best_ensemble" or model_name in registry_v2.models)
-    )
+
+    if (model_name not in registry_v2.models) or is_deep:
+        fallback_loaded = [
+            name for name, meta in registry_v2.model_meta.items()
+            if name in registry_v2.models and meta.get("family") == "classical"
+        ]
+        if fallback_loaded:
+            model_name = fallback_loaded[0]
+            family = registry_v2.model_meta.get(model_name, {}).get("family", "classical")
+            is_deep = family in ("deep_pytorch", "deep_keras")
+
+    ml_batchable = req.use_ml and not is_deep and (model_name == "best_ensemble" or model_name in registry_v2.models)
 
     # Determine scaler note for logging (mirrors training decision exactly)
     if registry_v2.model_meta.get(model_name, {}).get("requires_scaling", False):
@@ -337,8 +350,8 @@ async def simulate_batteries(req: SimulateRequest):
 
     effective_model = "linear_fallback"
     log.info(
-        "simulate: %d batteries x %d steps | model=%s | batchable=%s | scaler=%s | unit=%s",
-        len(req.batteries), N, model_name, ml_batchable, scaler_note, time_unit,
+        "simulate: %d batteries x %d steps | requested=%s | effective=%s | batchable=%s | scaler=%s | unit=%s",
+        len(req.batteries), N, requested_model, model_name, ml_batchable, scaler_note, time_unit,
     )
 
     results: list[BatterySimResult] = []

api/routers/visualize.py

@@ -17,6 +17,7 @@ from fastapi.responses import FileResponse
 
 from api.model_registry import registry, classify_degradation, soh_to_color
 from api.schemas import BatteryVizData, DashboardData
+from scripts.download_models import ensure_metadata_first, download_metrics_bundle
 
 router = APIRouter(prefix="/api", tags=["visualization"])
 
@@ -223,9 +224,24 @@ def _battery_stats_for_version(version: str) -> dict:
 def _build_metrics_payload(version: str) -> dict:
     _ensure_version(version)
     root = _version_root(version)
+
+    # Ensure artifacts required by metrics exist locally for this version.
+    try:
+        ensure_metadata_first([version])
+        results_dir = root / "results"
+        figures_dir = root / "figures"
+        has_results = results_dir.exists() and any(results_dir.glob("*"))
+        has_figures = figures_dir.exists() and any(figures_dir.glob("*"))
+        if not has_results and not has_figures:
+            download_metrics_bundle(version)
+    except Exception:
+        # Keep endpoint resilient; payload will still be built from whatever exists.
+        pass
+
     results = root / "results"
     reports = root / "reports"
     models_meta = _safe_read_json(root / "models.json")
+    datamap = _safe_read_json(root / "datamap.json")
 
     unified = _safe_read_csv_first([results / "unified_results.csv"])
     classical_results = _safe_read_csv_first([
@@ -258,9 +274,48 @@ def _build_metrics_payload(version: str) -> dict:
     vae_lstm = _safe_read_json_first([results / "vae_lstm_results.json"])
     dg_itransformer = _safe_read_json_first([results / "dg_itransformer_results.json"])
 
+    # Fallback: build unified/classical-like rows directly from models.json when
+    # result CSVs are not yet downloaded for a version.
+    if not unified and isinstance(models_meta, dict):
+        model_rows = []
+        for name, info in (models_meta.get("models") or {}).items():
+            if not isinstance(info, dict):
+                continue
+            model_rows.append({
+                "model": name,
+                "family": info.get("family"),
+                "R2": info.get("r2"),
+                "MAE": info.get("mae"),
+                "RMSE": info.get("rmse"),
+                "MAPE": info.get("mape"),
+                "within_5pct": info.get("within_5pct"),
+                "f1_macro": info.get("f1_macro"),
+                "f1_weighted": info.get("f1_weighted"),
+            })
+        unified = model_rows
+        if not classical_results:
+            classical_results = [r for r in model_rows if (r.get("family") or "").startswith("classical")]
+
+    # Fallback summaries derived from unified rows
+    if not training_summary and unified:
+        valid_r2 = [r.get("R2") for r in unified if isinstance(r.get("R2"), (int, float))]
+        valid_w5 = [r.get("within_5pct") for r in unified if isinstance(r.get("within_5pct"), (int, float))]
+        best = max(unified, key=lambda r: r.get("R2") if isinstance(r.get("R2"), (int, float)) else -999)
+        training_summary = {
+            "best_model": best.get("model"),
+            "best_r2": best.get("R2"),
+            "best_within_5pct": best.get("within_5pct"),
+            "total_models": len(unified),
+            "mean_within_5pct": (sum(valid_w5) / len(valid_w5)) if valid_w5 else None,
+            "passed_models": sum(1 for v in valid_w5 if v >= 95.0),
+            "pass_rate_pct": (sum(1 for v in valid_w5 if v >= 95.0) / len(valid_w5) * 100.0) if valid_w5 else 0.0,
+            "mean_r2": (sum(valid_r2) / len(valid_r2)) if valid_r2 else None,
+        }
+
     return {
         "version": version,
         "models_meta": models_meta,
+        "datamap": datamap,
         "unified_results": unified,
         "classical_results": classical_results,
         "classical_soh": classical_soh,

frontend/src/App.tsx

@@ -82,7 +82,7 @@ export default function App() {
         {activeTab === "predict" && <PredictionForm apiVersion={apiVersion} />}
         {activeTab === "graphs" && <GraphPanel />}
         {activeTab === "recommend" && <RecommendationPanel apiVersion={apiVersion} />}
-        {activeTab === "metrics" && <MetricsPanel />}
+        {activeTab === "metrics" && <MetricsPanel apiVersion={apiVersion} />}
         {activeTab === "paper" && <ResearchPaper />}
       </main>
 

frontend/src/components/MetricsPanel.tsx

@@ -99,7 +99,11 @@ function StatCard({ label, value, color = "text-green-400", subtitle, icon, tren
   );
 }
 
-export default function MetricsPanel() {
+type Props = {
+  apiVersion?: "v1" | "v2" | "v3";
+};
+
+export default function MetricsPanel({ apiVersion = "v3" }: Props) {
   const [data, setData] = useState<MetricsData | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -114,6 +118,10 @@ export default function MetricsPanel() {
   const [compareSelected, setCompareSelected] = useState<string[]>([]);
   const [chartView, setChartView] = useState<"bar" | "radar" | "scatter">("bar");
 
+  useEffect(() => {
+    setActiveVersion(apiVersion);
+  }, [apiVersion]);
+
   useEffect(() => {
     setLoading(true);
     setError(null);

frontend/src/components/RecommendationPanel.tsx

@@ -1,4 +1,7 @@
 import { useEffect, useState, useMemo } from "react";
+import { Canvas } from "@react-three/fiber";
+import { OrbitControls, Html } from "@react-three/drei";
+import * as THREE from "three";
 import {
   BarChart, Bar, XAxis, YAxis, Tooltip, Legend, ResponsiveContainer,
   CartesianGrid, RadarChart, Radar, PolarGrid, PolarAngleAxis, PolarRadiusAxis,
@@ -50,6 +53,40 @@ type Props = {
   apiVersion: "v1" | "v2" | "v3";
 };
 
+function Battery3D({ currentSoh, projectedSoh }: { currentSoh: number; projectedSoh: number }) {
+  const clamped = Math.max(0, Math.min(100, projectedSoh));
+  const fillHeight = 0.2 + (clamped / 100) * 2.6;
+  const fillY = -1.4 + fillHeight / 2;
+  const color = clamped >= 90 ? "#22c55e" : clamped >= 80 ? "#eab308" : clamped >= 70 ? "#f97316" : "#ef4444";
+
+  return (
+    <Canvas camera={{ position: [3.2, 2.2, 3.2], fov: 45 }}>
+      <ambientLight intensity={0.7} />
+      <directionalLight position={[3, 5, 2]} intensity={1.1} />
+      <group>
+        <mesh>
+          <cylinderGeometry args={[0.9, 0.9, 3.1, 48]} />
+          <meshPhysicalMaterial color="#94a3b8" transparent opacity={0.16} transmission={0.8} roughness={0.05} />
+        </mesh>
+        <mesh position={[0, fillY, 0]}>
+          <cylinderGeometry args={[0.76, 0.76, fillHeight, 48]} />
+          <meshStandardMaterial color={color} emissive={color} emissiveIntensity={0.3} roughness={0.35} />
+        </mesh>
+        <mesh position={[0, 1.75, 0]}>
+          <cylinderGeometry args={[0.24, 0.24, 0.22, 24]} />
+          <meshStandardMaterial color="#e5e7eb" metalness={0.9} roughness={0.1} />
+        </mesh>
+        <Html position={[0, -2.15, 0]} center>
+          <div className="text-xs text-gray-300 bg-gray-900/80 border border-gray-700 rounded px-2 py-1">
+            SOH: <span className="font-semibold text-white">{currentSoh.toFixed(1)}%</span> → <span className="font-semibold" style={{ color }}>{clamped.toFixed(1)}%</span>
+          </div>
+        </Html>
+      </group>
+      <OrbitControls enablePan={false} maxDistance={6} minDistance={2.4} />
+    </Canvas>
+  );
+}
+
 export default function RecommendationPanel({ apiVersion }: Props) {
   const [batteryId, setBatteryId] = useState("B0005");
   const [currentCycle, setCurrentCycle] = useState(100);
@@ -62,6 +99,7 @@ export default function RecommendationPanel({ apiVersion }: Props) {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [expandedRow, setExpandedRow] = useState<number | null>(null);
+  const [selectedRank, setSelectedRank] = useState<number>(1);
   const [chartTab, setChartTab] = useState<"rul" | "params" | "radar">("rul");
 
   // Fetch available loaded models for selector
@@ -84,6 +122,7 @@ export default function RecommendationPanel({ apiVersion }: Props) {
         ...(selectedModel ? { model_name: selectedModel } : {}),
       });
       setResult(res);
+      setSelectedRank(1);
     } catch (e: any) {
       setError(e.response?.data?.detail || e.message);
     } finally {
@@ -127,6 +166,8 @@ export default function RecommendationPanel({ apiVersion }: Props) {
 
   const baseline = result?.recommendations[0];
   const bestOnly = result?.recommendations.find((r) => r.rank === 1);
+  const selectedRec = result?.recommendations.find((r) => r.rank === selectedRank) ?? bestOnly;
+  const projectedSoh = Math.min(100, currentSoh + ((selectedRec?.rul_improvement_pct ?? 0) / 6));
 
   return (
     <div className="space-y-5">
@@ -327,18 +368,19 @@ export default function RecommendationPanel({ apiVersion }: Props) {
             )}
           </div>
 
-          {/* Recommendations table */}
-          <div className="bg-gray-900 rounded-xl border border-gray-800 overflow-hidden">
-            <div className="p-4 border-b border-gray-800 flex items-center justify-between">
-              <div className="flex items-center gap-2">
-                <Trophy className="w-4 h-4 text-yellow-400" />
-                <span className="text-sm font-semibold text-gray-300">
-                  Recommendations for {result.battery_id} — SOH: {result.current_soh}%
-                </span>
+          <div className="grid grid-cols-1 xl:grid-cols-2 gap-5">
+            {/* Recommendations table */}
+            <div className="bg-gray-900 rounded-xl border border-gray-800 overflow-hidden">
+              <div className="p-4 border-b border-gray-800 flex items-center justify-between">
+                <div className="flex items-center gap-2">
+                  <Trophy className="w-4 h-4 text-yellow-400" />
+                  <span className="text-sm font-semibold text-gray-300">
+                    Recommendations for {result.battery_id} — SOH: {result.current_soh}%
+                  </span>
+                </div>
+                <span className="text-xs text-gray-500">{result.recommendations.length} configs</span>
               </div>
-              <span className="text-xs text-gray-500">{result.recommendations.length} configs</span>
-            </div>
-            <div className="overflow-x-auto">
+              <div className="overflow-x-auto">
               <table className="w-full text-sm">
                 <thead>
                   <tr className="text-gray-500 border-b border-gray-800 bg-gray-950/50">
@@ -361,9 +403,12 @@ export default function RecommendationPanel({ apiVersion }: Props) {
                         <tr
                           key={rec.rank}
                           className={`border-b border-gray-800/40 hover:bg-gray-800/40 transition-colors cursor-pointer ${
-                            rec.rank === 1 ? "bg-yellow-900/10" : ""
+                            rec.rank === selectedRank ? "bg-emerald-900/20" : rec.rank === 1 ? "bg-yellow-900/10" : ""
                           }`}
-                          onClick={() => setExpandedRow(expanded ? null : rec.rank)}
+                          onClick={() => {
+                            setExpandedRow(expanded ? null : rec.rank);
+                            setSelectedRank(rec.rank);
+                          }}
                         >
                           <td className="py-2.5 px-3">
                             <span className="flex items-center"><RankIcon rank={rec.rank} /></span>
@@ -421,6 +466,23 @@ export default function RecommendationPanel({ apiVersion }: Props) {
                   })}
                 </tbody>
               </table>
+              </div>
+            </div>
+
+            {/* Interactive 3D battery panel */}
+            <div className="bg-gray-900 rounded-xl border border-gray-800 overflow-hidden">
+              <div className="p-4 border-b border-gray-800 flex items-center justify-between">
+                <span className="text-sm font-semibold text-gray-300">Interactive Battery Impact</span>
+                <span className="text-xs text-emerald-400">Selected: #{selectedRec?.rank ?? 1}</span>
+              </div>
+              <div className="h-105">
+                <Battery3D currentSoh={currentSoh} projectedSoh={projectedSoh} />
+              </div>
+              <div className="p-4 border-t border-gray-800 text-xs text-gray-400 space-y-1">
+                <div>RUL: <span className="text-white font-semibold">{selectedRec?.predicted_rul.toFixed(0) ?? "-"} cycles</span></div>
+                <div>Gain: <span className="text-emerald-400 font-semibold">{selectedRec && selectedRec.rul_improvement > 0 ? "+" : ""}{selectedRec?.rul_improvement.toFixed(0) ?? "-"} cycles</span></div>
+                <div>Conditions: <span className="text-white">{selectedRec?.ambient_temperature}°C, {selectedRec?.discharge_current}A, {selectedRec?.cutoff_voltage}V</span></div>
+              </div>
             </div>
           </div>
         </div>

frontend/src/components/ResearchPaper.tsx

@@ -32,16 +32,13 @@ const mdComponents: React.ComponentProps<typeof ReactMarkdown>["components"] = {
 
   // ── Lists ─────────────────────────────────────────────────────────────
   ul: ({ children }) => (
-    <ul className="space-y-1.5 mb-4 pl-1">{children}</ul>
+    <ul className="list-disc list-inside space-y-1.5 mb-4 text-gray-300 text-sm">{children}</ul>
   ),
   ol: ({ children }) => (
     <ol className="list-decimal list-inside space-y-1.5 mb-4 text-gray-300 text-sm">{children}</ol>
   ),
   li: ({ children }) => (
-    <li className="flex items-start gap-2 text-gray-300 text-sm">
-      <span className="text-green-400 mt-1 shrink-0">•</span>
-      <span>{children}</span>
-    </li>
+    <li className="text-gray-300 text-sm">{children}</li>
   ),
 
   // ── Code ─────────────────────────────────────────────────────────────
@@ -189,20 +186,27 @@ export default function ResearchPaper() {
   const [usedFallback, setUsedFallback] = useState(false);
 
   useEffect(() => {
-    fetch("/research_paper.md")
-      .then((r) => {
-        if (!r.ok) throw new Error(`HTTP ${r.status}`);
-        return r.text();
-      })
-      .then((md) => {
-        setMarkdown(md);
-        setLoading(false);
-      })
-      .catch(() => {
-        setMarkdown(FALLBACK);
-        setUsedFallback(true);
-        setLoading(false);
-      });
+    const sources = ["/research_paper.md", "/docs/research_paper.md"];
+    const tryLoad = async () => {
+      for (const src of sources) {
+        try {
+          const r = await fetch(src);
+          if (!r.ok) continue;
+          const md = await r.text();
+          if (md && md.trim().length > 0) {
+            setMarkdown(md);
+            setLoading(false);
+            return;
+          }
+        } catch {
+          // Try next source
+        }
+      }
+      setMarkdown(FALLBACK);
+      setUsedFallback(true);
+      setLoading(false);
+    };
+    tryLoad();
   }, []);
 
   return (

frontend/src/components/VersionSelector.tsx

@@ -11,11 +11,10 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
-  ChevronRight, Download, Check, RefreshCw, AlertCircle, Layers, HardDrive,
+  ChevronRight, Check, RefreshCw, Layers,
 } from "lucide-react";
 import {
   fetchVersions,
-  loadVersion,
   VersionInfo,
   fetchVersionModels,
   loadVersionModel,
@@ -30,7 +29,6 @@ interface Props {
 export default function VersionSelector({ activeVersion, onSwitch }: Props) {
   const [open, setOpen] = useState(false);
   const [versions, setVersions] = useState<VersionInfo[]>([]);
-  const [busy, setBusy] = useState<string | null>(null);
   const [modelBusy, setModelBusy] = useState<string | null>(null);
   const [expandedVersion, setExpandedVersion] = useState<string | null>(null);
   const [versionModels, setVersionModels] = useState<Record<string, VersionModelInfo[]>>({});
@@ -49,19 +47,14 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
 
   // Poll while a download is in progress
   useEffect(() => {
-    const hasDownloading = versions.some((v) => v.status === "downloading");
     const hasModelDownloading = Object.values(versionModels)
       .some((rows) => rows.some((m) => m.status === "downloading"));
-    if (hasDownloading && !pollRef.current) {
-      pollRef.current = setInterval(refresh, 2500);
-    }
     if (hasModelDownloading && !pollRef.current) {
       pollRef.current = setInterval(refresh, 2500);
     }
-    if (!hasDownloading && !hasModelDownloading && pollRef.current) {
+    if (!hasModelDownloading && pollRef.current) {
       clearInterval(pollRef.current);
       pollRef.current = null;
-      setBusy(null);
       setModelBusy(null);
     }
     return () => {
@@ -90,25 +83,8 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
     return () => document.removeEventListener("mousedown", handler);
   }, [open]);
 
-  const handleDownloadOrLoad = async (version: string) => {
-    setBusy(version);
-    try {
-      const res = await loadVersion(version);
-      if (res.status === "ready") {
-        // Loaded instantly from disk — auto-switch
-        onSwitch(version as "v1" | "v2" | "v3");
-        setBusy(null);
-        setOpen(false);
-      }
-      refresh();
-    } catch {
-      setBusy(null);
-    }
-  };
-
   const handleSwitch = (version: string) => {
     onSwitch(version as "v1" | "v2" | "v3");
-    setOpen(false);
   };
 
   const handleExpandVersion = async (version: string) => {
@@ -139,7 +115,7 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
   };
 
   const statusForVersion = (v: VersionInfo) => {
-    const isDownloading = v.status === "downloading" || busy === v.id;
+    const isDownloading = v.status === "downloading";
     const isError = v.status === "error";
     const isLoaded = v.loaded && v.model_count > 0;
     const isOnDisk = v.status === "on_disk" || (v.on_disk && !isLoaded && !isDownloading && !isError);
@@ -147,18 +123,6 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
     return { isDownloading, isError, isLoaded, isOnDisk, isNotDownloaded };
   };
 
-  // Auto-switch when download completes
-  useEffect(() => {
-    if (busy) {
-      const v = versions.find((ver) => ver.id === busy);
-      if (v && v.status === "ready" && v.loaded && v.model_count > 0) {
-        onSwitch(busy as "v1" | "v2" | "v3");
-        setBusy(null);
-        setOpen(false);
-      }
-    }
-  }, [versions, busy, onSwitch]);
-
   const activeDisplay = versions.find((v) => v.id === activeVersion)?.display
     ?? `v${activeVersion[1]}.0`;
 
@@ -195,7 +159,7 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
           </div>
 
           {versions.map((v) => {
-            const { isDownloading, isError, isLoaded, isOnDisk, isNotDownloaded } = statusForVersion(v);
+            const { isDownloading, isLoaded } = statusForVersion(v);
             const isActiveVersion = v.id === activeVersion;
             const isExpanded = expandedVersion === v.id;
             const models = versionModels[v.id] ?? [];
@@ -207,7 +171,13 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
                     hover:bg-gray-800/60 transition-colors"
                 >
                   <div className="flex-1 min-w-0">
-                    <span className={`text-sm font-medium ${isActiveVersion ? "text-white" : "text-gray-200"}`}>{v.display}</span>
+                    <button
+                      onClick={() => handleSwitch(v.id)}
+                      className={`text-sm font-medium ${isActiveVersion ? "text-white" : "text-gray-200 hover:text-white"}`}
+                      title={`Switch to ${v.display}`}
+                    >
+                      {v.display}
+                    </button>
                     {isActiveVersion && (
                       <span className="ml-2 text-xs text-green-400 italic">Active Version</span>
                     )}
@@ -221,72 +191,20 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
                         {v.model_count} models
                       </span>
                     )}
-                    {isOnDisk && (
-                      <span className="ml-2 text-xs text-yellow-400">on disk</span>
-                    )}
-                    {isError && (
-                      <span className="ml-2 text-xs text-red-400">error</span>
-                    )}
                     {isDownloading && (
                       <span className="ml-2 text-xs text-yellow-400 animate-pulse">
                         downloading...
                       </span>
                     )}
-                    {isNotDownloaded && (
-                      <span className="ml-2 text-xs text-gray-600">not downloaded</span>
-                    )}
                   </div>
 
                   <div className="flex items-center gap-1 shrink-0 ml-2">
-                    {isLoaded && !isActiveVersion && (
-                      <button
-                        onClick={() => handleSwitch(v.id)}
-                        className="px-2.5 py-1 rounded text-xs font-medium
-                          bg-green-700 hover:bg-green-600 text-white transition-colors"
-                        title={`Switch to ${v.display}`}
-                      >
-                        Switch
-                      </button>
-                    )}
-
-                    {isOnDisk && !isDownloading && (
-                      <button
-                        onClick={() => handleDownloadOrLoad(v.id)}
-                        className="flex items-center gap-1 px-2.5 py-1 rounded text-xs font-medium
-                          bg-blue-700 hover:bg-blue-600 text-white transition-colors"
-                        title={`Load ${v.display} into memory`}
-                      >
-                        <HardDrive className="w-3 h-3" />
-                        Load
-                      </button>
-                    )}
-
-                    {isNotDownloaded && !isDownloading && !isError && (
-                      <button
-                        onClick={() => handleDownloadOrLoad(v.id)}
-                        className="flex items-center gap-1 px-2.5 py-1 rounded text-xs font-medium
-                          bg-gray-700 hover:bg-gray-600 text-gray-300 hover:text-white transition-colors"
-                        title={`Download ${v.display} from HF Hub`}
-                      >
-                        <Download className="w-3 h-3" />
-                        Download
-                      </button>
-                    )}
-
                     {isDownloading && (
                       <RefreshCw className="w-3.5 h-3.5 text-yellow-400 animate-spin" />
                     )}
 
-                    {isError && !isDownloading && (
-                      <button
-                        onClick={() => handleDownloadOrLoad(v.id)}
-                        className="flex items-center gap-1 px-2.5 py-1 rounded text-xs font-medium
-                          bg-gray-700 hover:bg-red-700 text-red-400 hover:text-white transition-colors"
-                        title="Retry download"
-                      >
-                        <AlertCircle className="w-3 h-3" />
-                        Retry
-                      </button>
+                    {isLoaded && (
+                      <Check className="w-3.5 h-3.5 text-green-400" />
                     )}
 
                     <button

scripts/download_models.py

@@ -90,6 +90,27 @@ def _ensure_hub():
                                "huggingface_hub>=0.23", "-q"])
 
 
+def write_datamap(version: str) -> None:
+    """Write artifacts/<version>/datamap.json listing all locally available files."""
+    vroot = ARTIFACTS_DIR / version
+    vroot.mkdir(parents=True, exist_ok=True)
+    items = []
+    for p in sorted(vroot.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(vroot).as_posix()
+        items.append({
+            "path": rel,
+            "bytes": p.stat().st_size,
+        })
+    out = {
+        "version": version,
+        "count": len(items),
+        "files": items,
+    }
+    (vroot / "datamap.json").write_text(json.dumps(out, indent=2), encoding="utf-8")
+
+
 def download_version(version: str) -> None:
     """Download a single version (e.g. 'v1' or 'v2') from HF Hub into artifacts/."""
     _ensure_hub()
@@ -100,6 +121,7 @@ def download_version(version: str) -> None:
         allow_patterns=[f"{version}/**"],
         ignore_patterns=["*.log"],
     ))
+    write_datamap(version)
     print(f"[download_models] {version}/ ready")
 
 
@@ -199,6 +221,7 @@ def download_models(version: str, model_names: list[str]) -> None:
         allow_patterns=allow,
         ignore_patterns=["*.log"],
     ))
+    write_datamap(version)
     print(f"[download_models] Selected model artifacts ready for {version}")
 
 
@@ -207,17 +230,41 @@ def download_model(version: str, model_name: str) -> None:
     download_models(version, [model_name])
 
 
+def download_metrics_bundle(version: str) -> None:
+    """Download files needed by metrics page for a specific version."""
+    _ensure_hub()
+    from huggingface_hub import snapshot_download
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+    allow = [
+        f"{version}/models.json",
+        f"{version}/datamap.json",
+        f"{version}/results/**",
+        f"{version}/reports/**",
+        f"{version}/features/**",
+        f"{version}/figures/**",
+    ]
+    print(f"[download_models] Downloading metrics bundle for {version}")
+    snapshot_download(**_hf_kwargs(
+        allow_patterns=allow,
+        ignore_patterns=["*.log"],
+    ))
+    write_datamap(version)
+    print(f"[download_models] Metrics bundle ready for {version}")
+
+
 def download_models_meta_only(versions: list[str]) -> None:
     """Download only models.json for listed versions."""
     _ensure_hub()
     from huggingface_hub import snapshot_download
     ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
-    allow = [f"{v}/models.json" for v in versions]
+    allow = [f"{v}/models.json" for v in versions] + [f"{v}/datamap.json" for v in versions]
     print(f"[download_models] Downloading metadata files: {allow}")
     snapshot_download(**_hf_kwargs(
         allow_patterns=allow,
         ignore_patterns=["*.log"],
     ))
+    for v in versions:
+        write_datamap(v)
     print("[download_models] Metadata ready")
 
 
@@ -228,10 +275,18 @@ def download_all() -> None:
     ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
     print(f"[download_models] Downloading all versions from {REPO_ID} -> {ARTIFACTS_DIR}")
     snapshot_download(**_hf_kwargs(ignore_patterns=["*.log"]))
+    for v in ("v1", "v2", "v3"):
+        write_datamap(v)
     SENTINEL.write_text("downloaded\n")
     print("[download_models] Artifacts ready")
 
 
+def ensure_metadata_first(versions: list[str] | None = None) -> None:
+    """Guarantee models.json/datamap are present before registry usage."""
+    versions = versions or ["v1", "v2", "v3"]
+    download_models_meta_only(versions)
+
+
 def main() -> None:
     import argparse
     parser = argparse.ArgumentParser()