The Problem

Machine learning education is often split between theory and practice: textbooks show equations in isolation, while tutorials show code without mathematical context. Learners struggle to connect the loss surface, the gradient updates, and the final model weights. This repo addresses that by packaging ML algorithm implementations as visual, interactive Jupyter Notebooks.

What This Does

machine-learning-visualized is a Jupyter Book that assembles notebooks implementing and deriving ML algorithms from first principles. Each notebook produces visualizations of the training process, showing weights converging to their optima. The book structure is defined in _toc.yml, configuration in _config.yml, and the build pipeline in .github/workflows/ci.yml.

The repo itself contains no notebooks — they are downloaded from separate per-algorithm repositories (neural networks, autoencoders, logistic regression, PCA, k-means, gradient descent) via download_notebooks.sh. Interactive Marimo notebooks are also included to explore how weights affect loss functions. The site builds to static HTML and EPUB, deployable via Docker or the jupyter-book CLI.

How It Is Wired

Execution starts with download_notebooks.sh, which fetches notebooks from the linked GitHub repos into chapter1/ through chapter4/. The _toc.yml file defines the book's table of contents, and _config.yml holds build settings. The CI workflow in .github/workflows/ci.yml triggers on commits and pull requests, building the book and deploying the site.

The build has two paths: the jupyter-book CLI (pip install -U jupyter-book && jupyter-book build .) or Docker via Dockerfile.book and compose.yml. EPUB generation uses Dockerfile.pandoc with a pandoc conversion step. The book/ directory holds pre-built outputs (main.epub, main.pdf, main.tex) and generated images. The static analysis found 0 internal modules and 0 import edges — this is a build-and-publish pipeline, not a library with internal logic.

How To Use It

# Step 1: Download the notebooks
chmod +x ./download_notebooks.sh
./download_notebooks.sh

# Step 2: Build the book (Option 1: CLI)
pip install -U jupyter-book
jupyter-book build .

# Step 2 (Option 2: Docker Compose)
docker compose run --rm jupyter-book

# Step 3: Open the result
# Navigate to _build/html/index.html

Configuration is in _config.yml (book title, author, etc.) and _toc.yml (chapter order). No environment variables are required. Dependencies are listed in requirements.txt.

Real-World Use

This is for an educator or team building a visual ML curriculum. The workflow: fork the repo, edit _toc.yml to reorder chapters, add new algorithm repos to download_notebooks.sh, and push — CI rebuilds and deploys the site automatically. The per-algorithm repo separation lets you update one model's implementation without touching the book's build logic.

Code Health & Issues

Static analysis (deterministic, from this pipeline) found 6 findings: 0 critical, 0 high, 5 medium, 1 low.

  • Medium — No dependency update bot configured; advisories sit unpatched. Fix: add .github/dependabot.yml.
  • Medium — Dockerfile.book uses python:3.10-slim unpinned. Fix: pin by digest and enable Dependabot's docker ecosystem.
  • Medium — No dependency vulnerability scan in CI. Fix: add dependency-review-action on pull requests.
  • Medium — checkout in CI keeps the token; a malicious postinstall script could read it. Fix: set persist-credentials: false.
  • Medium — Dockerfile.book has no non-root USER directive. Fix: create an unprivileged user.
  • Low — CI jobs lack timeout-minutes. Fix: add realistic bounds.

No test files exist — this is a build pipeline, so tests would cover the shell script and CI config rather than logic. No lockfile for requirements.txt means non-reproducible builds.

The Bottom Line

A clean, well-structured Jupyter Book build pipeline with a solid CI workflow. The per-algorithm repo split is a smart organizational choice. The security findings are standard for a small project but worth fixing before public adoption. Best for educators building a visual ML course, not for developers needing a library.