AI support copilot project · Chapter 1 of 12

The plan and the pages

By the end of this chapter you know what DabbaDrop's support copilot will do and how its parts fit, you can read DabbaDrop's help pages from their files into Python (title, header lines, body), leave out a page that a newer one replaced, and measure the pages in tokens, the unit a model reads and charges by. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: The pages
  • 3 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

DabbaDrop sends home-style lunch dabbas from three Mumbai kitchens (Andheri, Dadar, Thane) to six delivery zones. Members ask the same questions all day on WhatsApp: is my late dabba refunded, what does delivery cost, is there Jain food in Thane, can I pause my Monthly plan. Sana, the support lead, answers about 180 of them on a weekday, by hand, from DabbaDrop's help pages. Last week she told a member that delivery costs ₹40. It costs ₹30: the ₹40 page was replaced on 1 October, but the old file is still in the folder.

Farah, the founder, wants a support copilot: an API that DabbaDrop's WhatsApp tool calls with a member's question. It answers from the help pages only, shows which page it used, and says "I don't know" when the pages do not say. Kunal, DabbaDrop's senior developer, builds it with you over twelve chapters. Every chapter starts from his finished code of the chapter before, so the project always runs.

Everything the copilot will ever say comes from the help pages, and right now nothing reads them. They are 35 markdown files in data/help. One of them is the old delivery charges page, and a program that reads "every file" reads the ₹40 page too. Before any search or any model, the app has to know what a page is, which pages are current, and how big they are.

The lesson

Tour of the codebase

This is chapter 1, so everything is new. The whole app is in your chapter's folder; the one file marked as yours is the only one you edit.

pyproject.toml                 the packages and their versions
app/__main__.py                python -m app: the server on port 8000, with reload
app/main.py                    create_app(): the FastAPI app
app/config.py                  every setting the app reads (models, sizes, prices)
app/lib/tokens.py              count_tokens(text), with tiktoken
app/lib/text.py                split_sentences(text) (chapter 2 uses it)
app/modules/health/            GET /health
app/modules/pages/router.py    GET /pages, /pages/stats, /pages/{id}: calls your functions
app/corpus/pages.py            yours: Page, parse_page, load_pages, corpus_stats
data/help/                     DabbaDrop's 35 help pages, one markdown file each

Start the app from the terminal:

$ python -m app
INFO:     Will watch for changes in these directories: ['/workspace/chapters/w-a1/app']
INFO:     Uvicorn running on http://127.0.0.1:8101 (Press CTRL+C to quit)
INFO:     Started reloader process [2297] using WatchFiles
INFO:     Started server process [2299]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

(Your port is 8000; this run used another one.) The saved request "Is the app up?" answers {"ok":true,"database":"up","counts":null}: there are no tables yet, chapter 3 makes them. "Every help page" answers 500 until you write Task 2, and the server's log says why:

  File "/workspace/chapters/w-a1/app/corpus/pages.py", line 79, in load_pages
    raise NotImplementedError("Task 2: load_pages is not written yet")
NotImplementedError: Task 2: load_pages is not written yet

The plan

A model such as GPT knows a lot about the world and nothing about DabbaDrop's refund rules. Asked about them, it guesses, and a guess sounds exactly as sure as a fact. The fix is to give the model the right part of the help pages with the question and tell it to answer from that part only. This is called retrieval-augmented generation, RAG: first retrieve, then generate. Kunal's plan has three stages, and the chapters follow them:

  1. Prepare the pages (chapters 1 to 3): read them, cut them into small pieces called chunks, turn each chunk into numbers that capture its meaning, and store them in Postgres.
  2. Search (chapters 4 to 6): for a question, find the five chunks that answer it best.
  3. Answer (chapters 7 to 12): send those chunks and the question to the model, with each chunk's id, and get back an answer that cites them, streamed, guarded, checked and cheap.

This chapter is the first step of the first stage: the pages, as Python objects.

A help page, line by line

Every page has the same shape:

$ head -7 data/help/delivery-charges.md
# Delivery charges
updated: 2026-10-01
tags: delivery charges, fees, monthly plan
supersedes: delivery-charges-2025

This page explains how much DabbaDrop charges for delivery and who gets free delivery.

The first line is the title after # . Then come header lines, one key: value each, up to the first blank line: updated is on every page, tags on most, supersedes only on a page that replaces an older one. Everything after the blank line is the body. The given Page dataclass holds those six things, with the date as a real date and the tags as a tuple.

Python gives you the pieces. text.splitlines() cuts a text into lines (a blank line becomes ""), and line.startswith("# ") tests a prefix. The interesting part is a header line. A value may hold a colon itself, so cutting at every colon is wrong:

>>> line = "owner: Bhavna: operations"
>>> line.split(":")
['owner', ' Bhavna', ' operations']
>>> line.partition(":")
('owner', ':', ' Bhavna: operations')

split cut the value in two. partition cuts at the first colon only and always gives back three parts: before, the colon, after. Keys are compared in lower case, so Tags: and tags: are the same header; strip both sides, because people type spaces:

>>> "  Kitchen ".strip().lower()
'kitchen'

A date in a file is text. date.fromisoformat reads the ISO form, and refuses anything else with a ValueError:

>>> from datetime import date
>>> date.fromisoformat("2026-10-01")
datetime.date(2026, 10, 1)
>>> date.fromisoformat("1 Oct 2026")
Traceback (most recent call last):
...
ValueError: Invalid isoformat string: '1 Oct 2026'

Tags are a comma list, and splitting has a trap. A string with no commas still splits into one item, and an empty string splits into one empty item:

>>> "veg, jain ,  nut free".split(",")
['veg', ' jain ', '  nut free']
>>> "".split(",")
['']

So a page with no tags line must give an empty tuple, not a tuple holding one empty string. And a missing header is not an error in itself: dict.get("salt") gives None where d["salt"] would raise KeyError.

A page that is broken (no title line, no updated) should stop ingestion loudly, with the page's id in the message, so whoever edits the pages knows which file to fix. That is a ValueError("jain-food: ...") you raise yourself; a bare KeyError: 'updated' names no page at all.

A folder of pages

Path from pathlib finds the files. folder.glob("*.md") gives every markdown file in the folder (and skips a notes.txt), path.stem is the name without the extension, which is the page's id, and path.read_text(encoding="utf-8") reads it. Say the encoding: the pages are full of ₹, and a machine set to another encoding would misread it.

>>> from pathlib import Path
>>> for f in sorted(Path("data/help").glob("de*.md")):
...     print(f.name, f.stem)
...
delivery-areas.md delivery-areas
delivery-charges-2025.md delivery-charges-2025
delivery-charges.md delivery-charges
delivery-slots.md delivery-slots

glob promises no order, so the result must be sorted by id. A stable order makes every later step repeatable.

Now the ₹40 problem. delivery-charges.md says supersedes: delivery-charges-2025. Bhavna keeps the old page in the folder on purpose, as a record of what members were told in 2025, but it must never reach a member. The rule is about the whole folder, not one page: you only know a page is replaced after you have read the page that replaces it. So read every page first, collect the ids that any page supersedes (a set, because you only ask "is this id in it?"), and keep the pages whose id is not in that set.

Tokens

A model does not read characters or words. It reads tokens, pieces of text from a fixed list of about 200,000, and everything about a model is counted in them: how much it can read at once, how fast it is and what it costs. app/lib/tokens.py counts them with tiktoken and OpenAI's o200k_base list, the one the lab model uses too:

>>> from app.lib.tokens import count_tokens, ENC
>>> for t in ["DabbaDrop", "dabba", " lunch", "Jain Thali", "₹180"]:
...     print(repr(t), count_tokens(t), [ENC.decode([x]) for x in ENC.encode(t)])
...
'DabbaDrop' 3 ['D', 'abba', 'Drop']
'dabba' 2 ['dab', 'ba']
' lunch' 1 [' lunch']
'Jain Thali' 4 ['J', 'ain', ' Th', 'ali']
'₹180' 2 ['₹', '180']
>>> count_tokens("The delivery charge is ₹30 per order.")
9

ENC.encode gives the token numbers and ENC.decode turns one back into its text. Common English words are one token each, with their leading space (the sentence about the delivery charge is 9 tokens). Words the list has not seen often, like DabbaDrop or Thali, break into pieces. A rough rule for English is four characters a token, but only counting tells you.

To find the biggest page, Python's max takes a key: it compares what the key gives and returns the item. When two items tie, it keeps the first one it saw. With nothing to compare it raises, unless you give it a default:

>>> max(["poha", "upma", "idli", "dal"], key=len)
'poha'
>>> print(max([], key=len, default=None))
None
>>> max([], key=len)
Traceback (most recent call last):
...
ValueError: max() iterable argument is empty

Why not send every page

The pages are small, so why search at all? Kunal tried the simplest copilot, a little script: every current page joined into one system message, then the question, sent with the openai package to the model named on the command line. The lab model has a window of 8,192 tokens:

$ python every_page.py lab-chat
Traceback (most recent call last):
...
openai.BadRequestError: Error code: 400 - {'error': {'message': "This model's maximum context length is 8192 tokens. However, your messages resulted in 9180 tokens. Please reduce the length of the messages.", 'type': 'invalid_request_error', 'param': 'messages', 'code': 'context_length_exceeded'}}

lab requests shows what the model received: a system message of 39,813 characters and the question, then context_length_exceeded. The lab's lab-chat-large has a window of 131,072, and it answered:

$ python every_page.py lab-chat-large
Thane Kitchen does not cook Jain food, so Jain dishes are not available in Thane.
9180 read, 19 written

Right, and expensive. At its price of ₹1,000 a million tokens read and ₹4,000 a million written, that is about ₹9.26 for one answer, about ₹1,666 for Sana's 180 questions a day, to read 9,180 tokens for the one sentence that answered. The pages will also grow, and a model given more to read finds the right sentence less reliably. Searching first sends a few hundred tokens instead.

The lab's models are stand-ins that run inside the lab with no internet. lab-chat behaves like a real chat model in the ways that matter here (windows, prices, errors, answering from what it is given), but its sentences are picked from what it reads, not written.

Your turn

  • Task 1, parse_page(page_id, text): one page from its text. The trap: a header value can hold a colon, and a page with no tags line has no tags, not one empty tag.
  • Task 2, load_pages(folder): every current page of a folder, by id. The trap: the ₹40 page must not come back.
  • Task 3, corpus_stats(pages): how many pages, their tokens, the biggest page. Kunal will ask: the help pages are about 9,000 tokens in all. Why not send every page to the model with every question, instead of searching for the right parts?

With the app running, send "Every help page", "The pages in tokens", "The Jain food page" and "The old delivery charges page" (which must answer 404). Then press Check. It parses made-up pages and DabbaDrop's own, and tells you the first thing that is not right yet. A first message looks like this:

parse_page("chai-break", text) raised an error: ValueError: too many values to unpack (expected 2)

That is a header line cut at every colon. And a folder read without the supersedes rule gives:

load_pages kept tea-old, which tea.md's supersedes line replaces: leave out every page another page supersedes

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    pages.py: read one help page

    Write parse_page(page_id, text) in app/corpus/pages.py. It returns a Page from one help page's text.

    The first line is the title ("# " then the title; title is the rest, stripped). Header lines follow, "key: value", up to the first blank line: split each on its first colon only, lower case and strip the key, strip the value. updated is the updated line's value as a date (date.fromisoformat); tags is the tags line split on commas, each tag stripped, as a tuple (an empty tuple when there is no tags line); supersedes is its value, or None when there is no such line. body is every line after that first blank line, joined with new lines and stripped. id is the page_id given.

    Raise ValueError, with the page's id in its message, when the first line does not start with "# " or there is no updated line.

    The Check parses a made-up page with a header whose value holds a colon, a page with no tags line, data/help/delivery-charges.md (supersedes delivery-charges-2025), and two broken pages.

  2. Task 2

    pages.py: load every page, without the replaced one

    Write load_pages(folder) in app/corpus/pages.py. Read every *.md file of the folder as UTF-8 and parse it with parse_page; a page's id is its file name without .md. Leave out every page whose id another page's supersedes names. Return the pages sorted by id.

    The Check loads a made-up folder (tea.md supersedes tea-old.md, biscuits.md, and a notes.txt that is not a page) and data/help, where delivery-charges supersedes delivery-charges-2025 (the old page that says delivery is ₹40); then GET /pages must list the 34 current pages and GET /pages/delivery-charges-2025 must answer 404.

  3. Task 3 · interview question

    Interview: pages.py, the pages in tokens

    Write corpus_stats(pages) in app/corpus/pages.py. Return a dict: "pages", how many pages there are; "tokens", the tokens of all their bodies together, each body counted with the given count_tokens; "largest", {"id": ..., "tokens": ...} for the page whose body has the most tokens (when two are as big, the first of them in the list), or None when the list is empty.

    The Check measures three made-up pages, two of the same size, then an empty list, then calls GET /pages/stats.

    Kunal will ask: the help pages are about 9,000 tokens in all. Why not send every page to the model with every question, instead of searching for the right parts?

What you will learn

  • The plan: what a copilot that answers from documents does, in the order this project builds it.
  • Reading a page: lines, a header of key: value lines, the first colon only, dates from ISO text, and a clear ValueError for a broken page.
  • A folder of pages: Path.glob, a file's stem, reading UTF-8, and leaving out a page another page supersedes.
  • Tokens: what a model reads, how tiktoken counts them, and what the count means for a model's window and its price.
  • Why not send every page: a real request that is too big.

More in The pages

Build The plan and the pages yourself

DabbaDrop answers the same customer questions all day. You build the copilot that answers them from its own help pages, with sources, and says so when it does not know. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.