Which Python Libraries Are Banned for Educational Clarity?

The ai-engineering-from-scratch curriculum bans every Python library except numpy, torch, h5py, zstandard, safetensors, and the standard library to force students to implement algorithms like backpropagation and attention mechanisms from first principles.

The rohitg00/ai-engineering-from-scratch repository enforces a strict whitelist policy to maintain educational clarity. By explicitly enumerating which Python libraries are banned for educational clarity, the curriculum ensures that learners build neural networks, tokenizers, and optimizers manually rather than relying on high-level abstractions that obscure core mechanics.

The Definitive Allow-List in AGENTS.md

The single source of truth for permitted dependencies lives in the Dependencies table within AGENTS.md at the repository root. According to this file, the allowed Python packages are strictly limited to:

• numpy
• torch
• h5py
• zstandard
• safetensors
• stdlib (Python standard library)

This whitelist approach means that every Python library not explicitly listed is considered banned. There are no exceptions; if a package does not appear in this table, importing it violates curriculum policy.

Common Libraries on the Ban List

While the allow-list is minimal, the ban list encompasses the vast majority of the PyPI ecosystem. Typical examples of banned libraries include:

• Data manipulation: pandas, polars, dask
• Machine learning frameworks: tensorflow, keras, scikit-learn, xgboost, lightgbm
• Visualization: matplotlib, seaborn, plotly, bokeh
• Computer vision: opencv, pillow, torchvision
• NLP utilities: torchtext, transformers, spaCy, nltk
• Web frameworks and HTTP: flask, fastapi, django, requests
• Database ORMs: sqlalchemy, peewee
• Web scraping: beautifulsoup4, scrapy

If a lesson requires functionality provided by any of these banned packages, students must implement the feature manually using only the allowed libraries or pure Python constructs.

Enforcement via CI Audit

Compliance is enforced automatically through continuous integration. The repository includes scripts/audit_lessons.py, a linter that scans each lesson file for import statements and validates them against the whitelist.

If a lesson attempts to import a banned module like pandas or tensorflow, the CI audit job fails immediately, blocking the pull request. This mechanism ensures uniformity across all lessons and prevents "black-box" dependencies from entering the codebase.

Code Examples: Allowed vs. Banned

The following examples demonstrate compliant and non-compliant coding patterns found in lesson files like phases/01-foundations/01-linear-algebra/code/main.py.

Compliant NumPy Implementation

Implementing a ReLU activation using only permitted libraries:

import numpy as np

def relu(x: np.ndarray) -> np.ndarray:
    """Rectified Linear Unit using only NumPy."""
    return np.maximum(0, x)

x = np.array([-1.0, 0.5, 2.0])
print(relu(x))          # → [0.  0.5 2. ]

Compliant PyTorch Implementation

Building a linear layer without high-level torch.nn utilities:

import torch

def linear(x: torch.Tensor, w: torch.Tensor, b: torch.Tensor) -> torch.Tensor:
    """Simple linear layer without torch.nn.Linear."""
    return x @ w.t() + b

x = torch.randn(3, 4)
w = torch.randn(2, 4)
b = torch.randn(2)
print(linear(x, w, b).shape)   # → torch.Size([3, 2])

Non-Compliant Import (Banned)

The following code would trigger a CI failure:

# ❌ This import is NOT permitted in any lesson

import pandas as pd          # banned – not in AGENTS.md allow-list

Attempting to use pandas for data preprocessing, matplotlib for plotting, or scikit-learn for train-test splits requires reimplementing those functionalities manually using numpy or standard library tools.

Summary

• The allow-list in AGENTS.md restricts Python dependencies to numpy, torch, h5py, zstandard, safetensors, and the standard library.
• All other libraries are banned by omission, including popular tools like pandas, scikit-learn, matplotlib, and tensorflow.
• Compliance is enforced automatically via scripts/audit_lessons.py in the CI pipeline.
• Educational goal: Manual implementation of backpropagation, tokenization, and attention mechanisms without hiding logic behind library APIs.

Frequently Asked Questions

What happens if I accidentally import a banned library in a lesson?

The CI audit job will detect the disallowed import during the pull request process and fail the build. You must remove the banned dependency and reimplement the required functionality using only the allowed libraries before the lesson can be merged.

Can I request an exception for a specific library like matplotlib for visualization?

No. The curriculum maintains a strict no-exceptions policy to preserve uniformity. If visualization is required, implement a simple ASCII-based plotting function or use numpy to format arrays for printing. This constraint reinforces the engineering principle of understanding your data without relying on high-level visualization abstractions.

Why is torchvision banned when torch is allowed?

While torch provides the fundamental tensor operations and autograd engine necessary for building neural networks from scratch, torchvision offers high-level datasets, pre-trained models, and image transformations that would short-circuit the learning process. The ban on torchvision ensures students implement their own data loaders and image preprocessing pipelines.

How do I handle data processing without pandas?

Use numpy for all tabular data manipulation. Load CSV files using the Python standard library csv module or numpy.genfromtxt, then perform transformations using numpy array operations. For complex data structures, use Python's built-in dataclasses or typing.NamedTuple instead of pandas DataFrames.

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