Retail Sales Forecasting

This project builds a retail demand forecasting workflow for weekly store sales and inventory planning. It uses synthetic Walmart-style data, trains a demand model, evaluates forecast errors, and converts those predictions into stock guidance for replenishment decisions.

Goals

• Forecast weekly sales by store
• Capture seasonality, promotions, and holiday demand effects
• Measure performance with RMSE, MAE, and R2
• Recommend inventory actions such as reorder or hold

Project structure

• src/data.py — synthetic generator and real retail transaction-to-weekly converter
• src/train.py — feature engineering and forecasting model
• src/inventory.py — inventory recommendation logic
• app.py — Streamlit dashboard
• tests/test_forecast.py — regression tests
• requirements.txt — Python dependencies
• real_retail_sales.csv — public supermarket transaction data used by the real-data demo mode

Setup

python -m pip install -r requirements.txt

Run the dashboard

.\.venv\Scripts\Activate.ps1
streamlit run app.py

Run tests

.\.venv\Scripts\Activate.ps1
pytest -q

Example workflow

1. Select real retail data, synthetic data, or upload your own CSV.
2. Build features such as promotion flag, inventory on hand, holiday effects, and previous sales.
3. Train a weekly sales model and evaluate error metrics.
4. Translate predicted demand into recommended stock and reorder actions.
5. Use the dashboard to monitor store planning decisions.

Real dataset source

The real-data demo uses the public supermarket sales transaction dataset published in the MohammedShehbazDamkar/Walmart-Sales-Data-Analysis--SQL-Project GitHub repository. The transaction records are aggregated by branch and week before forecasting. Inventory is an estimated planning field derived from weekly sales because the source dataset does not include stock-on-hand records.