Start here · Chapter 1

How to read this book

What the five parts cover and where to read them, what the boxes, widgets and checklists mean, how the book keeps your progress, how to ask an AI about a passage, how to reuse the book with credit, and how to help correct and improve it.

The shape of the book

The book climbs a ladder. Each rung uses only what the rungs below it taught, and the labs in Part V let you build what the rungs describe.

Part	What you learn	You can skip it if
I. Maths	Functions, logs, vectors, matrices, derivatives, gradient descent, probability, statistics, softmax and entropy. Everything later needs these.	You are comfortable with calculus and probability. Try each chapter's self-check to be sure.
II. ML foundations	What it means for a program to learn from data, how neural networks train, and the history of the problems that shaped them. Ends with a network you train yourself.	You have trained a neural network before.
III. How LLMs work	Tokens, embeddings, attention, the transformer and how large language models are trained and tuned. Ends with a tiny language model you train yourself.	You know how a transformer works inside.
IV. Applied concepts	The building blocks of an AI application: prompts, context, retrieval, tools, agents, MCP, guardrails, security, hallucination, memory, frameworks, quantisation, fine-tuning, production, evaluation and observability.	Never: these are the ideas the labs put to work.
V. Build it	Eleven labs in Python. You make a model call, test prompts, build retrieval with citations and measure it, write an agent and an MCP server, add guardrails, a judge and tracing, and put them together.	Never, if you want hands-on experience: this is the point of the book.

The cover gives three reading paths: Build now starts with the labs and dips into the concepts each one needs, Foundations reads Parts I to III in order, and Shipping covers running AI that other people rely on.

Where to read it

The book is free and needs no account. Its source is one public repository, aggarwaldev/build-ai-handbook on GitHub, and the website publishes that repository's book/ folder, so the pages are the same wherever you read them. There are three ways to open it:

Way	How	Progress
Online	Open handbook.aggarwal.dev in a browser, on a computer or a phone. On a narrow screen the contents fold behind the menu button.	Kept in that browser, for the website's address.
From disk	Get a copy of the repository (below) and double-click `book/index.html`. It needs no network, except for links to other sites and Ask AI.	Kept in Chrome and Edge. Firefox and Safari may refuse it (see below).
Served on your computer	In a copy of the repository, run `python3 tools/serve.py` and open `http://127.0.0.1:8765/` (see below).	Kept in every browser, for that address.

To get a copy, clone the repository with git, or download it as a ZIP and unpack it. The labs need the same copy.

git clone https://github.com/aggarwaldev/build-ai-handbook
cd build-ai-handbook                   # the repository root: book/, labs/ and tools/

Each address keeps its own progress, even in the same browser: the website, the book opened from disk and the book served on your computer start with separate records. To move your progress from one to another, or to join two records, use Export on the progress page at one address and Import at the other.

The website sets no cookies, runs no analytics and loads nothing from other sites: every script, style and image comes from the site itself. Your progress and notes stay in your browser. If you give Ask AI your own Anthropic API key, your question and the passage go from your browser straight to Anthropic, and nothing goes to the website (see below).

Serving the book on your computer

tools/serve.py serves your copy of the book on your own machine, for browsers that keep no progress for pages opened from disk. It uses only the Python standard library and holds no keys.

python3 tools/serve.py                 # or pick the port: --port 8800
# then open http://127.0.0.1:8765/

It listens on 127.0.0.1 only and answers only requests addressed to it there. It serves files from book/ only, and only of these kinds: HTML, CSS, JavaScript, SVG, PNG, JPEG, WOFF2, JSON, text, Markdown and Python. Any path with a part that starts with a dot, such as .git or .env, is refused, and so are folder listings.

Conventions

How the book names files

A file path looks like labs/03-rag/rag.py. Paths are named from the root of the book's repository, the folder that holds book/, labs/ and tools/; the pages themselves are in book/. tools/check_book.py checks that every path under those three folders exists. When a function or class matters, the book names it too. It never cites line numbers: they change with every edit, and a wrong line number is worse than none. To find a name, search the file for it.

The boxes

Why it matters

Explains the problem an idea solves. If you remember only one thing from a section, remember this.

Careful

A common mistake, or a rule that must not be broken.

Note

A side remark that helps but is not essential.

Build it

Sends you to the lab where you build the idea yourself. For example, Lab 0 sets up Python and a model backend for every other lab.

How the maths is written

Every formula comes after a worked example with real numbers, so you see the arithmetic before the symbols. Formulas are written in plain HTML, like this one for the average of three numbers:

mean = 2 + 4 + 93 = 153 = 5 Numbers first.

μ = 1n Σ_i=1ⁿ x_i Then the symbols: μ (the Greek letter mu) is the mean, Σ means "add up", and x_i is the i-th number.

The maths chapters end each idea with a Try it exercise. The answer sits in a box that opens on click. Work it out first; that is where the learning happens.

Interactive widgets

Widgets are labelled Try it. They run in your browser, use no network, and send nothing anywhere. Some use toy data, which the widget says plainly: a widget about embeddings, for example, uses vectors of six hand-picked numbers, not the hundreds of numbers a real embedding model produces. The ideas are the same; only the size differs.

Self-checks

Each chapter ends with three or four questions. Answer in your head, then click a question to see its answer. The progress page counts the answers you have opened, so you can see which chapters you checked yourself on.

Example: why does the book show numbers before symbols?

Because a formula is a summary of arithmetic you have already done. Seeing the arithmetic first makes each symbol name something you have met.

Checklists and your progress

The book keeps a record of your reading and building, so you can stop and pick up where you left off. There is no account and nothing leaves your computer.

Checklists. Each lab lists its steps as a checklist. Tick a step when you have done it and seen the result the lab describes. When every step on a page is ticked, the page is marked done for you; the message that says so has an Undo button.
Done. Every chapter and lab has a Mark this chapter done box above its previous and next links. Tick it when you have finished; it shows the date. Untick it to take it back.
My notes. Beside it is a notes box for that page. It saves as you type.
The sidebar shows a tick beside pages you have finished, a dot beside pages you have opened but not finished, and done/total for each part. The progress link in the top bar shows the percentage of chapters and labs done.
Your progress shows it all: where to continue, each part and lab, recent activity, your notes and the self-check answers you opened.

Progress is stored in this browser, in its IndexedDB storage (or its local storage if IndexedDB is not available). Clearing the site's data deletes it, and another browser or device starts empty. It also belongs to the address the book was opened from, so the website and a copy on your computer keep separate records (see above). To back it up or move it, use Export on the progress page, then Import on the other side: an import merges, keeping the newer record wherever both sides have one.

Careful

Opened straight from disk, the book keeps progress in Chrome and Edge, but Firefox and Safari may refuse storage for such pages or keep each page separately. If your ticks do not survive a reload, or every page shows a notice that progress is not being saved, read the book on the website, or serve your copy: run python3 tools/serve.py from the repository root and open http://127.0.0.1:8765/. Then export from the old address and import at the new one to bring your progress with you.

Ask AI about any passage

Select some text on any page and an Ask AI button appears beside it. It opens a small panel with your selection, the chapter title and a box for your question. Only those three things go into the question: the book's own text and what you type.

The default: Claude in a new tab

The panel builds one prompt from the chapter title, the selection (trimmed to 1,500 characters) and your question, and offers three ways to use it:

Copy prompt, the reliable way: it copies the prompt and opens a new Claude chat in a new tab, and you paste it there.
Open in Claude opens claude.ai/new with the prompt passed in the address as ?q=. Anthropic does not document this link, so the box may arrive empty or the behaviour may change; if it does, use Copy prompt.
Open in Claude Desktop uses the desktop app's documented link, claude://claude.ai/new?q=, which fills the prompt in for you to read and send. It needs the Claude desktop app installed.

You need to be signed in to Claude. Nothing else is needed: no key and no server.

Optional: answers in the page, with your own API key

With an Anthropic API key of your own, the panel can answer in the page itself, wherever you read the book: on the website, from disk or served on your computer. Under Answer here with your own API key in the panel, paste your key and press Use this key. The panel then shows an Ask here button.

What is sent, and where. Ask here sends the chapter title, the selection (trimmed to 3,000 characters) and your question from your browser straight to the Anthropic Messages API, and nowhere else: not to the website and not to tools/serve.py. It asks the model claude-haiku-5-5, unless you name another in the panel's Model box, with a limit of 2,048 output tokens. Current Claude models think before they answer and the thinking counts toward that limit, which is why it is not smaller. The panel shows only the text of the answer.
Where the key is kept. In this browser only, and by default for this tab only: it is gone when you close the tab. Tick Remember the key in this browser to keep it until you press Forget the key. A page opened from disk does not offer the box, because files opened from disk can share one storage area, so another file could read the key. The key goes only to Anthropic, in the request's x-api-key header. It is never part of the prompt or of an address, and a progress export leaves it out.
What it costs. Each answer is billed to your key, as any API call is. The book sets no limit of its own; your Anthropic account's limits apply.
When it fails. The panel shows Anthropic's own error message, such as a key it does not accept or a rate limit. Copy prompt and the Claude links still work.

Careful

Anyone who has your key can spend your money. Make a separate key for the book, as Lab 0 describes, with a monthly spend limit set in the Console. Delete it in the Console when you no longer need it, or at once if you think someone else has seen it. While the key is kept, a browser extension that may read this site's pages can read the key too, so do not keep one on a shared computer.

Running the labs

The labs in labs/ are small Python programs with tests. Lab 0 walks through the setup; in short:

python3 -m venv .venv
source .venv/bin/activate              # on Windows: .venv\Scripts\activate
pip install -r labs/requirements.txt
python labs/01-first-call/first_call.py "Say hello in five words"
cd labs && python -m pytest           # every lab's tests, offline

Python 3.10 or newer. The numbered labs need only anthropic, numpy and pytest; the projects in chapters 15, 20, 30 and 41 list their own extras in their folders.
The environment variable LLM_BACKEND picks who answers: anthropic (Claude, with your ANTHROPIC_API_KEY), ollama (a free model running on your computer) or fake (a scripted stand-in that needs nothing). The tests always use the fake backend, so they cost nothing and need no network.
Every lab page says what a run costs on Claude and how that was worked out. Ollama and the fake backend cost nothing.
To run a lab without installing anything, use the buttons near the top of its page. Open in Colab (with a Google account) and Launch on Binder (no account, but slow to start) open the lab's notebook from labs/notebooks/, which follows the page step by step. Open in Codespaces (with a GitHub account) opens the whole repository on a machine already set up, where the commands above work as written.

Reusing and crediting the book

You may copy, share, translate and adapt the book for any purpose, as long as you give credit. Two licences cover it:

The text, meaning the prose, figures and diagrams of the pages in book/, is under Creative Commons Attribution 4.0 (CC BY 4.0); the repository's LICENSE-TEXT says so. Give credit, link to the licence and say whether you changed anything.
The code, meaning everything under labs/, tools/ and book/assets/, the notebooks and the code samples in the pages, is under the MIT License. Keep its copyright and licence notice with any copy of the code.

A credit line you can copy:

"Build AI handbook" by Dev Aggarwal, https://handbook.aggarwal.dev/,
licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/

If you changed the text, add what you changed, such as "Adapted: chapter 6 shortened and translated into Spanish." When you reuse one chapter, you may link to its page instead of the cover. The credit must not suggest that the author endorses you or your use.

Help improve the book

The book is open source, and corrections and improvements are welcome from anyone who reads it. You do not need to be an expert: a reader who got stuck on a step knows exactly where it is unclear. What helps most:

Report a mistake or a problem. A wrong number, a lab that fails, an unclear step, a dead link or a page that misbehaves in your browser: open an issue on GitHub. Name the page and the section, say what you saw and what you expected, and give your browser or operating system if it matters. The list of issues shows what others have reported already.
Fix it yourself. Every page ends with an Edit this page link to its source on GitHub, where you can make the change and propose it as a pull request. A single typo or stale price is worth a pull request on its own.
Improve a lab or its tests. The labs are in labs/, and their tests run on the fake backend. A clearer step, a test for a case a lab misses, or a fix that makes a lab run on another system all help.
Propose a chapter or a lab. Open an issue first and describe what it would teach and where it would fit, so the idea can be agreed before you spend time writing it.

Issues and pull requests need a free GitHub account. The contributing guide says how to set up a copy, which checks to run and how to send a change.

Keeping this book current

Models, prices and APIs change quickly, so parts of a book like this go out of date. It stays correct when readers point out what has changed: if you find something stale, report it or fix it as above; the contributing guide says how to send the change. The rest of this section is for anyone changing the pages: the scripts that keep them consistent, and how to add a page.

The book is plain HTML, CSS and JavaScript, with helper scripts in tools/. The scripts run with plain python3 and need nothing installed; the tests in tools/tests/ need Node.

Script	What it does	Run it when
`tools/build_search_index.py`	Reads every page's headings, the glossary and the lab checklists into `book/assets/search-index.js`, which the search box, the glossary hover and the progress page use. `--check` only reports whether the file is stale.	After you add a page, a heading, a checklist item or a glossary entry.
`tools/build_site_meta.py`	Writes a marked block in each page's `head`: a description from the page's lead paragraph, its address on the website, the icon and the tags that link previews read. It also writes `book/sitemap.xml` and `book/robots.txt`. `--check` only reports what is out of date.	After you add a page, or change a page's main heading or lead paragraph.
`tools/check_links.py`	Checks that every internal link points at a file that exists, and at an `id` that exists in it.	Before every commit.
`tools/check_book.py`	Checks the book's structure: every page is in the contents list and loads the shared files, titles follow the pattern, heading ids are unique, checklist ids are unique and named after their page, callouts use the four kinds above, and every path in a `code class="path"` under `labs/`, `tools/` or `book/` exists. It also checks that the repository and website addresses in `book/assets/handbook.js` match the ones the Python tools use.	Before every commit.
`tools/serve.py`	Optional: serves the book on 127.0.0.1, for browsers that keep no progress for pages opened from disk (see above).	When your ticks do not survive a reload of a page opened from disk.
`tools/tests/`	Tests for the progress tracker, the footer's links and the Ask AI request, run with `node --test tools/tests/*.test.js`.	After you change `book/assets/progress.js` or `book/assets/handbook.js`.

python3 tools/build_search_index.py
python3 tools/check_links.py
python3 tools/check_book.py
node --test tools/tests/*.test.js
cd labs && python -m pytest

The repository's continuous integration runs the same checks, and the lab tests, on every push and pull request.

Adding a page

For a new chapter or lab, open an issue first (above), so its place in the book is agreed before you write it. Then:

Copy an existing page in book/, such as this one, and change its title, kicker and body. Keep the head, the sidebar nav and the pager nav as they are. The title ends with · Build AI handbook.
Add the page to the BOOK list at the top of book/assets/handbook.js, on one line like its neighbours. The sidebar, the previous and next links, the search and the progress tracker all follow that list.
Add a card for it to the contents on book/index.html.
Give every h2 and h3 an id, so search can link to it.
For a lab, end its steps with <ul class="checklist">, one <li data-check="page-name:step"> per step, where page-name is the file name without .html.
Run the search index, the link check and the book check.

Widgets live in book/assets/widgets/, one file per widget, each loaded only by the pages that use it. They use the small helpers in book/assets/handbook.js (HB.el, HB.svg, HB.fmt) and read colours from the CSS variables, so they follow the light and dark themes.

Self-check

Why does the book never cite line numbers?

Line numbers change with every edit above them, so they go stale quickly and send readers to the wrong place. A file and a function name stay correct much longer, and a search finds them.

You add a new chapter file. What else must change for it to appear in the sidebar?

The BOOK list in book/assets/handbook.js. Then add a card to the contents in book/index.html, and rerun tools/build_search_index.py so search finds its headings.

You ticked steps in a lab, opened the book on another computer, and the ticks are gone. Why, and what do you do?

Progress lives only in the browser where you made it. Export it from the progress page on the first computer and import the file on the second; the import keeps the newer record wherever both have one.

A widget shows six-number vectors for embeddings. Is that what real systems use?

No. Real embedding models produce hundreds or thousands of numbers per text. The widget uses six so you can read every number; the maths is identical.