Glossary

Terms in alphabetical order, each with the chapter and the file where it is defined and a one-line statement of what it means.

Use it when you remember the shape of an idea and not its name.

agent — Introduction, 00-introduction.md. A program that calls a model in a loop, runs whatever tool the model asks for, and stops when the model stops asking. The model picks the next step. This book does not build one.

agentic workflow — Introduction, 00-introduction.md. A workflow in which some of the jobs are carried out by a language model rather than by a person or by code written in advance.

API key — Introduction, 00-introduction.md. A secret string identifying your account to a service, meant to be read by programs rather than typed by people. Kept in the environment, never in a source file.

as-of date — Chapter 9, 09-a-corpus-you-can-trust.md. The date a fact was true as of: the day its source was read, not the day the law was enacted. Carried on every law and shown under every answer.

batch — Chapter 11, 11-measuring-the-whole-thing.md. A request to the API’s batch endpoint carrying many message requests at once, run at half the price, with results that come back in minutes, in any order, matched back by an id the caller chose.

BM25 — Chapter 4, 04-finding-it-by-its-words.md. A scoring function that ranks documents by how well their words match a query’s, combining term frequency, inverse document frequency and length normalisation.

checker — Chapter 3, 03-the-check-that-is-not-the-model.md. Code that decides whether a model’s output may be used, from the output and the inputs alone, without consulting the model.

chunk — Chapter 2, 02-writing-from-a-book.md. One piece of a section, usually a subsection, cut to the size retrieval works with: a paragraph, not a page.

citation — Introduction, 00-introduction.md. The record of which source an answer rests on: the page or the section, with the source’s own words beside it.

context window — Chapter 1, 01-talking-to-a-model.md. The maximum number of tokens that can be in a single request and its response combined. Exceed it and the API returns an error.

corpus — Introduction, 00-introduction.md. The body of text retrieval searches: here, a state’s driver manual, vehicle code, fine schedule and the licensing agency’s own pages.

cosine similarity — Chapter 5, 05-finding-it-by-meaning.md. The cosine of the angle between two vectors: 1 for the same direction, 0 for unrelated. How two embeddings are compared.

cross-encoder — Chapter 7, 07-choosing-what-it-reads.md. A small model fitted to take a question and one candidate and produce a score. Fast, and it scores by likeness, which is its limit.

degradation — Chapter 10, 10-failing-closed.md. The shape of doing less: each optional stage, when absent or failing, leaves the pipeline exactly as it was before that stage existed.

embedding — Chapter 5, 05-finding-it-by-meaning.md. A list of numbers a model produces from a piece of text, built so that two texts with similar meaning produce lists that point in similar directions.

eval — Chapter 11, 11-measuring-the-whole-thing.md. A harness run against the live model to measure how the whole pipeline answers, as opposed to a test, which measures one part with the model held still. Run by hand, on purpose.

fail closed — Chapter 10, 10-failing-closed.md. What a system does when a missing or broken part makes it do less rather than something wrong. For this pipeline, less means fewer stages or an honest refusal; wrong means an unchecked sentence on the screen.

figure — Chapter 2, 02-writing-from-a-book.md. A number a law states: a distance, a speed, a fine, an age, a count of days. The thing the check is built around.

fine schedule — Chapter 2, 02-writing-from-a-book.md. The court’s own list of what each offence costs, whether it can be paid without a court date, and the points. Keyed by section, and in no section of the code.

golden set — Chapter 11, 11-measuring-the-whole-thing.md. A fixed list of inputs with the facts a right output must carry, checked against the source by a person before they went in.

grounding — Chapter 3, 03-the-check-that-is-not-the-model.md. A figure is grounded when a source the answer cites states it, or the learner’s own question did, and an answer is grounded when every figure in it is.

harness — Chapter 11, 11-measuring-the-whole-thing.md. The program that runs a set of cases through the thing being measured and scores the results.

hash — Chapter 9, 09-a-corpus-you-can-trust.md. A fixed-length fingerprint of some text, SHA-256 here, that changes if a single byte of the text does. Recorded beside every fetched file.

inverse document frequency — Chapter 4, 04-finding-it-by-its-words.md. How rare a word is across all the documents. A word in every document scores near zero; a word in one document scores high.

join key — Chapter 8, 08-once-found-look-it-up.md. The value two records share that lets one be looked up from the other. Here, the section: the code’s subsections, the court’s schedule rows and the duty all carry it.

JSON schema — Chapter 1, 01-talking-to-a-model.md. A description of a JSON value: which fields it has, what type each is, which are required, and which values a string may take. Sent with a request to constrain the reply.

large language model — Chapter 1, 01-talking-to-a-model.md. A very large mathematical function that takes a sequence of text and produces a probability distribution over what text comes next, fitted on an enormous quantity of text.

manifest — Chapter 9, 09-a-corpus-you-can-trust.md. A committed record of what was last pushed somewhere outside the repository, in a form a test can recompute: a hash per state over the ids and the exact text embedded.

message — Chapter 1, 01-talking-to-a-model.md. One contribution to the exchange with a model: a role saying who is speaking and content saying what they said.

model ID — Chapter 1, 01-talking-to-a-model.md. The exact identifier of the model a request runs against. The field has no default.

mutation — Chapter 12, 12-tests-that-never-call-the-model.md. A deliberate change to the code that introduces the failure a test is for. A test that stays green under its mutation is a test of nothing.

namespace — Chapter 5, 05-finding-it-by-meaning.md. A partition of a vector index that a query is confined to. One per state, so a Maryland question can return no other state’s law.

outage — Chapter 10, 10-failing-closed.md. A stretch in which the model cannot be reached at all. Named in the log differently from a refusal, because the two are different problems with different fixes.

pool — Chapter 6, 06-saying-it-the-laws-way.md. The list retrieval hands to the reranker: 24 laws, or 32 when rephrased searches were fused into it, plus any agency-page rows for the family the rephraser named.

precision — Chapter 5, 05-finding-it-by-meaning.md. The fraction of the laws a search returns that answer the question.

prompt — Chapter 1, 01-talking-to-a-model.md. The text you give the model to act on: every message in the array plus the system field.

prompt caching — Chapter 2, 02-writing-from-a-book.md. The API keeping a copy of the beginning of a request so that the next request with the same beginning is charged a tenth of the price for that part. Matches on a prefix.

RAG — Introduction, 00-introduction.md. Retrieval-augmented generation: a model writing from retrieved sources rather than from memory. Find the right text, give it to the model, check what comes back against what you gave it.

recall — Chapter 5, 05-finding-it-by-meaning.md. The fraction of the laws that answer a question that a search returns.

reciprocal rank fusion — Chapter 5, 05-finding-it-by-meaning.md. Merging ranked lists by position rather than by score: a law in position r contributes 1 / (k + r) to its total, summed across every list it appears in.

refusal — Chapter 1, 01-talking-to-a-model.md. A stop reason meaning the model’s own safeguards declined the request. Arrives as a successful response with no answer in it. Distinct from the check’s refusal, which is code declining an answer the model did give.

register — Chapter 2, 02-writing-from-a-book.md. The voice an answer is written in: who it is written for, how long it runs, what it leaves out. Here, two sentences for a sixteen-year-old.

rephrase — Chapter 6, 06-saying-it-the-laws-way.md. To produce one or two searches in the code’s vocabulary that would find the law answering a learner’s question.

reranker — Chapter 7, 07-choosing-what-it-reads.md. A stage that takes a pool of candidates and the question, and orders the candidates by whether they answer it rather than by whether they resemble it.

retrieval — Introduction, 00-introduction.md. The job of finding, in a body of text too large to send whole, the few passages most likely to answer a question.

role — Chapter 1, 01-talking-to-a-model.md. Who is speaking in a message: user for you or your program, assistant for the model.

scope — Chapter 1, 01-talking-to-a-model.md. Which kind of thing a question is asking about. The pipeline built here answers one kind, road law, and sorts everything else as other.

scripted model — Chapter 12,12-tests-that-never-call-the-model.md. A function with the asker’s signature that returns replies you wrote, in order, and records what it was asked. No network, no model, and it can be made to say anything.

SDK — Introduction, 00-introduction.md. A software development kit: a library wrapping a service’s HTTP interface in ordinary functions.

section — Chapter 2, 02-writing-from-a-book.md. The unit a code is organised in, such as § 21-1003 of Maryland’s Transportation Article. Divided into lettered or numbered subsections.

source — Introduction, 00-introduction.md. One passage of the corpus that an answer may rest on.

stateless — Chapter 1, 01-talking-to-a-model.md. Retaining nothing between requests. Every request is answered from scratch using only what it contains.

stemming — Chapter 4, 04-finding-it-by-its-words.md. Reducing a word to a form that matches its variants, so that hydrants finds hydrant. Here, one rule: a word longer than three letters loses a single trailing s, unless it ends in ss.

stop reason — Chapter 1, 01-talking-to-a-model.md. Why the model stopped: end_turn when it finished, max_tokens when it hit the ceiling, refusal when its safeguards declined.

stop word — Chapter 4, 04-finding-it-by-its-words.md. A word that says nothing about which law is meant: a, the, how, can. Dropped before anything is counted.

structured output — Chapter 1, 01-talking-to-a-model.md. A reply constrained to match a schema sent with the request. The API guarantees the shape; the code checks it anyway.

subsection — Chapter 2, 02-writing-from-a-book.md. One of the lettered or numbered parts a section is divided into: (a), (b), (m). The unit retrieval works with.

system prompt — Chapter 1, 01-talking-to-a-model.md. A separate top-level system field carrying instructions about how to behave, as opposed to what to answer. Where the rules go; the laws go in the user message.

timeout — Chapter 1, 01-talking-to-a-model.md. The longest a program waits for a reply before giving up on it. Five seconds for a side job; the SDK’s default is ten minutes.

token — Chapter 1, 01-talking-to-a-model.md. The unit of text a model operates on: a run of characters somewhere between a letter and a word. What you are billed by, what max_tokens counts, and what the context window bounds.

vector — Chapter 5, 05-finding-it-by-meaning.md. The list of numbers an embedding model produces: 1,024 of them, for any text, in any language the model was fitted on.

vector index — Chapter 5, 05-finding-it-by-meaning.md. A store of vectors, each under an id, that answers one question: which of these are nearest to the vector I am holding? Only ids come back from it.

verbatim — Chapter 2, 02-writing-from-a-book.md. The source’s own characters, unchanged. Every hand-written statute’s quote and every code chunk’s is, and a test finds each in its committed section file.

workflow — Introduction, 00-introduction.md. A fixed sequence of jobs that a piece of work passes through, where each job has one responsibility and a defined output.