# roboparty/ufo architecture

> Architecture diagram of the GitHub repository roboparty/ufo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roboparty/ufo
- Repository: https://github.com/roboparty/ufo

## Overview

UFO is a humanoid-control research framework. Its principal workflow is to prepare robot-aware motion data and configuration, train an unsupervised reinforcement-learning policy in the MJLab environment, then run tracking, goal, or reward inference and optionally export an ONNX policy. The graph preserves the README’s data-import and robot-bring-up capabilities as well as the inference branches. Some subsystem internals are unsampled; those links are omitted rather than inferred.

Main entry points: [`humanoidverse/training/workspace.py`](https://github.com/roboparty/ufo/blob/main/humanoidverse/training/workspace.py) (Training workspace), [`humanoidverse/tracking_inference.py`](https://github.com/roboparty/ufo/blob/main/humanoidverse/tracking_inference.py) (Tracking inference), [`humanoidverse/reward_inference.py`](https://github.com/roboparty/ufo/blob/main/humanoidverse/reward_inference.py) (Reward inference), [`humanoidverse/goal_inference.py`](https://github.com/roboparty/ufo/blob/main/humanoidverse/goal_inference.py) (Goal inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_robot["Data and robots"]
  node_robot_inspect["Robot inspection<br/>[robot_inspect.py]"]
  node_robot_spec["Robot specifications"]
  node_data_build["Motion data build<br/>[data_build.py]"]
  node_motion_data["Motion data handling"]
end

subgraph group_learning["Training"]
  node_train["Training entrypoint<br/>[train.py]"]
  node_workspace["Training workspace<br/>[workspace.py]"]
  node_mjlab_env["MJLab environment"]
  node_rl_agents["RL agent algorithms"]
  node_replay[("Replay buffers<br/>[trajectory.py]")]
  node_observations["Motion observations"]
end

subgraph group_inference["Inference"]
  node_tracking["Tracking inference"]
  node_goal["Goal inference<br/>[goal_inference.py]"]
  node_reward["Reward inference"]
  node_inference_utils["MJLab inference utilities"]
  node_checkpoint_loader["Checkpoint loading<br/>[load_utils.py]"]
  node_reward_relabel["Reward relabeling"]
end

subgraph group_export["Export"]
  node_backward_encoder["Backward encoder export"]
end

node_user(("Engineer"))

node_user -->|"inspect robot"| node_robot_inspect
node_robot_inspect -->|"draft config"| node_robot_spec
node_user -->|"build manifest"| node_data_build
node_data_build -->|"prepare motion data"| node_motion_data
node_user -->|"start training"| node_train
node_train -.->|"configure training"| node_workspace
node_workspace -->|"build environment"| node_mjlab_env
node_workspace -->|"run agent"| node_rl_agents
node_workspace -->|"use replay buffer"| node_replay
node_mjlab_env -->|"compute observations"| node_observations
node_user -->|"run tracking"| node_tracking
node_user -->|"run goal inference"| node_goal
node_user -->|"run reward inference"| node_reward
node_tracking -->|"use utilities"| node_inference_utils
node_tracking -->|"load checkpoint"| node_checkpoint_loader
node_tracking -->|"export policy"| node_backward_encoder
node_goal -->|"use utilities"| node_inference_utils
node_goal -->|"load checkpoint"| node_checkpoint_loader
node_reward -->|"use utilities"| node_inference_utils
node_reward -->|"load checkpoint"| node_checkpoint_loader
node_reward -->|"relabel rewards"| node_reward_relabel

click node_robot_inspect "https://github.com/roboparty/ufo/blob/main/humanoidverse/tools/robot_inspect.py"
click node_robot_spec "https://github.com/roboparty/ufo/tree/main/humanoidverse/utils/robot_spec"
click node_data_build "https://github.com/roboparty/ufo/blob/main/humanoidverse/tools/data_build.py"
click node_motion_data "https://github.com/roboparty/ufo/tree/main/humanoidverse/utils/motion_data"
click node_train "https://github.com/roboparty/ufo/blob/main/humanoidverse/train.py"
click node_workspace "https://github.com/roboparty/ufo/blob/main/humanoidverse/training/workspace.py"
click node_mjlab_env "https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/envs/humanoidverse_mjlab.py"
click node_rl_agents "https://github.com/roboparty/ufo/tree/main/humanoidverse/agents"
click node_replay "https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/buffers/trajectory.py"
click node_observations "https://github.com/roboparty/ufo/blob/main/humanoidverse/envs/motion_observations.py"
click node_tracking "https://github.com/roboparty/ufo/blob/main/humanoidverse/tracking_inference.py"
click node_goal "https://github.com/roboparty/ufo/blob/main/humanoidverse/goal_inference.py"
click node_reward "https://github.com/roboparty/ufo/blob/main/humanoidverse/reward_inference.py"
click node_inference_utils "https://github.com/roboparty/ufo/blob/main/humanoidverse/mjlab_inference_utils.py"
click node_checkpoint_loader "https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/load_utils.py"
click node_reward_relabel "https://github.com/roboparty/ufo/blob/main/humanoidverse/mjlab_reward_relabel.py"
click node_backward_encoder "https://github.com/roboparty/ufo/blob/main/humanoidverse/export/backward_encoder.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_robot_inspect,node_robot_spec,node_data_build,node_motion_data toneBlue
class node_train,node_workspace,node_mjlab_env,node_rl_agents,node_replay,node_observations toneAmber
class node_tracking,node_goal,node_reward,node_inference_utils,node_checkpoint_loader,node_reward_relabel toneMint
class node_backward_encoder toneRose
class node_user toneIndigo
```

## Components

### Data and robots

- [Robot inspection](https://github.com/roboparty/ufo/blob/main/humanoidverse/tools/robot_inspect.py): `humanoidverse/tools/robot_inspect.py`
- [Robot specifications](https://github.com/roboparty/ufo/tree/main/humanoidverse/utils/robot_spec): `humanoidverse/utils/robot_spec`
- [Motion data build](https://github.com/roboparty/ufo/blob/main/humanoidverse/tools/data_build.py): `humanoidverse/tools/data_build.py`
- [Motion data handling](https://github.com/roboparty/ufo/tree/main/humanoidverse/utils/motion_data): `humanoidverse/utils/motion_data`

### Training

- [Training entrypoint](https://github.com/roboparty/ufo/blob/main/humanoidverse/train.py): `humanoidverse/train.py`
- [Training workspace](https://github.com/roboparty/ufo/blob/main/humanoidverse/training/workspace.py): `humanoidverse/training/workspace.py`
- [MJLab environment](https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/envs/humanoidverse_mjlab.py): `humanoidverse/agents/envs/humanoidverse_mjlab.py`
- [RL agent algorithms](https://github.com/roboparty/ufo/tree/main/humanoidverse/agents): `humanoidverse/agents`
- [Replay buffers](https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/buffers/trajectory.py): `humanoidverse/agents/buffers/trajectory.py`
- [Motion observations](https://github.com/roboparty/ufo/blob/main/humanoidverse/envs/motion_observations.py): `humanoidverse/envs/motion_observations.py`

### Inference

- [Tracking inference](https://github.com/roboparty/ufo/blob/main/humanoidverse/tracking_inference.py): `humanoidverse/tracking_inference.py`
- [Goal inference](https://github.com/roboparty/ufo/blob/main/humanoidverse/goal_inference.py): `humanoidverse/goal_inference.py`
- [Reward inference](https://github.com/roboparty/ufo/blob/main/humanoidverse/reward_inference.py): `humanoidverse/reward_inference.py`
- [MJLab inference utilities](https://github.com/roboparty/ufo/blob/main/humanoidverse/mjlab_inference_utils.py): `humanoidverse/mjlab_inference_utils.py`
- [Checkpoint loading](https://github.com/roboparty/ufo/blob/main/humanoidverse/agents/load_utils.py): `humanoidverse/agents/load_utils.py`
- [Reward relabeling](https://github.com/roboparty/ufo/blob/main/humanoidverse/mjlab_reward_relabel.py): `humanoidverse/mjlab_reward_relabel.py`

### Export

- [Backward encoder export](https://github.com/roboparty/ufo/blob/main/humanoidverse/export/backward_encoder.py): `humanoidverse/export/backward_encoder.py`

### Other components

- **Engineer**

## Connections

- Engineer → Robot inspection: inspect robot (evidence: `README.md`)
- Robot inspection → Robot specifications: draft config (evidence: `humanoidverse/tools/robot_inspect.py`)
- Engineer → Motion data build: build manifest (evidence: `README.md`)
- Motion data build → Motion data handling: prepare motion data (evidence: `README.md`)
- Engineer → Training entrypoint: start training (evidence: `README.md`)
- Training entrypoint → Training workspace: configure training
- Training workspace → MJLab environment: build environment (evidence: `humanoidverse/training/workspace.py`)
- Training workspace → RL agent algorithms: run agent (evidence: `humanoidverse/training/workspace.py`)
- Training workspace → Replay buffers: use replay buffer (evidence: `humanoidverse/training/workspace.py`)
- MJLab environment → Motion observations: compute observations (evidence: `humanoidverse/agents/envs/humanoidverse_mjlab.py`)
- Engineer → Tracking inference: run tracking (evidence: `README.md`)
- Engineer → Goal inference: run goal inference (evidence: `README.md`)
- Engineer → Reward inference: run reward inference (evidence: `README.md`)
- Tracking inference → MJLab inference utilities: use utilities (evidence: `humanoidverse/tracking_inference.py`)
- Tracking inference → Checkpoint loading: load checkpoint (evidence: `humanoidverse/tracking_inference.py`)
- Tracking inference → Backward encoder export: export policy (evidence: `humanoidverse/tracking_inference.py`)
- Goal inference → MJLab inference utilities: use utilities (evidence: `humanoidverse/goal_inference.py`)
- Goal inference → Checkpoint loading: load checkpoint (evidence: `humanoidverse/goal_inference.py`)
- Reward inference → MJLab inference utilities: use utilities (evidence: `humanoidverse/reward_inference.py`)
- Reward inference → Checkpoint loading: load checkpoint (evidence: `humanoidverse/reward_inference.py`)
- Reward inference → Reward relabeling: relabel rewards (evidence: `humanoidverse/reward_inference.py`)
