Add checkpoint manifest and compatible benchmark download workflow

Add config.json with checkpoint/statistics paths and integrity metadata; provide a manifest-driven downloader and document full/selected downloads. Preserve existing weights, statistics and evaluation commands. Configuration requests participate in standard Hub download statistics.

README.md

@@ -25,6 +25,8 @@ together with the normalization statistics required by each checkpoint.
 
 ```text
 README.md
+config.json                 Download manifest and architecture summary
+download_bridgewam.py       Optional manifest-driven downloader
 libero/
   model.pt
   dataset_stats.json
@@ -67,11 +69,73 @@ replans after 24 actions.
 
 ## Download
 
+`config.json` describes the released architecture and maps each benchmark to its
+checkpoint, matching normalization statistics, task configuration, file size and
+SHA-256 checksum. It is a BridgeWAM download manifest, **not** a Transformers
+`AutoConfig` file or a replacement for the codebase's Hydra task YAML.
+The existing `.pt` files, statistics, paths and model-loading API are unchanged.
+
+### Download all checkpoints
+
+The existing command still works and now also downloads `config.json`:
+
 ```bash
-pip install -U huggingface_hub
+pip install huggingface_hub
 hf download BridgeWAM/bridgewam --local-dir ./checkpoints/bridgewam
 ```
 
+### Download one benchmark
+
+Include `config.json` alongside the weights and their matching statistics:
+
+```bash
+# LIBERO (also used for LIBERO-Plus and LIBERO-Pro)
+hf download BridgeWAM/bridgewam config.json libero/model.pt libero/dataset_stats.json \
+  --local-dir ./checkpoints/bridgewam
+
+# RoboTwin
+hf download BridgeWAM/bridgewam config.json robotwin/model.pt robotwin/dataset_stats.json \
+  --local-dir ./checkpoints/bridgewam
+```
+
+On older installations (including the codebase's pinned `huggingface_hub==0.29.2`),
+replace `hf download` with `huggingface-cli download`. There is no need to upgrade
+the pinned training environment to use these downloads.
+
+### Manifest-driven Python downloader
+
+The helper supports `huggingface_hub>=0.29.2` and does not require PyTorch or CUDA.
+Download it once, then select `libero`, `robotwin`, or `all`:
+
+```bash
+hf download BridgeWAM/bridgewam download_bridgewam.py --local-dir ./bridgewam-tools
+python ./bridgewam-tools/download_bridgewam.py \
+  --benchmark libero --local-dir ./checkpoints/bridgewam
+```
+
+The helper reads `config.json`, downloads the selected checkpoint and statistics
+from the same resolved commit, and prints the matching evaluation arguments.
+It checks both file sizes and the statistics checksum; add `--verify` to also
+check the weights' SHA-256 (this reads approximately 10 GB per checkpoint).
+Use `--revision <commit-sha>` to pin a release containing the manifest. Downloads
+use the Hub's normal cache/resume behavior; the helper does not force downloads
+or add separate tracking requests. For offline inference, download first and
+continue using the existing local checkpoint and statistics paths below.
+
+### Download statistics
+
+Hugging Face counts requests to recognized configuration files such as
+`config.json`. Including this real manifest in the download allows the normal
+Hub download workflow to participate in its standard statistics. This is a
+repository-level request metric, not a count of unique people or completed
+weight downloads; it does not distinguish LIBERO from RoboTwin.
+
+Direct downloads of only the old `.pt` URLs remain supported, but do not by
+themselves request the configuration and may remain uncounted. Fully offline
+cache use makes no server request, and earlier uncounted downloads cannot be
+recovered by adding this file. Displayed statistics may take time to update.
+See [Hugging Face's download statistics documentation](https://huggingface.co/docs/hub/models-download-stats).
+
 ## Evaluation
 
 Install the [BridgeWAM code and dependencies](https://github.com/BridgeWam/BridgeWAM-code)

config.json

@@ -0,0 +1,61 @@
+{
+  "schema_version": 1,
+  "model_name": "BridgeWAM",
+  "description": "Download manifest and architecture summary for the released task-specific BridgeWAM checkpoints; use the matching codebase task YAML to instantiate the model.",
+  "checkpoint_format": "pytorch_weight_dictionary",
+  "architecture": {
+    "video_expert_layers": 30,
+    "action_expert_layers": 2,
+    "action_expert_architecture": "alternating_cross_self",
+    "num_lbqs": 32,
+    "lbq_start_layer": 0,
+    "lbq_readout_layer": -1,
+    "conditioning": "lbq_only"
+  },
+  "inference": {
+    "action_horizon": 32,
+    "num_inference_steps": 10,
+    "generates_future_video": false
+  },
+  "checkpoints": {
+    "libero": {
+      "task": "libero_uncond_2cam224_lbqs_only_2layer_alternating_cross_self_fullfinetune_1e-4",
+      "action_dim": 7,
+      "proprio_dim": 8,
+      "cameras": [
+        "front",
+        "wrist"
+      ],
+      "weights": {
+        "path": "libero/model.pt",
+        "size_bytes": 10120229217,
+        "sha256": "8afbff12d7bca4d978e78b18270a01a5233e56b24f3dded52b355e04cc9a12c3"
+      },
+      "normalization": {
+        "path": "libero/dataset_stats.json",
+        "size_bytes": 40940,
+        "sha256": "8d4d4a3d376bb91a75353562b0ae8ab217db8107fdcd10d0ed68fdcacf3a923e"
+      }
+    },
+    "robotwin": {
+      "task": "robotwin_bridgewam_3cam384_lbq32_2layer_1e-4",
+      "action_dim": 14,
+      "proprio_dim": 14,
+      "cameras": [
+        "head",
+        "left_wrist",
+        "right_wrist"
+      ],
+      "weights": {
+        "path": "robotwin/model.pt",
+        "size_bytes": 10120307498,
+        "sha256": "4decbb9d497b714dfe879e10da10506dc6fa21dbaab4dbeac5fb9d4abc490833"
+      },
+      "normalization": {
+        "path": "robotwin/dataset_stats.json",
+        "size_bytes": 88715,
+        "sha256": "7a02c46cfc8c5e746c0afbe41fca73f723eda34cbc083f8ca54f76d8f7468095"
+      }
+    }
+  }
+}

download_bridgewam.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""Download a matched BridgeWAM checkpoint/statistics pair from its manifest.
+
+Requires huggingface_hub>=0.29.2; no PyTorch or CUDA installation is needed.
+Existing model.pt paths and the BridgeWAM model loader remain unchanged.
+"""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+
+from huggingface_hub import HfApi, hf_hub_download
+
+
+REPO_ID = "BridgeWAM/bridgewam"
+
+
+def validate_manifest(config):
+    if config.get("schema_version") != 1 or config.get("model_name") != "BridgeWAM":
+        raise ValueError("Unsupported BridgeWAM download manifest")
+    variants = config.get("checkpoints", {})
+    if set(variants) != {"libero", "robotwin"}:
+        raise ValueError("Manifest must provide LIBERO and RoboTwin checkpoints")
+    for name, entry in variants.items():
+        if not isinstance(entry.get("task"), str) or not entry["task"]:
+            raise ValueError("Missing task configuration for " + name)
+        for role, filename in (("weights", "model.pt"), ("normalization", "dataset_stats.json")):
+            asset = entry[role]
+            path = PurePosixPath(asset["path"])
+            if str(path) != name + "/" + filename:
+                raise ValueError("Unexpected checkpoint/statistics path")
+            if not isinstance(asset["size_bytes"], int) or asset["size_bytes"] <= 0:
+                raise ValueError("Invalid asset size")
+            digest = asset["sha256"]
+            if len(digest) != 64 or any(c not in "0123456789abcdef" for c in digest):
+                raise ValueError("Invalid asset SHA-256")
+    return variants
+
+
+def verify_file(path, asset, check_hash):
+    if path.stat().st_size != asset["size_bytes"]:
+        raise ValueError("Size mismatch: " + str(path))
+    if check_hash:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(8 * 1024 * 1024), b""):
+                digest.update(chunk)
+        if digest.hexdigest() != asset["sha256"]:
+            raise ValueError("SHA-256 mismatch: " + str(path))
+
+
+def download(benchmark, local_dir, revision="main", verify=False):
+    if benchmark not in ("libero", "robotwin", "all"):
+        raise ValueError("Choose libero, robotwin or all")
+    # Resolve once, then pin the configuration, weights and statistics together.
+    commit = HfApi().model_info(REPO_ID, revision=revision).sha
+    if not commit:
+        raise ValueError("Could not resolve the requested repository revision")
+    local_dir = Path(local_dir)
+    config_path = hf_hub_download(
+        repo_id=REPO_ID, filename="config.json", revision=commit, local_dir=str(local_dir)
+    )
+    with open(config_path, encoding="utf-8") as handle:
+        variants = validate_manifest(json.load(handle))
+    selected = ("libero", "robotwin") if benchmark == "all" else (benchmark,)
+    results = {}
+    for name in selected:
+        entry = variants[name]
+        files = {}
+        for role in ("normalization", "weights"):
+            asset = entry[role]
+            path = Path(hf_hub_download(
+                repo_id=REPO_ID, filename=asset["path"], revision=commit,
+                local_dir=str(local_dir)
+            ))
+            # Always validate the small normalization file; weight hashing is optional.
+            verify_file(path, asset, check_hash=verify or role == "normalization")
+            files[role] = str(path)
+        results[name] = {"revision": commit, "task": entry["task"], **files}
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--benchmark", choices=("libero", "robotwin", "all"), required=True)
+    parser.add_argument("--local-dir", default="./checkpoints/bridgewam")
+    parser.add_argument("--revision", default="main", help="HF branch, tag or commit SHA")
+    parser.add_argument("--verify", action="store_true", help="Also SHA-256-check the large weights")
+    args = parser.parse_args()
+    results = download(args.benchmark, args.local_dir, args.revision, args.verify)
+    for name, result in results.items():
+        print("\nDownloaded {} at {}".format(name, result["revision"]))
+        print("task=" + result["task"])
+        print("ckpt=" + result["weights"])
+        print("EVALUATION.dataset_stats_path=" + result["normalization"])
+
+
+if __name__ == "__main__":
+    main()