For developers, engineers and project managers
Free interactive notes. Roll the dice a model rolls, train a tiny network in your browser, then finish by building a working agent harness on one page of Python.
17 notes · 81 interactive figures · 17 quizzes · free, no account
harness.py running
step 1 of 6
Model
Harness
Tools
messages: 1 item
messages
The harness starts a list with your question and sends the whole list to the model.
One real run of the loop that powers every agent. Pause it, or jump to any step.
The problem with AI explainers
You have read the explainers. You can say "attention" in a meeting. Ask how a model picks its next word and the picture goes soft. These notes make you do the thing, so the idea has somewhere to land.
A typical explainer
A note here
Poke every part of the machine until none of it feels like magic. Then write the loop that runs it.
What you get
Roll the dice a model rolls, train a tokenizer, tune a LoRA adapter, poison an MCP tool. 81 interactive figures across the series, each one built to be pushed until it breaks.
The capital of France is…
Sixteen parts, each leaning only on the ones before it. Tokens, weights, attention, training, retrieval, tools, agents.
Know why long chats cost more, what fits on one GPU, and when to retrieve instead of finetune, before the planning meeting.
Every part ends with a short quiz. Predict, answer, and see what you really understood. 17 quizzes in all.
The last lecture takes a harness apart line by line, then builds a working one on a single page of Python.
The series
About 6 hours of reading and playing in all. Each part stands on the one before it, and you can stop and pick it up next week.
Start with part 1What a model is made of
How it learns, and how you bend it cheaply
How it reaches outside itself
The loop, then the whole machine
How it works
Each note opens with a plain question, like why a model remembers nothing. The only prerequisite is the part before it.
Drag, roll, train, break. The note asks you to predict first, so you notice exactly where your picture was wrong.
A short quiz closes every part and points to the next. Stop anywhere and pick it up later.
Where it ends
The smart part you rent by the word. What you build is the dumbest program you have ever written: send the list to the model, run what it asks for, write the result down, go around again. Sixteen lines, and every agent runs on it.
harness.py
def harness(task):
messages = [user(task)] # the list starts with the question
for step in range(MAX_STEPS): # around and around...
reply = model(messages, tools=TOOLS) # send the whole list
messages.append(reply) # write its reply down
if reply.stop_reason != "tool_use": # no request? it's finished:
return reply.text # give the text to the user
results = []
for call in reply.tool_calls: # it asked for something:
try:
out = TOOLS[call.name](**call.input) # run it
except Exception as e:
out = error(e) # an error is just another result
results.append(tool_result(call.id, out))
messages.append(results) # write the results down
raise RuntimeError("step limit") # ...but not foreverQuestions
Yes. Every note is free to read, there is no account to make, and nothing sits behind an email form.
Most stop at a diagram. Here every concept has figures you operate, and you are asked to predict the result first, so you find the gaps in your own picture instead of nodding along.
It is built to end in practice. The tradeoffs that show up in real projects, like cost, hardware limits and tool security, each get their own part, and the final lecture builds a working agent harness on a page of Python.
Yes. Parts 1, 7, 10, 12, 13 and 15 are the ones that change decisions: why long chats cost more, when to retrieve instead of finetune, what fits on which hardware, and where security has to live when a model calls tools. You can skip the code and still follow every figure.
No. The figures do the arithmetic and show the maths with numbers you can change. The harness lecture has Python, short enough to read even if you never write it.
Start at part 1 if you are new, or jump to the harness lecture if you already know what tool calling is. Each part takes about 20 minutes to read, longer if you play with every figure. The whole series is roughly 6 hours.
Subscribe to the RSS feed at adamnotes.com/rss.xml with any feed reader. No email address needed.
About 20 minutes gets you through the first note. By the end of it you will know why a model remembers nothing, and you will have rolled the dice yourself.