Chapter 21 — A map of the official repository

Label the kitchen before turning on the stove

A toolbox is easier to trust once every drawer has a name. main.py is the switchboard. module.py contains the learning machinery. data/loader.py prepares the ingredients. conf/ stores the recipe. When something fails, this map tells you where to look before you start turning random screws.

Pin the evidence before installing it

This edition audits repository commit 3ea0dda dated 2026-09-02. A pinned checkout can be revisited; a floating main cannot.

git clone https://github.com/MLO-lab/LeVJEPA.git
cd LeVJEPA
git checkout 3ea0dda16030bc0fd6472bf809fc0a0ad836a812
git rev-parse HEAD
uv sync

The printed hash should match exactly. The project requires Python 3.12+ and locks dependencies in uv.lock. Use uv sync --extra data for dataset construction or uv sync --extra notebook for the notebooks. This is not an installed Python package; run commands from its repository root.

The directory map:

• main.py joins loader, shared encoder, projector, SIGReg, optimizer, and Lightning trainer.
• module.py implements the ViT, random token dropping, RoPE, block-causal mask, projector, and SIGReg.
• data/loader.py samples clips from Lance and makes one global plus several local views.
• callbacks.py schedules weight decay and saves evaluation-only EMA weights.
• conf/config.yaml is the Hydra recipe; conf/data/ points to datasets.
• scripts/ downloads and transcodes; slurm/ launches cluster jobs.
• training_workshop.ipynb dismantles training with a small model; feature_visualization.ipynb inspects patch features from released weights.

For a first trace, stay on one road. main() calls build_video_loader(). Transforms emit a global [B,T,C,H,W] tensor and local [B,V,T,C,H,W]. multiview_forward() rearranges them to [B,C,T,H,W], folds locals into the batch, runs one shared encoder, and takes token 0 ([CLS]). One projector maps all summaries before view MSE and 0.02 × SIGReg. Breakpoints along this road distinguish data-layout, encoder, and loss failures—and show that the global output is never detached.

The notebooks are lessons, not paper evaluation scripts. The workshop shrinks the model, frame count, and sparsity; the feature notebook only visualizes frozen output. Record every teaching simplification if you begin there. paper.md is a manuscript copy and may retain draft TODOs, so use arXiv v1 and release pages for formal claims.

Licensing is file-specific. The repository root uses MIT, while module.py, adapted from Meta V-JEPA, explicitly carries CC BY-NC 4.0; released weights use CC BY-NC 4.0 too. Dependencies and linked Walking Tours videos keep their own terms. A root MIT file does not grant blanket commercial permission.

The smallest environment check

After checkout, git status --short should print nothing. Then run:

uv run python -c "from module import SIGReg, vit_tiny; print('imports ok')"

imports ok proves only that this environment imports. It says nothing about training accuracy.

Repository records

• Pinned official repository at 3ea0dda
• Pinned README, main.py, and module.py
• Root license and official project page

Keep the map folded

1. A reproducible report records a commit, not merely “latest main.”
2. main.py assembles, module.py computes, and conf/ varies the recipe.
3. MIT does not cover every artifact; core adapted code and weights are noncommercial CC BY-NC 4.0.

Find the drawer

1. Why record the full commit hash?
2. Where is EMA bookkeeping, and is it a target encoder?
3. Does a root MIT license make the released weights commercial-use software?