\( \newcommand{\vect}[1]{\mathbf{#1}} \newcommand{\mat}[1]{\mathbf{#1}} \newcommand{\R}{\mathbb{R}} \newcommand{\E}{\mathbb{E}} \newcommand{\Prob}{\mathbb{P}} \newcommand{\T}{^{\top}} \newcommand{\norm}[1]{\lVert #1 \rVert} \newcommand{\abs}[1]{\lvert #1 \rvert} \newcommand{\ihat}{\mkern1mu\hat{\boldsymbol{\imath}}\mkern2mu} \newcommand{\jhat}{\mkern1mu\hat{\boldsymbol{\jmath}}\mkern2mu} \newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}} \newcommand{\argmax}{\operatorname*{arg\,max}} \newcommand{\argmin}{\operatorname*{arg\,min}} \newcommand{\cdata}[1]{\class{c-data}{#1}} \newcommand{\cmodel}[1]{\class{c-model}{#1}} \newcommand{\ctruth}[1]{\class{c-truth}{#1}} \newcommand{\cgrad}[1]{\class{c-grad}{#1}} \newcommand{\closs}[1]{\class{c-loss}{#1}} \newcommand{\cparam}[1]{\class{c-param}{#1}} \newcommand{\csecond}[1]{\class{c-second}{#1}} \renewcommand{\,}{\mkern3mu} \)

Contributing

How to help Applied AI Mastery: report a mistake, review the maths of a lesson, improve a figure, or write a module. Includes local setup and the checks every change must pass.

Thank you for helping. This project aims to teach all of data science and AI clearly, for free, and that is more than one person can do alone.

There are four ways to help, from five minutes to a few weeks.

1. Report a mistake or a confusing step

The most useful report says where you got lost.

Open an issue and give the lesson code (for example M02.4.1) and the sentence, equation or figure.
A wrong sign, a broken link, a typo and “this step lost me” are all welcome. So is “this figure is hard to read on my phone”.

2. Review a lesson

Every lesson is marked in review until someone other than its author has checked it. If you know a topic well, pick a lesson and check one of these:

Check	What to do
Sources	Open each cited source and confirm it says what the lesson claims
Maths	Re-derive every result on paper, without looking at the lesson’s steps first
Code	Run the cells, read them for clarity, try to break them
Figures	Does each figure teach one idea? Does it read at phone width and in greyscale? Is the alt text accurate?
Learning	If you are at the lesson’s level: work through it and note every place you slowed down

Report what you found in an issue titled Review: <lesson code> (<which check>). When a check passes, your name goes in that lesson’s reviewers list, with your consent.

3. Improve a figure or an interactive

Figures are Python scripts and interactives are small JavaScript modules, so a fix is a normal pull request. Read the style guide first: one colour language, labels on the parts, nothing decorative.

4. Write a lesson or a module

Please open an issue before you start, so that two people do not write the same module. Then:

Read the style guide and the notation guide.
Read a finished lesson and its figure scripts, for example M02.4.1.
Start each lesson from the blueprint: python tools/new_lesson.py M02.5.1 "Composing two maps" creates the lesson file with every section and block in place, three figure scripts, and the module folder if it is new. Folder and file names start with the item’s code.
Fill in every TODO: the lessons, the figure scripts, the module’s interactive, and a test file in tests/ that checks every number the lessons state.
Run the checks below until they pass, and open a pull request.

New courses are a bigger step: the course list is the project’s scope, so a new course starts as a written proposal in an issue.

Working locally

You need Python 3.12 or newer and Quarto 1.11 or newer.

git clone https://github.com/mkusiappiah/applied-ai-mastery.git
cd applied-ai-mastery
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

quarto preview          # builds the figures and the site, and reloads as you edit

If you have other Jupyter kernels installed on your machine, run export JUPYTER_PREFER_ENV_PATH=1 first, so that lesson code runs in this project’s environment and not in another one.

The checks

Every pull request runs these, and you can run them yourself first:

python -m pytest tests -q            # numeric tests for every derivation, and colour contrast
python tools/check_lessons.py        # blueprint, figures, alt text, notation, prerequisite graph
python tools/build_catalog.py        # regenerate catalog pages after adding lessons
python tools/run_figures.py          # every figure regenerates from its script
python tools/run_lesson_code.py      # every code cell runs and its assertions hold
quarto render && python tools/check_links.py _site    # the site builds and internal links resolve
npm install --no-save puppeteer-core && node tools/audit_overflow.mjs _site   # no text overflows its box

A change is ready when all of them pass.

A new module stays out of the navigation until a maintainer adds live: true to its module.yml, which happens when all of its lessons pass these checks.

Ground rules

Be kind and specific. Critique the lesson, not the person.
Sources must be opened. Cite only what you have opened and read against the claim. Never cite from memory.
Drafting tools are allowed, approval by them is not. If a tool helped you draft, you are still responsible for every equation and every citation. Test the numbers and open the sources.
No borrowed images. Every figure is drawn by a script in this repository.

Licence of contributions

By contributing you agree that:

your text and figures are licensed under CC BY-NC-SA 4.0 and your code under the MIT licence, like the rest of the project;
the maintainer may also publish the material in other formats, including printed and electronic books, and may later move the project to a more permissive Creative Commons licence;
you have the right to contribute what you submit.

You keep the copyright in your contribution, and you are credited in the changelog and in the lessons you worked on.