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

> Discover the purpose of the audit_lessons.py script in rohitg00/ai-engineering-from-scratch. This script validates lesson structure, documentation, and data schemas for the AI Engineering curriculum.

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

---

**The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) using Python to validate the entire curriculum or specific subsets.

Validate all lessons in the repository:

```bash
python scripts/audit_lessons.py

```

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

```bash
python scripts/audit_lessons.py --phase 5

```

Generate a machine-readable JSON report for CI integration:

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

```

## Summary

- The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validates the standard lesson structure in `phases/`, [`scripts/audit_certifications.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.