# allenai/molmospaces architecture

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

- Interactive diagram: https://gitdiagram.com/allenai/molmospaces
- Repository: https://github.com/allenai/molmospaces

## Overview

MolmoSpaces is a robotics simulation ecosystem for manipulation and navigation, supporting benchmark evaluation, policy execution, and trajectory generation. A central workflow configures a data-generation run, samples tasks, rolls policies through simulated environments, and prepares episode data for saving. The package also includes benchmark evaluation, robot control and planning, grasp generation, house generation, and rendering. README claims guide capability coverage; sampled source confirms parts of data generation, task behavior, camera setup, and remote policy clients, but not every subsystem’s wiring.

Main entry points: [`molmo_spaces/env/env.py`](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/env.py) (Simulation environment), [`molmo_spaces/data_generation/pipeline.py`](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/pipeline.py) (Rollout runner), [`molmo_spaces/data_generation/main.py`](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/main.py) (Data generation), [`molmo_spaces/tasks/opening_tasks.py`](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/tasks/opening_tasks.py) (Task implementations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runs["Runs and benchmarks"]
  node_datagen["Data generation<br/>[main.py]"]
  node_configs["Experiment configs<br/>[config_registry.py]"]
  node_rollouts["Rollout runner<br/>[pipeline.py]"]
  node_episodes["Episode data"]
  node_evaluation["Benchmark evaluation<br/>[eval_main.py]"]
  node_evalrunner["Evaluation runner"]
end

subgraph group_simulation["Simulation and tasks"]
  node_samplers["Task samplers<br/>[task_sampler.py]"]
  node_task["Task implementations<br/>[opening_tasks.py]"]
  node_environment["Simulation environment<br/>[env.py]"]
  node_objects["Scene objects<br/>[object_manager.py]"]
  node_cameras["Camera setup<br/>[camera_manager.py]"]
  node_renderer["Rendering"]
end

subgraph group_robotics["Robotics and policies"]
  node_robots["Robot models<br/>[abstract.py]"]
  node_controllers["Robot controllers<br/>[abstract.py]"]
  node_policies["Policy implementations<br/>[base_policy.py]"]
  node_learned["Learned policies"]
  node_planner["Motion planning<br/>[abstract.py]"]
  node_grasp["Grasp generation"]
end

subgraph group_assets["Assets and tools"]
  node_housegen["House generation"]
  node_resources["Simulation assets"]
  node_isaac["Isaac assets<br/>[main.py]"]
  node_maniskill["ManiSkill assets<br/>[main.py]"]
end

node_user(("Researcher"))
node_policy_server(("Remote policy service"))

node_user -->|"starts run"| node_datagen
node_datagen -->|"resolves config"| node_configs
node_datagen -->|"starts rollouts"| node_rollouts
node_rollouts -->|"samples tasks"| node_samplers
node_rollouts -->|"runs policy"| node_policies
node_samplers -->|"creates tasks"| node_task
node_task -->|"steps simulation"| node_environment
node_task -->|"queries objects"| node_objects
node_environment -->|"sets up cameras"| node_cameras
node_environment -->|"renders scene"| node_renderer
node_environment -->|"simulates robot"| node_robots
node_robots -->|"uses control"| node_controllers
node_policies -->|"includes implementations"| node_learned
node_learned -.->|"requests inference"| node_policy_server
node_policies -.->|"can use planning"| node_planner
node_rollouts -->|"prepares episode data"| node_episodes
node_user -->|"starts evaluation"| node_evaluation
node_evaluation -->|"runs evaluation"| node_evalrunner
node_evalrunner -->|"evaluates tasks"| node_samplers
node_grasp -.->|"finds objects"| node_objects
node_user -->|"generates grasps"| node_grasp
node_user -->|"builds houses"| node_housegen
node_user -->|"downloads assets"| node_isaac
node_user -->|"downloads assets"| node_maniskill
node_resources -.->|"supplies assets"| node_environment

click node_datagen "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/main.py"
click node_configs "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/config_registry.py"
click node_rollouts "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/pipeline.py"
click node_evaluation "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/evaluation/eval_main.py"
click node_evalrunner "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/evaluation/json_eval_runner.py"
click node_samplers "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/tasks/task_sampler.py"
click node_task "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/tasks/opening_tasks.py"
click node_environment "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/env.py"
click node_objects "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/object_manager.py"
click node_cameras "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/camera_manager.py"
click node_renderer "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/renderer/abstract_renderer.py"
click node_robots "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/robots/abstract.py"
click node_controllers "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/controllers/abstract.py"
click node_policies "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/policy/base_policy.py"
click node_learned "https://github.com/allenai/molmospaces/tree/main/molmo_spaces/policy/learned_policy"
click node_planner "https://github.com/allenai/molmospaces/blob/main/molmo_spaces/planner/abstract.py"
click node_grasp "https://github.com/allenai/molmospaces/tree/main/molmo_spaces/grasp_generation"
click node_housegen "https://github.com/allenai/molmospaces/tree/main/molmo_spaces/housegen"
click node_resources "https://github.com/allenai/molmospaces/tree/main/molmo_spaces/resources"
click node_isaac "https://github.com/allenai/molmospaces/blob/main/molmo_spaces_isaac/src/molmo_spaces_isaac/downloader/main.py"
click node_maniskill "https://github.com/allenai/molmospaces/blob/main/molmo_spaces_maniskill/src/molmo_spaces_maniskill/downloader/main.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_datagen,node_configs,node_rollouts,node_episodes,node_evaluation,node_evalrunner toneBlue
class node_samplers,node_task,node_environment,node_objects,node_cameras,node_renderer toneAmber
class node_robots,node_controllers,node_policies,node_learned,node_planner,node_grasp toneMint
class node_housegen,node_resources,node_isaac,node_maniskill toneRose
class node_user,node_policy_server toneIndigo
```

## Components

### Runs and benchmarks

- [Data generation](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/main.py): `molmo_spaces/data_generation/main.py`
- [Experiment configs](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/config_registry.py): `molmo_spaces/data_generation/config_registry.py`
- [Rollout runner](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/data_generation/pipeline.py): `molmo_spaces/data_generation/pipeline.py`
- **Episode data**
- [Benchmark evaluation](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/evaluation/eval_main.py): `molmo_spaces/evaluation/eval_main.py`
- [Evaluation runner](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/evaluation/json_eval_runner.py): `molmo_spaces/evaluation/json_eval_runner.py`

### Simulation and tasks

- [Task samplers](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/tasks/task_sampler.py): `molmo_spaces/tasks/task_sampler.py`
- [Task implementations](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/tasks/opening_tasks.py): `molmo_spaces/tasks/opening_tasks.py`
- [Simulation environment](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/env.py): `molmo_spaces/env/env.py`
- [Scene objects](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/object_manager.py): `molmo_spaces/env/object_manager.py`
- [Camera setup](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/env/camera_manager.py): `molmo_spaces/env/camera_manager.py`
- [Rendering](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/renderer/abstract_renderer.py): `molmo_spaces/renderer/abstract_renderer.py`

### Robotics and policies

- [Robot models](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/robots/abstract.py): `molmo_spaces/robots/abstract.py`
- [Robot controllers](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/controllers/abstract.py): `molmo_spaces/controllers/abstract.py`
- [Policy implementations](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/policy/base_policy.py): `molmo_spaces/policy/base_policy.py`
- [Learned policies](https://github.com/allenai/molmospaces/tree/main/molmo_spaces/policy/learned_policy): `molmo_spaces/policy/learned_policy`
- [Motion planning](https://github.com/allenai/molmospaces/blob/main/molmo_spaces/planner/abstract.py): `molmo_spaces/planner/abstract.py`
- [Grasp generation](https://github.com/allenai/molmospaces/tree/main/molmo_spaces/grasp_generation): `molmo_spaces/grasp_generation`

### Assets and tools

- [House generation](https://github.com/allenai/molmospaces/tree/main/molmo_spaces/housegen): `molmo_spaces/housegen`
- [Simulation assets](https://github.com/allenai/molmospaces/tree/main/molmo_spaces/resources): `molmo_spaces/resources`
- [Isaac assets](https://github.com/allenai/molmospaces/blob/main/molmo_spaces_isaac/src/molmo_spaces_isaac/downloader/main.py): `molmo_spaces_isaac/src/molmo_spaces_isaac/downloader/main.py`
- [ManiSkill assets](https://github.com/allenai/molmospaces/blob/main/molmo_spaces_maniskill/src/molmo_spaces_maniskill/downloader/main.py): `molmo_spaces_maniskill/src/molmo_spaces_maniskill/downloader/main.py`

### Other components

- **Researcher**
- **Remote policy service**

## Connections

- Researcher → Data generation: starts run
- Data generation → Experiment configs: resolves config
- Data generation → Rollout runner: starts rollouts
- Rollout runner → Task samplers: samples tasks
- Rollout runner → Policy implementations: runs policy
- Task samplers → Task implementations: creates tasks
- Task implementations → Simulation environment: steps simulation
- Task implementations → Scene objects: queries objects
- Simulation environment → Camera setup: sets up cameras
- Simulation environment → Rendering: renders scene
- Simulation environment → Robot models: simulates robot
- Robot models → Robot controllers: uses control
- Policy implementations → Learned policies: includes implementations
- Learned policies → Remote policy service: requests inference
- Policy implementations → Motion planning: can use planning
- Rollout runner → Episode data: prepares episode data
- Researcher → Benchmark evaluation: starts evaluation
- Benchmark evaluation → Evaluation runner: runs evaluation
- Evaluation runner → Task samplers: evaluates tasks
- Grasp generation → Scene objects: finds objects
- Researcher → Grasp generation: generates grasps
- Researcher → House generation: builds houses
- Researcher → Isaac assets: downloads assets
- Researcher → ManiSkill assets: downloads assets
- Simulation assets → Simulation environment: supplies assets