How This Course Works
One inbox, measured piece by piece
You do not study ten separate subjects. You build one thing, a service that reads the customer inbox of Tidewell Cycles, a made-up bike shop in Bristol, and every module adds a part to it. Every method in the course, from a regular expression to a hosted language model, is scored on the same 80 hand-written messages, so you see exactly what each one gains and what it costs. By the end you have one repository you can show and explain line by line.
The project, its people, its data and its dates are described in 03-the-tidewell-inbox.md. It is fictional; the real cases that open each lesson are not.
Who it is for
You can write basic Python: variables, loops, functions, lists and dictionaries, and you have run a notebook. If not, start with the Python course in this series. You do not need any machine learning or NLP background: the course starts from what a character is.
Pictures first
Every lesson is a walk through one example, one picture at a time. A figure shows an idea; a short paragraph says what the figure shows in plain words; a short block of code proves it; a walkthrough explains every line of that code. Then the next figure. A lesson has fifteen to thirty figures and takes thirty to forty-five minutes to read properly.
The same colours mean the same things in every figure:
| Colour | Means |
|---|---|
| Blue | Your code, the system, the normal path |
| Amber | A model's guess, or anything uncertain (messy text, a score that may be wrong) |
| Green | Correct, safe, passed |
| Red | Failure, a wrong label, danger |
| Grey | Optional, background, ignored |
Simple methods first
Every mechanism is built the plain way before the library way: a word count in plain Python before CountVectorizer, a tagger's accuracy counted by hand before a report, BLEU computed by hand before sacrebleu. Then the course uses the library that does the job properly: spaCy, scikit-learn, gensim, sentence-transformers, Hugging Face transformers. Large language models arrive last, in Module 10, as one more tool that has to beat the cheaper ones on the same test set.
The shape of every lesson
| Part | What happens | Why it is there |
|---|---|---|
| The situation | A problem in the Tidewell inbox, with named people | You learn the idea because you need it |
| A real case, first | Something that really happened, from a published paper, write-up or report, cited | So you know the idea matters outside a course |
| The idea | Figures and short paragraphs, one running example throughout | The picture comes before the vocabulary and the formula |
| Run it | A short piece of code, pasted into Colab, with a code walkthrough | You see it work, and you understand every line |
| Break it | You make it fail on purpose | Real systems fail; see the failure here first |
| In production | What teams do with this at scale | The part most courses leave out |
| Check yourself | Three to five questions, answers hidden until you click | You find out whether it stuck |
| Exercise | One task with a way to check it | You do it, not just read it |
| Key terms and sources | A short glossary and the sources the lesson used | So you can go further |
Three depths of topic
Not every topic deserves the same attention. Each one is marked in its heading:
| Mark | Meaning | What you get |
|---|---|---|
| (Essential) | You cannot do the job without it | Figures, code and a "break it" step |
| (Recommended) | Skip it only if you have a reason | A figure and a short section, often with code |
| (Optional) | Knowing it exists is enough | An "awareness card": what it is, when you would need it |
If you are short of time, do the Essential sections of every module first and come back for the rest.
What every module contains
| File | What it is |
|---|---|
README.md | What the module is for, what you need to know first, the lesson list |
| Numbered lessons | One file per group of topics |
...-module-lab.md | A guided build that adds this module's piece to the inbox service |
...-incident-file.md | A real, published failure, then the same failure replayed in the Tidewell inbox and fixed |
Module 11 is the capstone: one lab, with three tracks to choose from (classical only on a CPU; a fine-tuned DistilBERT; a hybrid router with a hosted LLM for the hard cases) and the same evidence required of each.
Skip what you know
Each module README starts with What you need first, so you can check whether it is safe to jump ahead. If you already train text classifiers, Module 5 (evaluation) and Module 10 (the bake-off) are the ones not to skip. Where another course in this series teaches a subject in more depth (transformer internals, prompting, retrieval pipelines), the module points you to it.
How to run the code
All code runs in Google Colab. Open a new notebook, paste each code block into a cell in order, and run it. Nearly every lesson runs on Colab's free CPU and needs no key. Fine-tuning DistilBERT in Module 7 is faster on Colab's free T4 GPU, and has a CPU path too.
A few lessons call a hosted language model, mostly in Module 10. They start with the same short setup cell, which lets you choose between three providers by changing one word: Groq and Gemini work in Colab with a free key; Ollama runs a model on your own computer. Setup, the libraries and their pinned versions, the one table of model prices, and how to run the whole repository on your own computer: 02-setup-colab-and-llm-providers.md.
The data is generated, not downloaded
All Tidewell data is made by code with a fixed seed, so every learner has exactly the same 1,800 messages, the same 80 hand-written test messages, the same help centre and the same threads, and nothing has to be downloaded or signed up for. Lessons paste only the blocks they need from 06-shared-data.md, and print a short fingerprint you can compare with the one on that page. All of it is simulated, and lessons say so.
Some topics cannot run in a notebook, such as running Ollama or setting up your own computer. Those sections give exact instructions, say plainly that they were not run in the course, and say what was checked instead.
Every output is real
Every output printed in a lesson came from running that lesson's code, on the date shown. There are no hand-written "example outputs". Where a lesson tests plumbing (a parser, a retry) with a scripted stand-in instead of a model, it says so, and the stand-in's replies are never presented as what a model said. Numbers in the text come from those runs or from a cited source. Simulated data is labelled simulated.
Your numbers may differ a little
The classical parts of the course are exact: run the same cell on the same data and you get the same numbers. Two places can differ by a message or two. Training a neural network on a GPU is not perfectly repeatable, so your fine-tuned DistilBERT may score slightly differently from ours. Hosted language models do not return the same words every time, even at temperature 0. Module 5 shows how to put a confidence interval on a test score, so you can tell a real difference from that noise.