Simplify StreamWAM model card

README.md

@@ -10,16 +10,26 @@ tags:
   - pytorch
 ---
 
-# StreamWAM
+<div align="center">
+  <h1>StreamWAM</h1>
+  <h3>Streaming World-Action Models for Robotic Manipulation</h3>
 
-StreamWAM provides synchronous and asynchronous world-action inference for robot manipulation. This repository contains two LIBERO checkpoints in their original FastWAM checkpoint format. StreamWAM loads them directly at runtime; no offline checkpoint conversion or duplicate model copy is required.
+  <a href="https://github.com/SJTU-DENG-Lab/StreamWAM"><img src="https://img.shields.io/badge/GitHub-Code-111827?logo=github" alt="GitHub Code"></a>
+  <a href="https://github.com/SJTU-DENG-Lab/StreamWAM/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-6B5BFF" alt="Apache 2.0 License"></a>
+</div>
 
-## Models
+StreamWAM is a research framework for streaming World-Action Models. It provides a unified testbed for studying and comparing efficient robot-control strategies.
 
-| Directory | Inference mode | Description |
+StreamWAM uses the actions currently being executed by the robot to guide its next prediction. This allows action execution and model inference to proceed together, reducing the time required to complete a robot task while maintaining strong control performance.
+
+This repository provides the released LIBERO checkpoints. The corresponding inference and evaluation code is available in the [StreamWAM GitHub repository](https://github.com/SJTU-DENG-Lab/StreamWAM).
+
+## Released checkpoints
+
+| Directory | Model | Description |
 | --- | --- | --- |
-| `joint-cd/` | Joint CD | Direct synchronous one-step consistency inference that jointly predicts world and action tokens. |
-| `ac-stream/` | AC-Stream | D0/D8 asynchronous inference that overlaps model prediction with action execution. The same checkpoint supports eager and accelerated backends. |
+| `joint-cd/` | FastWAM-Joint-CD | Fast one-step joint world-and-action prediction for LIBERO. |
+| `ac-stream/` | StreamWAM | Recommended StreamWAM checkpoint for efficient LIBERO evaluation. |
 
 Each directory contains:
 
@@ -28,56 +38,45 @@ model.pt
 dataset_stats.json
 ```
 
-The checkpoints use a Wan2.2 TI2V 5B backbone. The Wan2.2 model assets are not included in this repository and must be obtained separately.
+The checkpoints use the Wan2.2 TI2V 5B backbone. Wan2.2 model assets are not included here and must be downloaded separately.
 
-## Inference geometry
+## LIBERO results
 
-Both checkpoints target the following LIBERO setup:
+We evaluate all methods on LIBERO-10, LIBERO-Spatial, LIBERO-Goal, and LIBERO-Object with 50 trials per task. `Chunk Time` is the average model inference time for one action chunk. `Episode Time` is the average end-to-end task duration for long- and short-horizon tasks.
 
-- two RGB cameras, concatenated horizontally;
-- per-camera resolution: 224 x 224;
-- model image input: 224 x 448;
-- action dimension: 7;
-- proprioception dimension: 8;
-- action horizon: 32;
-- video context: 9 frames at inference time;
-- BF16 model execution.
+| Method | LIBERO-10 | Spatial | Goal | Object | Average (%) ↑ | Chunk Time (ms) ↓ | Episode Time (s) ↓ Long / Short |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| FastWAM | 96.20 | 96.20 | 94.20 | 96.20 | 95.70 | 493.0 | 16.31 / 8.25 |
+| FastWAM-Joint-CD | 97.20 | 99.60 | 98.60 | 100.00 | 98.85 | 114.2 | 6.89 / 3.74 |
+| **StreamWAM** | **96.60** | **98.80** | **97.40** | **100.00** | **98.20** | **41.0** | **5.36 / 3.15** |
 
-Joint CD uses one consistency step and replans every 16 executed actions.
+## Installation
 
-AC-Stream uses the H32/s16/d8 schedule:
+Clone the code repository and install the environment:
 
-- D0 starts without a clean action prefix;
-- D8 conditions on the first 8 clean actions of the current horizon;
-- background D8 inference is launched while actions are executing;
-- the controller advances by a stride of 16 actions;
-- deadline misses block at the boundary instead of installing a stale prediction.
+```bash
+git clone https://github.com/SJTU-DENG-Lab/StreamWAM.git
+cd StreamWAM
 
-## Requirements
+python -m pip install -U uv
+uv sync
+```
 
-Inference requires:
+The reference environment uses Python 3.10, PyTorch 2.7.1 with CUDA 12.8, and Triton 3.3.1.
 
-1. the StreamWAM source code;
-2. Wan2.2 TI2V 5B model assets;
-3. a LIBERO source checkout and simulator dependencies;
-4. the checkpoint and matching `dataset_stats.json` from this repository.
+Prepare LIBERO and the Wan2.2 backbone:
 
-The accelerated AC-Stream backend was validated with:
+```bash
+git clone https://github.com/Lifelong-Robot-Learning/LIBERO.git third_party/LIBERO
+uv pip install -e third_party/LIBERO --no-deps
 
-```text
-Python 3.10.20
-PyTorch 2.7.1+cu128
-Triton 3.3.1
-CUDA 12.8 runtime
-NVIDIA H100 80GB HBM3
-BF16
+uv run huggingface-cli download Wan-AI/Wan2.2-TI2V-5B \
+  --local-dir checkpoints/Wan2.2-TI2V-5B
 ```
 
-It uses static full-graph `torch.compile`, Inductor CUDA Graph Trees, prompt cross-attention K/V caching, attention-mask and schedule caching, and D0/D8 prewarming. Compilation or prewarming failure is reported instead of silently falling back to eager execution.
-
-## Download
+## Download checkpoints
 
-Install the Hugging Face CLI, authenticate if required, and download the repository:
+Download both released checkpoints:
 
 ```bash
 hf download SJTU-DENG-Lab/StreamWAM \
@@ -96,18 +95,24 @@ checkpoints/streamwam/
     └── dataset_stats.json
 ```
 
-## LIBERO evaluation
+## Run StreamWAM
 
-Set the external asset paths first:
+Evaluate all 40 LIBERO tasks once on four GPUs:
 
 ```bash
-export BACKBONE_PATH=/path/to/Wan2.2-TI2V-5B
-export LIBERO_HOME_PATH=/path/to/LIBERO
+PYTHON_BIN=.venv/bin/python \
+GPU_IDS=0,1,2,3 \
+BACKBONE_PATH="$PWD/checkpoints/Wan2.2-TI2V-5B" \
+LIBERO_HOME_PATH="$PWD/third_party/LIBERO" \
+CHECKPOINT_PATH="$PWD/checkpoints/streamwam/ac-stream/model.pt" \
+STATS_PATH="$PWD/checkpoints/streamwam/ac-stream/dataset_stats.json" \
+  bash examples/libero/scripts/launch_streamwam_libero_ac_stream_4gpu.sh \
+  --ac-stream-accelerated
 ```
 
-### Joint CD
+The launcher evaluates one trial for every task in `libero_spatial`, `libero_object`, `libero_goal`, and `libero_10`. GPU IDs can be changed through `GPU_IDS`.
 
-The following evaluates all 40 LIBERO tasks once with four persistent workers:
+## Run FastWAM-Joint-CD
 
 ```bash
 python examples/libero/multigpu_rollout.py \
@@ -117,9 +122,9 @@ python examples/libero/multigpu_rollout.py \
   --config examples/libero/configs/recipes/streamwam_libero_joint_cd_wan22_5b.yaml \
   --checkpoint-format fastwam \
   --checkpoint checkpoints/streamwam/joint-cd/model.pt \
-  --backbone-path "$BACKBONE_PATH" \
+  --backbone-path checkpoints/Wan2.2-TI2V-5B \
   --stats-path checkpoints/streamwam/joint-cd/dataset_stats.json \
-  --libero-home "$LIBERO_HOME_PATH" \
+  --libero-home third_party/LIBERO \
   --num-steps-wait 30 \
   --replan-steps 16 \
   --num-inference-steps 1 \
@@ -129,64 +134,13 @@ python examples/libero/multigpu_rollout.py \
   --save-video
 ```
 
-### AC-Stream eager
-
-```bash
-python examples/libero/multigpu_rollout.py \
-  --gpus 0,1,2,3 \
-  --suites libero_spatial,libero_object,libero_goal,libero_10 \
-  --num-trials 1 \
-  --config examples/libero/configs/recipes/streamwam_libero_ac_stream_wan22_5b.yaml \
-  --checkpoint-format fastwam \
-  --checkpoint checkpoints/streamwam/ac-stream/model.pt \
-  --backbone-path "$BACKBONE_PATH" \
-  --stats-path checkpoints/streamwam/ac-stream/dataset_stats.json \
-  --libero-home "$LIBERO_HOME_PATH" \
-  --num-steps-wait 30 \
-  --replan-steps 16 \
-  --num-inference-steps 1 \
-  --sampling-method ac-stream \
-  --fixed-seed \
-  --mujoco-gl egl \
-  --save-video
-```
-
-### AC-Stream accelerated
-
-Use the same checkpoint and append `--ac-stream-accelerated`:
-
-```bash
-python examples/libero/multigpu_rollout.py \
-  --gpus 0,1,2,3 \
-  --suites libero_spatial,libero_object,libero_goal,libero_10 \
-  --num-trials 1 \
-  --config examples/libero/configs/recipes/streamwam_libero_ac_stream_wan22_5b.yaml \
-  --checkpoint-format fastwam \
-  --checkpoint checkpoints/streamwam/ac-stream/model.pt \
-  --backbone-path "$BACKBONE_PATH" \
-  --stats-path checkpoints/streamwam/ac-stream/dataset_stats.json \
-  --libero-home "$LIBERO_HOME_PATH" \
-  --num-steps-wait 30 \
-  --replan-steps 16 \
-  --num-inference-steps 1 \
-  --sampling-method ac-stream \
-  --ac-stream-accelerated \
-  --fixed-seed \
-  --mujoco-gl egl \
-  --save-video
-```
-
-For the validated accelerated runtime, the final report should show one Dynamo graph, zero recompiles, zero Inductor CUDA Graph skips, and successful D0/D8 prewarming. Raw inference averages include startup effects; use the reported steady-state D8 latency for backend comparisons.
+For more evaluation options, see the [LIBERO guide](https://github.com/SJTU-DENG-Lab/StreamWAM/blob/main/examples/libero/LIBERO.md).
 
-## Checkpoint loading
+## License
 
-Use `--checkpoint-format fastwam` for both models. StreamWAM validates the video expert, action expert, and proprioception encoder key sets and tensor shapes before copying weights. A partial or incompatible checkpoint fails before mutating the model.
+Released under the [Apache License 2.0](https://github.com/SJTU-DENG-Lab/StreamWAM/blob/main/LICENSE).
 
-The matching statistics file is required for LIBERO state normalization and action denormalization. Do not mix statistics between `joint-cd` and `ac-stream`.
+## Acknowledgements
 
-## Scope and limitations
+StreamWAM builds on ideas and open-source work from [FastWAM](https://github.com/yuantianyuan01/FastWAM), [StarWAM](https://github.com/shaohua-pan/StarWAM), [LIBERO](https://github.com/Lifelong-Robot-Learning/LIBERO), and [Wan2.2](https://github.com/Wan-Video/Wan2.2).
 
-- These checkpoints are provided for LIBERO evaluation.
-- Wan2.2 backbone assets and LIBERO are external dependencies and are not redistributed here.
-- AC-Stream accelerated performance depends on GPU architecture, PyTorch/Triton versions, compilation cache state, and simulator workload.
-- The accelerated backend changes execution strategy but uses the same AC-Stream checkpoint and inference semantics.