jepa-notebooks is a notebook-first curriculum and supporting PyTorch codebase for learning Joint-Embedding Predictive Architectures (JEPA), from basic visual representations to simple world models and planning.
Most JEPA material is either paper-heavy or tied to research codebases optimized for scale. This repository narrows the scope to small, teachable notebooks plus reusable src/ modules that keep the examples consistent and testable.
- Developers who already know basic Python and PyTorch.
- Self-learners who want runnable examples instead of only papers.
- Reviewers who need a compact codebase for curriculum and architecture feedback.
As of 2026-03-16, this project is alpha. It is suitable for local learning, curriculum review, and CI-validated
src/utilities. It is not yet suitable as a fully reproducible executed notebook suite or as a production reference for large-scale JEPA training. Known limitations: notebooks are not executed in CI, notebook acceptance criteria are only partially enforced, and dependency pinning is still broad. Breaking changes in the next release: helper APIs and notebook structure may still change while the project is in alpha.
git clone https://github.com/AbdelStark/jepa-notebooks.git
cd jepa-notebooks
make setup
make test
make coverage
make notebook-structure
.venv/bin/jupyter notebook notebooks/These commands are the verified local workflow today. make coverage enforces the repository's 90% coverage floor for src/.
- Work through notebooks in order from
01to05. - After notebook
05, notebooks06and07can be studied independently. - Finish with notebooks
08to10, which depend on the earlier mental model.
Dependency order:
01 -> 02 -> 03 -> 04 -> 05 -> 08 -> 09 -> 10
\-> 06
\-> 07
The reusable code that notebooks build on lives in src/:
src/data/: masking strategiessrc/models/:SimpleCNN,VisionTransformer,Predictorsrc/training/: losses and training loopssrc/utils/: device, seeding, and plotting helpers
jepa-notebooks/
notebooks/ notebook curriculum
src/ reusable PyTorch modules used across notebooks
tests/ unit tests + notebook structure checks
.github/workflows/ CI
Makefile verified development commands
agents.md agent-facing repo instructions
ARCHITECTURE.md system map, invariants, operational notes
ROADMAP.md milestones and limitation register
CONTRIBUTING.md contribution workflow
CHANGELOG.md user-visible changes
CI currently runs on every push and pull request and checks:
pytestfor the fulltests/suite- coverage for
src/with a 90% minimum
CI does not currently execute the notebooks end-to-end. Structural notebook checks exist, but runtime regressions in notebooks can still ship.
- Notebook execution is manual; there is no notebook smoke-test harness in CI.
- Later notebooks are structurally present, but pedagogical acceptance criteria are not enforced uniformly across the whole curriculum.
- Dependency versions are specified as minimums, not a locked reproducible environment.
- This repository targets educational clarity, not scale, throughput, or distributed training.
Open a GitHub issue for bugs, unclear notebook sections, or curriculum gaps:
Several model and masking ideas are adapted from Meta's EB-JEPA and related JEPA papers. Preserve attribution in notebook and source changes where code or structure is derived from that work.
- Assran et al., Self-Supervised Learning from Images with a Joint-Embedding Predictive Architecture
- Bardes et al., Revisiting Feature Prediction for Learning Visual Representations from Video
- Bardes et al., VICReg: Variance-Invariance-Covariance Regularization
- Chen et al., A Simple Framework for Contrastive Learning of Visual Representations
- LeCun, A Path Towards Autonomous Machine Intelligence