README.md

---
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.