Event-Aware and Explainable Demand Forecasting System for Voltacore

This project is a comprehensive demand forecasting system for lithium EV batteries, integrating historical sales data with real-time news sentiment analysis to adjust forecasts dynamically.

🚀 Features

• Data Ingestion: Automatically loads and validates Excel sales data.
• Feature Engineering: Creates lags, rolling means, and time-based features.
• Forecast Engine: XGBoost Regressor with rigorous evaluation (MAE, RMSE, MAPE).
• Real-Time Adjustment: Fetches news via NewsAPI, computes sentiment with VADER, and adjusts forecasts based on global events (war, supply chain, etc.).
• Explainability: SHAP summary plots to explain model decisions.
• Sustainability (Green Score): Evaluates supply chain efficiency based on transport distance, fuel price, and inventory management.
• Interactive Dashboard: Streamlit-based UI for easy interaction.

📂 Structure

• app.py: Main Streamlit application.
• data_loader.py: Handles data loading and cleaning.
• feature_engineering.py: Generates ML features.
• forecast_model.py: XGBoost model wrapper.
• event_module.py: News fetching and sentiment analysis.
• explainability.py: SHAP visualizations.
• green_score.py: Logic for sustainability scoring.
• generate_mock_data.py: Script to generate sample data.
• frontend/: React + Vite frontend application providing a modern UI.

🛠 Setup & Run

🖥️ Backend (Streamlit & Python Engine)

1. Install Dependencies:

   pip install -r requirements.txt

2. Generate Data (Optional if you have your own file):

   python generate_mock_data.py

   This creates Voltacore_EV_Battery_Demo_Data.xlsx.

3. Run Application:

   streamlit run app.py

   (Note: On Windows, you can alternatively run the run.bat script to automate backend setup and startup).

4. NewsAPI Key:

   • Get a free API key from newsapi.org.
   • Enter it in the sidebar when running the app.

🎨 Frontend (React + Vite UI)

A modern web interface has been added to interact with the project more seamlessly.

1. Navigate to the frontend directory:

   cd frontend

2. Install Node dependencies:

   npm install

3. Start the development server:

   npm run dev

   This will start the UI development server (typically available at http://localhost:5173).

📊 Usage

1. Upload the excel file.
2. Click "Train Model".
3. Adjust "Next Week" parameters (Price, Holiday, Promo).
4. Click "Generate Forecast".
5. View the Base Forecast, Event-Adjusted Forecast, and Explanations.