Revise README for HorloML Supply Chain Web App

# Supply Chain Simulation - Watch Industry

# HorloML Supply Chain Forecasting Web App

A comprehensive supply chain simulation for the watch industry, implementing demand forecasting, supply planning, assembly, distribution, and customer behavior modeling.

An educational web application for teaching supply chain forecasting and demand planning, featuring AI-assisted predictions using zero-shot time series models.

## Installation

## Documentation

1. Clone or download the project files

2. Install in development mode:

- [Technical Report: Zero-Shot Forecasting Evaluation](./raport/medium_report.pdf)

- [Simulation System Documentation](./raport/sim.pdf)

```bash

pip install -e .

```

## Overview

Students analyze 10 years of historical sales data for 3 watch models and predict demand for Year 11. The app evaluates their predictions, shows the financial impact of forecasting errors, and optionally compares results against an AI model (TiRex).

Or install dependencies directly:

## Features

- **Historical Data Analysis**: View and analyze 10 years of monthly sales data

- **Excel Export**: Download historical data as Excel spreadsheet for offline analysis

- **Demand Forecasting**: Predict monthly demand for year 11 (12 months × 3 watches)

- **Financial Impact**: See how prediction errors affect revenue, costs, and profit

- **AI Comparison**: Compare student predictions against TiRex zero-shot model (teacher-controlled)

- **Performance Scoring**: Get accuracy metrics (MAPE, overall accuracy)

## Installation

### Option 1: Local Installation

```bash

# Create and activate virtual environment

python -m venv venv

source venv/bin/activate  # Linux/Mac

# or: venv\Scripts\activate  # Windows

# Install dependencies

pip install -r requirements.txt

```

## Project Structure

# Generate the dataset

python smart_data_generator.py

```

supply_chain_sim/

├── __init__.py              # Package initialization

├── entities.py              # Data models (Brand, Supplier, Customer, etc.)

├── synthetic_setup.py       # Generate synthetic entities

├── forecasting.py           # Demand forecasting with ML

├── supply_order.py          # Supply order logic and planning

├── event_injection.py       # Internal/external event management

├── assembly.py              # Component flow and watch assembly

├── distribution.py          # Retail distribution logic

├── customer_behavior.py     # Customer purchase simulation

├── model_update.py          # AI model updates and tracking

├── research_logging.py      # KPI tracking and reporting

└── simulation.py            # Main simulation orchestrator

# Run the web app

python app.py

```

## Usage

### Basic Run

The app will be available at `http://localhost:5001`

### Option 2: Docker

```bash

python run_simulation.py

# Generate data first (required before building)

python smart_data_generator.py

# Run with Docker Compose

docker compose up -d

```

### With Custom Parameters

The app will be available at `http://localhost:52999`

```bash

python run_simulation.py --days 60 --customers 1000 --retailers 10 --seed 123

```

## Watch Models

### Command Line Options

- `--days`: Number of simulation days (default: 30)

- `--customers`: Number of customers (default: 500)

- `--retailers`: Number of retailers (default: 6)

- `--seed`: Random seed for reproducibility (default: 42)

- `--debug`: Enable debug logging

### Programmatic Usage

```python

from supply_chain_sim import run_oneshot_simulation

# Custom configuration

config = {

    'seed': 42,

    'n_brands': 2,

    'n_suppliers': 5,

    'n_components': 15,

    'n_watches': 8,

    'n_warehouses': 2,

    'n_retailers': 6,

    'n_customers': 500,

    'simulation_days': 30,

    'timestep_days': 1

}

# Run simulation

simulation = run_oneshot_simulation(config)

```

| Model | Category | Price | Peak Season |

|-------|----------|-------|-------------|

| Luxury Classic | luxury | CHF 500 | Nov-Jan (holidays) |

| Sport Pro | sport | CHF 220 | Apr-Jul (summer) |

| Casual Style | casual | CHF 120 | Sep-Oct (back-to-school) |

## Educational Workflow

## Key Features

1. **Synthetic Entity Generation**: Creates brands, suppliers, customers, watches with realistic distributions

2. **Demand Forecasting**: ML-based demand prediction with uncertainty intervals

3. **Supply Planning**: Intelligent component ordering based on forecasts and inventory

4. **Event System**: Internal campaigns and external market events

5. **Assembly Simulation**: Component delivery delays and watch assembly with capacity constraints

6. **Distribution Logic**: Regional demand-based distribution to retailers

7. **Customer Behavior**: Purchase probability based on preferences, budget, and brand awareness

8. **Performance Tracking**: GMROI, fill rate, forecast accuracy, and other KPIs

9. **Research Logging**: Comprehensive reporting and baseline comparisons

## Simulation Flow

The simulation follows a linear flow as designed:

1. **Initialization**: Generate all entities

2. **Forecasting**: Predict demand using ML models

3. **Supply Planning**: Generate component orders

4. **Event Management**: Apply campaigns and market events

5. **Assembly**: Process deliveries and assemble watches

6. **Distribution**: Allocate watches to retailers

7. **Customer Simulation**: Process purchases and returns

8. **Model Updates**: Train AI models with new data

9. **KPI Tracking**: Log performance metrics

## Output

The simulation provides:

- Real-time progress updates for each timestep

- KPI tracking (GMROI, fill rate, conversion rate, forecast accuracy)

- Final comprehensive report with:

  - Model performance metrics

  - Average and final KPIs

  - Revenue and cost analysis

  - Comparison against baselines (if set)

## Notes

- Pygame rendering is prepared for future implementation

- Logging can be controlled via the --debug flag

- All random processes use seeds for reproducibility

- The simulation is designed to be modular and extensible

 No newline at end of file

1. **Home Page**: Students learn about the forecasting challenge

2. **Historical Data**: Analyze 10 years of sales patterns, download Excel for detailed analysis

3. **Make Predictions**: Enter demand forecasts for year 11 (paste from Excel supported)

4. **View Results**: See comparison with actual demand and financial impact

### Teacher Controls

The AI prediction feature is password-protected. Teachers can toggle AI access using the "Activate AI" button in the navbar. When enabled, students can use the "Fill with AI Model" button to see TiRex predictions and compare against their own forecasts.

Default password: `HorloML-AI` (configurable via `AI_PASSWORD` environment variable)

## ML Forecasting Evaluation

Multiple forecasting strategies were evaluated on the simulated data:

| Strategy | MAE | RMSE | MAPE % |

|----------|-----|------|--------|

| **TiRex** | **24.89** | 33.39 | **3.05** |

| Prophet | 25.58 | **32.30** | 3.35 |

| Ensemble | 26.78 | 36.36 | 3.30 |

| AR(12) | 27.67 | 37.52 | 3.51 |

| Trend | 30.78 | 39.34 | 4.06 |

| Naive | 42.67 | 55.21 | 5.24 |

TiRex, a zero-shot foundation model pre-trained on 47.5M time series, achieves competitive performance without any fine-tuning on the simulation data.

![Forecast Strategy Comparison](./raport/source/forecast_comparison.png)

## Data Generation

The `smart_data_generator.py` script creates realistic demand through customer behavior simulation:

- **160,000 simulated customers** across 3 segments (luxury buyers, sport enthusiasts, casual shoppers)

- **Bottom-up demand**: Aggregate demand emerges from individual purchase decisions

- **Emergent patterns**: Trend, seasonality, and variance arise naturally from behavioral parameters

See the [simulation documentation](./raport/sim.pdf) for details.

## File Structure

```

forecast_app/

├── app.py                 # Flask web application

├── smart_data_generator.py # Customer behavior simulation

├── data_generator.py      # Alternative simple generator

├── requirements.txt       # Python dependencies

├── Dockerfile

├── docker-compose.yml

├── data/                  # Generated datasets

└── templates/             # HTML templates

```