# ahiruneko/leflow architecture

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

- Interactive diagram: https://gitdiagram.com/ahiruneko/leflow
- Repository: https://github.com/ahiruneko/leflow

## Overview

LeFlow trains a latent-path flow planner and inverse-dynamics model over a frozen LeWorldModel, then evaluates it by turning generated latent paths into action chunks and reranking them with world-model rollouts. The graph also includes the repository’s LeWorldModel training path and benchmark configuration. Training and evaluation internals are described from the supplied excerpts; subsystem links without sampled call sites are limited to README-documented behavior.

Main entry points: [`eval.py`](https://github.com/ahiruneko/leflow/blob/main/eval.py) (Evaluation Runner), [`train_latent_planner.py`](https://github.com/ahiruneko/leflow/blob/main/train_latent_planner.py) (Planner Training), [`latent_planner.py`](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py) (Latent Path Solver), [`train.py`](https://github.com/ahiruneko/leflow/blob/main/train.py) (LeWM Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planner["Latent Planner"]
  node_planner_models["Flow and Inverse Dynamics<br/>[latent_planner.py]"]
  node_planner_checkpoint["Planner Checkpoint<br/>[latent_planner.py]"]
  node_solver["Latent Path Solver<br/>[latent_planner.py]"]
end

subgraph group_training["Model Training"]
  node_train_entry["Planner Training"]
  node_train_data["Dataset Loading"]
  node_planner_losses["Planner Losses<br/>[latent_planner.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_entry["Evaluation Runner<br/>[eval.py]"]
  node_eval_config["Benchmark Config"]
  node_solver_config["Latent Flow Config<br/>[latent_flow.yaml]"]
  node_policy["World Model Policy"]
  node_environment["Benchmark World"]
  node_results["Evaluation Results<br/>[eval.py]"]
end

subgraph group_worldmodel["World Model"]
  node_frozen_lewm["Frozen LeWM<br/>[latent_planner.py]"]
  node_lewm_train["LeWM Training<br/>[train.py]"]
  node_jepa["JEPA Model<br/>[jepa.py]"]
  node_model_layers["Model Layers<br/>[module.py]"]
end

node_user(("Engineer"))
node_dataset_service[("LeWM Datasets")]
node_checkpoint_service[("Frozen LeWM Checkpoints")]

node_user -->|"starts training"| node_train_entry
node_train_entry -->|"builds loaders"| node_train_data
node_train_data -->|"reads episodes"| node_dataset_service
node_train_entry -->|"loads backbone"| node_frozen_lewm
node_frozen_lewm -->|"loads reference"| node_checkpoint_service
node_train_entry -->|"constructs models"| node_planner_models
node_train_entry -->|"computes losses"| node_planner_losses
node_planner_losses -->|"trains parameters"| node_planner_models
node_train_entry -->|"saves state"| node_planner_checkpoint
node_user -->|"starts training"| node_lewm_train
node_lewm_train -->|"loads dataset"| node_dataset_service
node_lewm_train -->|"constructs model"| node_jepa
node_lewm_train -->|"builds components"| node_model_layers
node_user -->|"starts evaluation"| node_eval_entry
node_eval_entry -->|"loads settings"| node_eval_config
node_eval_entry -->|"reads episodes"| node_dataset_service
node_eval_entry -->|"creates world"| node_environment
node_eval_entry -->|"instantiates solver"| node_solver_config
node_eval_entry -->|"creates policy"| node_policy
node_policy -->|"dispatches plans"| node_solver
node_solver -->|"loads planner state"| node_planner_checkpoint
node_solver -->|"loads backbone"| node_frozen_lewm
node_solver -->|"generates paths and actions"| node_planner_models
node_solver -->|"scores rollouts"| node_environment
node_eval_entry -->|"runs episodes"| node_policy
node_eval_entry -->|"writes metrics"| node_results

click node_train_entry "https://github.com/ahiruneko/leflow/blob/main/train_latent_planner.py"
click node_train_data "https://github.com/ahiruneko/leflow/blob/main/train_latent_planner.py"
click node_frozen_lewm "https://github.com/ahiruneko/leflow/blob/main/latent_planner.py"
click node_planner_models "https://github.com/ahiruneko/leflow/blob/main/latent_planner.py"
click node_planner_losses "https://github.com/ahiruneko/leflow/blob/main/latent_planner.py"
click node_planner_checkpoint "https://github.com/ahiruneko/leflow/blob/main/latent_planner.py"
click node_lewm_train "https://github.com/ahiruneko/leflow/blob/main/train.py"
click node_jepa "https://github.com/ahiruneko/leflow/blob/main/jepa.py"
click node_model_layers "https://github.com/ahiruneko/leflow/blob/main/module.py"
click node_eval_entry "https://github.com/ahiruneko/leflow/blob/main/eval.py"
click node_eval_config "https://github.com/ahiruneko/leflow/tree/main/config/eval"
click node_solver_config "https://github.com/ahiruneko/leflow/blob/main/config/eval/solver/latent_flow.yaml"
click node_solver "https://github.com/ahiruneko/leflow/blob/main/latent_planner.py"
click node_results "https://github.com/ahiruneko/leflow/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_planner_models,node_planner_checkpoint,node_solver toneBlue
class node_train_entry,node_train_data,node_planner_losses,node_dataset_service,node_checkpoint_service toneAmber
class node_eval_entry,node_eval_config,node_solver_config,node_policy,node_environment,node_results toneMint
class node_frozen_lewm,node_lewm_train,node_jepa,node_model_layers toneRose
class node_user toneIndigo
```

## Components

### Latent Planner

- [Flow and Inverse Dynamics](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py): `latent_planner.py`
- [Planner Checkpoint](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py): `latent_planner.py`
- [Latent Path Solver](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py): `latent_planner.py`

### Model Training

- [Planner Training](https://github.com/ahiruneko/leflow/blob/main/train_latent_planner.py): `train_latent_planner.py`
- [Dataset Loading](https://github.com/ahiruneko/leflow/blob/main/train_latent_planner.py): `train_latent_planner.py`
- [Planner Losses](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py): `latent_planner.py`

### Evaluation

- [Evaluation Runner](https://github.com/ahiruneko/leflow/blob/main/eval.py): `eval.py`
- [Benchmark Config](https://github.com/ahiruneko/leflow/tree/main/config/eval): `config/eval`
- [Latent Flow Config](https://github.com/ahiruneko/leflow/blob/main/config/eval/solver/latent_flow.yaml): `config/eval/solver/latent_flow.yaml`
- **World Model Policy**
- **Benchmark World**
- [Evaluation Results](https://github.com/ahiruneko/leflow/blob/main/eval.py): `eval.py`

### World Model

- [Frozen LeWM](https://github.com/ahiruneko/leflow/blob/main/latent_planner.py): `latent_planner.py`
- [LeWM Training](https://github.com/ahiruneko/leflow/blob/main/train.py): `train.py`
- [JEPA Model](https://github.com/ahiruneko/leflow/blob/main/jepa.py): `jepa.py`
- [Model Layers](https://github.com/ahiruneko/leflow/blob/main/module.py): `module.py`

### Other components

- **Engineer**
- **LeWM Datasets**
- **Frozen LeWM Checkpoints**

## Connections

- Engineer → Planner Training: starts training
- Planner Training → Dataset Loading: builds loaders
- Dataset Loading → LeWM Datasets: reads episodes
- Planner Training → Frozen LeWM: loads backbone
- Frozen LeWM → Frozen LeWM Checkpoints: loads reference
- Planner Training → Flow and Inverse Dynamics: constructs models
- Planner Training → Planner Losses: computes losses
- Planner Losses → Flow and Inverse Dynamics: trains parameters
- Planner Training → Planner Checkpoint: saves state
- Engineer → LeWM Training: starts training
- LeWM Training → LeWM Datasets: loads dataset
- LeWM Training → JEPA Model: constructs model
- LeWM Training → Model Layers: builds components
- Engineer → Evaluation Runner: starts evaluation
- Evaluation Runner → Benchmark Config: loads settings
- Evaluation Runner → LeWM Datasets: reads episodes
- Evaluation Runner → Benchmark World: creates world
- Evaluation Runner → Latent Flow Config: instantiates solver
- Evaluation Runner → World Model Policy: creates policy
- World Model Policy → Latent Path Solver: dispatches plans
- Latent Path Solver → Planner Checkpoint: loads planner state
- Latent Path Solver → Frozen LeWM: loads backbone
- Latent Path Solver → Flow and Inverse Dynamics: generates paths and actions
- Latent Path Solver → Benchmark World: scores rollouts
- Evaluation Runner → World Model Policy: runs episodes
- Evaluation Runner → Evaluation Results: writes metrics