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

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 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, the front-matter specifies:

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

The 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 → Python implementation
• main.rs → Rust implementation
• 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 and the corresponding 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 and Python main.py both implement the identical query-key-value computation described in the shared 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 validates the Python version
• tests.rs validates the Rust version
• 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 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 and 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
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:

# 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 declare which languages must be implemented for each lesson
• Canonical filenames (main.py, main.rs, 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 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 script parses the Languages metadata block from each lesson's 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.

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.

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