# amazon-far/holosoma architecture

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

- Interactive diagram: https://gitdiagram.com/amazon-far/holosoma
- Repository: https://github.com/amazon-far/holosoma

## Overview

Holosoma combines humanoid RL training, policy inference/deployment, and motion retargeting. The primary workflow configures a robot and task, trains a policy in a supported simulator, then evaluates or deploys it through the shared inference pipeline. Retargeting is a distinct motion-data-to-robot-motion branch that can support whole-body tracking. The graph preserves documented algorithm, simulator, and robot capabilities; unsampled subsystem links are limited to README-supported relationships or omitted.

Main entry points: [`src/holosoma/holosoma/envs/base_task/base_task.py`](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/base_task/base_task.py) (Task environments), [`src/holosoma/holosoma/simulator/mujoco/mujoco.py`](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/mujoco/mujoco.py) (MuJoCo backend), [`src/holosoma/holosoma/train_agent.py`](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/train_agent.py) (Training entry), [`src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py`](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py) (Motion retargeter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training and tasks"]
  node_train["Training entry<br/>[train_agent.py]"]
  node_task["Task environments<br/>[base_task.py]"]
  node_loco["Locomotion task"]
  node_wbt["Whole-body task<br/>[wbt_manager.py]"]
  node_managers["Task managers"]
  node_algo["PPO and FastSAC"]
end

subgraph group_simulation["Simulation"]
  node_sceneconfig["Scene configuration<br/>[scene.py]"]
  node_simconfig["Simulator configuration<br/>[simulator.py]"]
  node_simbase["Simulator interface<br/>[base_simulator.py]"]
  node_isaacgym["IsaacGym backend<br/>[isaacgym.py]"]
  node_mujoco["MuJoCo backend<br/>[mujoco.py]"]
  node_scene["MuJoCo scene builder<br/>[scene_manager.py]"]
  node_objects["Object registry<br/>[object_registry.py]"]
end

subgraph group_inference["Inference and control"]
  node_inferenceconfig["Inference presets<br/>[inference.py]"]
  node_runpolicy["Policy runner<br/>[run_policy.py]"]
  node_policy["Locomotion and WBT policies"]
  node_service["ROS2 policy service<br/>[service_node.py]"]
  node_robot["Robot control SDKs"]
end

subgraph group_retargeting["Motion retargeting"]
  node_motion["Motion retargeter"]
  node_conversion["Motion conversion"]
  node_evaluation["Retargeting evaluation"]
end

node_user(("Engineer"))
node_robotactor(("Simulated or real robot"))
node_humanmotion(("Human motion data"))

node_user -->|"configures and starts"| node_train
node_train -->|"trains"| node_task
node_task -.->|"specializes as"| node_loco
node_task -.->|"specializes as"| node_wbt
node_loco -->|"extends"| node_task
node_wbt -->|"uses base task"| node_task
node_task -.->|"uses"| node_managers
node_train -->|"trains with"| node_algo
node_train -->|"selects simulator"| node_simconfig
node_simconfig -.->|"configures"| node_simbase
node_sceneconfig -->|"configures scene"| node_scene
node_simbase -->|"implemented by"| node_mujoco
node_simbase -.->|"implemented by"| node_isaacgym
node_mujoco -->|"builds scene with"| node_scene
node_mujoco -->|"uses registry"| node_objects
node_user -->|"chooses policy settings"| node_inferenceconfig
node_inferenceconfig -.->|"configures"| node_runpolicy
node_runpolicy -.->|"runs"| node_policy
node_service -->|"builds and serves"| node_policy
node_policy -.->|"sends commands through"| node_robot
node_robot -.->|"controls"| node_robotactor
node_humanmotion -->|"provides motion data"| node_motion
node_motion -.->|"produces robot motion"| node_conversion
node_conversion -.->|"supports evaluation"| node_evaluation
node_motion -->|"evaluated by"| node_evaluation
node_evaluation -->|"evaluates in"| node_mujoco
node_motion -->|"uses simulator"| node_mujoco

click node_train "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/train_agent.py"
click node_task "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/base_task/base_task.py"
click node_loco "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/locomotion/locomotion_manager.py"
click node_wbt "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/wbt/wbt_manager.py"
click node_managers "https://github.com/amazon-far/holosoma/tree/main/src/holosoma/holosoma/managers"
click node_algo "https://github.com/amazon-far/holosoma/tree/main/src/holosoma/holosoma/agents"
click node_sceneconfig "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/config_types/scene.py"
click node_simconfig "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/config_types/simulator.py"
click node_simbase "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/base_simulator/base_simulator.py"
click node_isaacgym "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/isaacgym/isaacgym.py"
click node_mujoco "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/mujoco/mujoco.py"
click node_scene "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/mujoco/scene_manager.py"
click node_objects "https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/shared/object_registry.py"
click node_inferenceconfig "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference/config/config_values/inference.py"
click node_runpolicy "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference/run_policy.py"
click node_policy "https://github.com/amazon-far/holosoma/tree/main/src/holosoma_inference/holosoma_inference/policies"
click node_service "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference_service/holosoma_service/holosoma_service/policy_control/service_node.py"
click node_robot "https://github.com/amazon-far/holosoma/tree/main/src/holosoma_inference/holosoma_inference/sdk"
click node_motion "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py"
click node_conversion "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/data_conversion/convert_data_format_mj.py"
click node_evaluation "https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/evaluation/eval_retargeting.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_train,node_task,node_loco,node_wbt,node_managers,node_algo toneBlue
class node_sceneconfig,node_simconfig,node_simbase,node_isaacgym,node_mujoco,node_scene,node_objects toneAmber
class node_inferenceconfig,node_runpolicy,node_policy,node_service,node_robot toneMint
class node_motion,node_conversion,node_evaluation toneRose
class node_user,node_robotactor,node_humanmotion toneIndigo
```

## Components

### Training and tasks

- [Training entry](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/train_agent.py): `src/holosoma/holosoma/train_agent.py`
- [Task environments](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/base_task/base_task.py): `src/holosoma/holosoma/envs/base_task/base_task.py`
- [Locomotion task](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/locomotion/locomotion_manager.py): `src/holosoma/holosoma/envs/locomotion/locomotion_manager.py`
- [Whole-body task](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/envs/wbt/wbt_manager.py): `src/holosoma/holosoma/envs/wbt/wbt_manager.py`
- [Task managers](https://github.com/amazon-far/holosoma/tree/main/src/holosoma/holosoma/managers): `src/holosoma/holosoma/managers`
- [PPO and FastSAC](https://github.com/amazon-far/holosoma/tree/main/src/holosoma/holosoma/agents): `src/holosoma/holosoma/agents`

### Simulation

- [Scene configuration](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/config_types/scene.py): `src/holosoma/holosoma/config_types/scene.py`
- [Simulator configuration](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/config_types/simulator.py): `src/holosoma/holosoma/config_types/simulator.py`
- [Simulator interface](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/base_simulator/base_simulator.py): `src/holosoma/holosoma/simulator/base_simulator/base_simulator.py`
- [IsaacGym backend](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/isaacgym/isaacgym.py): `src/holosoma/holosoma/simulator/isaacgym/isaacgym.py`
- [MuJoCo backend](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/mujoco/mujoco.py): `src/holosoma/holosoma/simulator/mujoco/mujoco.py`
- [MuJoCo scene builder](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/mujoco/scene_manager.py): `src/holosoma/holosoma/simulator/mujoco/scene_manager.py`
- [Object registry](https://github.com/amazon-far/holosoma/blob/main/src/holosoma/holosoma/simulator/shared/object_registry.py): `src/holosoma/holosoma/simulator/shared/object_registry.py`

### Inference and control

- [Inference presets](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference/config/config_values/inference.py): `src/holosoma_inference/holosoma_inference/config/config_values/inference.py`
- [Policy runner](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference/run_policy.py): `src/holosoma_inference/holosoma_inference/run_policy.py`
- [Locomotion and WBT policies](https://github.com/amazon-far/holosoma/tree/main/src/holosoma_inference/holosoma_inference/policies): `src/holosoma_inference/holosoma_inference/policies`
- [ROS2 policy service](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_inference/holosoma_inference_service/holosoma_service/holosoma_service/policy_control/service_node.py): `src/holosoma_inference/holosoma_inference_service/holosoma_service/holosoma_service/policy_control/service_node.py`
- [Robot control SDKs](https://github.com/amazon-far/holosoma/tree/main/src/holosoma_inference/holosoma_inference/sdk): `src/holosoma_inference/holosoma_inference/sdk`

### Motion retargeting

- [Motion retargeter](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py): `src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py`
- [Motion conversion](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/data_conversion/convert_data_format_mj.py): `src/holosoma_retargeting/holosoma_retargeting/data_conversion/convert_data_format_mj.py`
- [Retargeting evaluation](https://github.com/amazon-far/holosoma/blob/main/src/holosoma_retargeting/holosoma_retargeting/evaluation/eval_retargeting.py): `src/holosoma_retargeting/holosoma_retargeting/evaluation/eval_retargeting.py`

### Other components

- **Engineer**
- **Simulated or real robot**
- **Human motion data**

## Connections

- Engineer → Training entry: configures and starts (evidence: `README.md`)
- Training entry → Task environments: trains (evidence: `README.md`)
- Task environments → Locomotion task: specializes as (evidence: `src/holosoma/holosoma/envs/locomotion/locomotion_manager.py`)
- Task environments → Whole-body task: specializes as (evidence: `src/holosoma/holosoma/envs/wbt/wbt_manager.py`)
- Locomotion task → Task environments: extends (evidence: `src/holosoma/holosoma/envs/locomotion/locomotion_manager.py`)
- Whole-body task → Task environments: uses base task (evidence: `src/holosoma/holosoma/envs/wbt/wbt_manager.py`)
- Task environments → Task managers: uses (evidence: `src/holosoma/holosoma/envs/base_task/base_task.py`)
- Training entry → PPO and FastSAC: trains with (evidence: `README.md`)
- Training entry → Simulator configuration: selects simulator (evidence: `README.md`)
- Simulator configuration → Simulator interface: configures
- Scene configuration → MuJoCo scene builder: configures scene (evidence: `src/holosoma/holosoma/simulator/mujoco/scene_manager.py`)
- Simulator interface → MuJoCo backend: implemented by (evidence: `src/holosoma/holosoma/simulator/mujoco/mujoco.py`)
- Simulator interface → IsaacGym backend: implemented by
- MuJoCo backend → MuJoCo scene builder: builds scene with (evidence: `src/holosoma/holosoma/simulator/mujoco/mujoco.py`)
- MuJoCo backend → Object registry: uses registry (evidence: `src/holosoma/holosoma/simulator/mujoco/mujoco.py`)
- Engineer → Inference presets: chooses policy settings (evidence: `README.md`)
- Inference presets → Policy runner: configures
- Policy runner → Locomotion and WBT policies: runs
- ROS2 policy service → Locomotion and WBT policies: builds and serves (evidence: `src/holosoma_inference/holosoma_inference_service/holosoma_service/holosoma_service/policy_control/service_node.py`)
- Locomotion and WBT policies → Robot control SDKs: sends commands through
- Robot control SDKs → Simulated or real robot: controls
- Human motion data → Motion retargeter: provides motion data (evidence: `README.md`)
- Motion retargeter → Motion conversion: produces robot motion
- Motion conversion → Retargeting evaluation: supports evaluation
- Motion retargeter → Retargeting evaluation: evaluated by (evidence: `src/holosoma_retargeting/holosoma_retargeting/evaluation/eval_retargeting.py`)
- Retargeting evaluation → MuJoCo backend: evaluates in (evidence: `src/holosoma_retargeting/holosoma_retargeting/evaluation/eval_retargeting.py`)
- Motion retargeter → MuJoCo backend: uses simulator (evidence: `src/holosoma_retargeting/holosoma_retargeting/src/interaction_mesh_retargeter.py`)
