What Criteria Determine Which Dependencies Are Allowed or Banned in AI Engineering from Scratch?

The repository enforces a strict stdlib-first philosophy through a language-specific dependency allowlist defined in AGENTS.md, where only enumerated packages are permitted and all others are automatically banned to maintain educational clarity.

The rohitg00/ai-engineering-from-scratch curriculum maintains rigorous control over external dependencies to ensure learners focus on fundamental algorithmic concepts rather than framework specifics. Understanding what criteria determine which dependencies are allowed or banned is essential for contributors submitting lesson code to this educational repository. The project codifies these rules in its agent configuration and enforces them through automated continuous integration checks.

The Stdlib-First Philosophy

The foundational criterion governing all dependency decisions is educational clarity. According to the rationale documented in AGENTS.md at lines 59-60, the maintainers explicitly prioritize standard library solutions over third-party alternatives. This philosophy ensures every lesson remains self-contained and understandable without requiring knowledge of external package APIs, keeping the focus on core AI engineering concepts rather than library-specific implementations.

The Four Criteria for Allowed or Banned Dependencies

The dependency allowlist operates on four specific criteria that automatically classify imports as permitted or forbidden:

• Language-Specific Whitelist: For each supported language, AGENTS.md contains a table (lines 50-58) enumerating the exact set of allowed packages. Only libraries explicitly listed in this table—such as numpy or torch for Python—are permitted in lesson code.

• Stdlib-Only Fallback: If a capability can be expressed using the language's standard library, that approach is automatically allowed and preferred. This criterion bans third-party imports when built-in modules suffice.

• Pedagogical Necessity: Adding extra dependencies must serve a clear educational purpose that cannot be achieved with stdlib tools alone. Imports that obscure algorithmic learning goals are rejected.

• Automated Enforcement: The CI job audit executes scripts/audit_lessons.py to parse lesson source files and validate imports against the allowlist, failing the build immediately when banned dependencies are detected.

How the Allowlist Is Enforced in CI

When a contributor submits lesson code, the audit CI job automatically validates every import statement against the rules defined in AGENTS.md. The script scripts/audit_lessons.py scans directories like phases/*/*/code/ to detect violations before code reaches the main branch. Any import not explicitly listed in the language-specific table triggers a build failure, preventing accidental reliance on opaque third-party libraries.

Examples of Allowed and Banned Imports

Python Dependencies

Allowed: numpy appears in the Python allowlist (line 54 of AGENTS.md) for array mathematics.

# Using an allowed dependency – NumPy for array math

import numpy as np

def normalize(v):
    return v / np.linalg.norm(v)

print(normalize(np.array([3, 4])))

Banned: pandas is not listed in the allowlist and will be rejected by the audit script.

# ❗ This would be rejected – pandas is not on the allowlist

import pandas as pd

TypeScript Dependencies

Allowed: hono is explicitly permitted as a lightweight HTTP framework for TypeScript lessons.

// Allowed: Hono – the lightweight HTTP framework listed for TS
import { Hono } from 'hono';

const app = new Hono();
app.get('/', (c) => c.text('Hello, world!'));

export default app;

Banned: express does not appear in the TypeScript allowlist and violates the stdlib-first criteria.

// ❗ Express is not permitted – it is not in the allowlist
import express from 'express';

How to Request a New Dependency

When a contributor identifies functionality that cannot be realized with the standard library, they must submit a pull request to update AGENTS.md. The PR must justify the pedagogical need—explaining why the algorithmic concept requires this specific library and cannot be taught effectively using stdlib equivalents. The maintainers review these requests against the educational clarity criterion before modifying the allowlist table.

Summary

• The rohitg00/ai-engineering-from-scratch repository uses a strict language-specific whitelist defined in AGENTS.md (lines 50-58) to determine permitted packages.
• The stdlib-first philosophy (lines 59-60) prioritizes built-in modules over third-party code to maintain educational focus.
• Any import not explicitly listed is automatically banned and will fail the audit CI job running scripts/audit_lessons.py.
• Contributors must demonstrate pedagogical necessity when requesting new dependencies via pull request.

Frequently Asked Questions

What happens if I use a banned dependency in my lesson?

The CI pipeline will fail. The audit job runs scripts/audit_lessons.py against your code, detects the disallowed import, and blocks the merge until the violation is removed or the allowlist is updated through a reviewed pull request.

Is the standard library automatically allowed?

Yes. The stdlib-first philosophy means any functionality achievable with the language's built-in modules is automatically permitted and preferred. You do not need to list standard library imports in AGENTS.md.

How do I check if my import complies with the allowlist before submitting?

Run the audit script locally: python scripts/audit_lessons.py. This validates your lesson code against the current allowlist in AGENTS.md and flags any banned dependencies before you open a pull request.

Why are popular frameworks like Express banned while Hono is allowed?

The allowlist prioritizes educational clarity over market popularity. hono is permitted as a lightweight HTTP framework that minimizes abstraction complexity, while heavier frameworks like Express obscure underlying HTTP mechanics. The criteria favor libraries that reveal rather than hide core algorithmic concepts.

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