How Learning Paths Are Defined in AI Engineering From Scratch: A Complete Guide

Learning paths in the AI Engineering From Scratch repository are defined as declarative JSON documents stored in the learning-paths/ directory, containing structured metadata, ordered lessons, prerequisites, and execution commands that drive both the CLI tooling and static website UI.

The AI Engineering From Scratch curriculum by Rohit Ghumare uses a data-driven architecture to organize its educational content. Instead of hard-coding navigation logic, the repository stores learning path definitions as structured JSON files that declare dependencies, lesson sequences, and execution parameters. This declarative approach enables contributors to add new curriculum tracks by simply authoring JSON files without modifying application source code.

Learning Path Schema and Structure

Core Metadata Fields

Every learning path JSON file follows a standardized schema located in learning-paths/. The schemaVersion field tracks compatibility, while id provides a unique machine-readable identifier (e.g., model-context-protocol). Human-facing metadata includes title, summary, and estimatedMinutes, which the web UI renders in navigation panels.

Lesson Ordering and Grouping

The lessons array contains an ordered list of core curriculum items. Each lesson entry specifies:

• order: Execution sequence (integer)
• group: Logical category such as "core", "bidirectional", "secure", or "advanced"
• phase / lesson: Numeric location mapping to phases/<phase>/ directory structure
• title, path, minutes: UI rendering metadata and time estimates

Supplemental content lives in the optionalLessons array, which contains lessons not required for path completion but available for extended study.

Prerequisites and Invocation

The prerequisites array declares knowledge, software, or lesson dependencies that learners must satisfy before starting. The invocation or quickStart field specifies how to launch the path, typically containing a CLI command or skill name that scripts/lesson_run.py executes.

Implementation and Execution Pipeline

Website Discovery via build.js

In site/build.js, the build process scans the learning-paths/*.json directory to generate site/data.js. This generated file powers the navigation panels and routing logic on the documentation site. Because the discovery mechanism relies on filesystem scanning, adding a new JSON file automatically includes it in the site navigation without requiring code changes.

CLI Execution via lesson_run.py

The CLI helper scripts/lesson_run.py orchestrates local execution. It reads a path's quickStart.command (or the invocation field) and spawns the appropriate interpreter—either python3 or tsx—in the repository root. Before launching, the CLI prints prerequisite reminders based on the prerequisites array.

Working with Learning Path Files

Loading and Displaying Curriculum Structure

You can programmatically inspect any learning path by parsing its JSON definition:

import json, pathlib

PATH = pathlib.Path(
    "learning-paths/model-context-protocol.json"
).resolve()

with PATH.open() as f:
    data = json.load(f)

print(f"Learning Path: {data['title']}")
print("Core lessons (in order):")
for lesson in data["lessons"]:
    print(
        f"  {lesson['order']}. "
        f"{lesson['title']} – "
        f"{lesson['minutes']} min "
        f"[{lesson['path']}]"
    )

This script outputs the ordered lesson sequence with time estimates and directory locations, exactly as defined in learning-paths/model-context-protocol.json.

Launching Lessons Programmatically

To execute a learning path's quick-start command from Python:

import subprocess, json, pathlib

def launch_quickstart(path: str):
    with pathlib.Path(path).open() as f:
        spec = json.load(f)
    cmd = spec["quickStart"]["command"]
    cwd = pathlib.Path(spec["quickStart"]["workingDirectory"])
    subprocess.run(cmd.split(), cwd=cwd)

launch_quickstart("learning-paths/model-context-protocol.json")

This runs the exact command specified in the JSON (e.g., python3 phases/13-tools-and-protocols/06-mcp-fundamentals/code/main.py) with the correct working directory context.

Querying Optional Lessons

For Node.js environments, you can extract supplementary content:

const fs = require('fs');
const data = JSON.parse(
  fs.readFileSync('learning-paths/agent-skills.json', 'utf8')
);

console.log('Optional lessons:');
data.optionalLessons.forEach(l => {
  console.log(`- ${l.title} (${l.minutes} min) → ${l.path}`);
});

This pattern reads learning-paths/agent-skills.json to display elective modules without loading core lesson logic.

Key Files and Architecture

The learning path system relies on these specific source files:

• learning-paths/model-context-protocol.json: Defines the Model Context Protocol track, illustrating the full schema with core and optional lessons.
• learning-paths/agent-skills.json: Demonstrates the Agent Skills learning track with alternative groupings.
• site/build.js: Handles JSON discovery and generates the data layer for the static site.
• scripts/lesson_run.py: CLI entry point that parses quickStart commands and manages lesson execution.
• AGENTS.md: Documents the repository philosophy and the "one-commit-per-lesson" rule that learning paths enforce.

Summary

• Learning paths use declarative JSON files stored in learning-paths/ rather than code-based configuration.
• Each JSON defines ordered lessons, prerequisites, time estimates, and execution commands via standardized fields.
• The website build process (site/build.js) auto-discovers paths by scanning the JSON directory.
• The CLI runner (scripts/lesson_run.py) executes commands specified in quickStart fields after checking prerequisites.
• New curriculum tracks require only a new JSON file—no source code modifications needed.

Frequently Asked Questions

What file format does AI Engineering From Scratch use for learning paths?

The repository uses JSON documents following a custom schema. Each file contains fields like schemaVersion, id, lessons, and prerequisites that structure the curriculum metadata according to the specification in the repository root.

How does the repository handle lesson prerequisites?

The prerequisites array in each JSON file lists required knowledge or completed lessons. The CLI (scripts/lesson_run.py) prints reminders before execution, while the web UI uses this data to gate access or display warning indicators in the navigation panels.

Can I add a new learning path without modifying Python or JavaScript code?

Yes. Because the system is data-driven, you only need to create a new JSON file in learning-paths/ following the existing schema. Both site/build.js and scripts/lesson_run.py automatically discover and load new definitions at build time and runtime respectively.

Which files are responsible for rendering and executing learning paths?

site/build.js scans JSON files to generate site/data.js for the web interface, while scripts/lesson_run.py handles local execution by reading the quickStart.command field and spawning the appropriate interpreter in the repository root.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}