# How Multi-Language Lessons Are Handled in the AI Engineering Curriculum: A Complete Technical Guide

> Discover how the AI Engineering from Scratch curriculum handles multi-language lessons using a language-agnostic contract and metadata-driven automation for Python, TypeScript, Rust, and Julia.

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

---

**The AI Engineering from Scratch curriculum implements a language-agnostic lesson contract that enables any lesson to ship parallel implementations in Python, TypeScript, Rust, and Julia through metadata-driven automation.**

The *AI Engineering from Scratch* repository by rohitg00 demonstrates how to scale **multi-language lessons** across 503 modules without manual bookkeeping. The architecture separates language-agnostic educational content from language-specific code implementations, allowing contributors to add new languages by following a standardized file structure and front-matter convention.

## Front-Matter Driven Language Declaration

Each lesson’s metadata defines supported languages through a dedicated field in the markdown front-matter. In [`phases/01-math-foundations/01-linear-algebra-intuition/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/01-math-foundations/01-linear-algebra-intuition/docs/en.md), the `**Languages:**` field enumerates every language implementation that must exist for that lesson.

When the curriculum expands to include a new language, updating this field triggers the entire toolchain to recognize the change. The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generator and [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) CI script both parse this front-matter to validate that declared languages match actual implementations.

## Parallel Code Structure and Naming Conventions

Inside every lesson folder, the `code/` directory contains language-specific entry points following strict naming conventions. According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) operating manual, the file structure must align with the front-matter declaration:

- **Python**: [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py)
- **TypeScript**: [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts)
- **Rust**: [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs)
- **Julia**: `main.jl`

The presence of these files determines how the README table renders the language matrix and how the CI pipeline executes tests. The [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) utility automatically parses the `**Languages:**` fields and counts implementation files per lesson, ensuring the displayed language list stays synchronized with the repository.

## Automated Validation and Consistency Enforcement

The curriculum enforces its multi-language contract through automated auditing. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script validates that every lesson’s `**Languages:**` field matches the `main.*` files present in its `code/` directory, preventing orphaned implementations or missing translations.

This validation runs continuously in CI, guaranteeing that the 503-lesson curriculum maintains consistency. When discrepancies occur between the front-matter declaration and the actual file system, the build fails immediately, alerting maintainers to the specific phase and lesson requiring attention.

## Scaffolding New Language Implementations

Adding support for a new language requires minimal structural changes. The [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) script creates new lessons with a Python placeholder by default, but extending to TypeScript, Rust, or Julia follows a predictable pattern.

To add a TypeScript implementation to an existing lesson:

```bash

# Create the TypeScript entry point

touch phases/10-llms-from-scratch/01-tokenizers/code/main.ts

# Update the front-matter to declare both languages

# Edit: phases/10-llms-from-scratch/01-tokenizers/docs/en.md

# **Languages:** Python, TypeScript

```

The TypeScript stub mirrors the Python scaffold structure:

```typescript
export function main(): void {
  throw new Error("implement the lesson");
}

if (require.main === module) {
  main();
}

```

## Language-Aware Testing and Build Pipelines

Each language implementation maintains its own test suite under `code/tests/`, with the CI runner executing language-specific commands based on file extensions. For example, `phases/03-deep-learning-core/01-the-perceptron/code/tests/` contains tests that run via `python -m unittest` for Python implementations or `npx tsx --test` for TypeScript versions.

This separation allows the build pipeline to execute `python -m unittest discover` for `.py` files while simultaneously running `npx tsx --test` for `.ts` files within the same lesson, ensuring all language implementations pass before deployment.

## Language-Neutral Artifacts and Reusability

All reusable components live in the `outputs/` folder and remain **decoupled from implementation languages**. Prompts, skills, agents, and MCP servers stored here can be consumed by any language implementation without modification.

This means a lesson that ships a Python-based prompt can be consumed by a TypeScript-based agent, or vice versa, maximizing cross-language reusability while maintaining strict implementation isolation in the `code/` directories.

## Summary

- **Metadata-driven architecture**: The `**Languages:**` front-matter field in `phases/*/*/docs/en.md` serves as the single source of truth for multi-language support.
- **Strict file conventions**: Entry points must follow the `main.{py,ts,rs,jl}` naming pattern inside `code/` directories.
- **Automated validation**: [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) enforces consistency between declared languages and actual files.
- **Extensible scaffolding**: [`scripts/scaffold-lesson.sh`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/scaffold-lesson.sh) and manual file creation allow rapid addition of new languages.
- **Isolated testing**: Each language maintains separate test suites under `code/tests/` with appropriate CI runners.
- **Reusable outputs**: The `outputs/` folder contains language-agnostic artifacts accessible across all implementations.

## Frequently Asked Questions

### How do I add a new programming language to an existing lesson?

Create the appropriate entry point file in the lesson’s `code/` directory (e.g., [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs) for Rust), then update the `**Languages:**` field in the lesson’s [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) front-matter to include the new language. The [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) tool will automatically update the README table, and [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) will validate the new file exists.

### What happens if the Languages field doesn't match the code files?

The CI pipeline running [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) will fail the build, reporting a contract violation. According to the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) conventions, the `**Languages:**` field must match the `main.*` files present in `code/`, ensuring the curriculum maintains strict consistency between metadata declarations and actual implementations.

### Are lesson outputs tied to specific programming languages?

No. All artifacts in the `outputs/` folder—including prompts, skills, and agents—are **language-neutral** and can be consumed by any implementation. A Python lesson can use the same MCP server or prompt template as a TypeScript lesson without modification.

### How does the curriculum handle testing across multiple languages?

Each language implementation includes its own test suite under `code/tests/`. The CI runner detects file extensions and executes the appropriate test command: `python -m unittest` for Python, `npx tsx --test` for TypeScript, or `cargo test` for Rust. This enables parallel testing of all language implementations within a single lesson.