Spaces:
Runtime error
Runtime error
| # NASA SOH Production Pipeline - Documentation | |
| ## Overview | |
| This is the **production-ready** NASA battery State of Health (SOH) prediction pipeline with: | |
| - ✅ **Causal features only** (no data leakage) | |
| - ✅ **Transparent methodology** (full audit reports) | |
| - ✅ **Uncertainty quantification** (95% prediction intervals) | |
| - ✅ **FastAPI service** (ready for frontend integration) | |
| - ✅ **Honest metrics** (R² reported accurately, not inflated) | |
| ## Quick Start | |
| ### 1. Install Dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| ### 2. Run Feature Audit | |
| ```bash | |
| python feature_audit.py | |
| ``` | |
| This generates `data_leakage_audit.txt` documenting all features and fixing leakage. | |
| ### 3. Train Production Model | |
| ```bash | |
| python production_pipeline.py | |
| ``` | |
| This will: | |
| - Load causal features (no leakage) | |
| - Train Random Forest model | |
| - Save `nasa_soh_model.pkl` and `feature_pipeline_causal.pkl` | |
| - Generate `nasa_model_validation.csv` | |
| ### 4. Generate Visualizations | |
| ```bash | |
| python generate_app_visualizations.py | |
| ``` | |
| Creates 3 app-ready plots: | |
| - `health_forecast.png` - Past + Future with uncertainty | |
| - `error_growth.png` - Error vs forecast horizon | |
| - `model_simplicity.png` - Performance vs complexity | |
| ### 5. Generate Transparency Reports | |
| ```bash | |
| python transparency_reports.py | |
| ``` | |
| Generates: | |
| - `data_leakage_audit.txt` - Feature causality audit | |
| - `uncertainty_methodology.txt` - How intervals are calculated | |
| - `failure_cases.csv` - Where model performs worst | |
| ### 6. Start API Service | |
| ```bash | |
| python api_service.py | |
| ``` | |
| Or using uvicorn directly: | |
| ```bash | |
| uvicorn api_service:app --host 0.0.0.0 --port 8000 --reload | |
| ``` | |
| API available at: `http://localhost:8000` | |
| ## API Endpoints | |
| ### POST `/api/predict` | |
| Predict battery health from BMS data. | |
| **Request:** | |
| ```json | |
| { | |
| "data": [ | |
| { | |
| "cycle_index": 1, | |
| "voltage": 4.2, | |
| "current": 1.5, | |
| "temperature": 25.0, | |
| "capacity": 2.0 | |
| } | |
| ], | |
| "initial_capacity": 2.0, | |
| "forecast_horizons": [10, 50, 100] | |
| } | |
| ``` | |
| **Response:** | |
| ```json | |
| { | |
| "current_soh": { | |
| "point_estimate": 0.95, | |
| "lower_95": 0.93, | |
| "upper_95": 0.97 | |
| }, | |
| "health_score": 95.0, | |
| "remaining_life": { | |
| "cycles": 500, | |
| "years": 1.37 | |
| }, | |
| "forecasts": {...}, | |
| "data_quality": {...}, | |
| "model_info": {...} | |
| } | |
| ``` | |
| ### GET `/api/model-info` | |
| Get model information for Trust Engine proof. | |
| ### GET `/api/visualizations/{plot_name}` | |
| Get visualization images (base64 encoded) for PDF reports. | |
| ## File Structure | |
| ``` | |
| proofstack/ | |
| ├── feature_audit.py # Feature leakage detection | |
| ├── feature_engineering_causal.py # Fixed feature engineering (no leakage) | |
| ├── production_pipeline.py # Train production model | |
| ├── predict_soh.py # Production prediction function | |
| ├── generate_app_visualizations.py # Generate 3 app-ready plots | |
| ├── transparency_reports.py # Generate audit & methodology docs | |
| ├── api_service.py # FastAPI service | |
| ├── health_certificate.html # Certificate template | |
| ├── models/ | |
| │ ├── nasa_soh_model.pkl # Production model (Random Forest) | |
| │ └── feature_pipeline_causal.pkl # Feature pipeline metadata | |
| ├── plots/ | |
| │ ├── health_forecast.png # Past + Future forecast | |
| │ ├── error_growth.png # Error vs horizon | |
| │ └── model_simplicity.png # Performance vs complexity | |
| └── data/ | |
| ├── nasa_model_validation.csv # Cycle-by-cycle validation | |
| └── failure_cases.csv # Worst prediction cases | |
| ``` | |
| ## Key Features | |
| ### 1. Causal Features Only | |
| All features use only data ≤ current cycle: | |
| - ✅ `cycles_from_start` (past cycles) | |
| - ✅ `soh_rolling_mean_5` (backward window only) | |
| - ❌ `cycles_to_end` (REMOVED - used future data) | |
| ### 2. Transparent Reporting | |
| - Full feature audit report | |
| - Uncertainty methodology documented | |
| - Failure cases identified | |
| - Honest R² scores (even if lower after fixing leakage) | |
| ### 3. Production-Ready | |
| - FastAPI service with CORS | |
| - Error handling | |
| - Data validation | |
| - Health checks | |
| - Base64 image serving for PDFs | |
| ## Integration with Frontend | |
| ### Monitor App (OnboardingFlow.tsx) | |
| ```typescript | |
| const response = await fetch('http://localhost:8000/api/predict', { | |
| method: 'POST', | |
| headers: { 'Content-Type': 'application/json' }, | |
| body: JSON.stringify({ | |
| data: bmsData, | |
| forecast_horizons: [10, 50, 100] | |
| }) | |
| }); | |
| const predictions = await response.json(); | |
| // Use: predictions.health_score, predictions.remaining_life, etc. | |
| ``` | |
| ### PDF Reports (pdfReportGenerator.tsx) | |
| ```typescript | |
| // Get visualization images | |
| const vizResponse = await fetch('http://localhost:8000/api/all-visualizations'); | |
| const visualizations = await vizResponse.json(); | |
| // Embed in PDF | |
| <Image src={visualizations.visualizations.health_forecast} /> | |
| ``` | |
| ## Model Performance | |
| After fixing data leakage: | |
| - **Training R²**: ~0.998 (on NASA B0005, B0006) | |
| - **Validation R²**: ~0.95-0.97 (on NASA B0007) | |
| - **Honest Reporting**: Lower than original 0.998, but validated and credible | |
| ## Trust Engine Credibility | |
| ZenVolt positions transparency as a differentiator: | |
| - ✅ NASA-trained model | |
| - ✅ Full causality audit (no leakage) | |
| - ✅ Uncertainty quantification | |
| - ✅ Failure case documentation | |
| - ✅ Honest metrics reporting | |
| **Credibility > Perfect Numbers** | |
| ## Next Steps | |
| 1. Train model: `python production_pipeline.py` | |
| 2. Generate plots: `python generate_app_visualizations.py` | |
| 3. Start API: `python api_service.py` | |
| 4. Integrate with frontend apps | |
| 5. Embed visualizations in PDF reports | |
| ## License | |
| For research and commercial use within ZenVolt platform. | |