Spinneys-Egypt/Recommendation-Engine

# 🛒 Spinneys Egypt - AI-Powered Ordering Recommendation System **Complete end-to-end demand forecasting and intelligent ordering system built with production-grade architecture.** --- ## 📋 Table of Contents - Overview - Features - Architecture - Tech Stack - Project Structure - Installation - Quick Start - Usage Guide - API Documentation - ML Pipeline - Deployment - Contributing --- ## 🎯 Overview The Spinneys Ordering Recommendation System is a comprehensive AI-powered solution that: - Forecasts demand per item per store using gradient boosting models - Generates intelligent order recommendations based on forecasts and current stock - Provides a modern web interface for supply chain planners - Supports weekly automated retraining with model versioning - Handles Egyptian market-specific features (holidays, Ramadan, etc.) **Business Value:** - Reduce stockouts and overstock situations - Optimize inventory levels - Improve forecast accuracy - Enable data-driven ordering decisions - Track and analyze planner overrides --- ## ✨ Features ### 🤖 Machine Learning - **Advanced Forecasting**: CatBoost/LightGBM models with 47+ engineered features - **Model Registry**: Version tracking, metrics logging, automated promotion - **Weekly Retraining**: Automated pipeline with performance comparison - **Feature Engineering**: Lag features, rolling statistics, promotions, seasonality - **Parquet Format**: High-performance data storage (10-100x faster than CSV) ### 📊 Analytics & Recommendations - **7-Day Forecasts**: Store-item level demand predictions - **Smart Ordering**: Automated order quantity recommendations - **Priority System**: URGENT/HIGH/NORMAL prioritization - **Safety Stock**: Configurable multipliers and business rules ### 🎨 User Interface - **Modern Dashboard**: KPIs, system status, real-time insights - **Recommendations Grid**: Searchable, filterable, exportable table - **Item Details**: Forecast visualization, historical trends - **Override Management* …