🏆 MobAI’26 — Demand Forecasting + Warehouse Optimization

Ranked 1st place in MobAI’26 with a full AI system solving:

• Demand forecasting for 1129 SKUs
• Warehouse storage optimization
• Smart picking route planning

Built with Prophet, XGBoost, and FastAPI. Deployed on a cloud VM with interactive API.

MobAI'26 — AI Submission

Team: Aziba Mohammed Ayoub
GitHub: https://github.com/Azjob21/mobai-api
Live API: http://4.251.194.25:8000

---

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Task 2 — Demand Forecasting (Inference)

# Default: Forecast 10 days from 2026-02-15 for all 1129 products
python task2_forecasting/inference_forecast.py \
  --start_date 2026-02-15 --end_date 2026-02-24 \
  --output forecast_submission.csv

# Or provide historical data (optional — uses saved models)
python task2_forecasting/inference_forecast.py \
  --input data/sample_test_forecast.csv --output forecast_submission.csv

Output format:

Date,id_produit,quantite_demande
15-02-2026,31554,48.00
15-02-2026,31565,35.00

3. Task 1 — Warehouse Optimization (Inference)

python task1_optimization/inference_optimization.py \
  --input data/sample_test_optimization.csv \
  --output optimization_results.csv

Output format:

Product,Action,Location,Route,Reason
31554,Storage,0H-01-02,Reception -> Zone Picking B7 -> 0H-01-02,Segment=HF; High freq; Min distance
31565,Picking,0X-05-03,0X-05-03 -> Zone Picking B7 -> Expedition,High demand product; Freq=0.1580

4. Live API

uvicorn api/main:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 for the interactive API tester (12 endpoints).

---

Folder Structure

submission/
├── README.md                          ← This file
├── requirements.txt                   ← Python dependencies
├── technical_report.md                ← Technical report (6 pages)
│
├── task1_optimization/                ← TASK 1: Warehouse Optimization
│   ├── training_notebook_task1.ipynb  ← Training notebook
│   └── inference_optimization.py     ← Inference script (standalone)
│
├── task2_forecasting/                 ← TASK 2: Demand Forecasting
│   ├── training_notebook_task2.ipynb  ← Training notebook
│   ├── inference_forecast.py         ← Inference script (standalone)
│   └── holidays_dz.py               ← Algerian/Islamic holiday module
│
├── api/                              ← Full FastAPI Application
│   ├── main.py                       ← API server (12 endpoints)
│   ├── holidays_dz.py               ← Holiday features module
│   ├── index.html                    ← Interactive API tester UI
│   └── test_api.py                   ← Test suite (11/11 pass)
│
├── models/                           ← Saved Models (~3 MB total)
│   ├── xgboost_classifier_model.json ← XGBoost classifier (AUC=0.9389)
│   ├── xgboost_regression_model.json ← XGBoost regressor
│   ├── xgboost_lf_regressor_model.json
│   ├── prophet_meta.json            ← Prophet per-SKU metadata (571 products)
│   ├── forecast_config.json         ← Hyperparameters & performance metrics
│   ├── product_attributes.json      ← Physical product attributes
│   ├── delivery_stats.json          ← Transaction-derived features
│   └── cat_encoding.json            ← Category encoding map
│
└── data/                            ← Data Files
    ├── product_priorities.csv       ← Priority scores (1129 products)
    ├── product_segments.csv         ← HF/LF segments (233 HF, 896 LF)
    ├── warehouse_locations.csv      ← 837 warehouse slots
    ├── sample_test_optimization.csv ← Sample test data (Task 1)
    └── sample_test_forecast.csv     ← Sample test data (Task 2)

---

Models

All models are under 3 MB total and included directly in the models/ folder.

Model	File	Size	Metric
XGBoost Classifier	xgboost_classifier_model.json	1.66 MB	AUC = 0.9389
XGBoost Regressor	xgboost_regression_model.json	0.91 MB	Demand-days MAE
Prophet Metadata	prophet_meta.json	0.15 MB	571 SKUs fitted

---

Expected Runtime

Task	Operation	Time
Task 2	Inference (1 day × 1129 products)	~30 seconds
Task 2	Inference (10 days × 1129 products)	~5 minutes
Task 1	Inference (18 events, sample)	< 1 second
Task 1	Inference (1000 events)	~5 seconds

Hardware tested: Azure VM Standard B2s (2 vCPUs, 4 GB RAM), Python 3.12

---

API Endpoints (12 total)

Method	Path	Description
GET	/	Interactive API tester (HTML)
GET	/health	Health check, model status, warehouse occupancy
GET	/model-info	Full model documentation
GET	/warehouse-state	Current warehouse slot status
GET	/download/{filename}	Download generated CSV files
POST	/predict	Forecast demand (1+ products, 1 date)
POST	/generate-forecast	Full CSV forecast generation
POST	/explain	XAI: feature importances, model components
POST	/assign-storage	Smart storage assignment
POST	/optimize-picking	Picking route optimization
POST	/simulate	Chronological warehouse simulation
POST	/preparation-order	Daily preparation order generation
POST	/reset-warehouse	Reset warehouse state

---

Dependencies

• Python 3.10+
• fastapi, uvicorn, pydantic
• pandas, numpy, xgboost, scikit-learn
• prophet (for retraining only)
• openpyxl (for reading training data)

All listed in requirements.txt.