# AI Engineering From Scratch Lesson Contract: Complete Technical Specification

> Understand the AI Engineering from Scratch Lesson Contract. This technical specification ensures standardized metadata and structured quizzes for every lesson in the curriculum.

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

---

**The Lesson Contract is a formal specification defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) that mandates every lesson in the rohitg00/ai-engineering-from-scratch curriculum include standardized front-matter metadata in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) and a structured six-question quiz in [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) to ensure consistency across all 435 lessons.**

The rohitg00/ai-engineering-from-scratch repository maintains rigorous quality standards across its extensive curriculum through a formal **Lesson Contract**. This contract governs how lesson content is authored, structured, and validated before integration. According to the source code in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), the specification defines exact metadata fields, file locations, and assessment schemas that every lesson must implement to remain compatible with the curriculum's automated audit tooling.

## What Is the Lesson Contract?

The **Lesson Contract** is the authoritative specification that standardizes content creation across the AI Engineering From Scratch curriculum. As documented in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines ~68-123), this contract ensures that all 435 lessons follow identical patterns for documentation, assessment, and code presentation. The specification splits into two mandatory components: standardized front-matter for lesson documentation and a fixed JSON schema for knowledge validation.

## Core Components of the Lesson Contract

### Required Front-Matter in docs/en.md

Every lesson must contain a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file beginning with strict front-matter headers. According to [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines ~68-78), the markdown document must start with:

- **Title**: The lesson's display name
- **One-line hook**: A concise teaser describing the lesson's value
- **Type**: One of `Learn`, `Build`, or `Reference`
- **Languages**: Comma-separated list matching the `main.*` files in the `code/` folder
- **Prerequisites**: Up-stream lesson dependencies or `"None"`
- **Time**: Estimated duration (e.g., `~10 minutes`)

Following the front-matter, the document must include a **Learning Objectives** section containing 4-6 bullet points, each beginning with an action verb.

### quiz.json Schema Requirements

The second mandatory component is a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file adhering to a fixed schema defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines ~94-123). The JSON must include:

- **lesson**: Identifier string
- **title**: Quiz title matching the lesson
- **questions**: Array of exactly six question objects:
  - 1 pre-quiz question (`"stage": "pre"`)
  - 3 check-quiz questions (`"stage": "check"`)
  - 2 post-quiz questions (`"stage": "post"`)

Each question object requires:

- **stage**: `pre`, `check`, or `post`
- **question**: Prompt text
- **options**: Array of four answer choices
- **correct**: Zero-indexed integer (0-3) indicating the correct answer position
- **explanation**: Short rationale for the correct answer

## File Structure and Validation

The repository enforces the Lesson Contract through automated tooling. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script validates each lesson directory against these requirements before any merge. Key files involved in the contract include:

- [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md): Contains the complete Lesson Contract definition
- `phases/*/README.md`: Lesson-specific documentation referencing the contract
- `phases/*/*/docs/en.md`: Content file with required front-matter
- `phases/*/*/quiz.json`: Assessment file adhering to the six-question schema

## Practical Implementation Examples

### docs/en.md Front-Matter Example

```markdown

# Backpropagation from Scratch

> Derive the back-propagation algorithm without any library help.

**Type:** Build  
**Languages:** Python  
**Prerequisites:** None  
**Time:** ~15 minutes

## Learning Objectives

- Derive the gradient of a simple linear model.
- Implement the backward pass manually.
- Verify gradients with numerical approximation.
- Explain why back-propagation scales to deep networks.

```

### quiz.json Schema Example

```json
{
  "lesson": "backpropagation",
  "title": "Backpropagation from Scratch",
  "questions": [
    {"stage":"pre","question":"What does \"back-propagation\" compute?","options":["Loss","Gradients","Activations","Weights"],"correct":1,"explanation":"It computes gradients of the loss w.r.t. parameters."},
    {"stage":"check","question":"Which rule is used for gradient calculation?","options":["Chain Rule","Product Rule","Quotient Rule","L'Hôpital's Rule"],"correct":0,"explanation":"Back-propagation applies the chain rule."},
    {"stage":"check","question":"What is the purpose of a learning rate?","options":["Scale gradients","Initialize weights","Normalize data","Select optimizer"],"correct":0,"explanation":"It scales the gradient step size."},
    {"stage":"check","question":"Which of the following is a common issue with naive back-prop?","options":["Vanishing gradients","Exploding gradients","Both","None"],"correct":2,"explanation":"Both vanishing and exploding gradients can occur."},
    {"stage":"post","question":"What does a gradient-check verify?","options":["Speed","Correctness","Memory usage","Precision"],"correct":1,"explanation":"It checks that analytical gradients match numerical approximations."},
    {"stage":"post","question":"Which library can auto-differentiate?","options":["NumPy","PyTorch","Pandas","Matplotlib"],"correct":1,"explanation":"PyTorch provides automatic differentiation."}
  ]
}

```

## Summary

- The **Lesson Contract** in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) mandates standardized lesson structures across the rohitg00/ai-engineering-from-scratch curriculum.
- Every lesson requires [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with specific front-matter headers (Title, Type, Languages, Prerequisites, Time) and 4-6 action-oriented learning objectives.
- The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file must contain exactly six questions: one pre-quiz, three check-quizzes, and two post-quizzes, each with four options and zero-indexed correct answers.
- The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validation script enforces compliance automatically, ensuring all 435 lessons maintain uniform quality and structure.
- File paths follow the convention `phases/*/*/docs/en.md` and `phases/*/*/quiz.json` for lesson content and assessments respectively.

## Frequently Asked Questions

### What files are required to satisfy the AI Engineering From Scratch Lesson Contract?

Each lesson must provide a [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file containing standardized front-matter metadata and learning objectives, plus a [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) file with exactly six assessment questions. The repository's [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validates these files against the specification in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) before merging.

### How are quizzes structured in the curriculum?

The [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) schema requires an array of six questions: one pre-quiz to assess prior knowledge, three check-quizzes to verify understanding during the lesson, and two post-quizzes to confirm retention. Each question must provide four options with the correct answer specified as a zero-indexed integer (0-3) and a brief explanation.

### What types of lessons does the contract support?

The **Type** field in the front-matter accepts three values: `Learn` for conceptual introductions, `Build` for hands-on implementation projects, and `Reference` for documentation-style resources. This classification helps learners identify the appropriate engagement level for each lesson.

### How does the repository enforce the Lesson Contract?

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script automatically validates every lesson directory against the contract requirements, checking for mandatory metadata fields, proper [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) schema compliance, and correct file placement within the `phases/*/*/` directory structure.