# How Multi-Language Lessons Are Coordinated Across Python, Rust, TypeScript, and Julia

> Learn how ai-engineering-from-scratch coordinates multi language lessons in Python Rust TypeScript and Julia using lesson contracts naming conventions and audit scripts for cross language parity.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-08-29

---

**The ai-engineering-from-scratch curriculum enforces cross-language parity through lesson-level contracts defined in declarative front-matter, canonical file naming conventions, and automated audit scripts that validate every implementation against a shared specification.**

The rohitg00/ai-engineering-from-scratch repository teaches AI engineering through parallel implementations in Python, Rust, TypeScript, and Julia. Rather than maintaining isolated codebases, the project uses a **structured coordination system** that binds all language versions to a single source of truth. This ensures learners can explore identical algorithms regardless of their chosen stack, with automated tooling preventing divergence between implementations.

## Front-Matter Drives the Language Matrix

Every lesson begins in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) with a front-matter block that declares supported languages. This metadata serves as the **authoritative contract** for which implementations must exist.

In the transformer self-attention lesson at [`phases/07-transformers-deep-dive/02-self-attention-from-scratch/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/07-transformers-deep-dive/02-self-attention-from-scratch/docs/en.md), the front-matter specifies:

```markdown
**Languages:** Python, Rust, TypeScript, Julia

```

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) utility parses this declaration to verify that corresponding source files exist. If a language appears in the list but lacks an implementation, the audit fails and blocks the pull request.

## Canonical Entry Points in the code/ Directory

Each lesson contains a `code/` folder housing **canonical entry points** with fixed filenames. When the front-matter lists a language, the repository expects a matching `main.<ext>` file:

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

For example, the self-attention lesson includes both [`phases/07-transformers-deep-dive/02-self-attention-from-scratch/code/main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/07-transformers-deep-dive/02-self-attention-from-scratch/code/main.rs) and the corresponding [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) in the same directory. This rigid naming convention allows CI tooling to discover and validate implementations automatically without configuration files.

### Handling Missing Implementations

If a language is not yet implemented, the file is simply omitted. The front-matter is updated only when the implementation is actually added, preventing false advertising of unsupported features.

## Shared Specifications via Documentation

The lesson documentation remains **language-agnostic**, describing algorithms through mathematical notation and conceptual steps rather than syntax-specific instructions. All implementations must translate these specifications into their native idioms while preserving functional equivalence.

This approach eliminates divergence; the Rust [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs) and Python [`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) both implement the identical query-key-value computation described in the shared [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), merely expressed through different language primitives.

## Automated Validation and Testing

The repository maintains quality through **per-language test suites** and curriculum-wide audit scripts.

### Language-Specific Test Suites

Each implementation includes corresponding tests in `code/tests/`:

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

These suites verify that identical inputs produce identical outputs across all language implementations.

### The Audit Pipeline

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script scans every lesson folder to enforce the coordination contract. It checks that every language listed in the **Languages** front-matter block has a matching `main.<ext>` file in `code/`.

Additionally, [`scripts/check_readme_counts.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/check_readme_counts.py) and [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) generate the public curriculum site from the front-matter metadata, ensuring the documentation accurately reflects which implementations are available.

## Contributing a New Language Implementation

To add support for a new language to an existing lesson, contributors must follow a strict workflow that maintains the coordination contract:

1. Update the **Languages** list in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md)
2. Create `code/main.<ext>` implementing the algorithm described in the documentation
3. Add `code/tests.<ext>` verifying functional parity with reference implementations
4. Run `python3 scripts/audit_lessons.py` locally to confirm compliance

For example, adding Rust to a Python-only lesson requires:

```bash

# 1. Update the language list in the lesson's docs

sed -i '/\*\*Languages\*\:/ s/Python/Python, Rust/' docs/en.md

# 2. Create the Rust entry point (main.rs) following the spec

cat > code/main.rs <<'EOF'
/// Self-attention from scratch – Rust version
fn main() {
    // ... translate the algorithm from the docs into Rust ...
}
EOF

# 3. Add a Rust test suite (tests.rs) that mirrors tests.py

cat > code/tests.rs <<'EOF'
#[cfg(test)]
mod tests {
    #[test]
    fn test_self_attention() {
        // ... compare Rust output to reference output ...
    }
}
EOF

```

All files reside under the same lesson directory, ensuring the front-matter, entry points, and tests remain aligned.

## Summary

- **Front-matter contracts** in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) declare which languages must be implemented for each lesson
- **Canonical filenames** ([`main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py), [`main.rs`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.rs), [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.ts), `main.jl`) enable automated discovery and validation
- **Language-agnostic documentation** ensures all implementations follow identical algorithmic specifications
- **Per-language test suites** in `code/tests/` verify functional equivalence across Python, Rust, TypeScript, and Julia
- **Automated audits** via [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) prevent merges that would break the multi-language coordination contract

## Frequently Asked Questions

### How does the audit script validate multi-language coordination?

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script parses the **Languages** metadata block from each lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file. It then checks the `code/` directory for the corresponding `main.<ext>` files. If any listed language lacks its canonical entry point, the script returns a non-zero exit code, failing the CI pipeline and blocking the pull request.

### What happens if a language is listed in the front-matter but the implementation is missing?

The automated audit fails immediately. This enforcement prevents documentation from promising implementations that do not exist. Contributors must either add the missing `main.<ext>` file or remove the language from the **Languages** list in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md).

### Are the test suites identical across all four languages?

The test suites share identical input data and expected outputs, but the test code itself is language-specific. Each `tests.<ext>` file implements the same validation logic using native testing frameworks—pytest for Python, Cargo tests for Rust, Jest for TypeScript, and Julia's Test module—ensuring behavioral parity while respecting language idioms.

### Can I add a language not currently supported by the curriculum?

Yes. While the repository currently supports Python, Rust, TypeScript, and Julia, the coordination system is extensible. To add a new language, create the appropriate `main.<ext>` and `tests.<ext>` files, update the **Languages** front-matter, and ensure the audit script recognizes the new file extension. The modular structure of `ai-engineering-from-scratch` accommodates additional languages following the same contract-based approach.