# dstate/lbp architecture

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

- Interactive diagram: https://gitdiagram.com/dstate/lbp
- Repository: https://github.com/dstate/lbp

## Overview

LBP learns a LIBERO robot policy that plans backward from a latent final goal, predicts intermediate subgoals, then generates chunked actions conditioned on those goals. The README’s workflow is dataset conversion, planner training, policy training, and LIBERO evaluation; the graph focuses on runtime components and the policy-training entry point. Some planner-training and evaluation wiring is documented but its implementation was not sampled, so those links are limited to supported references.

Main entry points: [`train_policy_sim.py`](https://github.com/dstate/lbp/blob/main/train_policy_sim.py) (Policy trainer), [`models/LBP.py`](https://github.com/dstate/lbp/blob/main/models/LBP.py) (LBP policy), [`eval_libero.py`](https://github.com/dstate/lbp/blob/main/eval_libero.py) (LIBERO evaluator), [`datasets/LiberoEngine.py`](https://github.com/dstate/lbp/blob/main/datasets/LiberoEngine.py) (Dataset engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_converter["HDF5 converter<br/>[hdf52hdf5.py]"]
  node_hdf5[("LIBERO trajectories")]
  node_libero_data["Dataset engine<br/>[LiberoEngine.py]"]
end

subgraph group_planning["Latent planning"]
  node_planner["Latent planner<br/>[MidPlanner.py]"]
  node_decisionnce["DecisionNCE encoder"]
end

subgraph group_policy["Policy model"]
  node_policy["LBP policy<br/>[LBP.py]"]
  node_fusion["Goal attention<br/>[CrossAttn.py]"]
  node_vision["FiLM vision encoder<br/>[ResNet.py]"]
  node_action["Action heads<br/>[ActionHead.py]"]
  node_mlp["Residual MLP<br/>[MlpResNet.py]"]
end

subgraph group_learning["Training"]
  node_trainer["Policy trainer"]
  node_wrapper["Model wrapper<br/>[wrapper.py]"]
  node_scheduler["LR scheduler<br/>[scheduler.py]"]
  node_logger["Training logger<br/>[logger.py]"]
  node_checkpoint["Checkpoint utilities<br/>[tools.py]"]
end

subgraph group_runtime["Robot evaluation"]
  node_evaluator["LIBERO evaluator<br/>[eval_libero.py]"]
  node_libero["LIBERO simulator"]
end

node_user(("Researcher"))

node_user -->|"converts dataset"| node_converter
node_converter -->|"writes trajectories"| node_hdf5
node_hdf5 -.->|"loads trajectories"| node_libero_data
node_user -->|"trains policy"| node_trainer
node_trainer -->|"creates data engine"| node_libero_data
node_trainer -->|"creates model"| node_policy
node_policy -->|"generates subgoals"| node_planner
node_planner -->|"encodes image and language"| node_decisionnce
node_policy -->|"fuses goal latents"| node_fusion
node_policy -->|"encodes observations"| node_vision
node_policy -->|"predicts actions"| node_action
node_action -->|"uses residual network"| node_mlp
node_trainer -->|"wraps model"| node_wrapper
node_trainer -->|"updates learning rate"| node_scheduler
node_trainer -->|"logs metrics"| node_logger
node_trainer -->|"saves checkpoints"| node_checkpoint
node_user -->|"evaluates policy"| node_evaluator
node_evaluator -->|"runs benchmark"| node_libero
node_evaluator -->|"imports dataset package"| node_libero_data
node_evaluator -->|"imports model package"| node_policy

click node_converter "https://github.com/dstate/lbp/blob/main/hdf52hdf5.py"
click node_libero_data "https://github.com/dstate/lbp/blob/main/datasets/LiberoEngine.py"
click node_planner "https://github.com/dstate/lbp/blob/main/models/MidPlanner.py"
click node_policy "https://github.com/dstate/lbp/blob/main/models/LBP.py"
click node_fusion "https://github.com/dstate/lbp/blob/main/models/components/CrossAttn.py"
click node_vision "https://github.com/dstate/lbp/blob/main/models/components/ResNet.py"
click node_action "https://github.com/dstate/lbp/blob/main/models/components/ActionHead.py"
click node_mlp "https://github.com/dstate/lbp/blob/main/models/components/MlpResNet.py"
click node_trainer "https://github.com/dstate/lbp/blob/main/train_policy_sim.py"
click node_wrapper "https://github.com/dstate/lbp/blob/main/utils/wrapper.py"
click node_scheduler "https://github.com/dstate/lbp/blob/main/utils/scheduler.py"
click node_logger "https://github.com/dstate/lbp/blob/main/utils/logger.py"
click node_checkpoint "https://github.com/dstate/lbp/blob/main/utils/tools.py"
click node_evaluator "https://github.com/dstate/lbp/blob/main/eval_libero.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_converter,node_hdf5,node_libero_data toneBlue
class node_planner,node_decisionnce toneAmber
class node_policy,node_fusion,node_vision,node_action,node_mlp toneMint
class node_trainer,node_wrapper,node_scheduler,node_logger,node_checkpoint toneRose
class node_evaluator,node_libero,node_user toneIndigo
```

## Components

### Data preparation

- [HDF5 converter](https://github.com/dstate/lbp/blob/main/hdf52hdf5.py): `hdf52hdf5.py`
- **LIBERO trajectories**
- [Dataset engine](https://github.com/dstate/lbp/blob/main/datasets/LiberoEngine.py): `datasets/LiberoEngine.py`

### Latent planning

- [Latent planner](https://github.com/dstate/lbp/blob/main/models/MidPlanner.py): `models/MidPlanner.py`
- **DecisionNCE encoder**

### Policy model

- [LBP policy](https://github.com/dstate/lbp/blob/main/models/LBP.py): `models/LBP.py`
- [Goal attention](https://github.com/dstate/lbp/blob/main/models/components/CrossAttn.py): `models/components/CrossAttn.py`
- [FiLM vision encoder](https://github.com/dstate/lbp/blob/main/models/components/ResNet.py): `models/components/ResNet.py`
- [Action heads](https://github.com/dstate/lbp/blob/main/models/components/ActionHead.py): `models/components/ActionHead.py`
- [Residual MLP](https://github.com/dstate/lbp/blob/main/models/components/MlpResNet.py): `models/components/MlpResNet.py`

### Training

- [Policy trainer](https://github.com/dstate/lbp/blob/main/train_policy_sim.py): `train_policy_sim.py`
- [Model wrapper](https://github.com/dstate/lbp/blob/main/utils/wrapper.py): `utils/wrapper.py`
- [LR scheduler](https://github.com/dstate/lbp/blob/main/utils/scheduler.py): `utils/scheduler.py`
- [Training logger](https://github.com/dstate/lbp/blob/main/utils/logger.py): `utils/logger.py`
- [Checkpoint utilities](https://github.com/dstate/lbp/blob/main/utils/tools.py): `utils/tools.py`

### Robot evaluation

- [LIBERO evaluator](https://github.com/dstate/lbp/blob/main/eval_libero.py): `eval_libero.py`
- **LIBERO simulator**

### Other components

- **Researcher**

## Connections

- Researcher → HDF5 converter: converts dataset (evidence: `README.md`)
- HDF5 converter → LIBERO trajectories: writes trajectories (evidence: `README.md`)
- LIBERO trajectories → Dataset engine: loads trajectories
- Researcher → Policy trainer: trains policy (evidence: `README.md`)
- Policy trainer → Dataset engine: creates data engine (evidence: `train_policy_sim.py`)
- Policy trainer → LBP policy: creates model (evidence: `train_policy_sim.py`)
- LBP policy → Latent planner: generates subgoals (evidence: `models/LBP.py`)
- Latent planner → DecisionNCE encoder: encodes image and language (evidence: `models/MidPlanner.py`)
- LBP policy → Goal attention: fuses goal latents (evidence: `models/LBP.py`)
- LBP policy → FiLM vision encoder: encodes observations (evidence: `models/LBP.py`)
- LBP policy → Action heads: predicts actions (evidence: `models/LBP.py`)
- Action heads → Residual MLP: uses residual network (evidence: `models/components/ActionHead.py`)
- Policy trainer → Model wrapper: wraps model (evidence: `train_policy_sim.py`)
- Policy trainer → LR scheduler: updates learning rate (evidence: `train_policy_sim.py`)
- Policy trainer → Training logger: logs metrics (evidence: `train_policy_sim.py`)
- Policy trainer → Checkpoint utilities: saves checkpoints (evidence: `train_policy_sim.py`)
- Researcher → LIBERO evaluator: evaluates policy (evidence: `README.md`)
- LIBERO evaluator → LIBERO simulator: runs benchmark (evidence: `README.md`)
- LIBERO evaluator → Dataset engine: imports dataset package (evidence: `eval_libero.py`)
- LIBERO evaluator → LBP policy: imports model package (evidence: `eval_libero.py`)
