Glossary

91 terms from RAG Basics, in plain words, each with the chapter that teaches it.

Search the glossary

#

@classmethod: A Python decorator that makes a method belong to the class instead of one object, so you call it as `Index.load("index")`. The method receives the class as `cls`.

A

all-MiniLM-L6-v2: A small sentence-embedding model that turns chunks and questions into 384-number vectors so they can be compared by meaning. It reads at most 256 tokens of text, and anything past that is ignored.
ANTHROPIC_API_KEY: The environment variable that holds the secret key letting your program call Claude. Keep it out of code; if it is missing, the Kettle & Crane code falls back to a free demo mode.
argparse: Python's standard module for reading command-line arguments. In `ask.py` it reads the question and the `--role` option, and writes `--help` for you.

B

Beautiful Soup: A Python package that parses an HTML page into a tree you can search and edit. Kettle & Crane's loader uses it to delete menus and banners and keep the main content.
BM25: A classic keyword-matching score that ranks chunks by how well their words match the query. It finds exact terms like `KC-ESP-5LB` that embeddings blur.
Boilerplate: Text repeated on every web page, such as menus, headers, footers and promo banners. If you leave it in, every page can appear to match a question about, say, shipping.
Budget: The most source text, counted in characters, that a prompt may hold. `format_sources` stops adding chunks before the total passes it, so one huge chunk can't make every question slow and costly.

C

Candidate pool: The shortlist of chunks (20 here) that hybrid search passes to the slower reranker, which keeps the best 5.
CCPA: The California Consumer Privacy Act, a privacy law of the kind that applies to the customer questions an assistant logs. Under such laws you should keep logs only as long as you need them.
Chunk: A short piece of a document, such as one heading section of a Kettle & Crane help article. It is the unit you embed, retrieve and show to the model, so it should answer a question on its own.
Citation: A marker such as [S1] that links a statement in an answer to the source it came from. A person can check it, and your code can verify it.
Closed book: Asking the model a question with no sources at all, so it answers from memory alone. It serves as the baseline for measuring how much retrieval helps.
Context header: The first line of a chunk, naming its document and section, for example `Shipping Policy > Rates`. It tells both search and the model what the chunk is about.
Contextual chunk header: A technique where a model writes a sentence of context for each chunk before it is embedded. It helps with long manuals where headings alone are not enough.
Cosine similarity: A score for how close two embedding vectors are in meaning: 1 for the same meaning, near 0 for unrelated. For normalized vectors it equals the dot product, which is why a single matrix multiplication can score every chunk.
curl: A command-line tool for sending HTTP requests. For example, `-X POST` sets the method, `-H` adds a header and `-d` supplies the JSON body when calling the Ask our docs API.

D

Dataclass: A Python class that just holds named fields, with `__init__` written for you by Python. It is used for simple records such as `Doc`, `Chunk` and `Answer`.
Decorator: A line starting with `@` above a function that registers or changes it. In FastAPI, `@app.post("/ask")` registers the function as the handler for POST requests to `/ask`.
Demo mode: A free mode, turned on by `RAG_DEMO=1` or a missing API key, where every model call is replaced by a simple stand-in. All the code still runs, but demo answers start with `[demo]` and are poor.
Doc: A dataclass holding one loaded document or PDF page: its `source`, `title`, `text` and `meta`.

E

Effort: A setting for how much hidden thinking a model does before answering. Low effort makes replies cheaper and faster.
Embedding: A list of numbers (a vector) that captures the meaning of a text. Texts with similar meaning get similar vectors, so you can search by meaning.
Endpoint: A URL that programs send requests to. Kettle & Crane's help widget calls the `/ask` endpoint with a question.
Environment variable: A named setting stored outside your code, in your terminal session. It keeps secrets and options such as `ANTHROPIC_API_KEY`, `RAG_MODEL` and `RAG_DEMO` out of source files.
Evaluation set: A file of real questions, each labeled with the documents and reference answer that settle it. Here it is 35 questions, four of them unanswerable, used to measure retrieval and answer quality.

F

Faithful (grounded): An answer is faithful when every claim in it is supported by the sources the model was shown. A correct answer can still be unfaithful if it was right by luck.
FastAPI: A Python framework that turns typed functions into web API endpoints and checks request bodies against Pydantic classes. It serves the Ask our docs API.
Fine-tuning: Training a copy of a model further on your own examples. It teaches style, format or a narrow task, not reliable facts.
Fixed-size chunking: Cutting a document every set number of characters, often with overlap. It is simple but splits ideas mid-sentence and leaves headings behind.
Front matter: `key: value` lines between two `---` lines at the top of a Markdown file, such as `title` and `updated`. The loader moves them into the document's metadata.

H

Hallucination: A confident statement from a model that isn't true or isn't supported by any source. It happens when the model guesses about things, like Kettle & Crane's returns policy, that it never read.
Hash: A short fingerprint of a file's contents that changes whenever the file does. Storing one per document lets you re-embed only the files that changed.
Hit rate at k (hit@k): The share of questions for which at least one relevant document appears in the top k results. A hit@1 of 0.94 means the right document was first for 94% of questions.
HTTP header: Extra named information sent with an HTTP request. The Ask our docs API reads the `X-API-Key` header to decide which role the caller has.
HTTP status codes: Numbers a web server returns to say what happened: 200 OK, 401 unknown API key, 422 invalid request (such as a missing header).
Hybrid search: Combining vector (meaning) search and keyword search results into one ranking. It helps when users type exact codes like `KC-ESP-5LB`.

I

Indexing: The half of RAG that runs when documents change: load, chunk, embed and store. The saved result is the index that each question later searches.

J

JSONL: A file format with one JSON object per line, easy to append to and read line by line. It stores saved chunks, evaluation questions and evaluation results.

K

keep filter: A function passed to search that decides which chunks may be returned. Because it runs before retrieval, customers never see staff-only chunks.
Knowledge cutoff: The date a model's training data ends. Anything newer, and anything private like Kettle & Crane's policies, is unknown to it.

L

LangChain: An open-source framework of small, composable LLM and RAG components such as document loaders, text splitters and vector stores. It can handle loading, splitting and retrieval while your own code writes the answer.
Layout mode: A pypdf text-extraction option that keeps text where it sits on the page, so table rows stay together with their prices.
LlamaIndex: An open-source framework for loading, indexing and querying documents. A folder can be indexed in about three lines, but it may load files badly, such as HTML as raw markup.
LLM-as-judge: Using a model to grade another model's answers for correctness, faithfulness and refusal. It is cheap enough to run after every change, but you must check it against your own hand labels.
Long context: Pasting all your documents into every prompt instead of retrieving. It suits small, stable collections but its cost grows with the whole collection.

M

Metadata: Data about a document: its source path, update date, audience and PDF page. It later powers citations, newest-version rules and access filters.
MRR: Mean reciprocal rank: the average, over all questions, of 1 divided by the rank of the first relevant result. It rewards putting the right document near the top.

N

Node: LlamaIndex's word for a chunk.
Normalized vectors: Vectors scaled to length 1. With them, a plain dot product gives the cosine similarity, so one matrix multiplication scores every chunk.
NumPy: A Python library for fast arrays of numbers. It stores chunk vectors in a saved `.npy` file and computes all the dot products against a query with `@`.

O

OCR: Optical character recognition: software that reads text from images. A scanned PDF needs OCR before you can extract any text.
Overlap: Letting neighbouring fixed-size chunks share some characters so a sentence cut at one boundary survives in the next piece. It softens bad cuts but doesn't make pieces meaningful.

P

Personal data: Details that identify a person, such as names, emails and phone numbers in the wholesale account notes. Keep it out of the index, since the index is one more copy to protect.
pip install: The command that downloads and installs Python packages, such as `pip install anthropic pypdf`.
POST: The HTTP method for sending data to a web endpoint. The question goes in a POST request's JSON body.
Presidio: Microsoft's open-source tool for finding and removing personal data, including names and addresses that simple patterns miss.
Prompt caching: A feature where the model provider stores an unchanged start of your prompt and charges much less to reuse it. It doesn't help the RAG prompt, since sources change per question, but it does cut long-context costs.
Prompt injection: Text that tries to give the model new instructions. In RAG it can hide inside a document, such as a poisoned review telling the assistant to send customers to a fake refund address.
Pydantic: A Python library for describing data shapes as classes and checking data against them. It defines structured model output such as `Claim` and `Verdict`, and the request bodies FastAPI accepts.
pypdf: A pure-Python library for reading PDF files page by page. Its layout mode keeps table rows together, so a price stays next to its product.
pytest: A Python test runner that runs every function named `test_...` and fails it if an `assert` is false. Running tests in demo mode keeps them free and repeatable.

Q

Query half: The half of RAG that runs for every question: retrieve, prompt, answer and cite.
Query rewriting: Before retrieving, having the model turn a follow-up like "How long does it take to get there?" into a question that stands alone. Search can't use the raw follow-up.

R

RAG: Retrieval-augmented generation: for each question, find the passages most likely to hold the answer, put them in the prompt as named sources, and have the model answer only from them. The model reads instead of remembering.
Recall at k: The share of all relevant documents for a question that appear in the top k results, averaged over questions.
Reciprocal rank fusion (RRF): A way to merge rankings from different searches: each chunk gets 1/(60 + rank) from each list and the scores are summed. This avoids mixing incompatible score scales.
Redaction: Removing or masking personal data such as emails and phone numbers from text, here with regular expressions, before the text is chunked and indexed.
Reference answer: The staff-written correct answer for an evaluation question. The judge compares the assistant's answer against it.
Refusal ("I don't know"): The fixed sentence the model gives when the sources don't answer the question. A fixed wording lets your code detect a non-answer.
Regular expression: A compact pattern for finding or splitting text. Regexes can find citations like `[S3]`, emails, phone numbers and sentence ends.
Reranker: A model (a cross-encoder) that reads the question and each candidate chunk together and scores the match. It is slow, so it only sees a shortlist, but it gave the biggest retrieval gain in Kettle & Crane's evaluation.
Retrieval: The first RAG step: finding the few passages most likely to contain the answer. The prompt is then augmented with them and the model generates an answer from them.

S

Scanned PDF: A PDF that is a picture of text with no text layer, so `extract_text()` returns nothing. You need OCR first.
Search result block: A Claude API content block holding one source (chunk). With citations enabled, the reply's text blocks point back at the blocks they used.
sentence-transformers: A Python library that runs embedding models and cross-encoder rerankers locally. It supplies both the embedding step and the reranking step of retrieval.
Small-to-big: A retrieval idea that searches small chunks but sends the model the whole section around each hit, getting precise search and fuller context.
Source tag: The `<source id="S1">…</source>` wrapper that labels each retrieved chunk in the prompt. The short ID is what the model cites and your code maps back to a chunk.
Standalone question: A question that makes sense without the earlier conversation. For example, "How long does shipping take to Puerto Rico?" is the standalone form of "How long does it take to get there?".
Streaming: Sending a reply in pieces as it is generated, so the first words appear within a second. Checks that need the full text, such as citation checks, can only run at the end, so sources or a retraction come last.
Structured output: Getting the model's reply as a filled-in Pydantic object rather than free text. It is used for quoted claims and judge verdicts.
Superseded document: An older version of a document, such as the 2024 shipping policy, that a newer one replaces. Dropping it at indexing time keeps old prices from leaking into answers.
System prompt: The instructions given to the model before the user's message. In RAG it holds the rules: use only the sources, cite, and say "I don't know".

T

Threshold: A retrieval score below which you skip the model entirely and answer "I don't know". A cutoff of -10 on reranker scores catches only the two lowest-scoring evaluation questions, so it works alongside the prompt rule.
Token: The small pieces of text a model reads and bills by. English averages about four characters per token.
Tokenizer: The code that splits text into a model's tokens. Using the embedding model's own tokenizer lets you check that chunks fit under its 256-token limit.

U

uvicorn: The web server that runs a FastAPI app. `uvicorn api:app` means the `app` object in `api.py`.

V

Vector database: A database built to store and search embeddings at large scale. A plain NumPy file is enough for small collections, while tools like Chroma or pgvector suit beyond tens of thousands of chunks.
Vector search: Finding chunks whose embeddings are closest to the question's embedding, so it matches meaning rather than exact words.
Vector store: Where embeddings are kept for searching. In a simple setup it is just a NumPy array plus a file of chunks.
Virtual environment: An isolated Python setup for one project, created with `python3 -m venv .venv`, so its packages don't clash with others.