# lucas-maes/le-wm architecture

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

- Interactive diagram: https://gitdiagram.com/lucas-maes/le-wm
- Repository: https://github.com/lucas-maes/le-wm

## Overview

LeWorldModel is a compact JEPA world-model implementation: training learns latent next-state predictions from pixel sequences, while evaluation uses a loaded model to score candidate action rollouts for planning in control environments. The repository’s main internal layer is the JEPA model, built from encoder, action-embedding, prediction, and projection components, with a Gaussian latent regularizer in the training objective. Hydra configuration selects datasets, model/training settings, environments, and planning solvers. Training and evaluation depend on stable-pretraining and stable-worldmodel for orchestration and environment services; those libraries are external. Evidence for unsampled config wiring comes from the README and config paths, not inspected config contents.

Main entry points: [`eval.py`](https://github.com/lucas-maes/le-wm/blob/main/eval.py) (Evaluation runner), [`train.py`](https://github.com/lucas-maes/le-wm/blob/main/train.py) (Training runner), [`jepa.py`](https://github.com/lucas-maes/le-wm/blob/main/jepa.py) (JEPA model), [`config/eval/solver`](https://github.com/lucas-maes/le-wm/tree/main/config/eval/solver) (Planning solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_train["Data and training"]
  node_dataset[("HDF5 datasets")]
  node_preprocessing["Data preprocessing<br/>[utils.py]"]
  node_training_runner["Training runner<br/>[train.py]"]
  node_training_framework["Training framework"]
  node_checkpoint_save["Checkpoint saving<br/>[utils.py]"]
end

subgraph group_model["JEPA model"]
  node_jepa["JEPA model<br/>[jepa.py]"]
  node_encoder["Image encoder<br/>[jepa.py]"]
  node_action_embedder["Action embedder<br/>[module.py]"]
  node_predictor["AR predictor<br/>[module.py]"]
  node_projection_heads["Projection heads<br/>[module.py]"]
  node_sigreg["SIGReg regularizer<br/>[module.py]"]
end

subgraph group_planning["Planning and evaluation"]
  node_evaluation_runner["Evaluation runner<br/>[eval.py]"]
  node_world_environment["Control environment"]
  node_policy["World-model policy"]
  node_planner["Planning solver"]
  node_checkpoint_loader["Checkpoint loader"]
  node_metrics["Evaluation results<br/>[eval.py]"]
end

subgraph group_configuration["Configuration"]
  node_training_config["Training settings"]
  node_evaluation_config["Evaluation settings"]
end

node_user(("Engineer"))

node_user -->|"starts training"| node_training_runner
node_user -->|"starts evaluation"| node_evaluation_runner
node_training_config -->|"configures"| node_training_runner
node_evaluation_config -->|"configures"| node_evaluation_runner
node_training_runner -->|"loads data"| node_dataset
node_training_runner -->|"builds transforms"| node_preprocessing
node_training_runner -->|"delegates training"| node_training_framework
node_training_runner -->|"uses regularizer"| node_sigreg
node_training_runner -.->|"trains model"| node_jepa
node_training_framework -->|"runs callback"| node_checkpoint_save
node_jepa -->|"encodes pixels"| node_encoder
node_jepa -->|"embeds actions"| node_action_embedder
node_jepa -->|"predicts embeddings"| node_predictor
node_jepa -->|"projects embeddings"| node_projection_heads
node_evaluation_runner -->|"loads data"| node_dataset
node_evaluation_runner -->|"creates and evaluates"| node_world_environment
node_evaluation_runner -->|"loads model"| node_checkpoint_loader
node_evaluation_runner -->|"instantiates solver"| node_planner
node_evaluation_runner -->|"creates policy"| node_policy
node_evaluation_runner -->|"writes results"| node_metrics
node_policy -->|"uses solver"| node_planner
node_checkpoint_loader -.->|"loads checkpoint"| node_jepa

click node_training_config "https://github.com/lucas-maes/le-wm/tree/main/config/train"
click node_evaluation_config "https://github.com/lucas-maes/le-wm/tree/main/config/eval"
click node_preprocessing "https://github.com/lucas-maes/le-wm/blob/main/utils.py"
click node_training_runner "https://github.com/lucas-maes/le-wm/blob/main/train.py"
click node_checkpoint_save "https://github.com/lucas-maes/le-wm/blob/main/utils.py"
click node_jepa "https://github.com/lucas-maes/le-wm/blob/main/jepa.py"
click node_encoder "https://github.com/lucas-maes/le-wm/blob/main/jepa.py"
click node_action_embedder "https://github.com/lucas-maes/le-wm/blob/main/module.py"
click node_predictor "https://github.com/lucas-maes/le-wm/blob/main/module.py"
click node_projection_heads "https://github.com/lucas-maes/le-wm/blob/main/module.py"
click node_sigreg "https://github.com/lucas-maes/le-wm/blob/main/module.py"
click node_evaluation_runner "https://github.com/lucas-maes/le-wm/blob/main/eval.py"
click node_planner "https://github.com/lucas-maes/le-wm/tree/main/config/eval/solver"
click node_metrics "https://github.com/lucas-maes/le-wm/blob/main/eval.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_dataset,node_preprocessing,node_training_runner,node_training_framework,node_checkpoint_save toneBlue
class node_jepa,node_encoder,node_action_embedder,node_predictor,node_projection_heads,node_sigreg toneAmber
class node_evaluation_runner,node_world_environment,node_policy,node_planner,node_checkpoint_loader,node_metrics toneMint
class node_training_config,node_evaluation_config toneRose
class node_user toneIndigo
```

## Components

### Data and training

- **HDF5 datasets**
- [Data preprocessing](https://github.com/lucas-maes/le-wm/blob/main/utils.py): `utils.py`
- [Training runner](https://github.com/lucas-maes/le-wm/blob/main/train.py): `train.py`
- **Training framework**
- [Checkpoint saving](https://github.com/lucas-maes/le-wm/blob/main/utils.py): `utils.py`

### JEPA model

- [JEPA model](https://github.com/lucas-maes/le-wm/blob/main/jepa.py): `jepa.py`
- [Image encoder](https://github.com/lucas-maes/le-wm/blob/main/jepa.py): `jepa.py`
- [Action embedder](https://github.com/lucas-maes/le-wm/blob/main/module.py): `module.py`
- [AR predictor](https://github.com/lucas-maes/le-wm/blob/main/module.py): `module.py`
- [Projection heads](https://github.com/lucas-maes/le-wm/blob/main/module.py): `module.py`
- [SIGReg regularizer](https://github.com/lucas-maes/le-wm/blob/main/module.py): `module.py`

### Planning and evaluation

- [Evaluation runner](https://github.com/lucas-maes/le-wm/blob/main/eval.py): `eval.py`
- **Control environment**
- **World-model policy**
- [Planning solver](https://github.com/lucas-maes/le-wm/tree/main/config/eval/solver): `config/eval/solver`
- **Checkpoint loader**
- [Evaluation results](https://github.com/lucas-maes/le-wm/blob/main/eval.py): `eval.py`

### Configuration

- [Training settings](https://github.com/lucas-maes/le-wm/tree/main/config/train): `config/train`
- [Evaluation settings](https://github.com/lucas-maes/le-wm/tree/main/config/eval): `config/eval`

### Other components

- **Engineer**

## Connections

- Engineer → Training runner: starts training (evidence: `README.md`)
- Engineer → Evaluation runner: starts evaluation (evidence: `README.md`)
- Training settings → Training runner: configures (evidence: `README.md`)
- Evaluation settings → Evaluation runner: configures (evidence: `README.md`)
- Training runner → HDF5 datasets: loads data (evidence: `train.py`)
- Training runner → Data preprocessing: builds transforms (evidence: `train.py`)
- Training runner → Training framework: delegates training (evidence: `train.py`)
- Training runner → SIGReg regularizer: uses regularizer (evidence: `train.py`)
- Training runner → JEPA model: trains model
- Training framework → Checkpoint saving: runs callback
- JEPA model → Image encoder: encodes pixels (evidence: `jepa.py`)
- JEPA model → Action embedder: embeds actions (evidence: `jepa.py`)
- JEPA model → AR predictor: predicts embeddings (evidence: `jepa.py`)
- JEPA model → Projection heads: projects embeddings (evidence: `jepa.py`)
- Evaluation runner → HDF5 datasets: loads data (evidence: `eval.py`)
- Evaluation runner → Control environment: creates and evaluates (evidence: `eval.py`)
- Evaluation runner → Checkpoint loader: loads model (evidence: `eval.py`)
- Evaluation runner → Planning solver: instantiates solver (evidence: `eval.py`)
- Evaluation runner → World-model policy: creates policy (evidence: `eval.py`)
- Evaluation runner → Evaluation results: writes results (evidence: `eval.py`)
- World-model policy → Planning solver: uses solver
- Checkpoint loader → JEPA model: loads checkpoint
