PR 2 — Portable Public End-to-End Validation Fixture

docs/configuration.md

@@ -76,6 +76,37 @@ selection and must be disjoint. Model/task mismatches are rejected during
 config validation; binary tasks require `model.out_size=1`, while multiclass
 tasks require `model.out_size=task.num_classes`.
 
+## Hugging Face ROOT data
+
+Training preparation can resolve ROOT files directly from a pinned Hugging Face
+dataset. Use `data.source` instead of local `data.files`:
+
+```yaml
+source:
+  type: huggingface
+  repo_id: HWresearch/Delphes
+  repo_type: dataset
+  revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
+  files:
+    - path: testing/ttH_NLO_64.root
+      label: 0
+      sha256: 89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
+      size_bytes: 15050
+```
+
+The resolver uses the Hugging Face cache, downloads only configured files, and
+verifies optional size and SHA-256 metadata before ROOT ingestion. Ready-to-use
+configurations are `config_hf_smoke` for the 64-event fixture and
+`config_hf_delphes` for the pinned 12-process pretraining sources:
+
+```bash
+uv run gnn4colliders prepare --config-name config_hf_smoke
+uv run gnn4colliders prepare --config-name config_hf_delphes
+```
+
+The full Delphes configuration may download a large dataset. It is never used
+by the default configuration and is cached by the Hub client for later runs.
+
 ## Checkpoints and resolved configuration
 
 Training writes `epoch_####.pt` and the fully resolved configuration at

docs/end_to_end_validation.md

@@ -16,6 +16,15 @@ The captured runtime versions and seed policy are recorded in
 `validation/manifests/environments.json`; the HF composite fixture provenance
 is recorded in `validation/manifests/multiclass_fixture.json`.
 
+For the portable public regression, run:
+
+```bash
+uv run python -m validation.run_public_validation
+```
+
+This downloads or verifies the pinned `HWresearch/Delphes` 64-event fixture
+and compares the current rewrite against the checked-in legacy golden output.
+
 Strict parity applies to preprocessing, topology, fixed forward, loss, and
 one-step CPU updates. Multi-epoch, GPU and DDP comparisons are scientific:
 compare curves, metrics, distributions and event-level correlations. Named

pyproject.toml

@@ -11,6 +11,7 @@ requires-python = ">=3.12,<3.13"
 dependencies = [
     "awkward>=2.0",
     "hydra-core>=1.3",
+    "huggingface-hub>=0.36,<1",
     "numpy>=1.24,<2",
     "scikit-learn>=1.3",
     "torch==2.2.2",

src/gnn4colliders/cli/__init__.py

@@ -26,7 +26,7 @@ def _is_main_process() -> bool:
 
 def _help(command: str | None = None) -> None:
     if command:
-        print(f"Usage: gnn4colliders {command} [key=value ...]")
+        print(f"Usage: gnn4colliders {command} [--config-name NAME] [key=value ...]")
         print("Compose Hydra configuration with semantic overrides.")
     else:
         print(
@@ -36,11 +36,36 @@ def _help(command: str | None = None) -> None:
         print("Use gnn4colliders <command> --help for command help.")
 
 
-def _config(overrides: list[str]):
+def _config(overrides: list[str], *, config_name: str = "config"):
     config_resource = resources.files("gnn4colliders.configs")
     with resources.as_file(config_resource) as config_dir:
         with initialize_config_dir(version_base=None, config_dir=str(config_dir)):
-            return compose(config_name="config", overrides=overrides)
+            return compose(config_name=config_name, overrides=overrides)
+
+
+def _config_name(args: list[str]) -> tuple[str, list[str]]:
+    """Extract the optional config name while preserving Hydra overrides."""
+
+    remaining: list[str] = []
+    config_name = "config"
+    index = 0
+    while index < len(args):
+        argument = args[index]
+        if argument == "--config-name":
+            if index + 1 >= len(args):
+                raise ValueError("--config-name requires a config name")
+            config_name = args[index + 1]
+            index += 2
+            continue
+        if argument.startswith("--config-name="):
+            config_name = argument.split("=", 1)[1]
+            if not config_name:
+                raise ValueError("--config-name requires a config name")
+            index += 1
+            continue
+        remaining.append(argument)
+        index += 1
+    return config_name, remaining
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -59,7 +84,8 @@ def main(argv: list[str] | None = None) -> int:
         _help(command)
         return 0
     try:
-        config = _config(args)
+        config_name, overrides = _config_name(args)
+        config = _config(overrides, config_name=config_name)
         logging.basicConfig(
             level=getattr(logging, str(config.logging.level).upper(), logging.INFO)
         )

src/gnn4colliders/config/application.py

@@ -18,6 +18,7 @@ from gnn4colliders.data import (
     GraphSampleCache,
     RootEventDataset,
     SplitDefinition,
+    resolve_data_files,
     select_split,
 )
 from gnn4colliders.distributed import (
@@ -108,8 +109,7 @@ def prepare(config: DictConfig) -> Path:
             "prepare does not support distributed launch; run it once on rank 0"
         )
     data = config.data
-    if not data.files:
-        raise ValueError("prepare requires data.files")
+    files, labels = resolve_data_files(data)
     feature_branches = plain(data.get("feature_branches"))
     object_types = plain(data.get("object_types"))
     scales = plain(data.get("scales"))
@@ -118,9 +118,9 @@ def prepare(config: DictConfig) -> Path:
             "prepare requires data.feature_branches, object_types, and scales"
         )
     source = RootEventDataset(
-        data.files,
+        files,
         tree_name=str(data.tree_name),
-        label=data.get("label", 1),
+        label=labels,
         feature_branches=feature_branches,
         global_features=plain(data.get("global_features", [])),
         fold_var=str(data.get("fold_var", "eventNumber")),

src/gnn4colliders/configs/config_hf_delphes.yaml

@@ -0,0 +1,16 @@
+defaults:
+  - data: hf_delphes
+  - model: root_gnn/edge_network
+  - task: pretraining_multiclass
+  - trainer: default
+  - checkpoint: default
+  - inference: default
+  - environment: local
+  - distributed: single
+  - export: onnx
+  - _self_
+
+experiment:
+  name: hf_delphes_pretraining
+logging:
+  level: INFO

src/gnn4colliders/configs/config_hf_smoke.yaml

@@ -0,0 +1,16 @@
+defaults:
+  - data: hf_smoke
+  - model: root_gnn/edge_network_binary
+  - task: binary_classification
+  - trainer: debug
+  - checkpoint: default
+  - inference: default
+  - environment: local
+  - distributed: single
+  - export: onnx
+  - _self_
+
+experiment:
+  name: hf_smoke
+logging:
+  level: INFO

src/gnn4colliders/configs/data/hf_delphes.yaml

@@ -0,0 +1,46 @@
+defaults:
+  - _self_
+
+source:
+  type: huggingface
+  repo_id: HWresearch/Delphes
+  repo_type: dataset
+  revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
+  cache_dir: null
+  files:
+    - {path: samples/higgs/top-associated/tth/ttH_NLO_inc.root, label: 0}
+    - {path: samples/higgs/top-associated/thjb/tHjb_NLO_inc.root, label: 1}
+    - {path: samples/higgs/ggf/ggF_NLO_inc.root, label: 2}
+    - {path: samples/higgs/vbf/VBF_NLO_inc.root, label: 3}
+    - {path: samples/higgs/vh/wh/WH_NLO_inc.root, label: 4}
+    - {path: samples/higgs/vh/zh/ZH_NLO_inc.root, label: 5}
+    - {path: samples/photon/ttyy/ttyy.root, label: 6}
+    - {path: samples/top/multitop/tttt.root, label: 7}
+    - {path: samples/top/single-top/SingleT_schan.root, label: 8}
+    - {path: samples/top/ttbar/ttbar.root, label: 9}
+    - {path: samples/top/ttv/ttW.root, label: 10}
+    - {path: samples/top/multitop/ttt.root, label: 11}
+tree_name: output
+feature_branches:
+  - [jet_pt, ele_pt, mu_pt, ph_pt, MET_met]
+  - [jet_eta, ele_eta, mu_eta, ph_eta, 0]
+  - [jet_phi, ele_phi, mu_phi, ph_phi, MET_phi]
+  - CALC_E
+  - [jet_btag, 0, 0, 0, 0]
+  - [0, ele_charge, mu_charge, 0, 0]
+  - NODE_TYPE
+object_types: [vector, vector, vector, vector, single]
+scales: [0.1, 1, 1, 0.1, 1, 1, 1]
+global_features: []
+fold_var: Number
+weight_var: weight
+batch_size: 1024
+num_workers: 0
+shuffle: true
+seed: 42
+cache:
+  path: outputs/hf_delphes/graphs
+splits:
+  train_folds: [1, 2, 3]
+  validation_folds: [0]
+  test_folds: [4]

src/gnn4colliders/configs/data/hf_smoke.yaml

@@ -0,0 +1,41 @@
+defaults:
+  - _self_
+
+source:
+  type: huggingface
+  repo_id: HWresearch/Delphes
+  repo_type: dataset
+  revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
+  cache_dir: null
+  files:
+    - path: testing/ttH_NLO_64.root
+      label: 0
+      sha256: 89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
+      size_bytes: 15050
+tree_name: output
+feature_branches:
+  - [jet_pt, ele_pt, mu_pt, ph_pt, MET_met]
+  - [jet_eta, ele_eta, mu_eta, ph_eta, 0]
+  - [jet_phi, ele_phi, mu_phi, ph_phi, MET_phi]
+  - CALC_E
+  - [jet_btag, 0, 0, 0, 0]
+  - [0, ele_charge, mu_charge, 0, 0]
+  - NODE_TYPE
+object_types: [vector, vector, vector, vector, single]
+scales: [0.1, 1, 1, 0.1, 1, 1, 1]
+global_features: []
+fold_var: Number
+weight_var: weight
+batch_size: 8
+num_workers: 0
+shuffle: true
+seed: 42
+cache:
+  path: outputs/hf_smoke/graphs
+splits:
+  train_folds: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15,
+                16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
+                30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43,
+                44, 45, 46, 47]
+  validation_folds: [48, 49, 50, 51, 52, 53, 54, 55]
+  test_folds: [56, 57, 58, 59, 60, 61, 62, 63]

src/gnn4colliders/configs/model/root_gnn/edge_network_binary.yaml

@@ -0,0 +1,5 @@
+defaults:
+  - /model/root_gnn/edge_network
+  - _self_
+
+out_size: 1

src/gnn4colliders/data/__init__.py

@@ -11,6 +11,7 @@ from .graph_dataset import (
     TensorGraph,
     batch_graph_samples,
 )
+from .huggingface import resolve_data_files
 from .metadata import (
     CACHE_SCHEMA_VERSION,
     FEATURE_SCHEMA_VERSION,
@@ -42,6 +43,7 @@ __all__ = [
     "GRAPH_SCHEMA_VERSION",
     "CACHE_SCHEMA_VERSION",
     "RootEventDataset",
+    "resolve_data_files",
     "branch_names_from_specs",
     "read_tree",
     "tree_num_entries",

src/gnn4colliders/data/huggingface.py

@@ -0,0 +1,107 @@
+"""Hugging Face Hub data-source resolution for ROOT event files."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from huggingface_hub import hf_hub_download
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _verify_download(path: Path, entry: Mapping[str, Any]) -> Path:
+    expected_size = entry.get("size_bytes")
+    if expected_size is not None and path.stat().st_size != int(expected_size):
+        raise ValueError(
+            f"Hugging Face file size mismatch for {path}: expected "
+            f"{expected_size}, got {path.stat().st_size}"
+        )
+    expected_sha256 = entry.get("sha256")
+    if expected_sha256 is not None:
+        actual_sha256 = _sha256(path)
+        if actual_sha256 != str(expected_sha256):
+            raise ValueError(
+                f"Hugging Face file SHA-256 mismatch for {path}: expected "
+                f"{expected_sha256}, got {actual_sha256}"
+            )
+    return path
+
+
+def _entries(source: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    values = source.get("files", [])
+    if not isinstance(values, Sequence) or isinstance(values, (str, bytes)):
+        raise TypeError("data.source.files must be a sequence")
+    entries: list[Mapping[str, Any]] = []
+    for value in values:
+        if isinstance(value, str):
+            entries.append({"path": value})
+        elif isinstance(value, Mapping):
+            entries.append(value)
+        else:
+            raise TypeError("each data.source.files entry must be a path or mapping")
+    return entries
+
+
+def resolve_data_files(
+    data: Mapping[str, Any],
+) -> tuple[list[Path], Any]:
+    """Resolve configured ROOT files and labels for preparation.
+
+    A Hugging Face source is pinned by repository revision.  Downloads use the
+    Hub cache and are verified when an entry supplies ``sha256`` or
+    ``size_bytes``.  The returned paths have the same contract as the existing
+    local ``data.files`` interface.
+    """
+
+    source = data.get("source")
+    if not source:
+        files = data.get("files", [])
+        if not files:
+            raise ValueError("data.files or data.source is required")
+        return [Path(path) for path in files], data.get("label", 1)
+    if not isinstance(source, Mapping):
+        raise TypeError("data.source must be a mapping")
+    if str(source.get("type", "")).lower() != "huggingface":
+        raise ValueError(f"unsupported data.source.type: {source.get('type')!r}")
+    repo_id = source.get("repo_id")
+    revision = source.get("revision")
+    if not repo_id or not revision:
+        raise ValueError("Hugging Face data sources require repo_id and revision")
+    repo_type = str(source.get("repo_type", "dataset"))
+    cache_dir = source.get("cache_dir")
+    local_files_only = bool(source.get("local_files_only", False))
+    entries = _entries(source)
+    if not entries:
+        raise ValueError("data.source.files must not be empty")
+
+    paths: list[Path] = []
+    labels: list[Any] = []
+    has_entry_labels = []
+    for entry in entries:
+        filename = entry.get("path")
+        if not filename:
+            raise ValueError("each Hugging Face source file needs a path")
+        kwargs = {
+            "repo_id": str(repo_id),
+            "filename": str(filename),
+            "repo_type": repo_type,
+            "revision": str(revision),
+            "cache_dir": cache_dir,
+            "local_files_only": local_files_only,
+        }
+        path = Path(hf_hub_download(**kwargs))
+        paths.append(_verify_download(path, entry))
+        has_entry_labels.append("label" in entry)
+        labels.append(entry.get("label"))
+    if any(has_entry_labels) and not all(has_entry_labels):
+        raise ValueError("either every or no Hugging Face source file needs a label")
+    return paths, labels if all(has_entry_labels) else data.get("label", 1)

tests/integration/test_real_root_model.py

@@ -34,7 +34,11 @@ FEATURE_SCALES = [0.1, 1, 1, 0.1, 1, 1, 1]
 
 def _fixture_path() -> Path:
     configured = os.environ.get("GNN4COLLIDERS_ROOT_FIXTURE")
-    return Path(configured) if configured else Path("data/processed/ttH_NLO_64.root")
+    return (
+        Path(configured)
+        if configured
+        else Path("data/fixtures/testing/ttH_NLO_64.root")
+    )
 
 
 @pytest.fixture(scope="module")

tests/integration/test_real_root_sample.py

@@ -34,7 +34,7 @@ def _fixture_path() -> Path:
     configured = os.environ.get("GNN4COLLIDERS_ROOT_FIXTURE")
     if configured:
         return Path(configured)
-    return Path("data/processed/ttH_NLO_64.root")
+    return Path("data/fixtures/testing/ttH_NLO_64.root")
 
 
 @pytest.fixture(scope="module")
@@ -42,8 +42,8 @@ def root_tree():
     path = _fixture_path()
     if not path.exists():
         pytest.skip(
-            f"ROOT sample fixture is absent: {path}; download ttH_NLO.root and "
-            "create the reduced fixture first"
+            f"ROOT sample fixture is absent: {path}; run the public validation "
+            "command to download it"
         )
     root_file = uproot.open(path)
     tree = root_file["output"]

tests/unit/data/test_huggingface_source.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import pytest
+
+from gnn4colliders.data.huggingface import resolve_data_files
+
+
+def test_huggingface_source_resolves_files_and_labels(monkeypatch, tmp_path):
+    root_file = tmp_path / "sample.root"
+    root_file.write_bytes(b"fixture")
+    monkeypatch.setattr(
+        "gnn4colliders.data.huggingface.hf_hub_download",
+        lambda **kwargs: str(root_file),
+    )
+    paths, labels = resolve_data_files(
+        {
+            "source": {
+                "type": "huggingface",
+                "repo_id": "org/data",
+                "revision": "abc123",
+                "files": [{"path": "sample.root", "label": 4}],
+            }
+        }
+    )
+    assert paths == [root_file]
+    assert labels == [4]
+
+
+def test_huggingface_source_verifies_checksum(monkeypatch, tmp_path):
+    root_file = tmp_path / "sample.root"
+    root_file.write_bytes(b"fixture")
+    monkeypatch.setattr(
+        "gnn4colliders.data.huggingface.hf_hub_download",
+        lambda **kwargs: str(root_file),
+    )
+    checksum = hashlib.sha256(b"wrong").hexdigest()
+    with pytest.raises(ValueError, match="SHA-256 mismatch"):
+        resolve_data_files(
+            {
+                "source": {
+                    "type": "huggingface",
+                    "repo_id": "org/data",
+                    "revision": "abc123",
+                    "files": [{"path": "sample.root", "sha256": checksum}],
+                }
+            }
+        )
+
+
+def test_local_source_remains_unchanged(tmp_path: Path):
+    local = tmp_path / "events.root"
+    paths, label = resolve_data_files({"files": [str(local)], "label": 2})
+    assert paths == [local]
+    assert label == 2

tests/unit/test_package_import.py

@@ -37,3 +37,11 @@ def test_hydra_config_is_discoverable_from_package() -> None:
     config = _config([])
     assert config.model.name == "edge_network"
     assert config.task.type == "multiclass_classification"
+
+
+def test_huggingface_training_config_is_discoverable() -> None:
+    from gnn4colliders.cli import _config
+
+    config = _config([], config_name="config_hf_smoke")
+    assert config.data.source.repo_id == "HWresearch/Delphes"
+    assert config.model.out_size == 1

tests/unit/validation/test_fixture.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import shutil
+
+import pytest
+from validation.fixture import TESTING_FIXTURE, ensure_fixture, verify_fixture
+
+
+def test_checked_in_public_fixture_has_pinned_identity():
+    path = ensure_fixture("data/fixtures/testing/ttH_NLO_64.root", download=False)
+    assert path.stat().st_size == TESTING_FIXTURE.size_bytes
+
+
+def test_fixture_checksum_mismatch_is_rejected(tmp_path):
+    path = tmp_path / "fixture.root"
+    shutil.copyfile("data/fixtures/testing/ttH_NLO_64.root", path)
+    path.write_bytes(path.read_bytes() + b"corruption")
+    with pytest.raises(ValueError, match=r"fixture (size|SHA-256) mismatch"):
+        verify_fixture(path)

uv.lock

@@ -348,6 +348,7 @@ name = "gnn4colliders"
 source = { editable = "." }
 dependencies = [
     { name = "awkward" },
+    { name = "huggingface-hub" },
     { name = "hydra-core" },
     { name = "numpy" },
     { name = "scikit-learn" },
@@ -384,6 +385,7 @@ requires-dist = [
     { name = "awkward", specifier = ">=2.0" },
     { name = "dgl", marker = "platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'root-gnn'", specifier = "==2.2.0" },
     { name = "dgl", marker = "platform_machine == 'x86_64' and sys_platform == 'linux' and extra == 'root-gnn'", specifier = "==2.4.0+cu121", index = "https://data.dgl.ai/wheels/torch-2.2/cu121/repo.html" },
+    { name = "huggingface-hub", specifier = ">=0.36,<1" },
     { name = "hydra-core", specifier = ">=1.3" },
     { name = "numpy", specifier = ">=1.24,<2" },
     { name = "onnx", marker = "extra == 'onnx'", specifier = ">=1.16,<2" },
@@ -408,6 +410,41 @@ dev = [
     { name = "twine", specifier = ">=6,<7" },
 ]
 
+[[package]]
+name = "hf-xet"
+version = "1.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/ab/522a2ab67f27971a9d48ca666d4fca85ef7d5282d142e31fd087e27b1bbe/hf_xet-1.6.0.tar.gz", hash = "sha256:2e58454a340b3556dfa4972d5451aff4fba8dd42a236600ba1a1d2b1514f0fef", size = 920527, upload-time = "2026-08-03T22:33:13.243Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a2/50/7afa2c9c787405864fc47a0d1bbc02c62e9101947ed43c1f43899fc7d91d/hf_xet-1.6.0-cp38-abi3-macosx_10_12_x86_64.whl", hash = "sha256:633dc0cd71d32da58ab8c03ad38e2fac452c15c2b0a2866ebf6ededfe0a5061d", size = 4071729, upload-time = "2026-08-03T22:33:00.721Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/69/55b8dcf636142ae660fec1869fcac14c4da2e8412e14d6eee1523be77e9f/hf_xet-1.6.0-cp38-abi3-macosx_11_0_arm64.whl", hash = "sha256:f0906082d9932ae0c0057fa194041c22b4e2cdb46b2592ef3b91f020d62a081a", size = 3876287, upload-time = "2026-08-03T22:33:02.251Z" },
+    { url = "https://files.pythonhosted.org/packages/67/4e/a28359bf1c1ecf11eba22123168c138698f7cb576ac678f5a2e16cd5da08/hf_xet-1.6.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d62671bb130879cef0ee4c9ebe47a14af6c66ec53e6d84dc15936e5ffdfac82f", size = 4464663, upload-time = "2026-08-03T22:33:03.802Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/69/1f0cbc2fb22ae6082d094f743d1b8945a3f36f6089cb95f42b7ee348cda7/hf_xet-1.6.0-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0e6e21fa3cdfcdcd76748564bf593870a5e013f47d97cf10aed63aa222cff5b7", size = 4262538, upload-time = "2026-08-03T22:33:05.287Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/3a/4f4f2301ade26e404462d3336fa11f7958d914cabbabdd6e03c3c5d5658c/hf_xet-1.6.0-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:4fc74352a17015bd0ee90038bc9efe38db894cde45f268b6712b04fce8cd0acb", size = 4460520, upload-time = "2026-08-03T22:33:06.81Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/5f/311725e2a905534dfee2dcb5b08414f249147f1f12252bfc2bd24caa075c/hf_xet-1.6.0-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:8fb4f71cba6129110c3374a33f919001ff130488fc23553698e34cc1c2a1198c", size = 4675937, upload-time = "2026-08-03T22:33:08.616Z" },
+    { url = "https://files.pythonhosted.org/packages/98/b7/8c59a66d15205024662f1d66968136f13893f96df1ddc5087e2e281fc95f/hf_xet-1.6.0-cp38-abi3-win_amd64.whl", hash = "sha256:fb4fadde1b2b70bf4c0c14a6dccbe7194b1c28947fefd5bbe3fed9d940676c3b", size = 4033128, upload-time = "2026-08-03T22:33:10.171Z" },
+    { url = "https://files.pythonhosted.org/packages/73/63/ca511b6f802f28cf3489b280fe77475bcca8de85e81a6299d7916b5b5555/hf_xet-1.6.0-cp38-abi3-win_arm64.whl", hash = "sha256:3dc3e35441ba395006af5aaacc40ef2e603c51ef46c3530b9156185f00935ea3", size = 3859359, upload-time = "2026-08-03T22:33:11.725Z" },
+]
+
+[[package]]
+name = "huggingface-hub"
+version = "0.36.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "filelock" },
+    { name = "fsspec" },
+    { name = "hf-xet", marker = "platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'" },
+    { name = "packaging" },
+    { name = "pyyaml" },
+    { name = "requests" },
+    { name = "tqdm" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7c/b7/8cb61d2eece5fb05a83271da168186721c450eb74e3c31f7ef3169fa475b/huggingface_hub-0.36.2.tar.gz", hash = "sha256:1934304d2fb224f8afa3b87007d58501acfda9215b334eed53072dd5e815ff7a", size = 649782, upload-time = "2026-02-06T09:24:13.098Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a8/af/48ac8483240de756d2438c380746e7130d1c6f75802ef22f3c6d49982787/huggingface_hub-0.36.2-py3-none-any.whl", hash = "sha256:48f0c8eac16145dfce371e9d2d7772854a4f591bcb56c9cf548accf531d54270", size = 566395, upload-time = "2026-02-06T09:24:11.133Z" },
+]
+
 [[package]]
 name = "hydra-core"
 version = "1.3.5"
@@ -1340,6 +1377,9 @@ wheels = [
 name = "tqdm"
 version = "4.70.0"
 source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
 sdist = { url = "https://files.pythonhosted.org/packages/21/3b/6c24bec5be5e743ffd99576daa5cc077722fc7d5bbc00bd133fa0c698dc6/tqdm-4.70.0.tar.gz", hash = "sha256:55b0b0dbd97462d06ebee91e4dac24ed4d4702be82b24f07e6c1d27e08cea220", size = 795438, upload-time = "2026-07-27T11:33:15.271Z" }
 wheels = [
     { url = "https://files.pythonhosted.org/packages/f9/1c/01bfd571a64e7f270e6bab5e33777debe0edc56759233ce84f27dec92d14/tqdm-4.70.0-py3-none-any.whl", hash = "sha256:7f585706bfddbdebf89daac705b2dfcc16890130727d3197ca62c732b4310953", size = 80184, upload-time = "2026-07-27T11:33:13.167Z" },

validation/README.md

@@ -7,38 +7,58 @@ flattened storage plus offsets. Exact fields (IDs, labels, folds, offsets,
 topology) are exact-compared; floating fields use `tolerances.yaml`.
 
 ```bash
-uv run python -m validation.run_full_validation --smoke
-uv run python -m validation.run_full_validation \
-  --legacy-artifact validation_output/legacy \
-  --rewrite-artifact validation_output/rewrite \
-  --output validation_output/reports
+uv run python -m validation.run_public_validation
 ```
 
-Smoke validates serialization and comparison plumbing only; it does not claim
-legacy parity. Full scientific validation uses the same ROOT sample in both
-runtimes, with `GNN4COLLIDERS_E2E_FIXTURE` selecting an external fixture. Keep
+The command verifies the local fixture, downloads it from the pinned Hugging
+Face revision when necessary, extracts the rewrite, compares it with the
+checked-in legacy golden artifact, writes JSON and Markdown reports, and exits
+nonzero on a scientific mismatch. Use `--no-download` for offline runs. Keep
 generated output out of Git.
 
-## Current HF fixture campaign
+The lower-level artifact tooling remains available for regenerating references
+in the historical legacy environment:
+
+```bash
+uv run python -m validation.run_full_validation --smoke
+```
+
+## Current public HF fixture
+
+The normal public regression path requires only the current environment. It
+verifies the pinned public fixture, downloads it when missing, extracts the
+rewrite, and compares it with the legacy golden artifact:
+
+```bash
+uv run python -m validation.run_public_validation
+```
+
+The fixture identity is:
+
+```text
+repository: HWresearch/Delphes (dataset)
+revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
+path: testing/ttH_NLO_64.root
+sha256: 89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
+events: 64
+```
 
-The small fixture can be extracted in both environments:
+The historical extraction commands below are retained only for regenerating or
+auditing the golden artifact in a legacy environment:
 
 ```bash
-ROOT=/global/cfs/projectdirs/atlas/joshua/gnn_data/hf_validation/testing/ttH_NLO_64.root
+ROOT=data/fixtures/testing/ttH_NLO_64.root
 HF_SHA=89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
 
 conda run -n dgl env PYTHONPATH=.:legacy/root_gnn_dgl:src \
-  python validation/extract_legacy.py /tmp/legacy_ttree.root validation_output/legacy \
+  python validation/extract_legacy.py "$ROOT" validation_output/legacy \
   --source-sha256 "$HF_SHA"
 
 PYTHONPATH=.:src uv run python validation/extract_rewrite.py "$ROOT" \
   validation_output/rewrite --source-sha256 "$HF_SHA"
 ```
 
-The legacy environment is Python 3.8/Uproot 5.3 and cannot read the HF
-RNTuple directly. Convert the fixture to a temporary TTree with a modern
-Uproot process; this changes only the ROOT container representation, not event
-values. The manifest retains the original HF SHA-256. Then run `forward.py`
+The manifest retains the original HF SHA-256. Then run `forward.py`
 with `model_epoch_71.pt`, `train_step.py`, `compare_step.py`, and
 `compare_tasks.py` to generate fixed-forward, one-step, and task reports.
 

validation/extract_common.py

@@ -136,7 +136,7 @@ def extract_root(
             "events": event_count,
             "sha256": file_sha256(path),
             "source_sha256": source_sha256 or file_sha256(path),
-            "input_path": str(path),
+            "input_path": path.name,
             "feature_schema": [
                 "pt",
                 "eta",

validation/fixture.py

@@ -0,0 +1,111 @@
+"""Pinned public validation-fixture discovery, download, and verification."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import tempfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class PublicFixture:
+    repository: str
+    revision: str
+    repository_path: str
+    sha256: str
+    size_bytes: int
+
+    @property
+    def url(self) -> str:
+        return (
+            f"https://huggingface.co/datasets/{self.repository}/resolve/"
+            f"{self.revision}/{self.repository_path}?download=true"
+        )
+
+
+TESTING_FIXTURE = PublicFixture(
+    repository="HWresearch/Delphes",
+    revision="76a6c362bfba8e766ba7255a5c08a55257f78d0e",
+    repository_path="testing/ttH_NLO_64.root",
+    sha256="89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+    size_bytes=15050,
+)
+
+
+def default_fixture_path(root: str | Path = ".") -> Path:
+    return Path(root) / "data" / "fixtures" / "testing" / "ttH_NLO_64.root"
+
+
+def file_sha256(path: str | Path) -> str:
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def verify_fixture(path: str | Path, fixture: PublicFixture = TESTING_FIXTURE) -> Path:
+    """Verify size and SHA-256 before allowing a fixture into validation."""
+
+    path = Path(path)
+    if not path.is_file():
+        raise FileNotFoundError(f"validation fixture is missing: {path}")
+    actual_size = path.stat().st_size
+    if actual_size != fixture.size_bytes:
+        raise ValueError(
+            f"fixture size mismatch for {path}: expected {fixture.size_bytes}, "
+            f"got {actual_size}"
+        )
+    actual_sha256 = file_sha256(path)
+    if actual_sha256 != fixture.sha256:
+        raise ValueError(
+            f"fixture SHA-256 mismatch for {path}: expected {fixture.sha256}, "
+            f"got {actual_sha256}"
+        )
+    return path
+
+
+def download_fixture(
+    path: str | Path,
+    fixture: PublicFixture = TESTING_FIXTURE,
+    *,
+    timeout: float = 60.0,
+) -> Path:
+    """Download a pinned fixture atomically and verify it before returning."""
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".download", dir=path.parent
+    )
+    os.close(fd)
+    temporary = Path(temporary_name)
+    try:
+        with urllib.request.urlopen(fixture.url, timeout=timeout) as response:
+            with temporary.open("wb") as output:
+                while chunk := response.read(1024 * 1024):
+                    output.write(chunk)
+        verify_fixture(temporary, fixture)
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+    return path
+
+
+def ensure_fixture(
+    path: str | Path | None = None,
+    *,
+    download: bool = True,
+    fixture: PublicFixture = TESTING_FIXTURE,
+) -> Path:
+    """Return a verified local fixture, downloading it when necessary."""
+
+    path = Path(path) if path is not None else default_fixture_path()
+    if path.is_file():
+        return verify_fixture(path, fixture)
+    if not download:
+        raise FileNotFoundError(f"validation fixture is missing: {path}")
+    return download_fixture(path, fixture)

validation/golden/testing/legacy/artifact.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cc5164e3eda8f88991fc87a70e13e766b1ae2ef3604a614273d9f6c52cdcf792
+size 40151

validation/golden/testing/legacy/manifest.json

@@ -0,0 +1,33 @@
+{
+  "arrays": [
+    "edge_dst_flat",
+    "edge_features_flat",
+    "edge_offsets",
+    "edge_src_flat",
+    "folds",
+    "globals",
+    "labels",
+    "node_features_flat",
+    "node_offsets",
+    "sample_id",
+    "weights"
+  ],
+  "event_count": 64,
+  "events": 64,
+  "feature_schema": [
+    "pt",
+    "eta",
+    "phi",
+    "energy",
+    "btag",
+    "charge",
+    "node_type"
+  ],
+  "input_path": "ttH_NLO_64.root",
+  "repository_path": "testing/ttH_NLO_64.root",
+  "schema_version": 1,
+  "sha256": "89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+  "source": "huggingface://datasets/HWresearch/Delphes",
+  "source_sha256": "89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec",
+  "tree": "output"
+}

validation/manifests/dataset.json

@@ -1,6 +1,6 @@
 {
   "source": "https://huggingface.co/datasets/HWresearch/Delphes",
-  "revision": "main",
+  "revision": "76a6c362bfba8e766ba7255a5c08a55257f78d0e",
   "files": [
     {
       "repository_path": "testing/ttH_NLO_64.root",

validation/run_public_validation.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Run rewrite-vs-golden validation using the pinned public HF fixture."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from validation.compare import compare_artifacts, write_reports
+from validation.extract_common import (
+    FEATURE_BRANCHES,
+    OBJECT_TYPES,
+    SCALES,
+    extract_root,
+)
+from validation.fixture import TESTING_FIXTURE, ensure_fixture
+
+
+def _extract_rewrite(root_file: Path, output: Path) -> None:
+    from gnn4colliders.features import build_node_features
+
+    def build(event):
+        features, _ = build_node_features(event, FEATURE_BRANCHES, OBJECT_TYPES, SCALES)
+        return features
+
+    extract_root(
+        root_file,
+        output,
+        build_features=build,
+        sample_name=TESTING_FIXTURE.repository_path,
+        source_sha256=TESTING_FIXTURE.sha256,
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--fixture", type=Path)
+    parser.add_argument("--output", type=Path, default=Path("validation_output/public"))
+    parser.add_argument(
+        "--no-download",
+        action="store_true",
+        help="fail instead of downloading a missing fixture",
+    )
+    args = parser.parse_args()
+
+    fixture = ensure_fixture(args.fixture, download=not args.no_download)
+    golden = Path(__file__).parent / "golden" / "testing" / "legacy"
+    if not (golden / "manifest.json").is_file():
+        raise FileNotFoundError(f"golden reference is missing: {golden}")
+    rewrite = args.output / "rewrite"
+    _extract_rewrite(fixture, rewrite)
+    report = compare_artifacts(golden, rewrite)
+    report["fixture"] = {
+        "repository": TESTING_FIXTURE.repository,
+        "revision": TESTING_FIXTURE.revision,
+        "repository_path": TESTING_FIXTURE.repository_path,
+        "sha256": TESTING_FIXTURE.sha256,
+        "size_bytes": TESTING_FIXTURE.size_bytes,
+    }
+    report_dir = args.output / "report"
+    write_reports(report, report_dir)
+    print(
+        json.dumps(
+            {
+                "overall_status": report["overall_status"],
+                "fixture": str(fixture),
+                "report": str(report_dir),
+            },
+            indent=2,
+        )
+    )
+    return 0 if report["overall_status"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())