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

> Discover criteria for approved AI engineering dependencies. Explore the stdlib-first philosophy and dependency allowlist used in ai-engineering-from-scratch for clarity.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: best-practices
- Published: 2026-06-05

---

**The repository enforces a strict stdlib-first philosophy through a language-specific dependency allowlist defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). The script [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)) for array mathematics.

```python

# 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.

```python

# ❗ 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.

```typescript
// 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.

```typescript
// ❗ 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.