Every lesson in this repository is something a student does, not something they read.
A lesson ships only when all 14 gates below are green. tools/verify_all.py machine-checks
what a machine can in gates 1-12 (its docstring lists each check); tools/notebooks.py --check
and tools/verify_portable.py check gates 13 and 14. What no tool can judge -- whether an
objective is measurable, whether a quote is on the live page, whether a number in the prose was
typed -- is checked by an independent reviewer and recorded in the lesson's meta.yaml.
- Objectives — 3-5 measurable objectives in
meta.yaml, each starting with a verb ("implement", "measure", "explain why"). No objective may be "understand X". - Prerequisites and background — explicit lesson ids. A student who has done the
prerequisites can finish this lesson without reaching for anything else. A "Before you
start" box (
before_you_startinmeta.yaml, written into the notebook bytools/notebooks.py --inject) names 2-5 things the lesson assumes you can already do, and 2-5 places to learn them online: free first, paid books after, each a direct link with a one-clause reason. Links are checked bytools/check_resources.py; a reviewer confirms each one is really free (or really paid) and covers what is claimed. - Interleaving — no more than 40 lines of prose (non-blank markdown lines, hint blocks included) before the next thing the student runs. Concept, then immediately a cell they execute or edit.
- Scaffolded exercises — each exercise is a function stub with a docstring, a worked
example in the docstring,
# YOUR CODE HERE, andraise NotImplementedError. Never a blank cell. - Instant feedback — public
assert-based checks in the notebook, runnable by the student, with failure messages that name the likely mistake, not just "assertion failed". - Autograded —
tests/test_lesson.pydefines aRUBRICwith points, hidden cases and a hint per test. Partial credit is mandatory; all-or-nothing grading is a bug. - Solutions — a complete reference implementation in
solutions/, excluded from the student bundle by the build, never by.gitignorealone. - Self-check — 3+ multiple-choice questions probing the misconception the lesson exists
to fix, answers in
solutions/.
- Runs top to bottom, clean —
python lesson.pyexits 0 in a fresh interpreter. No hidden state, no cell-order dependence, no network access unless declared. - Budget honoured — declared
tierandbudget_secondsinmeta.yaml; the executor writes back measured wall time and peak RSS.cpu8means 8 GiB / 2 vCPU / <= 10 min. A lesson that exceeds its declared budget fails the gate; it does not get a bigger budget. - Data is real and free — every dataset named with its licence and a direct URL. No gated, non-commercial or registration-walled data on a required path.
- Claims sourced — every factual claim about the world carries a primary source URL
and an access date in
claims.yaml. Numbers in prose are generated, never typed.
Gates 1-12 are checked in this repository's environment, from this repository's directory. A student meets neither. They click a badge, and a notebook service opens one file in an empty directory, in a Python it chose. These two gates are about that moment.
- Opens anywhere —
lesson.ipynbis committed, generated fromlesson.py, and never edited by hand (tools/notebooks.py --check). Its first two cells are the launcher thattools/notebooks.py --injectgenerates: Open in Colab / Kaggle / Binder / Codespaces badges, and a cell that installs only what the lesson requires and is missing — pinned torequirements.txt, or for PyTorch torequirements-torch.txtand, on Linux, from PyTorch's CPU index — and fetches only the sibling files it needs. Never hand-edit it; fix the generator.tools/verify_portable.pymust pass: the notebook alone, in an empty directory, in a real kernel, in a minimal environment, on Python 3.11 and 3.12; and with--completed, the finished lesson must print the same results in both. A measurement of the student's machine — a time, a memory peak, a throughput — prints WITH ITS UNIT on the value itself (0.134 s,1.45 MiB,418 MB/s), never only in a column header. A number DERIVED from such a measurement — how many samples fit a control tick at the speed this machine ran — is itself a measurement and prints with≈in front of it. Both tell a student which numbers will differ on their machine, and they are how the comparison tells a measurement from a result: inputs and results are compared exactly, measurements are not. - Run all is a good experience — a student who opens the notebook and presses Run all
before writing a line must reach the last cell with no unhandled exception:
- every check and every demo that consumes an exercise's result runs through the lesson's
_tryguard, so an unfilled stub reports that it is not implemented yet, a wrong answer prints its check's hint and the notebook carries on, and a demo that needs an unfinished exercise names that exercise and skips; - each exercise offers progressive hints in collapsed
<details>blocks — first what to think about, then the approach in words. A hint never contains code that solves the exercise, a value the rubric checks, or a path undersolutions/; - every check that runs the student's code stops after a time limit, so an answer with a loop
that never ends fails its own row instead of freezing the notebook, and the board still
appears. The canonical guard (
tools/lesson_template/lesson.py, enforced by gate T intools/verify_all.py) gives an exercise's check_CHECK_SECONDS(never more than 10 s unlessmeta.yamlsays why), any other cell_DEMO_SECONDS(within the lesson's budget), and stops a check whose process grows by more than_MEMORY_MIB(768 MiB) of resident memory, so an answer that appends to a list for ever fails in seconds, not after gigabytes. A loop whose whole body sits in a bareexcept:is stopped too (on Python 3.12 and later also when it is inside two nested ones; on 3.11 a loop inside two nested bareexcept:blocks is not stopped, and one that allocates can fill the memory in under a second). A program the notebook starts (a compiled exercise) runs in a process group with a 1 GiB ceiling, a 64 MiB bound on what it may print, and the same time limit; the autograder (tools/grade.py) stops a rubric row after 45 s or 768 MiB of growth. What this does not cover: native Windows, which has no alarm clock, so a looping answer still hangs there (use WSL, Colab or Codespaces); a stopped check whose answer has already damaged state it shares with later cells; a thread the check started, which keeps running (and growing) after the check is stopped; the memory of a Python program the check starts (it is stopped with the check, but only compiled ones have a memory ceiling while they run); and code that is inside one native call (a very large numpy operation, a hand-written extension), which is stopped only when that call returns, whiletime.sleepand a read from a pipe are interrupted at once (on macOS, PyTorch'sDataLoaderwithnum_workersabove 0 can spin inside such a call when the guard's alarm lands in it, so no lesson uses worker processes). A time limit is not a security boundary; - the notebook ends with a progress board: one line per exercise marked ✅ passed, ❌ failed or ⏳ not started, then how many of how many are complete;
sys.exit/raise SystemExithappen only outside a notebook kernel. In a script or under CI, a failed check still ends the run non-zero; in a kernel it is a printed line, never a traceback at the foot of the page.tools/verify_portable.py(without--completed) is the check: every cell runs.
- every check and every demo that consumes an exercise's result runs through the lesson's
- Python notebooks are the default teaching surface (jupytext
py:percentis the source of truth;.ipynbis generated, never committed by hand). - C and C++ carry the systems lessons, where the point is memory, cache, precision or an
engine's real API. Built with
clang/make, graded by a test binary. - C# lessons are deferred until a .NET runner exists in CI. Authoring a C# exercise that has never been executed would violate gate 9.
A C/C++ lesson links against libmujoco inside the virtualenv, and the linker bakes that
ABSOLUTE path into the binary. Move the checkout, or rebuild the venv somewhere else, and the
binary still points at the old path: dyld: Library not loaded. make will not save you —
the binary is newer than its source, so it looks up to date.
tools/execute.py therefore deletes compiled artefacts before gating any language: c or
language: cpp lesson. A STUDENT who moves their checkout hits the same trap and has no such
guard, so every compiled lesson must tell them, in its "common mistakes" section, to run
make clean after moving or rebuilding. Authors: check this before marking a compiled lesson
reviewed.
Synapsa Commons · © 2026 RealAI · licensed under CC BY-NC-SA 4.0. You may use this material to learn and to teach, and copy, fork, share and adapt it. You must credit "Synapsa Commons by RealAI" with a link to https://github.com/TarrySingh/Artificial-Intelligence-Deep-Learning-Machine-Learning-Tutorials, say what you changed, and share adaptations under the same licence. You may not use it, or anything adapted from it, for commercial advantage or payment; for a commercial licence, contact RealAI. The full summary is in NOTICE; the licence's legal code governs.