The Problem

Most AI engineering material teaches theory in isolation from practice. Learners can describe attention but can't implement it, or they can call an API but can't explain what happens inside the model. This repo is a structured curriculum that forces hands-on implementation of every concept, from linear algebra to multi-agent systems, before touching high-level frameworks.

What This Does

This is a 20-phase, 435-lesson curriculum (~320 hours) covering math foundations, ML fundamentals, deep learning, vision, NLP, transformers, LLMs from scratch, agent engineering, and production infrastructure. Each lesson folder contains a docs/en.md explanation, a code/ implementation, a quiz.json assessment, and an outputs/ reusable artifact (prompt, skill, or agent). Languages include Python, TypeScript, Rust, and Julia.

The phases/ directory (2,178 files) is the core. Supporting pieces include scripts/ for automation, site/ for the web frontend, and glossary/ for reference terms. The repository also ships a Dockerfile, GitHub Actions CI, and a requirements.txt for dependencies.

How It Is Wired

Execution starts at individual lesson entry points. The primary entry is main in phases/04-computer-vision/01-image-fundamentals/code/main.py, which reaches 803 functions. Other entry points include run in phases/04-computer-vision/16-vision-pipeline-capstone/code/main.py and direct_sample in phases/10-llms-from-scratch/15-speculative-decoding-eagle3/code/main.py.

The call graph shows heavy reuse of core math primitives: sum is called from 361 places, max from 309, min from 136, and mean from 106. The most connected module is phases/01-math-foundations/12-tensor-operations/code/tensors.py, called from 162 files. phases/01-math-foundations/05-chain-rule-and-autodiff/code/autodiff.py defines the autodiff engine used across the curriculum.

External effects: 44 functions call models for inference, 56 read/write files, 42 perform cryptographic operations, and 5 run external commands. A typical path is main -> run -> gate_anchor which hashes objectives via hashlib.sha256, or extract_area -> search -> score -> predict for model inference. The wiring is largely self-contained; each lesson's code is independent, which means no cross-lesson coupling to worry about when modifying a single file.

How To Use It

Setup: Clone and install dependencies.

git clone https://github.com/moses-y/ai-engineering-from-scratch
cd ai-engineering-from-scratch
pip install -r requirements.txt

Running it: Each lesson has its own entry point. For example, run the deep learning core lessons via phases/03-deep-learning-core/03-backpropagation/code/main.py. The Dockerfile in phases/00-setup-and-tooling/07-docker-for-ai/code/ provides a containerized environment.

Configuration: No environment variables are required. API keys are covered as a lesson topic, not a prerequisite.

Real-World Use

A team onboarding new ML engineers could assign this curriculum as a structured ramp-up. Each lesson's outputs/ artifact—prompts, skills, agents—is immediately reusable in production workflows. For example, the agent-building lessons in phases/14-agent-engineering/ produce MCP servers and skills that can be dropped into an existing agent stack, giving engineers both understanding and shippable tooling.

Code Health & Issues

Static analysis found 165 findings (36 high, 129 medium). The most significant:

  • High - Duplicated code blocks: 740 repeated 6-line blocks across 91 files, concentrated in math and deep learning lessons. Extract shared helpers.
  • High - Deep nesting (47 instances): control flow reaches indentation depth 8 in files like phases/04-computer-vision/12-video-understanding/code/main.py. Use early returns.
  • Medium - Files opened without context managers (2 instances) and empty catch blocks in site/build.js and site/progress.js.
  • Medium - Broad exception handling in 8 files, including phases/00-setup-and-tooling/01-dev-environment/code/verify.py.

The repository has no test suite despite 55 test files present, and the CI workflow does not invoke them. The Docker base image (nvidia/cuda:12.4.1-devel-ubuntu22.04) is unpinned, and the container runs as root. Dependencies lack a lockfile, so builds are not reproducible.

The Bottom Line

This is a well-structured, hands-on curriculum that builds genuine understanding through implementation. The code duplication and missing test coverage are real concerns for maintainability, but for its intended purpose—education—the trade-off is acceptable. Engineers who want to understand AI deeply rather than just use frameworks will find this valuable.