README.md

---
license: mit
library_name: pytorch
language:
- en
tags:
- robotics
- humanoid
- unitree-g1
- diffusion-policy
- text-conditioned-control
- mujoco
- motionclip
- predictive-control
inference: false
---

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/">
    <img src="assets/predactor-readme-banner.svg" width="1400" alt="PredActor: predictive action diffusion for steerable onboard humanoid control.">
  </a>
</p>

<h1 align="center">PredActor Evaluation Artifacts</h1>

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/"><img alt="Project website" src="https://img.shields.io/badge/Project_Website-E7A12B?style=flat-square&logo=googlechrome&logoColor=171817"></a>
  <a href="https://arxiv.org/abs/2609.24840"><img alt="arXiv paper" src="https://img.shields.io/badge/arXiv-2609.24840-B31B1B?style=flat-square&logo=arxiv&logoColor=white"></a>
  <a href="https://github.com/MasterYip/PredActor"><img alt="Evaluation code" src="https://img.shields.io/badge/GitHub-Evaluation_Code-5A5A57?style=flat-square&logo=github&logoColor=white"></a>
  <a href="https://huggingface.co/MasterYip/PredActor_Artifacts"><img alt="Hugging Face artifacts" src="https://img.shields.io/badge/Hugging_Face-Model_Artifacts-FFD21E?style=flat-square&logo=huggingface&logoColor=171817"></a>
  <a href="https://github.com/MasterYip/PredActor/blob/master/LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/License-MIT-ECECEA?style=flat-square&labelColor=2F2F2D&color=ECECEA"></a>
</p>

<p align="center">
  <img src="assets/institution-strip.svg" width="100%" alt="Harbin Institute of Technology, Shanghai Innovation Institute, RoboParty Lab, Tsinghua University, Shanghai Jiao Tong University, HexLab, and SFTR">
</p>

Official evaluation checkpoints for
[PredActor](https://github.com/MasterYip/PredActor), a predictive action
diffusion controller for steerable Unitree G1 locomotion. The model jointly
predicts future states and actions, uses its internal state trajectory for
guidance, and directly executes the selected 29-DoF action.

## Overview

<p align="center">
  <a href="https://masteryip.github.io/predactor.github.io/">
    <img src="assets/predactor-preview.png" width="100%" alt="PredActor method and hardware overview">
  </a>
</p>

This repository contains the two learned artifacts required by the public
MuJoCo evaluation path:

- the released PDP051 text-conditioned PredActor policy;
- the fine-tuned G1 MotionCLIP encoder used for semantic conditioning.

Source code, the browser-based evaluator, and G1 robot assets are maintained in
the [public PredActor repository](https://github.com/MasterYip/PredActor).
Training datasets, experiment outputs, hardware deployment bundles, and
additional checkpoints are not included here.

## Quick Evaluation

Install [uv](https://docs.astral.sh/uv/), then run:

```bash
git clone https://github.com/MasterYip/PredActor.git
cd PredActor
uv sync --locked
uv run --locked python scripts/hf_download.py --filter checkpoints
uv run --locked predactor-eval
```

The downloader recreates the expected layout under the Git-ignored
`Artifacts/` directory and verifies the published byte sizes and SHA-256
identities. The evaluator opens `http://127.0.0.1:8765/`, uses CUDA when
available, and otherwise falls back to CPU.

## Released Artifacts

| Artifact | Role | Size | SHA-256 |
|---|---|---:|---|
| `checkpoints/predactor/pdp051/latest.ckpt` | Text-conditioned PredActor policy | 49,212,894 bytes | `2d963b32786f2989c6472726df9fcfe6b385590127e12e1f549a4b7d77488b2e` |
| `checkpoints/motionclip/g1-model-xyz-clip/checkpoint_0100.pth.tar` | Fine-tuned G1 MotionCLIP encoder | 542,749,069 bytes | `66a127df4958b346089b2020f2705c7456d9db0ee8b4bd9518608b708b35fc3c` |

`SHA256SUMS` records the same checkpoint identities in a format accepted by
`sha256sum --check`.

## Repository Layout

```text
PredActor_Artifacts/
|-- README.md
|-- SHA256SUMS
|-- assets/
|   |-- predactor-readme-banner.svg
|   |-- predactor-preview.png
|   `-- institution-strip.svg
|-- checkpoints/
|   |-- predactor/pdp051/latest.ckpt
|   `-- motionclip/g1-model-xyz-clip/checkpoint_0100.pth.tar
`-- dataset/
    `-- README.md
```

`dataset/` is reserved for future public datasets and currently contains no
dataset payloads.

## Model Details

- **Policy:** PDP051 using the public `g1prdp_cond_diffuse` evaluation profile.
- **Robot:** Unitree G1 with 29 actuated degrees of freedom.
- **Inputs:** proprioceptive observation history, a 512-dimensional semantic
  condition, and optional whole-body guidance commands.
- **Outputs:** a denoised action trajectory from which the current joint action
  is selected for direct execution.
- **State prediction:** future states remain internal to the policy and provide
  a differentiable target for classifier guidance.
- **Public runtime:** local MuJoCo evaluation through the PredActor Web UI.

## Intended Use

These artifacts support research reproduction and local simulation evaluation
of the released PredActor controller. They are intended for use with the
hash-pinned public code and configuration. The MotionCLIP checkpoint is the
semantic encoder expected by the released policy and should not be substituted
without revalidating compatibility.

## Limitations and Safety

- The public release is an evaluation package, not a training distribution.
- MuJoCo startup demonstrates software and checkpoint compatibility; it does
  not establish hardware safety or guarantee locomotion quality in a new
  environment.
- Real-robot deployment requires separate control, safety, and hardware
  validation that is outside this repository.
- PyTorch checkpoints use pickle-compatible deserialization. Load only files
  whose hashes match the published values and only from trusted sources.
- Performance may change with simulator, driver, GPU, or dependency versions
  outside the locked public environment.

## Evaluation and Demos

The [PredActor project page](https://masteryip.github.io/predactor.github.io/)
contains the method overview and simulation and hardware demonstrations. The
[public code repository](https://github.com/MasterYip/PredActor) provides the
reproducible MuJoCo evaluation workflow.

## License

PredActor is released under the
[MIT License](https://github.com/MasterYip/PredActor/blob/master/LICENSE).
Third-party dependencies and robot assets remain subject to their respective
upstream terms.

## Citation

```bibtex
@misc{ye2026predactorpredictiveactiondiffusion,
  title={PredActor: Predictive Action Diffusion for Steerable Onboard Humanoid Control},
  author={Lei Ye and Haibo Gao and Yitang Li and Peng Xu and Zetong Jing and Junhan Sun and Fanrong Dong and Ziqi Han and Xue Wang and Jianhua Sun and Cewu Lu and Hao Zhao and Liang Ding},
  year={2026},
  eprint={2609.24840},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2609.24840},
}
```