Why AI Engineering From Scratch Enforces Stdlib-First Dependencies Across Python, TypeScript, Rust, and Julia

AI Engineering From Scratch enforces a stdlib-first policy across all supported languages to ensure learners implement algorithms from raw mathematics before importing external frameworks, guaranteeing educational clarity and portable, reproducible code.

The AI Engineering From Scratch repository is structured as an educational curriculum rather than a production library, requiring students to build every algorithm from fundamental principles. By restricting code to each language's standard library, the project eliminates hidden implementation details and ensures lessons run deterministically on any machine without dependency management overhead.

The Educational Philosophy Behind Stdlib-First

The repository operates on a "Build It / Use It" philosophy explicitly documented in the project README. According to README.md lines 10-13, learners must first implement logic themselves using only standard library constructs, then optionally run the same algorithm through production-grade libraries like PyTorch or TensorFlow to compare behavior.

This approach ensures that students confront the underlying mathematics directly. When you write a matrix multiplication using only Python lists and loops rather than NumPy, you internalize the computational complexity and memory access patterns that high-level frameworks normally abstract away.

Five Core Reasons for the Stdlib-First Policy

The decision to restrict dependencies is codified in AGENTS.md lines 45-59, which defines the Dependency allowlist and explicitly bans external packages with the comment "stays stdlib-first for educational clarity" at line 59. The policy rests on five pedagogical pillars:

Educational clarity – By limiting code to the language's standard library, learners focus on algorithmic logic rather than memorizing third-party API signatures. The curriculum prioritizes understanding how gradient descent works mathematically over how to call torch.optim.SGD.

Portability and determinism – Stdlib code runs identically on any platform supporting the language version. Lessons work on a learner's laptop without pip install or npm install steps, and behavior remains deterministic across Windows, macOS, and Linux environments.

No hidden complexity – External libraries obscure implementation details. NumPy's broadcasting rules or Rust crate internals can mask the actual computational steps. The stdlib-first rule forces students to write low-level operations explicitly, cementing concepts like tensor indexing and memory layout.

Reproducible artifacts – Every lesson generates self-contained skills, prompts, and agents. Stdlib-only implementations guarantee that copying a lesson's output into another project never triggers dependency conflicts or version mismatches.

Consistent "Build It / Use It" split – After constructing a reference implementation from scratch, the same code is later executed through production libraries. Because the base implementation contains only stdlib code, the contrast between the handcrafted version and the optimized library version is explicit and pedagogically valuable.

Implementation Examples Across Languages

The repository demonstrates stdlib-first principles through concrete implementations in each supported language. Lesson metadata in phases/*/docs/en.md lines 6-7 explicitly marks languages as "Python (stdlib)" or "TypeScript (stdlib)" to reinforce this constraint.

Python Stdlib Implementation

This vector norm calculation from an early linear-algebra lesson uses only built-in Python types:

def l2_norm(v: list[float]) -> float:
    """Compute Euclidean (L2) norm of a vector using only the stdlib."""
    total = 0.0
    for x in v:
        total += x * x
    return total ** 0.5

TypeScript Node.js Stdlib Implementation

File processing without external npm packages, using only Node.js 20 built-in modules:

import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";

export async function countLines(path: string): Promise<number> {
  const rl = createInterface({
    input: createReadStream(path),
    crlfDelay: Infinity,
  });
  let lines = 0;
  for await (const _ of rl) lines++;
  return lines;
}

Rust Stdlib Implementation

A deterministic pseudo-random number generator for Monte-Carlo simulations, using only the standard library:

fn rng(seed: u64) -> impl Iterator<Item = f64> {
    let mut state = seed;
    std::iter::repeat_with(move || {
        // Simple linear-congruential generator
        state = state.wrapping_mul(6364136223846793005).wrapping_add(1);
        (state >> 33) as f64 / (1u64 << 31) as f64
    })
}

Julia Stdlib Implementation

The softmax function for classification lessons uses only Julia's base language features:

function softmax(x::Vector{Float64})
    maxval = maximum(x)
    exps = exp.(x .- maxval)          # stdlib broadcasting

    sumexp = sum(exps)
    return exps ./ sumexp
end

How the Policy is Enforced in the Repository

The stdlib-first rule is not merely advisory—it is mechanically enforced through repository configuration. The Dependency allowlist in AGENTS.md lines 52-58 explicitly enumerates permitted dependencies, effectively restricting code to language stdlibs and a few carefully-selected lightweight libraries.

When contributing new lessons, developers must mark the implementation language in the lesson metadata as "(stdlib)" to signal compliance. For example, the computer vision fundamentals lesson at phases/04-computer-vision/01-image-fundamentals/code/main.py demonstrates image processing using only Python's built-in struct and pathlib modules rather than OpenCV or PIL.

Summary

• AI Engineering From Scratch is a curriculum, not a production library, requiring students to implement algorithms from mathematical first principles.
• The stdlib-first policy ensures code runs portably across platforms without external dependencies, as documented in AGENTS.md lines 45-59.
• Restricting code to standard libraries eliminates hidden complexity, forcing learners to understand low-level operations like tensor mathematics and memory management.
• The "Build It / Use It" split documented in README.md lines 10-13 creates a pedagogical contrast between handcrafted implementations and optimized frameworks.
• All lesson metadata explicitly marks languages as "(stdlib)" to maintain consistent enforcement across Python, TypeScript, Rust, and Julia tracks.

Frequently Asked Questions

What does "stdlib-first" mean in AI Engineering From Scratch?

Stdlib-first means that all algorithm implementations must use only the language's standard library—Python's built-in modules, Node.js core modules, Rust's std crate, or Julia's base packages—without importing external frameworks like NumPy, TensorFlow, or PyTorch. This restriction is enforced through the Dependency allowlist in AGENTS.md lines 52-58 and reinforced in lesson metadata.

Why not use NumPy or TensorFlow directly in the lessons?

External libraries hide implementation details behind optimized C++ kernels and high-level APIs. By requiring students to write matrix operations and gradient calculations manually using only standard library constructs, the curriculum ensures they understand the computational complexity and mathematical foundations before accessing optimized implementations.

How does the repository enforce the stdlib-first rule?

The enforcement is multi-layered: the AGENTS.md file explicitly bans non-stdlib dependencies with the comment "stays stdlib-first for educational clarity" at line 59, lesson metadata in docs/en.md files labels every implementation with "(stdlib)", and code reviewers validate that imports are limited to standard library paths across all four supported languages.

Can I use external libraries after completing the stdlib implementation?

Yes. The "Build It / Use It" philosophy explicitly encourages learners to run their stdlib implementations alongside production libraries afterward. This comparison highlights the performance optimizations and API conveniences that frameworks provide, but only after the learner has built the algorithmic intuition through raw implementation.

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