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

> Discover how AI engineering learning paths are defined in the rohitg00/ai-engineering-from-scratch project. Explore structured JSON documents driving CLI tools and website UI.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: how-to-guide
- Published: 2026-08-26

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py) executes.

## Implementation and Execution Pipeline

### Website Discovery via build.js

In [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js), the build process scans the `learning-paths/*.json` directory to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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:

```python
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/model-context-protocol.json).

### Launching Lessons Programmatically

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

```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:

```javascript
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/learning-paths/agent-skills.json)**: Demonstrates the Agent Skills learning track with alternative groupings.
- **[`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)**: Handles JSON discovery and generates the data layer for the static site.
- **[`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py)**: CLI entry point that parses `quickStart` commands and manages lesson execution.
- **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)) auto-discovers paths by scanning the JSON directory.
- The **CLI runner** ([`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) and [`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js)** scans JSON files to generate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) for the web interface, while **[`scripts/lesson_run.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/lesson_run.py)** handles local execution by reading the `quickStart.command` field and spawning the appropriate interpreter in the repository root.