Know which tools this course uses, what each is for, which accounts you need, and how to keep keys and personal safe.
This course goes from understanding AI, to using AI tools, to building a tiny yourself. You will meet three kinds of tools:
Chat assistants — such as , which answer in a conversation.
— such as and , which read and change files on your computer.
tools — such as , which carry out multi-step tasks for you.
, and are the ground they all stand on, so the course teaches them too. Some chapters need a free account and some a paid plan. The teaching guide says which, and you can always follow along with the in-browser practice on SONUB instead.
Understand it the easy way
Think of it like this
Think of this course as filling a toolbox. A chat helper is the tool for asking and writing, a coding agent is the tool that edits the files on your computer, and a task agent is the tool that carries out a job with many steps. The shell, Git and Python are the workbench the tools stand on. And every toolbox needs a small safe: a place for passwords and keys that you never paste into a chat.
Example
You want a homepage for your club. You ask a chat helper for ideas and text, ask a coding agent to build the page in a project folder, save each working with Git, and publish it. The same steps return in later chapters, one tool at a time.
Common mistake
Pasting an or password into a chat “just this once” to make something work. Keys belong in environment variables or a that is never committed, and a leaked key must be replaced right away.
Three kinds of AI tools stand on three basics (shell, Git, Python). Keys and passwords stay locked away, never in a chat.A closer look
Two habits matter more than any tool. First, check the result: an AI answer, picture or change is a draft until you have read it, tested it or compared it with a source. Second, protect secrets: never paste passwords, API keys or other people's personal data into a chat, a or a file you share. API keys (the a shows to use an AI service) belong in environment variables or in a .env file (a kept only on your computer), and must never be saved (committed) to Git, which you learn in chapter 13.
Explain it yourself
Explain in your own words the three kinds of AI tools in this course and give one example of each.
Compare with an explanation
Chat assistants answer in a conversation (ChatGPT). Coding agents read and change files and run commands in a project (Codex, Claude Code). Agent tools carry out multi-step tasks across files and apps (Claude Cowork). All three produce drafts that I have to check.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Introduce the course map (5 min) → show one example of each kind of tool (10 min) → students set up accounts and a course folder (15 min) → safety rules and questions (10 min). Stretch or shorten each part to fit your lesson length.
Show on screen
Open this course and walk through the chapter list: getting started → how AI works → using AI tools → developer basics → build and publish → AI agents → agents that keep working → build your own → run your anywhere → the final project.
Ask a chat assistant one short question, then show a coding agent changing one line in a file, so students see the difference between talking and acting.
Show where an API key should live (an environment variable or a .env file) and how a line keeps it out of Git.
Student tasks
List which tools you can already use (ChatGPT, Codex, , ) and which you still need to sign up for.
Create an empty folder named ai-course on your computer; later chapters use it.
Done when
The student names the three kinds of AI tools with one example each and states the two safety habits.
If students get stuck
No paid plan: follow the demonstrations and use the in-browser practice on SONUB; every concept chapter works without an account.
A school or office computer blocks installs: use the web versions of the tools and the SONUB shell and Python practice.
Questions for the class
What is the difference between asking a chat assistant and letting a coding agent change your files?
Where should an API key be stored, and where must it never appear?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 2 · Beginner · How AI works
AI words: the 10 terms you will hear every day
Goal
Explain the everyday words — , , , , , , , , , — in one simple sentence each.
A model is a that has learned patterns from . A (LLM) learned them from huge amounts of text and predicts the next piece of text. The words in this chapter:
prompt — what you type
token — the unit the model reads, a small piece of a word
context window — how many tokens the model can see at once, including the conversation so far
parameters (also called ) — the numbers inside the model that training adjusts
training — the long, expensive learning step
inference — using the finished model to answer you
Understand it the easy way
Think of it like this
Picture a restaurant. The model is the chef, the prompt is your order slip, and tokens are the small pieces the ingredients are cut into. The context window is the size of the chef's worktable, and parameters are the skills the chef has built up. Training is cooking school, inference is cooking your meal right now, a hallucination is a dish that looks good but is not what you ordered, an API is the delivery window, and an agent is a chef who also goes shopping for the ingredients.
Example
You type “What will the weather be in Seoul tomorrow?”. The model reads it as tokens. A without a search tool cannot know tomorrow's weather, so it may invent a believable forecast (a hallucination). An agent with a search tool can look up a weather site first and then answer.
Common mistake
“More parameters always means more correct answers.” Size is only one part of what a model can do. and checking still decide how good the result is.
A closer look
A few more words:
hallucination — a confident answer that is wrong or made up. That is why you always check.
API — a door that lets your own program send a prompt and get the answer back, usually with a secret .
chatbot and agent — a chatbot only answers, but an agent can also act: read files, run commands and use tools, step by step, toward a goal.
open and — models, or models whose weights are published (), can be downloaded and run on your own computer. Closed models are used only through the company's app or API.
Explain it yourself
Explain to a friend what a context window is and why it matters.
Compare with an explanation
The context window is how much text (in tokens) the model can look at at one time — your prompt, files and the conversation so far. If something falls outside it, the model cannot see it any more, so long chats can lose early details. Putting the important facts into the prompt again fixes this.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Ask students which AI words they have heard (5 min) → explain the words in pairs: prompt/token, training/inference, chatbot/agent (15 min) → word-matching game (10 min) → self-check (10 min).
Show on screen
Type a sentence into a page or the SONUB tokens chapter and count the tokens together.
Ask a chatbot a question it cannot know (a made-up person) and show a hallucination; then show how to check it.
Compare a chatbot answering "how do I rename this file?" with an agent that actually renames it.
Student tasks
Make your own word card: each of the ten words with a one-sentence meaning and an example.
Find one hallucination by asking a chatbot about something very or very new, and write how you checked it.
Done when
Students can explain the ten words in their own words and give the difference between training and inference and between a chatbot and an agent.
If students get stuck
Students mix up training and inference: training = studying for the exam, inference = writing the exam.
Tokens are confusing: show that a long or rare word becomes several tokens while a common word is one.
Questions for the class
Why can a model "forget" what you said at the start of a very long conversation?
What is the difference between asking a chatbot and giving a task to an agent?
is a field of building systems for tasks such as prediction, recognition, planning, and generation. Some systems use rules written by people. instead fits patterns from ; uses with many layers.
Understand it the easy way
Think of it like this
Think of “vehicles”. Vehicles are the big group (AI). Cars are one kind of vehicle (machine learning), electric cars are one kind of car (deep learning), and one particular electric car model is like a . Each name is narrower than the one before.
Example
A that decides by rules a person wrote (for example, a rule that marks mail containing ‘free’ or ‘winner’ as spam) is AI without learning. A spam filter that learns from example emails is machine learning. Finding a cat in a photo is usually deep learning. A that answers your questions is built on an LLM.
Common mistake
“AI means .” ChatGPT is one product built on a . , and route planners are AI too.
AI is the biggest circle. Machine learning, deep learning and language models each sit inside the one before.A closer look
A large language model (LLM) is one kind of AI. Many text-generating LLMs predict the next from the available . , , and can work differently. Fluent language is not evidence that a system is alive or that its output is true.
Explain it yourself
Does every AI system generate the next word? Give a counterexample.
Compare with an explanation
No. A spam filter picks ‘spam’ or ‘not spam’, and a rule-based program only follows fixed conditions; neither generates the next word.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Ask what students think AI is (5 min) → sort examples into rules, machine learning and language models (10 min) → read and discuss the chapter (15 min) → self-check (10 min).
Show on screen
Show three examples side by side: a spam filter written with rules, a photo app that learned to recognise faces, and a chat assistant that generates text.
Draw three circles: artificial intelligence, machine learning inside it, deep learning inside that, and place language models in the innermost circle.
Student tasks
List five apps you use and label each one as rules, machine learning or a language model, with a reason.
Done when
The student gives a correct counterexample of an AI system that does not generate words.
If students get stuck
Students think every AI is ChatGPT: show a rule-based spam filter and a recommendation system as other kinds of AI.
Questions for the class
Is a thermostat that follows the rule "heat when below 20 °C" artificial intelligence? Why or why not?
State the task, useful , constraints, and a way to check the result.
A is input that guides a . Compare “Explain fractions” with “For a beginner, explain one half using a pizza example, then ask me one question without giving its answer.” The second request specifies an audience, an example, and a learning activity.
Understand it the easy way
Think of it like this
A prompt is like telling a taxi driver where to go. “Downtown, please” gets you somewhere near. “Exit 3 of City Hall station, by 10 o'clock” gets you exactly where you need to be. The clearer the destination, the less the driver has to guess.
Example
Vague: “Tell me about fractions.”
Clear: “Explain one half to a 9-year-old using a pizza, in three short sentences, then give one practice question without the answer.”
The second prompt sets the reader, the example, the length and the activity.
Common mistake
“If I write ‘You are an expert’, the answer will be expert-level.” A role can change the tone, but it does not add knowledge. You still need to check the facts.
A closer look
A role can guide tone, but does not grant expertise or guarantee compliance. Ask for sources when needed and verify that they support the claim. Compare two prompts on the same examples. Share only necessary information; a clearer prompt can help, but cannot remove every model limitation.
Explain it yourself
Does “You are an expert” make an answer reliable?
Compare with an explanation
No. It can guide the style; evidence and are still needed.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Compare a vague and a precise request (10 min) → improve one prompt together (10 min) → students write and test prompts (20 min) → discuss how to check answers (10 min).
Show on screen
Ask "Explain fractions", then the precise from the chapter, and compare audience, example and activity in the two answers.
Add "You are an expert" to a prompt and show that the answer can still contain a mistake.
Student tasks
Write a prompt for a topic you are learning that states the audience, one example and a way to check the answer.
Done when
The student's prompt names the task, the context, a constraint and a check.
If students get stuck
The answer is still vague: add an example of the output you want and a length limit.
Questions for the class
Which part of your prompt made the biggest difference to the answer?
Prompt engineering: six parts of a prompt that works
Goal
Write with a role, goal, , examples, constraints and , and improve a prompt step by step instead of starting again.
means writing instructions so that a gives the result you need. A good prompt usually has six parts:
Role — who the model should act as
Goal — what you want
Context — the facts, files or audience it needs
Examples — one or two samples of a good answer
Constraints — length, level, what to avoid
Output format — a list, a table, , a file
The more of these you give, the less the model has to guess.
Understand it the easy way
Think of it like this
A good prompt works like a recipe card handed to a cook. It says who is cooking (role), what dish you want (goal), what is in the fridge (context), a photo of the finished dish (example), what to avoid (constraints) and how to serve it (output format). With all six, the cook hardly has to guess.
Example
Role: “You are a primary school science teacher.”
Goal: “Explain the water cycle.”
Context: “The readers are 8-year-olds.”
Example: “Like this: ‘The sun warms the sea…’”
Constraints: “Five sentences, no difficult words.”
Output format: “A numbered list.”
Common mistake
Trying to write a perfect prompt in one go. Write a first , read the answer, and add only what was missing.
Role, goal, context, example, constraints and output format fit together like a recipe card. A vague note leaves the cook guessing.A closer look
Treat a prompt like a draft. Read the answer, find what is missing or wrong, and add exactly that to the prompt: "use simpler words", "give three options", "cite the source".
For hard tasks, ask the model to plan first and answer second.
Or split the task into several smaller prompts.
For , put the long-lived parts (rules, commands, style) in a project file such as CLAUDE.md or AGENTS.md, so you do not repeat them every time.
Explain it yourself
Rewrite "make a homepage" as a prompt with the six parts.
Compare with an explanation
For example: "You are a web designer (role). Make a one-page homepage for my bakery (goal). It sells bread and cakes in Seoul; customers are families (context). Keep the style like this sample: … (example). Use only and , , no more than four sections (constraints). Give one file (format)." Any prompt with all six parts is correct.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Show a weak prompt and its answer (5 min) → rebuild it with the six parts (15 min) → students improve a prompt in three rounds (15 min) → compare results (5 min).
Show on screen
Ask "write about climate" and then the same request with role, audience, length and format; compare the two answers.
Add one example answer to a prompt and show how the style of the result follows it.
Ask for the result as a table, then as JSON, from the same prompt.
Student tasks
Write a prompt with all six parts for a real task of yours (a study plan, a summary, an email).
Improve it twice: each time add one fix based on what was wrong in the answer, and keep all three versions.
Done when
The final prompt has the six parts, and the student can point to the change that fixed each problem.
If students get stuck
The answer is too long or too general: add the audience, a length limit and the format.
The model ignores a rule: move the rule to the end, say it once clearly, and ask it to check the rule before answering.
Questions for the class
Which of the six parts helps most when the answer is in the wrong style?
Why put long-lived rules in CLAUDE.md or AGENTS.md instead of every prompt?
Tell text pieces () apart from the numbers () given to them.
A converts text into pieces called tokens and maps them to IDs in a . Tokens may be words, word pieces, characters, or ; spaces and punctuation also matter. The same text can have different token counts with different tokenizers.
Understand it the easy way
Think of it like this
A tokenizer is like a machine that cuts a long paper strip of text into pieces of different sizes and hangs a number tag on each piece. The never sees letters — it only sees the row of number tags.
Example
The English word “unbelievable” might be cut into “un”, “believ” and “able”. A space or a full stop can be a token of its own. The same sentence can become a different number of tokens with a different tokenizer, and many languages need more tokens than English for the same meaning.
Common mistake
“The number of tokens equals the number of words (or letters).” It is neither. That is why the same text can cost a different amount, or fill the faster, in another language.
Text is cut into tokens of different sizes, and each token gets an ID number. The model works with the numbers.A closer look
Our toy lab uses a simple word tokenizer, not a tokenizer. An ID is just a label: ID 8 is not twice the meaning of ID 4. A context window limits how many tokens a model can use; the application may select, summarize, or discard material to fit.
Explain it yourself
If two tokens have adjacent IDs, must their meanings be similar?
Compare with an explanation
No. IDs identify vocabulary entries; their numerical distance does not measure meaning.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What a token is (10 min) → count tokens of the same sentence in different ways (10 min) → students tokenise their own sentences (20 min) → self-check (10 min).
Show on screen
Split "unbelievable!" into characters, into words and into word pieces such as un + believ + able + !, and count each.
Show that IDs are only labels: two tokens with neighbouring IDs can mean completely different things.
Student tasks
Write one sentence and split it into characters and into words; write a made-up ID next to each piece.
Done when
The student explains why the same text can have different token counts.
If students get stuck
Students confuse tokens with words: show a long word split into several tokens, a punctuation mark that can be its own token, and a space that usually joins the next word in one token.
Questions for the class
Why do services often count usage in tokens rather than words?
An ID is a label. A is a list of numbers. A one-hot vector marks just one position with 1 and the others with 0; it does not express semantic . An embedding is a learned vector. can place related uses near one another, depending on the and learning objective.
Understand it the easy way
Think of it like this
An embedding gives every word a place on a giant map. Words that are used in similar ways end up close together, and words that are used differently end up far apart. Instead of two coordinates like a paper map, the uses hundreds or thousands of numbers.
Example
“Cat” and “dog” sit close together, and “cat” and “car” sit far apart. That is why a search for “dog food” can still find a document about “food for puppies”, even though the words are different.
Common mistake
“If two words are close, they mean the same thing, or the sentence is true.” Closeness only shows similar use in the . “Hot” and “cold” can be close because they appear in the same kinds of sentences.
Things used in similar ways are placed close together on the map. Distance shows similarity of use, not truth.A closer look
Modern () use to mix in information from the other in the (you learn it in chapter 33), so a token's representation can change with its sentence. Similarity is not truth or identical meaning. The famous king − man + woman analogy is an illustrative result from some word embeddings, not a universal equation. Search compares query and document vectors in a compatible .
Explain it yourself
Do nearby embeddings prove that two statements say the same true thing?
Compare with an explanation
No. They may share a topic while disagreeing. Read and verify the actual claims.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
From IDs to vectors (10 min) → one-hot vectors versus learned embeddings (10 min) → students place words on a 2-D map (20 min) → self-check (10 min).
Show on screen
Write a one-hot vector for "cat" in a five-word vocabulary and show that it says nothing about similarity.
Draw a 2-D map where cat and dog are close and car is far, and explain that training places them there.
Student tasks
Place eight words of your choice on a 2-D map by meaning and explain two of the positions.
Done when
The student distinguishes an ID, a one-hot vector and an embedding.
If students get stuck
Students think nearby embeddings mean "true": show two opposite statements about the same topic that sit close together.
Questions for the class
If two sentences have nearby embeddings, what can and cannot we conclude?
Our model counts which word follows the previous word. If red follows sky three times and blue once, their are 3/4 and 1/4. Modern neural instead many to reduce prediction (a number for how wrong the predictions are). At inference time they use those weights and the available to calculate scores for the next . This demo illustrates conditional prediction, not the full .
Understand it the easy way
Think of it like this
Training is like months of studying for an exam: it takes a long time and a lot of energy, and it changes what is in your head (the weights). Inference is answering questions in the exam room: quick, and your head does not change. is an open-book exam: you are allowed to look things up in a book while you answer.
Example
A company wants a that answers questions about its own rules. means studying again so the rules change the weights. RAG means keeping the rule book open and handing the right page to the model with each question, so the rules can be updated without retraining.
Common mistake
“The model learns from every chat right away.” A normal chat is inference. Unless a company later uses the to train again, your chat does not change the weights.
Training slowly adjusts the dials (weights). Inference uses the locked dials to answer quickly.A closer look
Fine-tuning changes model weights; trains smaller while base weights can stay frozen. RAG (retrieval-augmented generation) retrieves material and supplies it as context without requiring weight updates. ranks lexical matches using term frequency with saturation and document-length ; compares learned . Either can miss evidence or retrieve misleading text. A chat message is not automatically a training update.
Explain it yourself
An app retrieves a new manual and adds it to the . Is that necessarily fine-tuning?
Compare with an explanation
No. Retrieval adds context. Fine-tuning requires a training process that updates weights.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Training versus inference (10 min) → the bigram counting example (10 min) → retrieval versus fine-tuning (10 min) → students sort scenarios (10 min) → self-check (10 min).
Show on screen
Work through the chapter's sky → red/blue counting example on the board and compute the probabilities.
Show an app that pastes a manual into the prompt (retrieval) and explain that the model's weights did not change.
Student tasks
Sort five scenarios into training, inference or retrieval, for example "a chatbot reads today's menu before answering".
Done when
The student explains what changes during training and what the model uses at inference time.
If students get stuck
Students think a chatbot learns from every chat: explain that its weights stay the same unless it is retrained.
Questions for the class
Why can a model answer about a document it was never trained on?
Know that always giving the same answer (consistency) is not the same as giving a right answer (factual ), and compare generation settings.
System instructions guide an assistant but do not guarantee obedience or secure tool access. The application must enforce . rescales scores before (the step that turns scores into ): lower positive values concentrate probability, higher values flatten it. keeps a fixed number of candidates; top-p keeps a set reaching a chosen . Neither setting checks facts. chooses a highest-scoring token rather than .
Understand it the easy way
Think of it like this
Temperature is like an adventure dial. Turn it down and the almost always picks the most likely word. Turn it up and it tries surprising words more often. Top-k keeps only the k most likely candidates in the jar, and top-p adds probabilities from the largest down and keeps the smallest group that reaches at least p.
Example
For a maths answer or a summary that must stay close to the source, use a low temperature. For story ideas or brainstorming names, a slightly higher temperature gives more variety. Either way, check the facts yourself.
Common mistake
“A lower temperature makes the answer true.” It only makes the choice more predictable. A wrong but likely sentence stays wrong.
Greedy decoding always takes the tallest bar. Sampling draws from the jar, so the result changes a little each time.A closer look
Try greedy and sampling modes several times in the builder. Sampling can repeat the same result. Temperature zero does not guarantee identical output across real systems: model , , tools, and numerical execution also matter. Then compare a vague question with one giving a goal, context, and a way to check the answer. Test a factual claim against an original source; use hints and explain the result in your own words.
Explain it yourself
Can a low-temperature model confidently repeat a false answer?
Compare with an explanation
Yes. Concentrated probabilities are not evidence of truth. Check the claim independently.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Instructions versus permissions (10 min) → temperature, top-k and top-p with numbers (15 min) → students predict outputs (15 min) → self-check (10 min).
Show on screen
Take scores for three tokens, apply a low and a high temperature, and show how the probabilities sharpen or flatten.
Ask the same question twice at a high temperature and show that the answers differ, then explain that neither is checked for truth.
Student tasks
For the probabilities 0.6, 0.3, 0.1, say which tokens top-k = 2 and top-p = 0.8 keep.
Done when
The student explains that a low temperature makes answers consistent but not necessarily correct.
If students get stuck
Students think the is a wall: explain that the application, not the , must enforce permissions.
Questions for the class
When would you want a higher temperature, and when a lower one?
Write requests with a goal, , constraints and an , improve them step by step, and check the answer before using it.
is a chat assistant built on large . It writes, summarises, translates, explains and plans. It can read files and pictures you attach, and search the web when that feature is on.
A good request has four parts:
the goal — what you want
the context — who it is for and what you already have
the constraints — length, tone, what to avoid
the format — a list, a table, an email
When the first answer misses, do not start over — say exactly what to change. Keep one conversation on one topic so earlier messages help instead of confuse.
Understand it the easy way
Think of it like this
Treat ChatGPT like a capable new helper on their first day. They work fast, but they do not know your situation unless you tell them, and they sometimes sound sure when they are wrong. Explain the job clearly, look at the first draft and give specific feedback.
Example
First request: “Write a party invitation.”
Better: “Write a birthday party invitation for my 10-year-old's classmates: Saturday 2 pm, at our home, bring a swimsuit, under 80 words, friendly tone.”
Follow-up: “Make the second sentence shorter and add a line asking parents to reply by Thursday.”
Common mistake
Mixing many topics in one chat. Earlier messages keep affecting later answers, so start a new chat for a new topic.
Improve the answer one step at a time with specific feedback, then check it against another source before you use it.A closer look
A language model predicts likely text, so a fluent answer can still be wrong. Ask for sources and open them, compare numbers with the original, and ask the to list its assumptions. For important facts, check a second, independent source. and projects let ChatGPT remember your preferences, but they are still instructions, not guarantees, so keep checking.
Explain it yourself
Rewrite the request "Help me with my presentation" so that it has a goal, context, constraints and a format.
Compare with an explanation
For example: "Goal: a five-slide outline. Context: a three-minute talk about recycling for 13-year-olds. Constraints: simple words, one statistic per slide with its source. Format: a slide title and two each." Any answer that clearly states all four parts is correct.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
A weak request versus a strong one (10 min) → live improvement in three turns (10 min) → students write and refine their own request (20 min) → compare and check answers (10 min).
Show on screen
Ask "Tell me about Korea." Then ask: "Goal: a five-line introduction to Korea for a 10-year-old. Context: they live in Brazil. Constraint: no history dates. Format: bullet points." Compare the two answers.
Follow up with a precise change such as "Make line 3 shorter and add one food example" instead of asking again from scratch.
Ask a question whose answer contains a number, ask for the source, open it and check whether the number matches.
Student tasks
Pick a real task (an email, a study plan, a summary) and write a request with a goal, context, constraints and a format.
Improve the answer in at least two follow-up messages and write down one claim you checked and how.
Done when
The final request has all four parts and the student shows one fact they checked against a source.
If students get stuck
The answer is too long or too general: add a length limit and an audience, and give one example of what you want.
The answer invents a source or a number: say so, ask for a link, and treat anything you cannot verify as unconfirmed.
Questions for the class
Which of the four parts changed the answer the most in your example?
Why can a confident, fluent answer still be wrong?
Describe a picture precisely, change one thing at a time, and check the result for mistakes, rights and honesty before using it.
Image turn a text description into a picture, and many can also edit a picture you give them. and can create and edit images, and Google offers its image models (the older models in the have been shut down). A good image includes:
the subject and the setting
the style
the composition — close-up or wide, where things are
the colours
the size or
To edit, say what must change and what must stay the same, for example "keep the girl and the background, change only the umbrella to yellow".
Understand it the easy way
Think of it like this
Asking for a picture is like describing a scene to an artist on the phone. They cannot see what is in your head, so say who is in the picture, where it is, the art style, how close the view is, the colours and the of the picture. When you ask for a change, say what must stay the same too.
Example
“A girl with a yellow umbrella walking on a rainy street at dusk, warm watercolour style, seen from a little distance, soft blue and orange colours, wide 3:2 picture.” Then: “Keep the girl and the street the same and change only the umbrella to red.”
Common mistake
Using the picture without zooming in. Look for extra fingers, wrong letters and impossible shadows, and do not present a generated picture as a real photo.
Zoom in before you use a generated picture: check hands, letters and shadows, and be honest that made it.A closer look
Generated pictures often hide small errors: wrong letters, extra fingers, impossible shadows. Always zoom in and check. Do not use a generated picture to pretend that something really happened, do not imitate a living artist or a real person without , and say that a picture was made with AI when it matters. Read the terms of the tool before using pictures commercially.
Explain it yourself
Write an edit request that changes only the background of a portrait to a beach and keeps the person exactly the same.
Compare with an explanation
For example: "Keep the person, their face, clothes, pose and lighting exactly as they are. Change only the background to a sunny beach with the sea behind them." It must name what changes and what stays.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
A weak prompt versus a strong one (10 min) → one edit that keeps everything else (10 min) → students make and edit their own picture (20 min) → review mistakes and rights (10 min).
Show on screen
Generate "a cat", then "a watercolour of an orange cat sleeping on a blue chair by a sunny window, wide shot, 4:3", and compare.
Edit the second picture: "Keep everything the same, change only the chair to green." Point out anything that changed by accident.
Zoom into the result and find one mistake in text, hands, shadows or perspective.
Student tasks
Write an image prompt with the subject, setting, style, composition, colours and size, and generate it.
Make one edit that changes exactly one thing and note whether anything else changed.
Done when
The student shows the prompt, the edit request and one mistake they found in the result.
If students get stuck
The picture ignores part of the prompt: put the most important detail first and remove words that conflict.
The text in the picture is misspelled: ask for fewer words, or add the text afterwards in a normal editor.
Questions for the class
Why should an edit request say what must stay the same?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 12 · Beginner · Using AI tools
Shell and basic commands: where AI tools run
Goal
Use the ten basic (, , , , , , , , clear, exit). Start and leave tools in a project folder, and know which commands are dangerous.
, , the and most run in a terminal, a window where you type commands for a called the . These are the basic words:
pwd — where am I
ls — what is here
cd — go there (cd .. goes back up)
mkdir — make a folder
cat — show a file
cp — copy
mv — move or rename
rm — delete (no recycle bin)
clear — clean the screen
exit — close the
You start an AI tool the same way, inside the project folder: (Claude Code), codex (Codex) or (Antigravity CLI). SONUB has a full shell course with a practice terminal in the , and this chapter sends you to its first units.
A closer look
Inside an AI tool, commands that start with a slash control the tool itself:
— writes a project instruction file.
/help — lists the commands.
— starts a fresh conversation.
/exit — leaves the tool.
Unit 11 of the shell course shows how to install AI tools and check them with . Install commands change, so compare them with the official page. Press to stop a command that is still running. When an AI proposes a command, read it before allowing it. rm deletes right away, with no recycle bin, and removes everything in a folder without asking.
Your progress for this chapter is recorded in that course.
Commands to type in your terminal
pwd # where am I?
ls # what is here?
mkdir ai-course # make a folder
cd ai-course # go into it (cd .. goes back up)
cat notes.txt # show a file
cp notes.txt copy.txt
mv copy.txt old.txt # move or rename
rm old.txt # delete for good (no recycle bin)
clear # clean the screen
claude # start an AI agent in this folder (or: codex, agy)
/init # inside the agent: write the project instruction file
/help # list the agent's commands
/exit # leave the agent
These run in a terminal on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Which three commands would you use to go into a folder called ai-course, see what is in it, and confirm where you are?
Compare with an explanation
cd ai-course to go in, ls to list what is there, and pwd to print where I am.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Why the terminal matters for AI tools (5 min) → a live tour of pwd, ls, cd and mkdir (10 min) → students do units 1 and 2 in the SONUB shell (25 min) → the install check from unit 11 (10 min).
Show on screen
Open the SONUB shell course and run pwd, ls, mkdir ai-course and cd ai-course in the practice terminal.
Type a wrong command on purpose and read the aloud together.
Show unit 11: the install commands for Claude Code and Codex and how --version confirms the install.
Student tasks
Finish shell unit 1 (meeting the terminal) and unit 2 (files and folders).
Open a terminal on your own computer and create the ai-course folder from the .
Done when
The student completes units 1 and 2 and can move into the ai-course folder without help.
If students get stuck
looks different: use or as the shell course explains, or keep practising in the SONUB terminal.
"" right after an install: close and reopen the terminal, then check the part of unit 11.
Questions for the class
What do pwd, ls and cd each tell you or change?
Why read a command before letting an AI agent run it?
Save every change with so that edits can be reviewed and undone, and use to share a project, open a and review it.
Git records of a project called , so you can see what changed and go back. That makes it the safety net for AI : commit before you let an work, then review its changes with git and keep or undo them.
GitHub is a website that keeps Git projects online. There you:
create a
your commits
open a pull request — a proposal to a set of changes that others can read, comment on and approve
SONUB's Git course teaches the step by step; this chapter adds the GitHub side.
Understand it the easy way
Think of it like this
Git works like save points in a video game. Each commit is a save point with a snapshot of the whole project, so if something goes wrong you can walk back to the last good one. GitHub is like a shelf that keeps a copy of your save points online, where friends can see them and suggest changes.
Example
Before asking an agent to “add a ”, commit. When the agent finishes, run git diff to see every changed line. If it looks good, commit again; if it broke the page, takes you back to the save point.
Common mistake
Letting an agent work for a long time without a single commit. Then there is no good save point to return to, and one big mistake is mixed up with all the good changes.
Each commit is a save point you can return to. GitHub keeps copies online, and a pull request asks to merge a side back into the one.A closer look
On GitHub, use issues to describe a task, to work on it without disturbing the main , and pull requests to review it. Keep repositories that contain private work private, and never commit a or a key; once it is pushed, assume it has leaked and replace the key. and can open pull requests too, but a person should read the diff before merging.
Explain it yourself
An AI agent changed five files and something broke. Which Git commands help you see the changes and go back?
Compare with an explanation
and git diff show what changed; git restore <file> undoes changes that are not committed yet; if they were committed, undoes that commit.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Why matters with AI (5 min) → commit, diff and undo on screen (10 min) → GitHub: create a repository, push, open and review a pull request (15 min) → students practise (20 min).
Show on screen
In a project folder run , and git commit -m "start", change a line, then run git diff to show exactly what changed.
Create a repository on GitHub, push the project and open a pull request from a branch.
Leave a review comment on one changed line, then approve it or request changes.
Student tasks
Take steps 1–5 of the Git course (or show that you know them), then make three commits in the ai-course folder.
Push the folder to a new GitHub repository and open one pull request that changes a single file.
Done when
The student's GitHub repository shows at least three commits and one pull request with a description.
If students get stuck
The push is rejected for : sign in with the (gh auth login) or a , and never type the into a chat.
A secret was committed by mistake: revoke and replace the key at once, then remove it from the code; deleting the file alone is not enough.
Questions for the class
Why commit before letting an AI agent change your project?
Write and run small and use , the building blocks of every in this course.
Python is the most common language for because it is short to write and has strong . SONUB's Python course teaches printing, , , , and in the with automatic checking. Finish it first, or make sure you know those ideas.
Models, however, work on many numbers at once, and for that we use . A NumPy array holds a grid of numbers, and one line such as a @ b multiplies whole . That is exactly what a does.
Understand it the easy way
Think of it like this
Plain Python handles numbers like a calculator: one at a time. NumPy handles a whole grid of numbers at once, like a spreadsheet that can multiply two tables in a single step. Models are made of huge grids of numbers, so this is the tool that makes them fast enough.
Example
Adding 1 to a million numbers with a Python loop means a million small steps. With a NumPy array a, writing a + 1 does all of them in one line, and a @ b multiplies two whole matrices.
Common mistake
Skipping the basic Python course and starting with NumPy. Without lists, loops and functions, the from NumPy are very hard to read.
A loop handles one number at a time. NumPy handles the whole grid at once — that is why models use it.A closer look
Three NumPy ideas carry the rest of the course:
— how many rows and columns
— an operation is stretched across the whole array automatically
— working on the whole array at once instead of writing a Python loop
The examples in this chapter run in your browser. On your own computer, install Python 3, make a with -m venv .venv, turn it on with source .venv/bin/activate (on , .venv\\activate), then install NumPy with install numpy.
Example code
Runs in your browser with Python and NumPy. Change the and run it again.
Explain it yourself
One array has the shape (4, 3) and another (3, 2). What is the shape of their product, and why?
Compare with an explanation
(4, 2): needs the inner sizes (3 and 3) to match, and the result keeps the outer sizes, 4 and 2.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Check the Python basics (10 min) → NumPy arrays, shape and @ on screen (10 min) → students run and change the example (20 min) → explain together (10 min).
Show on screen
Run the example and point at the shape, the broadcast result and the matrix product.
Change the scores in the softmax line and show that the still add up to 1.
Write the same addition as a Python loop and as one NumPy line, and compare.
Student tasks
Finish the SONUB Python course up to functions, or show the teacher that you can write a small function.
Change the example: make a 3×3 array, multiply it by a 3×1 array and predict the shape before you run it.
Done when
The student predicts the shape of a matrix product correctly and explains what softmax returns.
If students get stuck
A about shapes: print the .shape of both arrays; for a @ b the inner sizes must match.
" numpy" on your own computer: activate the virtual environment and run pip install numpy.
Questions for the class
Why use NumPy instead of a Python loop?
What do the numbers returned by softmax always add up to?
is widely used for because such as and provide numerical and machine-learning tools. SONUB runs Python in the browser using . Loading the and packages takes time. Printing a greeting checks that runs; it does not train an AI .
Understand it the easy way
Think of it like this
Running code is like doing a science experiment: you predict what will happen, run it, look at the result and change one thing at a time. The message that appears is the result of the experiment, not a sign that you did something wrong.
Example
Before you press Run, guess what (2 + 3 * 4) will show. Then run it and compare. If you guessed 20, change it to (2 + 3) * 4 and run again to see why the answer is 14 the first time.
Common mistake
Changing many lines at once when there is an error. Change one thing, run again, and read the last line of the first — it usually names the problem.
A closer look
The example below applies a rule written by a person. Change the score or and predict the output before running it. A function uses return to give a value back; print only displays it. Test boundary cases such as a score exactly equal to the threshold. This has no learning step.
Example code
Runs in your browser with Python and NumPy. Change the code and run it again.
Explain it yourself
A programmer changes an if-condition. Did the learn from ?
Compare with an explanation
No. Editing a rule is programming. Learning requires a process that derives model behavior from data.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Run the example (10 min) → change one condition and predict the output (10 min) → students write a small function (20 min) → self-check (10 min).
Show on screen
Run the chapter's example code and change the question so the else runs.
Point out that changing an if-condition is programming, not learning from data.
Student tasks
Write a function that answers three different questions with if//else and test it with each.
Done when
The student predicts which branch runs before running the code.
If students get stuck
: line up the lines inside if and else with four spaces.
Questions for the class
What is the difference between a program a person changes and a model that learns?
Build a one-page homepage with an by describing it, reviewing each change and keeping the project in .
means building mainly by describing what you want in plain words and letting an AI write the . You steer, test and decide.
Start small: a folder, a Git and a short brief. The brief says:
who the site is for
the sections
the style
the rules — plain and , works on a phone, no outside
Ask the for the first , open in a , and then improve it one change at a time: "make the smaller", "add a contact section", "fix the on a phone".
Understand it the easy way
Think of it like this
Vibe coding is like working with a builder while you are the architect. You describe the house you want in everyday words, the builder (the AI) puts it up, and you walk through it, point at what is wrong and ask for changes. You still decide what gets built and check that it is safe.
Example
“Make a one-page site for my book club: a title, a photo area, the next meeting date and a join button. Plain HTML and CSS, it must work on a phone.” Then open index.html, try it on a narrow window and ask: “Make the button bigger and put the date above the photo.”
Common mistake
Accepting every change without opening the page. Check it in the browser after each , and when a version works.
Describe → the AI builds → you check in the browser → you give feedback. Repeat in small rounds and save each working version.A closer look
You are still the developer. Read every change before you accept it, commit to Git after each working step so you can go back, and test on a real phone width. Never let the agent put passwords or in the page — a homepage is public, and everything in it can be read. When the page works, it is ready to publish: the next chapter puts it on the internet with .
Commands to type in your terminal
mkdir homepage && cd homepage
git init # save points from the first minute
claude # or: codex, agy
# then, inside the agent:
# "Make a one-page homepage in index.html for <who it is for>.
# Sections: <...>. Style: <...>. Plain HTML and CSS, works on a phone,
# no outside libraries. Show me the plan before you write."
git add index.html
git commit -m "first working homepage"
git restore index.html # throw away a change you do not like
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
List the four steps you repeat for each change in vibe coding.
Compare with an explanation
Describe one change → let the agent make it → check it in the browser (also at phone width) → commit to Git if it works, or go back if it does not. Any answer with ask, check and save is correct.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Write the brief together (10 min) → the agent builds version one (10 min) → three rounds of "look, ask, check, commit" (25 min) → show the pages (5 min).
Show on screen
In an empty homepage folder run , start the agent and paste a six-part for a one-page site.
Open index.html, resize the browser to phone width, and ask the agent to fix what breaks.
Commit, ask for a bad change, then return to the last commit with .
Student tasks
Build your own one-page homepage (a club, a hobby, a portfolio) with at least three sections.
Make at least three commits with clear messages, one per working change.
Done when
The page opens in a browser, reads well at phone width, has no secrets in it and has a Git history of small steps.
If students get stuck
The agent rewrites everything each time: ask for one small change and name the file and section.
The page looks broken on a phone: ask for a layout and check at 390 width.
Questions for the class
Why commit after every working step when an AI writes the code?
Why must a public homepage never contain an API key?
Publish to the web: deploy your homepage on Cloudflare
Goal
Publish a static homepage on with or from , update it, and know what is public after you publish.
Cloudflare Pages — , , and images — on 's worldwide . There is a free plan, and you get an address like your-project.pages.dev. There are two ways in:
— install and run wrangler login (Wrangler is Cloudflare's command-line tool, and npx runs it without installing). Create the project with npx wrangler pages project create my-homepage, then, from the folder with , run npx wrangler pages ./ --project-name=my-homepage.
— push the project to GitHub and connect the in the Cloudflare . After that, every push publishes a new automatically.
Choose one at the start. A Direct Upload project cannot be switched to Git integration later.
Understand it the easy way
Think of it like this
Deploying is like moving your shop from your living room to a busy street. On your laptop only you can visit the page. After deploying, the files sit on around the world and anyone with the address can open them.
Example
Your homepage folder has index.html, style.css and a photo. You upload the folder, get an address like your-project.pages.dev, and open it on your phone. Next time you change the page and deploy again, everyone sees the new version.
Common mistake
Uploading the whole project folder with a or keys inside. Everything you deploy to a static site can be downloaded by anyone, so check the folder first.
Deploying copies your files to servers around the world, so the same page opens for everyone at one address.A closer look
Everything you publish is public, so check that no keys, private notes or .env files are in the folder.
Each deployment gets its own , and the address shows the one, so you can test before sharing. A custom such as myname.com can be added later in the dashboard.
You can ask your to run the deploy , but read them first and never paste your Cloudflare into a chat.
Commands to type in your terminal
# Direct Upload — run in the folder that has index.html
npx wrangler login
npx wrangler pages project create my-homepage
npx wrangler pages deploy ./ --project-name=my-homepage
# -> https://my-homepage.pages.dev
# Choose at the start: a Direct Upload project cannot switch to Git integration later.
These run in a on your own computer or server, not on this page. Read each line before you run it.
Explain it yourself
Explain in three steps how your homepage goes from your computer to the internet.
Compare with an explanation
1. in to Cloudflare with Wrangler (or connect GitHub). 2. Upload the folder with index.html as a Pages project. 3. Cloudflare serves it from its network at a pages.dev address, and each new upload replaces the live version. Any answer with login, upload and the public address is correct.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What is and why static is simple (5 min) → deploy with Wrangler together (15 min) → change the page and deploy again (10 min) → connect GitHub as the second way (10 min).
Show on screen
Run npx wrangler login and npx wrangler pages deploy ./ --project-name=demo-homepage, then open the pages.dev address.
Change one line, deploy again, and show the new deployment and its preview address in the dashboard.
Show a that keeps .env out, and explain why nothing secret belongs in a static site.
Student tasks
Publish your vibe-coding homepage and share the pages.dev address.
Make one improvement, publish it again and confirm the change is live.
Done when
The homepage is reachable at a pages.dev address, an update has been published, and the student can explain what is public.
If students get stuck
"npx: ": install Node.js () first, then open a new terminal.
The page shows : deploy the folder that contains index.html, not its .
Questions for the class
What is the difference between Direct Upload and Git integration?
Why is a static site safe to host for free but unsafe for secrets?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 18 · Intermediate · Build and publish
Google Play: put your app on Android phones
Goal
Know the steps to publish an app on : developer account, , , and review — plus the testing rule for new personal accounts.
To publish on Google Play you need three things:
a developer account — a one-time registration fee and an identity check
an app built as an Android App Bundle (.aab), signed with your
a store listing — name, description, , an icon, a address, and answers about content and
If you build the app with an (for example with ), ask it to make a . Keep the file and its passwords out of and out of every chat.
Understand it the easy way
Think of it like this
Getting an app into a store is like getting your product onto a big shop's shelf. The shop checks three things: that the product is really yours (signing), that the box shows what is inside (screenshots, description, icon), and that you are honest about (privacy policy). Finally a reviewer looks at it.
Example
Ask your agent for a release build signed with your upload key, then go to Play Console, fill in the store listing, answer the data safety questions and send the build to first. On a new personal account, you can apply for only after a closed test with 12 testers for 14 days.
Common mistake
Losing the signing key or committing it to Git. Keep the key file and its passwords outside the project, with a in a safe place.
Signing, store listing, privacy and review: four gates every app passes before it reaches people's phones.A closer look
Releases go through tracks: internal testing, closed testing, open testing and production. New personal developer accounts must first run a closed test with at least 12 testers who stay opted in for 14 days in a row before they can apply for production access, so plan your testers early. Every release is reviewed by Google, and each update needs a higher . Rules and screens change, so follow the official Play Console help next to this chapter.
Commands to type in your terminal
# Flutter: build a signed Android App Bundle for Google Play
flutter build appbundle
# -> build/app/outputs/bundle/release/app-release.aab
# Keep the upload key and its passwords out of Git:
# android/key.properties
# *.jks
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Put these in order: production, closed test, release bundle, store listing.
Compare with an explanation
Release bundle → store listing → closed test (12 testers for 14 days for a new personal account) → production. The bundle and listing can be prepared in either order, but testing always comes before production.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
From app to store: the big picture (10 min) → build a release bundle together (15 min) → walk through the Play Console listing (15 min) → plan the 12-tester closed test (10 min).
Show on screen
Show a release build command (for Flutter: appbundle) and where the .aab file appears.
Walk through Play Console: create the app, the store listing, the data-safety form and the testing tracks.
Show where the upload key is stored and why it must never be committed or shared.
Student tasks
Write the store listing for your app: name, short and full description, and a list of screenshots to take.
Make a tester plan: 12 people, how you will invite them, and how you will keep them in the test for 14 days.
Done when
The student can list the steps from release bundle to production, explain the tracks and the closed-test rule, and has a listing draft and tester plan.
If students get stuck
No developer account or not old enough: practise with the listing and tester plan; a parent or the school can own the account.
The upload is rejected for the : raise the version code (Flutter: the number after + in ).
Questions for the class
Why do new personal accounts have to run a closed test before production?
What happens if you lose your upload key, and how do you protect it?
Know the steps to publish an iPhone app: , , , and — plus the most common reasons for rejection.
Publishing on the needs three things:
a with
a membership in the Apple Developer Program (a yearly fee)
a record for your app in App Store Connect — , name, , a address, and the privacy details of the it collects
You the app in Xcode (or with a such as ipa) and upload it. With automatic signing on, Xcode handles the signing and for you.
Understand it the easy way
Think of it like this
The App Store follows the same idea as , with Apple's own gates: a Mac with Xcode, a yearly developer membership, a bundle ID that names your app, and an app record in App Store Connect. Think of it as a second shop with its own checklist.
Example
Archive the app in Xcode (or with a build tool), upload it, and invite a few friends through TestFlight. When their feedback is fixed, fill in the privacy details and screenshots and submit the for review.
Common mistake
Submitting with placeholder screenshots, a broken login or a missing privacy policy. Reviewers reject apps that do not match their description, so test the exact build you send.
The same four gates as Google Play, with Apple's tools: Xcode signing, App Store Connect listing, privacy details and App Review.A closer look
Every uploaded build can go to TestFlight first, so testers install it before the public does. When you submit for release, Apple's App Review checks the app against its guidelines. Common rejections:
The app crashes or has placeholder content.
The privacy details are missing.
There is a login but no test account for the reviewer.
There is third-party login without an equivalent privacy-friendly option such as .
The app is only a website wrapped in an app, with little to do (the minimum-functionality rule, guideline 4.2).
Read the rejection message, fix exactly that and resubmit.
Commands to type in your terminal
# Flutter on a Mac with Xcode: build the iOS archive for App Store Connect
flutter build ipa
# -> build/ios/archive/Runner.xcarchive (open it in Xcode)
# -> Xcode: Distribute App -> App Store Connect -> TestFlight first
# A website only wrapped in an app can be rejected (App Review Guidelines 4.2 — minimum functionality)
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Your app was rejected because "the app crashed on launch". What do you do?
Compare with an explanation
Here is the order:
it on a real iPhone or in TestFlight with the same version.
Fix the crash and raise the .
Upload a new build.
Reply in App Store Connect saying what was fixed.
Fixing, re-uploading and replying are the key steps.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Apple's path: account → build → TestFlight → review (10 min) → archive and upload together (15 min) → App Store Connect listing (15 min) → rejection reasons and how to answer (10 min).
Show on screen
In Xcode choose Product → Archive, then Distribute App → App Store Connect.
In App Store Connect show the TestFlight tab, add an internal tester and install the build on a phone.
Read a real-looking rejection message together and write the fix and the reply.
Student tasks
Fill in a listing draft: name, subtitle, description, keywords, privacy policy address and a demo account for the reviewer.
Check your app against the five common rejection reasons and note what to fix.
Done when
The student can explain archive, upload, TestFlight and review in order, and their checklist covers the common rejection reasons.
If students get stuck
No Mac or no membership: practise the listing and the checklist, and test the app on or the web.
Upload fails with a signing error: turn on automatic signing in Xcode and choose your team.
Questions for the class
Why test with TestFlight before submitting for review?
Why does Apple ask for a demo account when your app has a login?
Agents and sub-agents: how an AI works step by step
Goal
Explain the loop (observe, think, act, repeat) and the four parts of an agent. Explain why is called a , a , an or an agent depending on the . Also explain what tools and an agent has, and when a hands work to .
An agent is an system that, given a goal, judges for itself, acts with tools, looks at the result and decides the next action. A gives one answer to one question and stops. An agent repeats this loop by itself until the task is done or it needs you.
Observe — it reads file contents, search results and to see where things stand.
Think — the decides what to do next.
Act — it uses a tool (edits a file, runs a , calls an , drives a ).
Repeat — it looks at the result and goes again until the goal is reached.
An agent is made of four parts: a language model () as the brain that thinks, tools that reach out into the world (today often connected with ), what it has done so far, and a goal with an end condition that tells it when the job is finished. Its power comes from its tools, and its limits come from its permissions — what it may read, change and run without asking. Claude Code, and the all work in this loop. They differ in , settings and commands, not in the basic loop.
Agent and mean different things.
Agent — a noun. Something that finishes the whole job completely on its own.
Agentic — an adjective. It describes a tool that thinks and decides with AI as it works, but cannot bring the job to a complete end with AI alone. You can say agentic tool, agentic , agentic music generator and so on.
So is Claude Code a tool or an agent? There is no single answer. Depending on what you point at, how you use it and what kind of conversation you are in, all four names are right.
Tool — when you name the product. , which makes it, introduces it as "Claude Code is an tool". If you ask and approve one step at a time, it feels like a smart tool.
Harness — when you mean the itself. The official Claude Code glossary says "Claude Code is the harness; is the model inside it". The harness gives the model file access, execution, permission checks, memory loading and the loop that chains actions together.
Agentic system — when you talk about design. Anthropic groups every system that connects a language model with tools under this name. that follow a fixed order and agents where the model decides its own steps both belong here.
Agent — when you mean the harness and the model running together. Give it a big goal and automatic approval, and it works as an agent that finds files, fixes them and runs tests on its own. The harness that powers Claude Code was taken out as the (formerly the Claude Code SDK), and the same harness builds agents that do not write code.
Understand it the easy way
Think of it like this
An agent is like a helpful intern working through a task: it reads the goal, decides the next step, uses a tool, looks at the result and decides again. Permissions are the house — what the intern may open, change or run without asking you first.
Example
“Find why the test fails and fix it.” The agent reads the test file, runs the test, sees the error, opens the code, makes a change and runs the test again. Each step is one of the loop. A is like sending a second intern to search the docs while the first keeps working.
Common mistake
Giving every permission on the first day. Start by letting the agent read and propose, approve commands one by one, and widen permissions only for jobs you understand.
Goal → plan the next step → use a tool → look at the result → again. You decide, at the gate, what the agent may do.A closer look
In technical terms, a tool is something the model calls — reading a file (Read), running a command (Bash), editing a file (Edit). A harness works the other way round: it calls the model. When the model asks "read this file", the harness runs it and hands back the result. So, strictly speaking, the Claude Code program is not a tool but a harness. Do not mix this up with the everyday phrase "AI tool".
A sub-agent is a helper the main agent starts for one part of the job. It has its own fresh . So it can read many files or search widely and report back only the conclusion, which keeps the main conversation short. Sub-agents can also run on independent parts.
Where they live — in Claude Code they are files with a name, a description, allowed tools and instructions, in (for the project) or ~/.claude/agents/ (for you).
How to use them — give a sub-agent a narrow job and only the tools it needs. Its report is still a draft you check.
Explain it yourself
Your project has 300 files and you want to know where the login code is. Why is a sub-agent a good idea?
Compare with an explanation
Reading many files fills the context window. A sub-agent can do the search in its own fresh context and return only "the login code is in these three files", so the main conversation stays short and focused. A sub-agent is also safe because it cannot change anything.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Act out the agent loop with a student as the "agent" (10 min) → watch a real agent's (10 min) → write a sub-agent file (20 min) → discuss when not to use one (10 min).
Show on screen
Give a a small task and point at each step: the plan, the tool call, the result and the next decision.
Ask the agent to search the whole project for one thing and show it handing the search to a read-only sub-agent.
Open a sub-agent file in .claude/agents/ and read its name, description, tools and instructions.
Student tasks
Draw the agent loop for a task of your own (for example "fix the broken link on my homepage") with every tool it would use.
Write a read-only reviewer sub-agent: a description of when to use it, tools limited to reading, and a three-line checklist.
Done when
The student can explain the loop, the role of tools and permissions, and why a sub-agent has its own context, and has a working sub-agent file.
If students get stuck
The sub-agent is never used: make the description say exactly when to use it, in the words of the request.
The agent does too much at once: ask for a plan first and approve one step at a time.
Questions for the class
What is the difference between a chatbot answer and an agent loop?
Why give a sub-agent fewer tools than the main agent?
Product details checked on 2026-10-19. AI tools change quickly — compare with the official page.
Chapter 21 · Advanced · AI agents
Codex: OpenAI's coding agent
Goal
Give a clear task with the files, the expected behaviour and a way to check it, then review its changes before you keep them.
Codex is 's . It works in your (the Codex CLI), in code editors and in the app. It reads your project, edits files and runs to test its work.
It follows the instructions in an file at the root of the project, so you can state your rules once — for example which command runs the tests. Codex asks for approval before risky actions. You choose how much it may do on its own, from to editing the workspace.
Understand it the easy way
Think of it like this
Codex is a coding agent you can use in several places — the terminal, your editor or the ChatGPT app. Think of AGENTS.md as a note on the fridge for every new helper: the house rules and the commands to run, written once and read every time.
Example
Put “Run tests with test. Never edit files in .” in AGENTS.md. Then ask Codex: “Add to the and make the tests pass.” It reads the note, makes the change and runs npm test before telling you it is done.
Common mistake
Switching to full access to skip the questions. The questions are your chance to catch a wrong command before it runs.
A closer look
Good coding requests are specific: what to change, in which files, how it should behave afterwards, and how to check it (a test, a command, an example ). For a bigger task, ask for a plan first. When Codex is finished, read the , run the tests yourself, and only what you understand. runs a task without the interactive screen, which is handy in . The Codex CLI is the , and the is the model inside it. The next chapter, "Harness", looks at the harness more closely.
Explain it yourself
Rewrite "make my code better" into a request Codex can carry out and check.
Compare with an explanation
For example: "In word_count.py, make count_words ignore punctuation and capital letters. Keep the function name. Add a test where 'Hello, hello!' counts as one unique word. Run -m and show the result." It names the file, the behaviour and the check.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What a coding agent does (5 min) → a live task with a clear request (15 min) → students give Codex their own small task (20 min) → review the diffs together (10 min).
Show on screen
In the ai-course folder, write an AGENTS.md with one rule, for example "Run python -m pytest after every change."
Ask Codex for a small script with a test, approve its steps, and show the test running.
Open diff and walk through every changed line before committing.
Student tasks
Give Codex a task that names the file, the behaviour and the check — for example a function that counts the words in a text, with a test.
Review the diff, run the test yourself, then commit with a message that describes the change.
Done when
The student's commit contains working code and a test, and the student can explain every changed line.
If students get stuck
Codex changes more than you asked: stop it, undo with , and repeat the request naming the exact files.
Sign-in or plan problems: sign in with your ChatGPT account; if Codex is not included in your plan, follow the demonstration and practise reviewing the teacher's diff.
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 22 · Advanced · AI agents
Harness: every prompt uses the harness
Goal
Explain why even a short uses a , through , and .
Everything about the harness — the three perspectives (Codex, Claude Code, LangChain) with their original sources, the loop figure, the path a single "hello" takes, built-in and project harnesses and — is on the Harness page. Open it with the links below, read it together, then finish the with this chapter's self-explanation.
The explanations for this chapter live on that page only. Open it together in class and mark your progress here with the button below.
Explain it yourself
Does a single greeting to Codex use a harness? Explain using the diagram and one source.
Compare with an explanation
Yes. The greeting triggers the agent loop supplied by the Codex harness. can return an answer immediately; are optional. The greeting is input, while the harness is the system processing it.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Read the three sources → follow the diagram → compare a direct answer with use → explain the summary in your own words.
Show on screen
In Codex, send a short greeting. Follow user input, inference and the answer on the diagram.
In Claude Code, ask it to explain a file. Identify the model's reasoning and the file access supplied by the harness.
Open the LangChain source and locate system prompts, tools, infrastructure, and .
Student tasks
Describe how a simple greeting and a request to read a file each use the harness.
Classify a model, , tool and check using the three sources.
Done when
Explain that short prompts also use the harness, distinguish model, prompt and execution system, and support your explanation with a source.
If students get stuck
If the names are confusing, separate the model that generates a response from the system that runs the loop and tools.
Without a product account, use the diagram, official texts and a teacher's demonstration.
Questions for the class
Why does a direct answer without a tool call still use the harness?
Why can changing tool affect a model trained with that harness?
Product details checked on 2026-10-21. AI tools change quickly — compare with the official page.
Chapter 23 · Advanced · AI agents
Claude Code 1: set up a project and give lasting instructions
Goal
Start in a project, give it lasting instructions in , and control what it may do with .
Claude Code is 's . Depending on the it is rightly called a tool, a , an or an (the agents and chapter explains which name fits when). It runs in the and also in editors, the and the web. In a project folder, type to start. It reads the code, answers questions about it, edits files and runs .
A file named CLAUDE.md at the root of the project is read at the start of every . Put these there:
the project's purpose
the commands that build and test it
your
The drafts a CLAUDE.md for you by reading the project.
Understand it the easy way
Think of it like this
Claude Code reads CLAUDE.md at the start of every session, like a new team member reading the project handbook on their first morning. A short, clear handbook — what the project is, how to build and test it, and your rules — saves you from repeating yourself.
Example
Run /init in your project. Claude Code looks around and writes a first CLAUDE.md. Read it, delete anything wrong and add two lines of your own, such as “Use Korean for messages” and “Run the tests before saying a task is done”.
Common mistake
Writing a CLAUDE.md as long as a book. Long instructions get skimmed. Keep the rules that matter every day and move the rest into (see the chapter) or separate documents.
A closer look
Claude Code asks before it edits files or runs commands, and you decide whether to allow an action once, for the session, or always. live in , and lets Claude Code read and propose a plan without changing anything. Start strict, loosen only what you trust, and never allow a command you do not understand.
Explain it yourself
Write three lines you would put in CLAUDE.md for a small homework project.
Compare with an explanation
For example: "Purpose: homework exercises for a Python . Test: run python -m after every change. Rule: keep functions short and explain each one in a comment." Any answer with a purpose, a test command and a rule is correct.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Install check and first start (10 min) → CLAUDE.md with /init (10 min) → permissions and plan mode (10 min) → students set up their own project (20 min).
Show on screen
Start claude in the ai-course folder and ask "What is in this project?"
Run /init, then edit the generated CLAUDE.md to add one rule about tests.
Press to switch to plan mode, ask for a change, and show that nothing is edited until you approve the plan.
Student tasks
Start Claude Code in your ai-course folder and write a CLAUDE.md with the purpose, the test command and two rules.
Ask Claude Code for a change in plan mode and read its plan without approving it.
Done when
The student's project has a CLAUDE.md with a test command and rules, and the student can explain what plan mode does.
If students get stuck
"claude: ": repeat the install check in unit 11 and reopen the terminal.
It asks for permission too often: allow "always" only for safe commands such as running the tests, never for deleting files.
Questions for the class
What belongs in CLAUDE.md, and why is it read in every session?
Run a whole task loop with : describe the goal, review the plan, let it change and test the , then review and keep or undo the result.
Working well with a follows a loop. Explain the goal and how to check it. Read the plan and correct it before any file changes. Let the edit and run the tests. Read the yourself. Keep the change with a , or undo it. Many small loops beat one giant request, because each loop is easy to check.
Understand it the easy way
Think of it like this
Working with a coding agent is like cooking with a recipe you taste as you go: decide the dish, read the plan, let it cook one step, taste (test), and only then go on. Small rounds are easy to check and easy to undo.
Example
Round 1: “Plan how to add a search box. Do not edit files yet.” Fix the plan. Round 2: “Do step 1 and run the tests.” Read the diff and commit. Round 3: the next step. Three short rounds beat one giant request.
Common mistake
Saying “looks good” without reading the diff. The diff shows exactly what changed — including files you did not expect to be touched.
Plan → edit → test → review → commit, in small rounds. Each round is easy to check and easy to undo.A closer look
Give the agent ways to check itself: tests, a that must succeed, or an example of the correct output. If a heads in the wrong direction, press to stop, say what was wrong, or undo with and make a fresh request; long sessions collect confusing , and starts clean. For work you repeat, save the steps as a (see the chapter). For a long job with a you can check, use and the agent keeps working until it is met (see the Goal and chapter).
Explain it yourself
Put these in order: read the diff, describe the goal and the check, commit, approve the plan, run the tests.
Compare with an explanation
Describe the goal and the check → approve the plan → (the agent changes the code and) run the tests → read the diff → commit.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
The five-step loop on the board (5 min) → a live loop on a small feature (15 min) → students run two loops on their project (20 min) → share one thing the agent got wrong (10 min).
Show on screen
Ask: "Add a function that returns the most common word in a text, with tests. Show me the plan first." Correct one detail of the plan.
Let it edit and run the tests; when a test fails, show how it reads the error and fixes the code.
Review git diff and commit; then make a bad change on purpose and undo it with .
Student tasks
Run one complete loop on your project: a goal with a check, the plan, the change, the tests, the diff, the commit.
Run a second loop that improves something from the first, and write one sentence about what you corrected in the plan.
Done when
The student's Git history shows two commits made through the loop, each with passing tests.
If students get stuck
The agent says the tests pass but they fail: run the test command yourself and trust the output, not the summary.
The conversation gets confused: commit or undo what you have, use /clear, and start again with a short, precise request.
Questions for the class
Why are several small loops better than one big request?
What do you do when the agent goes in the wrong direction?
Antigravity CLI (agy): Google's agent in your terminal
Goal
Start Google's with and give it a task. Compare it with and , and use more than one to check each other.
The Antigravity CLI is Google's for the . Run the from its official page, then start it with the agy. Google also offers a migration guide for users of the older .
It uses Google's and works like the other agents:
You run it in a project folder.
You describe the task.
You approve its plans and commands, and it reads and edits files.
The first time you run it, it opens the so you can sign in with your Google account. It can also send parts of a task to several helper agents at once.
Understand it the easy way
Think of it like this
Antigravity CLI is another coding agent, Google's, that lives in the terminal. Once you know one agent, the others feel familiar — like driving a different car: the pedals are in the same places, only some buttons and settings move.
Example
Start agy in your project folder, sign in with your Google account the first time, and give it the same kind of task you gave Codex or Claude Code. Compare the plans the agents make for the same task.
Common mistake
Following an old Gemini CLI guide word for word. Tools and commands change, so check the official page for the current install and sign-in steps.
A closer look
Knowing three agents is useful because each model has different strengths and blind spots. A good habit is cross-checking: ask one agent to make a change and another to review it, or ask several to analyse the same problem separately and compare — where they disagree, open the files yourself and decide. Keep the same project rules for all of them in AGENTS.md, which many agents read, so they follow the same instructions.
Explain it yourself
Two agents disagree about the cause of a . How do you decide who is right?
Compare with an explanation
Look at the evidence each gives — the file and line, the — and check it yourself: run the , read the line, write a small test. The answer that matches the real behaviour wins, even if only one agent said it.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Three agents side by side: Claude Code, Codex, agy (10 min) → install and sign in to agy (10 min) → the same small task in two agents (20 min) → compare and decide (10 min).
Show on screen
Run agy in the practice project and ask it to explain the project structure.
Give the same bug to agy and to Claude Code or Codex, and compare the two plans.
Ask one agent to review the other agent's change and show how you decide between them.
Student tasks
Write an AGENTS.md with your project rules and check that two agents follow it.
Give one task to two agents and write a short table: what each did, what was better, what was wrong.
Done when
The student has run agy on a project, compared two agents on the same task and can explain why cross-checking catches mistakes.
If students get stuck
agy does not start or cannot sign in: check the official install page and sign in with a Google account in the browser.
The agents give different answers: that is the point — open the files they point to and let the evidence decide, not the majority.
Questions for the class
Why can two different agents find more mistakes than one?
Why put the rules in AGENTS.md when you use several agents?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 26 · Advanced · AI agents
Agent Skills: teach an AI agent a repeatable task
Goal
Read and write a file so that an does a repeatable task the same way every time, and test when it is used.
Everything about agent — what they are, how they work, the SKILL.md , making your first skill, tips and installing the SONUB skills — is on the page. Open it with the links below, read it together, then finish the with this chapter’s self-check.
The explanations for this chapter live on that page only. Open it together in class and mark your progress here with the button below.
Explain it yourself
Write a description for a skill that meeting notes into an action list.
Compare with an explanation
For example: "Turns meeting notes into a numbered action list with an owner and a due date. Use when the user asks for action items or a to-do list from a meeting. Not for writing full minutes." It says what it does, when to use it and what it is not for.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What a skill is and where it lives (10 min) → read a real skill together (10 min) → students write a small skill (20 min) → test when it triggers (10 min).
Show on screen
Open the example SKILL.md and point at the name, the description and the steps.
Put the skill in weekly-report/ and ask "Write my weekly report"; then ask something unrelated and show that the skill is not used.
Make the description vague and show how the skill becomes unreliable.
Student tasks
Write a SKILL.md for a task you repeat (a summary, a checklist, a report) with a clear description and three to five steps.
Test it with two requests that should use it and one that should not, and note the results.
Done when
The skill has a name, a description that says when to use it, numbered steps and a check, and it is used correctly in the tests.
If students get stuck
The skill is never used: put the words people actually say into the description.
It is used for the wrong requests: add what it is not for to the description.
Questions for the class
Why does the agent the name and the description at first?
Why read a skill before installing it from the internet?
Product details checked on 2026-10-16. AI tools change quickly — compare with the official page.
Chapter 27 · Advanced · AI agents
MCP: build a server and a client that connect AI to your tools
Goal
Explain what the , and do, read a small written without an , test it with a shell-script client, connect it to , and know where that setting is saved.
is an for connecting apps to outside and . Before MCP, every AI app needed its own custom connection for every tool. With MCP you build a server once, and any app that speaks MCP — Claude Code, , or your own — can use it.
MCP was created by , the company that makes . Official documentation: https://claude.com/docs/connectors/building/mcp
Three roles:
Host: the AI app the person uses (Claude Code, an editor, a chat app).
Client: the inside the host. One client talks to one server.
Server: a small program that offers abilities to the AI.
A server can offer three kinds of things:
Tools: functions the AI may call, such as "search the notes" or "add a row".
: data the app can read, such as a file or a record, each at an address ().
: ready-made message a user can pick.
The messages are 2.0 — small objects such as ("what can you do?") and ("do this, with these arguments"). They travel over one of two standard : (the client starts the server as a program on the same computer and they talk through standard input and output) or (the server runs at a web address, so many users can reach it).
Understand it the easy way
Think of it like this
MCP is like the USB of AI apps. Before USB, every printer and keyboard needed its own plug; now any device with a USB plug fits any computer. An MCP server is the device, the AI app is the computer, and the shared plug means you build a server once and every MCP app can use it.
Example
The strange-add server offers one tool: it adds two numbers plus a random number from 0 to 100.
You connect it to Claude Code with one .
You say "Use strange-add to add 2 and 3": the AI reads the tool description, asks for your approval, and the client calls strange-add on the server. The answer is not 5 — proof that the tool really ran.
Common mistake
Installing any MCP server you find. A server runs on your computer with your . Read it or choose a trusted one, and give it only the folder or key it needs.
One plug shape: the AI app connects to many tools through MCP servers, and a person approves before a tool runs.A closer look
The server (mcp-server.py) uses only the , so you can see the itself. It reads one JSON-RPC message per line from standard input and writes one reply per line to standard output:
: the client says hello with a . The server answers with the same , says that it has tools and gives its name.
tools/list: the server returns its one tool, strange-add, with a description and an input (a and b are numbers).
tools/call: the server runs strange-add and returns the result as text.
A message without an id is a (such as notifications/initialized), so the server sends no reply. Any other request (such as ) gets an empty result.
strange-add adds a random number from 0 to 100 to a + b. The model cannot work that out by itself, so an answer that is not 5 for 2 + 3 proves that the tool really ran. stdout carries the protocol messages only — one stray () breaks the conversation, so write to stderr. print(..., =True) sends each reply at once.
The client (mcp-client.sh) is a that plays the host's part without any AI. It starts the server, sends the whole (initialize, the initialized notification, tools/list, tools/call, ping) and checks each reply, printing PASS or FAIL. 0 means that everything passed. Test a server like this before you connect it to an . In a real client the model joins the loop:
send the user's question and the tool list to the model;
when the model asks for a tool, the client calls it on the server with tools/call;
send the result back, and the model writes the final answer.
This hand-made server speaks the style that starts with initialize (protocol version 2025-06-18), which clients such as Claude Code still accept. The newest (2026-07-28) carries the version in every request instead of an initialize . For real services, use the official SDKs (Python MCPServer, ), which follow the specification for you.
Safety: a tool is code that runs with your permissions, and tool descriptions are untrusted unless the server is trusted. The specification asks hosts to get the user's consent before calling a tool. Install only servers you have read or trust, give a server the smallest access it needs, keep keys in rather than in code, and watch for — a web page or file that a tool reads may contain instructions aimed at the AI.
mcp-server.py
"""
mcp-server.py: the smallest MCP server.
One tool, plain Python (standard library only), no SDK.
Who is who
MCP server This program. It offers tools (functions the AI
may use).
Host The app the user talks to (Claude Code, Codex).
It runs one MCP client for each connected server.
MCP client The part of the host that talks to this server
with JSON-RPC messages (here over stdio: one JSON
message per line).
Model The LLM (Claude Opus, GPT, ...). It never talks to
the server directly. It only talks to the host.
Flow
1. Discover tools
The client asks for the tools (tools/list). The server replies
with each tool's name, description and input schema.
2. Offer tools
The host sends the user's message to the model, together
with the tool list.
3. Model decides
The model answers directly, or asks for a tool call
(tool name + arguments). It never runs the tool itself.
4. Call the tool
The client sends the request to the server (tools/call).
5. Run the tool
The server runs the function and returns the result.
6. Model continues
The host gives the result back to the model. The model may
call more tools (3-6 again) or write the final answer.
Model Host (MCP client) MCP server
| | 1. tools/list ------> |
| | <------ tool list |
| <-- 2. message + tool list |
| 3. tool call --> | |
| | 4. tools/call ------> |
| | <------ 5. result |
| <-- 6. result | |
Rule for stdio servers: stdout carries protocol messages only.
Never print() anything else there. Write logs to stderr.
"""
import json
import random
import sys
SERVER_INFO = {"name": "strange-add-mcp", "version": "1.0.0"}
# The tool. The model reads the description to decide when to use it.
STRANGE_ADD = {
"name": "strange-add",
"description": "Add two numbers with a strange number.",
"inputSchema": {
"type": "object",
"properties": {
"a": {"type": "number"},
"b": {"type": "number"},
},
"required": ["a", "b"],
},
}
def strange_add(a, b):
"""Add a + b and a random number from 0 to 100 (always >= a + b).
The model cannot guess the answer, so a right answer proves
that the tool was really called.
"""
return a + b + random.randint(0, 100)
def handle(method, params):
"""Return the result for one request. Others (like ping) get {}."""
if method == "initialize":
# Use the client's protocol version and say "I have tools".
return {
"protocolVersion": params["protocolVersion"],
"capabilities": {"tools": {}},
"serverInfo": SERVER_INFO,
}
if method == "tools/list":
return {"tools": [STRANGE_ADD]}
if method == "tools/call":
args = params["arguments"]
total = strange_add(args["a"], args["b"])
return {"content": [{"type": "text", "text": str(total)}]}
return {}
def main():
# One JSON-RPC message per line comes in, one reply per line goes out.
for line in sys.stdin:
request = json.loads(line)
# No id means a notification: send no reply.
if "id" not in request:
continue
result = handle(request["method"], request.get("params", {}))
reply = {"jsonrpc": "2.0", "id": request["id"], "result": result}
# flush=True sends the reply at once.
print(json.dumps(reply), flush=True)
if __name__ == "__main__":
main()
mcp-client.sh
#!/bin/sh
# mcp-client.sh: the simplest MCP client, a shell script.
# It starts mcp-server.py, talks to it over stdio (one JSON-RPC
# message per line) and checks every reply.
# Exit code 0 means every check passed.
SERVER="python3 $(dirname "$0")/mcp-server.py"
# 1. Send the whole session at once and keep the replies.
# id 1 initialize agree on a version
# (no id) notifications/initialized "ready" (no reply)
# id 2 tools/list which tools are there?
# id 3 tools/call run strange-add(2, 3)
# id 4 ping is the server alive?
replies=$(
$SERVER <<'EOF'
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "shell-mcp-client", "version": "1.0.0"}}}
{"jsonrpc": "2.0", "method": "notifications/initialized"}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "strange-add", "arguments": {"a": 2, "b": 3}}}
{"jsonrpc": "2.0", "id": 4, "method": "ping"}
EOF
)
echo "--- Server replies ---"
echo "$replies"
echo "--- Checks ---"
failed=0
# 2. check <label> <reply id> <text the reply must contain>
check() {
reply=$(echo "$replies" | grep -F "\"id\": $2,")
if echo "$reply" | grep -qF "$3"; then
echo "PASS $1"
else
echo "FAIL $1 (expected: $3)"
failed=1
fi
}
check "initialize: protocol version" 1 '"protocolVersion": "2025-06-18"'
check "initialize: server info" 1 '"serverInfo": {'
check "initialize: has tools" 1 '"capabilities": {"tools": {}}'
check "tools/list: strange-add" 2 '"name": "strange-add"'
check "ping: empty result" 4 '"result": {}'
# 3. strange-add adds a random 0 to 100,
# so the answer only has to be >= 2 + 3.
total=$(echo "$replies" | grep -F '"id": 3,' |
sed 's/.*"text": "\([0-9]*\)".*/\1/')
if [ "$total" -ge 5 ] 2>/dev/null; then
echo "PASS tools/call: strange-add(2, 3) >= 5 (got $total)"
else
echo "FAIL tools/call: strange-add(2, 3) >= 5 (got $total)"
failed=1
fi
exit $failed
Commands to type in your terminal
# put the two files above into one folder
mkdir -p ~/tmp/mcp && cd ~/tmp/mcp
# mcp-server.py mcp-client.sh
# 1) test the server without any AI
sh mcp-client.sh # -> 6 x PASS, exit code 0
# 2) connect it to Claude Code (no --scope: the "local" scope)
claude mcp add strange-add -- python3 ~/tmp/mcp/mcp-server.py
claude mcp list # strange-add: ... - Connected
claude mcp get strange-add # Scope: Local config
# 3) where it was saved: NOT in this folder (no new file here)
# ~/.claude.json -> projects -> "<this folder>" -> mcpServers
jq '.projects["'"$PWD"'"].mcpServers' ~/.claude.json
# 4) use it: start Claude Code in THIS folder
claude # "Use strange-add to add 2 and 3"
# -> not 5 (e.g. 61): the tool ran
claude mcp remove strange-add -s local
These run in a on your own computer or server, not on this page. Read each line before you run it.
Explain it yourself
Name the three roles in MCP and the three kinds of things a server can offer, with one example each.
Compare with an explanation
Roles: the host is the AI app (Claude Code), the client is the connector inside it, and the server is the program that offers abilities (a notes server). A server offers tools the model can call (add a note), resources the app can read (notes://shopping) and prompts a user can pick (a "summarise my notes" template).
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What MCP is and its three roles (10 min) → read mcp-server.py together, message by message (15 min) → test it with mcp-client.sh (10 min) → connect it to Claude Code and find where the setting is saved (15 min).
Show on screen
Open mcp-server.py and follow one message through it: a tools/call line comes in on stdin, handle() picks the , strange_add() runs, and one JSON line goes out on stdout. Point at the tool description that the model will read.
Run mcp-client.sh and read the replies line by line: initialize, tools/list, tools/call and ping each get one reply, the notification gets none, and all six checks pass. Then add print("hello") to the server, run the client again and show the failure.
Run claude mcp add strange-add -- ~/mcp/mcp-server.py and check it with claude mcp list. Show that no new file appeared in the folder, then show the entry in ~/.claude.json under projects → this folder → mcpServers. Start Claude Code in that folder, ask "Use strange-add to add 2 and 3", and show the approval prompt and an answer that is not 5.
Student tasks
Add a second tool to mcp-server.py — for example word-count, which returns the number of words in a text. Add its definition to tools/list, and in tools/call check the tool name to run the right function.
Add checks for the new tool to mcp-client.sh and run it until every check passes. Then connect the server to Claude Code and find its entry in ~/.claude.json. Without a Claude Code account, mcp-client.sh alone is enough — it plays the host's part.
Done when
The student's client prints PASS for every check, including the new tool, and the student can say where claude mcp add saved the setting and why the server does not appear in another folder.
If students get stuck
The client fails, or Claude Code says that the server failed to connect: a print() or an went to stdout. Keep stdout for JSON replies only, write logs to stderr, and run sh mcp-client.sh again.
The server is missing in Claude Code: you started Claude Code in a different folder. The local scope belongs to the folder where you ran claude mcp add. Check ~/.claude.json, start Claude Code in that folder, or add the server again with --scope user.
Questions for the class
Why does the description of a tool matter as much as its code?
Why should you read an MCP server before you install it, even if it is popular?
Product details checked on 2026-10-20. AI tools change quickly — compare with the official page.
Chapter 28 · Advanced · AI agents
Claude Cowork: hand over multi-step work
Goal
Use an for tasks across files and apps, set clear limits, follow its progress and check the finished work.
uses the same agent technology as but needs no . In the you describe a task and give it access to the folder it needs. For example, say "sort these 40 receipts into a spreadsheet by month", and it plans the steps, works through them and shows its progress. It is made for office and study work:
organising files
drafting documents from notes
collecting information into a table
Cowork is available on paid plans.
Understand it the easy way
Think of it like this
Cowork is like handing a folder to a capable assistant: “Sort these receipts by month into a spreadsheet.” You explain the job, give access to the folders it needs, and watch the progress list as it works through the steps.
Example
Give Cowork a folder of meeting notes and ask: “Make a one-page summary of decisions and a table of who does what by when.” Check the table against two of the notes before you send it to anyone.
Common mistake
Giving access to your whole drive for a small task. Share only the folder the job needs.
A closer look
The more an agent can do, the more your instructions matter:
Give it only the folders it needs.
Say what it must not do (delete, send, buy).
Ask it to stop and ask when it is unsure.
Check the result against the originals.
A useful habit from teams is cross-checking: give the same question to two or more tools, compare the answers, and decide from the evidence, not from the majority. SONUB's own developers work this way — one question goes to several AI , and every claim is then checked in the source files.
Explain it yourself
List four things a good task brief for an agent tool must contain.
Compare with an explanation
The goal, the input (which files or folder), the expected output, and the limits (what it must not do, and when to stop and ask).
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
What an agent tool is (5 min) → a live task with limits (15 min) → students design a task brief (20 min) → cross-check two AI answers (10 min).
Show on screen
Give Cowork a sample folder of notes and ask for a one-page summary document; point out where it asks for .
Show a task brief with limits: which folder, what output, what it must not do, and when to ask.
Ask the same factual question to two AI tools, compare the answers and check the source.
Student tasks
Write a task brief for a real chore: the goal, the input folder, the expected output and three things it must not do.
If you have access, run it in Cowork and compare three items of the output with the originals; if not, ask two AI tools the same question and compare.
Done when
The brief names the goal, the input, the output and the limits, and the student reports at least one item they checked.
If students get stuck
No paid plan: write the task brief and do the cross-checking task with free tools — the planning is the same.
The agent touched the wrong files: give it a copy of the folder instead of the original, and narrow its access.
Questions for the class
Why should an agent work on a copy of your files at first?
When AI tools disagree, why decide from the evidence instead of the majority?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 29 · Advanced · Agents that keep working
Goal and Ralph Loop: let an agent keep going until it is really done
Goal
Set a goal with a clear , run an in a loop until the goal is met, and stop it safely with checks, limits and budgets.
Normally an agent stops once it decides that one request is done. A goal one request into a long task: you state the objective and the finish line, and the agent keeps working, checking its progress after each step.
and both have the :
/goal with a finish line sets the goal and starts working right away.
/goal alone shows the goal and its status.
/goal clear removes it. In Codex, /goal pause and resume pause and continue it.
In Claude Code, a separate small reads the conversation after every turn and gives a verdict: not yet met (keep working), met, or impossible (both clear the goal). It does not run or read files, so write a finish line that 's own output can prove, such as a test result. The status shows the time, turns and so far.
In Codex, a goal is active, paused, complete or budget-limited. It may be marked complete only when evidence such as passing tests supports it.
The is the same idea built from a simple trick: a (a small that runs automatically the moment it stops) catches the agent when it tries to finish and feeds the same back in. The agent sees its own earlier work in the files and history and improves it, round after round. It comes as a Claude Code and is another way to do the same job; Claude Code's /goal itself works as a Stop hook for that only.
Understand it the easy way
Think of it like this
A normal agent stops once it thinks one request is done, like a who stops at the first corner. A goal is like a race with a finish line and : the agent keeps running, checks its list at each checkpoint and only stops when the finish line — your done criteria — is really reached, or the budget runs out.
Example
“/goal All tests pass and the explains how to run the app.” The agent works, runs the tests, sees two failures, fixes them, checks the README and stops only when both conditions are met. A Ralph loop does something similar by giving the agent the same prompt again every time it tries to stop.
Common mistake
A goal without a clear finish line, like “make it better”. Write something that can be checked: a test that passes, a page that loads, a list that is complete.
The agent keeps going checkpoint by checkpoint until the done criteria are met — or you pause it, or the budget runs out.A closer look
A loop is only as good as its finish line. "Make it better" never ends; "all tests in tests/ pass and the page loads without errors" can be checked.
Always set a limit, or the loop can run all night and spend money for nothing:
a — with /goal in Claude Code, end the finish line with “or stop after 20 turns”
a the agent may say only when it is true
a
Claude Code's /goal does not change your : to let it run on its own, use it in ; otherwise Claude still asks before commands you have not allowed.
Start loops on a fresh Git , keep the project's in or , and check the result yourself. "Done" from an agent is a claim, not a proof.
Commands to type in your terminal
# Claude Code — keep working until a finish line you can check is met
/goal All tests in tests/ pass and the homepage loads without errors, or stop after 20 turns
/goal # show the condition, turns and tokens
/goal clear # remove it before it is met
claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"
# Codex — the same idea, plus pause and resume
/goal All tests in tests/ pass and the homepage loads without errors
/goal # show the goal and its status
/goal pause # also: /goal resume, /goal clear
# Claude Code plugin — Ralph Loop: the same prompt again and again, with limits
/ralph-loop "Fix the failing tests in tests/. Say DONE only when all pass." --completion-promise "DONE" --max-iterations 5
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Rewrite "make the homepage good" as a goal for a loop.
Compare with an explanation
For example: "The homepage passes the , has no , reads well at 390 width and every link works. Stop after at most 8 rounds." It has checkable conditions and a limit.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Why one reply is not enough for big tasks (5 min) → write a goal with a finish line (10 min) → run a short loop with a limit (20 min) → review what it did in Git (15 min).
Show on screen
In Codex type /goal with a measurable objective, then /goal to see the status, and pause it.
In Claude Code, set /goal with a measurable finish line ending in “or stop after 20 turns”, check the status (turns, tokens) with /goal, then remove it with /goal clear. Compare by running the same job as a Ralph Loop with a completion phrase and at most 5 rounds.
Show after the loop and check the work against the finish line.
Student tasks
Rewrite three vague requests ("improve my site", "fix ", "write tests") as goals with a checkable finish line.
Run one loop of at most 5 rounds on a practice branch and write what each round changed.
Done when
The goal has a checkable finish line and a limit, the loop stopped by itself, and the student verified the result.
If students get stuck
The loop never stops: stop it with /goal clear (or /cancel-ralph for the Ralph Loop), then add a maximum number of rounds and a finish line that can be tested.
Each round undoes the last one: the goal is unclear — write the finish line as a test or a checklist.
Questions for the class
Why does a loop need both a finish line and a limit?
Why should you still check the work when the agent says it is done?
Product details checked on 2026-10-26. AI tools change quickly — compare with the official page.
Chapter 30 · Advanced · Agents that keep working
VPS and tmux: keep an agent working 24 hours a day
Goal
Rent a small (), connect with , run an inside so it keeps working after you disconnect, and keep the server and your keys safe.
A VPS is a small computer you rent in a . It stays on when your laptop sleeps. You connect with ssh user@address using an instead of a password, install your tools (, , , the agent) and your project. But if you start an agent directly in the SSH , it stops when the connection drops. tmux solves that:
tmux new -s agent — opens a session. Start the agent inside it.
+b, then d — from the session. The agent keeps running.
-t agent — later, brings you back to the same screen.
tmux — lists the sessions.
Understand it the easy way
Think of it like this
A VPS is a small computer you rent in a data centre that never sleeps. tmux is like a room on that computer whose light stays on after you leave: you start the agent inside the room, close the door (detach), and come back later to find it still working.
Example
ssh into the server, run tmux new -s agent, start the agent, then press Ctrl+b and d to leave. Close your laptop. Tomorrow, ssh in again and run tmux attach -t agent to see what it did overnight.
Common mistake
Logging in with a password and leaving the server open to the internet. Use SSH keys, keep the system updated and never store keys in the project folder you share.
Your laptop can and disconnect. On the VPS, the tmux session keeps the agent working until you come back.A closer look
An agent running all night needs guard rails:
Give it a clear goal with a and a limit.
Run it on a , and let it so you can review the work in the morning.
Keep in , never in the , and set a spending limit with your provider.
Protect the server: SSH keys only, a , and regular updates.
Check on the session with tmux attach or by reading the , and stop it with or tmux kill-session -t agent.
Commands to type in your terminal
ssh user@address # log in with an SSH key, not a password
tmux new -s agent # open a session called "agent"
claude # start the agent with a goal and a limit
# press Ctrl+b, then d -> detach; the agent keeps working
exit # log out — the session stays on the server
ssh user@address
tmux ls # list sessions
tmux attach -t agent # back to the same screen
tmux kill-session -t agent # stop it for good
These run in a on your own computer or server, not on this page. Read each line before you run it.
Explain it yourself
Write the to start a tmux session called agent, leave it running and come back to it later.
Compare with an explanation
tmux new -s agent, start the , press Ctrl+b then d to detach; later, after logging in again, tmux attach -t agent. tmux ls shows the sessions if you forget the name.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Why a server: always on, always online (5 min) → SSH in with a key (10 min) → tmux new, detach, attach (15 min) → start a limited agent and check it later (20 min).
Show on screen
Connect with ssh, run tmux new -s agent, start a long command, press Ctrl+b d, out, log in again and tmux attach -t agent.
Inside tmux start an agent with a goal and a round limit on a practice branch.
Show where the API key lives (an environment variable) and the provider's spending-limit page.
Student tasks
Practise tmux on your own computer or a VPS: create a session, detach, list sessions, attach and it.
Write a night-run plan: the goal and finish line, the limit, the branch, how you will check it and how you will stop it.
Done when
The student can keep a program running after disconnecting with tmux and has a safe night-run plan with a limit and a review step.
If students get stuck
"no sessions" on attach: the session was ended or the server restarted — check with tmux ls and start a new one.
SSH asks for a password or is refused: add your to the server and connect with the user.
Questions for the class
Why does a program stop when SSH disconnects, and how does tmux prevent that?
What three limits should an agent running all night always have?
Build small functions such as mean and maximum, and explain what their outputs mean.
Start with an average, a maximum value, and a . max returns the largest value; returns its position. For single-label classification, that position can identify the highest-scoring . A score is not automatically a . Changing a decision threshold can change which examples are classified as positive.
Understand it the easy way
Think of it like this
A is like a small judge with a scorecard. It multiplies each input by how much it cares about it (a ), adds them up with a starting bonus (the bias) and then decides how strongly to . That last step is the — a dimmer switch that turns the total into an output, for example a value between 0 and 1 for sigmoid.
Example
Scores for three animals: cat 2.1, dog 3.4, rabbit 0.5. max gives 3.4, and argmax gives position 1 (counting from 0) — the dog. With a threshold of 3.0 the answer is “dog”; raise the threshold to 4.0 and nothing is chosen at all.
Common mistake
Reading any score between 0 and 1 as a trustworthy probability. A score can look like a percentage without being calibrated — check how often the is actually right at that score.
Inputs × weights, added together with a bias, then the activation function decides how strongly the neuron lights up.A closer look
A neuron can combine inputs as z = w·x + b and apply an activation function. Sigmoid maps a finite real number to a value between 0 and 1; it is one activation, not the definition of every neuron. Other use ReLU or . Implementing sigmoid shows a building block, not a trained network. The missions then introduce models fitted from ; passing examples is a checkpoint, not proof of .
Explain it yourself
For [0.2, 0.7, 0.1], what do max and argmax return using zero-based indexing?
Compare with an explanation
max = 0.7; argmax = 1. A value and its index are different outputs.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Average, max and argmax (10 min) → thresholds and activations (10 min) → students do the lab missions (20 min) → self-check (10 min).
Show on screen
For [0.2, 0.7, 0.1] show max, argmax and the class that argmax chooses.
Move a decision threshold from 0.5 to 0.3 and show which examples change class.
Student tasks
Complete the average, maximum and threshold missions in the AI lab mode.
Done when
The student explains the difference between max and argmax and why a score is not automatically a probability.
If students get stuck
Off-by-one answers for argmax: remind students that counts positions from 0.
Questions for the class
Why might a doctor choose a lower threshold for a warning test?
Split into and evaluation sets, and explain what a score cannot tell you.
Use to fit and . has four measurements: sepal length and width, and petal length and width. Split data before fitting. Learn from the training portion and evaluate on examples. A high training score can coexist with poor results on new data; this is . Keep fitted to too, so evaluation information does not leak into learning.
Understand it the easy way
Think of it like this
Training and a model is like studying for an exam. If you memorise the answers to the practice sheet, you score 100% on that sheet but fail the real exam with new questions. That is overfitting. So you keep some questions aside (the test set) that the model never sees while learning.
Example
Split the 150 Iris flowers: 120 for training and 30 kept aside. A , which classifies by asking one question after another, scores 100% on the 120 when its depth is unlimited, but it can score lower on the 30 kept aside (87% with some splits). A big gap between the training and test scores means it memorised the sheet, so try limiting the depth and compare.
Common mistake
Peeking at the test set again and again while tuning. Each peek teaches you the test, so the final score looks better than the model really is. Use a validation split (a part set aside from the training data for choosing settings) for tuning and keep the test set for the end.
Memorising the practice sheet is overfitting. Keep test questions locked away and check the model on them only at the end.A closer look
The k and tree depth are chosen outside fitting; coefficients can be learned . Use a validation split or cross-validation to choose settings, then reserve the test set for the final estimate. Repeatedly tuning to test results makes that estimate optimistic. Report the split, baseline, score, and errors. One small Iris experiment is a first project, not proof that a model works for every population or task.
Explain it yourself
A model scores 100% on the data it learned from. What should you check next?
Compare with an explanation
Evaluate on appropriate unseen data and inspect errors and leakage. alone is not enough.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Train/test split on the board (10 min) → fit and evaluate a model (15 min) → students compare training and test scores (15 min) → self-check (10 min).
Show on screen
Split a small table into training and test rows, fit on the first part and score on the second.
Show a model that scores 100% on training data and worse on test data, and name it overfitting.
Student tasks
Complete the regression and classification missions and write down the training and test scores.
Done when
The student explains why a score on the training data is not enough.
If students get stuck
: make sure and other preprocessing are fitted on the training part only.
Questions for the class
Your model scores 100% on its training data. What do you check next?
Build an LLM 1: characters, counts and a first generator
Goal
Turn text into numbers with a character , count which character follows which, and generate new text from those counts.
Every starts by turning text into numbers. The simplest tokenizer gives each character an . The simplest , a model, counts how often each character follows each other character and turns the counts into . To generate text it picks the next character with those probabilities, adds it, and repeats. Run the below: it prints the IDs, the most likely characters after "h", some generated text and the .
Understand it the easy way
Think of it like this
A bigram model is like keeping a tally of which letter tends to follow which. After reading lots of text you have a table: after “q” almost always comes “u”, after “t” often comes “h”. To write, you roll a die weighted by that table, one letter at a time.
Example
In “hello hello help”, “h” is followed by “e” three times, so after “h” the model picks “e” with probability 3/3 = 1. After “l” come “l”, “o”, “l”, “o” and “p”, so each choice has its own share. Generate a few letters and you get something like “helo hello hel”.
Common mistake
Expecting real sentences from a bigram model. It only remembers one letter back, so it writes word-shaped nonsense. That is exactly why the next chapters add more .
Count which piece follows which, turn the counts into probabilities, then roll one piece at a time.A closer look
The loss measures how surprised the model is by the real next character — the average of minus the log of its probability. A perfect model would have a loss of 0. Real use made of several characters and look at a much longer context, but the is the same: text → IDs → probabilities for the next token → pick one → repeat.
Example code
Runs in your with and . Change the code and run it again.
Explain it yourself
The table says that after "t" comes "h" with probability 0.7 and "e" with 0.3. What happens when the model generates after "t"?
Compare with an explanation
It picks "h" about 7 times in 10 and "e" about 3 times in 10, at random according to those probabilities, and then continues from the character it picked.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Text into numbers on the board (10 min) → run the code and read the output (10 min) → students change the text and the start character (20 min) → talk about the loss (10 min).
Show on screen
Run the code and explain each printed line: the , and decode, the probabilities after "h", the generated text and the loss.
Change the text to a few sentences in another style and run it again; show how the generated text changes.
Point at the probs line and show that every row adds up to 1.
Student tasks
Replace the text with three sentences of your own and generate 40 characters from a letter of your choice.
Find which character most often follows "e" in your text and check it by counting by hand.
Done when
The student runs the code with their own text and explains what one row of the probability table means.
If students get stuck
A when generating: the start character is not in the text; choose a character that appears in it.
The output looks like nonsense: that is expected, because a bigram model sees only one previous character.
Replace counting with a small that learns and by and sees three characters of .
A counting table cannot look further back without exploding in size, but a neural network can. Each character gets a learned , an embedding.
The joins the vectors of the last three characters and passes them through a (a middle layer between that mixes the numbers into features).
It outputs a score for every possible next character.
turns the scores into .
compares the prediction with the real next character, computes the , and moves every weight a small step in the direction that lowers it. That step is gradient descent, and the backward pass computes the direction.
Understand it the easy way
Think of it like this
Training a neural network is like walking down a foggy hill to reach the lowest valley. The height is the loss — how wrong the model is. You cannot see the valley, but you can feel which way the ground slopes under your feet (the gradient) and take a small step downhill. Many small steps later, you are near the bottom.
Example
At step 0 the loss is about 3.4. Guessing at random among the 15 characters would give about 2.7, so at first the model does even worse than that. After about 300 steps it falls toward 0.2, and the generated text starts to form real-looking words because the model looks at the last three characters.
Common mistake
Taking huge steps to finish faster. If the is too large, you jump over the valley and the loss bounces or explodes. Smaller steady steps usually win.
Gradient descent: feel the slope of the loss and take a small step downhill, again and again.A closer look
Watch the loss fall as the steps go by: the is learning. The generated text now forms real words because it sees more context. controls how adventurous generation is — below 1 picks safer characters, above 1 takes more risks. Large have billions of weights and train on enormous amounts of text with , but each is this same idea.
Example code
Runs in your with and . Change the and run it again.
Explain it yourself
What happens to the generated text when the temperature goes from 0.8 down to 0.2, and why?
Compare with an explanation
It becomes more repetitive and safe, because dividing the scores by a small temperature makes the most likely character's probability much larger than the others.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Embeddings and a hidden layer on the board (10 min) → run the code and watch the loss (10 min) → students change the temperature and the text (20 min) → explain one training step (10 min).
Show on screen
Run the code and point at the loss falling every 50 steps.
Change the temperature in generate() to 0.3 and then to 1.5 and compare the texts.
Set lr to 5.0 and run again; show that a step that is too large makes training unstable.
Student tasks
Change the training text to your own sentences and train again; note the final loss.
Try two temperatures and describe the difference in one sentence.
Done when
The student shows the loss going down and explains what an embedding and a training step are.
If students get stuck
The loss becomes nan: the learning rate is too high; lower lr below its current value, for example to 0.1.
Generation fails with your text: the start string must be three characters that appear in the text.
Questions for the class
What does the backward pass compute?
Why does more context make the text look more like real words?
Build an LLM 3: attention, the heart of a transformer
Goal
Add so that every position can look back at earlier characters and decide which ones matter, then train it and inspect it.
, the architecture behind today's , are built on attention:
For each position the makes a query (what am I looking for?).
Every earlier position offers a (what do I contain?) and a value (what do I pass on?).
Comparing the query with the keys gives attention that add up to 1.
The output mixes the values with those weights.
A stops a position from looking at characters that come after it, so the model cannot cheat. Position tell the model where each character stands.
Understand it the easy way
Think of it like this
Attention is like a classroom where each student can look back at earlier students' notes. Each one holds up a question card (query), every earlier student wears a name tag (key) and holds their notes (value). The better a name tag matches the question, the more of that student's notes get copied. A rule says nobody may peek at students who come later (the causal mask).
Example
In “The cat sat because it was tired”, when the model reaches “it”, its query matches the key of “cat” strongly, so much of the value of “cat” flows into “it”. In a large, well-trained model, printing the attention weights would show a big number next to “cat”; the small character model in this chapter shows attention gathering on nearby characters.
Common mistake
Thinking attention weights explain everything the model “thinks”. They show where one head looked in one layer — a useful clue, not a full explanation.
Each position asks a question (query), compares it with every earlier name tag (key) and mixes their notes (values). No peeking at what comes later.A closer look
This trains one with a of eight characters, entirely in , and prints the attention weights of the last character, so you can see which earlier characters it relies on. A real transformer stacks many layers with many heads each, adds and , and trains with an such as on far more text. Everything else — , embeddings, , , and — you have now built yourself.
Example code
Runs in your with and NumPy. Change the code and run it again.
Explain it yourself
In one sentence each, say what the query, the key and the value do.
Compare with an explanation
The query describes what the current position is looking for; the key describes what each earlier position contains so that it can be matched with the query; the value is the information passed on in proportion to that match.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
with an everyday example (10 min) → run the code and read the loss and the attention weights (10 min) → students experiment (20 min) → connect it to real LLMs (10 min).
Show on screen
Explain attention with a sentence: in "the dog ran because it was scared", the word "it" attends to "dog".
Run the code and read the attention weights of the last character: which earlier positions get the most weight?
Remove the mask (multiply it by 0) and show that the loss drops suspiciously low because the model can see the answer.
Student tasks
Train with your own text and generate from a start string of your choice.
Print the attention weights for another example, such as X[10:11], and describe what the last character attends to.
Done when
The student trains the model, shows the loss going down, and explains query, key, value and the causal mask in their own words.
If students get stuck
errors after changing T: the mask and the windows both depend on T, so change T in one place only.
is slow on an old device: lower the number of steps to 200; the loss still falls.
Questions for the class
Why does the model need a causal mask?
What do the attention weights of one position add up to?
Train a small with the same design as on your own computer with and . Watch the fall and generate text from your .
GPT-2 is a stack of :
and position
layers of and a small
a final layer that scores every possible next token
The smallest GPT-2 has about 124 million and was trained on billions of tokens with large for days. That is too big for a laptop. But the same design, made small, does train on a laptop. With 4 layers, 4 and 128-number embeddings (about 0.8 million parameters), it learns from a small text such as Shakespeare in about 3 minutes on the .
's , written in PyTorch (a Python for building and neural networks), is the classic short for this: prepare the , run the training script, then sample text. Its author now marks it as old and points to , a newer project. Still, nanoGPT is the clearest way to see a GPT-2-style model in a few hundred lines.
Understand it the easy way
Think of it like this
GPT-2 is like a layer cake: the same transformer block stacked again and again, each layer refining the guess a little more. The full-size cake needs a professional bakery (big GPUs for days); a cupcake with the same recipe — fewer, thinner layers — bakes in your kitchen in a few minutes.
Example
4 layers, 4 attention heads, embeddings of 128 numbers: about 0.8 million parameters, trained on Shakespeare for about 3 minutes on a laptop. Sample from it and you get text with Shakespeare-like and names, even if the words do not always make sense.
Common mistake
Watching only the training loss. If the training loss keeps falling while the starts to rise, the model is memorising — stop there or make it smaller.
The same recipe at two sizes: full GPT-2 needs a bakery, a tiny GPT-2 bakes on your laptop.A closer look
Training repeats one step:
Take a of text.
Predict each next token.
Measure the error (the loss).
Nudge every parameter to make the loss smaller.
Watch two numbers: the training loss, and the validation loss on text the model has not seen. If only the training loss falls, the model is memorising. When training ends you have a with all the parameters.
On a use the mps device, on an card use , and otherwise the cpu with a smaller model. The chapters before this one built the same pieces by hand in ; here you use them at real size.
Commands to type in your terminal
git clone https://github.com/karpathy/nanoGPT
cd nanoGPT
pip install torch numpy transformers datasets tiktoken wandb tqdm
python data/shakespeare_char/prepare.py # text -> characters -> numbers
# a small GPT on the CPU (about 3 minutes); on a Mac use --device=mps
python train.py config/train_shakespeare_char.py --device=cpu --compile=False \
--eval_iters=20 --log_interval=1 --block_size=64 --batch_size=12 \
--n_layer=4 --n_head=4 --n_embd=128 --max_iters=2000 \
--lr_decay_iters=2000 --dropout=0.0
python sample.py --out_dir=out-shakespeare-char --device=cpu
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Name the three main parts of a GPT and what each one does.
Compare with an explanation
Embeddings turn tokens and positions into ; transformer blocks (self-attention plus a small neural network) mix information between the tokens; the turns the last vector into a score for every possible next token. Then picks the next token.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
From the three browser chapters to GPT-2: the same blocks, bigger (10 min) → set up Python and PyTorch (10 min) → prepare data and start training (15 min) → sample text and read the loss curve (15 min).
Show on screen
Show the GPT-2 block diagram and match each part to the build-llm chapters: embeddings, attention, the next-token scores.
Run the Shakespeare from nanoGPT with a small CPU setting (about 3 minutes) and show the training and validation loss as it prints.
Generate text from an early checkpoint and from the final one, and compare.
Student tasks
Train the small model on your computer (or on a free ) and save the loss values at the start and the end.
Change one setting — the number of layers, the embedding size or the — and write how the loss and the text changed.
Done when
The student trained a model, has a checkpoint, can show the loss falling and can explain training loss versus validation loss.
If students get stuck
Out of : lower the batch size, the or the number of layers.
Training is very slow on the CPU: make the model smaller or use a free cloud notebook with a GPU.
Questions for the class
Why does the same GPT-2 design work at a much smaller size?
What does it mean when the training loss keeps falling but the validation loss rises?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 37 · Master · Run your model anywhere
The runner: the program that brings a model to life
Goal
Explain what a does: load the , tokenize, run the step by step, sample and stream. Then run a model with or .
A trained model is only a file of numbers. A runner is the that uses it. It repeats this work:
Load the weights into .
Turn your text into with the model's .
Run the model to get scores for the next token.
Sample one token with settings like .
Add it to the text and show it on screen, one token at a time ().
It keeps a of earlier work (the ) so each new token is fast, and it applies the the model was trained with. Ollama and llama.cpp are runners around models, and services like run such runners on their .
Understand it the easy way
Think of it like this
A trained model is like a music record, and the runner is the record player. The record holds all the music (the weights), but you need a player to read it, turn your words into tokens, play the next note, and keep going. Different players read different record formats.
Example
Ollama and llama.cpp read files on an ordinary computer. You type a question, the runner tokenizes it, runs the model, samples a token, shows it on the screen and repeats — that is why answers appear word by word.
Common mistake
Thinking a model needs an internet key. A runner on your own computer can offer an with no key, and your does not leave the machine.
The model is the record; the runner is the player that reads it and plays the next token, one at a time.A closer look
Runners differ in where they run and which file formats they read:
— runs your directly.
llama.cpp — runs GGUF files on computers and phones; Ollama — on computers.
and phones — can also use , a model format many tools read, or Apple's () and Google's () own .
Many runners offer a , so your own app can talk to a model on your computer exactly like it talks to a API — with no key and no data leaving the machine. Your checkpoint becomes runnable in these engines after a conversion step, which the next chapter does.
Commands to type in your terminal
# a runner on your computer: download a small open model and chat
ollama run llama3.2:1b
# the same runner as a local API — no key, nothing leaves the machine
curl http://localhost:11434/api/generate -d '{
"model": "llama3.2:1b",
"prompt": "Explain a token in one sentence.",
"stream": false
}'
These run in a on your own computer or server, not on this page. Read each line before you run it.
Explain it yourself
List the steps a runner repeats to produce each new token.
Compare with an explanation
It repeats these steps:
Take the text so far, as tokens.
Run the model to get a score for every possible next token.
Turn the scores into .
Sample one token, using temperature and similar settings.
Append it and show it.
It stops at a or the length limit.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Weights are just numbers: what is missing? (5 min) → the runner's loop step by step (15 min) → run a small with Ollama or llama.cpp (20 min) → call its local API (10 min).
Show on screen
Write the runner loop on the board: tokenize → model → scores → sample → append → repeat, and connect it to the chapter.
Run a small open model locally (for example ollama run with a 1-billion-parameter model) and show tokens streaming.
Call the local API with , with "stream": false in the request, and show the whole answer coming back as one object. Without it, a JSON line arrives for every token.
Student tasks
Write the runner loop as numbered steps in your own words and mark where temperature is used.
Run a small open model on your computer and measure how many tokens per second it produces.
Done when
The student can explain each step of the runner loop, has run a local model and knows that a runner can serve a local API.
If students get stuck
The model is too slow or does not fit: choose a smaller model or a more strongly file.
The answers look strange: the chat template or tokenizer does not match the model — use the files that came with it.
Questions for the class
Why is a weights file alone not enough to chat with a model?
What is the advantage of running a model locally instead of through a cloud API?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 38 · Master · Run your model anywhere
Your LLM on your phone: convert, shrink and embed
Goal
Convert a to a phone-friendly format, shrink it with , it with a in an app and use it offline on your own phone.
Phones have little , so the model must be small and compressed. Quantization stores each with fewer . For example, 4 bits instead of 16 makes the file about four times smaller with only a small in quality.
The usual path:
Convert the model to with the conversion tools.
Quantize it ( is a common choice).
Test it on your computer first.
Your own can be exported too, but not the from chapter 34 (shakespeare_char) as it is: retrain it with the (/shakespeare) and save it in GPT-2 format. And a tiny model trained on Shakespeare will only write Shakespeare. For a useful assistant, start from a small of about 1 to 3 billion parameters.
Understand it the easy way
Think of it like this
Quantization is like packing for a trip with a small suitcase. Instead of folding every shirt neatly at full size (16 bits per number), you roll them tight (4 bits). Everything still fits and looks almost the same, but the suitcase is about four times smaller — small enough for a phone.
Example
A 3-billion-parameter model at 16 bits is about 6 ; quantized to about 4 bits it is under 2 GB. Copy the GGUF file into an offline chat app on your phone, switch on airplane mode and ask it something — it still answers.
Common mistake
Expecting a tiny model trained on Shakespeare to be a helpful assistant. For a useful phone assistant, start from a small open model and keep short.
Quantization packs the same model with fewer bits per number, so it fits and runs on a phone — even offline.A closer look
There are two ways to use it on a phone:
The quick way — copy the GGUF file into an app that already contains a runner, such as , and chat offline.
The builder's way — put the runner in your own app, for example in a app or a llama.cpp in a app. Ship or download the model file, and call it from your .
Everything stays on the phone, so it works without the internet and keeps data private. But it is slower than the and uses battery, so keep prompts short and models small. Another way is to keep the runner on your computer and call its from the phone over the same Wi-Fi. That is easier, but it works only near that computer.
Do not confuse a model in an app with embeddings, the from the embeddings chapter. A small on the phone can also search your own notes.
Commands to type in your terminal
# your own nanoGPT: train it with the GPT-2 tokenizer (data/shakespeare, not shakespeare_char)
# and save the weights as a Hugging Face GPT-2 folder (./my-model) — then it converts like any model
# llama.cpp: model folder -> GGUF (16-bit) -> 4-bit Q4_K_M
python convert_hf_to_gguf.py ./my-model --outfile my-model-f16.gguf
./llama-quantize my-model-f16.gguf my-model-Q4_K_M.gguf Q4_K_M
ls -lh my-model-*.gguf # about four times smaller
# quick way: copy my-model-Q4_K_M.gguf into an offline chat app (e.g. PocketPal AI)
# builder's way: embed a runner in your app (llama.rn, a llama.cpp binding) and load the file
These run in a on your own computer or , not on this page. Read each line before you run it.
Explain it yourself
Describe the path from a trained model on your computer to a chat on your phone in four steps.
Compare with an explanation
1. Convert the model to a phone-friendly format such as GGUF. 2. Quantize it (for example to 4 bits) so it fits in memory. 3. Put it in an app that contains a runner — an existing offline chat app or your own app with an embedded runner. 4. Load it on the phone and chat offline. on the computer between the steps is also good.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Why phones need small models (5 min) → convert and quantize on a computer (15 min) → run it in a phone app (15 min) → how an app embeds a runner (15 min).
Show on screen
Show the file size of the same model at 16-bit and at 4-bit and test both on a computer.
Load a small quantized GGUF model into an offline chat app on a phone, turn on airplane mode and chat.
Show a few lines of app code that load the model file and stream from the embedded runner.
Student tasks
Choose a small open model, find its quantized GGUF file, and estimate whether it fits in your phone's memory.
Run it on your phone offline and write the speed (tokens per second) and one thing it does well and one it does badly.
Done when
The student can explain conversion, quantization and embedding a runner in an app, and has run a model offline on a phone (or on a computer if no phone is available).
If students get stuck
The app crashes when loading: the model is too big for the phone's memory — use a smaller model or stronger quantization.
No phone available: run the same GGUF file with llama.cpp on a computer; the steps are the same.
Questions for the class
What do you gain and what do you lose with 4-bit quantization?
Product details checked on 2026-10-15. AI tools change quickly — compare with the official page.
Chapter 39 · Master · Final project
Final project: build something with AI and show your work
Goal
Plan, build and present a small project with the tools of this course, with a history and checks that show it works.
Choose a small, useful project — for example a quiz generator for your , a script that organises your files, a web page about a hobby, or your own mini trained on a text you like. Then:
Write a one-page plan: the goal, the users, and how you will check that it works.
Build it with a in small loops.
after each working step.
Keep the on your rules with AGENTS.md, CLAUDE.md or a .
Finally, open a on that describes what you built and how to try it.
Understand it the easy way
Think of it like this
A final project is like a science fair. You pick a small question, build something that answers it, test it, and stand by your poster to explain what worked, what went wrong and how you found out. The honesty of the story matters as much as the result.
Example
Project: a quiz generator for your class. Plan: 10 questions from a chapter, checked by a friend. Build it in small loops with an agent, commit each working step, record one moment the made a wrong question and how you caught it, then open a pull request with .
Common mistake
Choosing a project that is too big to finish. A small project that works and is explained well beats a huge one that never runs.
Plan, build in small loops, check and present honestly — what you made, what the AI made and how you checked it.A closer look
The presentation matters as much as the : show the plan, one moment when the AI got something wrong and how you noticed, the tests or checks you ran, and what you would do next. Credit honestly — say which parts you wrote, which the AI wrote, and how you checked them.
Explain it yourself
What four things should the description of your final pull request contain?
Compare with an explanation
What the project does, how to run or try it, how it was checked (tests or examples), and which parts were made with AI help.
You mark this yourself. Nothing is graded here.
Mark this chapter as understood?
This cannot be undone yet, so mark it only when you really understand.
Marked as understood
You mark this yourself. Nothing is graded here.
Teaching guide
How to run this chapter in class. Students may read it too.
Lesson flow
Project ideas and scope (15 min) → students plan and build over one or more lessons → presentations with the Git history and a demo (about 10 min each).
Show on screen
Show an example plan with a goal, users, checks and three milestones.
Show a finished example : the commits, a CLAUDE.md or AGENTS.md, and a pull request with a clear description.
Give a short example presentation that includes one AI mistake and how it was caught.
Student tasks
Write the one-page plan and get the teacher's approval before you start building.
Build it in at least three commits and open a pull request with a description and instructions to try it.
Done when
The pull request exists, the project works as described, and the student can explain one AI mistake and one check.
If students get stuck
The project is too big: cut it down to one feature that works from start to finish, then add more.
The code works but the student cannot explain it: ask the agent to explain it line by line, then rewrite one part yourself.
Questions for the class
Which check gave you the most confidence that your project works?
Which parts did you do yourself, and which did the AI do?
