# jlingohr/magenta-torch architecture

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

- Interactive diagram: https://gitdiagram.com/jlingohr/magenta-torch
- Repository: https://github.com/jlingohr/magenta-torch

## Overview

##### Project type + purpose (from README + tree)
This is an **ML research/engineering codebase**: a **PyTorch implementation of MusicVAE** using **recurrent architectures (LSTM/GRU)**. It’s primarily a **training + inference pipeline** for symbolic music (MIDI), not a web service.

##### Top-level entrypoints / “system boundary”
- **`scripts/`**
- `preprocess.py` → CLI/runner for dataset creation
- `train.py` → CLI/runner for training
- `evaluate.py` → CLI/runner for evaluation (and possibly sampling quality metrics)
- **`conf.yml`** → central configuration for paths, hyperparameters, model settings
- **`requirements.txt`** → external runtime deps (PyTorch, YAML, MIDI libs, etc.)

These are the “outer interface” of the system.

##### Core library modules (`src/`) = internal components
- **Data path**
- `src/preprocess.py` → library preprocessing logic (invoked by `scripts/preprocess.py`)
- `src/dataset.py` → Dataset/Dataloader definitions and data access
- `src/transform.py` → feature transforms / normalization / encoding steps
- `src/midi_functions.py` → MIDI I/O + conversions (MIDI ↔ events/tokens/roll)
- **Model path**
- `src/model.py` → MusicVAE model assembly (encoder/decoder, latent sampling)
- `src/layers.py` → reusable NN building blocks (RNN cells, projections, etc.)
- `src/loss.py` → VAE losses (recon + KL, possibly annealing schedules)
- **Training + lifecycle**
- `src/trainer.py` → training loop orchestration (epochs, optimizer steps, logging hooks)
- `src/checkpoint.py` → save/load model/optimizer states
- `src/sampler.py` → latent sampling / sequence generation utilities
- `src/reconstruction.py` → encode-decode reconstruction flow (for eval/inspection)

##### Preprocess flow
- `scripts/preprocess.py` → `src/preprocess.py` → `src/midi_functions.py` + `src/transform.py`
- Output: **processed dataset artifacts** (files on disk)

##### Training flow
- `scripts/train.py` → `src/trainer.py`
- `trainer.py` uses:
- `src/dataset.py` (loads processed artifacts)
- `src/model.py` + `src/layers.py`
- `src/loss.py`
- `src/checkpoint.py` (writes checkpoints)
- Output: **checkpoints** + (optional) logs/metrics

##### Evaluation flow
- `scripts/evaluate.py` → likely `src/reconstruction.py` and/or `src/sampler.py`
- Reads: checkpoints + dataset
- Outputs: metrics + reconstructed/generated MIDI (via `src/midi_functions.py`)

- **CLI Runners** (`scripts/*.py`)
- **Core Library** (`src/*`)
- **File-based Artifacts**
- Raw MIDI dataset (input)
- Preprocessed dataset (intermediate)
- Checkpoints (model artifacts)
- Generated/Reconstructed MIDI (output)
- **External Libraries**
- PyTorch (training runtime)
- MIDI parsing/writing library (whatever `requirements.txt` implies)
- YAML loader for `conf.yml`

- Raw MIDI → Preprocess → Preprocessed dataset
- Preprocessed dataset → Training → Checkpoints
- Checkpoints + Dataset → Evaluate/Sample → MIDI outputs + metrics

This is where you “separate into as many components as possible” and show crisp dependencies.

##### Data & Representation
- `midi_functions.py`
- `transform.py`
- `preprocess.py`
- `dataset.py`

##### Model
- `model.py`
- Depends on: `layers.py`
- Used by: `trainer.py`, `reconstruction.py`, `sampler.py`
- `loss.py`
- Used by: `trainer.py`

##### Training & Lifecycle
- `trainer.py`
- Depends on: `model.py`, `loss.py`, `dataset.py`, `checkpoint.py`
- `checkpoint.py`
- Used by: `trainer.py`, `evaluate.py`, `sampler.py`, `reconstruction.py`

##### Inference utilities
- `sampler.py`
- Uses: `model.py`, `checkpoint.py`, outputs MIDI via `midi_functions.py`
- `reconstruction.py`
- Uses: `model.py`, `dataset.py`/data batches, outputs MIDI via `midi_functions.py`

##### Relationships/interactions to highlight (what matters architecturally here)
Because this is a VAE training pipeline, emphasize these interactions:

- **Encoding/decoding loop**: Dataset batch → Encoder (RNN) → latent z → Decoder (RNN) → reconstructed sequence
- **Loss computation**: recon loss + KL (and any schedules/annealing that `loss.py` likely supports)
- **Checkpoint lifecycle**: periodic save during training; load for evaluation/sampling
- **Representation conversions**:
- MIDI ↔ internal event/token representation (central role of `midi_functions.py`)
- Transform/encoding steps that must match between preprocess and inference

##### Clear labels
- “`scripts/train.py` (CLI entrypoint)”
- “`src/trainer.py` (training loop)”
- “Checkpoint files (model.pt / optimizer state)”
- “Preprocessed dataset (serialized tensors / indices)”

##### User/CLI Lane
- preprocess.py | train.py | evaluate.py (each reads conf.yml)

##### Core Modules Lane (`src/`)
- Preprocess/Transform/MIDI funcs
- Dataset
- Model/Layers/Loss
- Trainer/Checkpoint
- Sampler/Reconstruction

##### Artifacts Lane (Disk)
- Raw MIDI
- Preprocessed dataset
- Checkpoints
- Generated MIDI + metrics

Then connect:
- preprocess runner → preprocess modules → preprocessed dataset
- train runner → trainer → (dataset + model + loss) → checkpoints
- eval runner → (checkpoint + model + sampler/reconstruction + midi funcs) → generated MIDI + metrics

- exact dataset artifact formats (e.g., `.npz`, `.pt`, `.pkl`)
- exact MIDI library used (e.g., `pretty_midi`, `mido`)
- hyperparameters that influence architecture (latent size, RNN type, sequence length)
- whether evaluation computes quantitative metrics or only reconstruction outputs

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Level 0/1: Context + Containers (vertical)
%% =========================
subgraph "System Boundary: MusicVAE Research Codebase (PyTorch)"
direction TB

  subgraph "User / CLI Runners (scripts/)"
  direction TB
    U["Researcher / Engineer"]:::user
    CLI_PRE["scripts/preprocess.py\n(CLI: dataset creation)"]:::script
    CLI_TRN["scripts/train.py\n(CLI: training)"]:::script
    CLI_EVL["scripts/evaluate.py\n(CLI: evaluation & sampling)"]:::script
  end

  subgraph "Configuration & Dependencies"
  direction TB
    CONF["conf.yml\n(central configuration)"]:::config
    REQS["requirements.txt\n(external runtime deps)"]:::config
  end

  subgraph "Core Library (src/)"
  direction TB

    subgraph "Data & Representation"
    direction TB
      LIB_PRE["src/preprocess.py\n(preprocessing logic)"]:::data
      MIDI["src/midi_functions.py\n(MIDI I/O & conversions)"]:::data
      XFORM["src/transform.py\n(transforms/encoding/normalization)"]:::data
      DS["src/dataset.py\n(Dataset + DataLoader)"]:::data
    end

    subgraph "Model"
    direction TB
      MODEL["src/model.py\n(MusicVAE: encoder/decoder, latent z)"]:::model
      LAYERS["src/layers.py\n(RNN blocks, projections)"]:::model
      LOSS["src/loss.py\n(recon + KL, schedules)"]:::model
    end

    subgraph "Training & Lifecycle"
    direction TB
      TRAINER["src/trainer.py\n(training loop orchestration)"]:::train
      CKPT["src/checkpoint.py\n(save/load model & optimizer)"]:::train
    end

    subgraph "Inference Utilities"
    direction TB
      SAMP["src/sampler.py\n(latent sampling / generation)"]:::infer
      RECON["src/reconstruction.py\n(encode-decode reconstruction)"]:::infer
    end

  end

  subgraph "File-based Artifacts (Disk)"
  direction TB
    RAW[("Raw MIDI Dataset\n(.mid files)")]:::artifact
    PROC[("Preprocessed Dataset Artifacts\n(serialized tensors/indices)")]:::artifact
    CKPTS[("Checkpoints\n(model.pt / optimizer state)")]:::artifact
    OUT[("Generated / Reconstructed MIDI\n+ Metrics / Reports")]:::artifact
  end

  subgraph "External Libraries (Runtime)"
  direction TB
    TORCH["PyTorch\n(tensors, autograd, optimizers)"]:::external
    MIDILIB["MIDI parsing/writing library\n(e.g., pretty_midi / mido)"]:::external
    YAMLLIB["YAML loader\n(read conf.yml)"]:::external
  end

end

%% =========================
%% Workflow: Preprocess
%% =========================
U -->|"runs"| CLI_PRE
CLI_PRE -->|"reads_config"| CONF
CLI_PRE -->|"invokes"| LIB_PRE
LIB_PRE -->|"uses"| MIDI
LIB_PRE -->|"uses"| XFORM
RAW -.->|"read_midi"| MIDI
LIB_PRE -.->|"writes"| PROC

%% =========================
%% Workflow: Training
%% =========================
U -->|"runs"| CLI_TRN
CLI_TRN -->|"reads_config"| CONF
CLI_TRN -->|"invokes"| TRAINER
PROC -.->|"loaded_by"| DS
TRAINER -->|"uses"| DS
TRAINER -->|"uses"| MODEL
MODEL -->|"builds_on"| LAYERS
TRAINER -->|"computes"| LOSS
TRAINER -->|"saves/loads"| CKPT
CKPT -.->|"writes"| CKPTS
TORCH -->|"runtime_for"| TRAINER
TORCH -->|"runtime_for"| MODEL
TORCH -->|"runtime_for"| LOSS

%% =========================
%% Workflow: Evaluation / Sampling
%% =========================
U -->|"runs"| CLI_EVL
CLI_EVL -->|"reads_config"| CONF
CLI_EVL -->|"invokes"| RECON
CLI_EVL -->|"invokes"| SAMP

PROC -.->|"batches_for"| RECON
CKPTS -.->|"loaded_by"| CKPT
RECON -->|"uses"| MODEL
RECON -->|"uses"| DS
RECON -->|"loads"| CKPT
RECON <-->|"midi_read_write"| MIDI
RECON -.->|"writes"| OUT

SAMP -->|"uses"| MODEL
SAMP -->|"loads"| CKPT
SAMP -->|"outputs_via"| MIDI
SAMP -.->|"writes"| OUT

%% =========================
%% Cross-cutting: Config/Deps
%% =========================
YAMLLIB -->|"parses"| CONF
REQS -->|"pins_versions_for"| TORCH
REQS -->|"pins_versions_for"| MIDILIB
REQS -->|"pins_versions_for"| YAMLLIB
MIDILIB -->|"used_by"| MIDI

%% =========================
%% Architectural highlights (VAE loop)
%% =========================
DS -->|"batch_sequences"| MODEL
MODEL -->|"encode→z→decode"| LOSS
MODEL -->|"reconstructs_sequences"| RECON
MODEL -->|"samples_from_latent_z"| SAMP

%% =========================
%% Click events (from component_mapping)
%% =========================
click CLI_PRE "https://github.com/jlingohr/magenta-torch/blob/master/scripts/preprocess.py"
click CLI_TRN "https://github.com/jlingohr/magenta-torch/blob/master/scripts/train.py"
click CLI_EVL "https://github.com/jlingohr/magenta-torch/blob/master/scripts/evaluate.py"
click CONF "https://github.com/jlingohr/magenta-torch/blob/master/conf.yml"
click REQS "https://github.com/jlingohr/magenta-torch/blob/master/requirements.txt"
click LIB_PRE "https://github.com/jlingohr/magenta-torch/blob/master/src/preprocess.py"
click MIDI "https://github.com/jlingohr/magenta-torch/blob/master/src/midi_functions.py"
click XFORM "https://github.com/jlingohr/magenta-torch/blob/master/src/transform.py"
click DS "https://github.com/jlingohr/magenta-torch/blob/master/src/dataset.py"
click MODEL "https://github.com/jlingohr/magenta-torch/blob/master/src/model.py"
click LAYERS "https://github.com/jlingohr/magenta-torch/blob/master/src/layers.py"
click LOSS "https://github.com/jlingohr/magenta-torch/blob/master/src/loss.py"
click TRAINER "https://github.com/jlingohr/magenta-torch/blob/master/src/trainer.py"
click CKPT "https://github.com/jlingohr/magenta-torch/blob/master/src/checkpoint.py"
click SAMP "https://github.com/jlingohr/magenta-torch/blob/master/src/sampler.py"
click RECON "https://github.com/jlingohr/magenta-torch/blob/master/src/reconstruction.py"

%% =========================
%% Styles
%% =========================
classDef user fill:#ffffff,stroke:#111827,stroke-width:1px,color:#111827
classDef script fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#111827
classDef config fill:#fff7ed,stroke:#9a3412,stroke-width:1px,color:#7c2d12
classDef data fill:#e0f2fe,stroke:#075985,stroke-width:1px,color:#0c4a6e
classDef model fill:#ede9fe,stroke:#5b21b6,stroke-width:1px,color:#3b0764
classDef train fill:#dcfce7,stroke:#166534,stroke-width:1px,color:#14532d
classDef infer fill:#ffe4e6,stroke:#9f1239,stroke-width:1px,color:#881337
classDef artifact fill:#fef9c3,stroke:#854d0e,stroke-width:1px,color:#713f12
classDef external fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#1e3a8a
```
