VERSION.md

Project Versioning & Structure

Current Active Version: v2.0

All active models, artifacts, and features use the v2.0 versioning scheme.

Directory Structure

artifacts/
├── v1/                     ← Legacy models (cross-battery split)
│   ├── models/
│   │   ├── classical/
│   │   ├── deep/
│   │   └── ensemble/
│   ├── scalers/
│   ├── figures/
│   ├── results/
│   ├── logs/
│   └── features/
│       
├── v2/                     ← Current production (intra-battery split) ✓
│   ├── models/
│   │   ├── classical/      ← 14 classical ML models
│   │   ├── deep/           ← 8 deep learning models  
│   │   └── ensemble/       ← Weighted ensemble
│   ├── scalers/            ← Feature scalers for linear models
│   ├── figures/            ← All validation visualizations (PNG, HTML)
│   ├── results/            ← CSV/JSON results and feature matrices
│   ├── logs/               ← Training logs
│   └── features/           ← Feature engineering artifacts

V2 Key Changes from V1

Aspect	V1	V2
Data Split	Cross-battery (groups of batteries)	Intra-battery chronological (first 80% cycles per battery)
Train/Test Contamination	⚠️ YES (same batteries in both)	✓ NO (different time periods per battery)
Generalization	Poor (batteries see same time periods)	Better (true temporal split)
Test Realism	Interpolation (within-cycle prediction)	Extrapolation (future cycles)
Classical Models	6 standard models	14 models (added ExtraTrees, GradientBoosting, KNN ×3)
Deep Models	8 models	Retraining in progress
Ensemble	RF + XGB + LGB (v1 trained)	RF + XGB + LGB (v2 trained when available)

Model Statistics

Classical Models (V2)

• Total: 14 models
• Target Metric: Within-±5% SOH accuracy ≥ 95%
• Current Pass Rate: See artifacts/v2/results/v2_validation_report.html

Configuration

Active version is set in src/utils/config.py:

ACTIVE_VERSION: str = "v2"

API defaults to v2:

registry = registry_v2  # Default registry (v2.0.0 models)

Migration Checklist ✓

• ✓ Created versioned artifact directories under artifacts/v2/
• ✓ Moved all v2 models to artifacts/v2/models/classical/ etc.
• ✓ Moved all results to artifacts/v2/results/
• ✓ Moved all figures to artifacts/v2/figures/
• ✓ Moved all scalers to artifacts/v2/scalers/
• ✓ Updated notebooks (NB03-09) to use get_version_paths('v2')
• ✓ Updated API to default to v2 registry
• ✓ Organized scripts into scripts/data/, scripts/models/
• ✓ Moved tests to tests/ folder
• ✓ Cleaned up legacy artifact directories

File Locations

Content	Path
Models (classical)	artifacts/v2/models/classical/*.joblib
Models (deep)	artifacts/v2/models/deep/*.pth
Models (ensemble)	artifacts/v2/models/ensemble/*.joblib
Scalers	artifacts/v2/scalers/*.joblib
Results CSV	artifacts/v2/results/*.csv
Feature matrix	artifacts/v2/results/battery_features.csv
Visualizations	artifacts/v2/figures/*.{png,html}
Logs	artifacts/v2/logs/*.log

Running Scripts

# Run v2 model validation test
python tests/test_v2_models.py

# Run quick prediction test  
python tests/test_predictions.py

# Retrain classical models (WARNING: takes ~30 min)
python scripts/models/retrain_classical.py

# Generate/patch notebooks (one-time utilities)
python scripts/data/write_nb03_v2.py
python scripts/data/patch_dl_notebooks_v2.py

Next Steps

1. ✓ Verify v2 model accuracy meets thresholds
2. ✓ Update research paper with v2 results
3. ✓ Complete research notes for all notebooks
4. ✓ Test cycle recommendation engine
5. Deploy v2 to production

Version History

Version	Date	Status	Notes
v1.0	2025-Q1	✓ Complete	Classical + Deep models, cross-battery split
v2.0	2026-02-25	✓ Active	Intra-battery split, improved generalization
v3.0	TBD	--	Physics-informed models, uncertainty quantification