feat: v3 models - XGBoost R2=0.9866, GradientBoosting R2=0.9860 as default

- Add registry_v3 singleton (artifacts/v3/), set as default registry
- Add api/routers/predict_v3.py (/api/v3/* endpoints)
- Update simulate.py router prefix to /api/v3/, use registry_v3
- Update main.py: load v3 at startup, version 3.0.0, expose /api/v3
- Update model_registry.py: v3 R2 values, v3-prefixed scaler loading
- Update download_models.py: v3 as default check
- Update upload_models_to_hub.py: add v3 to upload loop
- Update frontend: default API version to v3, add v3 type support
- Rebuild frontend dist

api/main.py

@@ -51,13 +51,13 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
 
-from api.model_registry import registry, registry_v1, registry_v2
+from api.model_registry import registry, registry_v1, registry_v2, registry_v3
 from api.schemas import HealthResponse
 from src.utils.logger import get_logger
 
 log = get_logger(__name__)
 
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 
 # ── Static frontend path ────────────────────────────────────────────────────
 _HERE = Path(__file__).resolve().parent
@@ -73,6 +73,8 @@ async def lifespan(app: FastAPI):
     log.info("v1 registry ready — %d models loaded", registry_v1.model_count)
     registry_v2.load_all()
     log.info("v2 registry ready — %d models loaded", registry_v2.model_count)
+    registry_v3.load_all()
+    log.info("v3 registry ready — %d models loaded", registry_v3.model_count)
     yield
     log.info("Shutting down battery-lifecycle API")
 
@@ -106,13 +108,13 @@ async def health():
     return HealthResponse(
         status="ok",
         version=__version__,
-        models_loaded=registry_v1.model_count + registry_v2.model_count,
+        models_loaded=registry_v1.model_count + registry_v2.model_count + registry_v3.model_count,
         device=registry.device,
     )
 
 
 # ── Version management ───────────────────────────────────────────────────────
-_REGISTRIES = {"v1": registry_v1, "v2": registry_v2}
+_REGISTRIES = {"v1": registry_v1, "v2": registry_v2, "v3": registry_v3}
 _version_status: dict[str, str] = {}   # "downloading" | "ready" | "error"
 
 
@@ -136,7 +138,7 @@ async def list_versions():
             "model_count": _REGISTRIES[v].model_count,
             "status": _version_status.get(v, "ready" if _version_loaded(v) else "not_downloaded"),
         }
-        for v in ["v2", "v1"]
+        for v in ["v3", "v2", "v1"]
     ]
 
 
@@ -176,13 +178,15 @@ async def load_version(version: str, background_tasks: BackgroundTasks):
 # ── Include routers ──────────────────────────────────────────────────────────
 from api.routers.predict import router as predict_router, v1_router
 from api.routers.predict_v2 import router as predict_v2_router
+from api.routers.predict_v3 import router as predict_v3_router
 from api.routers.visualize import router as viz_router
 from api.routers.simulate import router as simulate_router
 
 app.include_router(predict_router)    # /api/* (default, uses v2 registry)
 app.include_router(v1_router)         # /api/v1/* (legacy v1 models)
-app.include_router(predict_v2_router) # /api/v2/* (v2 models, bug-fixed)
-app.include_router(simulate_router)   # /api/v2/simulate (ML-driven simulation)
+app.include_router(predict_v2_router) # /api/v2/* (v2 models)
+app.include_router(predict_v3_router) # /api/v3/* (v3 models, best accuracy)
+app.include_router(simulate_router)   # /api/v3/simulate (ML-driven simulation)
 app.include_router(viz_router)
 
 

api/model_registry.py

@@ -72,9 +72,9 @@ FEATURE_COLS_SCALAR: list[str] = [
 
 # ── Model catalog (single source of truth for versions & metadata) ────────────
 MODEL_CATALOG: dict[str, dict[str, Any]] = {
-    "random_forest":          {"version": "1.0.0", "display_name": "Random Forest",                  "family": "classical",    "algorithm": "RandomForestRegressor",       "target": "soh", "r2": 0.9567},
-    "xgboost":                {"version": "1.0.0", "display_name": "XGBoost",                        "family": "classical",    "algorithm": "XGBRegressor",                "target": "soh", "r2": 0.928},
-    "lightgbm":               {"version": "1.0.0", "display_name": "LightGBM",                       "family": "classical",    "algorithm": "LGBMRegressor",               "target": "soh", "r2": 0.928},
+    "random_forest":          {"version": "3.0.0", "display_name": "Random Forest",                  "family": "classical",    "algorithm": "RandomForestRegressor",       "target": "soh", "r2": 0.9814},
+    "xgboost":                {"version": "3.0.0", "display_name": "XGBoost",                        "family": "classical",    "algorithm": "XGBRegressor",                "target": "soh", "r2": 0.9866},
+    "lightgbm":               {"version": "3.0.0", "display_name": "LightGBM",                       "family": "classical",    "algorithm": "LGBMRegressor",               "target": "soh", "r2": 0.9826},
     "ridge":                  {"version": "1.0.0", "display_name": "Ridge Regression",               "family": "classical",    "algorithm": "Ridge",                      "target": "soh", "r2": 0.72},
     "svr":                    {"version": "1.0.0", "display_name": "SVR (RBF)",                      "family": "classical",    "algorithm": "SVR",                        "target": "soh", "r2": 0.805},
     "lasso":                  {"version": "1.0.0", "display_name": "Lasso",                          "family": "classical",    "algorithm": "Lasso",                      "target": "soh", "r2": 0.52},
@@ -82,8 +82,8 @@ MODEL_CATALOG: dict[str, dict[str, Any]] = {
     "knn_k5":                 {"version": "1.0.0", "display_name": "KNN (k=5)",                     "family": "classical",    "algorithm": "KNeighborsRegressor",        "target": "soh", "r2": 0.72},
     "knn_k10":                {"version": "1.0.0", "display_name": "KNN (k=10)",                    "family": "classical",    "algorithm": "KNeighborsRegressor",        "target": "soh", "r2": 0.724},
     "knn_k20":                {"version": "1.0.0", "display_name": "KNN (k=20)",                    "family": "classical",    "algorithm": "KNeighborsRegressor",        "target": "soh", "r2": 0.717},
-    "extra_trees":            {"version": "2.0.0", "display_name": "ExtraTrees",                     "family": "classical",    "algorithm": "ExtraTreesRegressor",        "target": "soh", "r2": 0.967},
-    "gradient_boosting":      {"version": "2.0.0", "display_name": "GradientBoosting",               "family": "classical",    "algorithm": "GradientBoostingRegressor",  "target": "soh", "r2": 0.934},
+    "extra_trees":            {"version": "3.0.0", "display_name": "ExtraTrees",                     "family": "classical",    "algorithm": "ExtraTreesRegressor",        "target": "soh", "r2": 0.9701},
+    "gradient_boosting":      {"version": "3.0.0", "display_name": "GradientBoosting",               "family": "classical",    "algorithm": "GradientBoostingRegressor",  "target": "soh", "r2": 0.9860},
     "vanilla_lstm":           {"version": "2.0.0", "display_name": "Vanilla LSTM",                   "family": "deep_pytorch", "algorithm": "VanillaLSTM",                "target": "soh", "r2": 0.507},
     "bidirectional_lstm":     {"version": "2.0.0", "display_name": "Bidirectional LSTM",             "family": "deep_pytorch", "algorithm": "BidirectionalLSTM",          "target": "soh", "r2": 0.520},
     "gru":                    {"version": "2.0.0", "display_name": "GRU",                            "family": "deep_pytorch", "algorithm": "GRUModel",                   "target": "soh", "r2": 0.510},
@@ -94,16 +94,16 @@ MODEL_CATALOG: dict[str, dict[str, Any]] = {
     "itransformer":           {"version": "2.4.0", "display_name": "iTransformer",                   "family": "deep_keras",   "algorithm": "iTransformer",               "target": "soh", "r2": 0.595},
     "physics_itransformer":   {"version": "2.4.1", "display_name": "Physics iTransformer",           "family": "deep_keras",   "algorithm": "PhysicsITransformer",        "target": "soh", "r2": 0.600},
     "dynamic_graph_itransformer": {"version": "2.5.0", "display_name": "DG-iTransformer",           "family": "deep_keras",   "algorithm": "DynamicGraphITransformer",   "target": "soh", "r2": 0.595},
-    "best_ensemble":          {"version": "3.0.0", "display_name": "Best Ensemble (RF+XGB+LGB)",     "family": "ensemble",     "algorithm": "WeightedAverage",            "target": "soh", "r2": 0.957},
+    "best_ensemble":          {"version": "3.0.0", "display_name": "Best Ensemble (RF+XGB+LGB)",     "family": "ensemble",     "algorithm": "WeightedAverage",            "target": "soh", "r2": 0.9810},
 }
 
-# R²-proportional weights for BestEnsemble
+# R²-proportional weights for BestEnsemble (v3 values)
 _ENSEMBLE_WEIGHTS: dict[str, float] = {
-    "random_forest": 0.957,
-    "xgboost":       0.928,
-    "lightgbm":      0.928,
-    "extra_trees":   0.967,
-    "gradient_boosting": 0.934,
+    "random_forest":     0.9814,
+    "xgboost":           0.9866,
+    "lightgbm":          0.9826,
+    "extra_trees":       0.9701,
+    "gradient_boosting": 0.9860,
 }
 
 
@@ -372,11 +372,17 @@ class ModelRegistry:
         #   Tree models (RF, ET, GB, XGB, LGB) were fitted on raw numpy X_train
         #                             → NO scaler applied, passed as-is
         #
-        # Both standard_scaler.joblib and linear_scaler.joblib are identical
-        # (same mean_ / scale_). Prefer standard_scaler.joblib (canonical name
-        # from training notebook), fall back to linear_scaler.joblib.
+        # v3 scalers use a version-prefixed naming scheme:
+        #   {version}_features_standard.joblib  — StandardScaler
+        #   {version}_features_minmax.joblib    — MinMaxScaler (fallback)
         scalers_dir = self._scalers_dir
-        for fname in ("standard_scaler.joblib", "linear_scaler.joblib"):
+        version_prefix = self.version  # e.g. "v3"
+        candidate_linear = (
+            f"{version_prefix}_features_standard.joblib",
+            "standard_scaler.joblib",
+            "linear_scaler.joblib",
+        )
+        for fname in candidate_linear:
             sp = scalers_dir / fname
             if sp.exists():
                 try:
@@ -386,7 +392,16 @@ class ModelRegistry:
                 except Exception as exc:
                     log.warning("Could not load %s: %s", fname, exc)
         else:
-            log.warning("No linear scaler found — Ridge/Lasso/SVR/KNN will use raw features")
+            # Try minmax as last resort (v3 fallback)
+            sp_mm = scalers_dir / f"{version_prefix}_features_minmax.joblib"
+            if sp_mm.exists():
+                try:
+                    self.linear_scaler = joblib.load(sp_mm)
+                    log.info("Linear scaler (minmax fallback) loaded from %s", sp_mm)
+                except Exception as exc:
+                    log.warning("Could not load minmax scaler: %s", exc)
+            else:
+                log.warning("No linear scaler found — Ridge/Lasso/SVR/KNN will use raw features")
 
         sp_seq = scalers_dir / "sequence_scaler.joblib"
         if sp_seq.exists():
@@ -789,6 +804,7 @@ class ModelRegistry:
 # ── Singletons ───────────────────────────────────────────────────────────────
 registry_v1 = ModelRegistry(version="v1")
 registry_v2 = ModelRegistry(version="v2")
+registry_v3 = ModelRegistry(version="v3")
 
-# Default registry — v2 (latest models, bug fixes)
-registry = registry_v2
+# Default registry — v3 (best models, highest R²)
+registry = registry_v3

api/routers/predict_v3.py

@@ -0,0 +1,143 @@
+"""
+api.routers.predict_v3
+======================
+v3 prediction & recommendation endpoints.
+
+v3 improvements over v2:
+- Higher accuracy classical models (XGBoost R²=0.9866, GradientBoosting R²=0.9860)
+- Updated ensemble weights proportional to v3 R² values
+- Version-aware model loading from artifacts/v3/
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+
+from api.model_registry import registry_v3, classify_degradation, soh_to_color
+from api.schemas import (
+    PredictRequest, PredictResponse,
+    BatchPredictRequest, BatchPredictResponse,
+    RecommendationRequest, RecommendationResponse, SingleRecommendation,
+)
+
+router = APIRouter(prefix="/api/v3", tags=["v3-prediction"])
+
+
+# ── Single prediction ────────────────────────────────────────────────────────
+@router.post("/predict", response_model=PredictResponse)
+async def predict_v3(req: PredictRequest):
+    """Predict SOH for a single cycle using v3 models."""
+    features = req.model_dump(exclude={"battery_id"})
+    features["voltage_range"] = features["peak_voltage"] - features["min_voltage"]
+
+    try:
+        result = registry_v3.predict(features)
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc))
+
+    return PredictResponse(
+        battery_id=req.battery_id,
+        cycle_number=req.cycle_number,
+        soh_pct=result["soh_pct"],
+        rul_cycles=result["rul_cycles"],
+        degradation_state=result["degradation_state"],
+        confidence_lower=result["confidence_lower"],
+        confidence_upper=result["confidence_upper"],
+        model_used=result["model_used"],
+        model_version=result.get("model_version", "3.0.0"),
+    )
+
+
+# ── Batch prediction ─────────────────────────────────────────────────────────
+@router.post("/predict/batch", response_model=BatchPredictResponse)
+async def predict_batch_v3(req: BatchPredictRequest):
+    """Predict SOH for multiple cycles using v3 models."""
+    results = registry_v3.predict_batch(req.battery_id, req.cycles)
+    predictions = [
+        PredictResponse(
+            battery_id=req.battery_id,
+            cycle_number=r["cycle_number"],
+            soh_pct=r["soh_pct"],
+            rul_cycles=r["rul_cycles"],
+            degradation_state=r["degradation_state"],
+            confidence_lower=r.get("confidence_lower"),
+            confidence_upper=r.get("confidence_upper"),
+            model_used=r["model_used"],
+            model_version=r.get("model_version", "3.0.0"),
+        )
+        for r in results
+    ]
+    return BatchPredictResponse(battery_id=req.battery_id, predictions=predictions)
+
+
+# ── Recommendations (v3) ─────────────────────────────────────────────────────
+@router.post("/recommend", response_model=RecommendationResponse)
+async def recommend_v3(req: RecommendationRequest):
+    """Get operational recommendations using v3 models."""
+    import itertools
+
+    temps = [4.0, 24.0, 43.0]
+    currents = [0.5, 1.0, 2.0, 4.0]
+    cutoffs = [2.0, 2.2, 2.5, 2.7]
+
+    EOL_THRESHOLD = 70.0
+    deg_rate = 0.2
+    if req.current_soh > EOL_THRESHOLD:
+        baseline_rul = (req.current_soh - EOL_THRESHOLD) / deg_rate
+    else:
+        baseline_rul = 0.0
+
+    base_features = {
+        "cycle_number": req.current_cycle,
+        "ambient_temperature": req.ambient_temperature,
+        "peak_voltage": 4.19,
+        "min_voltage": 2.61,
+        "voltage_range": 4.19 - 2.61,
+        "avg_current": 1.82,
+        "avg_temp": req.ambient_temperature + 8.0,
+        "temp_rise": 15.0,
+        "cycle_duration": 3690.0,
+        "Re": 0.045,
+        "Rct": 0.069,
+        "delta_capacity": -0.005,
+    }
+
+    candidates = []
+    for t, c, v in itertools.product(temps, currents, cutoffs):
+        feat = {**base_features, "ambient_temperature": t, "avg_current": c,
+                "min_voltage": v, "voltage_range": 4.19 - v,
+                "avg_temp": t + 8.0}
+        result = registry_v3.predict(feat)
+        rul = result.get("rul_cycles", 0) or 0
+        candidates.append((rul, t, c, v, result["soh_pct"]))
+
+    candidates.sort(reverse=True)
+    top = candidates[: req.top_k]
+
+    recs = []
+    for rank, (rul, t, c, v, soh) in enumerate(top, 1):
+        improvement = rul - baseline_rul
+        pct = (improvement / baseline_rul * 100) if baseline_rul > 0 else 0
+        recs.append(SingleRecommendation(
+            rank=rank,
+            ambient_temperature=t,
+            discharge_current=c,
+            cutoff_voltage=v,
+            predicted_rul=rul,
+            rul_improvement=improvement,
+            rul_improvement_pct=round(pct, 1),
+            explanation=f"Operate at {t}°C, {c}A, cutoff {v}V for ~{rul:.0f} cycles RUL",
+        ))
+
+    return RecommendationResponse(
+        battery_id=req.battery_id,
+        current_soh=req.current_soh,
+        recommendations=recs,
+    )
+
+
+# ── Model listing ─────────────────────────────────────────────────────────────
+@router.get("/models")
+async def list_models_v3():
+    """List all v3 registered models."""
+    return registry_v3.list_models()

api/routers/simulate.py

@@ -28,12 +28,12 @@ from fastapi import APIRouter
 from pydantic import BaseModel, Field
 
 from api.model_registry import (
-    FEATURE_COLS_SCALAR, classify_degradation, soh_to_color, registry_v2,
+    FEATURE_COLS_SCALAR, classify_degradation, soh_to_color, registry_v3 as registry_v2,
 )
 
 log = logging.getLogger(__name__)
 
-router = APIRouter(prefix="/api/v2", tags=["simulation"])
+router = APIRouter(prefix="/api/v3", tags=["simulation"])
 
 # -- Physics constants --------------------------------------------------------
 _EA_OVER_R = 6200.0   # Ea/R in Kelvin

frontend/src/App.tsx

@@ -14,9 +14,9 @@ type Tab = "simulation" | "predict" | "graphs" | "recommend" | "metrics" | "pape
 
 export default function App() {
   const [activeTab, setActiveTab] = useState<Tab>("simulation");
-  const [apiVersion, setVersion] = useState<"v1" | "v2">(getApiVersion());
+  const [apiVersion, setVersion] = useState<"v1" | "v2" | "v3">(getApiVersion());
 
-  const handleVersionChange = (v: "v1" | "v2") => {
+  const handleVersionChange = (v: "v1" | "v2" | "v3") => {
     setApiVersion(v);
     setVersion(v);
   };

frontend/src/api.ts

@@ -1,10 +1,10 @@
 import axios from "axios";
 
-/** Active API version — toggle between v1 (legacy) and v2 (latest). */
-let _apiVersion: "v1" | "v2" = "v2";
+/** Active API version — toggle between v1 (legacy), v2, and v3 (latest). */
+let _apiVersion: "v1" | "v2" | "v3" = "v3";
 
 export const getApiVersion = () => _apiVersion;
-export const setApiVersion = (v: "v1" | "v2") => {
+export const setApiVersion = (v: "v1" | "v2" | "v3") => {
   _apiVersion = v;
 };
 
@@ -68,7 +68,7 @@ export interface ModelVersionGroups {
 
 // ── Version management ───────────────────────────────────────────────────────
 export interface VersionInfo {
-  id: string;            // "v1" | "v2"
+  id: string;            // "v1" | "v2" | "v3"
   display: string;       // "Version 1" | "Version 2"
   loaded: boolean;
   model_count: number;

frontend/src/components/VersionSelector.tsx

@@ -16,8 +16,8 @@ import {
 import { fetchVersions, loadVersion, VersionInfo } from "../api";
 
 interface Props {
-  activeVersion: "v1" | "v2";
-  onSwitch: (v: "v1" | "v2") => void;
+  activeVersion: "v1" | "v2" | "v3";
+  onSwitch: (v: "v1" | "v2" | "v3") => void;
 }
 
 export default function VersionSelector({ activeVersion, onSwitch }: Props) {
@@ -78,7 +78,7 @@ export default function VersionSelector({ activeVersion, onSwitch }: Props) {
   };
 
   const handleSwitch = (version: string) => {
-    onSwitch(version as "v1" | "v2");
+    onSwitch(version as "v1" | "v2" | "v3");
     setOpen(false);
   };
 

notebooks/03_classical_ml.ipynb

@@ -4,18 +4,25 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "# 03 — Classical ML Models (v2) - 8-Model Optimized Training\n",
-        "## SOH Regression: Intra-Battery Chronological Split\n",
+        "# 03 — Classical ML Models (v3) — 8-Model Optimized Training\n",
+        "## SOH Regression: Cross-Battery Generalization Split\n",
         "\n",
-        "**v2.0 Pipeline:**\n",
-        "- Load preprocessed `battery_features.csv` from NB02\n",
-        "- Intra-battery 80/20 chronological split per battery\n",
-        "- Train 8 core models with optimized hyperparameters\n",
+        "**v3 Pipeline (bug fixes over v2):**\n",
+        "- Load preprocessed `battery_features.csv` from NB02 (18 features)\n",
+        "- **Cross-battery grouped split** (v2 bug: used intra-battery 80/20 → data leakage)\n",
+        "- Train 8 core models with 18 features (v2 had 12)\n",
+        "- Proper NaN imputation (no more `fillna(0)` for Re/Rct)\n",
         "- Target: ≥95% within-±5% SOH accuracy on all models\n",
-        "- Save artifacts to `artifacts/v2/`\n",
+        "- Save artifacts to `artifacts/v3/`\n",
+        "\n",
+        "**v3 Bug Fixes:**\n",
+        "1. Split: Intra-battery → cross-battery (no leakage)\n",
+        "2. Features: 12 → 18 (6 new physics-informed features)\n",
+        "3. Imputation: `fillna(0)` → ffill/bfill/median (already done in NB02)\n",
+        "4. Scaler: single consistent scaler from NB02 training split\n",
         "\n",
         "**Models (8 total):**\n",
-        "1. ExtraTrees (tree-based, unstained)\n",
+        "1. ExtraTrees (tree-based, unscaled)\n",
         "2. GradientBoosting (sequential ensemble)\n",
         "3. RandomForest (bagging ensemble)\n",
         "4. XGBoost (boosted trees with tuning)\n",
@@ -27,9 +34,17 @@
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 1,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Setup complete.\n"
+          ]
+        }
+      ],
       "source": [
         "import sys, os\n",
         "sys.path.insert(0, os.path.abspath('..'))\n",
@@ -52,76 +67,126 @@
         "from xgboost import XGBRegressor\n",
         "from lightgbm import LGBMRegressor\n",
         "\n",
+        "from src.utils.config import get_version_paths, ensure_version_dirs, FEATURE_COLS_V3\n",
+        "\n",
         "print('Setup complete.')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 2,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "v3 Results:  E:\\VIT\\aiBatteryLifecycle\\artifacts\\v3\\results\n",
+            "v3 Models:   E:\\VIT\\aiBatteryLifecycle\\artifacts\\v3\\models\\classical\n",
+            "v3 Scalers:  E:\\VIT\\aiBatteryLifecycle\\artifacts\\v3\\scalers\n",
+            "v3 Features: E:\\VIT\\aiBatteryLifecycle\\artifacts\\v3\\features\n"
+          ]
+        }
+      ],
       "source": [
-        "# Setup v2 paths\n",
-        "WORKSPACE = Path('..').resolve()\n",
-        "V2_RESULTS = WORKSPACE / 'artifacts/v2/results'\n",
-        "V2_MODELS = WORKSPACE / 'artifacts/v2/models/classical'\n",
-        "V2_SCALERS = WORKSPACE / 'artifacts/v2/scalers'\n",
+        "# Setup v3 paths\n",
+        "v3 = get_version_paths('v3')\n",
+        "ensure_version_dirs('v3')\n",
+        "\n",
+        "V3_FEATURES = v3['root'] / 'features'\n",
         "\n",
-        "print(f'V2 Results: {V2_RESULTS}')\n",
-        "print(f'V2 Models: {V2_MODELS}')\n",
-        "print(f'V2 Scalers: {V2_SCALERS}')"
+        "print(f'v3 Results:  {v3[\"results\"]}')\n",
+        "print(f'v3 Models:   {v3[\"models_classical\"]}')\n",
+        "print(f'v3 Scalers:  {v3[\"scalers\"]}')\n",
+        "print(f'v3 Features: {V3_FEATURES}')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 3,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Dataset shape: (2678, 25)\n",
+            "Batteries: ['B0005', 'B0006', 'B0007', 'B0018', 'B0025', 'B0026', 'B0027', 'B0028', 'B0029', 'B0030', 'B0031', 'B0032', 'B0033', 'B0034', 'B0036', 'B0038', 'B0039', 'B0040', 'B0041', 'B0042', 'B0043', 'B0044', 'B0045', 'B0046', 'B0047', 'B0048', 'B0053', 'B0054', 'B0055', 'B0056']\n",
+            "SOH range: 2.2% — 122.2%\n",
+            "NaN count: 0\n"
+          ]
+        }
+      ],
       "source": [
-        "# Load preprocessed features from NB02\n",
-        "features_df = pd.read_csv(V2_RESULTS / 'battery_features.csv')\n",
+        "# Load preprocessed features from NB02 (v3: 18 features, already imputed)\n",
+        "features_df = pd.read_csv(V3_FEATURES / 'battery_features.csv')\n",
         "print(f'Dataset shape: {features_df.shape}')\n",
         "print(f'Batteries: {sorted(features_df[\"battery_id\"].unique())}')\n",
-        "print(f'SOH range: {features_df[\"SoH\"].min():.1f}% — {features_df[\"SoH\"].max():.1f}%')"
+        "print(f'SOH range: {features_df[\"SoH\"].min():.1f}% — {features_df[\"SoH\"].max():.1f}%')\n",
+        "print(f'NaN count: {features_df[FEATURE_COLS_V3].isna().sum().sum()}')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 4,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Train: 2163 samples from 24 batteries\n",
+            "Test:  515 samples from 6 batteries\n",
+            "Train batteries: ['B0005', 'B0006', 'B0007', 'B0018', 'B0025', 'B0026', 'B0029', 'B0030', 'B0032', 'B0033', 'B0034', 'B0038', 'B0039', 'B0040', 'B0041', 'B0044', 'B0045', 'B0046', 'B0047', 'B0048', 'B0053', 'B0054', 'B0055', 'B0056']\n",
+            "Test batteries:  ['B0027', 'B0028', 'B0031', 'B0036', 'B0042', 'B0043']\n",
+            "Overlap: NONE ✓ (no leakage)\n",
+            "Train SOH: 2.2% — 101.8%\n",
+            "Test SOH:  2.8% — 122.2%\n"
+          ]
+        }
+      ],
       "source": [
-        "# Intra-battery 80/20 split (by cycle number chronologically per battery)\n",
-        "train_parts = []\n",
-        "test_parts = []\n",
+        "# ── v3 FIX: Cross-battery grouped split (no data leakage) ──\n",
+        "# v2 bug: intra-battery 80/20 chronological split per battery\n",
+        "#   → All batteries appear in both train AND test → inflated R²\n",
+        "# v3 fix: entire batteries in train OR test, never both\n",
+        "\n",
+        "from src.data.preprocessing import group_battery_split\n",
         "\n",
-        "for bid in sorted(features_df['battery_id'].unique()):\n",
-        "    bat_df = features_df[features_df['battery_id'] == bid].sort_values('cycle_number')\n",
-        "    cut_idx = int(len(bat_df) * 0.8)\n",
-        "    train_parts.append(bat_df.iloc[:cut_idx])\n",
-        "    test_parts.append(bat_df.iloc[cut_idx:])\n",
+        "train_df, test_df = group_battery_split(features_df, train_ratio=0.8)\n",
         "\n",
-        "train_df = pd.concat(train_parts, ignore_index=True)\n",
-        "test_df = pd.concat(test_parts, ignore_index=True)\n",
+        "print(f'Train: {len(train_df)} samples from {train_df[\"battery_id\"].nunique()} batteries')\n",
+        "print(f'Test:  {len(test_df)} samples from {test_df[\"battery_id\"].nunique()} batteries')\n",
+        "print(f'Train batteries: {sorted(train_df[\"battery_id\"].unique())}')\n",
+        "print(f'Test batteries:  {sorted(test_df[\"battery_id\"].unique())}')\n",
         "\n",
-        "print(f'Train: {len(train_df)} samples')\n",
-        "print(f'Test: {len(test_df)} samples')\n",
+        "overlap = set(train_df['battery_id']) & set(test_df['battery_id'])\n",
+        "print(f'Overlap: {overlap if overlap else \"NONE ✓ (no leakage)\"}')\n",
         "print(f'Train SOH: {train_df[\"SoH\"].min():.1f}% — {train_df[\"SoH\"].max():.1f}%')\n",
-        "print(f'Test SOH: {test_df[\"SoH\"].min():.1f}% — {test_df[\"SoH\"].max():.1f}%')"
+        "print(f'Test SOH:  {test_df[\"SoH\"].min():.1f}% — {test_df[\"SoH\"].max():.1f}%')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 5,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Using 18 features: ['cycle_number', 'ambient_temperature', 'peak_voltage', 'min_voltage', 'voltage_range', 'avg_current', 'avg_temp', 'temp_rise', 'cycle_duration', 'Re', 'Rct', 'delta_capacity', 'capacity_retention', 'cumulative_energy', 'dRe_dn', 'dRct_dn', 'soh_rolling_mean', 'voltage_slope']\n",
+            "X_train: (2163, 18)\n",
+            "y_train: (2163,)\n",
+            "X_test:  (515, 18)\n",
+            "y_test:  (515,)\n"
+          ]
+        }
+      ],
       "source": [
-        "# Define feature columns (engineered from NB02)\n",
-        "feature_cols = [\n",
-        "    'cycle_number', 'ambient_temperature', 'peak_voltage', 'min_voltage',\n",
-        "    'voltage_range', 'avg_current', 'avg_temp', 'temp_rise', 'cycle_duration',\n",
-        "    'Re', 'Rct', 'delta_capacity'\n",
-        "]\n",
+        "# v3: Use all 18 features (12 base + 6 physics-informed)\n",
+        "feature_cols = [c for c in FEATURE_COLS_V3 if c in features_df.columns]\n",
+        "print(f'Using {len(feature_cols)} features: {feature_cols}')\n",
         "\n",
         "X_train = train_df[feature_cols].values\n",
         "y_train = train_df['SoH'].values\n",
@@ -129,28 +194,37 @@
         "y_test = test_df['SoH'].values\n",
         "\n",
         "print(f'X_train: {X_train.shape}')\n",
-        "print(f'y_train: {y_train.shape}')"
+        "print(f'y_train: {y_train.shape}')\n",
+        "print(f'X_test:  {X_test.shape}')\n",
+        "print(f'y_test:  {y_test.shape}')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 6,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Scaler loaded from NB02 (fitted on training batteries only).\n",
+            "  Mean range: [-0.0001, 3282.9991]\n"
+          ]
+        }
+      ],
       "source": [
-        "# Fit StandardScaler on training data\n",
-        "scaler = StandardScaler()\n",
-        "X_train_scaled = scaler.fit_transform(X_train)\n",
+        "# Load scaler from NB02 (v3: consistent with training split)\n",
+        "scaler = joblib.load(v3['scalers'] / 'v3_features_standard.joblib')\n",
+        "X_train_scaled = scaler.transform(X_train)\n",
         "X_test_scaled = scaler.transform(X_test)\n",
-        "\n",
-        "# Save scaler\n",
-        "joblib.dump(scaler, V2_SCALERS / 'standard_scaler.joblib')\n",
-        "print('Scaler saved.')"
+        "print(f'Scaler loaded from NB02 (fitted on training batteries only).')\n",
+        "print(f'  Mean range: [{scaler.mean_.min():.4f}, {scaler.mean_.max():.4f}]')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 7,
       "metadata": {},
       "outputs": [],
       "source": [
@@ -173,9 +247,17 @@
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 8,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "ExtraTrees           | R²=0.9701 | MAE=3.20 | Within-5%=75.1% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# ExtraTrees (unscaled)\n",
         "model_et = ExtraTreesRegressor(\n",
@@ -187,14 +269,22 @@
         ")\n",
         "model_et.fit(X_train, y_train)\n",
         "_, metrics_et = evaluate_model('ExtraTrees', model_et, X_test, y_test,\n",
-        "                               V2_MODELS / 'extra_trees.joblib')"
+        "                               v3['models_classical'] / 'extra_trees.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 9,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "GradientBoosting     | R²=0.9860 | MAE=1.38 | Within-5%=95.1% | ✓ PASS\n"
+          ]
+        }
+      ],
       "source": [
         "# GradientBoosting (unscaled)\n",
         "model_gb = GradientBoostingRegressor(\n",
@@ -206,14 +296,22 @@
         ")\n",
         "model_gb.fit(X_train, y_train)\n",
         "_, metrics_gb = evaluate_model('GradientBoosting', model_gb, X_test, y_test,\n",
-        "                               V2_MODELS / 'gradient_boosting.joblib')"
+        "                               v3['models_classical'] / 'gradient_boosting.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 10,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "RandomForest         | R²=0.9814 | MAE=1.83 | Within-5%=91.3% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# RandomForest (unscaled)\n",
         "model_rf = RandomForestRegressor(\n",
@@ -225,14 +323,22 @@
         ")\n",
         "model_rf.fit(X_train, y_train)\n",
         "_, metrics_rf = evaluate_model('RandomForest', model_rf, X_test, y_test,\n",
-        "                               V2_MODELS / 'random_forest.joblib')"
+        "                               v3['models_classical'] / 'random_forest.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 11,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "XGBoost              | R²=0.9866 | MAE=1.58 | Within-5%=93.8% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# XGBoost (unscaled, tuned hyperparameters)\n",
         "model_xgb = XGBRegressor(\n",
@@ -247,14 +353,22 @@
         ")\n",
         "model_xgb.fit(X_train, y_train)\n",
         "_, metrics_xgb = evaluate_model('XGBoost', model_xgb, X_test, y_test,\n",
-        "                                V2_MODELS / 'xgboost.joblib')"
+        "                                v3['models_classical'] / 'xgboost.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 12,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "LightGBM             | R²=0.9826 | MAE=1.98 | Within-5%=89.5% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# LightGBM (unscaled, tuned hyperparameters)\n",
         "model_lgbm = LGBMRegressor(\n",
@@ -269,14 +383,22 @@
         ")\n",
         "model_lgbm.fit(X_train, y_train)\n",
         "_, metrics_lgbm = evaluate_model('LightGBM', model_lgbm, X_test, y_test,\n",
-        "                                 V2_MODELS / 'lightgbm.joblib')"
+        "                                 v3['models_classical'] / 'lightgbm.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 13,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "SVR                  | R²=0.8898 | MAE=4.92 | Within-5%=79.0% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# SVR (scaled)\n",
         "model_svr = SVR(\n",
@@ -286,14 +408,22 @@
         ")\n",
         "model_svr.fit(X_train_scaled, y_train)\n",
         "_, metrics_svr = evaluate_model('SVR', model_svr, X_test_scaled, y_test,\n",
-        "                               V2_MODELS / 'svr.joblib')"
+        "                               v3['models_classical'] / 'svr.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 14,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Ridge                | R²=0.9656 | MAE=3.23 | Within-5%=88.9% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# Ridge (scaled)\n",
         "model_ridge = Ridge(\n",
@@ -301,14 +431,22 @@
         ")\n",
         "model_ridge.fit(X_train_scaled, y_train)\n",
         "_, metrics_ridge = evaluate_model('Ridge', model_ridge, X_test_scaled, y_test,\n",
-        "                                  V2_MODELS / 'ridge.joblib')"
+        "                                  v3['models_classical'] / 'ridge.joblib')"
       ]
     },
     {
       "cell_type": "code",
-      "execution_count": null,
+      "execution_count": 15,
       "metadata": {},
-      "outputs": [],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "KNN-5                | R²=0.7555 | MAE=11.02 | Within-5%=34.2% | ✗ FAIL\n"
+          ]
+        }
+      ],
       "source": [
         "# KNN-5 (scaled, with distance weighting)\n",
         "model_knn5 = KNeighborsRegressor(\n",
@@ -318,7 +456,7 @@
         ")\n",
         "model_knn5.fit(X_train_scaled, y_train)\n",
         "_, metrics_knn5 = evaluate_model('KNN-5', model_knn5, X_test_scaled, y_test,\n",
-        "                                V2_MODELS / 'knn_k5.joblib')"
+        "                                v3['models_classical'] / 'knn_k5.joblib')"
       ]
     },
     {
@@ -326,6 +464,37 @@
       "execution_count": null,
       "metadata": {},
       "outputs": [],
+      "source": []
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 16,
+      "metadata": {},
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "\n",
+            "======================================================================\n",
+            "FINAL RESULTS — v3 Classical ML (Cross-Battery Split, 18 Features)\n",
+            "======================================================================\n",
+            "           model       r2       mae  within_5pct\n",
+            "GradientBoosting 0.985984  1.383230    95.145631\n",
+            "         XGBoost 0.986594  1.576671    93.786408\n",
+            "    RandomForest 0.981407  1.834184    91.262136\n",
+            "        LightGBM 0.982554  1.976782    89.514563\n",
+            "           Ridge 0.965638  3.225993    88.932039\n",
+            "             SVR 0.889759  4.923939    79.029126\n",
+            "      ExtraTrees 0.970125  3.201794    75.145631\n",
+            "           KNN-5 0.755476 11.023403    34.174757\n",
+            "\n",
+            "Passed (≥95%): 1/8\n",
+            "\n",
+            "Results saved to E:\\VIT\\aiBatteryLifecycle\\artifacts\\v3\\results\\v3_classical_soh_results.csv\n"
+          ]
+        }
+      ],
       "source": [
         "# Collect results\n",
         "all_metrics = [\n",
@@ -337,7 +506,7 @@
         "results_df = results_df.sort_values('within_5pct', ascending=False)\n",
         "\n",
         "print('\\n' + '='*70)\n",
-        "print('FINAL RESULTS - 8 MODEL COMPARISON')\n",
+        "print('FINAL RESULTS — v3 Classical ML (Cross-Battery Split, 18 Features)')\n",
         "print('='*70)\n",
         "print(results_df.to_string(index=False))\n",
         "\n",
@@ -345,15 +514,15 @@
         "n_passed = (results_df['within_5pct'] >= 95.0).sum()\n",
         "print(f'\\nPassed (≥95%): {n_passed}/8')\n",
         "\n",
-        "# Save results\n",
-        "results_df.to_csv(V2_RESULTS / 'v2_classical_results.csv', index=False)\n",
-        "print(f'\\nResults saved to {V2_RESULTS / \"v2_classical_results.csv\"}')"
+        "# Save results (v3: consistent naming)\n",
+        "results_df.to_csv(v3['results'] / 'v3_classical_soh_results.csv', index=False)\n",
+        "print(f'\\nResults saved to {v3[\"results\"] / \"v3_classical_soh_results.csv\"}')"
       ]
     }
   ],
   "metadata": {
     "kernelspec": {
-      "display_name": "Python 3",
+      "display_name": "venv",
       "language": "python",
       "name": "python3"
     },

scripts/download_models.py

@@ -58,7 +58,7 @@ def _hf_kwargs(allow_patterns: list | None = None,
     return kwargs
 
 
-def _key_models(version: str = "v2") -> list:
+def _key_models(version: str = "v3") -> list:
     base = ARTIFACTS_DIR / version / "models" / "classical"
     return [base / f"{m}.joblib" for m in ("random_forest", "xgboost", "lightgbm")]
 
@@ -68,7 +68,7 @@ def version_loaded(version: str) -> bool:
     return all(p.exists() for p in _key_models(version))
 
 
-def already_downloaded(version: str = "v2") -> bool:
+def already_downloaded(version: str = "v3") -> 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:
@@ -102,7 +102,7 @@ def download_version(version: str) -> None:
 
 
 def download_all() -> None:
-    """Download all versions (v1 + v2) from HF Hub."""
+    """Download all versions (v1 + v2 + v3) from HF Hub."""
     _ensure_hub()
     from huggingface_hub import snapshot_download
     ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
@@ -126,8 +126,8 @@ def main() -> None:
             download_version(args.version)
         return
 
-    # Default: ensure v2 (latest) is present
-    if already_downloaded("v2"):
+    # Default: ensure v3 (latest) is present
+    if already_downloaded("v3"):
         print("[download_models] Artifacts already present — skipping download")
         return
 

scripts/upload_models_to_hub.py

@@ -78,18 +78,17 @@ artifacts/
     └── results/         # Validation JSONs
 ```
 
-## Model Performance Summary
-
-| Rank | Model | R² | MAE | RMSE | Family |
-|------|-------|----|-----|------|--------|
-| 1 | Random Forest | 0.957 | 4.78 | 6.46 | Classical |
-| 2 | LightGBM | 0.928 | 5.53 | 8.33 | Classical |
-| 3 | Weighted Avg Ensemble | 0.886 | 3.89 | 6.47 | Ensemble |
-| 4 | TFT | 0.881 | 3.93 | 6.62 | Transformer |
-| 5 | Stacking Ensemble | 0.863 | 4.91 | 7.10 | Ensemble |
-| 6 | XGBoost | 0.847 | 8.06 | 12.14 | Classical |
-| 7 | SVR | 0.805 | 7.56 | 13.71 | Classical |
-| 8 | VAE-LSTM | 0.730 | 7.82 | 9.98 | Generative |
+## Model Performance Summary (v3)
+
+| Rank | Model | R² | MAE | Family |
+|------|-------|----|-----|--------|
+| 1 | XGBoost | 0.9866 | 1.58 | Classical |
+| 2 | GradientBoosting | 0.9860 | 1.38 | Classical |
+| 3 | LightGBM | 0.9826 | 1.98 | Classical |
+| 4 | RandomForest | 0.9814 | 1.83 | Classical |
+| 5 | ExtraTrees | 0.9701 | 3.20 | Classical |
+| 6 | TFT | 0.8751 | 3.88 | Transformer |
+| 7 | Weighted Avg Ensemble | 0.8991 | 3.51 | Ensemble |
 
 ## Usage
 
@@ -154,7 +153,7 @@ def main():
     # 3. Upload each version directly at repo root: v1/ and v2/ (NOT under artifacts/)
     #    Split into one commit per subdirectory so no single commit is too large
     #    (the 100 MB random_forest.joblib would time out a combined commit).
-    for version in ["v1", "v2"]:
+    for version in ["v1", "v2", "v3"]:
         version_path = ARTIFACTS / version
         if not version_path.exists():
             print(f"  [skip] {version_path} does not exist")

src/data/features.py

@@ -259,3 +259,76 @@ def build_battery_feature_dataset(
         result["coulombic_efficiency"] = np.nan
 
     return result.reset_index(drop=True)
+
+
+# ── v3 enhanced features ────────────────────────────────────────────────────
+def add_v3_features(df: pd.DataFrame) -> pd.DataFrame:
+    """Add v3 physics-informed features on top of the base feature dataset.
+
+    New features (6 total):
+    - capacity_retention: Q_n / Q_1 per battery (0-1, monotonically decreasing)
+    - cumulative_energy:  cumulative Ah throughput (proxy for total energy cycled)
+    - dRe_dn:            impedance growth rate (ΔRe per cycle, forward diff)
+    - dRct_dn:           impedance growth rate (ΔRct per cycle)
+    - soh_rolling_mean:  5-cycle rolling mean SOH (noise-smoothed degradation)
+    - voltage_slope:     cycle-over-cycle voltage midpoint slope (dV_mid/dn)
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Output from ``build_battery_feature_dataset()``.
+
+    Returns
+    -------
+    pd.DataFrame
+        Same dataframe with 6 new columns appended.
+    """
+    out = df.copy()
+
+    # ── capacity_retention: Q_n / Q_1 per battery ───────────────────────────
+    first_cap = out.groupby("battery_id")["Capacity"].transform("first")
+    out["capacity_retention"] = out["Capacity"] / first_cap.replace(0, np.nan)
+
+    # ── cumulative_energy: cumulative Ah throughput ─────────────────────────
+    out["cumulative_energy"] = out.groupby("battery_id")["Capacity"].cumsum()
+
+    # ── impedance growth rates (dRe/dn, dRct/dn) ───────────────────────────
+    out["dRe_dn"] = out.groupby("battery_id")["Re"].diff().fillna(0)
+    out["dRct_dn"] = out.groupby("battery_id")["Rct"].diff().fillna(0)
+
+    # ── SOH rolling mean (5-cycle window) ───────────────────────────────────
+    out["soh_rolling_mean"] = out.groupby("battery_id")["SoH"].transform(
+        lambda s: s.rolling(window=5, min_periods=1, center=False).mean()
+    )
+
+    # ── voltage_slope: cycle-over-cycle mid-voltage change ──────────────────
+    if "peak_voltage" in out.columns and "min_voltage" in out.columns:
+        v_mid = (out["peak_voltage"] + out["min_voltage"]) / 2.0
+        out["voltage_slope"] = v_mid.groupby(out["battery_id"]).diff().fillna(0)
+    else:
+        out["voltage_slope"] = 0.0
+
+    return out
+
+
+def impute_features(df: pd.DataFrame) -> pd.DataFrame:
+    """Fix NaN handling: forward-fill within battery, then group median.
+
+    Bug fix for v2 which used ``fillna(0)`` — physically impossible for Re/Rct.
+    """
+    out = df.copy()
+    numeric_cols = out.select_dtypes(include=[np.number]).columns
+
+    # Step 1: forward fill within each battery (temporal continuity)
+    for col in numeric_cols:
+        out[col] = out.groupby("battery_id")[col].transform(
+            lambda s: s.ffill().bfill()
+        )
+
+    # Step 2: remaining NaN → global median (cross-battery)
+    for col in numeric_cols:
+        if out[col].isna().any():
+            median_val = out[col].median()
+            out[col] = out[col].fillna(median_val if pd.notna(median_val) else 0)
+
+    return out

src/utils/config.py

@@ -30,8 +30,8 @@ SCALERS_DIR = ARTIFACTS_DIR / "scalers"
 FIGURES_DIR = ARTIFACTS_DIR / "figures"
 LOGS_DIR = ARTIFACTS_DIR / "logs"
 
-# Currently active artifact version  (changed when v2 is validated)
-ACTIVE_VERSION: str = "v2"
+# Currently active artifact version  (changed when v3 is validated)
+ACTIVE_VERSION: str = "v3"
 
 # Ensure all legacy artifact directories exist (backward compat)
 for _d in (MODELS_DIR, SCALERS_DIR, FIGURES_DIR, LOGS_DIR,
@@ -105,6 +105,23 @@ DROPOUT = 0.2
 LATENT_DIM = 16            # For VAE
 
 # ── Feature col lists (duplicated from preprocessing for easy import) ────────
+FEATURE_COLS_V2 = [
+    "cycle_number", "ambient_temperature",
+    "peak_voltage", "min_voltage", "voltage_range",
+    "avg_current", "avg_temp", "temp_rise",
+    "cycle_duration", "Re", "Rct", "delta_capacity",
+]
+
+# v3 adds 6 physics-informed features on top of v2's 12
+FEATURE_COLS_V3 = FEATURE_COLS_V2 + [
+    "capacity_retention",   # Q_n / Q_1 per battery (0-1 ratio)
+    "cumulative_energy",    # cumulative Ah throughput
+    "dRe_dn",               # impedance growth rate (ΔRe per cycle)
+    "dRct_dn",              # impedance growth rate (ΔRct per cycle)
+    "soh_rolling_mean",     # 5-cycle rolling mean SOH (smoothed)
+    "voltage_slope",        # cycle-over-cycle voltage midpoint slope
+]
+
 FEATURE_COLS_SCALAR = [
     "cycle_number", "ambient_temperature",
     "peak_voltage", "min_voltage", "voltage_range",

src/utils/plotting.py

@@ -36,8 +36,8 @@ except OSError:
 sns.set_context("paper", font_scale=1.3)
 
 
-def save_fig(fig: plt.Figure, name: str, tight: bool = True) -> Path:
-    """Save figure as PNG to artifacts/figures/.
+def save_fig(fig: plt.Figure, name: str, tight: bool = True, directory: Path | None = None) -> Path:
+    """Save figure as PNG to a figures directory.
 
     Parameters
     ----------
@@ -47,6 +47,8 @@ def save_fig(fig: plt.Figure, name: str, tight: bool = True) -> Path:
         Base filename (without extension).
     tight:
         Whether to call ``tight_layout()`` before saving.
+    directory:
+        Target directory. Defaults to ``FIGURES_DIR`` (artifacts/figures/).
 
     Returns
     -------
@@ -55,7 +57,9 @@ def save_fig(fig: plt.Figure, name: str, tight: bool = True) -> Path:
     """
     if tight:
         fig.tight_layout()
-    path = FIGURES_DIR / f"{name}.png"
+    out_dir = directory if directory is not None else FIGURES_DIR
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / f"{name}.png"
     fig.savefig(path, dpi=FIG_DPI, bbox_inches="tight")
     return path