If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mnielsen/neural-networks-and-deep-learning shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 2y ago

• 9 active contributors
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 92% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mnielsen/neural-networks-and-deep-learning repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mnielsen/neural-networks-and-deep-learning.

What it runs against: a local clone of mnielsen/neural-networks-and-deep-learning — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mnielsen/neural-networks-and-deep-learning | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | Last commit ≤ 734 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mnielsen/neural-networks-and-deep-learning. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mnielsen/neural-networks-and-deep-learning.git
#   cd neural-networks-and-deep-learning
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mnielsen/neural-networks-and-deep-learning and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mnielsen/neural-networks-and-deep-learning(\\.git)?\\b" \\
  && ok "origin remote is mnielsen/neural-networks-and-deep-learning" \\
  || miss "origin remote is not mnielsen/neural-networks-and-deep-learning (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 734 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~704d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mnielsen/neural-networks-and-deep-learning"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Educational implementation of neural network fundamentals accompanying Michael Nielsen's book "Neural Networks and Deep Learning". It provides working Python code samples demonstrating backpropagation, gradient descent, regularization, and deep learning concepts on MNIST handwritten digit classification, with visualization scripts that generate publication-quality figures. Flat structure: src/ contains core modules (network.py, network2.py, network3.py using Theano), data/mnist.pkl.gz is the training dataset, fig/ contains 40+ visualization scripts and their generated PNG outputs for book figures. No tests directory. No formal package structure.

Students and educators learning neural network mathematics and implementation details; people reading the accompanying textbook at http://neuralnetworksanddeeplearning.com who want to understand the algorithms by studying and running working code examples.

Stable but unmaintained: published in 2012-2022, no recent commits visible, explicitly states the maintainer will not update for Python 3 or modern Theano versions. The code works as-is for its intended educational purpose but is essentially frozen in time. Appropriate for learning fundamentals, not for production use.

Multiple critical dependency risks: pinned to Theano 0.7.0 (released 2015, unmaintained since 2017), NumPy 1.13.3 (2017), and scikit-learn 0.19.0 (2017)—all obsolete. Python 2.6/2.7 requirement is deprecated. Installation will fail on modern systems. Single maintainer with no active development. Use only in controlled educational environments or within Docker containers with old Python.

Nothing active. Repository is read-only educational material. No ongoing development, PRs, or issues being resolved. Last updates were clarifications for the book publication years ago.

git clone https://github.com/mnielsen/neural-networks-and-deep-learning.git
cd neural-networks-and-deep-learning
pip install numpy==1.13.3 scipy==0.19.1 scikit-learn==0.19.0 Theano==0.7.0
python src/network.py

Note: This will only work on Python 2.7 or with significant modifications. For Python 3, use the fork mentioned in README instead.

Daily commands: Run specific network implementations: python src/network.py trains a 2-layer network on MNIST. Run figure generation: python fig/multiple_eta.py generates fig/multiple_eta.png comparing learning rates. Each script is self-contained; no server or daemon needed.

• src/network2.py: Core implementation with backpropagation, SGD, and regularization—the main algorithm reference
• src/network.py: Simplest implementation (no regularization) showing raw backprop math, good learning starting point
• src/network3.py: Theano-based version with convolutional layers and GPU support, demonstrates deep learning
• src/mnist_loader.py: Loads data/mnist.pkl.gz; required dependency for all training scripts
• data/mnist.pkl.gz: 60,000 training + 10,000 test 28x28 grayscale digit images, the dataset all examples use
• fig/multiple_eta.py: Exemplary visualization script showing learning rate impact; template for creating new figures
• README.md: States Python 2.6/2.7 requirement and explicitly notes no Python 3 updates will be made

For algorithm changes: Edit src/network2.py (main implementation, ~300 lines, contains backprop in backprop() method, SGD in update_mini_batch()). For visualization: Create new script in fig/ following pattern of fig/multiple_eta.py (loads MNIST, runs network, plots results). For new datasets: Modify src/mnist_loader.py to add loader for your data format. For GPU acceleration: Modify src/network3.py (Theano layer definitions).

Python 2 only: Code uses xrange, print statements, dict.items() differences—will not run on Python 3.0+ without translation. Theano GPU requirement: network3.py assumes Theano/CUDA setup; CPU-only systems will run slowly. Data pickle format: mnist.pkl.gz uses Python 2 pickle protocol; may not unpickle in Python 3 without encoding='latin1'. Old NumPy API: Code uses deprecated functions like random.rand() instead of random.Generator; upgrading NumPy will cause breakage. No entry point: No main executable or setup.py; must invoke scripts directly with Python interpreter.

• Backpropagation — The core algorithm implemented in network.py and network2.py; understanding its chain-rule mechanics through code is essential to grasp how neural networks learn
• Stochastic Gradient Descent (SGD) — The optimization method used in network2.py's update_mini_batch(); variants of SGD power all modern neural network training
• L1 and L2 Regularization — Implemented in network2.py to prevent overfitting; the fig/overfitting*.py and fig/regularized*.png scripts visually demonstrate why regularization matters
• Vanishing Gradient Problem — Deep networks (network3.py with 4+ layers) suffer from this; fig/norms_during_training_*.json files measure activation magnitudes across layers to visualize the problem
• Mini-batch Gradient Descent — network2.py uses mini-batches instead of full-batch or single-sample updates; critical for practical training speed and memory efficiency
• Weight Initialization — network.py and network2.py initialize weights from Gaussian distributions; initialization strategy affects training speed and final accuracy (visible in fig/initial_gradient.json)
• Convolution (in Theano) — network3.py implements convolutional layers using Theano; essential for image tasks like MNIST classification shown in the code

• unexploredtest/neural-networks-and-deep-learning — Official Python 3.8-3.10 port of this same repository, maintained separately since the original won't update for Python 3
• tensorflow/tensorflow — Modern deep learning framework that implements the same algorithms (backprop, SGD, regularization) taught here, but production-ready with GPU/TPU support
• pytorch/pytorch — Alternative modern framework with similar capability to TensorFlow, used in contemporary neural network education
• jcjohnson/pytorch-tutorial — Tutorial-focused PyTorch examples teaching the same neural network concepts as this repo but for current Python versions
• perceptrons-and-neural-networks/book-code — Other classic textbook neural network implementations with similar pedagogical goals

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create Python 3.8+ compatibility layer in src/network3.py

The README explicitly states that network3.py uses Theano 0.6/0.7 and needs modification for later versions. This is a concrete blocker for Python 3.8-3.10 users. A new contributor could create a compatibility shim or migrate to a modern alternative (e.g., TensorFlow/Keras) while keeping the original Theano version. This directly addresses a stated maintenance gap and would unlock the codebase for modern Python users.

• [ ] Review src/network3.py and identify all Theano 0.6/0.7 specific APIs
• [ ] Create src/network3_compat.py with either Theano updates or a TensorFlow/Keras implementation maintaining the same interface
• [ ] Add version detection logic to automatically select the appropriate backend
• [ ] Test against Python 3.8, 3.9, 3.10 environments
• [ ] Update README with migration notes and new supported versions

Add unit tests for src/ modules (test_network.py, test_network2.py, test_network3.py)

The repo has no test files despite containing 3 main network implementations. Given this is educational code accompanying a published book, adding tests ensures correctness and provides learning value. Tests should validate backpropagation calculations, MNIST loading, and gradient descent behavior across all network modules.

• [ ] Create tests/test_network.py validating src/network.py (basic feedforward, backprop correctness on toy datasets)
• [ ] Create tests/test_network2.py validating src/network2.py (cost functions, regularization, MNIST loading)
• [ ] Create tests/test_network3.py validating src/network3.py (Theano compilation, training loops)
• [ ] Add numerical gradient checking tests to verify backpropagation accuracy
• [ ] Add GitHub Actions workflow (.github/workflows/test.yml) to run tests on Python 2.7 and 3.8+

Document fig/ script dependencies and add fig/README.md with regeneration instructions

The fig/ directory contains ~20 Python scripts that generate book figures, but there's no documentation of their dependencies, execution order, or how to regenerate figures. This creates friction for contributors and readers wanting to reproduce book results. A central README would clarify which scripts depend on which data files and JSON intermediates.

• [ ] Create fig/README.md documenting purpose of each script category (mnist.py, weight_initialization.py, overfitting.py, etc.)
• [ ] Map data dependencies: identify which scripts require data/mnist.pkl.gz or generate intermediate .json files
• [ ] Document execution order (e.g., generate_gradient.py → initial_gradient.json → misleading_gradient.py)
• [ ] Add a Makefile or shell script (fig/generate_all_figures.sh) to regenerate all figures in correct order
• [ ] Note any Python 2 vs 3 compatibility issues specific to figure generation scripts

• Port network.py to Python 3: The simplest implementation (no dependencies beyond NumPy/SciPy) would be a good first translation task—replace print statements, xrange→range, update dict iteration. Provides educational value as Python 2→3 migration reference.
• Add unit tests for backprop: The repository has zero test files. Create a test/test_network2.py with numerical gradient checking (compare analytical gradients from backprop against finite differences) for the network2.py implementation—fundamental practice in deep learning.
• Document figure generation pipeline: Currently 40+ .py scripts in fig/ produce PNGs with no metadata. Add a fig/README.md listing which script generates which figure, what it demonstrates, and how to reproduce it—helps readers connect code to book sections.

This repository presents significant security risks primarily due to its legacy status. The codebase uses severely outdated dependencies (6+ years old) that no longer receive security updates, Python 2 which is EOL, and includes a binary pickle file with potential code execution risks. While this appears to be intentional (educational material from 2012-2022 accompanying a book with no plans for updates), the lack of explicit security warnings or disclosure policies is concerning. The project should be clearly marked as 'legacy/educational only' with warnings against production use. Any actual usage should migrate to modern Python 3 with current dependencies, or use the provided Python 3 fork.

• Critical · Severely Outdated and Vulnerable Dependencies — requirements.txt. The project uses extremely outdated dependencies with known security vulnerabilities. numpy 1.13.3 (released Sept 2017), scikit-learn 0.19.0 (May 2017), scipy 0.19.1 (Sept 2017), and Theano 0.7.0 (Nov 2016) are all 6+ years old and contain multiple known CVEs. These packages are no longer maintained and receive no security updates. Fix: Update all dependencies to latest stable versions: numpy>=1.24.0, scikit-learn>=1.3.0, scipy>=1.10.0. Note: Theano is deprecated; consider migrating to PyTorch or TensorFlow. At minimum, document that this is legacy code for educational purposes only.
• High · Python 2.6/2.7 End-of-Life — README.md, entire codebase. The codebase is explicitly written for Python 2.6 or 2.7, which reached end-of-life in 2020 and 2010 respectively. Python 2 no longer receives security updates. This creates significant security risks when running the code. Fix: Migrate to Python 3.8+. The repository acknowledges a Python 3 fork exists; recommend users use that version or provide official Python 3 migration. Add .python-version or python_requires in setup.py to prevent Python 2 usage.
• High · Pickle File with Unknown Origin — data/mnist.pkl.gz. The repository includes a binary pickle file (data/mnist.pkl.gz) with unknown provenance. Pickle deserialization can execute arbitrary code if the file has been tampered with or originates from untrusted sources. This is a known attack vector. Fix: Replace pickle with safer serialization formats (JSON, HDF5, CSV). If pickle must be used, implement cryptographic verification. Document the source and verify integrity via checksums (SHA256). Consider regenerating the dataset from trusted sources.
• Medium · Incomplete/Truncated License Information — README.md. The MIT License notice in README.md appears to be cut off mid-sentence ('Permission is hereby granted, free of charge, to any person obtaining a copy of this software and docume'), which may create ambiguity about the actual license scope and permissions granted. Fix: Complete and display the full, untruncated MIT License text. Include a separate LICENSE.txt file in the repository root with the complete legal text.
• Medium · No Security Audit or Disclosure Policy — Repository root. The repository lacks a SECURITY.md file or documented security policy for reporting vulnerabilities. The README states 'bug reports are welcome' but provides no responsible disclosure mechanism. Fix: Create a SECURITY.md file with: (1) clear instructions for responsible vulnerability disclosure, (2) expected response timeline, (3) statement that this is legacy educational code with known limitations, (4) recommendation against production use.
• Low · Minimal Dependency Pinning — requirements.txt. Requirements.txt uses exact version pinning, which is good for reproducibility but prevents security patches. However, given the age of these versions, no patches exist, making this a non-issue for this specific case. Fix: Document why exact versions are pinned (educational reproducibility). Consider adding a note warning users about security implications.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.