SimbaMunatsi/zimbabwe-retail-forecast

# Zimbabwe Retail Demand Forecasting Platform An end-to-end ML forecasting platform that predicts daily retail sales and explains the forecast using SHAP. Built with XGBoost, FastAPI, Streamlit, Docker, MLflow, and GitHub Actions. ## Business Problem Retailers often rely on spreadsheets and intuition to decide how much stock to order next week. Poor forecasts lead to: * Stockouts * Excess inventory * Lost sales * Higher holding costs This project demonstrates a production-style ML system that predicts store demand and provides explainable drivers behind each forecast. ## Key Results * **Baseline MAE:** 2,422.84 * **XGBoost MAE:** 653.86 * **Forecast improvement:** 73% reduction in error ## Architecture Streamlit UI → FastAPI → XGBoost + SHAP → JSON Response ```text ┌─────────────────────┐ │ Streamlit UI │ │ (Port 8501) │ └──────────┬──────────┘ │ HTTP POST ▼ ┌─────────────────────┐ │ FastAPI Backend │ │ /predict │ │ /health │ └──────────┬──────────┘ │ ┌─────┴─────┐ ▼ ▼ ┌─────────┐ ┌─────────┐ │XGBoost │ │ SHAP │ │Forecast │ │Explain │ └────┬────┘ └────┬────┘ └─────┬─────┘ ▼ ┌─────────────────────┐ │ JSON Response │ │ Forecast + Drivers │ └─────────────────────┘ ``` ## Demo ### Dashboard ### API Documentation ## Tech Stack | Layer | Technology | |---|---| | **Frontend** | Streamlit | | **Backend API** | FastAPI | | **ML Model** | XGBoost | | **Explainability** | SHAP | | **Experiment Tracking** | MLflow | | **Containerization** | Docker + Docker Compose | | **CI/CD** | GitHub Actions | | **Testing** | Pytest | ## Features * Interactive sales forecasting dashboard * Real-time API predictions * SHAP feature attribution * MLflow experiment tracking * Dockerized microservice architecture * Automated CI pipeline ## Quick Start **1. Clone the repository** ```bash git clone github.com cd zimbabwe-retail-forecast ``` **2. Run with Docker** ` …