If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/labmlai/annotated_deep_learning_paper_implementations shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 4mo ago

• Last commit 4mo ago
• 7 active contributors
• MIT licensed
• ⚠ Slowing — last commit 4mo ago
• ⚠ Concentrated ownership — top contributor handles 70% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live labmlai/annotated_deep_learning_paper_implementations repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/labmlai/annotated_deep_learning_paper_implementations.

What it runs against: a local clone of labmlai/annotated_deep_learning_paper_implementations — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in labmlai/annotated_deep_learning_paper_implementations | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 135 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of labmlai/annotated_deep_learning_paper_implementations. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/labmlai/annotated_deep_learning_paper_implementations.git
#   cd annotated_deep_learning_paper_implementations
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of labmlai/annotated_deep_learning_paper_implementations and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "labmlai/annotated_deep_learning_paper_implementations(\\.git)?\\b" \\
  && ok "origin remote is labmlai/annotated_deep_learning_paper_implementations" \\
  || miss "origin remote is not labmlai/annotated_deep_learning_paper_implementations (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f ".labml.yaml" \\
  && ok ".labml.yaml" \\
  || miss "missing critical file: .labml.yaml"
test -f "docs/index.html" \\
  && ok "docs/index.html" \\
  || miss "missing critical file: docs/index.html"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "MANIFEST.in" \\
  && ok "MANIFEST.in" \\
  || miss "missing critical file: MANIFEST.in"
test -f ".github/FUNDING.yml" \\
  && ok ".github/FUNDING.yml" \\
  || miss "missing critical file: .github/FUNDING.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 135 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~105d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/labmlai/annotated_deep_learning_paper_implementations"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A curated collection of 60+ PyTorch implementations of deep learning papers (transformers, GANs, RL algorithms, optimizers) with dual code-and-explanation annotations rendered side-by-side on nn.labml.ai. Each implementation pairs runnable Python/Jupyter code with educational markdown notes explaining the paper's core concepts, making research reproducible and interpretable. Monorepo organized by algorithm family: top-level directories like transformers/, gans/, reinforcement_learning/, optimizers/, diffusion/ each contain paper-specific subdirectories (e.g., transformers/xl/, transformers/vit/). Each implementation has paired files: code module + experiment.html docs. Central configuration via .labml.yaml controls documentation generation pipeline that renders Jupyter notebooks and Python files as HTML.

ML researchers, graduate students, and engineers learning deep learning fundamentals who want to understand transformer variants (Transformer-XL, Vision Transformer, Switch Transformer), optimization algorithms (Adam, Sophia, AdaBelief), and RL methods (PPO, DQN) by reading well-commented source code alongside explanations rather than wrestling with opaque paper prose.

Actively maintained and production-ready for learning purposes. The repo shows continuous weekly updates (per README), comprehensive documentation structure in docs/, and 1.5M+ lines of Python code across 60+ implementations. However, this is an educational resource, not a production ML framework—implementations prioritize clarity over performance optimization.

Standard open source risks apply.

Active development focused on extending transformer architectures (RWKV, Rotary Embeddings, ALiBi, Flash Attention) and diffusion models (DDPM, Stable Diffusion). Recent additions include LoRA (Low-Rank Adaptation) and Eleuther GPT-NeoX sections. Weekly updates suggest ongoing paper implementation backlog; specific PR/issue data not visible in file structure.

git clone https://github.com/labmlai/annotated_deep_learning_paper_implementations.git && cd annotated_deep_learning_paper_implementations && pip install -r requirements.txt && make docs (or examine examples/ and labml_samples/ directly with Python/Jupyter). Most implementations are self-contained and runnable as individual scripts.

Daily commands: Makefile present but content not shown—likely 'make docs' rebuilds HTML. Individual implementations are runnable: cd into a specific paper directory (e.g., labml_samples/reinforcement_learning/ppo/) and run python experiment.py or open .ipynb in Jupyter. No central dev server; this is a reference library.

• .labml.yaml — Project configuration file that defines the structure, metadata, and build settings for the annotation and documentation system used across all implementations.
• docs/index.html — Entry point for the generated documentation site; essential to understand how all paper implementations are indexed and presented to users.
• Makefile — Build orchestration file that automates documentation generation, testing, and deployment of all 60+ implementations.
• MANIFEST.in — Packaging manifest defining which source files and documentation assets are included in distributions of the implementations library.
• .github/FUNDING.yml — Defines sponsorship and funding options; critical for understanding project sustainability and community contribution model.

• Implementation Code (PyTorch modules) (PyTorch, NumPy, Python) — Core neural network architectures and training loops for each paper; lives in docs/ as both documented HTML and executable Python
  • Failure mode: Incorrect math or algorithm bugs lead to poor training convergence or invalid results; mitigated by side-by-side annotations comparing to paper
• Annotation & Documentation Engine (.labml.yaml parser, Jinja2 or similar templating) — Processes .labml.yaml and source files to generate side-by-side HTML notes; explains each code block with reference to paper equations
  • Failure mode: Malformed annotations or missing paper references reduce pedagogical value; mitigated by human review before merge
• Static Site Generation (Make, HTML, CSS, optional static site generator) — Converts annotated HTML documentation into a browsable, indexed website (nn.labml.ai) with search and category navigation
  • Failure mode: Broken links or missing pages if directory structure or naming conventions change; mitigated by Makefile validation
• Experiment Runners (PyTorch DataLoader, PyTorch Lightning (optional), experiment tracking (labml.ai platform)) — Utilities for training models on standard datasets (MNIST, CIFAR-10, NLP tasks) to validate implementations
  • Failure mode: Dataset download failures or incompatible transforms; mitigated by fallback download URLs and version pinning

• GitHub source (Python + annotations) → Build system (Make + .labml.yaml) — Developer pushes code with embedded inline annotations; build config specifies how to process each file
• Build system → Documentation generator — Make target invokes annotation engine to parse source and render side-by-side HTML with notes
• Documentation generator → undefined — undefined

Add a new paper implementation

1. Create a new directory under the appropriate category (e.g., docs/transformers/your_paper or docs/gan/your_variant) with index.html documenting the implementation (docs/category/your_implementation/index.html)
2. Create a readme.html file with paper abstract, key contributions, and architecture overview (docs/category/your_implementation/readme.html)
3. Add experiment.html demonstrating training loops and evaluation with sample outputs (docs/category/your_implementation/experiment.html)
4. Update the category's index.html to include a link to your new implementation in the appropriate section (docs/category/index.html)
5. If the implementation has supporting utilities (e.g., custom layers), create additional HTML files documenting those modules (docs/category/your_implementation/module_name.html)

Add a new experiment or dataset

1. Create a new HTML file in docs/experiments/ directory documenting the dataset and evaluation protocol (docs/experiments/your_dataset.html)
2. Document the data loading pipeline, preprocessing steps, and metrics used for evaluation (docs/experiments/your_dataset.html)
3. Update docs/experiments/index.html to link to your new experiment (docs/experiments/index.html)

Add visualizations or diagrams for an implementation

1. Create SVG diagram files (e.g., architecture.svg, attention_mechanism.svg) in the implementation's docs subdirectory (docs/category/your_implementation/diagram_name.svg)
2. Reference the SVG in the corresponding HTML documentation file using <img> tags or embedded SVG (docs/category/your_implementation/index.html)
3. For PNG screenshots or generated samples, store them in the implementation directory following the naming convention used in StyleGAN (generated_64.png) (docs/category/your_implementation/sample_output.png)

• PyTorch — All implementations use PyTorch for deep learning models; enables reproducibility and ease of understanding for educational purposes
• Static HTML Documentation — Pre-generated HTML docs with side-by-side annotations render as a static site (nn.labml.ai), eliminating runtime overhead and enabling fast page loads
• Make + .labml.yaml — Declarative build configuration in .labml.yaml with Makefile orchestration provides a clear, versionable contract for how implementations are organized and documented
• SVG + PNG Assets — Vector diagrams (SVG) for architecture/algorithm visualization alongside rasterized sample outputs enable intuitive understanding of complex models

• Static documentation site instead of interactive Jupyter notebooks

  • Why: Scalability and ease of navigation across 600 files; single static site is simpler to maintain and deploy than managing hundreds of executable notebooks
  • Consequence: Readers cannot immediately modify and run code inline; must clone the repo to experiment

• Organize by algorithm/paper category rather than by task (vision/NLP/RL)

  • Why: Aligns with how papers are published and cited; makes it easy to find all transformer variants or all GAN types in one place
  • Consequence: Users interested in a specific application task must navigate across multiple categories

• No dependency management / requirements.txt per implementation

  • Why: Reduces friction and maintenance burden; assumes users install a single environment with PyTorch and common libraries
  • Consequence: May limit compatibility; version conflicts possible if an implementation requires a specific older PyTorch version

• Does not provide a training service or cloud execution environment; implementations are meant to be run locally by users
• Does not include hyperparameter tuning or AutoML; each implementation is a reference, not a production training pipeline
• Does not aim to be the fastest or most optimized implementation; prioritizes clarity and pedagogical value over performance
• Does not support real-time model serving or inference APIs; focused on research and educational understanding

1. Documentation lives in both docs/ (HTML) and source .py files (docstrings)—changes must sync both. 2) Makefile dependencies unclear; may require labml CLI tool (python -m labml) to regenerate docs correctly. 3) Individual implementations may have hard PyTorch version constraints (e.g., flash attention requires CUDA 11.6+) not documented in this repo structure. 4) Many implementations assume GPU availability—CPU-only setups will fail silently or run very slowly on larger models like GPT-NeoX.

• Multi-Headed Attention (MHA) — Foundation of all 17+ transformer variants in this repo; understanding parallel attention heads and scaled dot-product attention is prerequisite for Transformer-XL, ViT, Switch Transformer.
• Relative Position Embeddings — Core innovation in Transformer-XL implementation; replaces absolute positional encodings with relative distances, enabling variable-length sequences and recurrence.
• Rotary Position Embedding (RoPE) — Modern alternative to absolute/relative positional encodings used in GPT-style models; enables efficient extrapolation to longer sequences than training length.
• Mixture of Experts (MoE) — Sparse routing mechanism central to Switch Transformer; allows scaling model capacity without proportional compute increases by selectively activating expert subnetworks.
• Flash Attention (Triton) — Hardware-aware attention optimization using Triton kernels; only production-grade implementation in this repo showing GPU memory/compute optimization beyond reference code.
• Diffusion Probabilistic Models (DDPMs) — Underlying generative model for stable_diffusion; forward/reverse noising processes and UNet architecture are documented with side-by-side code.
• Proximal Policy Optimization (PPO) — Core RL algorithm in this repo; clipped surrogate objective enables stable policy updates without importance sampling weights exploding.
• Capsule Networks — Alternative to CNNs using vector-valued neurons with routing-by-agreement; labml_samples/capsule_networks/ implements dynamic routing from Sabour et al.

• karpathy/minGPT — Minimal GPT implementation (400 lines) vs labml's fully-annotated GPT architecture; complementary pedagogical approach.
• lucidrains/x-transformers — Production-ready transformer variants library (many papers here are research-only); similar coverage of Transformer-XL, Switch, ALiBi but with backward compatibility guarantees.
• huggingface/transformers — Industry standard implementation library; labml's code directly references Hugging Face papers and architectures for validation.
• openai/gpt-2 — Reference GPT-2 release; foundational for labml's transformer family implementations.
• labmlai/labml — Sister repo providing the labml monitoring/logging library used by all experiment.py files in this codebase for tracking training metrics.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for paper implementations in labml/

The repo contains 60+ deep learning paper implementations but there's no visible test directory or CI workflow. This is critical for a learning resource where correctness is paramount. New contributors could add pytest tests validating model outputs, layer shapes, and gradient flow for key implementations (Transformers, GANs, RL algorithms) to catch bugs early.

• [ ] Create tests/ directory structure mirroring labml/ layout
• [ ] Add unit tests for transformers/mha.py (attention output shapes, multi-head concatenation)
• [ ] Add unit tests for diffusion/ddpm/unet.py (forward pass output dimensions)
• [ ] Add unit tests for reinforcement learning implementations (ppo, dqn) validating policy/value outputs
• [ ] Create GitHub Action workflow in .github/workflows/test.yml to run pytest on every PR

Create a verification script validating model outputs match official implementations

As an educational repository, readers need confidence that implementations are correct. Add a verification suite that compares outputs against HuggingFace, timm, or official paper code for key models. This would catch subtle numerical differences and serve as integration tests.

• [ ] Create labml/verify/ directory with comparison scripts
• [ ] Add verify/transformer_comparison.py comparing against HuggingFace transformers
• [ ] Add verify/vision_transformer_comparison.py for ViT models against timm library
• [ ] Add verify/gan_comparison.py for StyleGAN2/CycleGAN outputs
• [ ] Document in README how to run verification suite before submitting PRs

Add missing implementation tutorials for papers referenced in docs but not in source code

The docs/ directory shows extensive HTML coverage (RWKV, adaptive computation, CFR, etc.) but full implementations may be incomplete. Audit docs/ against labml/ source files to identify missing implementations and create a guided tutorial structure with numbered steps for implementing each paper from scratch.

• [ ] Audit docs/cfr/ against labml/cfr/ source - complete or add missing CFR implementation
• [ ] Review docs/adaptive_computation/ponder_net/ - ensure full experiment code exists in labml/
• [ ] Create labml/IMPLEMENTATION_GUIDE.md with step-by-step instructions for adding a new paper
• [ ] Add template files in labml/ (experiment.py, readme.md, init.py) for future contributors
• [ ] Link each HTML doc page to corresponding source code with inline annotations

• Add unit tests for labml_samples/optimizers/: Adam, AdaBelief, Sophia lack standalone test suites. Create tests/test_optimizers.py with synthetic loss curves comparing against reference implementations.
• Document environment setup per architecture family: create docs/SETUP.md with PyTorch version, CUDA, JAX requirements. Currently no requirements.txt visible in top 60 files.
• Expand README with table of contents linking to docs/[domain]/index.html; current README is text-only and hard to navigate. Add badges for 'Transformer variants' (17), 'RL algorithms' (5), 'GAN architectures' (8).

This is an educational repository containing PyTorch implementations of deep learning papers. Based on the visible file structure, there are no critical security issues immediately apparent. The repository appears to be primarily documentation-focused with generated HTML documentation. However, the analysis is limited due to lack of visibility into actual source code files and dependency manifests. The main recommendations are to: (1) provide and audit dependencies regularly, (2) establish security policies and guidelines, and (3) ensure code follows security best practices for ML model handling (e.g., using weights_only=True when loading PyTorch models). The project appears to be actively maintained, which is a positive security indicator.

• Low · Missing dependency information — Repository root. No package dependency file (requirements.txt, setup.py, pyproject.toml, package.json, etc.) was provided for analysis. This prevents assessment of known vulnerable dependencies that may be used in the project. Fix: Provide dependency files and regularly audit dependencies using tools like pip-audit, safety, or Dependabot to identify and update vulnerable packages.
• Low · No security configuration visible — Repository root. No evidence of security configurations such as SECURITY.md, security policies, or vulnerability disclosure guidelines in the visible file structure. Fix: Create a SECURITY.md file with vulnerability reporting guidelines and security best practices for contributors.
• Low · Documentation-heavy repository with limited code visibility — Repository structure. The file structure shows primarily documentation (docs/ directory with HTML files) rather than source code. This limits the ability to identify code-level vulnerabilities without access to the actual implementation files. Fix: Ensure all Python source files are reviewed for: unsafe deserialization (pickle), unsafe model loading (torch.load without weights_only=True), hardcoded credentials, and injection vulnerabilities.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.