What Is the Purpose of the scripts/audit_lessons.py Script in rohitg00/ai-engineering-from-scratch?

The scripts/audit_lessons.py script serves as the canonical validator that enforces structural consistency, documentation completeness, and data-schema correctness across every lesson directory in the AI Engineering curriculum.

The scripts/audit_lessons.py file in the rohitg00/ai-engineering-from-scratch repository functions as the mechanical gatekeeper for the entire educational curriculum. It programmatically validates that each lesson adheres to the naming conventions, documentation standards, and content schemas defined in AGENTS.md. By implementing a linear validation pipeline, the script guarantees that all educational content remains CI-friendly and mechanically enforceable before publication.

The Validation Pipeline of scripts/audit_lessons.py

The validator implements a systematic seven-stage pipeline that traverses the repository structure and applies strict quality controls at each step.

Lesson Discovery and Naming Conventions

The script begins by walking the phases/ directory through the iter_lesson_dirs generator function (lines 65-82). Each discovered lesson folder must match the strict NN-slug pattern enforced by the LESSON_DIR_RE regular expression (lines 25-26). This ensures consistent directory naming across the curriculum.

Documentation Completeness Checks

Every lesson must contain a docs/en.md file that meets specific quality thresholds. The validator checks that the file is valid UTF-8, exceeds the MIN_DOC_BYTES minimum size threshold (lines 33-34), and contains a proper top-level H1 heading matched by H1_RE (lines 28-29). These checks prevent empty or malformed documentation from entering the repository.

Source Code Verification

The script verifies that the code/ subdirectory is never empty by checking against CODE_IGNORED_NAMES (lines 32-33). If a lesson directory lacks substantive source files, the validator raises the L005 error code, flagging missing implementation code that should accompany the theoretical documentation.

Quiz Schema Validation

For interactive lessons containing assessments, the script loads and validates quiz.json against the CANONICAL_QUIZ_KEYS schema (lines 30-31). It enforces option count boundaries using MIN_OPTIONS and MAX_OPTIONS (lines 35-36) and validates that the correct index points to a valid option (L009). Legacy quiz formats trigger warning L007 through the LEGACY_QUIZ_KEYS detector, prompting migration to modern schemas.

Internal Link Resolution

Using MD_LINK_RE (lines 27-28), the parser extracts all markdown links from docs/en.md and confirms that every relative path points to an existing file. Broken internal links generate the L010 error, ensuring curriculum cross-references remain functional across the repository.

Reporting and Exit Codes

The main function (lines 44-73) aggregates all findings into an Audit object. By default, it prints a human-readable summary, but when invoked with --json, it outputs machine-readable reports suitable for CI pipelines. The script returns a non-zero exit code if any validation failures exist, enabling automated build gates to block malformed content.

How to Run the Lesson Validator

You can execute scripts/audit_lessons.py using Python to validate the entire curriculum or specific subsets.

Validate all lessons in the repository:

python scripts/audit_lessons.py

Limit validation to a specific phase (for example, phase 05):

python scripts/audit_lessons.py --phase 5

Generate a machine-readable JSON report for CI integration:

python scripts/audit_lessons.py --json > audit_report.json

Summary

• The scripts/audit_lessons.py script serves as the canonical validator for the rohitg00/ai-engineering-from-scratch curriculum.
• It enforces the NN-slug naming convention through LESSON_DIR_RE and validates directory structure in phases/.
• Documentation must include a UTF-8 docs/en.md file exceeding MIN_DOC_BYTES with a valid H1 heading.
• Source code directories must not be empty; missing code triggers L005 errors.
• Quiz files undergo strict schema validation against CANONICAL_QUIZ_KEYS with option count checks via MIN_OPTIONS and MAX_OPTIONS.
• Broken internal links generate L010 errors, ensuring curriculum integrity.
• The script supports JSON output (--json) and returns non-zero exit codes for CI pipeline integration.

Frequently Asked Questions

What does the L005 error code indicate in scripts/audit_lessons.py?

The L005 error indicates that a lesson's code/ directory is empty or contains only ignored files according to CODE_IGNORED_NAMES (lines 32-33). This validation ensures that every theoretical lesson includes accompanying implementation code, maintaining the repository's practical, hands-on educational standard.

How does scripts/audit_lessons.py validate quiz.json files?

The script loads quiz.json and validates it against CANONICAL_QUIZ_KEYS (lines 30-31) to ensure required fields are present. It checks that option counts fall between MIN_OPTIONS and MAX_OPTIONS (lines 35-36) and verifies that the correct index actually exists within the options array (L009). Legacy quiz formats trigger warning L007 to prompt schema updates.

Can I integrate scripts/audit_lessons.py into a CI/CD pipeline?

Yes. The script supports machine-readable JSON output via the --json flag and returns a non-zero exit code when validation failures occur. This design makes it ideal for GitHub Actions, GitLab CI, or other automated build systems that need to block merges containing malformed lessons or broken internal links.

What is the difference between scripts/audit_lessons.py and scripts/audit_certifications.py?

While scripts/audit_lessons.py validates the standard lesson structure in phases/, scripts/audit_certifications.py applies the same validation philosophy to certification-specific content. Both scripts share architectural patterns for schema enforcement and link validation, but target different content areas within the rohitg00/ai-engineering-from-scratch ecosystem.

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