How Multi-Language Lessons Are Implemented in ai-engineering-from-scratch: Python, Julia, Rust, and TypeScript

TLDR: The ai-engineering-from-scratch curriculum stores every lesson implementation as a code/main.<ext> file—such as main.py, main.jl, main.rs, and main.ts—under a strict AGENTS.md contract that makes each language version interchangeable, scaffolded automatically, and tested via extension-based CI detection.

The rohitg00/ai-engineering-from-scratch repository teaches AI engineering through hands-on lessons that intentionally support multiple programming languages. By standardizing how lessons are structured, tested, and scaffolded, the project makes its multi-language lessons discoverable and runnable without forcing authors to maintain separate repositories. This architecture is governed by the contract defined in AGENTS.md and executed by automation scripts in the scripts/ directory.

Multi-Language Lesson Structure and the AGENTS.md Contract

Every lesson lives inside a phases/ directory, organized under a phase folder and a lesson slug. Within that folder, a code/ directory holds the implementations, while docs/en.md stores the lesson documentation. Each language version is stored as code/main.<ext>, where the extension maps to the language—.py for Python, .jl for Julia, .rs for Rust, and .ts for TypeScript.

The AGENTS.md file defines the strict contract that makes this possible. Every lesson's docs/en.md includes front-matter that declares supported languages in a Languages field. The Monocular Depth lesson, for example, sets this value in phases/04-computer-vision/26-monocular-depth/docs/en.md. The scaffold script reads this list to generate stubs, and the CI runner reads it to decide which test commands to invoke.

Scaffolding New Lessons with scripts/scaffold-lesson.sh

When authors create a new lesson, they run scripts/scaffold-lesson.sh. This helper reads the Languages front-matter from the lesson's docs/en.md, creates the code/ and code/tests/ directories, and writes a stub file for every declared language. For example, adding TypeScript to a lesson generates code/main.ts with a header comment pointing back to the lesson spec.

The script emits boilerplate using patterns like cat >"$LESSON_DIR/code/main.<ext>" <<'EOF'. Each stub is intentionally small—usually four to six header lines—and cites the lesson documentation so authors know which logical steps to implement. Authors then fill in each main.<ext> with a language-native implementation that follows the same algorithmic flow.

Uniform Public API Across All Languages

To keep implementations interchangeable, every code/main.<ext> exposes the same public contract. Most lessons provide a run() function or an executable script that runs end-to-end when invoked directly. This uniformity means downstream lessons can call the entry point regardless of the underlying language.

Because each file follows the same logical steps—load a dataset, run a model, write artifacts—readers can compare implementations without learning language-specific boilerplate. The standard invocations are:

• Python: python3 main.py
• Julia: julia main.jl
• Rust: cargo run --release
• TypeScript: npx tsx code/main.ts

Testing Multi-Language Implementations

Each language maintains its own test suite inside code/tests/. The tests import the local main.<ext> and verify that the public API behaves identically to the reference implementation. Because the suites are language-specific, they use idiomatic testing frameworks.

Python Unit Tests

Python tests live in code/tests/test_*.py and run with the built-in unittest module:

python3 -m unittest discover

Julia Unit Tests

Julia tests live in code/tests/test_*.jl and execute through the Julia REPL:

julia --project -e 'using Test; include("code/tests/runtests.jl")'

Rust Unit Tests

Rust tests are governed by code/Cargo.toml and executed with Cargo:

cargo test --manifest-path code/Cargo.toml

TypeScript Unit Tests

TypeScript tests use *.test.ts files and run via tsx:

npx tsx --test code/tests/*.test.ts

Continuous Integration with scripts/audit_lessons.py

The scripts/audit_lessons.py CI script walks every lesson directory under phases/, builds a list of existing main.<ext> files by their extensions, and invokes the appropriate interpreter. It maps .py to python3 -m unittest discover, .jl to the Julia Test runner, .rs to cargo test, and .ts to npx tsx --test. This guarantees that every multi-language implementation is exercised on every push without manual per-lesson configuration.

Detection relies purely on file suffixes, so adding a new language to the curriculum only requires updating scripts/scaffold-lesson.sh and scripts/audit_lessons.py to recognize the new extension.

Real-World Multi-Language Examples in the Repository

The repository already contains production lessons that follow this pattern.

Python: Monocular Depth

The lesson at phases/04-computer-vision/26-monocular-depth/code/main.py implements monocular depth estimation. It runs standalone with:

python3 phases/04-computer-vision/26-monocular-depth/code/main.py

Julia: Full Transformer

The Julia implementation at phases/07-transformers-deep-dive/05-full-transformer/code/main.jl builds a full transformer model. Execute it with:

julia phases/07-transformers-deep-dive/05-full-transformer/code/main.jl

TypeScript: The Agent Loop

The agent-loop lesson at phases/14-agent-engineering/01-the-agent-loop/code/main.ts demonstrates agent orchestration. Run it via:

npx tsx phases/14-agent-engineering/01-the-agent-loop/code/main.ts

Rust: Crate-Based Execution

When a lesson includes Rust, it places code/main.rs alongside a code/Cargo.toml. The standard invocation is:

cargo run --manifest-path phases/<lesson-slug>/code/Cargo.toml

Each path follows the exact phases/<phase>/<lesson>/code/main.<ext> convention, keeping the curriculum predictable for readers and automation alike.

Summary

• Folder convention: Lessons live in phases/ and store implementations as code/main.<ext>.
• Front-matter contract: docs/en.md declares supported languages via the Languages field, enforced by AGENTS.md.
• Automated scaffolding: scripts/scaffold-lesson.sh generates stubs for every declared language.
• Idiomatic testing: Each language uses its own framework inside code/tests/, called by extension-specific commands.
• CI coverage: scripts/audit_lessons.py detects main.py, main.jl, main.rs, and main.ts files and runs the correct runner automatically.

Frequently Asked Questions

What languages does ai-engineering-from-scratch support?

The curriculum supports Python, Julia, Rust, and TypeScript by default. The extension-based detection in scripts/audit_lessons.py and the stub generation in scripts/scaffold-lesson.sh make it possible to add more languages by recognizing new file suffixes and adding the corresponding test commands.

How does the CI know which test runner to use for each lesson?

The scripts/audit_lessons.py runner scans each lesson's code/ directory for main.<ext> files. It maps .py to python3 -m unittest discover, .jl to the Julia Test module, .rs to cargo test, and .ts to npx tsx --test. Because detection is purely based on file suffixes, no per-lesson configuration file is required.

Can I add a new language to an existing lesson?

Yes. Update the lesson's docs/en.md front-matter to include the new language in the Languages list. Then run scripts/scaffold-lesson.sh to generate the main.<ext> stub and code/tests/ directory. Finally, implement the logic so it exposes the same public API—usually a run() function or end-to-end script—and add language-specific tests.

Why does each language implementation use the same public API?

Uniform entry points—such as a run() function or executable script—make lessons interchangeable across the repository. Readers and downstream code can invoke python3 main.py, julia main.jl, or cargo run with identical expectations. This design keeps the educational focus on AI algorithms rather than language-specific idiosyncrasies.

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