Dependency Controls for Python and TypeScript in the AI Engineering From Scratch Curriculum

The AI Engineering From Scratch curriculum enforces a strict stdlib-first policy through a centralized allowlist in AGENTS.md, permitting only six specific Python packages and four TypeScript packages to ensure educational clarity and reproducibility.

The rohitg00/ai-engineering-from-scratch repository maintains rigorous dependency controls to keep lessons focused on fundamental concepts rather than external abstractions. By mandating a stdlib-first approach and explicitly listing allowed third-party libraries in a single source of truth, the curriculum guarantees that learners can execute all code without navigating complex dependency trees. These specific dependency controls for Python and TypeScript are automatically enforced via CI checks to prevent configuration drift.

The AGENTS.md Dependency Contract

The foundation of the curriculum's dependency management resides in AGENTS.md, which serves as the central contract for the entire repository. This file contains a Dependencies table that explicitly defines the allowlist for each language, ensuring every lesson adheres to the educational mandate of minimizing external complexity.

Python Allowlist

For Python implementations, the curriculum restricts imports to the standard library plus six specifically vetted packages. According to AGENTS.md, permitted third-party libraries include:

• numpy for numerical computing
• torch for deep learning operations
• h5py for HDF5 file format support
• zstandard for compression algorithms
• safetensors for secure tensor serialization

Any lesson requiring functionality beyond these packages must justify the addition as violating the "stays stdlib-first for educational clarity" principle, requiring an update to the AGENTS.md table.

TypeScript Allowlist

TypeScript lessons operate under similar constraints, leveraging Node.js 20+ standard library capabilities supplemented by four approved packages:

• hono as the web framework
• zod for schema validation
• ws exclusively when WebSocket functionality is required
• @hono/node-server for server-side rendering

This restricted set ensures that networking and API concepts remain transparent without hiding implementation details behind heavy frameworks.

Automated Enforcement via CI

The repository automatically validates dependency compliance through scripts/audit_lessons.py. This CI script parses each lesson's import statements and requirements.txt or package.json files, flagging any violations of the AGENTS.md allowlist before merge.

Implementation Examples

Python Configuration

Lessons declare Python dependencies in a root or lesson-specific requirements.txt file, strictly adhering to the six-package limit:

# requirements.txt - AI Engineering From Scratch

# Permitted packages only - see AGENTS.md Dependencies table

numpy
torch
h5py
zstandard
safetensors

Attempting to include additional libraries such as pandas or requests triggers CI failures in scripts/audit_lessons.py.

TypeScript Configuration

TypeScript lessons utilize a package.json structure that enforces Node.js 20+ and references only the approved ecosystem:

{
  "dependencies": {
    "hono": "^4.3.5",
    "zod": "^3.22.4",
    "ws": "^8.17.0",
    "@hono/node-server": "^1.1.0"
  },
  "engines": {
    "node": ">=20"
  }
}

Note that ws should be omitted unless the lesson explicitly implements WebSocket communication, as per the AGENTS.md specification.

Summary

• The stdlib-first policy in rohitg00/ai-engineering-from-scratch limits Python to six external packages and TypeScript to four.
• AGENTS.md serves as the single source of truth for dependency allowlists, editable only when educational justification meets the strict complexity criteria.
• Continuous integration via scripts/audit_lessons.py automatically blocks pull requests introducing non-allowed dependencies.
• Learners benefit from reproducible environments without heavy or obscure package requirements.

Frequently Asked Questions

What is the stdlib-first policy in the AI Engineering From Scratch curriculum?

The stdlib-first policy requires that every lesson prioritize standard library functionality over third-party packages to maintain educational clarity. This approach ensures learners understand core algorithms and data structures without abstraction layers hiding implementation details, permitting external libraries only when fundamental to the concept being taught.

How do I add a new dependency to the curriculum?

Adding a new dependency requires updating the Dependencies table in AGENTS.md and providing justification that the package is essential for educational purposes while maintaining the stdlib-first philosophy. The change must pass review in scripts/audit_lessons.py by updating the allowlist constants within the validation logic.

What happens if I use a non-allowed package in my lesson?

Using a non-allowed package causes the CI pipeline to fail when scripts/audit_lessons.py detects the violation during automated checks. The build will block merging until the unauthorized import is removed or the AGENTS.md contract is formally amended to include the new dependency.

Is Node.js 20+ strictly required for all TypeScript lessons?

Yes, the curriculum mandates Node.js 20 or higher as specified in the engines field of package.json and documented in AGENTS.md. This version requirement ensures consistent access to modern JavaScript features and standard library APIs used throughout the TypeScript implementations.

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