README.md

---
pretty_name: BridgeWAM Checkpoints
library_name: pytorch
tags:
  - robotics
  - robot-learning
  - imitation-learning
  - embodied-ai
  - libero
  - robotwin
  - world-action-model
  - latent-bridge-queries
---

# BridgeWAM Checkpoints

Released checkpoints for **BridgeWAM**, a video-action model that connects a
pretrained video expert to a lightweight action expert through **Latent Bridge
Queries (LBQs)**.

This repository provides separate checkpoints for **LIBERO** and **RoboTwin**,
together with the normalization statistics required by each checkpoint.

## Files

```text
README.md
config.json                 Download manifest and architecture summary
download_bridgewam.py       Optional manifest-driven downloader
libero/
  model.pt
  dataset_stats.json
robotwin/
  model.pt
  dataset_stats.json
```

## Included checkpoints

| Checkpoint | Benchmark | Camera inputs | Action dimensions |
| --- | --- | --- | ---: |
| `libero/model.pt` | LIBERO | Front and wrist cameras | 7 |
| `robotwin/model.pt` | RoboTwin | Head and two wrist cameras | 14 |

Use these checkpoints with the following task configurations in the BridgeWAM
codebase:

- **LIBERO:** `task=libero_uncond_2cam224_lbqs_only_2layer_alternating_cross_self_fullfinetune_1e-4`
- **RoboTwin:** `task=robotwin_bridgewam_3cam384_lbq32_2layer_1e-4`

Always use the `dataset_stats.json` from the **same benchmark folder** as the
checkpoint. The two checkpoints have different action and proprioception
dimensions and are not interchangeable.

## BridgeWAM configuration

Both checkpoints use a 30-layer Wan2.2 video expert and a two-layer action expert
with alternating cross-attention and self-attention. They use **32 LBQs**, injected
from video layer `0` and read out at the final video layer (`readout_layer=-1`).
Action conditioning uses `lbq_only`, without direct Video-to-Action K/V routing.

The standard action-inference path computes LBQ conditioning once from the
observations, language instruction and proprioception, then reuses it throughout
action denoising. It does **not** generate future video at test time.

The release inference settings use a 32-step action horizon and 10 denoising
steps. The LIBERO evaluator replans after 10 actions; the RoboTwin evaluator
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 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)
and run the commands below from the code repository root, in its configured
Linux/CUDA environment. The checkpoints require the matching Wan VAE, text
encoder and tokenizer resources, as described in the code README. These external
resources and simulator assets are not included in this model repository.

Common environment settings:

```bash
export BRIDGEWAM_PYTHON="$(command -v python)"
export PYTHONPATH="$PWD/src:$PWD${PYTHONPATH:+:$PYTHONPATH}"
export CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
export MUJOCO_GL=egl
export PYOPENGL_PLATFORM=egl
export DIFFSYNTH_MODEL_BASE_PATH=/path/to/pretrained-models
```

### LIBERO

Install LIBERO and configure its BDDL files, initial states and simulator assets.
Replace `/path/to/LIBERO` with the environment repository path.

```bash
export LIBERO_ROOT=/path/to/LIBERO
export PYTHONPATH="$LIBERO_ROOT:$PYTHONPATH"

python experiments/libero/run_libero_manager.py \
  task=libero_uncond_2cam224_lbqs_only_2layer_alternating_cross_self_fullfinetune_1e-4 \
  ckpt=./checkpoints/bridgewam/libero/model.pt \
  EVALUATION.dataset_stats_path=./checkpoints/bridgewam/libero/dataset_stats.json \
  EVALUATION.output_dir="./runs/eval/libero/$(date +%Y%m%d_%H%M%S)" \
  EVALUATION.num_trials=50 \
  EVALUATION.num_inference_steps=10 \
  model.skip_dit_load_from_pretrain=true \
  seed=42 \
  MULTIRUN.num_gpus=8 \
  MULTIRUN.max_tasks_per_gpu=6
```

The default manager evaluates all 40 tasks across LIBERO-Spatial, LIBERO-Object,
LIBERO-Goal and LIBERO-Long (`libero_10`).

### LIBERO-Plus

Use the same `libero/model.pt` and `libero/dataset_stats.json` for LIBERO-Plus;
no separate Plus checkpoint is required. Install the external LIBERO-Plus
environment, its extra dependencies and simulator assets. Sensor-noise tasks
also require ImageMagick. Replace `/path/to/LIBERO-plus` below with that checkout.

The full protocol evaluates **10,030 task variants with one trial per variant**.
Each worker loads the model once and evaluates a shard of up to 50 variants.

```bash
export ROOT_DIR="$PWD"
export LIBERO_PLUS_REPO=/path/to/LIBERO-plus
export LIBERO_ROOT="$LIBERO_PLUS_REPO"
export PYTHONPATH="$PWD/src:$PWD:$LIBERO_PLUS_REPO"

LIBERO_PLUS_DETACH=true \
bash experiments/libero-plus/run_stage1.sh \
  task=libero_uncond_2cam224_lbqs_only_2layer_alternating_cross_self_fullfinetune_1e-4 \
  ckpt=./checkpoints/bridgewam/libero/model.pt \
  EVALUATION.dataset_stats_path=./checkpoints/bridgewam/libero/dataset_stats.json \
  EVALUATION.output_dir="./runs/eval/libero-plus/$(date +%Y%m%d_%H%M%S)" \
  EVALUATION.num_trials=1 \
  EVALUATION.num_inference_steps=10 \
  EVALUATION.save_rollout_video=true \
  LIBERO_PLUS.repo_path="$LIBERO_PLUS_REPO" \
  LIBERO_PLUS.expected_num_tasks=10030 \
  model.skip_dit_load_from_pretrain=true \
  seed=42 \
  MULTIRUN.tasks_per_worker=50 \
  MULTIRUN.num_gpus=8 \
  MULTIRUN.max_tasks_per_gpu=5
```

This launcher requires `tmux` and detaches the manager by default. It prints the
session name and log location; returning to the terminal does not mean evaluation
has finished. Wait for completion before starting another benchmark on the same
GPUs. Results include `libero_plus_task_results.csv` and
`libero_plus_summary.json` in the selected output directory.

### LIBERO-Pro

Use the same LIBERO checkpoint and statistics for LIBERO-Pro. Install the external
LIBERO-PRO checkout with its benchmark task map, BDDL files, initial states and
simulator assets. The current adapter expects these resources under
`LIBERO-PRO/libero/libero/{bddl_files,init_files,assets}`. Use the same generated
resource release and environment variant for comparisons between models.

The full protocol selects **200 tasks across five perturbation categories**
(environment, position, object, language and task), with **50 trials per task**
for 10,000 episodes. These are separate perturbation categories, not their runtime
combinations. A task-count check alone does not verify resource equivalence.

```bash
export LIBERO_PRO_REPO=/path/to/LIBERO-PRO
export LIBERO_ROOT="$LIBERO_PRO_REPO"
export PYTHONPATH="$PWD/src:$PWD:$LIBERO_PRO_REPO"

python experiments/libero-pro/run_libero_pro_manager.py \
  task=libero_uncond_2cam224_lbqs_only_2layer_alternating_cross_self_fullfinetune_1e-4 \
  ckpt=./checkpoints/bridgewam/libero/model.pt \
  EVALUATION.dataset_stats_path=./checkpoints/bridgewam/libero/dataset_stats.json \
  EVALUATION.output_dir="./runs/eval/libero-pro/$(date +%Y%m%d_%H%M%S)" \
  EVALUATION.num_trials=50 \
  EVALUATION.num_inference_steps=10 \
  EVALUATION.save_rollout_video=true \
  LIBERO_PRO.repo_path="$LIBERO_PRO_REPO" \
  'LIBERO_PRO.perturbations=[environment,position,object,language,task]' \
  LIBERO_PRO.expected_num_tasks=200 \
  model.skip_dit_load_from_pretrain=true \
  seed=42 \
  MULTIRUN.num_gpus=8 \
  MULTIRUN.max_tasks_per_gpu=5
```

The Pro manager runs in the foreground and waits for all workers; run it inside
`tmux` if it must survive a terminal disconnect. Each run writes an isolated
environment configuration, `task_manifest.jsonl`, task logs, `summary.json` and
`manager_runtime.json`. Use a fresh output directory and check that the summary
is complete; an existing summary file alone does not establish completion.

### RoboTwin

Install the complete RoboTwin environment and assets at `third_party/RoboTwin`,
and expose the `bridgewam_policy` adapter under its `policy/` directory. Empty
placeholder files are not a working simulator installation.

```bash
python experiments/robotwin/run_robotwin_manager.py \
  task=robotwin_bridgewam_3cam384_lbq32_2layer_1e-4 \
  ckpt=./checkpoints/bridgewam/robotwin/model.pt \
  EVALUATION.dataset_stats_path=./checkpoints/bridgewam/robotwin/dataset_stats.json \
  EVALUATION.output_dir="./runs/eval/robotwin/$(date +%Y%m%d_%H%M%S)" \
  EVALUATION.eval_num_episodes=100 \
  EVALUATION.num_inference_steps=10 \
  model.skip_dit_load_from_pretrain=true \
  seed=42 \
  MULTIRUN.num_gpus=8 \
  MULTIRUN.max_tasks_per_gpu=4
```

The manager schedules clean and randomized evaluation settings. The concurrency
values above are launch settings, not minimum GPU requirements; reduce
`MULTIRUN.max_tasks_per_gpu` if GPU memory is insufficient.

## Notes and limitations

- These are task-specific research checkpoints, not general-purpose robot policies.
- Use the matching camera layout, action/state representation and normalization.
- Load weights through the BridgeWAM model loader and matching task configuration;
  these are not Transformers `AutoModel` checkpoints.
- Successful checkpoint loading does not establish closed-loop task success.
  Benchmark results require the corresponding simulator and a complete evaluation.
- Real-robot deployment requires independent validation and appropriate safeguards.
- Upstream software, model and dataset licenses continue to apply.

## Project

- Code: [BridgeWAM-code](https://github.com/BridgeWam/BridgeWAM-code)
- Checkpoints: [BridgeWAM/bridgewam](https://huggingface.co/BridgeWAM/bridgewam)

BridgeWAM builds on Wan, Fast-WAM and LeRobot components. See the code repository
for upstream attribution, environment setup and additional evaluation instructions.