SupplyChain-JEPA

SupplyChain-JEPA is a predictive world model for structured supply-chain data. It maps partially observed entity-time tokens into latent operational states and predicts both hidden/future state representations and action-conditioned future representations.

This repository contains the selected pretrained model release. Downstream task heads and task-specific adaptations are intentionally kept separate from the shared pretrained weights.

Architecture

The release follows one continuous weight chain:

1. a context encoder for visible operational history;
2. a stop-gradient target encoder defining latent prediction targets;
3. a lightweight State predictor for hidden or future operational state;
4. an action-conditioned Dynamics predictor for counterfactual future state;
5. optional semantic-state and grounding heads.

The core contains 73,629,696 parameters. The context encoder width is 384 with six Transformer layers. Inputs use a unified entity-time token schema spanning numerical values, categorical values, observation status, time, entity roles, and local topology indices.

Files

• model.safetensors: encoder chain plus State and Dynamics predictors.
• state_auxiliary.safetensors: pooled-state, semantic-state, and grounding heads.
• config.json: architecture and component configuration.
• tensorizer.json: fitted feature and vocabulary mapping.
• schema.json: canonical tensor interface.
• normalization.json: numerical normalization statistics.
• modeling_supplychain_jepa.py: model definition.
• load_model.py: strict loader with checksum verification.
• CHECKSUMS.sha256: release-file integrity manifest.

Loading

from huggingface_hub import snapshot_download

snapshot = snapshot_download(
    repo_id="htizhang/SupplyChain-JEPA",
    revision="<immutable-commit-sha>",
)

import sys
sys.path.insert(0, snapshot)
from load_model import load_supplychain_jepa

bundle = load_supplychain_jepa(snapshot)
model = bundle["model"]
state_predictor = model.state_predictor
dynamics_predictor = model.dynamics_predictor
state_pool_predictor = bundle["state_pool_predictor"]

Always pin an immutable repository commit when using the model in an experiment.

Intended use

The model is intended for research on partially observed supply-chain state estimation, demand recovery, operational risk ranking, action evaluation, and optimization-support systems. Dataset-specific adapters are required to map raw records into the canonical token schema.

Limitations

This is a research model rather than a production decision system. It does not enforce feasibility, inventory balance, service constraints, or safety policies by itself. Operational deployment should place explicit constraints and an optimization or control layer around model predictions.