# kartik13-op/world-model architecture

> Architecture diagram of the GitHub repository kartik13-op/world-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartik13-op/world-model
- Repository: https://github.com/kartik13-op/world-model

## Overview

AI World Model V3 turns source video into frame/action training data, learns an autoencoder plus action-conditioned latent dynamics, and provides interactive camera-driven playback with optional idle-time scene reconstruction. The README and sampled code support the main pipeline and GUI branches; playback internals are only partially excerpted, so some documented relationships are cited to the README rather than inferred from unseen code.

Main entry points: [`main.py`](https://github.com/kartik13-op/world-model/blob/main/main.py) (CLI Commands), [`gui.py`](https://github.com/kartik13-op/world-model/blob/main/gui.py) (Desktop GUI), [`world_model/play.py`](https://github.com/kartik13-op/world-model/blob/main/world_model/play.py) (Interactive Playback), [`world_model/train.py`](https://github.com/kartik13-op/world-model/blob/main/world_model/train.py) (World Model Training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_cli["CLI Commands<br/>[main.py]"]
  node_gui["Desktop GUI<br/>[gui.py]"]
end

subgraph group_data["Video Preparation"]
  node_prep["Video Preprocessing<br/>[preprocess.py]"]
end

subgraph group_learning["Model Learning"]
  node_training["World Model Training<br/>[train.py]"]
  node_model["World Model<br/>[model.py]"]
  node_recontrain["Reconstructor Training<br/>[reconstructor.py]"]
  node_reconengine["Reconstruction Engine<br/>[upscaler.py]"]
end

subgraph group_runtime["Interactive Runtime"]
  node_playback["Interactive Playback<br/>[play.py]"]
  node_controls["Camera Controls<br/>[play.py]"]
  node_display["Display Output<br/>[play.py]"]
end

subgraph group_project["Project State"]
  node_artifacts[("Frames and Actions<br/>[config.py]")]
  node_projectpaths["Project Paths<br/>[config.py]"]
  node_worldcheckpoint["World Checkpoint<br/>[config.py]"]
  node_reconcheckpoint["Reconstructor Checkpoint<br/>[config.py]"]
  node_verify["Pipeline Verification<br/>[verify.py]"]
end

node_user(("User"))
node_video["Source Video"]

node_user -->|"runs commands"| node_cli
node_user -->|"opens interface"| node_gui
node_cli -->|"launches"| node_gui
node_gui -->|"starts preprocessing"| node_prep
node_gui -->|"starts training"| node_training
node_gui -->|"starts training"| node_recontrain
node_gui -->|"starts playback"| node_playback
node_gui -->|"runs checks"| node_verify
node_cli -->|"dispatches to"| node_prep
node_cli -->|"dispatches to"| node_training
node_cli -->|"dispatches to"| node_recontrain
node_cli -->|"dispatches to"| node_playback
node_cli -->|"dispatches to"| node_verify
node_video -->|"supplies footage"| node_prep
node_prep -->|"creates project"| node_projectpaths
node_prep -->|"writes frames/actions"| node_artifacts
node_training -->|"reads training data"| node_artifacts
node_training -->|"trains"| node_model
node_training -->|"saves checkpoint"| node_worldcheckpoint
node_recontrain -->|"delegates training"| node_reconengine
node_recontrain -->|"saves checkpoint"| node_reconcheckpoint
node_playback -->|"reads input"| node_controls
node_playback -->|"steps and decodes"| node_model
node_playback -.->|"loads optional model"| node_reconcheckpoint
node_playback -->|"reconstructs idle scene"| node_reconengine
node_playback -->|"renders frames"| node_display
node_verify -->|"checks data"| node_artifacts
node_verify -->|"checks checkpoint"| node_worldcheckpoint
node_verify -->|"checks checkpoint"| node_reconcheckpoint
node_projectpaths -->|"defines locations"| node_artifacts
node_projectpaths -->|"defines location"| node_worldcheckpoint
node_projectpaths -->|"defines location"| node_reconcheckpoint

click node_cli "https://github.com/kartik13-op/world-model/blob/main/main.py"
click node_gui "https://github.com/kartik13-op/world-model/blob/main/gui.py"
click node_prep "https://github.com/kartik13-op/world-model/blob/main/world_model/preprocess.py"
click node_artifacts "https://github.com/kartik13-op/world-model/blob/main/world_model/config.py"
click node_projectpaths "https://github.com/kartik13-op/world-model/blob/main/world_model/config.py"
click node_training "https://github.com/kartik13-op/world-model/blob/main/world_model/train.py"
click node_model "https://github.com/kartik13-op/world-model/blob/main/world_model/model.py"
click node_worldcheckpoint "https://github.com/kartik13-op/world-model/blob/main/world_model/config.py"
click node_recontrain "https://github.com/kartik13-op/world-model/blob/main/world_model/reconstructor.py"
click node_reconengine "https://github.com/kartik13-op/world-model/blob/main/world_model/upscaler.py"
click node_reconcheckpoint "https://github.com/kartik13-op/world-model/blob/main/world_model/config.py"
click node_playback "https://github.com/kartik13-op/world-model/blob/main/world_model/play.py"
click node_controls "https://github.com/kartik13-op/world-model/blob/main/world_model/play.py"
click node_verify "https://github.com/kartik13-op/world-model/blob/main/world_model/verify.py"
click node_display "https://github.com/kartik13-op/world-model/blob/main/world_model/play.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_cli,node_gui,node_user toneBlue
class node_prep toneAmber
class node_training,node_model,node_recontrain,node_reconengine toneMint
class node_playback,node_controls,node_display toneRose
class node_artifacts,node_projectpaths,node_worldcheckpoint,node_reconcheckpoint,node_verify,node_video toneIndigo
```

## Components

### User Interfaces

- [CLI Commands](https://github.com/kartik13-op/world-model/blob/main/main.py): `main.py`
- [Desktop GUI](https://github.com/kartik13-op/world-model/blob/main/gui.py): `gui.py`

### Video Preparation

- [Video Preprocessing](https://github.com/kartik13-op/world-model/blob/main/world_model/preprocess.py): `world_model/preprocess.py`

### Model Learning

- [World Model Training](https://github.com/kartik13-op/world-model/blob/main/world_model/train.py): `world_model/train.py`
- [World Model](https://github.com/kartik13-op/world-model/blob/main/world_model/model.py): `world_model/model.py`
- [Reconstructor Training](https://github.com/kartik13-op/world-model/blob/main/world_model/reconstructor.py): `world_model/reconstructor.py`
- [Reconstruction Engine](https://github.com/kartik13-op/world-model/blob/main/world_model/upscaler.py): `world_model/upscaler.py`

### Interactive Runtime

- [Interactive Playback](https://github.com/kartik13-op/world-model/blob/main/world_model/play.py): `world_model/play.py`
- [Camera Controls](https://github.com/kartik13-op/world-model/blob/main/world_model/play.py): `world_model/play.py`
- [Display Output](https://github.com/kartik13-op/world-model/blob/main/world_model/play.py): `world_model/play.py`

### Project State

- [Frames and Actions](https://github.com/kartik13-op/world-model/blob/main/world_model/config.py): `world_model/config.py`
- [Project Paths](https://github.com/kartik13-op/world-model/blob/main/world_model/config.py): `world_model/config.py`
- [World Checkpoint](https://github.com/kartik13-op/world-model/blob/main/world_model/config.py): `world_model/config.py`
- [Reconstructor Checkpoint](https://github.com/kartik13-op/world-model/blob/main/world_model/config.py): `world_model/config.py`
- [Pipeline Verification](https://github.com/kartik13-op/world-model/blob/main/world_model/verify.py): `world_model/verify.py`

### Other components

- **User**
- **Source Video**

## Connections

- User → CLI Commands: runs commands (evidence: `README.md`)
- User → Desktop GUI: opens interface (evidence: `README.md`)
- CLI Commands → Desktop GUI: launches (evidence: `main.py`)
- Desktop GUI → Video Preprocessing: starts preprocessing (evidence: `gui.py`)
- Desktop GUI → World Model Training: starts training (evidence: `gui.py`)
- Desktop GUI → Reconstructor Training: starts training (evidence: `gui.py`)
- Desktop GUI → Interactive Playback: starts playback (evidence: `gui.py`)
- Desktop GUI → Pipeline Verification: runs checks (evidence: `gui.py`)
- CLI Commands → Video Preprocessing: dispatches to (evidence: `main.py`)
- CLI Commands → World Model Training: dispatches to (evidence: `README.md`)
- CLI Commands → Reconstructor Training: dispatches to (evidence: `main.py`)
- CLI Commands → Interactive Playback: dispatches to (evidence: `main.py`)
- CLI Commands → Pipeline Verification: dispatches to (evidence: `README.md`)
- Source Video → Video Preprocessing: supplies footage (evidence: `README.md`)
- Video Preprocessing → Project Paths: creates project (evidence: `world_model/preprocess.py`)
- Video Preprocessing → Frames and Actions: writes frames/actions (evidence: `world_model/preprocess.py`)
- World Model Training → Frames and Actions: reads training data (evidence: `world_model/train.py`)
- World Model Training → World Model: trains (evidence: `world_model/train.py`)
- World Model Training → World Checkpoint: saves checkpoint (evidence: `README.md`)
- Reconstructor Training → Reconstruction Engine: delegates training (evidence: `world_model/reconstructor.py`)
- Reconstructor Training → Reconstructor Checkpoint: saves checkpoint (evidence: `README.md`)
- Interactive Playback → Camera Controls: reads input (evidence: `README.md`)
- Interactive Playback → World Model: steps and decodes (evidence: `README.md`)
- Interactive Playback → Reconstructor Checkpoint: loads optional model (evidence: `world_model/play.py`)
- Interactive Playback → Reconstruction Engine: reconstructs idle scene (evidence: `world_model/play.py`)
- Interactive Playback → Display Output: renders frames (evidence: `README.md`)
- Pipeline Verification → Frames and Actions: checks data (evidence: `world_model/verify.py`)
- Pipeline Verification → World Checkpoint: checks checkpoint (evidence: `world_model/verify.py`)
- Pipeline Verification → Reconstructor Checkpoint: checks checkpoint (evidence: `world_model/verify.py`)
- Project Paths → Frames and Actions: defines locations (evidence: `world_model/config.py`)
- Project Paths → World Checkpoint: defines location (evidence: `world_model/config.py`)
- Project Paths → Reconstructor Checkpoint: defines location (evidence: `world_model/config.py`)
