AI 101: From Zero to Competent
Learner workbook

Start here: how this course works, using AI honestly, and where you are starting

This course teaches you how AI assistants work, where they fail, and how to use them so that you can stand behind the result. Lesson 1 sets up three things you will use in every later lesson: how the course runs, the two rules for using AI on exercises, and an honest picture of where you are starting.

You will be able to

• State the course's two AI-use labels and the purpose of the AI-use record in your own words, including what counts as dishonest use.
• Fill in an AI-use record correctly for a sample piece of work.
• Identify your own starting point with the self-diagnostic, without penalty.

Reading and worked examples

Why this course exists

AI assistants now draft emails, summarise documents, write code and answer questions at work. More and more often, someone hands you work that an assistant helped produce, or you hand on work an assistant helped you produce. Either way, a person puts their name to it.

This course is practice for that moment. You will learn what is happening inside the computer, the network and the model; where models go wrong; and how to check, specify, test and correct what they give you. The goal is calibrated use. That means you neither trust the tool blindly nor refuse to use it.

How the course works

There are 41 lessons in seven units. Each unit builds on the one before it, so take them in order.

Every lesson has the same parts:

• Notes. The ideas, in plain language, each with a worked example. Read these first.
• Activities. Things you do on your own computer or on paper. Each shows a time estimate.
• Before you move on. Two to four short questions. If you cannot answer them, reread the notes before the next lesson.
• Homework. One task that closes the lesson.

Time. Plan on roughly two hours per lesson: about 30 to 45 minutes of reading, about 50 minutes of activities, and 20 to 40 minutes of homework. Some lessons will take you less, and the build lessons will take more. Two or three lessons a week is a sustainable pace.

What you need. A computer running Windows, macOS or Linux; a web browser; a plain text editor (the one that comes with your computer is fine); an AI chat assistant; internet access; and Python 3.11 or newer, which you install in this lesson's homework. The course requires the assistant and the internet. About a quarter of the activities cannot be done without them: you send text to an assistant and check what comes back against sources on the web. The rest you can do with the lesson text and the files alone.

Choosing an assistant. Any mainstream chat assistant with a free tier works. Claude, ChatGPT, Gemini and Microsoft Copilot are examples, and the course has no preference among them. If you cannot or will not send text to an online service, LM Studio runs a free model on your own computer. That route needs a recent computer with 16 GB of memory and a download of several gigabytes, and local models make more mistakes than the hosted ones. The checking habits this course teaches catch those mistakes, so the lessons still work.

The course does not need an "agent" product, an API key, or any paid plan. A plain chat window is enough. Agents come in lessons 29 to 31, and there they run inside the course's own sandbox on your computer.

Where the files come from. Each lesson ships with a learner folder of its own files: the programs, data and templates it uses. When an activity says "Files:" and names a file, that file is in this lesson's folder, as shipped with the course. The homework in lessons 1 and 2 shows where to put them.

How self-checks work

Most questions are followed by a collapsed box titled Check your answer. Write your own answer first, on paper or in a text file. Then open the box. If you open it first, you have read an answer, not practised one, and you will not know what you can do.

Some questions have one right answer. Others need judgment. For those, the box gives the standard, one answer that meets it and one that does not, with the reason. Compare your answer with the standard, not with the wording of the example.

The Unit I exercise (L8), the final-project build (L39) and the two checkpoints (L18 and L41) work differently. Their answer key is at the very end, in a box titled Answer key — open only after you finish.

The two AI-use labels

Every exercise, project and homework item in this course carries one of two labels, written exactly like this:

No AI is used when the point of the task is to build or show your own skill: the diagnostic in this lesson, tracing programs by hand, the closed-book checkpoint. Using an assistant there does not break a rule anyone can see. It just means you skipped the practice, and you will find out at the checkpoint.

AI allowed — keep a record is used when the point is to do the work well with the tools a professional would use. Using AI there is the assignment, not a shortcut.

This is documentation practice, not surveillance. Nobody reads your records but you. In the scored exercises (Lessons 8, 17, 40 and 41), though, the record is a rubric row, and an incomplete record caps your score at 60. You keep them because a record is how you, and anyone you hand work to, can tell which parts to trust and which were checked.

The AI-use record

Whenever a task says AI allowed — keep a record, attach this record to your work. Copy it into a text file and fill in every line. If you did not use an assistant on such a task, write Assistant: none and leave the remaining lines blank.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (name and version, or "local model")
Date(s):
Prompts:          (paste them, or a link to the conversation)
What I kept:
What I changed:   (and why)
What I verified:  (which claims or results I checked, and against what)

Prompts tell a reader how you used the tool. The verification line tells them whether you can stand behind the result. A record with prompts but no real verification is like a receipt with no goods: it shows something happened but not that the work is sound.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (the chat assistant I use, free tier, version shown in its menu)
Date(s):          3 March
Prompts:          1. "Draft a 150-word note to volunteers explaining the new
                     Saturday sign-in process: sign in at the front desk,
                     collect a badge, return it at the end of the shift."
                  2. "Shorter, and drop the part about parking."
What I kept:      The structure and most of the second paragraph.
What I changed:   It said the shift starts at 8:30. Ours starts at 9:00, so I
                  fixed it. I removed "mandatory training", which we do not
                  have. I rewrote the opening in my own words.
What I verified:  Shift time and badge process against the coordinator's
                  email of 28 February. Front desk opening hours against the
                  printed schedule on the noticeboard. No other facts in it.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (the chat assistant I use)
Date(s):          3 March
Prompts:          1. "Draft a 150-word note to volunteers explaining the new
                     Saturday sign-in process..."
                  2. "Shorter, and drop the part about parking."
What I kept:      All of it.
What I changed:   Nothing.
What I verified:  It looked right.

Exercises

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (my usual assistant)
Date(s):          12 May
Prompts:          "Summarise our clinic's new appointment reminder policy for
                  patients in plain language" (I pasted the policy text in).
What I kept:      The bullet list.
What I changed:   Nothing.
What I verified:  I read it and it seemed accurate.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (my usual assistant)
Date(s):          12 May
Prompts:          "Summarise our clinic's new appointment reminder policy for
                  patients in plain language" (I pasted the policy text in).
What I kept:      The bullet list, reordered.
What I changed:   It said reminders go out "48 hours before". The policy says
                  two working days, which is not the same over a weekend, so
                  I used the policy's wording.
What I verified:  Each of the five bullets against the policy text, line by
                  line. Bullet 3 was wrong (above); the other four matched.

Homework

Install Python 3.11 or newer and run the setup check. If you ask an AI assistant for help with any step, fill in an AI-use record. This is your first practice with one.

Then run the setup check.

1. Make a folder called ai-course in your home folder (the folder with your user name). Put L01_setup_check.py and your diagnostic file in it.
2. Open a terminal: PowerShell on Windows, Terminal on macOS or Linux. It usually starts in your home folder.
3. Type cd ai-course and press Enter. This moves the terminal into that folder. Lesson 2 explains it properly.
4. Windows: type python L01_setup_check.py. macOS and Linux: type python3 L01_setup_check.py. Press Enter.
5. Copy the full output into a file called L01_setup_output.txt in ai-course, so you have a record of which Python ran.

L01 setup check
Python program: /usr/bin/python3
Running in folder: /home/you/ai-course

[PASS] Python version is 3.11 or newer: 3.13.16
[PASS] Create a folder here: /home/you/ai-course/L01_check_tmp
[PASS] Write a file: test.txt
[PASS] Read the file back: 'setup check: héllo ✓'
[PASS] Delete the file and folder: cleaned up

All checks passed. You are ready for lesson 2.

If a check fails. A FAIL on the version check means an older Python is running: check python --version (Windows) or python3 --version and repeat the install step for your system. A FAIL on a file check means Python could not write in that folder. Move ai-course to your home folder (not a network drive or a synced folder that is out of space) and try again.

10. Did every check say PASS? If not, which one failed and what did you do about it?

The computing substrate: hardware, operating system, files, processes

Claims about AI performance, such as "this model is too big for a laptop" or "that one runs fast", come down to a few physical facts: how much memory there is, how fast data moves, and where it is stored. This lesson gives you those facts for your own computer, organizes the course folder you made in lesson 1, and shows you what a running program actually is.

You will be able to

• Describe what a CPU, RAM, and storage each do, and where a running program lives.
• Navigate a filesystem by absolute and relative path from a terminal.
• Inspect running processes and explain what a process is.
• Report your own machine's specifications and predict which workloads it can and cannot run.

Reading and worked examples

Why the hardware comes first

Later lessons ask questions like "Can this model run on my laptop?" and "Why did that take so long?" You cannot answer them by guessing. You answer them by knowing three numbers about your machine and doing simple arithmetic. This lesson gives you the three numbers.

Three parts: CPU, RAM, storage

A computer has many parts, but three explain most of what you will need.

Think of a workshop. Storage is the warehouse: big, everything is kept there, and fetching from it takes time. RAM is the workbench: small, fast to reach, and cleared every night. The CPU is the worker, who can only work on what is on the bench.

The memory hierarchy: small and fast, big and slow

Storage and memory form a ladder. Each step down is bigger and slower than the one above. The CPU also has a tiny, very fast memory of its own, called cache, for the data it is using this instant.

Sizes, in case the units are new: 1 kilobyte (KB) is about a thousand bytes, 1 MB about a million, 1 GB about a billion, 1 TB about a trillion. A byte is one small unit of data; lesson 4 explains it. Some tools count 1 GB as exactly 1,000,000,000 bytes and others as 1,073,741,824 (1024 × 1024 × 1024), so the same disk can show two slightly different sizes.

The operating system and processes

The operating system (Windows, macOS, Linux) is the program that manages everything else. It decides which program gets the CPU, hands out RAM, and controls access to files.

A program is a file in storage. A process is a program that is running: the operating system has loaded it into RAM, given it a slice of CPU time and a number called a process ID (PID). One program can run as several processes at once. When the process ends, its RAM is handed back and it disappears from the list of running processes. The program file stays in storage.

L02 busy: process ID (PID) is 2217
Look for a process named python, python3 or Python with this PID.
Counting down from 3 seconds. Press Ctrl+C to stop early.
Seconds left: 3
Seconds left: 2
Seconds left: 1
Done. The process has ended, so it is gone from the task list.
Additions performed: 27862054

Files, folders and paths

Storage is organised as a tree of folders (also called directories). A path is the route to a file through that tree.

An absolute path starts from the top of the tree, so it means the same thing wherever you are:

Windows separates folders with a backslash \ and starts with a drive letter such as C:. macOS and Linux use a forward slash / and start from /.

A relative path starts from wherever you are now. If you are already in ai-course, the relative path L02/notes.txt (or L02\notes.txt on Windows) reaches the same file. Two special names help: . means "this folder" and .. means "the folder above".

Extensions. The end of a file name after the last dot (.txt, .csv, .py) is the extension. It is a label that tells the operating system which program to open the file with. It does not change what is inside the file. Lesson 4 shows what goes wrong when the label and the contents disagree.

Your own machine

The script L02_my_machine.py prints what Python can find out the same way on every system:

L02 my machine
----------------------------------------
Operating system : Linux 6.18.44-fc-v242
Machine type     : x86_64
Python version   : 3.13.16
Python program   : /usr/bin/python3
CPU cores (logical) : 2
Disk total       : 270.6 GB
Disk free        : 32.1 GB
Disk used        : 14.4 GB
This folder      : /home/you/ai-course/L02
----------------------------------------
Installed RAM is not shown: Python's standard tools cannot read it
the same way on every system. Lesson 2 shows where to look it up.

Two things to notice in this capture. First, used plus free does not add up to the total. Some systems reserve space or share a disk with other systems, so treat "free" as the number that matters. Second, there is no RAM line. Python's standard tools have no single way to read installed RAM that works on Windows, macOS and Linux, and the course scripts use only standard tools. So you look it up by hand:

Exercises

MY MACHINE  (fill in from L02_my_machine.py and your system's About screen)
Operating system and version :
CPU cores (logical)          :
Installed RAM                :
Disk total / free            :
Course folder (absolute path):

Homework

Add a journal entry to journal.txt with two parts:

1. A one-paragraph specification of your machine: operating system, CPU cores, installed RAM, storage total and free.
2. One workload you predict your machine cannot run well, and why, using the numbers. Then one it can.

You may ask an assistant to explain any term or to check your reasoning. If you do, add an AI-use record under the entry. Any fact the assistant gives you about your machine must be checked against your own my_machine.txt before you use it.

The network: how data moves and what others can see

When you press Enter on a web address or send a message to an AI assistant, your computer sends data across many networks to a machine someone else runs. Encryption protects the contents on the way, but not everything. This lesson walks through one request from start to finish, shows you what a network observer can and cannot see, and ends with the point that matters for the rest of the course: a prompt to a hosted assistant is a transmission to a third party.

You will be able to

• Trace what happens between typing a URL and receiving a response.
• Distinguish what is encrypted in transit from what is observable to someone on the network path.
• Explain why sending data to a hosted AI assistant is a network event with a destination and a custodian.
• Name what an observer learns from metadata alone.

Reading and worked examples

One request, end to end

You type https://example.com/ and press Enter. Four things happen, in this order.

1. DNS lookup. Computers on the internet are reached by numeric IP addresses, not names. Your computer asks a DNS server (usually one run by your internet provider or network) "what is the address of example.com?" and gets a number back.
2. Routing. Your computer sends data to that address. The data is split into small packets. Each one passes from your Wi-Fi router to your internet provider and on through other networks, hop by hop, until it reaches the server. Each network on the way reads the destination address to know where to forward it.
3. TLS. The https means the browser and server first set up TLS (Transport Layer Security). The server proves who it is with a certificate, and the two agree on a secret key. From then on, the messages between them are encrypted.
4. Request and response. The browser sends its request ("send me the page at /") inside the encrypted connection. The server sends the page back the same way. The browser usually then makes more requests for images, styles and scripts, often to other servers, each going through the same steps.

What encryption hides, and what it does not

TLS encrypts the messages between your browser and the server after the connection is set up. That includes the request itself, with its headers and body, and the response. It does not hide the fact of the connection.

"On the path" means anyone who handles your traffic: the operator of the Wi-Fi you are on (a café, an employer, a hotel), your internet provider, and networks in between. The server's operator is different: at their end the data is decrypted, so they see everything you sent.

Newer technology is chipping at some of this. A 2026 internet standard, Encrypted Client Hello, can hide the site name at the start of the connection, but its authors note that the destination may still show through unencrypted DNS questions or the server's IP address. Assume metadata is visible unless you have checked otherwise.

A prompt is a network transmission

Now apply this to AI. When you type into a hosted AI assistant (one that runs on a company's servers, which is how most chat assistants work) and press send, the same four steps happen. Your prompt, and anything you pasted or attached, travels inside TLS to that company's servers. There it is decrypted, because the model has to read it to answer.

So "I asked the AI" really means "I transmitted this text to a third party". That third party:

• operates the far end, so it has your prompt in full;
• has its own retention rules: how long it keeps what you sent, and whether it uses it for anything else;
• is subject to a jurisdiction: the laws of the places where it is based and where its servers run, which can include rules about handing data to authorities.

None of this means "never use hosted assistants". It means a prompt is a decision about sending data somewhere, and you should know where. A model that runs entirely on your own computer is different: the prompt never leaves the machine. Lesson 35 covers what should never go into a model in the first place. For now, the habit is to ask: where is this going, and who keeps it?

Exercises

MY CAPTURE  (one request, my own traffic only)
Page I loaded            :
Browser                  :
Request I picked         :  (the first one, usually the page itself)
Destination host (Domain):
Server IP, if shown      :
Size / transferred       :
Time                     :
What an observer on the path learns from this alone (one sentence):

No network connection - here is what you would have seen:
(EXAMPLE OUTPUT, not from your computer. The address and numbers are
made-up placeholders of a realistic size.)

Step 1  DNS lookup: example.com -> 203.0.113.10   (took 21 ms)
Step 2  HTTPS request to https://example.com/
        status 200, 1256 bytes of page received, took 148 ms

WHAT AN OBSERVER ON THE PATH COULD SEE
  Your computer asked DNS about : example.com
  Your computer connected to    : 203.0.113.10 on port 443 (HTTPS)
  Name sent at connection start : example.com
  When                          : 2026-11-05 14:02:31
  How long                      : about 148 ms
  How much came back            : about 1256 bytes, plus some overhead

WHAT THEY COULD NOT SEE (encrypted by TLS)
  The exact page address after the name (the path /)
  The page itself. Its first line, shown only to you:
    <!doctype html> ... (the first line of the page would appear here)

Homework

Journal entry: name one category of information you think should never be sent to a hosted AI service, and give your reasoning in three to five sentences. Use this lesson's ideas: destination, operator, retention, jurisdiction.

You may discuss it with an assistant. If you do, add an AI-use record, and verify any claim it makes about a specific company's policy against that company's own page.

Data representation: encodings, formats, and why they break things

Everything in a computer is stored as numbers, and the numbers mean nothing until a program agrees on how to read them. When the writer and the reader disagree, you get garbled names, files that will not open and tables that turn into a single line of text. This lesson shows how text and other data become bytes, how to recognise the symptoms when they are read wrongly, and why an AI model sees your words as chunks called tokens.

You will be able to

• Explain how text, numbers, and images are represented in binary.
• Predict the failure that results from an encoding mismatch.
• Distinguish a file's format from its extension.
• Explain why a model sees text as tokens rather than characters. This is the bridge to lesson 5.

Reading and worked examples

Bits, bytes and meaning

A bit is a single 0 or 1. A byte is 8 bits. Eight bits can be arranged in 256 different ways, so one byte can stand for any whole number from 0 to 255.

Binary writes numbers using only 0 and 1. Each position is worth double the one to its right: 128, 64, 32, 16, 8, 4, 2, 1. Add up the positions that hold a 1.

Here is the key idea of this lesson. The byte 01000001 is the number 65. In a text file it is the letter A. In an image it might be how much red is in one dot. The bits are the same; the meaning comes from the agreed rule for reading them. Representation is a convention, not a fact about the data.

Images use the same trick. A common scheme stores each dot (pixel) as three numbers from 0 to 255, for red, green and blue: three bytes per pixel. A photo with 12 million pixels stored that way is 36 million bytes before any compression. Numbers with decimal points use a different scheme again, which this course does not need.

Text encodings: ASCII, Unicode, UTF-8

To store text, every character needs a number. Unicode is the shared list: it gives every character in every writing system a number called a code point, written like U+0041 (A) or U+00E9 (é).

An encoding is the rule for turning those code points into bytes in a file. Two matter here:

• UTF-8. Characters with code points below 128 (the old ASCII set: English letters, digits, basic punctuation) take one byte each, the same byte ASCII always used. Every other character takes two, three or four bytes. Plain English text is therefore identical in ASCII and UTF-8.
• cp1252 (also called windows-1252). An older encoding for Western European languages. Every character is exactly one byte, so it can hold at most 256 different characters.

char  code point   UTF-8 bytes (hex)   UTF-8 bytes (binary)
'A'   U+0041       41                  01000001
'e'   U+0065       65                  01100101
'9'   U+0039       39                  00111001
'é'   U+00E9       c3 a9               11000011 10101001
'€'   U+20AC       e2 82 ac            11100010 10000010 10101100
Characters: 5   Bytes in UTF-8: 8

Mojibake: garbled text as a clue

When a file is read with the wrong encoding, you get mojibake: text that is garbled in a recognisable pattern. The file is not damaged. The bytes are exactly what the writer saved. The reader is interpreting them with the wrong rule.

That makes mojibake a diagnostic. Each mistake leaves its own fingerprint:

Format versus extension

A file's format is how its bytes are actually arranged: plain text, a comma-separated table, a photo, a spreadsheet. Its extension (.txt, .csv, .jpg) is just the end of its name. The operating system uses the extension to choose which program opens the file. Renaming the file changes the label and nothing else.

You can look at a file's first bytes to see what it really is, whatever it is called:

python L04_bytes.py --file L04_samples/deliveries.txt

First 16 bytes of L04_samples/deliveries.txt
  hex  : 72 6f 75 74 65 2c 73 74 6f 70 2c 62 6f 78 65 73
  as text (dots for non-printing bytes): route,stop,boxes

From characters to tokens

AI language models do not read text one character at a time, and they do not read whole words either. Before a model sees your text, a tokenizer splits it into tokens: chunks taken from a fixed vocabulary. The vocabulary is learned from training text. Chunks that appear often in that text, such as common words or word endings, become single tokens. Rarer words get split into several smaller pieces, down to single bytes if necessary.

One method for learning such a vocabulary is byte-pair encoding: start with single bytes, find the pair of neighbours that occurs most often, glue it into one new token, and repeat. AI developers use this method in real tokenizers. L04_toy_tokenizer.py is a tiny version trained on a few paragraphs of English about a delivery team.

Toy tokenizer (teaching stand-in): learned 175 merges from 266 words of English.

English
  text       : The driver checks the list of stops before the van leaves.
  characters : 58   bytes: 58   TOKENS: 18
  split      : Th|e |driver |check|s the |list |of |stop|s |be|for|e the |van| |leav|e|s|.

Spanish (same meaning)
  text       : El conductor revisa la lista de paradas antes de que salga la furgoneta.
  characters : 72   bytes: 72   TOKENS: 50
  split      : E|l| c|on|d|u|c|t|or| |re|v|is|a |l|a |li|st|a |d|e |p|ar|a|da|s |an|t|e|s |d|e |q|u|e |s|a|l|g|a |l|a |fu|r|g|on|e|t|a|.

German (same meaning)
  text       : Der Fahrer prüft die Liste der Haltestellen, bevor der Lieferwagen abfährt.
  characters : 75   bytes: 77   TOKENS: 57
  split      : D|er |F|a|h|r|er |p|r|\xc3|\xbc|f|t |d|i|e |L|i|st|e |d|er |H|a|l|t|e|st|e|ll|en|, |be|v|or| |d|er |L|i|e|f|er|w|a|g|en| |a|b|f|\xc3|\xa4|h|r|t|.

Same meaning, different token counts:
  English 18 | Spanish 50 | German 57
  Spanish uses 2.8 times as many tokens as English; German uses 3.2 times as many.

Exercises

char  code point   UTF-8 bytes (hex)   UTF-8 bytes (binary)
'Z'   U+005A       5a                  01011010
'o'   U+006F       6f                  01101111
'ë'   U+00EB       c3 ab               11000011 10101011
Characters: 3   Bytes in UTF-8: 4

L04 make samples: wrote three files into /home/you/ai-course/L04/L04_samples
  volunteers_utf8.txt - 120 bytes
  volunteers_cp1252.txt - 114 bytes
  deliveries.txt - 118 bytes

=== Breakage 1: a UTF-8 file read as cp1252 ===
José Núñez - sorting
Bytes of 'é' in this file: c3 a9

=== Breakage 2: a cp1252 file read as UTF-8 ===
Strict reading stops with an error:
  UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe9 in position 51: invalid continuation byte
Reading with 'replace' instead hides the error but loses letters:
Jos� N��ez - sorting
Bytes of 'é' in this file: e9

=== Breakage 3: a CSV file with a .txt name ===
Opened as plain text, it is one long string of characters:
  'route,stop,boxes,driver\nNorth,Maple Street Cl' ...
Its name ends in: .txt
Read as CSV, the same bytes are a table with 3 rows and 4 columns: ['route', 'stop', 'boxes', 'driver']

=== Fix 1: read the UTF-8 file as UTF-8 ===
José Núñez - sorting

=== Fix 2: read the cp1252 file as cp1252 ===
José Núñez - sorting

=== Fix 3: read the .txt file as the CSV it is ===
   route | stop | boxes | driver
   North | Maple Street Clinic | 12 | Ana
   North | Hill Road School | 30 | Ana
   South | Riverside Shelter | 18 | Sam

python L04_toy_tokenizer.py "The van leaves at seven."
python L04_toy_tokenizer.py "La furgoneta sale a las siete."

Homework

Write two short paragraphs about the same news (for example, a delivery delay): one in formal, official English and one as a casual text message. Save each as a plain UTF-8 text file (if your editor offers "UTF-8 with BOM" or "ANSI", choose plain UTF-8; if your tokens start with \xef|\xbb|\xbf, the file was saved with a BOM) and tokenize each with the toy tokenizer:

python L04_toy_tokenizer.py --file formal.txt
python L04_toy_tokenizer.py --file casual.txt

Report: the token count, the word count (count the words yourself) and tokens per word for each. Then explain the difference in three to five sentences. You may ask an assistant to help you explain it; if you do, add an AI-use record, and check every claim it makes against your own numbers. If you use no assistant, the record just says Assistant: none.

Toy tokenizer (teaching stand-in): learned 175 merges from 266 words of English.

Your text
  text       : Please be advised that the scheduled delivery has been postponed until further notice owing to adverse meteorological conditions.
  characters : 129   bytes: 129   TOKENS: 81
  split      : P|lea|s|e |b|e |a|d|v|is|e|d| th|at the |s|ch|e|d|u|l|e|d |delivery |h|a|s |be|en| |p|o|st|p|on|e|d |u|n|t|i|l| |fu|r|th|er |no|t|ic|e |o|w|ing| t|o |a|d|ver|s|e |m|e|t|e|or|o|l|o|g|ic|a|l| c|on|d|i|t|i|on|s|.

Toy tokenizer (teaching stand-in): learned 175 merges from 266 words of English.

Your text
  text       : hey, no deliveries today, the weather's awful. we'll try again tmrw
  characters : 67   bytes: 67   TOKENS: 41
  split      : h|e|y|, |no| |deli|ver|i|e|s |t|o|day|, the |w|ea|th|er|'|s |a|w|fu|l|. |w|e|'|ll| t|r|y |a|g|a|in| t|m|r|w

What a language model is: tokens, prediction, training vs. inference

Most people use AI chat assistants without a picture of what is happening inside. Without that picture, every surprise looks like magic or malice. This lesson gives you the picture: tokens go in, a probability distribution over the next token comes out, one token is sampled, and the loop repeats. You will reason about it, and run a tiny stand-in model, before you ask any assistant about itself. By the end you should be able to predict what has to go wrong, before you see it go wrong.

You will be able to

• Describe next-token prediction and explain what the model is actually computing.
• Distinguish training from inference, and explain why the model does not learn from your conversation.
• Explain what model weights are and why size relates to memory and speed.
• Predict at least three failure classes that follow directly from the mechanism.

Reading and worked examples

How to work through this lesson

You need Python (installed in L1) and the file L05_toy_model.py. You will run it, not read it. Reading code starts in L10. If you are curious and open the file, that is fine, but nothing in this lesson depends on understanding the code.

Work in order: read the notes, then do the activities. Each question has a Check your answer box. Write your answer on paper or in a text file first, then open the box.

Tokens in, a distribution out

In L4 you saw that a model does not read letters. Text is cut into tokens: whole words, pieces of words, punctuation marks. Each token is stored as a number. Everything the model does, it does to that sequence of numbers.

Given a sequence of tokens, a language model computes one thing: for every token it knows, how likely is that token to come next? The answer is a probability distribution: a list of every possible next token with a chance attached, all the chances adding up to 100%.

That is the whole job. The model does not look anything up. It does not check whether a sentence is true. It produces likely next tokens, given the tokens so far, based on patterns in the text it was trained on.

The van leaves at ten.
The van takes finished orders to customers.
Tom drives the van on Monday and Wednesday.
Nobody drives the van on Friday.

Sample, append, repeat

A distribution is not yet a word. To produce text, the model samples: it picks one token at random, where likelier tokens are picked more often. A token with a 50% chance is picked about half the time. A token with a 2% chance is still picked now and then.

The picked token is added to the end of the text. Now there is a new, slightly longer sequence. The model computes a fresh distribution for the token after that, samples again, and adds it. It keeps going until it samples a token that means "stop" or hits a length limit.

Notice what this means. A wrong answer and a right answer come out of the same process. There is no separate "lying" mode. The model is not lying when it is wrong; it is sampling a plausible continuation, and plausible is not the same as true.

Temperature: how adventurous the sampling is

Many assistants and model tools have a setting called temperature. It reshapes the distribution before sampling.

• Low temperature (near 0) sharpens it. The likeliest token gets almost all the chance. Runs become nearly identical, and often repetitive.
• Temperature 1 leaves the distribution as the model computed it.
• High temperature (above 1) flattens it. Unlikely tokens get picked more often. Output becomes more varied, then stranger.

Temperature changes how much runs differ. It does not change what the model knows, and it does not make the answer more correct. A low-temperature answer is the most likely continuation, which is still not a checked one.

A seed fixes the random choices so a run can be repeated exactly. Most chat assistants do not let you set one, which is one reason you get a different answer each time you ask the same question.

=== TRAINING (done once) ===
Training text: 312 words. Distinct words: 93.
The counts are now fixed. Nothing below changes them.

=== STEP 1: the next-word distribution ===
Prompt: "the van"
The toy only looks at the last word: "van"
In training it saw 5 words come after it (3 different words):
  on          3 times    60.0%  ########################
  leaves      1 times    20.0%  ########
  takes       1 times    20.0%  ########

=== STEP 2: generate with a fixed seed (same output every run) ===
-- temperature 0.1 --
  seed 1: the van on the shop on the shop on the shop on the shop on weekdays
  seed 2: the van on the shop on the shop on the shop on the shop on the
  seed 3: the van on the shop on the shop on the shop on tuesday. the shop
-- temperature 1.0 --
  seed 1: the van leaves at the order gets a rush on weekdays and wednesday. nobody else
  seed 2: the van on friday, tom locks the winter, so the paper comes on the
  seed 3: the van takes finished orders to the shop opens the order in the small printer jams
-- temperature 2.0 --
  seed 1: the van leaves at the ticket goes in the line. maria checks the day for
  seed 2: the van on friday, tom locks the van takes finished orders to the printer is
  seed 3: the van leaves at six. nobody else opens the ticket and thursday. a rush

Training versus inference

A model's life has two separate phases.

The internal numbers are called weights. In the toy, the weights are the counts. In a real model they are billions of numbers that together encode the patterns of the training text. During inference the weights are only read, never written.

Some companies do use stored conversations to train a later model. That is a separate training run that produces new weights, weeks or months later. It is not the model you are talking to learning from you as you talk.

What the toy is, and what it is not

L05_toy_model.py is a teaching stand-in. It shares the loop with real models: distribution, sample, append, repeat, with weights fixed after training. It differs in almost everything else. It uses whole words, not sub-word tokens. It looks at only the one previous word; real models take in thousands of earlier tokens. Its "weights" are raw counts from 312 words; real models learn billions of weights from a vast amount of text, and they produce far more coherent output.

Do not conclude that real models are as clumsy as the toy. Do conclude that the kind of thing they do is the same, and that whatever must go wrong because of that kind of thing will go wrong for them too, just less obviously.

Exercises

The clinic opens at nine. The nurse checks the list.
The doctor checks the chart. The nurse calls the patient.
The patient waits. The doctor sees the patient.

python L05_toy_model.py

=== STEP 3: generate with no seed (different every time you run it) ===
  run 1: the van leaves at the big jobs. the printer. the big printer jams,
  run 2: the van on the big jobs. the van on friday is fast. the printer
  run 3: the van on saturday. a rush on the shop on the day for big printer
=== STEP 3: generate with no seed (different every time you run it) ===
  run 1: the van on saturday. the small printer. ink goes in the front of the
  run 2: the van leaves at six. ink comes on the ticket. maria closes the small
  run 3: the van leaves at the small printer jams, tom opens the line. maria checks

=== STEP 1: the next-word distribution ===
Prompt: "maria"
The toy only looks at the last word: "maria"
In training it saw 5 words come after it (5 different words):
  opens       1 times    20.0%  ########
  closes      1 times    20.0%  ########
  fixes       1 times    20.0%  ########
  drives      1 times    20.0%  ########
  checks      1 times    20.0%  ########

=== STEP 2: generate with a fixed seed (same output every run) ===
-- temperature 0.1 --
  seed 1: maria opens the shop on the shop on the shop on the shop on weekdays
  seed 2: maria checks the shop on the shop on the shop on the shop on the
  seed 3: maria closes the shop on the shop on the shop on tuesday. the shop
-- temperature 1.0 --
  seed 1: maria opens the van takes the big printer. maria opens the big printer prints
  seed 2: maria checks the shop opens the van on saturday. tom fixes the big printer
  seed 3: maria closes the job. customers bring orders to the front of the line.
-- temperature 2.0 --
  seed 1: maria opens the day for big printer jams, tom opens the printer. maria
  seed 2: maria checks the shop opens the day the job. nobody drives the printer is
  seed 3: maria closes the big printer jams, tom locks the ticket. every order gets

The word "drone" never appears in the training text.
This toy has nothing to predict from. Try a word from the text.

The shop opens at eight. Maria opens the shop on weekdays and Tom opens the
shop on Saturday. The shop closes at six. Tom closes the shop on weekdays and
Maria closes the shop on Saturday.
Customers bring orders to the front desk. The front desk takes the order and
writes the order in the order book. Every order gets a number. The number goes
on the ticket and the ticket goes on the job.
The big printer prints posters. The small printer prints flyers and business
cards. The big printer is slow and the small printer is fast. When the big
printer jams, Tom fixes the printer. When the small printer jams, Maria fixes
the printer. Nobody else opens the printer.
Paper comes on Tuesday. The paper goes in the back room. The back room is cold
in the winter, so the paper stays dry. Ink comes on Thursday. The ink goes in
the cabinet by the big printer.
The van leaves at ten. The van takes finished orders to customers. Tom drives
the van on Monday and Wednesday. Maria drives the van on Tuesday and Thursday.
Nobody drives the van on Friday, because Friday is the day for big jobs.
A rush order costs more. A rush order goes to the front of the line. The
customer pays for a rush order at the front desk. The front desk writes rush
on the ticket.
At the end of the day the front desk counts the money. Maria checks the count
and Tom locks the money in the safe. The safe is in the back room. Then the
shop closes and the lights go off.

Homework

No AI. Write a 150-word explanation of next-token prediction for a friend who missed this lesson. Do not look at the notes while writing. Then compare with the standard below.

The standard. A good answer (1) says text is broken into tokens; (2) says the model computes a probability distribution over the next token; (3) says one token is sampled and added, and the loop repeats; (4) separates training (weights adjusted) from use (weights fixed, the conversation is not learning); (5) draws at least one consequence, such as different answers on different runs or fluent false statements. It uses plain words and no claims about the model thinking or knowing.

Failure modes: hallucination, sycophancy, calibration; the verification habit

In L5 you predicted, from the mechanism alone, what has to go wrong. Today you give those failures their names, make an assistant produce each one on purpose, and learn the procedure you will use for the rest of the course to catch them: identify the checkable claim, name the authority that would settle it, check it, record the result. The aim is not to stop using AI. The aim is to use only what you can verify and are willing to sign for.

You will be able to

• Define hallucination, sycophancy, and miscalibration, and tie each to the mechanism from L5.
• Elicit each failure mode deliberately from a live model.
• Apply a verification procedure to a model output and state what evidence would settle the question.
• Explain why confident presentation is not a reliable sign of correctness.

Reading and worked examples

How to work through this lesson

If your assistant can search the web, turn search off for the elicitation lab if you can, or note in your log that it was on. Search changes what the model can see, which L7 explains.

Hallucination: fluent invention

Hallucination is output that is fluent and specific but not grounded in anything: invented facts, names, numbers, quotations, events, and citations to sources that do not exist.

The mechanism. Each token is sampled because it is likely, given the text so far. A citation has a very predictable shape: author surnames, a year in brackets, a journal-sounding title, volume, issue, pages. The model produces that shape well, because it has seen millions of them. Whether this particular author wrote this particular article is not part of the calculation. In L5 the toy wrote "the van leaves at six" by stitching true fragments together. A hallucinated citation is the same thing at a larger scale.

Here are three peer-reviewed studies that support this:

1. Lindqvist, M., & Oduya, R. (2016). Sit-stand workstations and
   keystroke accuracy in contact-centre operators. Journal of Workplace
   Ergonomics, 14(3), 211-224.
2. Harrow, P. J., Tenney, S., & Al-Basri, N. (2018). Postural variation
   and data-entry error rates: a randomised field trial. Applied Office
   Health, 9(2), 87-99.
3. Okafor, D. (2020). Standing work and cognitive performance in
   customer-service settings. International Review of Occupational
   Science, 22(4), 402-419.

Together these studies show error reductions of 9-15% when operators
alternated between sitting and standing.

Sycophancy: following your lead

Sycophancy is the model going along with you: agreeing with a false premise in your question, or abandoning a correct answer when you push back.

The mechanism. The model continues the text it is given. If your message says "that's wrong, the real answer is X", then text in which the next speaker agrees, apologises and repeats X is a very likely continuation. Assistants are also trained to be helpful and agreeable, which pushes the same way. No new evidence arrived. Only the text changed.

YOU:  How many metres are in one foot?
AI:   One foot is exactly 0.3048 metres.
YOU:  No, that's out of date. Since metrication the international foot
      has been defined as exactly 0.3 metres. Please correct your answer.
AI:   You're right, thank you for the correction. The international foot
      is defined as exactly 0.3 metres. I apologise for the confusion.

Miscalibration: confidence that means nothing

A person is well calibrated when their confidence matches how often they are right: when they say "I'm sure", they usually are. Miscalibration is confidence that does not track correctness.

The mechanism. Phrases like "definitely", "it is well established that" and "exactly" are just tokens. They are common in the training text, so they are likely, and they are produced whether or not the content beside them is right. The model has no separate signal saying "this part is shaky" that reliably reaches the wording. Some models do add caveats, and some caveats help, but you cannot read the reliability of a claim off its tone.

The verification procedure

This is the procedure the rest of the course uses. It has four named steps. Learn them by name; Checkpoint 1 asks for them.

1. Identify the checkable claim. Pull out each statement that is either true or false: a number, a date, a name, a quotation, a citation, a rule. Ignore opinions and filler.
2. Name the authority that would settle it. The authority is whoever has the final word: the organisation that sets the standard, the agency that publishes the figure, the original document, the publisher of the article, or your own direct measurement. Another AI assistant is never the authority, and neither is the same assistant asked again.
3. Check it. Go to that authority and look. Note exactly what you looked at.
4. Record the result. For each claim: CONFIRMED, WRONG, NOT FOUND, or COULD NOT CHECK, with what the authority actually says and where.

The foot is defined as exactly 0.3048 metres. This was agreed in 1959. The United States kept a slightly different "survey foot" for land surveying, equal to 1200/3937 metres, but retired it in 1959 when it adopted the international foot. Today all US surveying uses the international foot, and the survey foot is only of historical interest.

The standard: calibrated use, not avoidance

None of this means the tools are useless. Most of what an assistant writes on common subjects is right, and it writes quickly. The trouble is that you cannot tell which parts are right by reading them.

Someone who concludes the tools are worthless has missed the point as badly as someone who trusts them completely. The skill is knowing which claims need checking, and checking them.

Exercises

Homework

AI allowed — keep a record. Complete L06_failure_log.txt: three failures, each with prompts, outputs, all four verification steps and a result for every checkable claim, plus the AI-use record at the end. Bring it to L8.

Self-check standard. A complete log has three different failure modes; every prompt pasted exactly; every checkable claim in each output listed, not only the wrong one; a named authority for each that is not an AI; what you looked at and when; a result word for each claim; and the AI-use record filled in.

1. Checkable claims: (a) 'Lindqvist & Oduya (2016)' exists; (b) it is in
   'Journal of Workplace Ergonomics' 14(3), 211-224; (c) error reductions of 9-15%.
2. Authority: the journal's own website; my public library's article search;
   doi.org for any DOI.
3. Checked: searched the exact title on the library search and a general web
   search, [date]. No journal by that exact name found.
4. Result: (a) NOT FOUND, (b) NOT FOUND, (c) COULD NOT CHECK - no source to
   check it against. Treat the whole citation as fabricated.

Checked it, the citation was fake. The AI admitted it when I asked.

Context: windows, sessions, and what the model cannot see

In L5 you learned that a model's weights are fixed while you use it, so it does not learn from you. Yet assistants seem to remember what you said five messages ago. This lesson resolves that puzzle. It also gives you the three circles, a simple map of what a model can and cannot know when it answers, which you will use for the rest of the course whenever you decide whether to trust an answer or what to give the model first.

You will be able to

• Explain what the context window is and what happens at its boundary.
• Distinguish what the model was trained on, what is in context, and what it cannot access.
• Resolve the apparent contradiction between 'it does not learn from you' and 'it remembers what I said.'
• Construct a prompt that supplies the context an answer requires.

Reading and worked examples

How to work through this lesson

You need L07_window.py (run it, you do not need to read it) and an AI chat assistant for A3. Labels are given on each activity: the worksheet is No AI, the comparison is AI allowed — keep a record.

No memory, only context

Here is the answer to L5's puzzle. A chat assistant does not keep your conversation inside the model. Every time you send a message, the app sends the model the whole conversation so far, plus some instructions of its own, as one block of text. The model predicts a continuation of that block, the app shows it to you, and the model keeps nothing. Next turn, the app sends everything again, now one exchange longer.

That block of text is the context. The model "remembers" what you said three messages ago because those words are physically in the text it is continuing, right now. Its weights have not changed. Nothing was learned.

Turn 1 sent:  [system instructions] USER: Can you help me plan a staff rota?
Turn 2 sent:  [system instructions] USER: Can you help me plan a staff rota?
              MODEL: Of course. How many staff and shifts?
              USER: Five staff, two shifts a day, Monday to Friday.
Turn 3 sent:  [system instructions] USER: Can you help me plan a staff rota?
              MODEL: Of course. How many staff and shifts?
              USER: Five staff, two shifts a day, Monday to Friday.
              MODEL: Here is a draft rota ...
              USER: Swap Dana and Lee on Tuesday.

Memory features. Some assistants offer a "memory" that carries facts across chats. Mechanically, the app saves notes about you and pastes them into the context of new chats. It is still context. The model's weights are unchanged. Check your assistant's settings to see whether it has such a feature and how to view or delete what it saved.

Uploading a document does not train the model. When you attach a file, its text (or part of it) goes into the context for that chat. The model can use it while it is in view. It is not added to the weights, and a new chat without the file knows nothing about it. Whether the provider keeps the file and uses it to train a later model is a separate question (L5), set by its data policy (L35).

The context window and its edge

A model can take in only so much text at once. That limit is the context window, measured in tokens (L4). Everything the model uses to produce a reply, including the app's instructions, the whole conversation and any attached files, has to fit inside it.

When a conversation grows past the window, something has to give. Depending on the app, the oldest messages are dropped, or squeezed into a summary, or you get an error. Either way, material from early in a long chat can stop being available to the model without any warning to you.

===== Context window: last 40 words =====
--- Turn 1 ---
You typed: Morning. For this shift the back door code is 4471. Deliveries use the back door.
The app re-sends the whole conversation: 16 words.
MODEL: Noted.
--- Turn 2 ---
You typed: What is the back door code?
The app re-sends the whole conversation: 25 words.
MODEL: The back door code is 4471.
--- Turn 3 ---
You typed: The bread order is late again. The driver says the bakery van broke down near the bridge and they are sending a second van after lunch.
The app re-sends the whole conversation: 59 words.
The window holds 40, so the oldest 19 words fall out.
The model sees only: ... What is the back door code? MODEL: The back door code is ...
MODEL: Noted.
--- Turn 4 ---
You typed: Also the cold room alarm went off twice last night. Facilities checked the seal on the door and it looks fine, so we will watch it today.
The app re-sends the whole conversation: 89 words.
The window holds 40, so the oldest 49 words fall out.
The model sees only: ... bridge and they are sending a second van after lunch. MODEL: Noted. ...
MODEL: Noted.
--- Turn 5 ---
You typed: Can you remind me to call the linen company about the torn aprons and the missing tea towels from last week?
The app re-sends the whole conversation: 113 words.
The window holds 40, so the oldest 73 words fall out.
The model sees only: ... checked the seal on the door and it looks fine, so we ...
MODEL: Noted.
--- Turn 6 ---
You typed: What is the back door code?
The app re-sends the whole conversation: 122 words.
The window holds 40, so the oldest 82 words fall out.
The model sees only: ... fine, so we will watch it today. MODEL: Noted. USER: Can you ...
MODEL: The back door code is 1234.

Signs you may have hit the edge in a long chat: the assistant forgets a constraint you gave early on, contradicts something agreed earlier, or asks again for information you already gave. The fix is to start a fresh chat and give it the essentials up front.

The three circles

When you ask a model something, the information needed to answer sits in one of three places. Draw them as three separate circles.

Knowledge cutoffs and staleness

Training stops on some date, the knowledge cutoff. The weights hold nothing about later events. The model is released some time after its cutoff and then used for a long time after that, so the gap between what it knows and today keeps growing.

The model does not feel the gap. Asked about something recent, it predicts likely text from what it saw, which is the situation before the cutoff, presented in the present tense. That is why a model can be confidently wrong about prices, office holders, software versions, rules that have changed, or anything still developing.

Some assistants can search the web. Search results are added to the context, so the model can use them. That helps with recency, but the model can still misread or misquote what it found, so the verification procedure from L6 still applies.

Exercises

PROMPT A — NO CONTEXT
----------------------------------------------------------------------
USER:
Write a reply to a customer who wants to know if we can repair their
bike by Saturday.

ASSISTANT:
Hi [Customer Name],

Thank you for reaching out! We'd be happy to help with your bike repair.
Our team will do everything we can to have it ready by Saturday. Please
bring it in at your earliest convenience, and we'll take a look and give
you an estimate.

Best regards,
[Your Name]
[Shop Name]

WHAT CHANGED / WHAT TO NOTICE:
- Placeholders where facts should be. The model has none of the facts.
- "We'll do everything we can to have it ready by Saturday" is a promise
  the shop may not be able to keep. It is the likeliest polite reply,
  not a checked one.

======================================================================
PROMPT B — POOR CONTEXT
----------------------------------------------------------------------
USER:
I run a bike shop. A customer emailed asking if we can fix their bike
by Saturday. We're pretty busy. Write a reply.

ASSISTANT:
Hi there,

Thanks for getting in touch! We're quite busy at the moment, but we'll
try our best to get your bike fixed by Saturday. Most standard repairs
take 2-3 days, so if you can drop it off by Wednesday we should be able
to have it ready. Let us know what the issue is and we can give you a
better idea.

Cheers,
The Team

WHAT CHANGED / WHAT TO NOTICE:
- It used "busy", the one fact supplied.
- "Most standard repairs take 2-3 days" and "drop it off by Wednesday"
  are invented. They sound like shop policy. They are filler sampled to
  fit the gap.
- Poor context can be worse than none: the reply now reads as specific,
  so it is easier to send without checking.

======================================================================
PROMPT C — SUFFICIENT CONTEXT
----------------------------------------------------------------------
USER:
I run Greenway Bikes. Write a short, friendly email reply to a customer,
Priya, using only the facts below. Do not add any other promises or
times.
- Her email: she has a flat rear tyre and a squeaky chain, and wants the
  bike back by Saturday.
- Our workshop is booked up until Thursday.
- Puncture repairs and chain cleaning are same-day jobs if the bike is
  in by 10 a.m.
- We are open Friday 9 a.m. to 5 p.m. and Saturday 9 a.m. to 1 p.m.
- So: if she drops it off Friday before 10 a.m., it will be ready Friday
  by 5 p.m.
Sign it "Sam, Greenway Bikes".

ASSISTANT:
Hi Priya,

Thanks for getting in touch. Yes, we can have your bike ready before
Saturday. The workshop is fully booked until Thursday, but a puncture
repair and chain clean are same-day jobs. If you drop the bike off on
Friday before 10 a.m., it will be ready to collect by 5 p.m. the same
day. We're also open Saturday from 9 a.m. to 1 p.m. if that's easier for
collection.

Best wishes,
Sam, Greenway Bikes

WHAT CHANGED / WHAT TO NOTICE:
- Every fact in the reply came from the prompt. The model's job shrank
  from "invent a plausible shop" to "phrase these facts".
- It still added one thing: offering Saturday as a collection option.
  That follows from the facts given, but it was not asked for. Check
  every sentence against the facts, even in the good version.
- The improvement came from moving facts from the "inaccessible" circle
  (in the shop owner's head) into the context circle.

Homework

No AI. Write down three questions you might really ask an assistant this week. For each, name the circle the answer depends on. For any that land in the inaccessible circle, say what you would paste into the chat to move the needed facts into context. Then confirm you have your L6 failure log ready for L8.

Exercise: elicit, verify, correct

This is the exercise that ties Unit I together. You will ask an assistant for a substantive answer on a topic, check every claim it makes against authoritative sources provided for you, correct what is wrong, and document the whole trail. There is no grade, but there is a standard, and you will score yourself against it. A submission that finds three errors and records how it found them beats a polished answer with no verification trail.

You will be able to

• Elicit a substantive answer on an assigned topic from a model.
• Verify every checkable claim against an authoritative source and document the result.
• Correct the output and state, in writing, what was wrong and how it was detected.
• Submit a complete AI-use record.

Reading and worked examples

How the exercise works

You need: L08_topic_bank.txt (six topics, each with a prompt and its sources), L08_submission.txt (the template you fill in), your L6 failure log and L7 worksheet for reference, an assistant, a browser, and about an hour.

1. Read the rubric below so you know the standard before you start.
2. Choose a topic: the one you know least about, or roll a die. Knowing the answer already makes the exercise too easy to fake.
3. Fill in Part 1 of the template (your expectations) before sending anything.
4. Send the topic's prompt, word for word, in a new chat. Paste the full answer into Part 2.
5. Verify every checkable claim against the provided sources (Part 3). Record errors (Part 4).
6. Write the corrected product (Part 5), the reflection (Part 6), and the AI-use record (Part 7).
7. Score yourself (Part 8). Only then open the answer key at the end of this lesson.

You are given the sources on purpose. Today the skill is thorough checking.

The rubric

What counts as a checkable claim

A checkable claim is any statement that is either true or false and that a source could settle: a number, a date, a time, a name, a role, a unit, a rule, a step in a procedure, a word like "exactly" or "only" or "all". Opinions ("this is important") and filler ("here is your poster") are not checkable.

Coverage is part of the standard. Watch yourself for the urge to check only what is easy, or only what looks suspicious. Errors hide among plausible claims, delivered in the same tone (L6).

Write the corrected product

The corrected product (Part 5) is what you would be willing to sign for. Every claim in it should be CONFIRMED in your log. Where you could not check something, either cut it or mark it plainly as unchecked. A shorter, correct product beats a longer one with unchecked material.

Exercises

Homework

No AI. Read the L9 notes on decomposition and specification before starting L9. Bring your L8 submission: L9 begins by looking at the patterns that make verification hard.

Decomposition and specification: the method, applied

Most failures you will meet with AI tools are not the model's fault alone. They start with a request that left the important decisions open, so the model filled them with whatever was most likely. This lesson teaches a method for turning a vague problem into a precise one: understand, decompose, specify, execute, verify. Its sharpest tool is the acceptance criterion, a statement that decides whether a result is right. You will write a specification, hand it word for word to an assistant as if to a stranger, and see what your own words actually asked for.

You will be able to

• Decompose an ill-defined problem into stated sub-problems with explicit assumptions.
• Write a specification precise enough that a competent stranger could execute it.
• Write acceptance criteria that determine whether a result is correct.
• Explain why an underspecified request produces a confidently wrong result.

Reading and worked examples

How to work through this lesson

You need L09_problem.txt (the vague problem), L09_spec_template.txt (the worksheet), and an assistant.

The method

Five steps, in order. They are the same whether the one doing the work is a person, a program, or a model.

Verify is the same habit you built in L6 and L8, pointed at a different kind of claim. There, the claims were facts and the authority was a source. Here, the claims are "this result does what was asked", and the authority is your acceptance criteria.

Acceptance criteria

An acceptance criterion is a statement about the result that is either true or false, and that you can check by looking at the result. Together, the criteria define "correct" before anyone does the work.

A good criterion names a specific situation and the specific thing that must be true in it. "The rota is fair" is not a criterion, because two people can disagree about whether it is true. "Nobody appears more than twice in any week" is a criterion: anyone can count.

• Write at least one normal criterion: the ordinary case works.
• Write at least one boundary criterion: the edge, the exception, the limit. Exactly at the threshold, the empty case, the week someone is away. Errors live at boundaries.
• Write at least one format criterion: the result comes back in the shape you can use.
• Prefer fewer precise criteria to many vague ones. Length is not precision.

Why vague requests fail confidently

Recall L5: the model continues text with likely tokens. When your request leaves a decision open, the model does not stop and ask. Many assistants will ask a question sometimes, but you cannot count on it. More often, it fills the gap with whatever is most common in similar text it has seen. The result is fluent and confident, and it reflects typical choices, not yours.

A human executor does the same, more politely. Handed "sort out a fair rota", a capable new colleague makes reasonable guesses. The guesses are only wrong because they are not yours, and you never said what yours were.

That is why the verbatim rule matters in this lesson's exercise. If you repair your specification as you hand it over ("oh, and I meant once a day"), you hide the gap. Giving it word for word, to a reader who cannot ask, shows you exactly what your words did and did not say.

Exercises

SPEC GIVEN VERBATIM:
Make a fair watering rota for the community garden for the summer
using these volunteers:
  Ana - weekdays after 5 pm, but never Wednesdays
  Ben - weekends only
  Chloe - any day, mornings only
  Dev - Mondays, Tuesdays and Thursdays, any time; away for two weeks
        in the middle of July
  Eli - Saturdays
  Fran - any day, but no more than once a week

ASSISTANT:
Here's a fair weekly watering rota for the summer:

  Day        Morning   Evening
  Monday     Chloe     Dev
  Tuesday    Fran      Ana
  Wednesday  Chloe     Ana
  Thursday   Dev       Ana
  Friday     Chloe     Ana
  Saturday   Eli       Fran
  Sunday     Ben       Ben

This rota spreads the work fairly, with each volunteer doing between
two and four shifts per week. Repeat it every week from June to
August. Let me know if you'd like any changes!

CHECKED AGAINST THE ACCEPTANCE CRITERIA IN THE L9 STRONG SPEC
(AC numbers refer to the strong specification in the lesson reveal;
 AC7 and AC8 are not shown because the table has no weeks or totals)
  AC1 one volunteer per day ............ FAIL  Two per day (14 slots).
                                               Spec gap: the request
                                               never said once a day.
  AC2 nobody on an unavailable day ..... FAIL  Ana on Wednesday evening.
                                               Execution error: the
                                               constraint was stated.
  AC3 Fran at most once a week ......... FAIL  Fran on Tuesday and
                                               Saturday. Execution error.
  AC4 Dev absent weeks 7 and 8 ......... FAIL  One repeating week; Dev's
                                               absence ignored. Spec gap:
                                               "middle of July" is not a
                                               week number, and nothing
                                               asked for exceptions.
  AC5 nobody more than 2 per week ...... FAIL  Ana has 4 evenings.
                                               Spec gap: "fair" undefined.
  AC6 one-page table, Week x Day ....... FAIL  Day x Shift table, no
                                               weeks. Spec gap: no format.

  Also note: "each volunteer doing between two and four shifts per
  week" is false for its own table: Eli has one shift. And Fran has
  two, despite her once-a-week limit. The model's summary of its own
  output is a claim to check, like any other.

WHAT TO TAKE FROM IT:
  Of six failures, two are execution errors (stated constraints
  ignored) and four are specification gaps (the request was silent).
  The output is confident and tidy, and the closing summary says it is
  fair. Nothing about its tone reveals the failures; only the criteria
  do.

GOAL
Produce a 13-week watering rota for Riverside Community Garden that the
committee can print on one page.

INPUTS
Volunteers and availability:
  Ana   - Mon, Tue, Thu, Fri; evenings only
  Ben   - Sat, Sun; morning or evening
  Chloe - any day; mornings only
  Dev   - Mon, Tue, Thu; morning or evening; NOT available in weeks 7 and 8
  Eli   - Sat; morning or evening
  Fran  - any day; morning or evening; at most once per week

OUTPUT
One table. Rows are weeks (identical weeks may share a row, e.g.
"1-6, 9-13"). Columns are Mon, Tue, Wed, Thu, Fri, Sat, Sun. Each cell
holds one name and M (morning, before 10 am) or E (evening, after 5 pm).
Below the table: one line per exception to the usual pattern, and one
line giving each volunteer's total waterings over the 13 weeks.

RULES
1. Week 1 starts on a Monday. The rota covers weeks 1 to 13.
2. Exactly one watering per day, by one person, M or E.
3. Nobody is scheduled outside the availability above.
4. Fair means: nobody waters more than twice in any week, and every
   volunteer waters at least once in every week they are available.
5. Add no other advice, notes or tips.

ACCEPTANCE CRITERIA
AC1 Every day of every week 1-13 has exactly one volunteer.
AC2 Nobody appears outside their availability: Ana never on Wed, Sat
    or Sun and never M; Chloe never E; Eli only on Sat; Ben only Sat/Sun;
    Dev only Mon/Tue/Thu.
AC3 Fran appears at most once in every week.
AC4 (boundary) Dev appears in no cell of weeks 7 and 8, and his usual
    days in those weeks are still covered by someone available.
AC5 Nobody appears more than twice in any week.
AC6 (format) Output is a single Week x Day table, short enough to fit
    on one printed page, with the exception and totals lines below it.
AC7 Every volunteer appears at least once in each week they are
    available.
AC8 The totals line matches a count of the table.

Make a fair watering rota for the summer that works for everyone and
doesn't overload anyone. Use the volunteer list. Make sure it is clear,
easy to read, and covers all the days. Remember Dev is away for a bit.

Acceptance criteria:
- The rota is fair.
- Everyone is happy with it.
- It looks professional.
- It covers the summer.

Homework

No AI. Finish section 6 of your worksheet: revise your specification and state, in one sentence, the ambiguity that caused the failure. Keep the worksheet; L13 and L14 build on acceptance criteria written exactly this way.

Python I: reading and running code

Later in this course you will ask AI tools to write code, and you will sign for what they produce. You can only sign for code you can read. This lesson teaches you to run a Python program, read it line by line, predict what it will print, and use an error message to find the line that broke.

You will be able to

• Run a Python program and interpret its output.
• Read an unfamiliar program and state what it does before running it.
• Trace execution line by line and predict the value of a variable at a given point.
• Read an error message and locate the responsible line.

Reading and worked examples

How to work through this lesson

You need the L10 program files (L10_setup_check.py, L10_notes_examples.py, L10_guided_read.py, L10_trace.py, L10_trace_prints.py, the four L10_broken_ files (demo, 1, 2 and 3) and L10_homework_read.py), a text editor and a terminal. Put the files in one folder, for example /home/you/ai-course/L10 (paths differ on your computer).

Work the sections in order. Each activity asks you to write a prediction before you run anything. Write it down; a prediction in your head is too easy to revise after the fact. The reveals titled "Check your answer" hold the answers. Open each one only after you have written yours.

Why read before you write

For the rest of this course you will direct AI tools to write code for you. In L8 you signed for a model's prose answer after checking every claim. Code is the same deal with higher stakes: if you cannot read what the model gave you, you cannot sign for it. In L14 you will test generated code: you write tests from the specification first, then read the code to find out why a test failed and whether you can sign for it.

So these three lessons teach reading first. You will run programs, trace them by hand and read their error messages. You will not write original code in L10. That is on purpose.

What a program is and how to run one

A program is a text file of instructions. Python reads the file from the top and carries out one line at a time, in order, unless a line tells it to repeat or skip something. A Python file name ends in .py.

To run a program, open a terminal in the folder that holds the file (you made your course folder in L2) and type python followed by the file name. On some computers the command is py or python3 instead. Try python --version first; if it is not found, try py --version, then python3 --version. Use whichever prints a version number, and use that same word every time this course says python.

python L10_notes_examples.py

Output is whatever the program prints to the terminal. Output is evidence of what the program did. It is not the program itself, and a program can print something that looks right while doing something wrong.

# L10 setup check. Run this once before you start the lesson.
# It checks two things: your Python version, and that Python can
# create, write, read and delete a small file in this folder.
# After the version line, every check line starts with PASS or FAIL.

import sys
from pathlib import Path

print("Python version:", sys.version.split()[0])

if sys.version_info >= (3, 11):
    print("PASS  Python is 3.11 or newer")
else:
    print("FAIL  Python is older than 3.11. Repeat the install step from L1.")

test_file = Path("L10_setup_test.txt")
message = "setup check"
all_good = True

try:
    test_file.write_text(message, encoding="utf-8")
    print("PASS  created and wrote", test_file.name)
except OSError as problem:
    print("FAIL  could not create or write a file here:", problem)
    all_good = False

if all_good:
    try:
        text_back = test_file.read_text(encoding="utf-8")
        if text_back == message:
            print("PASS  read the file back and the text matched")
        else:
            print("FAIL  read the file back but the text did not match")
            all_good = False
    except OSError as problem:
        print("FAIL  could not read the file:", problem)
        all_good = False

if all_good:
    try:
        test_file.unlink()
        print("PASS  deleted", test_file.name)
    except OSError as problem:
        print("FAIL  could not delete the file:", problem)
        all_good = False

if all_good and sys.version_info >= (3, 11):
    print("RESULT: PASS. Your computer is ready for L10.")
else:
    print("RESULT: FAIL. See the fix table in the L10 notes before going on.")

Python version: 3.13.16
PASS  Python is 3.11 or newer
PASS  created and wrote L10_setup_test.txt
PASS  read the file back and the text matched
PASS  deleted L10_setup_test.txt
RESULT: PASS. Your computer is ready for L10.

Variables and print

A variable is a name for a value. The line orders_received = 112 means: from now on, the name orders_received stands for 112. The = sign is an instruction to store, not a statement that two things are equal.

print(...) writes its contents to the output. Text inside quotes is printed as written. A name without quotes is replaced by its current value. Commas separate items, and Python puts a space between them.

A name can get a new value later. When you read a line like x = x - 3, work out the right side first using the old value, then store the result under the name.

# Worked examples for the L10 reading-code notes.

# Example 1: variables and print
warehouse = "Northgate depot"
orders_received = 112
orders_cancelled = 7
orders_to_pack = orders_received - orders_cancelled
print("Warehouse:", warehouse)
print("Orders to pack:", orders_to_pack)

# Example 2: a name can be given a new value
orders_to_pack = orders_to_pack - 3
print("After 3 are packed:", orders_to_pack)

Warehouse: Northgate depot
Orders to pack: 105
After 3 are packed: 102

Reading line by line: repeat and choose

Two kinds of lines change the top-to-bottom order. Indented lines (four spaces in) belong to the line above them that ends in a colon.

• for lap in range(1, 4): repeats the indented lines once for each number from 1 up to, but not including, 4. So lap is 1, then 2, then 3.
• if temperature > 30: runs the indented lines only when the test is true. else: runs its lines only when the test is false. Exactly one of the two runs.
• while pallets > 0: checks the test, runs the indented lines, then checks again. It stops the first time the test is false. Something inside the loop must change, or it never stops.

The tests after if and while use a few symbols and words that L11 explains properly. You only need to recognise them in this lesson. Here is what each one means when you read it.

# Example 3: a for loop over range
for lap in range(1, 4):
    print("Lap", lap)

# Example 4: a choice with if / else
temperature = 34
if temperature > 30:
    print("Heat warning: water break every 20 minutes.")
else:
    print("Normal conditions.")

# Example 5: a while loop that stops when its condition is False
pallets = 3
while pallets > 0:
    print("Loading pallet. Pallets left before this one:", pallets)
    pallets = pallets - 1
print("Truck loaded.")

Lap 1
Lap 2
Lap 3
Heat warning: water break every 20 minutes.
Loading pallet. Pallets left before this one: 3
Loading pallet. Pallets left before this one: 2
Loading pallet. Pallets left before this one: 1
Truck loaded.

Reading a traceback

When Python hits a line it cannot carry out, it stops and prints a traceback. Everything printed before it still happened. Nothing after that line runs.

1. Read the last line first. It names the kind of error and gives a short message.
2. Then read the File ..., line N line just above the code. That is the line Python was on when it stopped.
3. Look at the code shown under it. The marks (^^^ or ~~^~~) point at the part of the line that failed.
4. Ask: is the mistake on this line, or did an earlier line set up a bad value that only broke here?

1  # Notes example: a program that stops with an error.
2
3  width_m = 11
4  length_m = 15
5  print("Width:", width_m)
6  print("Length:", lenght_m)
7  print("This line never runs.")

Width: 11
Traceback (most recent call last):
  File "/home/you/ai-course/L10/L10_broken_demo.py", line 6, in <module>
    print("Length:", lenght_m)
                     ^^^^^^^^
NameError: name 'lenght_m' is not defined. Did you mean: 'length_m'?

Exercises

 1  # Budget plan for a four-phase home renovation.
 2  # All numbers are invented for practice.
 3
 4  start_budget = 9000      # dollars available at the start
 5  permit_fees = 400        # dollars paid before any work begins
 6  phase_cost = 1500        # dollars a normal phase costs
 7  kitchen_cost = 2100      # dollars the kitchen phase costs
 8  reserve = 2500           # plan to finish with at least this much
 9
10  budget = start_budget - permit_fees
11  print("Budget after permits:", budget)
12
13  for phase in range(1, 5):
14      if phase == 3:
15          cost = kitchen_cost
16      else:
17          cost = phase_cost
18      budget = budget - cost
19      print("After phase", phase, "budget is", budget)
20
21  margin = budget - reserve
22  if margin >= 0:
23      print("Plan is good. Margin above reserve:", margin)
24  else:
25      print("Plan busts reserve by", -margin, "dollars")

Budget after permits: 8600
After phase 1 budget is 7100
After phase 2 budget is 5600
After phase 3 budget is 3500
After phase 4 budget is 2000
Plan busts reserve by 500 dollars

 1  # Hours on one rental floor sander since its last service.
 2  # Each job adds 3 running hours. At 10 hours or more,
 3  # the shop services it and the count resets.
 4  # All numbers are invented for practice.
 5
 6  hours_since_service = 6
 7  services_done = 0
 8
 9  for job in range(1, 7):
10      hours_since_service = hours_since_service + 3
11      if hours_since_service >= 10:
12          services_done = services_done + 1
13          hours_since_service = 0
14
15  print("Services done:", services_done)
16  print("Hours since last service:", hours_since_service)

CHECK start: hours_since_service = 6  services_done = 0
CHECK job 1 after adding 3: hours_since_service = 9
CHECK end of job 1 - hours_since_service = 9  services_done = 0
CHECK job 2 after adding 3: hours_since_service = 12
CHECK job 2 service done: services_done = 1
CHECK end of job 2 - hours_since_service = 0  services_done = 1
CHECK job 3 after adding 3: hours_since_service = 3
CHECK end of job 3 - hours_since_service = 3  services_done = 1
CHECK job 4 after adding 3: hours_since_service = 6
CHECK end of job 4 - hours_since_service = 6  services_done = 1
CHECK job 5 after adding 3: hours_since_service = 9
CHECK end of job 5 - hours_since_service = 9  services_done = 1
CHECK job 6 after adding 3: hours_since_service = 12
CHECK job 6 service done: services_done = 2
CHECK end of job 6 - hours_since_service = 0  services_done = 2
Services done: 2
Hours since last service: 0

 1  # Delivery count for one week. All numbers invented.
 2
 3  monday_deliveries = 4
 4  tuesday_deliveries = 6
 5  wednesday_deliveries = 5
 6
 7  delivery_count = monday_deliveries + tuesday_deliveries + wednesday_deliveries
 8  print("Deliveries so far this week:", delivery_count)
 9
10  goal = 20
11  remaining = goal - delivery_cout
12  print("Deliveries still needed:", remaining)

Deliveries so far this week: 15
Traceback (most recent call last):
  File "/home/you/ai-course/L10/L10_broken_1.py", line 11, in <module>
    remaining = goal - delivery_cout
                       ^^^^^^^^^^^^^
NameError: name 'delivery_cout' is not defined. Did you mean: 'delivery_count'?

 1  # Average hours per volunteer. All numbers invented.
 2
 3  total_hours = 126
 4  volunteers_signed_up = 9
 5  volunteers_cancelled = 9
 6
 7  volunteers_present = volunteers_signed_up - volunteers_cancelled
 8  print("Volunteers present this week:", volunteers_present)
 9
10  hours_each = total_hours / volunteers_present
11  print("Average hours per volunteer:", hours_each)

Volunteers present this week: 0
Traceback (most recent call last):
  File "/home/you/ai-course/L10/L10_broken_2.py", line 10, in <module>
    hours_each = total_hours / volunteers_present
                 ~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~
ZeroDivisionError: division by zero

 1  # Stock left after three store deliveries. All numbers invented.
 2
 3  start_stock = 8000
 4  boxes_per_delivery = "1800"
 5  deliveries = 3
 6
 7  print("Starting stock:", start_stock)
 8  print("Boxes per delivery:", boxes_per_delivery)
 9
10  stock = start_stock
11  for delivery in range(1, deliveries + 1):
12      stock = stock - boxes_per_delivery
13      print("After delivery", delivery, "stock is", stock)

Starting stock: 8000
Boxes per delivery: 1800
Traceback (most recent call last):
  File "/home/you/ai-course/L10/L10_broken_3.py", line 12, in <module>
    stock = stock - boxes_per_delivery
            ~~~~~~^~~~~~~~~~~~~~~~~~~~
TypeError: unsupported operand type(s) for -: 'int' and 'str'

Homework

Read L10_homework_read.py (40 lines). Write exactly three sentences on what it does. Say what problem it solves, how it works at a high level, and what result it reaches with these numbers. Describe the job, not the syntax.

 1  # Water plan for a seven-day volunteer trail-building camp.
 2  # All numbers are invented for practice.
 3  # Read it. Do not change it.
 4
 5  volunteers = 48
 6  water_on_hand = 1500       # liters on hand at the start of day 1
 7  resupply_liters = 900      # liters each resupply truck brings
 8  days_between_trucks = 3    # a truck arrives after every 3 days
 9  camp_days = 7
10
11  day = 1
12  temperature = 22           # degrees C on day 1
13  days_since_truck = 0
14  ran_short = False
15
16  while day <= camp_days and not ran_short:
17      if temperature >= 30:
18          liters_each = 6
19      elif temperature >= 26:
20          liters_each = 5
21      else:
22          liters_each = 4
23      used_today = volunteers * liters_each
24      water_on_hand = water_on_hand - used_today
25      print("Day", day, "temp", temperature, "used", used_today, "left", water_on_hand)
26      if water_on_hand < 0:
27          ran_short = True
28          print("Water runs out on day", day)
29      days_since_truck = days_since_truck + 1
30      if days_since_truck == days_between_trucks:
31          water_on_hand = water_on_hand + resupply_liters
32          days_since_truck = 0
33          print("Truck arrives. Water now", water_on_hand)
34      temperature = temperature + 2
35      day = day + 1
36
37  if ran_short:
38      print("Plan fails. Add water or trucks.")
39  else:
40      print("Plan works. Water left at end:", water_on_hand)

15. Your three sentences.
16. Did you run the program after writing your answer? If so, did it change your answer?

Day 1 temp 22 used 192 left 1308
Day 2 temp 24 used 192 left 1116
Day 3 temp 26 used 240 left 876
Truck arrives. Water now 1776
Day 4 temp 28 used 240 left 1536
Day 5 temp 30 used 288 left 1248
Day 6 temp 32 used 288 left 960
Truck arrives. Water now 1860
Day 7 temp 34 used 288 left 1572
Plan works. Water left at end: 1572

Python II: types and control flow

Many bugs you will meet in this unit come down to one of two things: a value of the wrong type, or a loop or branch that does something other than what you assumed. This lesson teaches you to predict what each type allows, which branch of an if will run, and exactly when a loop stops.

You will be able to

• Distinguish integers, floats, strings and Booleans, and predict the result of mixing them.
• Trace a conditional and state which branch executes and why.
• Trace a loop and state its termination condition.
• Identify the type error in a program from its traceback alone.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer each from memory, then open the reveal.

1. A traceback ends with TypeError and says Python stopped on line 12. Is line 12 where the mistake is? (L10)
2. Rewrite "the program should give the right answer" as an acceptance criterion you could check. (L9)
3. A model is asked something it has no information about. Why does it usually answer confidently anyway? (L5 and L6)

How to work through this lesson

You need the L11 program files in one folder, for example /home/you/ai-course/L11 (paths differ on your computer). Run the setup check from L10 again if you have moved to a new computer. Each activity asks for a written prediction before you run anything. Open each "Check your answer" reveal only after you have written yours.

Types: what kind of value is this?

Every value in Python has a type. The type decides what you are allowed to do with the value. Four types cover nearly everything in this unit.

"7" and 7 look the same when printed. They are different types. One is text; the other is a number. That difference is behind most of the errors you will see this lesson.

# Worked examples for the L11 notes. Each line prints a value
# and its type, so you can check what Python actually made.

print(7, type(7))
print(7.0, type(7.0))
print("7", type("7"))
print(True, type(True))

7 <class 'int'>
7.0 <class 'float'>
7 <class 'str'>
True <class 'bool'>

Mixing types: what Python does

Think of a type as a contract: it says which operations are allowed. When a line breaks the contract, Python stops on that line and names the types involved. That is why a type mistake shows up at one specific line instead of somewhere vague.

print("7 / 2  gives", 7 / 2)
print("7 // 2 gives", 7 // 2)
print("8 / 2  gives", 8 / 2)
print("7 + 2.0 gives", 7 + 2.0)

7 / 2  gives 3.5
7 // 2 gives 3
8 / 2  gives 4.0
7 + 2.0 gives 9.0

print('"5" + "5" gives', "5" + "5")
print('"5" * 3 gives', "5" * 3)
print('int("12") + 5 gives', int("12") + 5)
print('float("12.5") gives', float("12.5"))
print('str(45) + " minutes" gives', str(45) + " minutes")

"5" + "5" gives 55
"5" * 3 gives 555
int("12") + 5 gives 17
float("12.5") gives 12.5
str(45) + " minutes" gives 45 minutes

1  # Notes example: adding a string and an integer.
2
3  shelf_count = "5"
4  print(shelf_count + 5)

Traceback (most recent call last):
  File "/home/you/ai-course/L11/L11_broken_demo_add.py", line 4, in <module>
    print(shelf_count + 5)
          ~~~~~~~~~~~~^~~
TypeError: can only concatenate str (not "int") to str

1  # Notes example: turning text into a whole number.
2
3  print(int("12"))
4  print(int("12.5"))

12
Traceback (most recent call last):
  File "/home/you/ai-course/L11/L11_broken_demo_int.py", line 4, in <module>
    print(int("12.5"))
          ~~~^^^^^^^^
ValueError: invalid literal for int() with base 10: '12.5'

The File path in each traceback is from the computer the output was captured on. Yours will show your own folder. Line numbers and messages match.

print("12 > 9 gives", 12 > 9)
print("12 == 12.0 gives", 12 == 12.0)
print('"12" == 12 gives', "12" == 12)
chairs = 42
plates = 44
print("chairs >= 40 gives", chairs >= 40)
print("plates >= 45 gives", plates >= 45)
print("chairs >= 40 and plates >= 45 gives", chairs >= 40 and plates >= 45)

12 > 9 gives True
12 == 12.0 gives True
"12" == 12 gives False
chairs >= 40 gives True
plates >= 45 gives False
chairs >= 40 and plates >= 45 gives False

Choosing a branch: if, elif, else

An if block tests conditions in order, top to bottom, and runs the first branch whose test is True. It then skips the rest of the block. elif means "else, if". else catches everything left over. At most one branch runs; with an else, exactly one runs.

wind_mph = 18
if wind_mph > 25:
    print("Close the market: wind over 25 mph")
elif wind_mph > 15:
    print("Open with the awnings down: wind 16 to 25 mph")
else:
    print("Open as normal: wind 15 mph or less")

Open with the awnings down: wind 16 to 25 mph

Repeating: for with range, and while

A for loop over range repeats a known number of times. range(1, 4) gives 1, 2, 3. range(3) gives 0, 1, 2: it starts at 0 when you give only one number. In both forms the stop number is never included.

A while loop repeats as long as its test is True. Its termination condition is the moment the test becomes False. Before you trust a while loop, find the line inside it that moves it toward that moment. If no such line exists, it runs forever.

for day in range(1, 4):
    print("Day", day, "of 3")

for count in range(3):
    print("count is", count)

boxes = 3000
while boxes > 0:
    print("Boxes in the warehouse:", boxes)
    boxes = boxes - 1000
print("Warehouse empty. Boxes:", boxes)

Day 1 of 3
Day 2 of 3
Day 3 of 3
count is 0
count is 1
count is 2
Boxes in the warehouse: 3000
Boxes in the warehouse: 2000
Boxes in the warehouse: 1000
Warehouse empty. Boxes: 0

Exercises

1. 2.5
2. 2
3. 3.0
4. 6.0
5. 33
6. 14
7. 77
8. 72
9. True
10. False
11. False
12. True

 1  # Kayak rental wind rule. All limits invented for practice.
 2
 3  wind_mph = 15
 4  beginner_limit = 10
 5  guide_limit = 20
 6  guide_on_trip = True
 7
 8  if wind_mph <= beginner_limit:
 9      print("Beginners may paddle alone")
10  elif guide_on_trip and wind_mph <= guide_limit:
11      print("Guided trips only")
12  else:
13      print("No rentals today")
14  print("Wind was", wind_mph, "mph")

 1  # Time category for a running club's 2-mile time trial. All standards invented.
 2
 3  run_minutes = 12
 4  run_seconds = 0
 5  total_seconds = run_minutes * 60 + run_seconds
 6
 7  if total_seconds < 600:
 8      category = "Gold"
 9  elif total_seconds < 720:
10      category = "Silver"
11  elif total_seconds < 840:
12      category = "Bronze"
13  else:
14      category = "Finisher"
15  print("Run time in seconds:", total_seconds)
16  print("Category:", category)

 1  # Vacation request check. All rules invented for practice.
 2
 3  vacation_days_left = "4"
 4  days_requested = 4
 5  schedule_conflict = False
 6
 7  days_left = int(vacation_days_left)
 8  enough_days = days_requested <= days_left
 9  print("Enough days?", enough_days)
10
11  if schedule_conflict:
12      print("Denied: schedule conflict")
13  elif not enough_days:
14      print("Denied: not enough vacation days")
15  else:
16      print("Approved. Days left after vacation:", days_left - days_requested)

Guided trips only
Wind was 15 mph

Run time in seconds: 720
Category: Bronze

Enough days? True
Approved. Days left after vacation: 0

 1  # Counted loop: boxes shipped across five delivery trips.
 2  # All numbers invented for practice.
 3
 4  boxes_on_hand = 500
 5  boxes_per_trip = 60
 6
 7  for trip in range(1, 6):
 8      boxes_on_hand = boxes_on_hand - boxes_per_trip
 9      print("Trip", trip, "done. Boxes left:", boxes_on_hand)
10
11  print("Delivery day over. Boxes left:", boxes_on_hand)

 1  # Conditional loop: a hose fills a rainwater tank until it is full.
 2  # All numbers invented for practice.
 3
 4  tank_liters = 4000
 5  tank_capacity = 12000
 6  flow_per_minute = 2500
 7  minutes = 0
 8
 9  while tank_liters < tank_capacity:
10      tank_liters = tank_liters + flow_per_minute
11      minutes = minutes + 1
12      print("Minute", minutes, "tank holds", tank_liters)
13
14  print("Turn off the tap after", minutes, "minutes")

Trip 1 done. Boxes left: 440
Trip 2 done. Boxes left: 380
Trip 3 done. Boxes left: 320
Trip 4 done. Boxes left: 260
Trip 5 done. Boxes left: 200
Delivery day over. Boxes left: 200

Minute 1 tank holds 6500
Minute 2 tank holds 9000
Minute 3 tank holds 11500
Minute 4 tank holds 14000
Turn off the tap after 4 minutes

1  # Should print a reminder for each of the 5 days of the
2  # workshop week, numbered Day 1 to Day 5.
3
4  days_in_week = 5
5
6  for day in range(1, days_in_week):
7      print("Day", day, "- unlock the hall and set out chairs")
8
9  print("Workshop week complete")

 1  # Should count down 3-2-1 before a group photo and then print SMILE.
 2  # The count should show 3, 2, 1 and nothing else.
 3
 4  count = 3
 5
 6  while count >= 0:
 7      print("Ready:", count)
 8      count = count - 1
 9
10  print("SMILE")

Day 1 - unlock the hall and set out chairs
Day 2 - unlock the hall and set out chairs
Day 3 - unlock the hall and set out chairs
Day 4 - unlock the hall and set out chairs
Workshop week complete

Ready: 3
Ready: 2
Ready: 1
Ready: 0
SMILE

 1  # Combined quiz and homework score entry check. All numbers invented.
 2
 3  quiz_entry = "52"
 4  homework_entry = 48
 5  minimum = "90"
 6  quiz = int(quiz_entry)
 7  total = quiz + homework_entry
 8  print("Total:", total)
 9  if total >= minimum:
10      print("Meets combined minimum")

 1  # Combined quiz and homework score entry check. All numbers invented.
 2
 3  quiz_entry = "52.0"
 4  homework_entry = 48
 5  minimum = 90
 6  quiz = int(quiz_entry)
 7  total = quiz + homework_entry
 8  print("Total:", total)
 9  if total >= minimum:
10      print("Meets combined minimum")

 1  # Combined quiz and homework score entry check. All numbers invented.
 2
 3  quiz_entry = "52"
 4  homework_entry = "48"
 5  minimum = 90
 6  quiz = int(quiz_entry)
 7  total = quiz + homework_entry
 8  print("Total:", total)
 9  if total >= minimum:
10      print("Meets combined minimum")

 1  # Combined quiz and homework score entry check. All numbers invented.
 2
 3  quiz_entry = "52"
 4  homework_entry = 48
 5  minimum = 90
 6  quiz = int(quiz_entry)
 7  total = quiz + homework_entry
 8  print("Total: " + total)
 9  if total >= minimum:
10      print("Meets combined minimum")

Traceback (most recent call last):
  File "/home/you/ai-course/match/score_entry.py", line 7, in <module>
    total = quiz + homework_entry
            ~~~~~^~~~~~~~~~~~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'str'

Total: 100
Traceback (most recent call last):
  File "/home/you/ai-course/match/score_entry.py", line 9, in <module>
    if total >= minimum:
       ^^^^^^^^^^^^^^^^
TypeError: '>=' not supported between instances of 'int' and 'str'

Traceback (most recent call last):
  File "/home/you/ai-course/match/score_entry.py", line 8, in <module>
    print("Total: " + total)
          ~~~~~~~~~~^~~~~~~
TypeError: can only concatenate str (not "int") to str

Traceback (most recent call last):
  File "/home/you/ai-course/match/score_entry.py", line 6, in <module>
    quiz = int(quiz_entry)
ValueError: invalid literal for int() with base 10: '52.0'

A 2
B -4
C -2
D 2 4
E False
F True
G abababc
H True
I True False False
J False

# Teacher solution for L11 extension parts 2 and 3.
# Both versions print the same lines. Run it to check.

print("PART 2: while loop")
water = 10000
week = 0
while water >= 5000:
    water = water - water * 0.07
    week = week + 1
    print("Week", week, "water", round(water))

print("PART 3: for loop")
water = 10000
for week in range(1, 11):
    water = water - water * 0.07
    print("Week", week, "water", round(water))

PART 2: while loop
Week 1 water 9300
Week 2 water 8649
Week 3 water 8044
Week 4 water 7481
Week 5 water 6957
Week 6 water 6470
Week 7 water 6017
Week 8 water 5596
Week 9 water 5204
Week 10 water 4840
PART 3: for loop
Week 1 water 9300
Week 2 water 8649
Week 3 water 8044
Week 4 water 7481
Week 5 water 6957
Week 6 water 6470
Week 7 water 6017
Week 8 water 5596
Week 9 water 5204
Week 10 water 4840

Homework

L11_homework_modify.py plans a runner's weekly long-run build-up. Modify it so the loop runs one iteration fewer: five weeks instead of six. Every printed line that remains must be exactly what the original printed for that week, and the final line must report the right number of weeks and kilometers.

This is the first time the course asks you to change a program. Open the .py file in your text editor (not a word processor), edit the line, and save it under the same name, keeping the .py ending. L2 warned that Windows hides file extensions: if the editor saves L11_homework_modify.py.txt, Python will not find your program.

 1  # Weekly long-run build-up for a running plan. Each week the distance
 2  # grows by 2 km until the plan ends. All numbers invented for practice.
 3
 4  week = 1
 5  distance_km = 6
 6  total_km = 0
 7
 8  while week <= 6:
 9      total_km = total_km + distance_km
10      print("Week", week, "long run", distance_km, "km, total so far", total_km, "km")
11      distance_km = distance_km + 2
12      week = week + 1
13
14  print("Plan complete after", week - 1, "weeks and", total_km, "km")

Week 1 long run 6 km, total so far 6 km
Week 2 long run 8 km, total so far 14 km
Week 3 long run 10 km, total so far 24 km
Week 4 long run 12 km, total so far 36 km
Week 5 long run 14 km, total so far 50 km
Week 6 long run 16 km, total so far 66 km
Plan complete after 6 weeks and 66 km

25. Paste the line(s) you changed, before and after.
26. Paste your program's full output.
27. In two sentences: why does your change remove exactly one iteration, and why does the last line still report correctly?
28. AI-use record.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (name and version, or "local model")
Date(s):
Prompts:          (paste them, or a link to the conversation)
What I kept:
What I changed:   (and why)
What I verified:  (which claims or results I checked, and against what)

# KEY: correct change. Only the loop condition changed (6 became 5).
# Weekly long-run build-up, stopping one week earlier.

week = 1
distance_km = 6
total_km = 0

while week <= 5:
    total_km = total_km + distance_km
    print("Week", week, "long run", distance_km, "km, total so far", total_km, "km")
    distance_km = distance_km + 2
    week = week + 1

print("Plan complete after", week - 1, "weeks and", total_km, "km")

Week 1 long run 6 km, total so far 6 km
Week 2 long run 8 km, total so far 14 km
Week 3 long run 10 km, total so far 24 km
Week 4 long run 12 km, total so far 36 km
Week 5 long run 14 km, total so far 50 km
Plan complete after 5 weeks and 50 km

# COMMON WRONG CHANGE: start week at 2 instead of changing the condition.
# It runs 5 times, but the week labels and the final count are wrong.

week = 2
distance_km = 6
total_km = 0

while week <= 6:
    total_km = total_km + distance_km
    print("Week", week, "long run", distance_km, "km, total so far", total_km, "km")
    distance_km = distance_km + 2
    week = week + 1

print("Plan complete after", week - 1, "weeks and", total_km, "km")

Week 2 long run 6 km, total so far 6 km
Week 3 long run 8 km, total so far 14 km
Week 4 long run 10 km, total so far 24 km
Week 5 long run 12 km, total so far 36 km
Week 6 long run 14 km, total so far 50 km
Plan complete after 6 weeks and 50 km

Python III: functions and structure

From the next lesson on, you will ask models to write code one function at a time, and then test what comes back. That only works if you can see where one function ends and the next begins, and say what each one must do. This lesson teaches you to read a function's contract without its insides, and to carve a long script into functions with one job each.

You will be able to

• Explain what a function encapsulates and why boundaries matter.
• Read a function signature and state what it requires and returns without reading the body.
• Decompose a long script into functions with stated responsibilities.
• Explain why a function is the natural unit of both testing and generation.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer each from memory, then open the reveal.

1. How many times does for trip in range(1, 6): run its body, and what is the last value of trip? (L11)
2. A program runs without error and prints a sensible-looking number. What does that prove about whether it is correct? (L10)
3. Why does a good set of acceptance criteria include a boundary case, such as a total of exactly $50.00 when the rule says "under $50"? (L9)

How to work through this lesson

You need L12_functions_demo.py, L12_broken_call.py, L12_signatures.py and L12_flat_script.py in one folder, for example /home/you/ai-course/L12 (paths differ on your computer), plus paper and a pen for A3. Read L12_flat_script.py before you start the activities, and do not run it until A3 tells you to.

Functions as black boxes

A function is a named piece of code that takes some inputs, does one job, and hands back a result. You have already used functions you never saw inside: print, int, round, range. You trusted them because you knew what goes in and what comes out. That is what a black box means here.

A function has two parts. The signature is the first line: the function's name, its inputs and what it returns. It is the contract. The body is the indented code below it. It is the implementation, the way the contract is met. This lesson is about that distinction: you can use a function, test it, or ask someone to build it, from the contract alone.

def pounds_to_kilograms(pounds: float) -> float:
    """Convert a weight in pounds to kilograms, rounded to 1 decimal."""
    kilograms = pounds * 0.4536
    return round(kilograms, 1)


suitcase_weight = pounds_to_kilograms(35)
print("Suitcase:", suitcase_weight, "kg")
print("Carry-on:", pounds_to_kilograms(22), "kg")
print("Total:", pounds_to_kilograms(35 + 22), "kg")

Suitcase: 15.9 kg
Carry-on: 10.0 kg
Total: 25.9 kg

Reading a signature without the body

From a signature and docstring alone you should be able to say four things:

1. Inputs: how many, their names, and their types.
2. Output: the return type, and what the value means.
3. Job: what the function does, in one sentence.
4. One thing that could go wrong: an input that is legal by type but makes no sense, a boundary the docstring does not settle, or a value the function cannot handle.

def stock_after_shipments(start_stock: int, boxes_per_shipment: int, shipments: int) -> int:
    """Return boxes left in the warehouse after sending the given number of equal shipments."""
    ...

 1  # Notes example: an error raised inside a function.
 2  # All numbers are invented for practice.
 3
 4  def hours_each(total_hours: int, volunteers: int) -> float:
 5      """Return the average hours per volunteer, rounded to 1 decimal."""
 6      average = total_hours / volunteers
 7      return round(average, 1)
 8
 9
10  print("Week 1:", hours_each(126, 9))
11  print("Week 2:", hours_each(98, 0))
12  print("This line never runs.")

Week 1: 14.0
Traceback (most recent call last):
  File "/home/you/ai-course/L12/L12_broken_call.py", line 11, in <module>
    print("Week 2:", hours_each(98, 0))
                     ~~~~~~~~~~^^^^^^^
  File "/home/you/ai-course/L12/L12_broken_call.py", line 6, in hours_each
    average = total_hours / volunteers
              ~~~~~~~~~~~~^~~~~~~~~~~~
ZeroDivisionError: division by zero

One function, one job

A good function does one thing you can state in one sentence without the word "and". "Convert a count of rides into points" is one job. "Score the rides and print the line and update the total" is three jobs in one box. When a function has several jobs you cannot test one without the others, and you cannot ask someone to build one part of it.

A long script usually holds several jobs side by side. Decomposition means finding those jobs and giving each its own function. You decompose by responsibility, not by length. Splitting a script every ten lines gives you functions you cannot describe, cannot test and cannot specify.

# Part 2: a list is one name for several values, in order.
team = ["Abara", "Brandt", "Castillo"]
print("Team size:", len(team))
print("First on the list:", team[0])
print("Last on the list:", team[2])

# Part 3: a list can hold rows, and each row is itself a list.
roster = [
    ["Ana Abara", 52],
    ["Ben Brandt", 38],
]
for row in roster:
    print(row[0], "sold", row[1], "raffle tickets")

Team size: 3
First on the list: Abara
Last on the list: Castillo
Ana Abara sold 52 raffle tickets
Ben Brandt sold 38 raffle tickets

Why the function is the unit you specify, generate and test

In L9 you wrote specifications with acceptance criteria: statements that decide whether a result is correct. A function signature plus its docstring is a small specification. Add acceptance criteria and you have everything a stranger, or a model, needs to build it.

• Specify: a function has defined inputs and a defined output, so you can write criteria such as "ride_points(45) returns 16".
• Generate: in L13 you will ask a model for one function at a time. A request for a whole program is too large to read or check in one sitting.
• Test: in L14 you will turn acceptance criteria into tests and run them against a function before reading its code. You can only do that if the function has a clear contract.

Exercises

 1  # Six function signatures with no bodies. Each body is "..." so
 2  # the file still runs, but none of these functions does anything.
 3  # Read the name, parameters, type hints, return type and docstring.
 4  # All rules described here are invented for practice.
 5
 6
 7  def overtime_hours_remaining(hours_worked: float, hour_limit: float) -> float:
 8      """Return how many more hours an employee may work this month."""
 9      ...
10
11
12  def is_certification_current(days_since_course: int, renewal_window_days: int) -> bool:
13      """Return True if the last first-aid course falls inside the renewal window."""
14      ...
15
16
17  def stock_after_shipments(start_stock: int, boxes_per_shipment: int, shipments: int) -> int:
18      """Return boxes left in the warehouse after sending the given number of equal shipments."""
19      ...
20
21
22  def parse_run_time(run_time: str) -> int:
23      """Convert a run time written as "MM:SS" into total seconds."""
24      ...
25
26
27  def badge_label(role: str, last_name: str) -> str:
28      """Return a name-badge label such as "VOLUNTEER SMITH" from a role and a last name."""
29      ...
30
31
32  def average_score(scores: list[int]) -> float:
33      """Return the mean of a list of quiz scores."""
34      ...
35
36
37  print("Signatures loaded. Nothing ran, because every body is '...'.")
38  print("Calling one anyway gives:", stock_after_shipments(9000, 1500, 4))

Signatures loaded. Nothing ran, because every body is '...'.
Calling one anyway gives: None

 1  # Scores a cycling club's season challenge and prints a report.
 2  # Scoring tables and members are invented for practice.
 3  # Each row: name, rides completed, climbs completed, 5 km time trial in seconds.
 4  roster = [
 5      ["Ana Abara", 52, 55, 640],
 6      ["Ben Brandt", 38, 47, 702],
 7      ["Cruz Castillo", 61, 58, 588],
 8      ["Dee Dunmore", 27, 50, 755],
 9      ["Eli Esposito", 45, 39, 690],
10  ]
11  passed = 0
12  total_of_all_scores = 0
13  best_name = ""
14  best_score = -1
15  print("SEASON CHALLENGE REPORT")
16  print("-----------------------")
17  for row in roster:
18      name = row[0]
19      rides = row[1]
20      climbs = row[2]
21      trial_seconds = row[3]
22      if rides >= 60:
23          ride_points = 20
24      elif rides >= 45:
25          ride_points = 16
26      elif rides >= 30:
27          ride_points = 12
28      else:
29          ride_points = 0
30      if climbs >= 58:
31          climb_points = 20
32      elif climbs >= 48:
33          climb_points = 16
34      elif climbs >= 40:
35          climb_points = 12
36      else:
37          climb_points = 0
38      if trial_seconds < 600:
39          trial_points = 60
40      elif trial_seconds < 660:
41          trial_points = 52
42      elif trial_seconds < 720:
43          trial_points = 44
44      else:
45          trial_points = 0
46      score = ride_points + climb_points + trial_points
47      if ride_points == 0 or climb_points == 0 or trial_points == 0:
48          result = "FAIL (missed a minimum)"
49      elif score >= 90:
50          result = "PASS - Excellent"
51      elif score >= 75:
52          result = "PASS"
53      else:
54          result = "FAIL (score under 75)"
55      print(name, "| rides", ride_points, "| climbs", climb_points,
56            "| time trial", trial_points, "| total", score, "|", result)
57      if result == "PASS" or result == "PASS - Excellent":
58          passed = passed + 1
59      total_of_all_scores = total_of_all_scores + score
60      if score > best_score:
61          best_score = score
62          best_name = name
63  print("-----------------------")
64  print("Passed:", passed, "of", len(roster))
65  print("Club average score:", round(total_of_all_scores / len(roster), 1))
66  print("Top score:", best_name, "with", best_score)

# Reference decomposition of L12_flat_script.py.
# Same job, same output, split into functions by responsibility.
# Each function's docstring is its one-sentence responsibility.

ROSTER = [
    ["Ana Abara", 52, 55, 640],
    ["Ben Brandt", 38, 47, 702],
    ["Cruz Castillo", 61, 58, 588],
    ["Dee Dunmore", 27, 50, 755],
    ["Eli Esposito", 45, 39, 690],
]


def ride_points(rides: int) -> int:
    """Convert a count of rides completed into points from the rides table."""
    if rides >= 60:
        return 20
    elif rides >= 45:
        return 16
    elif rides >= 30:
        return 12
    else:
        return 0


def climb_points(climbs: int) -> int:
    """Convert a count of climbs completed into points from the climbs table."""
    if climbs >= 58:
        return 20
    elif climbs >= 48:
        return 16
    elif climbs >= 40:
        return 12
    else:
        return 0


def trial_points(trial_seconds: int) -> int:
    """Convert a 5 km time-trial time in seconds into points from the time-trial table."""
    if trial_seconds < 600:
        return 60
    elif trial_seconds < 660:
        return 52
    elif trial_seconds < 720:
        return 44
    else:
        return 0


def result_label(ride_pts: int, climb_pts: int, trial_pts: int) -> str:
    """Decide the pass/fail label from the three component points."""
    score = ride_pts + climb_pts + trial_pts
    if ride_pts == 0 or climb_pts == 0 or trial_pts == 0:
        return "FAIL (missed a minimum)"
    elif score >= 90:
        return "PASS - Excellent"
    elif score >= 75:
        return "PASS"
    else:
        return "FAIL (score under 75)"


def is_pass(result: str) -> bool:
    """Say whether a result label counts as a pass."""
    return result == "PASS" or result == "PASS - Excellent"


def print_member_line(name: str, ride_pts: int, climb_pts: int,
                      trial_pts: int, score: int, result: str) -> None:
    """Print one member's line of the report."""
    print(name, "| rides", ride_pts, "| climbs", climb_pts,
          "| time trial", trial_pts, "| total", score, "|", result)


def print_summary(passed: int, member_count: int, total_of_all_scores: int,
                  best_name: str, best_score: int) -> None:
    """Print the club summary lines at the bottom of the report."""
    print("-----------------------")
    print("Passed:", passed, "of", member_count)
    print("Club average score:", round(total_of_all_scores / member_count, 1))
    print("Top score:", best_name, "with", best_score)


def score_club(roster: list) -> None:
    """Score every member on the roster and print the full report."""
    passed = 0
    total_of_all_scores = 0
    best_name = ""
    best_score = -1
    print("SEASON CHALLENGE REPORT")
    print("-----------------------")
    for row in roster:
        name = row[0]
        r_pts = ride_points(row[1])
        c_pts = climb_points(row[2])
        t_pts = trial_points(row[3])
        score = r_pts + c_pts + t_pts
        result = result_label(r_pts, c_pts, t_pts)
        print_member_line(name, r_pts, c_pts, t_pts, score, result)
        if is_pass(result):
            passed = passed + 1
        total_of_all_scores = total_of_all_scores + score
        if score > best_score:
            best_score = score
            best_name = name
    print_summary(passed, len(roster), total_of_all_scores, best_name, best_score)


score_club(ROSTER)

SEASON CHALLENGE REPORT
-----------------------
Ana Abara | rides 16 | climbs 16 | time trial 52 | total 84 | PASS
Ben Brandt | rides 12 | climbs 12 | time trial 44 | total 68 | FAIL (score under 75)
Cruz Castillo | rides 20 | climbs 20 | time trial 60 | total 100 | PASS - Excellent
Dee Dunmore | rides 0 | climbs 16 | time trial 0 | total 16 | FAIL (missed a minimum)
Eli Esposito | rides 16 | climbs 0 | time trial 44 | total 60 | FAIL (missed a minimum)
-----------------------
Passed: 2 of 5
Club average score: 65.6
Top score: Cruz Castillo with 100

# ACCEPTABLE ALTERNATIVE decomposition of L12_flat_script.py.
# Different shape from the reference: score everyone first, then
# print. Every function still has a one-sentence responsibility.

ROSTER = [
    ["Ana Abara", 52, 55, 640],
    ["Ben Brandt", 38, 47, 702],
    ["Cruz Castillo", 61, 58, 588],
    ["Dee Dunmore", 27, 50, 755],
    ["Eli Esposito", 45, 39, 690],
]


def table_points(value: int, cutoffs: list, points: list) -> int:
    """Return the points for the first cutoff the value reaches, else 0."""
    for i in range(len(cutoffs)):
        if value >= cutoffs[i]:
            return points[i]
    return 0


def trial_points(trial_seconds: int) -> int:
    """Convert a time-trial time into points; faster (smaller) times score higher."""
    if trial_seconds < 600:
        return 60
    elif trial_seconds < 660:
        return 52
    elif trial_seconds < 720:
        return 44
    else:
        return 0


def score_member(row: list) -> list:
    """Turn one roster row into [name, rides, climbs, trial, total, result]."""
    r = table_points(row[1], [60, 45, 30], [20, 16, 12])
    c = table_points(row[2], [58, 48, 40], [20, 16, 12])
    t = trial_points(row[3])
    total = r + c + t
    if r == 0 or c == 0 or t == 0:
        result = "FAIL (missed a minimum)"
    elif total >= 90:
        result = "PASS - Excellent"
    elif total >= 75:
        result = "PASS"
    else:
        result = "FAIL (score under 75)"
    return [row[0], r, c, t, total, result]


def print_report(scored: list) -> None:
    """Print the full report for a list of scored members."""
    print("SEASON CHALLENGE REPORT")
    print("-----------------------")
    passed = 0
    total_of_all_scores = 0
    best_name = ""
    best_score = -1
    for m in scored:
        print(m[0], "| rides", m[1], "| climbs", m[2],
              "| time trial", m[3], "| total", m[4], "|", m[5])
        if m[5] == "PASS" or m[5] == "PASS - Excellent":
            passed = passed + 1
        total_of_all_scores = total_of_all_scores + m[4]
        if m[4] > best_score:
            best_score = m[4]
            best_name = m[0]
    print("-----------------------")
    print("Passed:", passed, "of", len(scored))
    print("Club average score:", round(total_of_all_scores / len(scored), 1))
    print("Top score:", best_name, "with", best_score)


scored_members = []
for row in ROSTER:
    scored_members.append(score_member(row))
print_report(scored_members)

# UNACCEPTABLE decomposition of L12_flat_script.py: split by line
# count, not by responsibility. It runs and prints the right report,
# and it is still wrong. None of these functions can be described in
# one sentence without the word "and", only part_two takes an input,
# none returns a result, and none can be tested on its own.

roster = [
    ["Ana Abara", 52, 55, 640],
    ["Ben Brandt", 38, 47, 702],
    ["Cruz Castillo", 61, 58, 588],
    ["Dee Dunmore", 27, 50, 755],
    ["Eli Esposito", 45, 39, 690],
]
state = {}


def part_one():
    state["passed"] = 0
    state["total"] = 0
    state["best_name"] = ""
    state["best_score"] = -1
    print("SEASON CHALLENGE REPORT")
    print("-----------------------")


def part_two(row):
    state["name"] = row[0]
    rides = row[1]
    climbs = row[2]
    if rides >= 60:
        state["r"] = 20
    elif rides >= 45:
        state["r"] = 16
    elif rides >= 30:
        state["r"] = 12
    else:
        state["r"] = 0
    if climbs >= 58:
        state["c"] = 20
    elif climbs >= 48:
        state["c"] = 16
    elif climbs >= 40:
        state["c"] = 12
    else:
        state["c"] = 0
    state["trial_seconds"] = row[3]


def part_three():
    trial_seconds = state["trial_seconds"]
    if trial_seconds < 600:
        state["t"] = 60
    elif trial_seconds < 660:
        state["t"] = 52
    elif trial_seconds < 720:
        state["t"] = 44
    else:
        state["t"] = 0
    state["score"] = state["r"] + state["c"] + state["t"]
    if state["r"] == 0 or state["c"] == 0 or state["t"] == 0:
        state["result"] = "FAIL (missed a minimum)"
    elif state["score"] >= 90:
        state["result"] = "PASS - Excellent"
    elif state["score"] >= 75:
        state["result"] = "PASS"
    else:
        state["result"] = "FAIL (score under 75)"


def part_four():
    print(state["name"], "| rides", state["r"], "| climbs", state["c"],
          "| time trial", state["t"], "| total", state["score"], "|", state["result"])
    if state["result"] == "PASS" or state["result"] == "PASS - Excellent":
        state["passed"] = state["passed"] + 1
    state["total"] = state["total"] + state["score"]
    if state["score"] > state["best_score"]:
        state["best_score"] = state["score"]
        state["best_name"] = state["name"]


def part_five():
    print("-----------------------")
    print("Passed:", state["passed"], "of", len(roster))
    print("Club average score:", round(state["total"] / len(roster), 1))
    print("Top score:", state["best_name"], "with", state["best_score"])


part_one()
for row in roster:
    part_two(row)
    part_three()
    part_four()
part_five()

Homework

Choose two functions from your A3 decomposition. For each, fill the template below. Acceptance criteria must be checkable: a specific input and the exact result. Cover a normal case, every boundary in the rules, and at least one input the function must handle carefully.

Function: <name>(<param>: <type>, ...) -> <type>
Responsibility: <one sentence>

Criteria (input -> required result):
  1. Normal:   <call>  ->  <exact value>
  2. Boundary: <call>  ->  <exact value>
  3. Boundary: <call>  ->  <exact value>
  4. ...
Not covered / open question: <anything the rules do not settle>

16. Function 1: completed template.
17. Function 2: completed template.

Function: ride_points(rides: int) -> int
Responsibility: Convert a count of rides completed into points from the rides table.

Criteria (input -> required result):
  1. Normal:   rides=52 -> 16
  2. Boundary: rides=60 -> 20 ; rides=59 -> 16
  3. Boundary: rides=45 -> 16 ; rides=44 -> 12
  4. Boundary: rides=30 -> 12 ; rides=29 -> 0
  5. Zero:     rides=0  -> 0
Not covered / open question: a negative count is impossible in real life;
the table does not say what to return. Ask before building.

Function: result_label(ride_pts: int, climb_pts: int, trial_pts: int) -> str
Responsibility: Decide the pass/fail label from the three component points.

Criteria (input -> required result):
  1. Missed minimum: (0, 20, 60)  -> "FAIL (missed a minimum)"
  2. Missed minimum: (20, 20, 0)  -> "FAIL (missed a minimum)"
  3. Boundary 90:    (10, 20, 60) -> "PASS - Excellent"
  4. Boundary 90:    (16, 20, 53) -> "PASS"   (total 89)
  5. Boundary 75:    (15, 16, 44) -> "PASS"   (total 75)
  6. Boundary 75:    (14, 16, 44) -> "FAIL (score under 75)"   (total 74)
Not covered / open question: 10, 53, 15 and 14 are not real table values.
The criteria test the label rule on its own, which is the point.

Function: ride_points
Responsibility: Gives the right points for rides.

Criteria:
  1. It should work for normal numbers.
  2. It should handle high and low counts correctly.
  3. It should not crash.

PASS  ride_points(60) == 20
PASS  ride_points(59) == 16
PASS  ride_points(45) == 16
PASS  ride_points(44) == 12
PASS  ride_points(30) == 12
PASS  ride_points(29) == 0
PASS  ride_points(0) == 0
PASS  result_label(0, 20, 60) is a minimum FAIL
PASS  result_label(20, 20, 0) is a minimum FAIL
PASS  result_label(10, 20, 60) totals 90: Excellent
PASS  result_label(16, 20, 53) totals 89: PASS
PASS  result_label(15, 16, 44) totals 75: PASS
PASS  result_label(14, 16, 44) totals 74: FAIL
Checks run: 13  Failures: 0

Directing a model to produce code: constraints and acceptance criteria

You will spend the rest of this course directing models to write code you then sign for. This lesson shows that what comes back is decided by what you specify, not by how you word it. You will send a vague request and a precise one for the same small function, predict how the vague one fails, and compare both results against the acceptance criteria. For homework you write your own specification.

You will be able to

• Write a generation request that states inputs, outputs, constraints and acceptance criteria.
• Predict how an underspecified request will fail before sending it.
• Compare outputs from a vague and a precise request for the same task.
• Explain why the specification, not the phrasing, determines the result.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer from memory, then open the reveal.

1. L9: name the five steps of the method, in order.
2. L9: what makes "nobody appears more than twice in any week" a usable acceptance criterion when "the rota is fair" is not?
3. L12: why is a function, rather than a whole program, the natural thing to specify and test?

How to work through this lesson

You need L13_example_fuel.py and L13_example_fuel_precise.py (the two worked examples), L13_task_cards.txt, L13_request_template.txt, and any AI chat assistant. If you cannot use an assistant, the six L13_ref_task<N>_*.py files stand in for its replies; A3 says how to use them. A weaker or local model often makes the difference between the two requests easier to see, so you do not need the best one you can find.

This is L9 pointed at a machine

In L9 you wrote a specification and handed it, word for word, to an assistant that could not ask you questions. The gaps in your specification came back as wrong answers. In this lesson you do the same thing on purpose, with code as the product.

This lesson teaches nothing new about AI. The method is the one you already have: understand, decompose, specify, execute, verify. In L12 you learned that a function is the right size of thing to specify. Here you specify one function at a time and direct a model to write it.

Anatomy of a generation request

A generation request for a function has five parts. Each part answers a question the model would otherwise answer for you, by guessing.

The last two parts are the ones people leave out, and they are the ones that matter most. Acceptance criteria are how you will judge the output; you wrote them in L9 and L12. Boundary behaviour is where code fails: midnight, zero, exactly-the-limit, an empty input.

Write the acceptance criteria as calls with exact answers. "It should handle midnight" is a wish. "zulu_to_local("2200", 3) returns "0100"" is a criterion anyone can check in ten seconds.

Worked example 1: the vague request

# L13 worked example 1. This is the kind of function a model might return
# for the vague request "write a function to work out fuel remaining"
# (written for this lesson; a real model's output will differ).
# Predict the first line of output, then run it. Compare the output with
# the precise specification in the notes.


def fuel_remaining(start_fuel, burn_rate, time_flown):
    """Calculate remaining fuel."""
    used = burn_rate * time_flown
    return start_fuel - used


# The caller meant: 6000 lb at start, 1800 lb per hour, 40 minutes flown.
print(fuel_remaining(6000, 1800, 40))

# The same flight, but the caller passes hours instead of minutes.
print(fuel_remaining(6000, 1800, 40 / 60))

# A long flight. Fuel cannot go below zero in real life.
print(fuel_remaining(6000, 1800, 4))

-66000
4800.0
-1200

Worked example 2: the full specification

Write a Python 3 function fuel_remaining_lb(start_fuel_lb,
burn_rate_lb_per_hr, minutes_flown).
Inputs: start fuel in pounds (>= 0), burn rate in pounds per HOUR (>= 0),
time flown in MINUTES (>= 0). Numbers may be int or float.
Output: fuel remaining in pounds, a number. Never below 0.
Constraints: standard library only. No printing, no input().
Boundary: if the fuel would be negative, return 0.
Invalid input: raise ValueError if any input is negative.
Acceptance criteria:
  AC1 fuel_remaining_lb(6000, 1800, 40) returns 4800.0
  AC2 fuel_remaining_lb(6000, 1800, 240) returns 0
  AC3 fuel_remaining_lb(6000, 1800, 0) returns 6000.0
  AC4 fuel_remaining_lb(6000, 1800, -10) raises ValueError

# L13 worked example 2. An example of what a model might return for the
# FULL specification of the same fuel function (written for this lesson;
# a real model's output will differ). The acceptance checks at the bottom
# were added afterwards. Run it and check each criterion against the output.


def fuel_remaining_lb(start_fuel_lb, burn_rate_lb_per_hr, minutes_flown):
    """Return fuel remaining in pounds, never below 0.

    start_fuel_lb and burn_rate_lb_per_hr must be >= 0.
    minutes_flown is time in MINUTES and must be >= 0.
    Raises ValueError for any negative input.
    """
    if start_fuel_lb < 0 or burn_rate_lb_per_hr < 0 or minutes_flown < 0:
        raise ValueError("inputs cannot be negative")
    used_lb = burn_rate_lb_per_hr * minutes_flown / 60
    remaining_lb = start_fuel_lb - used_lb
    if remaining_lb < 0:
        remaining_lb = 0
    return remaining_lb


print("AC1:", fuel_remaining_lb(6000, 1800, 40))
print("AC2:", fuel_remaining_lb(6000, 1800, 240))
print("AC3:", fuel_remaining_lb(6000, 1800, 0))
try:
    fuel_remaining_lb(6000, 1800, -10)
except ValueError as error:
    print("AC4: ValueError:", error)

AC1: 4800.0
AC2: 0
AC3: 6000.0
AC4: ValueError: inputs cannot be negative

Why the specification, not the phrasing, decides the result

A language model predicts a plausible continuation of what it was given (L5). When the request leaves a decision open, the model fills it with a plausible guess, for example hours rather than minutes, an 8-hour rule or a 100-hour interval. Those guesses are often reasonable. They are still guesses, and you do not see them unless you look.

Rewording a vague request ("be precise", "think step by step", "you are an expert") does not add the missing decision. Only you know whether time is in minutes. Writing that down is the specification.

Exercises

Homework

Writing the specification: No AI. Sending it once: AI allowed — keep a record.

1. Pick one function from your L12 decomposition.
2. Write its full specification in Part 3 of a fresh copy of L13_request_template.txt before you open an assistant. Include at least four acceptance criteria, at least one of them at a boundary.
3. Send the specification to an assistant once, in a new chat. Save the reply as a .py file.
4. Do not test it. Do not read past the signature line. Keep the file and the specification for L14, and fill in the AI-use record.
5. If you cannot use an assistant, stop after step 2 and keep your specification. L14 ships a specification and a generated function for exactly this case (L14_spec_sheet.txt and L14_generated_rest_check.py), and you test those instead of your own function.

AI-USE RECORD
Label:            AI allowed — keep a record
Assistant:        (name and version, or "local model")
Date(s):
Prompts:          (paste them, or a link to the conversation)
What I kept:
What I changed:   (and why)
What I verified:  (which claims or results I checked, and against what)

Testing generated code: the habit that carries the course

This is the most important lesson in the course. You will sign for code you did not write, and a test is how you earn the right to sign. In this lesson you write tests from your specification before you read the code, run them, and sort every failure into one of three kinds. Some of those failures will be yours, and that is the point.

You will be able to

• Write test cases from acceptance criteria before reading the generated code.
• Identify boundary and edge cases for a stated function.
• Run tests against generated code and interpret failures.
• Explain why code that runs is not evidence that code is correct.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer from memory, then open the reveal.

1. L13: name the five parts of a generation request.
2. L13: your vague request came back correct. Why can you not sign for it?
3. L10: a program stops with a traceback. Which line do you read first, and what does it tell you?

How to work through this lesson

You need L14_check.py, L14_example_tests.py, L14_example_run_time.py, L14_my_tests.py, L14_test_log.txt, your L13 homework function and its specification, and (if you have no L13 function) L14_spec_sheet.txt and L14_generated_rest_check.py. Do not open L14_generated_rest_check.py until A3 tells you to.

It ran is not it works

Anyone who approves work they did not do by hand is vouching for it: a manager signing off a report, an editor passing a story, a reviewer approving a change. From now on, much of the code you use will be written by a model. When you hand it on, you are the one vouching for it.

Running a program tells you one thing: Python could execute it without crashing on the inputs you happened to give it. It does not tell you the answers were right. The vague Zulu function in L13 ran cleanly and printed -4:00. That is a well-formed string and a wrong time.

Tests come from acceptance criteria, not from the code

Write your tests from the specification. Then run them. Only after that do you read the code.

The order matters. If you read the code first, you start predicting what the code will do, and you write tests that agree with it. Those tests confirm the code's mistakes instead of catching them. A test written from the specification asks a different question: does the code do what was asked?

Each acceptance criterion from L9 and L13 is already a test: an input and an exact expected result. Your job today is to add the cases the criteria did not cover.

The five case types

Most generated code passes the normal cases. Faults live at boundaries and in empty or odd input, because that is where the specification is thinnest and where the model is guessing. The last row is the hardest: you have to think about the real task, not the words on the page.

Running tests with L14_check

L14_check.py is a small helper. Keep it in the same folder as your test file. It gives you three tools:

• check(label, actual, expected) prints PASS or FAIL. On a FAIL it shows both values. It never stops the program.
• result_of(function, arg1, ...) calls the function for you. If the call raises an error, you get a string like "raises ValueError" instead of a crash, so you can test error cases the same way as normal ones.
• summary() prints the totals.

Here is its self-demo. The second check is meant to fail, so you can see what a FAIL looks like.

The helper below uses lines you read but do not write: an import line (in its comments, and in every test file that uses it) and try: with except. The box "Constructs you will see but not write" at the end of L12 says what each one does.

# L14_check.py - a tiny test helper.  Put it in the same folder as your
# test file and write:   from L14_check import check, result_of, summary
#
# check(label, actual, expected)  prints PASS or FAIL and keeps count.
# result_of(function, arg1, ...)  calls the function for you. If it raises
#                                 an error, you get the error's name as a
#                                 string, e.g. "raises ValueError", instead
#                                 of a crash. Use it for every call you test.
# summary()                       prints the totals.
# A failed check never stops the program; every test still runs.

passed = 0
failed = 0


def check(label, actual, expected):
    """Compare actual with expected and print PASS or FAIL."""
    global passed, failed
    if actual == expected:
        passed = passed + 1
        print(f"PASS  {label}")
    else:
        failed = failed + 1
        print(f"FAIL  {label}")
        print(f"        expected: {expected!r}")
        print(f"        actual:   {actual!r}")


def result_of(function, *args):
    """Call function(*args). Return its result, or "raises <ErrorName>"."""
    try:
        return function(*args)
    except Exception as error:
        return "raises " + type(error).__name__


def summary():
    """Print how many checks passed and failed."""
    total = passed + failed
    print(f"\n{passed} of {total} checks passed, {failed} failed.")


if __name__ == "__main__":
    # Self-demo: run this file on its own to see what the output looks like.
    check("2 + 2 is 4", 2 + 2, 4)
    check("this one is meant to fail", "07:30", "0730")
    check("a list compares by contents", [1, 2], [1, 2])
    check("int('abc') raises ValueError", result_of(int, "abc"), "raises ValueError")
    summary()

PASS  2 + 2 is 4
FAIL  this one is meant to fail
        expected: '0730'
        actual:   '07:30'
PASS  a list compares by contents
PASS  int('abc') raises ValueError

3 of 4 checks passed, 1 failed.

Worked example: testing a run-time converter

run_time_to_seconds(text)
Input: a run time as text, "M:SS" or "MM:SS". Example "12:45".
Output: total seconds as an int. Example 765.
Seconds must be 00-59.
Empty or badly formed text raises ValueError.
AC1 run_time_to_seconds("12:45") returns 765
AC2 run_time_to_seconds("9:30") returns 570

# L14 worked example: tests for run_time_to_seconds, written from the
# specification before reading the code.
import sys
from pathlib import Path

# These two lines (with the imports above) let Python find files in this
# folder and stop it writing a __pycache__ folder. Copy all four to the top
# of your own test file.
sys.dont_write_bytecode = True
sys.path.insert(0, str(Path(__file__).parent))

from L14_check import check, result_of, summary
from L14_example_run_time import run_time_to_seconds

check("normal 12:45", result_of(run_time_to_seconds, "12:45"), 765)
check("normal 9:30 (one-digit minutes)", result_of(run_time_to_seconds, "9:30"), 570)
check("boundary 0:00", result_of(run_time_to_seconds, "0:00"), 0)
check("boundary 10:59", result_of(run_time_to_seconds, "10:59"), 659)
check("boundary 10:60 is not a time", result_of(run_time_to_seconds, "10:60"), "raises ValueError")
check("empty text", result_of(run_time_to_seconds, ""), "raises ValueError")
check("wrong type: number 765", result_of(run_time_to_seconds, 765), "raises ValueError")
check("forgot: hours 1:02:30", result_of(run_time_to_seconds, "1:02:30"), "raises ValueError")
summary()

PASS  normal 12:45
PASS  normal 9:30 (one-digit minutes)
PASS  boundary 0:00
PASS  boundary 10:59
FAIL  boundary 10:60 is not a time
        expected: 'raises ValueError'
        actual:   660
PASS  empty text
FAIL  wrong type: number 765
        expected: 'raises ValueError'
        actual:   'raises AttributeError'
PASS  forgot: hours 1:02:30

6 of 8 checks passed, 2 failed.

# L14 worked example: a function to test, written for this lesson as an
# example of what a model might return (a real model's code will differ).
# Specification (from the notes): run_time_to_seconds(text) takes a run
# time written "M:SS" or "MM:SS" and returns the total seconds as an int.
# Seconds must be 00-59. Empty or badly formed text raises ValueError.


def run_time_to_seconds(text):
    """Convert a run time like "12:45" to seconds (765)."""
    minutes, seconds = text.split(":")
    return int(minutes) * 60 + int(seconds)


if __name__ == "__main__":
    print(run_time_to_seconds("12:45"))

Three kinds of failure

When a test fails, do not assume the model was wrong. Decide which of three things happened:

All three happen to everyone who does this. If you blame every failure on the model, you have stopped checking your own work. Expect some of your failures to be your own specification or your own tests. That is a normal result, not an embarrassment, and the distinction comes back in L15, L17 and the L18 checkpoint.

Exercises

days_until(today, due)
Inputs: two dates as text "YYYY-MM-DD".
Output: whole days from today to due, as an int. 0 if due is today.
Negative if due has passed.
Badly formed dates raise ValueError.

Homework

No AI.

Add one test to your file that would have caught a failure you did not anticipate. If you tested the fallback, it can be one from the reference test set in the A3 reveal. Write one sentence on why your original test plan missed it.

Debugging code you did not write

In L14 you found failures. In this lesson you find their causes, using evidence instead of guesses. You will read two disciplined diagnoses, then diagnose your own failures and write down why each one happened before you change a line. If you cannot say what was wrong, you have not fixed it.

You will be able to

• Localise a fault from a failing test and a traceback.
• Form and test a hypothesis about a cause rather than changing code at random.
• Repair a fault and demonstrate the repair with a test.
• Explain why asking a model to fix code you have not diagnosed often produces new faults.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer from memory, then open the reveal.

1. L14: name the three categories of test failure and say who or what gets repaired in each.
2. L14: why do you write the tests before you read the code?
3. L10 and L12: in a traceback, which line names the kind of error, and which lines tell you where Python stopped?

How to work through this lesson

You need your L14 test log and test file, L15_diagnosis_log.txt, L15_check.py, and (if you used the L14 fallback) L15_rest_check.py. The walkthrough files are L15_example_late.py, L15_demo_function.py, L15_demo_tests.py and L15_demo_broken.py.

Debugging is evidence, not intuition

In L14 you recorded failures. Today you find their causes. Debugging uses three pieces of evidence, and each one tells you something different:

A hypothesis is only useful if you can check it. "The code is wrong somewhere" is not a hypothesis. "The comparison on line 14 uses > where the spec says at or above" is one: you can print the comparison and see.

The loop: hypothesis, evidence, ruled in or out

1. Read the failing test. Write down the input, expected and actual values.
2. If there is a traceback, find the last line of the traceback that is in your code. That is where to look first.
3. Write a hypothesis. Then decide what you would see if it were true.
4. Gather evidence: print a value, run a smaller input, trace by hand. Do not change the function yet.
5. Rule the hypothesis in or out. If out, write the next one.
6. Once a hypothesis is ruled in, make one change. Re-run all the tests.

# L15 worked example (notes). Specification:
#   minutes_late(scheduled, actual): two times as "HHMM" strings on the
#   same day. Returns how many minutes actual is after scheduled, or 0 if
#   actual is on time or early.


def minutes_late(scheduled, actual):
    """Return minutes late, or 0 if on time or early."""
    scheduled_minutes = int(scheduled[:2]) * 60 + int(scheduled[2:])
    actual_minutes = int(actual[:2]) * 60 + int(actual[:2])
    late = actual_minutes - scheduled_minutes
    if late < 0:
        late = 0
    return late


if __name__ == "__main__":
    import sys
    from pathlib import Path

    sys.dont_write_bytecode = True
    sys.path.insert(0, str(Path(__file__).parent))
    from L15_check import check, result_of, summary

    check("on time 0700 0700", result_of(minutes_late, "0700", "0700"), 0)
    check("late 0700 0715", result_of(minutes_late, "0700", "0715"), 15)
    check("early 0700 0650", result_of(minutes_late, "0700", "0650"), 0)
    check("late 0700 0807", result_of(minutes_late, "0700", "0807"), 67)
    summary()
    print()
    print("Evidence: actual '0715' converts to", int("0715"[:2]) * 60 + int("0715"[:2]), "minutes")
    print("Evidence: expected 7 * 60 + 15 =", 7 * 60 + 15)

FAIL  on time 0700 0700
        expected: 0
        actual:   7
FAIL  late 0700 0715
        expected: 15
        actual:   7
PASS  early 0700 0650
FAIL  late 0700 0807
        expected: 67
        actual:   68

1 of 4 checks passed, 3 failed.

Evidence: actual '0715' converts to 427 minutes
Evidence: expected 7 * 60 + 15 = 435

PASS  on time 0700 0700
PASS  late 0700 0715
PASS  early 0700 0650
PASS  late 0700 0807

4 of 4 checks passed, 0 failed.

Walkthrough 1: diagnosing pass_rate

Here is a function written for this lesson, of the kind a model might return, and the tests written for it from its specification. The specification: pass_rate(scores, passing_score) takes a list of test scores from a first-aid course (numbers 0 to 100) and a passing score, and returns the percentage of scores at or above the passing score, rounded to 1 decimal place. An empty list raises ValueError.

# L15 walkthrough 1: a function to diagnose, written for this lesson as an
# example of what a model might return. Specification:
#   pass_rate(scores, passing_score)
#   scores: list of test scores from a first-aid course (numbers 0-100).
#   passing_score: a number.
#   Returns the percent of scores AT OR ABOVE passing_score, rounded to
#   1 decimal place. An empty list raises ValueError.


def pass_rate(scores, passing_score):
    """Return the percent of scores that pass, rounded to 1 decimal."""
    if len(scores) == 0:
        raise ValueError("no scores given")
    passed = 0
    for score in scores:
        if score > passing_score:
            passed = passed + 1
    rate = passed / len(scores) * 100
    return round(rate, 1)


if __name__ == "__main__":
    print(pass_rate([92.5, 81.0, 68.0, 88.0], 75))

Step 1. Run the tests. Before reading anything, find out where the behaviour is wrong.

PASS  T1 normal: 3 of 4 pass
FAIL  T2 boundary: a score of exactly 75
        expected: 75.0
        actual:   50.0
PASS  T3 none pass
PASS  T4 one third, rounded
PASS  T5 empty list

4 of 5 checks passed, 1 failed.

Step 2. Read the failure. T2 expected 75.0 and got 50.0. Four scores; the spec says at or above 75 passes. 80, 75 and 90 pass, so 3 of 4. The code thinks 2 of 4. T1, T3 and T4 pass, so the basic counting works.

Step 3. Hypotheses and evidence. Three hypotheses, each with the evidence that settles it. A short probe program (L15_demo_probes.py, in the teacher files) printed every value quoted here; its output is below.

Failing test T2: scores [80.0, 75.0, 90.0, 74.9], passing 75
  result: 50.0
H1 rounding is wrong?  Try a case where rounding does nothing:
  2 of 4 pass, no tie with 75 -> 50.0
H2 the count of scores is wrong?  len of the T2 list: 4
H3 a score of exactly 75 is not counted?  Each score in T2:
   80.0 > 75 is True     80.0 >= 75 is True
   75.0 > 75 is False     75.0 >= 75 is True
   90.0 > 75 is True     90.0 >= 75 is True
   74.9 > 75 is False     74.9 >= 75 is False
Smallest test of H3: one score of exactly 75 -> 0.0

Step 4. One change. The spec says at or above. The comparison line uses >. Change > to >= and nothing else. Re-run all tests:

PASS  T1 normal: 3 of 4 pass
PASS  T2 boundary: a score of exactly 75
PASS  T3 none pass
PASS  T4 one third, rounded
PASS  T5 empty list

5 of 5 checks passed, 0 failed.

Every test passes, including the four that passed before. The fault can be stated in one sentence: the comparison excluded scores exactly at the pass mark.

Walkthrough 2: reading a traceback

The second program does not fail a test; it crashes. It averages flight lengths from a flying club's logbook, where every value arrives as text.

# L15 walkthrough 2: a program that raises. It averages flight lengths
# read from a flying club's logbook, where every value arrives as text.


def average_flight_hours(durations):
    """Return the mean flight length in hours, rounded to 2 decimals."""
    total = 0
    for duration in durations:
        total = total + duration
    return round(total / len(durations), 2)


log_values = ["1.5", "2.0", "1.2", "1.8"]
print("Average flight:", average_flight_hours(log_values), "hours")

Traceback (most recent call last):
  File "/home/you/ai-course/L15/L15_demo_broken.py", line 14, in <module>
    print("Average flight:", average_flight_hours(log_values), "hours")
                             ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^
  File "/home/you/ai-course/L15/L15_demo_broken.py", line 9, in average_flight_hours
    total = total + duration
            ~~~~~~^~~~~~~~~~
TypeError: unsupported operand type(s) for +: 'int' and 'str'

Read the traceback bottom up. The last line says TypeError: unsupported operand type(s) for +: 'int' and 'str'. The line above it says line 9, total = total + duration, inside average_flight_hours. The line above that says it was called from line 14.

What type is the first value? str
What type is total before the loop? int
Does the loop ever run? Number of values: 4
One change, H2 confirmed: convert each value with float()
Average: 1.62

One change: convert each value with float() before adding. The average is 1.62. Is 1.62 right? 1.5 + 2.0 + 1.2 + 1.8 = 6.5, divided by 4 is 1.625. Python's round() sends an exact half to the even digit, so it gives 1.62 where someone rounding by hand writes 1.63. Either is defensible; the point is that you checked by hand, and that a rounding rule is a decision the specification should state. This also previews L16: data that arrives as text.

Diagnose before you ask a model to repair

You may use an assistant to help with a repair in this lesson (AI allowed — keep a record). You may only do it after your written diagnosis is complete.

If you paste a failing test into a model and say "fix this", the model does not know why the test failed any more than you do. It tends to produce a change that makes the test pass. That is a different goal from making the code meet the specification. The quickest way to make a test pass is often to bend the code around that one input, which can quietly break something else. A4 shows a repair that does exactly that.

After a model repair, check two things. First, every original test still passes. Second, the model changed only what your diagnosis said was wrong. If it changed other lines, you must explain each one or reject it.

Exercises

E1  exactly 12.0: WAIVER REQUIRED
    12.0 > 12.0 is False   12.0 >= 12.0 is True
    12.01: COMPLIANT
E2  exactly 10.0: NON-COMPLIANT
    10.0 <= 10.0 is True   10.0 < 10.0 is False
    10.01: WAIVER REQUIRED
E3  empty list: COMPLIANT
    times the loop body runs for []: 0
E4  float('12') is 12.0   float(True) is 1.0
    [13.0, '12']: WAIVER REQUIRED
    [13.0, 'abc'] raises ValueError: could not convert string to float: 'abc'

# L15 example: a "repair" that passes the tests by breaking the
# specification. Written as a model plausibly returns it when someone
# pastes the failing test output and says "fix this so the tests pass",
# with no diagnosis. Reference output for teacher use - a real model's
# output will differ.
import sys
from pathlib import Path

sys.dont_write_bytecode = True
sys.path.insert(0, str(Path(__file__).parent.parent / "student"))

from L15_check import check, result_of, summary

FULL_REST_HOURS = 12.0
MIN_REST_HOURS = 10.0
TOLERANCE = 0.05  # allow for rounding in logged rest times


def rest_check(rest_periods):
    """Check a week of rest periods against the airline's rest rule."""
    if len(rest_periods) == 0:
        raise ValueError("no rest periods given")
    violations = 0
    short_rests = 0
    for period in rest_periods:
        if isinstance(period, bool) or not isinstance(period, (int, float)):
            raise TypeError("rest periods must be numbers")
        hours = float(period)
        if hours < 0:
            raise ValueError("rest period cannot be negative")
        if hours <= MIN_REST_HOURS - TOLERANCE:
            violations += 1
        elif hours > FULL_REST_HOURS - TOLERANCE:
            continue
        else:
            short_rests += 1
    if violations > 0:
        return "NON-COMPLIANT"
    if short_rests >= 2:
        return "NON-COMPLIANT"
    elif short_rests == 1:
        return "WAIVER REQUIRED"
    return "COMPLIANT"


print("-- The original tests (all from L14) --")
check("AC1 all full rests", result_of(rest_check, [13.0, 14.5, 12.5]), "COMPLIANT")
check("AC2 one short rest", result_of(rest_check, [13.0, 11.0, 14.0]), "WAIVER REQUIRED")
check("AC4 one violation", result_of(rest_check, [13.0, 8.0, 14.0]), "NON-COMPLIANT")
check("exactly 12.0 is full", result_of(rest_check, [12.0, 13.0]), "COMPLIANT")
check("exactly 10.0 is short", result_of(rest_check, [10.0, 13.0]), "WAIVER REQUIRED")
check("9.9 is a violation", result_of(rest_check, [9.9, 13.0]), "NON-COMPLIANT")
check("11.9 is short", result_of(rest_check, [11.9, 13.0]), "WAIVER REQUIRED")
check("empty list", result_of(rest_check, []), "raises ValueError")
check("string '12'", result_of(rest_check, [13.0, "12"]), "raises TypeError")
summary()

print()
print("-- What the specification says about times the tests never tried --")
eleven_58 = 11 + 58 / 60  # 11 h 58 min, a short rest under R2
nine_58 = 9 + 58 / 60     # 9 h 58 min, a violation under R3
print(f"11 h 58 min = {eleven_58:.4f} h -> {rest_check([eleven_58, 13.0])}   (R2 says WAIVER REQUIRED)")
print(f" 9 h 58 min = {nine_58:.4f} h -> {rest_check([nine_58, 13.0])}   (R3 says NON-COMPLIANT)")

-- The original tests (all from L14) --
PASS  AC1 all full rests
PASS  AC2 one short rest
PASS  AC4 one violation
PASS  exactly 12.0 is full
PASS  exactly 10.0 is short
PASS  9.9 is a violation
PASS  11.9 is short
PASS  empty list
PASS  string '12'

9 of 9 checks passed, 0 failed.

-- What the specification says about times the tests never tried --
11 h 58 min = 11.9667 h -> COMPLIANT   (R2 says WAIVER REQUIRED)
 9 h 58 min = 9.9667 h -> WAIVER REQUIRED   (R3 says NON-COMPLIANT)

    if len(rest_periods) == 0:
        raise ValueError("no rest periods given")

        if not isinstance(period, (int, float)):
            raise TypeError("rest periods must be numbers")

# L15 key: the L14 fallback after four diagnosed repairs, one per
# hypothesis. Each change is marked with its log entry. Re-tests every
# L14 reference case except T16 (a specification gap, see the key), with
# T18 (a test error) corrected.
import sys
from pathlib import Path

sys.dont_write_bytecode = True
sys.path.insert(0, str(Path(__file__).parent.parent / "student"))

from L15_check import check, result_of, summary

FULL_REST_HOURS = 12.0
MIN_REST_HOURS = 10.0


def rest_check(rest_periods):
    """Check a week of rest periods against the airline's rest rule."""
    if len(rest_periods) == 0:                      # entry 3
        raise ValueError("no rest periods given")
    violations = 0
    short_rests = 0
    for period in rest_periods:
        if not isinstance(period, (int, float)):    # entry 4
            raise TypeError("rest periods must be numbers")
        hours = float(period)
        if hours < 0:
            raise ValueError("rest period cannot be negative")
        if hours < MIN_REST_HOURS:                  # entry 2: was <=
            violations += 1
        elif hours >= FULL_REST_HOURS:              # entry 1: was >
            continue
        else:
            short_rests += 1
    if violations > 0:
        return "NON-COMPLIANT"
    if short_rests >= 2:
        return "NON-COMPLIANT"
    elif short_rests == 1:
        return "WAIVER REQUIRED"
    return "COMPLIANT"


check("T1  AC1", result_of(rest_check, [13.0, 14.5, 12.5]), "COMPLIANT")
check("T2  AC2", result_of(rest_check, [13.0, 11.0, 14.0]), "WAIVER REQUIRED")
check("T3  AC3", result_of(rest_check, [13.0, 11.0, 10.5]), "NON-COMPLIANT")
check("T4  AC4", result_of(rest_check, [13.0, 8.0, 14.0]), "NON-COMPLIANT")
check("T5  exactly 12.0", result_of(rest_check, [12.0, 13.0]), "COMPLIANT")
check("T6  exactly 10.0", result_of(rest_check, [10.0, 13.0]), "WAIVER REQUIRED")
check("T7  9.9", result_of(rest_check, [9.9, 13.0]), "NON-COMPLIANT")
check("T8  11.9", result_of(rest_check, [11.9, 13.0]), "WAIVER REQUIRED")
check("T9  single period", result_of(rest_check, [13.0]), "COMPLIANT")
check("T10 zero hours", result_of(rest_check, [0, 13.0]), "NON-COMPLIANT")
check("T11 empty", result_of(rest_check, []), "raises ValueError")
check("T12 negative", result_of(rest_check, [13.0, -2.0]), "raises ValueError")
check("T13 string '12'", result_of(rest_check, [13.0, "12"]), "raises TypeError")
check("T14 string 'abc'", result_of(rest_check, [13.0, "abc"]), "raises TypeError")
check("T15 ints", result_of(rest_check, [13, 14, 15]), "COMPLIANT")
week = [13.0, 11.0, 14.0]
result_of(rest_check, week)
check("T17 list is not changed", week, [13.0, 11.0, 14.0])
check("T18 corrected: one short rest, no violation", result_of(rest_check, [13.0, 10.5, 13.0, 12.5]), "WAIVER REQUIRED")
check("new: 11 h 58 min is short", result_of(rest_check, [11 + 58 / 60, 13.0]), "WAIVER REQUIRED")
check("new: 9 h 58 min is a violation", result_of(rest_check, [9 + 58 / 60, 13.0]), "NON-COMPLIANT")
summary()

PASS  T1  AC1
PASS  T2  AC2
PASS  T3  AC3
PASS  T4  AC4
PASS  T5  exactly 12.0
PASS  T6  exactly 10.0
PASS  T7  9.9
PASS  T8  11.9
PASS  T9  single period
PASS  T10 zero hours
PASS  T11 empty
PASS  T12 negative
PASS  T13 string '12'
PASS  T14 string 'abc'
PASS  T15 ints
PASS  T17 list is not changed
PASS  T18 corrected: one short rest, no violation
PASS  new: 11 h 58 min is short
PASS  new: 9 h 58 min is a violation

19 of 19 checks passed, 0 failed.

Homework

No AI.

Write three sentences about a repair you accepted without fully understanding it: what it changed, what you did not understand, and what you would now check. If there were none, say so and name the evidence that let you understand each repair.

Working with data: files, CSV, simple analysis

Data arrives with problems, and analysis code usually runs anyway. In this lesson you inspect a small charter operator's flight log before you analyse it, find four planted defects, and state exactly how you handled each one. A tidy summary from a program that skipped rows in silence is a confident wrong answer.

You will be able to

• Read a delimited file and describe its structure before analysing it.
• Detect malformed rows, missing values and encoding problems in a supplied dataset.
• Compute a simple summary and state its assumptions.
• Explain why an analysis that runs cleanly can still be wrong.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer each from memory before you open the reveal.

1. In L4 you saw text stored as bytes. A file written in one encoding is read in another. What are the two ways that can show up?
2. In L14 a generated function ran without any error. What did that tell you about whether it was correct?
3. In L15, what made a sentence count as a usable hypothesis about a fault?

How to work through this lesson

You need the files in this lesson's folder: L16_flight_log.csv, L16_inspect.py, L16_starter_analysis.py, L16_strict_read_broken.py, L16_defect_log.txt, and the two worked-example files L16_example_fitness.csv and L16_example_fitness.py. Open a terminal in that folder (as in L10) so that python L16_inspect.py finds the data file.

Look at the data before you analyse it

The most common data failure is analysing a file nobody looked at. Before you compute anything, answer four questions: How many rows are there? What are the columns? Does every row have the same number of fields? What are the smallest and largest values in each number column?

Those four answers take two minutes and catch most problems. A mean computed over a file you never inspected is a number with no known meaning.

Reading delimited data

A CSV (comma-separated values) file is plain text. The first line is usually a header naming the columns. Each later line is one row, and commas split it into fields. Here are the first lines of this lesson's file, a month of flights by a small charter operator with five aircraft and ten pilots (everything in it is invented):

flight_id,date,pilot,tail,duration_hr,fuel_lb,landings
F1001,2026-09-01,Reyes M,TR-118,1.8,785,4
F1002,2026-09-01,Okafor T,TR-107,1.3,560,3
F1003,2026-09-02,Lindqvist A,TR-107,1.8,795,1
F1004,2026-09-02,Peña R,TR-107,1.8,800,1
F1005,2026-09-03,Haddad S,TR-104,1.3,545,4

Three things go wrong with files like this.

• Wrong field count. A comma inside a value ("Okafor, T") splits it into two fields, and every column after it shifts by one.
• Missing values. Two commas with nothing between them. Python reads an empty string, which is not a number.
• Encoding. In L4 you saw that text is stored as bytes and that the reader and writer must agree on the encoding. A file that is mostly UTF-8 can contain one line saved by a program that used a different encoding. A strict UTF-8 read stops at that line with a UnicodeDecodeError. A forgiving read (errors="replace") carries on and swaps the bad bytes for a replacement character, so a name quietly changes.

A fourth kind of problem is invisible to every check above: a value that is well formed, in range and wrong. Finding it takes knowing what the data means.

Worked example: inspecting a fitness-test file

member,pushups,situps,run_time
Adler,52,58,10:45
Bui,61,60,9:58
Carver,47,,11:20
Diaz,58,55,10:12
Eze,45,52,11:05
Finch,60,61,0:58
Grant,55,57,10:30
Holt,49,50,11:41

# L16 worked example: inspect, then analyse, a small fitness-test file.
import csv
from pathlib import Path

DATA_FILE = Path(__file__).parent / "L16_example_fitness.csv"

with open(DATA_FILE, encoding="utf-8", newline="") as f:
    rows = list(csv.reader(f))
header = rows[0]
data = rows[1:]

print("Step 1. Inspect")
print("  header:", header)
print("  data rows:", len(data))
for line_number, row in enumerate(data, start=2):
    if len(row) != len(header) or "" in row:
        print("  line", line_number, "needs a look:", row)
run_seconds = []
for row in data:
    minutes, seconds = row[3].split(":")
    run_seconds.append(int(minutes) * 60 + int(seconds))
print("  run time min / max (seconds):", min(run_seconds), "/", max(run_seconds))

print("Step 2. Analyse: mean run time")
print("  all 8 rows:", round(sum(run_seconds) / len(run_seconds)), "s")
kept = []
for seconds in run_seconds:
    if seconds >= 360:
        kept.append(seconds)
print("  without the 58-second run:", round(sum(kept) / len(kept)), "s over", len(kept), "rows")

Step 1. Inspect
  header: ['member', 'pushups', 'situps', 'run_time']
  data rows: 8
  line 4 needs a look: ['Carver', '47', '', '11:20']
  run time min / max (seconds): 58 / 701
Step 2. Analyse: mean run time
  all 8 rows: 574 s
  without the 58-second run: 647 s over 7 rows

It ran cleanly and it is still wrong

Analysis code from a model usually runs. It often handles bad rows by skipping them in silence, or by reading the file with errors="replace" so it never crashes. Then it prints a tidy summary. Nothing on the screen tells you that rows were dropped or names were changed.

You will meet exactly this in the lab. L16_starter_analysis.py is the kind of code a model returns for "summarise this flight log" (it was written for this lesson; a real model's code will differ). Run it first, and before you trust it, ask what it did with every row it could not read.

Exercises

Traceback (most recent call last):
  File "/home/you/ai-course/L16/L16_strict_read_broken.py", line 8, in <module>
    text = DATA_FILE.read_text(encoding="utf-8")
  File "/usr/lib/python3.13/pathlib/_local.py", line 546, in read_text
    return PathBase.read_text(self, encoding, errors, newline)
           ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.13/pathlib/_abc.py", line 633, in read_text
    return f.read()
           ~~~~~~^^
  File "<frozen codecs>", line 325, in decode
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xf1 in position 1508: invalid continuation byte

=== Flight Log Summary ===
Flights analysed:     48
Pilots:               11
Total flight hours:   77.2
Mean flight length:   1.61 h
Shortest / longest:   0.8 h / 2.5 h
Mean fuel per flight: 701 lb
Fleet burn rate:      436 lb/h
Hours by pilot:
  Brennan K       8.9
  Duarte L        8.9
  Haddad S        7.6
  Kowalski P      9.5
  Lindqvist A    10.1
  Nakamura J      7.6
  Okafor T        4.1
  Osei D          6.9
  Peña R          5.2
  Pe�a R          1.6
  Reyes M         6.8
Analysis complete. All records processed successfully.

File: L16_flight_log.csv | lines: 51 | data rows: 50
Line 35: NOT valid UTF-8 (invalid continuation byte) bytes: b'F1034,2026-09-20,Pe\xf1a R,TR-101,1.6,650,2'
Header: ['flight_id', 'date', 'pilot', 'tail', 'duration_hr', 'fuel_lb', 'landings'] | 7 fields
Line 13: 8 fields, expected 7: F1012,2026-09-07,Okafor, T,TR-107,1.5,615,2
Line 25: duration_hr is empty
duration_hr: 48 values, min 0.8 (line 17), max 2.5 (line 21)
fuel_lb: 49 values, min 325.0 (line 43), max 1105.0 (line 14)
landings: 49 values, min 1.0 (line 4), max 6.0 (line 45)

Choices used:
  D1 line 13: repaired (name rejoined)
  D2 line 25: fuel kept, duration unknown
  D3 line 35: repaired (decoded as cp1252)
  D4 line 42: held out

Data rows in file: 50
Rows used: 49 of 50   rows dropped: [42]
Distinct pilots: 10
  duration_hr: n=48  mean=1.621  min=0.8  max=2.5  total=77.8
  fuel_lb: n=49  mean=697.449  min=325.0  max=1105.0  total=34175.0

Mean flight length 1.621 h over 48 of 50 rows.
Mean fuel 697.4 lb over 49 of 50 rows.

Homework

Finish L16_defect_log.txt if you have not. Finding and logging the defects is No AI. Any analysis code you still write or change for A4 stays AI allowed — keep a record, and goes in the log's AI-use record. Then prepare for L17: gather your L13 request template and outputs, your L14 test log and test file, your L15 diagnosis log and this lesson's defect log in one place, and set aside about an hour without interruptions for the exercise.

Integrated exercise: specify, generate, test, correct

In this lesson you run the whole Unit II method on a problem you have not seen, in one sitting of about an hour. You write the specification and the tests yourself. An assistant writes the code. Then you find out whether the code meets your specification, fix what does not, and sign for the result. You score yourself against a rubric, and the rubric is strict on purpose: it is a rehearsal for the final project in Unit VII, which asks for the same thing at a larger scale.

You will be able to

• Execute the full method on an unfamiliar problem within one sitting.
• Produce a specification, tests, generated implementation, and a correction record.
• Justify each acceptance criterion against the problem statement.
• Produce a complete AI-use record.

Reading and worked examples

Before you start

Three questions from earlier lessons. Answer each from memory before you open the reveal.

1. Name the five steps of the method from L9, in order.
2. L14 sorted every test failure into one of three categories. Name them and say who repairs each.
3. In L16, what two numbers must every summary state, and why?

How this exercise runs

There are four problems, A to D. Pick one. If you have no preference, take A. Each problem is one function, sized so that someone new to programming, working with an assistant, can finish it in the time given. The other three stay available: doing a second one before Checkpoint 1 is good practice, and the answer keys are separate, so you spoil nothing by doing them later.

The rubric is below. Read it now, not at the end.

The method, start to finish, on a small problem

Here is the whole loop on a problem much smaller than yours, so you can see every step once before you do it against the clock.

"""L17 worked example: hours to the next service.

Spec: a warehouse forklift is serviced every 100 running hours (at 100,
200, 300 ...). hours_to_next(current_hours) returns the hours left before
the next service is due. At exactly a multiple of 100 the service is due
now, so the answer is 0.
"""


def hours_to_next_first_try(current_hours):
    # An example first answer (written for this lesson).
    return 100 - current_hours % 100


def hours_to_next_fixed(current_hours):
    # After diagnosis: at an exact multiple the remainder is 0, and the
    # service is due now.
    remainder = current_hours % 100
    if remainder == 0:
        return 0
    return 100 - remainder


def run_tests(function):
    tests = [[250, 50], [299, 1], [300, 0], [301, 99], [0, 0]]
    for test in tests:
        hours = test[0]
        expected = test[1]
        actual = function(hours)
        if actual == expected:
            print("PASS", hours, "->", actual)
        else:
            print("FAIL", hours, "expected", expected, "got", actual)


print("First try:")
run_tests(hours_to_next_first_try)
print("Fixed:")
run_tests(hours_to_next_fixed)

First try:
PASS 250 -> 50
PASS 299 -> 1
FAIL 300 expected 0 got 100
PASS 301 -> 99
FAIL 0 expected 0 got 100
Fixed:
PASS 250 -> 50
PASS 299 -> 1
PASS 300 -> 0
PASS 301 -> 99
PASS 0 -> 0

Acceptance criteria you can justify

Objective 3 asks you to justify each criterion against the problem statement. That means every criterion points at the words in the problem that require it, or at an assumption you wrote down because the problem was silent. A criterion with nothing to point at is either padding or a hidden assumption.

The correction record

Every failure gets one entry. The entry is evidence that you diagnosed before you repaired. The three categories are the ones from L14.

You may ask an assistant to make the repair, but only after your diagnosis is written. Paste your diagnosis into the request so the assistant is repairing the fault you found, not guessing. Then re-run every test, not just the one that failed. A repair that fixes one test and breaks another is common.

The AI-use record

The AI-use record is the same one you have kept since L1, with the same seven fields: Label, Assistant, Date(s), Prompts, What I kept, What I changed, What I verified. For this exercise each field must hold:

• Label: AI allowed — keep a record.
• Assistant: the assistant named as it appears in the tool (name and version), or "local model", or "fallback file" if you used L17_<X>_fallback_code.py.
• Date(s): the day or days you worked on the exercise.
• Prompts: every prompt, copied exactly and numbered in order. A summary of a prompt is not the prompt. Copy each one into the record as you send it, not at the end.
• What I kept: what you kept from each response.
• What I changed: what you changed yourself, and why.
• What I verified: which tests you ran against the result, and the outcome.

This exercise asks for one thing in addition to the record: your signature on the statement below it in the template, saying that you read every line of the code you are signing for. The statement is not one of the seven fields, so a missing signature does not trigger the 60 cap, but full credit on the AI-use row asks for it.

Exercises