---
library_name: generic
tags:
  - time-series-forecasting
  - demand-forecasting
  - supply-chain
  - gru
  - lstm
  - lightgbm
  - xgboost
  - random-forest
  - pytorch
  - keras
  - mixture-of-experts
---

# Saudi Supply/Demand Forecasting Models

A collection of trained models and supporting artifacts (scalers, encoders, feature lists, evaluation results) from a supply/demand forecasting and delivery-time-prediction project.

## Repository Structure

This repo mirrors the original local project layout, preserved as-is because many experiment folders share identically-named files (`best_model.pth`, `scaler.joblib`, etc.):

| Folder | Contents |
|---|---|
| `deep_learning_models/` | GRU/LSTM/Mixture-of-Experts forecasters + LightGBM residual model + scalers/stats |
| `deployment_package/` | Packaged deployment artifacts (metadata, scaler, MoE model, residual model) |
| `dl_multi_horizon_cv_out/` | Cross-validated multi-horizon models (4 folds) + fold histories/scalers |
| `dl_multi_horizon_finalized_out/` | Finalized multi-horizon PyTorch model |
| `dl_multi_horizon_finalized_improved_out/` | Improved finalized multi-horizon PyTorch model |
| `dl_multi_horizon_out_safe_v2/` | Keras multi-horizon model variant |
| `dl_multi_horizon_out_safe_v3/` | PyTorch multi-horizon model variant |
| `dl_multi_horizon_rewrite_out/` | Rewritten multi-horizon PyTorch model |
| `eval_results/` | Global and per-SKU RMSE evaluation CSVs |
| `logs/` | Training run logs (TFT run metrics/hparams) |
| `m5_memory_safe/` | Memory-safe M5 top-K model + scaler + feature columns |
| `models/` | Preprocessor artifact |
| `models_and_views/` | Lead-time prediction model (Keras + LightGBM), preprocessing artifacts, train/test views |
| `models_dl/` | Deep multi-task Keras model + preprocessor + results/plots |
| `models_safe/` | PyTorch model checkpoint |
| `moe_eval/` | Mixture-of-Experts evaluation CSVs |
| `plots/` | Evaluation plots (residuals, true vs predicted, worst-SKU RMSE) |
| `pytorch_finalized_fixed/` | Metadata for a finalized PyTorch pipeline |
| `pytorch_models/` | Multi-task PyTorch model |
| `trained_models/` | Classical ML models: LightGBM, XGBoost, Random Forest |

## Loading Models

**PyTorch (`.pth` / `.pt`):**
```python
import torch
model = torch.load("path/to/model.pth", map_location="cpu")
```

**Keras (`.keras` / `.h5`):**
```python
import tensorflow as tf
model = tf.keras.models.load_model("path/to/model.keras")
```

**Scikit-learn / joblib / pickle artifacts:**
```python
import joblib
obj = joblib.load("path/to/artifact.joblib")
```

**LightGBM text models:**
```python
import lightgbm as lgb
model = lgb.Booster(model_file="path/to/model.txt")
```

## Intended Use

Research, experimentation, model comparison, and further development of supply-chain demand/lead-time forecasting pipelines.

## Limitations

Many folders represent iterative experiments (rewrites, safe variants, CV folds) rather than a single canonical model — check `dl_results.json` / `cv_fold_results.json` / `results.json` in each folder for that experiment's metrics before choosing one to deploy. Models should be independently validated before production use.

## License

No standardized open-source license has been specified. Review data provenance and licensing before redistribution or commercial use.