How This Course Works
One system, built piece by piece
You do not build fourteen small demos. You build one retrieval system, Hollin Answers, and every module adds a part to it. Hollin Home Appliances is a made-up appliance maker whose support agents, repair partners and customers need answers from its documents. By the end you have a service you can show in an interview and explain stage by stage: how a document gets in, how a question finds it, how the answer cites it, and how you know it works.
The project, its people, its documents and its dates are described in 03-hollin-answers.md. It is fictional; the real cases that open each lesson are not.
One corpus, with traps in it
Every lesson uses the same forty Hollin documents, thirty-six labelled questions and five users, from 06-shared-data.md. The corpus is small enough to embed on a Colab CPU in seconds, and built to go wrong in instructive ways: an archived policy that contradicts the current one, a near-duplicate, one error code with two meanings, a table that only a careful parser keeps, documents only some people may see, a forum post with an instruction planted in it, and questions it cannot answer. You meet each trap in the module that fixes it. All of it is simulated.
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 forty to seventy-five minutes to read properly; each module README gives the time.
The same colours mean the same things in every figure:
| Colour | Means |
|---|---|
| Blue | Your system, the normal path |
| Amber | The model, anything uncertain |
| Green | Correct, safe, passed |
| Red | Failure, attack, danger |
| Grey | Optional, background, ignored |
The shape of every lesson
| Part | What happens | Why it is there |
|---|---|---|
| The situation | A problem at Hollin, brought by a named person | You learn the idea because you need it |
| A real case, first | Something that really happened, from a published source, 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 | Retrieval fails quietly; 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 Hollin Answers |
...-incident-file.md | A real, published failure, then the same failure replayed on Hollin's data and fixed |
Module 14 is a capstone lab with no new topics: it assembles the earlier modules into one production service.
Plain Python first, then the framework
Each mechanism is built by hand first, in a few lines of plain Python: BM25 scoring, cosine similarity, reciprocal rank fusion, a permission filter, a citation check. Once you have seen how it works, the lesson shows the same thing in LangChain (models, retrievers, text splitters, vector stores) or, for loops and state, LangGraph. You will know what the framework is doing for you, and you can still debug it when it does something surprising.
Measure everything
A retrieval system can look fine on five questions and be wrong on the sixth. From Module 4 on, lessons score changes on the labelled questions (how often the right document is found, and how high), and from Module 9 on, they check answers and citations. Module 11 turns this into a harness and a gate that blocks a change that makes things worse. Every number in a lesson came from running that lesson's code.
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. No installation is needed beyond the install cells the lessons give you. The module labs write files into one repository kept in your Google Drive, so it survives from one Colab session to the next; the Module 1 lab sets that up.
Every lesson that calls a model starts with the same short setup cell. It lets you choose between three model providers by changing one word. Groq and Gemini work in Colab with a free key. Ollama runs a model on your own computer, so if you choose it you work in a code editor on your machine. Embedding models and rerankers run locally from Hugging Face, in Colab or on your computer, with no key. Setup for both routes, the extra libraries and how to run the whole project locally: 02-setup-colab-and-llm-providers.md.
Some topics cannot run in a notebook: a PostgreSQL server with pgvector, Docker Compose, a CI pipeline. Those lessons give exact instructions for your own computer, say plainly that they were not run in the course, and say what was checked against the official documentation instead.
The tools
Everything in the course is open source, apart from the hosted model services, which are shown as options. Embeddings come from sentence-transformers, keyword search from rank_bm25, vector search from Chroma and FAISS in notebooks and PostgreSQL with pgvector in the service, the service itself from FastAPI. Hosted embedding, reranking and vector database products are named, and their official snippets shown, but not run.
Your answers will not match ours exactly
Language models do not return the same words every time. When a lesson shows output, yours may be worded differently. Retrieval is more stable: with the same documents, the same model and the same settings, the same documents come back in the same order. When an answer changes, the course teaches you to ask first whether retrieval changed, which is most of the skill.