phiri13/retail-inventory-ai

An executable AI system that forecasts product demand for South African retail stores using historical sales data and Prophet time-series models. Built with production automation: Docker, FastAPI inference API, rate limiting, error handling, and disk-based model registry. Extensible foundation for SA-specific features # RetailAI-ZA > API for retail inventory forecasting using Prophet time-series models ## Overview Production-ready API for forecasting retail product demand across multiple stores. Built with FastAPI, Prophet, and containerized for cloud deployment. **Key Features:** - RESTful API with versioned endpoints (`/v1/`) - Prophet time-series forecasting engine - Disk-based model registry with metadata tracking - Docker containerization for reproducible deployments - OpenAPI/Swagger documentation ## Quick Start ### Using Docker (Recommended) ```bash # Build and start the API docker-compose up --build # API available at localhost # Docs at localhost ``` ### Local Development ```bash # Install dependencies pip install -r requirements.txt # Start the API python -m uvicorn api.main:app --reload --app-dir src # Access at localhost ``` ## API Endpoints ### Health Check ```bash GET /v1/health ``` ### Generate Forecast ```bash POST /v1/forecast Content-Type: application/json { "store_id": "default", "product_id": "generic", "days": 30 } ``` **Response:** ```json { "store_id": "default", "product_id": "generic", "horizon_days": 30, "forecasts": [ {"date": "2026-01-06", "forecast": 185.4}, {"date": "2026-01-13", "forecast": 192.1}, ... ] } ``` ## Architecture ``` retail-inventory-ai/ ├── src/ │ ├── api/ │ │ ├── main.py # FastAPI app │ │ ├── schemas.py # Pydantic models │ │ └── v1/ │ │ ├── health.py # Health endpoint │ │ └── forecast.py # Forecast endpoint │ └── models/ │ ├── registry/ # Model storage │ ├── load_model.py # Model loader │ └── train_prophet.py # Training script ├── data/ │ └── raw/ # Training data ├── Dockerfile # Container definition ├── docker-compose.yml # Local orchestration └── requirements.txt # Python dependencies ``` ## Model …