fix: memory overload by adding top models and options to load singular models

api/main.py

@@ -53,6 +53,7 @@ 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 src.utils.logger import get_logger
 
 log = get_logger(__name__)
@@ -67,10 +68,20 @@ _FRONTEND_DIST = _HERE.parent / "frontend" / "dist"
 # ── Lifespan ─────────────────────────────────────────────────────────────────
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """Load only v3 (latest) models on startup; v1/v2 loaded on-demand."""
+    """Load only top v3 models on startup; v1/v2 loaded on-demand."""
     log.info("Loading model registries …")
-    registry_v3.load_all()
-    log.info("v3 registry ready — %d models loaded", registry_v3.model_count)
+    startup_models = select_top_models("v3")
+    if startup_models:
+        registry_v3.load_all(only_models=set(startup_models))
+        log.info(
+            "v3 registry ready — %d models loaded (startup top-%d set: %s)",
+            registry_v3.model_count,
+            DEFAULT_STARTUP_TOP_MODELS,
+            ", ".join(startup_models),
+        )
+    else:
+        registry_v3.load_all()
+        log.warning("Top-5 selection unavailable; loaded full v3 registry")
     # v1 and v2 are NOT loaded at startup — download + load on-demand via
     # POST /api/versions/{v}/load to reduce startup time and memory usage.
     if _version_loaded("v1"):
@@ -118,6 +129,7 @@ async def health():
 # ── Version management ───────────────────────────────────────────────────────
 _REGISTRIES = {"v1": registry_v1, "v2": registry_v2, "v3": registry_v3}
 _version_status: dict[str, str] = {}   # "downloading" | "ready" | "error"
+_model_status: dict[str, str] = {}     # "vX:model" -> status
 
 
 def _artifacts_dir() -> Path:
@@ -125,8 +137,14 @@ def _artifacts_dir() -> Path:
 
 
 def _version_loaded(version: str) -> bool:
-    base = _artifacts_dir() / version / "models" / "classical"
-    return any(base.glob("*.joblib")) if base.exists() else False
+    base = _artifacts_dir() / version / "models"
+    if not base.exists():
+        return False
+    return any(base.rglob("*.joblib")) or any(base.rglob("*.pt")) or any(base.rglob("*.keras"))
+
+
+def _model_status_key(version: str, model_name: str) -> str:
+    return f"{version}:{model_name}"
 
 
 @app.get("/api/versions", tags=["meta"])
@@ -157,7 +175,7 @@ async def list_versions():
 
 
 async def _bg_load_version(version: str) -> None:
-    import subprocess, sys as _sys
+    import sys as _sys
     try:
         proc = await asyncio.create_subprocess_exec(
             _sys.executable, "scripts/download_models.py", "--version", version,
@@ -177,6 +195,33 @@ async def _bg_load_version(version: str) -> None:
         log.error("Failed to load version %s: %s", version, exc)
 
 
+async def _bg_load_model(version: str, model_name: str) -> None:
+    import sys as _sys
+
+    key = _model_status_key(version, model_name)
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            _sys.executable,
+            "scripts/download_models.py",
+            "--version",
+            version,
+            "--model",
+            model_name,
+            stdout=asyncio.subprocess.PIPE,
+            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)
+        else:
+            _model_status[key] = "error"
+            log.error("Failed to download/load 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)
+
+
 @app.post("/api/versions/{version}/load", tags=["meta"])
 async def load_version(version: str, background_tasks: BackgroundTasks):
     """Download + activate a model version from HF Hub (runs in background)."""
@@ -210,6 +255,65 @@ async def get_version_models_meta(version: str):
     return _json.loads(meta_path.read_text(encoding="utf-8"))
 
 
+@app.get("/api/versions/{version}/models", tags=["meta"])
+async def list_version_models(version: str):
+    """List all models in models.json with disk/memory/load status."""
+    if version not in _REGISTRIES:
+        raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+
+    reg = _REGISTRIES[version]
+    rows = []
+    for model_name, info in reg._catalog.items():
+        key = _model_status_key(version, model_name)
+        status = _model_status.get(key)
+        loaded = model_name in reg.models
+        if status is None:
+            status = "ready" if loaded else ("on_disk" if reg.model_on_disk(model_name) else "not_downloaded")
+        rows.append({
+            "name": model_name,
+            "display_name": info.get("display_name", model_name),
+            "family": info.get("family", "unknown"),
+            "r2": info.get("r2"),
+            "has_file": bool(info.get("file")),
+            "on_disk": reg.model_on_disk(model_name),
+            "loaded": loaded,
+            "status": status,
+        })
+    return rows
+
+
+@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."""
+    if version not in _REGISTRIES:
+        raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+
+    reg = _REGISTRIES[version]
+    if model_name not in reg._catalog:
+        raise HTTPException(status_code=404, detail=f"Unknown model '{model_name}' in {version}")
+
+    # Virtual models have no direct downloadable artifact.
+    if not reg._catalog.get(model_name, {}).get("file"):
+        if reg.load_model(model_name):
+            return {"status": "ready", "version": version, "model": model_name}
+        raise HTTPException(status_code=400, detail=f"Model '{model_name}' cannot be loaded directly")
+
+    key = _model_status_key(version, model_name)
+    if _model_status.get(key) == "downloading":
+        return {"status": "downloading", "version": version, "model": model_name}
+
+    if reg.model_on_disk(model_name):
+        if reg.load_model(model_name):
+            _model_status[key] = "ready"
+            return {"status": "ready", "version": version, "model": model_name}
+        _model_status[key] = "error"
+        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)
+    return {"status": "downloading", "version": version, "model": model_name}
+
+
 # ── Include routers ──────────────────────────────────────────────────────────
 from api.routers.predict import router as predict_router, v1_router
 from api.routers.predict_v2 import router as predict_v2_router

api/model_registry.py

@@ -185,22 +185,49 @@ class ModelRegistry:
             cinfo = self._catalog.get(cname, {})
             self._ensemble_weights[cname] = cinfo.get("r2", 1.0)
 
+    def model_on_disk(self, model_name: str) -> bool:
+        """Return True when the model artifact file exists on disk.
+
+        Virtual models (e.g., best_ensemble) have no direct file and therefore
+        return False.
+        """
+        info = self._catalog.get(model_name, {})
+        rel = info.get("file")
+        if not rel:
+            return False
+        return (self._artifacts / rel).exists()
+
+    def load_model(self, model_name: str) -> bool:
+        """Load one model (and ensemble dependencies when applicable).
+
+        Returns True if the target model is available in memory after loading.
+        """
+        if model_name in self.models:
+            return True
+
+        targets: set[str] = {model_name}
+        if model_name == "best_ensemble":
+            targets.update(self._ensemble_components)
+
+        self.load_all(only_models=targets)
+        return model_name in self.models
+
     # ── Loading ──────────────────────────────────────────────────────────
-    def load_all(self) -> None:
+    def load_all(self, only_models: set[str] | None = None) -> None:
         """Scan artifacts/models and load all available model artefacts.
 
         Safe to call multiple times — subsequent calls are no-ops when the
         registry is already populated.
         """
-        if self.models:
+        if only_models is None and self.models:
             log.debug("Registry already populated — skipping load_all()")
             return
         self._detect_device()
         self._load_scaler()
         self.feature_cols = self._load_feature_cols()
-        self._load_classical()
-        self._load_deep_pytorch()
-        self._load_deep_keras()
+        self._load_classical(only_models=only_models)
+        self._load_deep_pytorch(only_models=only_models)
+        self._load_deep_keras(only_models=only_models)
         self._register_ensemble()
         self._choose_default()
         log.info(
@@ -217,7 +244,7 @@ class ModelRegistry:
         except ImportError:
             log.info("torch not installed — deep PyTorch models unavailable")
 
-    def _load_classical(self) -> None:
+    def _load_classical(self, only_models: set[str] | None = None) -> None:
         """Eagerly load all sklearn/XGBoost/LightGBM joblib artefacts."""
         cdir = self._models_dir / "classical"
         if not cdir.exists():
@@ -225,6 +252,10 @@ class ModelRegistry:
             return
         for p in sorted(cdir.glob("*.joblib")):
             name = p.stem
+            if only_models is not None and name not in only_models:
+                continue
+            if name in self.models:
+                continue
             # Skip non-model dumps (param search results, classifiers)
             if (
                 "best_params" in name
@@ -308,7 +339,7 @@ class ModelRegistry:
             log.warning("Cannot build PyTorch model '%s': %s", name, exc)
         return None
 
-    def _load_deep_pytorch(self) -> None:
+    def _load_deep_pytorch(self, only_models: set[str] | None = None) -> None:
         """Load PyTorch .pt state-dict files into reconstructed model instances."""
         ddir = self._models_dir / "deep"
         if not ddir.exists():
@@ -320,6 +351,10 @@ class ModelRegistry:
             return
         for p in sorted(ddir.glob("*.pt")):
             name = p.stem
+            if only_models is not None and name not in only_models:
+                continue
+            if name in self.models:
+                continue
             n_feat = self._detect_n_feat(p)
             model = self._build_pytorch_model(name, n_feat=n_feat)
             if model is None:
@@ -349,11 +384,20 @@ class ModelRegistry:
                     "path": str(p), "load_error": str(exc),
                 }
 
-    def _load_deep_keras(self) -> None:
+    def _load_deep_keras(self, only_models: set[str] | None = None) -> None:
         """Load TensorFlow/Keras .keras model files."""
         ddir = self._models_dir / "deep"
         if not ddir.exists():
             return
+
+        if only_models is not None:
+            requested_keras = any(
+                self._catalog.get(m, {}).get("family") == "deep_keras"
+                for m in only_models
+            )
+            if not requested_keras:
+                return
+
         try:
             import tensorflow as tf
         except ImportError:
@@ -382,6 +426,10 @@ class ModelRegistry:
             _custom_objects = {}
         for p in sorted(ddir.glob("*.keras")):
             name = p.stem
+            if only_models is not None and name not in only_models:
+                continue
+            if name in self.models:
+                continue
             try:
                 model = tf.keras.models.load_model(str(p), custom_objects=_custom_objects, safe_mode=False)
                 self.models[name] = model

frontend/src/api.ts

@@ -86,6 +86,25 @@ export const fetchVersions = () =>
 export const loadVersion = (version: string) =>
   baseApi.post<{ status: string; version: string }>(`/versions/${version}/load`).then((r) => r.data);
 
+export interface VersionModelInfo {
+  name: string;
+  display_name: string;
+  family: string;
+  r2: number | null;
+  has_file: boolean;
+  on_disk: boolean;
+  loaded: boolean;
+  status: "ready" | "on_disk" | "not_downloaded" | "downloading" | "error";
+}
+
+export const fetchVersionModels = (version: string) =>
+  baseApi.get<VersionModelInfo[]>(`/versions/${version}/models`).then((r) => r.data);
+
+export const loadVersionModel = (version: string, model: string) =>
+  baseApi
+    .post<{ status: string; version: string; model: string }>(`/versions/${version}/models/${model}/load`)
+    .then((r) => r.data);
+
 /** Models metadata JSON for a specific version. */
 export const fetchVersionModelsMeta = (version: string) =>
   baseApi.get<any>(`/versions/${version}/models-meta`).then((r) => r.data);

frontend/src/components/VersionSelector.tsx

@@ -13,7 +13,14 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import {
   ChevronRight, Download, Check, RefreshCw, AlertCircle, Layers, HardDrive,
 } from "lucide-react";
-import { fetchVersions, loadVersion, VersionInfo } from "../api";
+import {
+  fetchVersions,
+  loadVersion,
+  VersionInfo,
+  fetchVersionModels,
+  loadVersionModel,
+  VersionModelInfo,
+} from "../api";
 
 interface Props {
   activeVersion: "v1" | "v2" | "v3";
@@ -24,6 +31,9 @@ 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[]>>({});
   const menuRef = useRef<HTMLDivElement>(null);
   const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
 
@@ -40,18 +50,33 @@ 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 (!hasDownloading && pollRef.current) {
+    if (hasModelDownloading && !pollRef.current) {
+      pollRef.current = setInterval(refresh, 2500);
+    }
+    if (!hasDownloading && !hasModelDownloading && pollRef.current) {
       clearInterval(pollRef.current);
       pollRef.current = null;
       setBusy(null);
+      setModelBusy(null);
     }
     return () => {
       if (pollRef.current) clearInterval(pollRef.current);
     };
-  }, [versions, refresh]);
+  }, [versions, versionModels, refresh]);
+
+  useEffect(() => {
+    if (!expandedVersion) return;
+    fetchVersionModels(expandedVersion)
+      .then((rows) => {
+        setVersionModels((prev) => ({ ...prev, [expandedVersion]: rows }));
+      })
+      .catch(() => {});
+  }, [expandedVersion, versions]);
 
   // Close on outside click
   useEffect(() => {
@@ -86,6 +111,33 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
     setOpen(false);
   };
 
+  const handleExpandVersion = async (version: string) => {
+    if (expandedVersion === version) {
+      setExpandedVersion(null);
+      return;
+    }
+    setExpandedVersion(version);
+    try {
+      const rows = await fetchVersionModels(version);
+      setVersionModels((prev) => ({ ...prev, [version]: rows }));
+    } catch {
+      // ignore
+    }
+  };
+
+  const handleLoadModel = async (version: string, model: string) => {
+    const key = `${version}:${model}`;
+    setModelBusy(key);
+    try {
+      await loadVersionModel(version, model);
+      const rows = await fetchVersionModels(version);
+      setVersionModels((prev) => ({ ...prev, [version]: rows }));
+      refresh();
+    } catch {
+      // ignore
+    }
+  };
+
   // Auto-switch when download completes
   useEffect(() => {
     if (busy) {
@@ -156,98 +208,153 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
             const isLoaded = v.loaded && v.model_count > 0;
             const isOnDisk = v.status === "on_disk" || (v.on_disk && !isLoaded && !isDownloading && !isError);
             const isNotDownloaded = v.status === "not_downloaded" && !v.on_disk;
+            const isExpanded = expandedVersion === v.id;
+            const models = versionModels[v.id] ?? [];
 
             return (
-              <div
-                key={v.id}
-                className="flex items-center justify-between px-3 py-2.5
-                  hover:bg-gray-800/60 transition-colors"
-              >
-                <div className="flex-1 min-w-0">
-                  <span className="text-sm font-medium text-gray-200">{v.display}</span>
-                  {v.features && (
-                    <span className="ml-2 text-xs text-gray-500">
-                      {v.features}f
-                    </span>
-                  )}
-                  {isLoaded && (
-                    <span className="ml-2 text-xs text-gray-500">
-                      {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 key={v.id} className="border-t border-gray-800/80 first:border-t-0">
+                <div
+                  className="flex items-center justify-between px-3 py-2.5
+                    hover:bg-gray-800/60 transition-colors"
+                >
+                  <div className="flex-1 min-w-0">
+                    <span className="text-sm font-medium text-gray-200">{v.display}</span>
+                    {v.features && (
+                      <span className="ml-2 text-xs text-gray-500">
+                        {v.features}f
+                      </span>
+                    )}
+                    {isLoaded && (
+                      <span className="ml-2 text-xs text-gray-500">
+                        {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">
-                  {/* Switch button — loaded and ready */}
-                  {isLoaded && (
-                    <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>
-                  )}
+                  <div className="flex items-center gap-1 shrink-0 ml-2">
+                    {isLoaded && (
+                      <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>
+                    )}
 
-                  {/* Load button — on disk but not loaded in memory */}
-                  {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>
-                  )}
+                    {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>
+                    )}
 
-                  {/* Download button — not on disk */}
-                  {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>
-                  )}
+                    {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" />
+                    )}
 
-                  {/* Spinner while downloading */}
-                  {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>
+                    )}
 
-                  {/* Error retry */}
-                  {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"
+                      onClick={() => handleExpandVersion(v.id)}
+                      className="px-2 py-1 rounded text-xs font-medium bg-gray-800 hover:bg-gray-700 text-gray-300 transition-colors"
+                      title="Show model-level controls"
                     >
-                      <AlertCircle className="w-3 h-3" />
-                      Retry
+                      {isExpanded ? "Hide Models" : "Models"}
                     </button>
-                  )}
+                  </div>
                 </div>
+
+                {isExpanded && (
+                  <div className="px-3 pb-3">
+                    <div className="rounded-lg border border-gray-800 bg-gray-950/50 overflow-hidden">
+                      <div className="px-2 py-1.5 text-[11px] text-gray-500 border-b border-gray-800">
+                        Download / load models individually
+                      </div>
+                      <div className="max-h-44 overflow-auto">
+                        {models.length === 0 && (
+                          <div className="px-2 py-2 text-xs text-gray-600">No model metadata available</div>
+                        )}
+                        {[...models]
+                          .sort((a, b) => (b.r2 ?? -1) - (a.r2 ?? -1))
+                          .map((m) => {
+                            const key = `${v.id}:${m.name}`;
+                            const downloading = m.status === "downloading" || modelBusy === key;
+                            const loaded = m.loaded;
+                            const onDisk = m.on_disk;
+                            const canDownload = m.has_file;
+                            return (
+                              <div key={m.name} className="flex items-center justify-between px-2 py-1.5 border-b border-gray-900 last:border-b-0">
+                                <div className="min-w-0 pr-2">
+                                  <div className="text-xs text-gray-200 truncate">{m.display_name}</div>
+                                  <div className="text-[11px] text-gray-500 truncate">
+                                    {m.family}
+                                    {m.r2 != null ? ` • R2 ${m.r2.toFixed(3)}` : ""}
+                                    {loaded ? " • loaded" : onDisk ? " • on disk" : ""}
+                                  </div>
+                                </div>
+                                <div className="flex items-center gap-1">
+                                  {loaded && <span className="text-[11px] text-green-400">ready</span>}
+                                  {!loaded && canDownload && !downloading && (
+                                    <button
+                                      onClick={() => handleLoadModel(v.id, m.name)}
+                                      className="px-2 py-0.5 rounded text-[11px] font-medium bg-blue-700 hover:bg-blue-600 text-white"
+                                    >
+                                      {onDisk ? "Load" : "Download"}
+                                    </button>
+                                  )}
+                                  {downloading && <RefreshCw className="w-3 h-3 text-yellow-400 animate-spin" />}
+                                  {!canDownload && <span className="text-[11px] text-gray-500">virtual</span>}
+                                </div>
+                              </div>
+                            );
+                          })}
+                      </div>
+                    </div>
+                  </div>
+                )}
               </div>
             );
           })}

scripts/download_models.py

@@ -20,6 +20,7 @@ Local layout after download  (local_dir = ARTIFACTS_DIR):
 
 import os
 import sys
+import json
 from pathlib import Path
 
 # ──────────────────────────────────────────────────────────────────────────────
@@ -34,6 +35,7 @@ HF_TOKEN  = os.getenv("HF_TOKEN", "")
 # HF repo stores v1/ and v2/ at root → local_dir=ARTIFACTS_DIR maps them to
 #   artifacts/v1/...  and  artifacts/v2/...
 ARTIFACTS_DIR = Path(__file__).resolve().parent.parent / "artifacts"
+DEFAULT_STARTUP_TOP_MODELS = 3
 
 # Sentinel file — written after a successful full download
 SENTINEL = ARTIFACTS_DIR / ".hf_downloaded"
@@ -101,6 +103,110 @@ def download_version(version: str) -> None:
     print(f"[download_models] {version}/ ready")
 
 
+def _read_models_meta(version: str) -> dict:
+    meta_path = ARTIFACTS_DIR / version / "models.json"
+    if not meta_path.exists():
+        return {}
+    try:
+        return json.loads(meta_path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _model_score(info: dict) -> float:
+    """Return a comparable score for a model metadata record.
+
+    Priority:
+      1) R2 (higher is better)
+      2) f1_weighted / f1_macro (higher is better)
+      3) within_5pct (higher is better)
+      4) mae (lower is better; converted to negative contribution)
+    """
+    if not isinstance(info, dict):
+        return float("-inf")
+
+    r2 = info.get("r2")
+    if isinstance(r2, (int, float)):
+        return float(r2)
+
+    # Fallback when r2 is unavailable.
+    f1w = info.get("f1_weighted")
+    if isinstance(f1w, (int, float)):
+        return float(f1w)
+
+    f1m = info.get("f1_macro")
+    if isinstance(f1m, (int, float)):
+        return float(f1m)
+
+    w5 = info.get("within_5pct")
+    if isinstance(w5, (int, float)):
+        return float(w5) / 100.0
+
+    mae = info.get("mae")
+    if isinstance(mae, (int, float)):
+        return -float(mae)
+
+    return float("-inf")
+
+
+def select_top_models(version: str, top_k: int = DEFAULT_STARTUP_TOP_MODELS) -> list[str]:
+    """Pick top-k concrete models from models.json by best available metric score.
+
+    Excludes virtual entries without a model file.
+    """
+    meta = _read_models_meta(version)
+    models = meta.get("models", {}) if isinstance(meta, dict) else {}
+    scored: list[tuple[float, str]] = []
+    for name, info in models.items():
+        if not isinstance(info, dict):
+            continue
+        if not info.get("file"):
+            continue
+        score = _model_score(info)
+        if score != float("-inf"):
+            scored.append((score, name))
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return [name for _, name in scored[:top_k]]
+
+
+def _collect_model_patterns(version: str, model_names: list[str]) -> list[str]:
+    """Build allow_patterns for model files + required shared artifacts."""
+    meta = _read_models_meta(version)
+    models = meta.get("models", {}) if isinstance(meta, dict) else {}
+    patterns = {
+        f"{version}/models.json",
+        f"{version}/features/train_split.csv",
+        f"{version}/scalers/features_standard.joblib",
+        f"{version}/scalers/sequence_scaler.joblib",
+        f"{version}/scalers/features_minmax.joblib",
+    }
+    for model_name in model_names:
+        info = models.get(model_name, {})
+        rel_file = info.get("file") if isinstance(info, dict) else None
+        if rel_file:
+            patterns.add(f"{version}/{rel_file}")
+    return sorted(patterns)
+
+
+def download_models(version: str, model_names: list[str]) -> None:
+    """Download selected model artifacts for one version."""
+    _ensure_hub()
+    from huggingface_hub import snapshot_download
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+    allow = _collect_model_patterns(version, model_names)
+    print(f"[download_models] Downloading selected models for {version}: {model_names}")
+    snapshot_download(**_hf_kwargs(
+        allow_patterns=allow,
+        ignore_patterns=["*.log"],
+    ))
+    print(f"[download_models] Selected model artifacts ready for {version}")
+
+
+def download_model(version: str, model_name: str) -> None:
+    """Download one model artifact (plus required metadata/scalers)."""
+    download_models(version, [model_name])
+
+
 def download_models_meta_only(versions: list[str]) -> None:
     """Download only models.json for listed versions."""
     _ensure_hub()
@@ -131,8 +237,15 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("--version", default=None,
                         help="Download only this version, e.g. v1 or v2")
+    parser.add_argument("--model", default=None,
+                        help="Download only this model key inside --version")
     args = parser.parse_args()
 
+    if args.version and args.model:
+        download_models_meta_only([args.version])
+        download_model(args.version, args.model)
+        return
+
     if args.version:
         if version_loaded(args.version):
             print(f"[download_models] {args.version} already present — skipping")
@@ -144,12 +257,18 @@ def main() -> None:
     # latest (v3) heavy model artifacts at startup.
     download_models_meta_only(["v1", "v2", "v3"])
 
-    # Then fetch v3 artifacts if key models are missing.
-    if already_downloaded("v3"):
-        print("[download_models] v3 artifacts already present — skipping download")
+    # Then fetch only top-N (default=3) v3 model artifacts by best score.
+    top_models = select_top_models("v3")
+    if not top_models:
+        print("[download_models] Could not resolve top models from models.json, falling back to full v3 download")
+        if already_downloaded("v3"):
+            print("[download_models] v3 artifacts already present — skipping download")
+            return
+        download_version("v3")
         return
 
-    download_version("v3")
+    print(f"[download_models] Default startup model set (v3 top-{DEFAULT_STARTUP_TOP_MODELS}): {top_models}")
+    download_models("v3", top_models)
 
 
 if __name__ == "__main__":