feat: HF model repo at v1/v2 root; version selector UI with download submenu; artifacts/ out of git

.gitignore

@@ -1,23 +1,8 @@
 # ─────────────────────────────────────────────────────────────────────────────
-# Binary artifacts — figures, notebooks, numpy arrays (too large / not needed)
+# Entire artifacts/ lives on HF Hub model repo (NeerajCodz/aiBatteryLifeCycle)
+# Downloaded at Docker startup via scripts/download_models.py
 # ─────────────────────────────────────────────────────────────────────────────
-artifacts/v1/figures/
-artifacts/v2/figures/
-artifacts/v2/reports/
-artifacts/v2/results/*.npz
-artifacts/v2/results/*.png
-notebooks/
-# ─────────────────────────────────────────────────────────────────────────────
-# Model artifacts — stored on HF Hub, NOT in git
-# Download via: python scripts/download_models.py
-# or automatically on Docker startup
-# ─────────────────────────────────────────────────────────────────────────────
-artifacts/v1/models/
-artifacts/v2/models/
-artifacts/v1/scalers/
-artifacts/v2/scalers/
-# Sentinel written by download_models.py
-artifacts/.hf_downloaded
+artifacts/
 
 # Python
 __pycache__/

Dockerfile

@@ -43,12 +43,11 @@ RUN mkdir -p artifacts/v1/models/classical artifacts/v1/models/deep \
              artifacts/v2/scalers artifacts/v2/results artifacts/v2/reports \
              artifacts/logs
 
-# Copy project source
+# Copy project source (artifacts/ is NOT in git — downloaded at runtime)
 COPY src/ src/
 COPY api/ api/
 COPY scripts/ scripts/
 COPY cleaned_dataset/ cleaned_dataset/
-COPY artifacts/ artifacts/
 
 # Copy built frontend
 COPY --from=frontend-build /app/frontend/dist frontend/dist

api/main.py

@@ -42,10 +42,11 @@ Docker
 
 from __future__ import annotations
 
+import asyncio
 from contextlib import asynccontextmanager
 from pathlib import Path
 
-from fastapi import FastAPI
+from fastapi import BackgroundTasks, FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
@@ -110,6 +111,68 @@ async def health():
     )
 
 
+# ── Version management ───────────────────────────────────────────────────────
+_REGISTRIES = {"v1": registry_v1, "v2": registry_v2}
+_version_status: dict[str, str] = {}   # "downloading" | "ready" | "error"
+
+
+def _artifacts_dir() -> Path:
+    return Path(__file__).resolve().parent.parent / "artifacts"
+
+
+def _version_loaded(version: str) -> bool:
+    base = _artifacts_dir() / version / "models" / "classical"
+    return any(base.glob("*.joblib")) if base.exists() else False
+
+
+@app.get("/api/versions", tags=["meta"])
+async def list_versions():
+    """Return all known versions with loaded / downloading status."""
+    return [
+        {
+            "id": v,
+            "display": f"Version {v[1]}",
+            "loaded": _version_loaded(v),
+            "model_count": _REGISTRIES[v].model_count,
+            "status": _version_status.get(v, "ready" if _version_loaded(v) else "not_downloaded"),
+        }
+        for v in ["v2", "v1"]
+    ]
+
+
+async def _bg_load_version(version: str) -> None:
+    import subprocess, sys as _sys
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            _sys.executable, "scripts/download_models.py", "--version", version,
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT,
+        )
+        await proc.wait()
+        if proc.returncode == 0:
+            _REGISTRIES[version].load_all()
+            _version_status[version] = "ready"
+            log.info("Version %s loaded on demand — %d models", version,
+                     _REGISTRIES[version].model_count)
+        else:
+            _version_status[version] = "error"
+            log.error("download_models.py failed for version %s", version)
+    except Exception as exc:
+        _version_status[version] = "error"
+        log.error("Failed to load version %s: %s", version, 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)."""
+    if version not in _REGISTRIES:
+        raise HTTPException(status_code=400, detail=f"Unknown version '{version}'")
+    if _version_status.get(version) == "downloading":
+        return {"status": "downloading", "version": version}
+    _version_status[version] = "downloading"
+    background_tasks.add_task(_bg_load_version, version)
+    return {"status": "downloading", "version": version}
+
+
 # ── Include routers ──────────────────────────────────────────────────────────
 from api.routers.predict import router as predict_router, v1_router
 from api.routers.predict_v2 import router as predict_v2_router

artifacts/v1/results/classical_rul_results.csv

@@ -1,4 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_5cyc
-RandomForest,8.942333980582523,137.23446964660195,11.714711675777682,-0.15748641443851108,120.88277153106779,0.4058252427184466
-XGBoost,6.7578043937683105,74.80780029296875,8.649150264214905,0.3690432906150818,90.60895087232073,0.429126213592233
-LightGBM,9.174716686966466,125.80377799208308,11.216228331845027,-0.06107572161612751,112.25501529299473,0.35145631067961164

artifacts/v1/results/classical_soh_results.csv

@@ -1,11 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.807727531282236,0.29514563106796116
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.24854368932038834
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.22330097087378642
-SVR,7.562130215902278,187.88576938734298,13.707143006014892,0.805143828272144,97.82839183781172,0.32233009708737864
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.26019417475728157
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713165,0.2407766990291262
-ElasticNet,15.796038594619795,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.06407766990291262
-Lasso,15.830927911593506,462.77574982037044,21.512223265398916,0.5200556632227833,145.46522399976544,0.05242718446601942
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.05048543689320388

artifacts/v1/results/dg_itransformer_results.json

@@ -1,9 +0,0 @@
-{
-  "MAE": 12.886456320718098,
-  "MSE": 323.38418900793243,
-  "RMSE": 17.982886003306934,
-  "R2": 0.12310012848141882,
-  "MAPE": 69.98234771512423,
-  "tol_2pct": 0.04827586206896552,
-  "tol_5pct": 0.2896551724137931
-}

artifacts/v1/results/ensemble_results.csv

@@ -1,9 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tol_2pct
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,0.3482758620689655
-tft,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,0.21379310344827587
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.7482515597481125,0.8372059046352616,10.924057540803656,0.12413793103448276
-vae_lstm,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,0.09310344827586207
-batterygpt,8.020673063309337,129.06954589210812,11.360877866261397,0.6500105074494692,12.874349389916773,0.28620689655172415
-vanilla_lstm,10.561354979478219,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.15862068965517243
-bidirectional_lstm,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.10689655172413794
-attention_lstm,14.181327172488002,288.23989200564256,16.977629163273726,0.21839863277892768,24.827876450140888,0.15862068965517243

artifacts/v1/results/final_rankings.csv

@@ -1,23 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct,tol_2pct,tol_5pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.80772753128224,0.2951456310679611,,
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.2485436893203883,,
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,,0.3482758620689655,
-TFT,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,,0.2137931034482758,
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.2233009708737864,,
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.748251559748112,0.8372059046352616,10.924057540803656,,0.1241379310344827,
-SVR,7.562130215902278,187.88576938734295,13.707143006014892,0.805143828272144,97.82839183781172,0.3223300970873786,,
-VAE-LSTM,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,,0.09310344827586207,
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.2601941747572815,,
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058,,
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713164,0.2407766990291262,,
-BatteryGPT,8.020673063309337,129.06954589210812,11.360877866261395,0.6500105074494692,12.874349389916771,,0.2862068965517241,
-GRU,9.275809104339835,134.65458890701777,11.604076391812397,0.6348659095727935,15.248492181524448,0.193103448275862,,
-Vanilla LSTM,10.56135497947822,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.1586206896551724,,
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.1068965517241379,,
-ElasticNet,15.796038594619796,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.0640776699029126,,
-Lasso,15.830927911593506,462.7757498203704,21.51222326539892,0.5200556632227833,145.46522399976544,0.0524271844660194,,
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.0504854368932038,,
-iTransformer,14.544141949115827,275.09890344946007,16.58610573490535,0.2540321967199925,73.33406651321724,,0.0172413793103448,
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.2183986327789276,24.827876450140888,0.1586206896551724,,
-DG-iTransformer,14.183794754173379,313.5635374005159,17.707725359303375,0.1497301506825386,94.26231665878274,,0.1103448275862069,0.2
-Physics iTransformer,16.41156271618159,379.65023683665015,19.48461538847124,-0.0294728537142276,97.60205959509742,,0.0,

artifacts/v1/results/lstm_soh_results.csv

@@ -1,5 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct
-GRU,9.275809104339837,134.65458890701777,11.604076391812395,0.6348659095727935,15.248492181524448,0.19310344827586207
-Vanilla LSTM,10.561354979478219,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.15862068965517243
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.10689655172413794
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.21839863277892768,24.827876450140888,0.15862068965517243

artifacts/v1/results/transformer_soh_results.csv

@@ -1,5 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tol_2pct
-TFT,9.538144323660262,127.31655440584875,11.283463759229644,0.6547639804432781,18.98017853690174,0.05517241379310345
-BatteryGPT,9.614953606189902,135.34729964687295,11.633885836076997,0.6329875309153767,15.44417472623618,0.1793103448275862
-iTransformer,9.356759048993766,150.35062176683638,12.261754432659153,0.5923039981808029,14.4907916127095,0.1310344827586207
-Physics iTransformer,12.1375468649355,214.65431642999653,14.651085844741901,0.4179358518552816,24.985288391381786,0.07931034482758621

artifacts/v1/results/unified_results.csv

@@ -1,23 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct,tol_2pct,tol_5pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.80772753128224,0.2951456310679611,,
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.2485436893203883,,
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,,0.3482758620689655,
-TFT,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,,0.2137931034482758,
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.2233009708737864,,
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.748251559748112,0.8372059046352616,10.924057540803656,,0.1241379310344827,
-SVR,7.562130215902278,187.88576938734295,13.707143006014892,0.805143828272144,97.82839183781172,0.3223300970873786,,
-VAE-LSTM,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,,0.09310344827586207,
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.2601941747572815,,
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058,,
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713164,0.2407766990291262,,
-BatteryGPT,8.020673063309337,129.06954589210812,11.360877866261395,0.6500105074494692,12.874349389916771,,0.2862068965517241,
-GRU,9.275809104339835,134.65458890701777,11.604076391812397,0.6348659095727935,15.248492181524448,0.193103448275862,,
-Vanilla LSTM,10.56135497947822,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.1586206896551724,,
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.1068965517241379,,
-ElasticNet,15.796038594619796,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.0640776699029126,,
-Lasso,15.830927911593506,462.7757498203704,21.51222326539892,0.5200556632227833,145.46522399976544,0.0524271844660194,,
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.0504854368932038,,
-iTransformer,14.544141949115827,275.09890344946007,16.58610573490535,0.2540321967199925,73.33406651321724,,0.0172413793103448,
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.2183986327789276,24.827876450140888,0.1586206896551724,,
-DG-iTransformer,14.183794754173379,313.5635374005159,17.707725359303375,0.1497301506825386,94.26231665878274,,0.1103448275862069,0.2
-Physics iTransformer,16.41156271618159,379.65023683665015,19.48461538847124,-0.0294728537142276,97.60205959509742,,0.0,

artifacts/v1/results/vae_lstm_results.json

@@ -1,8 +0,0 @@
-{
-  "MAE": 8.494939970437716,
-  "MSE": 100.78674732190278,
-  "RMSE": 10.039260297546965,
-  "R2": 0.7267031327397879,
-  "MAPE": 14.250142040133243,
-  "tol_2pct": 0.09310344827586207
-}

artifacts/v2/results/classical_rul_results.csv

@@ -1,4 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_5cyc
-RandomForest,8.942333980582523,137.23446964660195,11.714711675777682,-0.15748641443851108,120.88277153106779,0.4058252427184466
-XGBoost,6.7578043937683105,74.80780029296875,8.649150264214905,0.3690432906150818,90.60895087232073,0.429126213592233
-LightGBM,9.174716686966466,125.80377799208308,11.216228331845027,-0.06107572161612751,112.25501529299473,0.35145631067961164

artifacts/v2/results/classical_soh_results.csv

@@ -1,11 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.807727531282236,0.29514563106796116
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.24854368932038834
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.22330097087378642
-SVR,7.562130215902278,187.88576938734298,13.707143006014892,0.805143828272144,97.82839183781172,0.32233009708737864
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.26019417475728157
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713165,0.2407766990291262
-ElasticNet,15.796038594619795,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.06407766990291262
-Lasso,15.830927911593506,462.77574982037044,21.512223265398916,0.5200556632227833,145.46522399976544,0.05242718446601942
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.05048543689320388

artifacts/v2/results/dg_itransformer_results.json

@@ -1,9 +0,0 @@
-{
-  "MAE": 12.886456320718098,
-  "MSE": 323.38418900793243,
-  "RMSE": 17.982886003306934,
-  "R2": 0.12310012848141882,
-  "MAPE": 69.98234771512423,
-  "tol_2pct": 0.04827586206896552,
-  "tol_5pct": 0.2896551724137931
-}

artifacts/v2/results/ensemble_results.csv

@@ -1,9 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tol_2pct
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,0.3482758620689655
-tft,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,0.21379310344827587
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.7482515597481125,0.8372059046352616,10.924057540803656,0.12413793103448276
-vae_lstm,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,0.09310344827586207
-batterygpt,8.020673063309337,129.06954589210812,11.360877866261397,0.6500105074494692,12.874349389916773,0.28620689655172415
-vanilla_lstm,10.561354979478219,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.15862068965517243
-bidirectional_lstm,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.10689655172413794
-attention_lstm,14.181327172488002,288.23989200564256,16.977629163273726,0.21839863277892768,24.827876450140888,0.15862068965517243

artifacts/v2/results/final_rankings.csv

@@ -1,23 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct,tol_2pct,tol_5pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.80772753128224,0.2951456310679611,,
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.2485436893203883,,
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,,0.3482758620689655,
-TFT,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,,0.2137931034482758,
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.2233009708737864,,
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.748251559748112,0.8372059046352616,10.924057540803656,,0.1241379310344827,
-SVR,7.562130215902278,187.88576938734295,13.707143006014892,0.805143828272144,97.82839183781172,0.3223300970873786,,
-VAE-LSTM,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,,0.09310344827586207,
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.2601941747572815,,
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058,,
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713164,0.2407766990291262,,
-BatteryGPT,8.020673063309337,129.06954589210812,11.360877866261395,0.6500105074494692,12.874349389916771,,0.2862068965517241,
-GRU,9.275809104339835,134.65458890701777,11.604076391812397,0.6348659095727935,15.248492181524448,0.193103448275862,,
-Vanilla LSTM,10.56135497947822,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.1586206896551724,,
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.1068965517241379,,
-ElasticNet,15.796038594619796,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.0640776699029126,,
-Lasso,15.830927911593506,462.7757498203704,21.51222326539892,0.5200556632227833,145.46522399976544,0.0524271844660194,,
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.0504854368932038,,
-iTransformer,14.544141949115827,275.09890344946007,16.58610573490535,0.2540321967199925,73.33406651321724,,0.0172413793103448,
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.2183986327789276,24.827876450140888,0.1586206896551724,,
-DG-iTransformer,14.183794754173379,313.5635374005159,17.707725359303375,0.1497301506825386,94.26231665878274,,0.1103448275862069,0.2
-Physics iTransformer,16.41156271618159,379.65023683665015,19.48461538847124,-0.0294728537142276,97.60205959509742,,0.0,

artifacts/v2/results/lstm_soh_results.csv

@@ -1,5 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct
-GRU,9.275809104339837,134.65458890701777,11.604076391812395,0.6348659095727935,15.248492181524448,0.19310344827586207
-Vanilla LSTM,10.561354979478219,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.15862068965517243
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.10689655172413794
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.21839863277892768,24.827876450140888,0.15862068965517243

artifacts/v2/results/transformer_soh_results.csv

@@ -1,5 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tol_2pct
-TFT,9.538144323660262,127.31655440584875,11.283463759229644,0.6547639804432781,18.98017853690174,0.05517241379310345
-BatteryGPT,9.614953606189902,135.34729964687295,11.633885836076997,0.6329875309153767,15.44417472623618,0.1793103448275862
-iTransformer,9.356759048993766,150.35062176683638,12.261754432659153,0.5923039981808029,14.4907916127095,0.1310344827586207
-Physics iTransformer,12.1375468649355,214.65431642999653,14.651085844741901,0.4179358518552816,24.985288391381786,0.07931034482758621

artifacts/v2/results/unified_results.csv

@@ -1,23 +0,0 @@
-model,MAE,MSE,RMSE,R2,MAPE,tolerance_acc_2pct,tol_2pct,tol_5pct
-RandomForest,4.78051739475878,41.771168089034525,6.463061819991708,0.956679157080545,28.80772753128224,0.2951456310679611,,
-LightGBM,6.909989455704782,89.23030742727897,9.446179514876846,0.9074593240133356,56.94413475231037,0.2485436893203883,,
-Weighted Avg Ensemble,3.737822790616429,37.739016006374186,6.1432089339671805,0.8976655649469139,5.478476687258817,,0.3482758620689655,
-TFT,4.732738753085752,46.68825874782447,6.832880706394959,0.8733984854887593,7.499287950788588,,0.2137931034482758,
-XGBoost,8.506303251021016,136.22476526016746,11.67153654238239,0.8587214117403497,72.81562821369698,0.2233009708737864,,
-Stacking Ensemble,5.76908337148985,60.03540223313905,7.748251559748112,0.8372059046352616,10.924057540803656,,0.1241379310344827,
-SVR,7.562130215902278,187.88576938734295,13.707143006014892,0.805143828272144,97.82839183781172,0.3223300970873786,,
-VAE-LSTM,8.494939970437716,100.78674732190278,10.039260297546965,0.7267031327397879,14.250142040133243,,0.09310344827586207,
-KNN-10,11.665738368704334,265.7682207905257,16.302399234177948,0.7243720041223407,89.92209971367193,0.2601941747572815,,
-KNN-5,11.751580021863887,270.3768092061512,16.44313866651228,0.7195924409938166,88.41470284019084,0.2757281553398058,,
-KNN-20,12.035078655061884,272.741740151536,16.514894494108525,0.71713977312056,101.98653839713164,0.2407766990291262,,
-BatteryGPT,8.020673063309337,129.06954589210812,11.360877866261395,0.6500105074494692,12.874349389916771,,0.2862068965517241,
-GRU,9.275809104339835,134.65458890701777,11.604076391812397,0.6348659095727935,15.248492181524448,0.193103448275862,,
-Vanilla LSTM,10.56135497947822,155.95773910638056,12.488304092485118,0.5770995427937917,14.375050332959946,0.1586206896551724,,
-Bidirectional LSTM,11.134867385317946,167.3343794115467,12.935779041540046,0.5462502472468515,17.124593156141298,0.1068965517241379,,
-ElasticNet,15.796038594619796,460.3763913475375,21.45638346384445,0.5225440358554927,144.4728811908027,0.0640776699029126,,
-Lasso,15.830927911593506,462.7757498203704,21.51222326539892,0.5200556632227833,145.46522399976544,0.0524271844660194,,
-Ridge,15.860549029501184,464.1921925903698,21.545119925179574,0.5185866716299998,145.65718178268125,0.0504854368932038,,
-iTransformer,14.544141949115827,275.09890344946007,16.58610573490535,0.2540321967199925,73.33406651321724,,0.0172413793103448,
-Attention LSTM,14.181327172488002,288.23989200564256,16.977629163273726,0.2183986327789276,24.827876450140888,0.1586206896551724,,
-DG-iTransformer,14.183794754173379,313.5635374005159,17.707725359303375,0.1497301506825386,94.26231665878274,,0.1103448275862069,0.2
-Physics iTransformer,16.41156271618159,379.65023683665015,19.48461538847124,-0.0294728537142276,97.60205959509742,,0.0,

artifacts/v2/results/v2_classical_results.csv

@@ -1,9 +0,0 @@
-model,r2,mae,within_5pct
-extra_trees,0.9545111863206289,1.325439106747622,99.27007299270073
-svr,0.9749418151896808,0.8447528977381709,99.27007299270073
-ridge,0.96260007301777,1.238689808585007,99.27007299270073
-xgboost,0.9701536078007467,1.276102318230126,98.72262773722628
-gradient_boosting,0.9427669688063848,1.4114545626753392,98.54014598540147
-knn_k5,0.9303819293635062,1.7036079148305412,97.62773722627736
-random_forest,0.9518568236961867,1.6867479514298702,96.71532846715328
-lightgbm,0.9560384659829149,1.5661312778770975,95.98540145985402

artifacts/v2/results/v2_intra_battery.json

@@ -1,9 +0,0 @@
-{
-  "target": "within_5pct >= 95",
-  "passed_models": 8,
-  "total_models": 8,
-  "best_model": "extra_trees",
-  "best_within_5pct": 99.27007299270073,
-  "best_r2": 0.9545111863206289,
-  "notes": "XGBoost\u2192LGB+GB Ensemble, Ridge\u2192ExtraTrees-Scaled, KNN\u2192SVR Ensemble"
-}

artifacts/v2/results/v2_model_validation.csv

@@ -1,17 +0,0 @@
-model,mae,rmse,r2,within_2pct,within_5pct,passed_95
-random_forest,0.9087291273437881,1.969167860523798,0.9768094711831841,83.75912408759125,95.07299270072993,True
-svr,1.6349861755580366,3.4846680412456976,0.9273780344781068,82.48175182481752,88.86861313868614,False
-xgboost,1.0395094776911078,2.3264169017858896,0.9676316722415876,82.2992700729927,88.86861313868614,False
-lightgbm,1.5073643559068495,2.9029505644051135,0.9496007058102836,81.02189781021897,88.13868613138686,False
-knn_k20,2.486675866923982,6.500672824933502,0.7472670935266853,84.12408759124088,85.21897810218978,False
-knn_k10,2.537245189395581,6.643166546082999,0.7360659298020076,84.48905109489051,84.67153284671532,False
-knn_k5,2.5366661790854557,6.661080117527008,0.734640592527769,84.48905109489051,84.67153284671532,False
-lasso,6.338197702892737,7.855862262540625,0.63090947633286,13.321167883211679,49.63503649635037,False
-ridge,6.354219600702956,7.877916808246509,0.6288341980649439,13.138686131386862,49.63503649635037,False
-elasticnet,6.359292593403684,7.8720819252103045,0.6293838121478381,13.503649635036496,49.27007299270073,False
-physics_itransformer,11.942222882334457,19.560215899810355,-1.288191997636034,15.875912408759124,44.70802919708029,False
-itransformer,18.775672188288702,24.807532802455988,-2.680546617377897,10.948905109489052,25.18248175182482,False
-dynamic_graph_itransformer,14.5743662824896,18.019296255058386,-0.9418730093540923,6.204379562043796,17.335766423357665,False
-extra_trees,21.583514681220528,25.105434141924782,-2.769473079864784,5.839416058394161,9.48905109489051,False
-gradient_boosting,29.48091148539111,32.124687008446905,-5.1719583162447185,0.0,0.18248175182481752,False
-best_rul_model,61.6389790255578,62.979116792145476,-22.721290167829615,0.0,0.0,False

artifacts/v2/results/v2_training_summary.json

@@ -1,14 +0,0 @@
-{
-  "version": "v2.0",
-  "timestamp": "2026-02-25T18:16:44.705048",
-  "total_models": 12,
-  "passed_models": 5,
-  "pass_rate_pct": 41.66666666666667,
-  "best_model": "extra_trees",
-  "best_within_5pct": 99.27007299270073,
-  "best_r2": 0.9545111863206289,
-  "mean_within_5pct": 77.38746958637469,
-  "train_samples": 2130,
-  "test_samples": 548,
-  "batteries": 30
-}

artifacts/v2/results/v2_validation_summary.json

@@ -1,11 +0,0 @@
-{
-  "timestamp": "2026-02-25T16:31:44.904601",
-  "test_samples": 548,
-  "test_batteries": 30,
-  "total_models_tested": 16,
-  "models_passed_95pct": 1,
-  "overall_pass_rate_pct": 6.25,
-  "best_model": "random_forest",
-  "best_within_5pct": 95.07299270072993,
-  "mean_within_5pct": 53.809306569343065
-}

artifacts/v2/results/vae_lstm_results.json

@@ -1,8 +0,0 @@
-{
-  "MAE": 8.494939970437716,
-  "MSE": 100.78674732190278,
-  "RMSE": 10.039260297546965,
-  "R2": 0.7267031327397879,
-  "MAPE": 14.250142040133243,
-  "tol_2pct": 0.09310344827586207
-}

frontend/src/App.tsx

@@ -5,6 +5,7 @@ import GraphPanel from "./components/GraphPanel";
 import RecommendationPanel from "./components/RecommendationPanel";
 import MetricsPanel from "./components/MetricsPanel";
 import ResearchPaper from "./components/ResearchPaper";
+import VersionSelector from "./components/VersionSelector";
 import { ToastProvider } from "./components/Toast";
 import { getApiVersion, setApiVersion } from "./api";
 import { BatteryCharging } from "lucide-react";
@@ -42,24 +43,11 @@ export default function App() {
             <h1 className="text-lg font-bold">AI Battery Lifecycle Predictor</h1>
           </div>
           <div className="flex items-center gap-4">
-            {/* Version toggle */}
-            <div className="flex items-center gap-2 bg-gray-800 rounded-lg p-1">
-              {(["v1", "v2"] as const).map((v) => (
-                <button
-                  key={v}
-                  onClick={() => handleVersionChange(v)}
-                  className={`px-3 py-1 rounded text-xs font-bold transition-colors ${
-                    apiVersion === v
-                      ? v === "v2"
-                        ? "bg-green-600 text-white"
-                        : "bg-blue-600 text-white"
-                      : "text-gray-400 hover:text-white"
-                  }`}
-                >
-                  {v.toUpperCase()}
-                </button>
-              ))}
-            </div>
+            {/* Version selector with submenu */}
+            <VersionSelector
+              activeVersion={apiVersion}
+              onSwitch={handleVersionChange}
+            />
             <nav className="flex gap-1">
             {tabs.map((t) => (
               <button

frontend/src/api.ts

@@ -66,6 +66,21 @@ export interface ModelVersionGroups {
   default_model: string | null;
 }
 
+// ── Version management ───────────────────────────────────────────────────────
+export interface VersionInfo {
+  id: string;            // "v1" | "v2"
+  display: string;       // "Version 1" | "Version 2"
+  loaded: boolean;
+  model_count: number;
+  status: "ready" | "not_downloaded" | "downloading" | "error";
+}
+
+export const fetchVersions = () =>
+  baseApi.get<VersionInfo[]>("/versions").then((r) => r.data);
+
+export const loadVersion = (version: string) =>
+  baseApi.post<{ status: string; version: string }>(`/versions/${version}/load`).then((r) => r.data);
+
 export interface BatteryVizData {
   battery_id: string;
   soh_pct: number;

frontend/src/components/VersionSelector.tsx

@@ -0,0 +1,220 @@
+/**
+ * VersionSelector
+ *
+ * Shows the active API version badge ("Version 2") with a chevron icon.
+ * Clicking opens a submenu listing all available versions:
+ *   - Active version: shown with a check mark
+ *   - Downloaded but inactive: "Switch" button
+ *   - Not yet downloaded: Download icon button → triggers server-side download
+ *     then auto-switches when ready
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  ChevronRight, Download, Check, RefreshCw, AlertCircle, Layers,
+} from "lucide-react";
+import { fetchVersions, loadVersion, VersionInfo } from "../api";
+
+interface Props {
+  activeVersion: "v1" | "v2";
+  onSwitch: (v: "v1" | "v2") => void;
+}
+
+export default function VersionSelector({ activeVersion, onSwitch }: Props) {
+  const [open, setOpen] = useState(false);
+  const [versions, setVersions] = useState<VersionInfo[]>([]);
+  const [busy, setBusy] = useState<string | null>(null);   // version being downloaded
+  const menuRef = useRef<HTMLDivElement>(null);
+  const pollRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+  // ── Load version list ────────────────────────────────────────────────────
+  const refresh = useCallback(() => {
+    fetchVersions()
+      .then(setVersions)
+      .catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  // ── Poll while a download is in progress ────────────────────────────────
+  useEffect(() => {
+    const hasDownloading = versions.some((v) => v.status === "downloading");
+    if (hasDownloading && !pollRef.current) {
+      pollRef.current = setInterval(refresh, 2500);
+    }
+    if (!hasDownloading && pollRef.current) {
+      clearInterval(pollRef.current);
+      pollRef.current = null;
+      setBusy(null);
+    }
+    return () => {
+      if (pollRef.current) clearInterval(pollRef.current);
+    };
+  }, [versions, refresh]);
+
+  // ── Close on outside click ───────────────────────────────────────────────
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: MouseEvent) => {
+      if (menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [open]);
+
+  // ── Actions ──────────────────────────────────────────────────────────────
+  const handleDownload = async (version: string) => {
+    setBusy(version);
+    try {
+      await loadVersion(version);
+      refresh();                       // poll will take over
+    } catch {
+      setBusy(null);
+    }
+  };
+
+  const handleSwitch = (version: string) => {
+    onSwitch(version as "v1" | "v2");
+    setOpen(false);
+  };
+
+  const activeDisplay = versions.find((v) => v.id === activeVersion)?.display
+    ?? `Version ${activeVersion[1]}`;
+
+  // Versions that are NOT the active one
+  const others = versions.filter((v) => v.id !== activeVersion);
+
+  return (
+    <div className="relative" ref={menuRef}>
+      {/* Badge button */}
+      <button
+        onClick={() => setOpen((o) => !o)}
+        className={`flex items-center gap-1.5 px-3 py-1.5 rounded-lg text-xs font-bold
+          transition-colors select-none
+          ${activeVersion === "v2"
+            ? "bg-green-600 text-white hover:bg-green-500"
+            : "bg-blue-600 text-white hover:bg-blue-500"}`}
+        title="Switch model version"
+      >
+        <Layers className="w-3.5 h-3.5 opacity-80" />
+        {activeDisplay}
+        <ChevronRight
+          className={`w-3.5 h-3.5 transition-transform duration-200
+            ${open ? "rotate-90" : ""}`}
+        />
+      </button>
+
+      {/* Dropdown */}
+      {open && (
+        <div
+          className="absolute right-0 top-full mt-2 w-56
+            bg-gray-900 border border-gray-700 rounded-xl shadow-2xl z-50
+            overflow-hidden"
+        >
+          {/* Header */}
+          <div className="px-3 py-2 border-b border-gray-700 text-xs text-gray-400 font-medium">
+            Model Versions
+          </div>
+
+          {/* Active version row */}
+          <div className="flex items-center justify-between px-3 py-2.5 bg-gray-800/50">
+            <div>
+              <span className="text-sm font-semibold text-white">{activeDisplay}</span>
+              <span className="ml-2 text-xs text-green-400">active</span>
+            </div>
+            <Check className="w-4 h-4 text-green-400 shrink-0" />
+          </div>
+
+          {/* Other versions */}
+          {others.length === 0 && (
+            <div className="px-3 py-3 text-xs text-gray-500 text-center">
+              No other versions available
+            </div>
+          )}
+          {others.map((v) => {
+            const isDownloading = v.status === "downloading" || busy === v.id;
+            const isError = v.status === "error";
+            const canSwitch = v.loaded && !isDownloading;
+
+            return (
+              <div
+                key={v.id}
+                className="flex items-center justify-between px-3 py-2.5
+                  hover:bg-gray-800/60 transition-colors"
+              >
+                <div>
+                  <span className="text-sm font-medium text-gray-200">{v.display}</span>
+                  {v.loaded && v.model_count > 0 && (
+                    <span className="ml-2 text-xs text-gray-500">
+                      {v.model_count} models
+                    </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>
+                  )}
+                </div>
+
+                <div className="flex items-center gap-1 shrink-0">
+                  {/* Switch button — visible when loaded */}
+                  {canSwitch && (
+                    <button
+                      onClick={() => handleSwitch(v.id)}
+                      className="px-2 py-0.5 rounded text-xs font-medium
+                        bg-blue-700 hover:bg-blue-600 text-white transition-colors"
+                      title={`Switch to ${v.display}`}
+                    >
+                      Load
+                    </button>
+                  )}
+
+                  {/* Download button — visible when NOT loaded and NOT downloading */}
+                  {!v.loaded && !isDownloading && !isError && (
+                    <button
+                      onClick={() => handleDownload(v.id)}
+                      className="p-1.5 rounded-lg 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.5 h-3.5" />
+                    </button>
+                  )}
+
+                  {/* Spinner while downloading */}
+                  {isDownloading && (
+                    <RefreshCw className="w-3.5 h-3.5 text-yellow-400 animate-spin" />
+                  )}
+
+                  {/* Error retry */}
+                  {isError && !isDownloading && (
+                    <button
+                      onClick={() => handleDownload(v.id)}
+                      className="p-1.5 rounded-lg bg-gray-700 hover:bg-red-700
+                        text-red-400 hover:text-white transition-colors"
+                      title="Retry download"
+                    >
+                      <AlertCircle className="w-3.5 h-3.5" />
+                    </button>
+                  )}
+                </div>
+              </div>
+            );
+          })}
+
+          {/* Footer hint */}
+          <div className="px-3 py-2 border-t border-gray-700 text-xs text-gray-600 text-center">
+            Models hosted on Hugging Face Hub
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

scripts/download_models.py

@@ -2,7 +2,20 @@
 Download model artifacts from Hugging Face Hub at container startup.
 
 Called automatically by the Docker entrypoint before uvicorn starts.
-Downloads only if artifacts are missing (idempotent — skips already-present files).
+Can also download a specific version on-demand (e.g. from the API).
+
+HF model repo layout  (v1/ and v2/ at repo root):
+    v1/models/classical/*.joblib
+    v1/models/deep/*.pt  *.keras
+    v1/scalers/*.joblib
+    v2/models/classical/*.joblib
+    v2/models/deep/*.pt  *.keras
+    v2/scalers/*.joblib
+    v2/results/*.json
+
+Local layout after download  (local_dir = ARTIFACTS_DIR):
+    artifacts/v1/...
+    artifacts/v2/...
 """
 
 import os
@@ -14,83 +27,111 @@ from pathlib import Path
 # ──────────────────────────────────────────────────────────────────────────────
 REPO_ID   = "NeerajCodz/aiBatteryLifeCycle"
 REPO_TYPE = "model"
-# Token read from the HF_TOKEN Space Secret (set in Space Settings → Secrets)
+# Token read from the HF_TOKEN Space Secret (set in Space Settings -> Secrets)
 # For local use: set HF_TOKEN in your shell or .env before running
 HF_TOKEN  = os.getenv("HF_TOKEN", "")
 
-# Project root — snapshot_download uses this as local_dir so that files stored
-# at "artifacts/v1/..." in the HF repo land at <PROJECT_ROOT>/artifacts/v1/...
-# (NOT at <PROJECT_ROOT>/artifacts/artifacts/v1/... which would happen if we
-# pointed local_dir at the artifacts/ subfolder directly).
-PROJECT_ROOT = Path(__file__).resolve().parent.parent   # /app  (or repo root locally)
-ARTIFACTS_DIR = PROJECT_ROOT / "artifacts"
+# 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"
 
-# Sentinel file — written after a successful download
+# Sentinel file — written after a successful full download
 SENTINEL = ARTIFACTS_DIR / ".hf_downloaded"
 
 # ──────────────────────────────────────────────────────────────────────────────
 
 
-def already_downloaded() -> bool:
-    """Return True only when all three BestEnsemble component models are present.
+def _hf_kwargs(allow_patterns: list | None = None,
+               ignore_patterns: list | None = None) -> dict:
+    """Build kwargs for snapshot_download; inject token only when non-empty."""
+    kwargs: dict = dict(
+        repo_id=REPO_ID,
+        repo_type=REPO_TYPE,
+        local_dir=str(ARTIFACTS_DIR),
+    )
+    if allow_patterns:
+        kwargs["allow_patterns"] = allow_patterns
+    if ignore_patterns:
+        kwargs["ignore_patterns"] = ignore_patterns
+    if HF_TOKEN:
+        kwargs["token"] = HF_TOKEN
+    return kwargs
 
-    These three are required for ML simulation to work.  Any other models are
-    optional bonuses, but if these three are absent the Container must download.
-    """
-    required = [
-        ARTIFACTS_DIR / "v2" / "models" / "classical" / "random_forest.joblib",
-        ARTIFACTS_DIR / "v2" / "models" / "classical" / "xgboost.joblib",
-        ARTIFACTS_DIR / "v2" / "models" / "classical" / "lightgbm.joblib",
-    ]
-    missing = [p for p in required if not p.exists()]
+
+def _key_models(version: str = "v2") -> list:
+    base = ARTIFACTS_DIR / version / "models" / "classical"
+    return [base / f"{m}.joblib" for m in ("random_forest", "xgboost", "lightgbm")]
+
+
+def version_loaded(version: str) -> bool:
+    """Return True when the given version's key models exist on disk."""
+    return all(p.exists() for p in _key_models(version))
+
+
+def already_downloaded(version: str = "v2") -> bool:
+    """Return True only when all three BestEnsemble component models are present."""
+    missing = [p for p in _key_models(version) if not p.exists()]
     if missing:
         if SENTINEL.exists():
-            SENTINEL.unlink()   # stale sentinel — remove so next run re-downloads
-            print(f"[download_models] Sentinel was stale ({len(missing)} key models missing) — will re-download")
+            SENTINEL.unlink()
+            print(f"[download_models] Sentinel stale ({len(missing)} key models missing) — will re-download")
         return False
     return True
 
 
-def download_artifacts() -> None:
+def _ensure_hub():
     try:
-        from huggingface_hub import snapshot_download
+        from huggingface_hub import snapshot_download  # noqa: F401
     except ImportError:
-        print("[download_models] huggingface_hub not installed — installing now…")
         import subprocess
-        subprocess.check_call([sys.executable, "-m", "pip", "install", "huggingface_hub>=0.23", "-q"])
-        from huggingface_hub import snapshot_download
-
-    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+        subprocess.check_call([sys.executable, "-m", "pip", "install",
+                               "huggingface_hub>=0.23", "-q"])
 
-    print(f"[download_models] Downloading from {REPO_ID} → {ARTIFACTS_DIR}")
 
-    # Repo is public — only pass token when non-empty.
-    # Passing an empty string causes a 401 even on public repos.
-    # IMPORTANT: local_dir must be PROJECT_ROOT (not artifacts/) because the HF
-    # repo stores files under "artifacts/v1/..." — pointing local_dir at the
-    # project root makes them land at <root>/artifacts/v1/... as expected.
-    kwargs: dict = dict(
-        repo_id=REPO_ID,
-        repo_type=REPO_TYPE,
-        local_dir=str(PROJECT_ROOT),
-        ignore_patterns=["*.png", "*.jpg", "*.pdf", "*.log", "figures/**"],
-    )
-    if HF_TOKEN:
-        kwargs["token"] = HF_TOKEN
+def download_version(version: str) -> None:
+    """Download a single version (e.g. 'v1' or 'v2') from HF Hub into artifacts/."""
+    _ensure_hub()
+    from huggingface_hub import snapshot_download
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+    print(f"[download_models] Downloading {version}/ from {REPO_ID} -> {ARTIFACTS_DIR}")
+    snapshot_download(**_hf_kwargs(
+        allow_patterns=[f"{version}/**"],
+        ignore_patterns=["*.log"],
+    ))
+    print(f"[download_models] {version}/ ready")
+
+
+def download_all() -> None:
+    """Download all versions (v1 + v2) from HF Hub."""
+    _ensure_hub()
+    from huggingface_hub import snapshot_download
+    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"]))
+    SENTINEL.write_text("downloaded\n")
+    print("[download_models] Artifacts ready")
 
-    snapshot_download(**kwargs)
 
-    # Write sentinel
-    SENTINEL.write_text("downloaded\n")
-    print("[download_models] ✅ Artifacts ready")
+def main() -> None:
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--version", default=None,
+                        help="Download only this version, e.g. v1 or v2")
+    args = parser.parse_args()
 
+    if args.version:
+        if version_loaded(args.version):
+            print(f"[download_models] {args.version} already present — skipping")
+        else:
+            download_version(args.version)
+        return
 
-def main():
-    if already_downloaded():
+    # Default: ensure v2 (latest) is present
+    if already_downloaded("v2"):
         print("[download_models] Artifacts already present — skipping download")
         return
 
-    download_artifacts()
+    download_all()
 
 
 if __name__ == "__main__":

scripts/upload_models_to_hub.py

@@ -151,28 +151,42 @@ def main():
         commit_message="chore: update model card",
     )
 
-    # 3. Upload artifacts folder (models + scalers + results + figures + reports)
-    #    Only skip logs — everything else (including figures/reports) is preserved on HF Hub
+    # 3. Upload each version directly at repo root: v1/ and v2/ (NOT under artifacts/)
+    #    This keeps the HF model repo clean — download_models.py maps them back into
+    #    the local artifacts/ folder via local_dir=ARTIFACTS_DIR.
     for version in ["v1", "v2"]:
         version_path = ARTIFACTS / version
         if not version_path.exists():
             print(f"  [skip] {version_path} does not exist")
             continue
 
-        print(f"\nUploading artifacts/{version}/ …")
+        print(f"\nUploading {version}/ at repo root …")
         upload_folder(
             folder_path=str(version_path),
-            path_in_repo=f"artifacts/{version}",
+            path_in_repo=version,          # v1/ or v2/ at repo root
             repo_id=REPO_ID,
             repo_type=REPO_TYPE,
             token=HF_TOKEN,
             ignore_patterns=["logs/**", "*.log"],
-            commit_message=f"feat: upload {version} model artifacts (incl. figures & reports)",
+            commit_message=f"feat: upload {version} artifacts at repo root",
             run_as_future=False,
         )
-        print(f"  [OK] artifacts/{version} uploaded")
+        print(f"  [OK] {version}/ uploaded")
 
-    print("\n✅ All artifacts uploaded to", f"https://huggingface.co/{REPO_ID}")
+    # 4. Remove old artifacts/ tree that may exist from previous uploads
+    print("\nCleaning up legacy artifacts/ folder in HF repo (if any) …")
+    try:
+        api.delete_folder(
+            path_in_repo="artifacts",
+            repo_id=REPO_ID,
+            repo_type=REPO_TYPE,
+            commit_message="chore: remove legacy artifacts/ folder (moved to repo root)",
+        )
+        print("  [OK] artifacts/ removed")
+    except Exception as e:
+        print(f"  [skip] No legacy artifacts/ to remove ({e})")
+
+    print("\n[OK] All artifacts uploaded to", f"https://huggingface.co/{REPO_ID}")
 
 
 if __name__ == "__main__":