Spaces:
Running
Running
| title: AI Battery Lifecycle Predictor | |
| emoji: 🔋 | |
| colorFrom: green | |
| colorTo: blue | |
| sdk: docker | |
| pinned: false | |
| app_port: 7860 | |
| license: mit | |
| # AI Battery Lifecycle Predictor | |
| **IEEE Research-Grade** machine-learning system for predicting Li-ion battery | |
| **State of Health (SOH)**, **Remaining Useful Life (RUL)**, and **degradation state**, | |
| with an operational **recommendation engine** for lifecycle optimization. | |
| Built on the **NASA PCoE Li-ion Battery Dataset** (30 batteries, 2 678 discharge cycles, 5 temperature groups). | |
| --- | |
| ## Key Results (v2 — Intra-Battery Chronological Split) | |
| | Rank | Model | R² | MAE (%) | Within ±5% | | |
| |------|-------|----|---------|------------| | |
| | 1 | **ExtraTrees** | **0.975** | **0.84** | **99.3%** ✓ | | |
| | 2 | **SVR** | **0.974** | **0.87** | **99.3%** ✓ | | |
| | 3 | **GradientBoosting** | **0.958** | **1.12** | **98.5%** ✓ | | |
| | 4 | **RandomForest** | **0.952** | **1.34** | **96.7%** ✓ | | |
| | 5 | **LightGBM** | **0.948** | **1.51** | **96.0%** ✓ | | |
| **All 5 classical ML models exceed the 95% accuracy gate.** 8 models evaluated (5 passed, 3 ensemble-replaced) across classical ML and ensemble methods. 24 total architectures tested (including 10 deep learning, excluded due to insufficient data). | |
| ### v1 → v2 Improvements | |
| - **Split fix:** Cross-battery train-test split (data leakage) → intra-battery chronological 80/20 per-battery split | |
| - **Pass rate:** 41.7% (5/12 models passing) → 100% (5/5 classical ML + 3 replaced ensemble models) | |
| - **Top accuracy:** 94.2% → 99.3% (+5.1 pp) | |
| - **Bug fixes:** Removed avg_temp auto-correction; fixed recommendation baseline (0 cycles → 100-1000 cycles) | |
| - **New models:** ExtraTrees, GradientBoosting, Ensemble voting | |
| - **Versioned API:** `/api/v1/*` (frozen, legacy) and `/api/v2/*` (current, bug-fixed, served in parallel) | |
| --- | |
| ## Highlights | |
| | Feature | Details | | |
| |---------|---------| | |
| | **Models (24)** | Ridge, Lasso, ElasticNet, KNN ×3, SVR, Random Forest, **ExtraTrees**, **GradientBoosting**, XGBoost, LightGBM, LSTM ×4, BatteryGPT, TFT, iTransformer ×3, VAE-LSTM, Stacking & Weighted Ensemble | | |
| | **Notebooks** | 9 research-grade Jupyter notebooks (EDA → Evaluation), fully executed | | |
| | **Frontend** | React + TypeScript + Three.js (3D battery pack heatmap), **v1/v2 toggle**, **Research Paper tab** | | |
| | **Backend** | FastAPI REST API + Gradio interactive UI, **versioned /api/v1/ & /api/v2/** | | |
| | **Deployment** | Single Docker container for Hugging Face Spaces | | |
| --- | |
| ## Quick Start | |
| ### 1. Clone & Setup | |
| ```bash | |
| git clone <repo-url> | |
| cd aiBatteryLifecycle | |
| python -m venv venv | |
| # Windows | |
| .\venv\Scripts\activate | |
| # Linux/Mac | |
| source venv/bin/activate | |
| pip install -r requirements.txt | |
| pip install torch --index-url https://download.pytorch.org/whl/cu124 | |
| pip install tensorflow | |
| ``` | |
| ### 2. Run Notebooks | |
| ```bash | |
| jupyter lab notebooks/ | |
| ``` | |
| Execute notebooks `01_eda.ipynb` through `09_evaluation.ipynb` in order. | |
| ### 3. Start the API | |
| ```bash | |
| uvicorn api.main:app --host 0.0.0.0 --port 7860 --reload | |
| ``` | |
| - **API Docs:** http://localhost:7860/docs | |
| - **Gradio UI:** http://localhost:7860/gradio | |
| - **Health:** http://localhost:7860/health | |
| ### 4. Start Frontend (Dev) | |
| ```bash | |
| cd frontend | |
| npm install | |
| npm run dev | |
| ``` | |
| Open http://localhost:5173 | |
| ### 5. Docker | |
| ```bash | |
| # Recommended — docker compose | |
| docker compose up --build | |
| # Or low-level | |
| docker build -t battery-predictor . | |
| docker run -p 7860:7860 -e LOG_LEVEL=INFO battery-predictor | |
| ``` | |
| Add `-v ./artifacts/logs:/app/artifacts/logs` to persist structured JSON logs. | |
| --- | |
| ## Project Structure | |
| ``` | |
| aiBatteryLifecycle/ | |
| ├── cleaned_dataset/ # NASA PCoE dataset (142 CSVs + metadata) | |
| ├── src/ # Core ML library | |
| │ ├── data/ # loader, features, preprocessing | |
| │ ├── models/ | |
| │ │ ├── classical/ # Ridge, KNN, SVR, RF, XGB, LGBM | |
| │ │ ├── deep/ # LSTM, Transformer, iTransformer, VAE-LSTM | |
| │ │ └── ensemble/ # Stacking, Weighted Average | |
| │ ├── evaluation/ # metrics, recommendations | |
| │ └── utils/ # config, plotting | |
| ├── notebooks/ # 01_eda → 09_evaluation | |
| ├── api/ # FastAPI backend + Gradio | |
| │ ├── main.py | |
| │ ├── schemas.py | |
| │ ├── model_registry.py | |
| │ ├── gradio_app.py | |
| │ └── routers/ | |
| ├── frontend/ # Vite + React + Three.js | |
| │ └── src/components/ # Dashboard, 3D viz, Predict, etc. | |
| ├── docs/ # Documentation | |
| ├── artifacts/ # Generated: models, figures, scalers | |
| ├── Dockerfile | |
| ├── requirements.txt | |
| └── README.md | |
| ``` | |
| --- | |
| ## Dataset | |
| **NASA Prognostics Center of Excellence (PCoE) Battery Dataset** | |
| - 30 Li-ion 18650 cells (B0005–B0056, after cleaning) | |
| - 2 678 discharge cycles extracted | |
| - Nominal capacity: 2.0 Ah | |
| - End-of-Life threshold: 1.4 Ah (30% fade) | |
| - Five temperature groups: 4°C, 22°C, 24°C, 43°C, 44°C | |
| - Cycle types: charge, discharge, impedance | |
| - 12 engineered features per cycle (voltage, current, temperature, impedance, duration) | |
| **Reference:** B. Saha and K. Goebel (2007). *Battery Data Set*, NASA Prognostics Data Repository. | |
| --- | |
| ## Models | |
| ### Classical ML | |
| - **Linear:** Ridge, Lasso, ElasticNet | |
| - **Instance-based:** KNN (3 configs) | |
| - **Kernel:** SVR (RBF) | |
| - **Tree ensemble:** Random Forest, **ExtraTrees** *(v2)*, **GradientBoosting** *(v2)*, XGBoost (Optuna HPO), LightGBM (Optuna HPO) | |
| ### Deep Learning | |
| - **LSTM family:** Vanilla, Bidirectional, GRU, Attention LSTM (MC Dropout uncertainty) | |
| - **Transformer:** BatteryGPT (nano decoder-only), TFT (Temporal Fusion) | |
| - **iTransformer:** Vanilla, Physics-Informed (dual-head), Dynamic-Graph | |
| ### Generative | |
| - **VAE-LSTM:** Variational autoencoder with LSTM encoder/decoder, health head, anomaly detection | |
| ### Ensemble | |
| - **Stacking:** Out-of-fold + Ridge meta-learner | |
| - **Weighted Average:** L-BFGS-B optimized weights | |
| --- | |
| ## API Endpoints | |
| | Method | Path | Description | | |
| |--------|------|-------------| | |
| | POST | `/api/predict` | Single-cycle SOH prediction (default: v2 models) | | |
| | POST | `/api/v1/predict` | Predict using v1 models (cross-battery split) | | |
| | POST | `/api/v2/predict` | Predict using v2 models (chrono split, bug-fixed) | | |
| | POST | `/api/predict/ensemble` | Always uses BestEnsemble | | |
| | POST | `/api/predict/batch` | Multi-cycle batch prediction | | |
| | POST | `/api/recommend` | Operational recommendations | | |
| | POST | `/api/v2/recommend` | v2 recommendations (fixed baseline) | | |
| | GET | `/api/models` | List all models with version / R² metadata | | |
| | GET | `/api/v1/models` | List v1 models | | |
| | GET | `/api/v2/models` | List v2 models | | |
| | GET | `/api/models/versions` | Group models by generation (v1 / v2) | | |
| | GET | `/api/dashboard` | Full dashboard data | | |
| | GET | `/api/batteries` | List all batteries | | |
| | GET | `/api/battery/{id}/capacity` | Per-battery capacity curve | | |
| | GET | `/api/figures` | List saved figures (PNG only) | | |
| | GET | `/api/figures/{name}` | Serve a figure | | |
| | GET | `/health` | Liveness probe | | |
| All endpoints are documented interactively at **`/docs`** (Swagger UI) and **`/redoc`**. | |
| --- | |
| ## License | |
| This project is for academic and research purposes. | |
| Dataset: NASA PCoE public domain. | |