HemasSCRG — GNN-Based Supply Chain Risk Graph System

Team Dream4 | University of Moratuwa | AITHON 2026
Target SBU: Atlas Axilia | Hemas Consumer Brands

---

Overview

HemasSCRG models the entire Hemas supply chain as a dynamic heterogeneous knowledge graph and applies a Relational Graph Convolutional Network (R-GCN) to predict cascade failures 7–28 days before they occur.

Three Committed Features (Grand Finale)

Feature	Description
F1	Interactive Supply Chain Risk Graph Dashboard — live colour-coded nodes (green → amber → red)
F2	Cascade Disruption Simulator (What-If Engine) — select any node, trigger a disruption, visualise downstream cascade
F3	28-Day Risk Forecast Panel — temporal risk trajectory with seasonal adjustments and alert thresholds

---

Prerequisites

• Python 3.10+ (3.11 recommended)
• pip and ideally a virtual environment
• 4 GB RAM minimum (CPU training is fine — takes ~2 min)
• GPU optional (CUDA supported automatically)

---

Setup from Scratch

Step 1 — Clone / Create project directory

# If from zip:
unzip hemas_scrg.zip && cd hemas_scrg

# Or if you already have the folder:
cd hemas_scrg

Step 2 — Create a virtual environment (recommended)

python -m venv venv

# Activate on macOS/Linux:
source venv/bin/activate

# Activate on Windows:
venv\Scripts\activate

Step 3 — Install PyTorch (CPU)

# CPU-only (recommended for demo)
pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cpu

If you have CUDA 11.8:

pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cu118

Step 4 — Install PyTorch Geometric

pip install torch-scatter torch-sparse torch-cluster torch-spline-conv \
    -f https://data.pyg.org/whl/torch-2.1.0+cpu.html

pip install torch-geometric==2.4.0

Note: If the above fails, use the simplified fallback (see Troubleshooting section).

Step 5 — Install remaining dependencies

pip install -r requirements.txt

Step 6 — Generate Data & Train Model

python train.py

This will:

1. Generate 10,000+ synthetic supply chain records across 6 node types
2. Build the heterogeneous PyG graph (40 suppliers, 120 SKUs, 8 warehouses, 25 distributors, 200 retailers, 15 external events)
3. Train the R-GCN for 150 epochs (~2 minutes on CPU)
4. Save the model to models/
5. Print a validation summary

Step 7 — Launch the Dashboard

streamlit run frontend/app.py

Open your browser at http://localhost:8501

(Optional) Step 8 — Launch the REST API

uvicorn backend.api:app --reload --host 0.0.0.0 --port 8000

API docs at http://localhost:8000/docs

---

Project Structure

hemas_scrg/
├── data/
│   ├── generate_data.py      ← Synthetic dataset generator (10k transactions)
│   ├── suppliers.csv         ← Generated: 40 suppliers
│   ├── skus.csv              ← Generated: 120 SKUs
│   ├── warehouses.csv        ← Generated: 8 warehouses/DCs
│   ├── distributors.csv      ← Generated: 25 distributors
│   ├── retailers.csv         ← Generated: 200 retailers
│   ├── external_events.csv   ← Generated: 15 external risk events
│   ├── transactions.csv      ← Generated: 10,000 transactions
│   └── edges.json            ← Generated: graph edge definitions
│
├── models/
│   ├── rgcn_model.py         ← R-GCN model + Graph builder + Inference engine
│   ├── rgcn_model.pt         ← Saved model weights (after training)
│   └── graph.pt              ← Saved PyG graph (after training)
│
├── frontend/
│   └── app.py                ← Streamlit dashboard (F1, F2, F3)
│
├── backend/
│   └── api.py                ← FastAPI REST API
│
├── train.py                  ← Training entrypoint
├── requirements.txt          ← Python dependencies
└── README.md

---

Graph Schema

Node Types & Features

Node Type	Count	Key Features
Supplier	40	lead_time, reliability_score, capacity, late_delivery_rate
SKU/Product	120	demand_velocity, unit_price, margin, shelf_life
Warehouse/DC	8	stock_level, utilisation, throughput, capacity
Distributor	25	delivery_sla, order_frequency, coverage_area
Retailer	200	sales_velocity, channel_type, region
External Risk	15	severity, risk_impact, event_type

Edge Relations (5 types)

Supplier ──[produces]──► SKU
SKU ──[stored_at]──► Warehouse
Warehouse ──[dispatches_to]──► Distributor
Distributor ──[delivers_to]──► Retailer
External ──[impacts]──► Supplier

---

R-GCN Architecture

Input Node Features (per type)
         │
   Linear Projection → hidden_dim=64
         │
   HeteroConv Layer 1 (SAGEConv + LayerNorm + Residual)
         │
   HeteroConv Layer 2 (SAGEConv + LayerNorm + Residual)
         │
   HeteroConv Layer 3 (SAGEConv + LayerNorm + Residual)
         │
   Risk Head: Linear(64→32) → ReLU → Dropout(0.2) → Linear(32→1) → Sigmoid
         │
   Risk Score ∈ [0, 1]

---

API Endpoints

Method	Endpoint	Description
GET	/nodes	All nodes with risk scores (filterable)
GET	/nodes/{node_id}	Single node detail
GET	/graph/summary	Risk summary by node type
GET	/graph/edges	Graph edge list
POST	/simulate/cascade	Run What-If cascade simulation
POST	/forecast	28-day risk forecast
GET	/alerts	Nodes above risk threshold
GET	/network/health	Overall network health

---

Troubleshooting

PyTorch Geometric install fails

Use the fallback lightweight mode — replace the imports in models/rgcn_model.py:

pip install torch-geometric --no-deps
pip install torch-scatter torch-sparse --no-build-isolation

Or use the simpler pip install:

pip install pyg-lib -f https://data.pyg.org/whl/torch-2.1.0+cpu.html

"No module named torch_geometric"

pip install torch_geometric
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv \
    -f https://data.pyg.org/whl/torch-2.1.0+cpu.html

Streamlit won't launch

pip install --upgrade streamlit
streamlit run frontend/app.py --server.port 8502

Out of memory on training

Reduce the dataset size in data/generate_data.py:

N_RETAILERS = 100  # from 200
N_TRANSACTIONS = 5000  # from 10000

---

Retrain from scratch

python train.py --retrain --epochs 200

---

Tech Stack

Layer	Technology
GNN Framework	PyTorch Geometric (PyG) — R-GCN/HeteroConv
Graph Construction	NetworkX, PyG HeteroData
Data Processing	Python, Pandas, NumPy, scikit-learn
Backend API	FastAPI + Uvicorn
Dashboard	Streamlit + Plotly
Version Control	Git / GitHub

---

HemasSCRG — Team Dream4 · AITHON 2026 · University of Moratuwa