(Part A and Part B) we built the upgraded pipeline and watched it work: pointed at a research paper, a NIST standard, and a report with a broken table of contents, it returned a typed, cited answer each time. So why does it work? And would a naive RAG, the kind almost everyone builds first, embed the pages, keep the closest few, ask, have done the same?

This article runs the two side by side. The short answer is no, and the useful part is where the naive one breaks: not in one place, but at each of the four bricks in turn, document parsing, question parsing, retrieval, and generation, each time for a reason you can name and fix.

It is also why the usual reflexes — rewrite the prompt, shrink the chunks, swap the embedding model — do not help. The wrong answer does not come from the prompt. It comes from a brick upstream handing the model the wrong context, which the model then answers faithfully. Getting all four bricks right, not just the prompt, is what this series calls context engineering. Every failure below is a real run, never an assumed one; the companion notebook reproduces each one. Article 7quinquies (most RAG hallucinations are retrieval failures) makes the same case at the retrieval level on one document; this one shows it across all four bricks.

where this article sits: a companion to Article 9 (the upgraded pipeline), in Part III – Image by author

📓 The runnable notebook for this article is on GitHub: doc-intel/notebooks-vol1. It runs the naive baseline and the upgraded pdf_qa side by side on each document below, prints both answers with their confidence, and reproduces every cross in the figures on your own machine.

The public companion-code repo at doc-intel/notebooks-vol1 – Image by author

1. The naive baseline, brick by brick

The baseline is the 100-line pipeline from Article 1 (minimal RAG): parse the PDF, turn the question into keywords, keep the top few pages by match, ask the model to answer. On a short, clean, prose paper it works, and Article 9’s own tests confirmed it: on Attention Is All You Need and the RAG paper, naive and upgraded both answer correctly.

The upgraded pipeline is the same four bricks, each with a tighter contract: parsing returns a relational line_df instead of flat text, question parsing expands the query into the document’s vocabulary, retrieval routes on the table of contents, generation returns a typed answer. A naive RAG runs the loose version of every brick. The gap opens exactly where each loose brick hands the model the wrong thing. Each section below isolates one brick: it swaps that brick for its naive version and leaves the others reasonable, so the failure, and the fix, belong to the brick named in the heading.

The same symptom, a confident wrong answer, arrives four ways, one per brick, each closed by a different contract – Image by author

Read it top to bottom: the same symptom, a confident wrong answer, arrives four different ways, and a different brick closes each. The rest of the article walks the four, each on a real document.

2. Parsing: a table flattened into noise

Document: World Bank Commodity Markets Outlook (a report built around price tables). Question: What is the 2025 annual average price forecast for U.S. natural gas (Henry Hub)?

Real runs on the same table question: what each pipeline does, the answer it returns, and why – Image by author

A naive pipeline parses a PDF the common way: dump flat text with get_text() and cut it into fixed-size chunks. That is fine for prose and fatal for tables. A price table is a grid; flat extraction linearises it, and a fixed-size chunker then cuts the stream wherever the character budget runs out. The row label Henry Hub lands in one chunk and its 3.5 cell in another. Retrieval hands the model chunks that never carry both, and it answers honestly: “not stated in these lines,” confidence 0.00.

Nothing was hallucinated. The number was in the document; the parser destroyed the one thing that made it an answer, the alignment between the label and the cell.

The fix is relational parsing. Instead of flat text, the upgraded brick returns a line_df: one row per text line, each with its bounding box. The table’s row stays intact, the model reads Henry Hub and 3.5 on the same line, and returns “$3.5 per mmbtu” at confidence 0.99. This is the whole argument of the parsing brick (Article 5): stop returning flat text, keep the relational shape the answer lives in.

3. Question: a word the document never uses

Document: NIST SP 800-207, Zero Trust Architecture. Question: What are the pillars of zero trust architecture?

Real runs on the same question: what each pipeline does, the answer it returns, and why – Image by author

The document never uses the word pillars. It calls them tenets. A naive pipeline searches the pages for the query’s own words, pillars scores against nothing, and the model reports “the specific pillars are not listed,” confidence 0.20. The answer is right there, under a different name; the right pages were never even searched.

This is not a ranking problem, and no bigger top-k fixes it: the query word simply is not in the document. It is a vocabulary problem, and it lives one brick before retrieval, in question parsing. The user’s word and the document’s word are synonyms the raw string cannot bridge.

The fix is question parsing. Before retrieval runs, the brick normalizes and expands the query, mapping domain synonyms (pillars → tenets, principles) so retrieval searches for the words the document actually uses. It then anchors the tenets section, and generation returns all seven at confidence 0.95, noting the document’s own term. The same expansion lets a user ask about a dog and match a policy that only ever says animal, the case Article 7quinquies (most RAG hallucinations are retrieval failures) walks in detail.

4. Retrieval: the answer below the cutoff

Document: NIST Cybersecurity Framework 2.0 (32 pages, native table of contents). Question: How is a Profile defined in CSF 2.0?

Real runs on the same question: what each pipeline does, the answer it returns, and why – Image by author

The word Profile is on many pages of CSF 2.0: it names a section, recurs in prose, heads examples. Only one section defines it. Keyword and cosine retrieval rank a page by how relevant it looks to the term, and every Profile page looks equally relevant. The naive pipeline keeps the top few by frequency, none of which is the defining page, and the model reports “not defined in these lines,” confidence 0.10. The answering page fell below the top-k cutoff.

The fix is retrieval that routes on structure. The upgraded brick reads the document’s own table of contents through a small LLM, sees the section titled CSF Profiles, and anchors retrieval there instead of on raw frequency. Generation sees the defining paragraph and returns the full definition with a citable span, confidence 0.95.

The same routing scales where naive retrieval gets worse. On the 400-plus-page NIST SP 800-53 control catalog, asked for the single AU-2 Event Logging control, naive retrieval dilutes it past the cutoff among a thousand near-identical siblings and returns “NA” at 0.00; the router locates the AU family and the AU-2 entry directly and returns the full requirement, clause by clause, at 0.98. Routing on structure does not degrade as the document grows; ranking on frequency does.

5. Generation: a confident answer with no self-check

Document: World Bank Commodity Markets Outlook, April 2024 (its forecasts stop at 2025). Question: What is the 2026 annual average price forecast for crude oil (Brent)?

Real runs on the same question: what each pipeline does, the answer it returns, and why – Image by author

This time both pipelines retrieve the same, correct context: the energy pages with the price table. The document simply has no 2026 row. A naive pipeline’s generation brick asks the model for a free-text answer, and a free-text model asked a question tends to answer. It grabs the nearest number, the 2025 value of $79, and returns “the 2026 Brent forecast is $79 per barrel”, confident, fluent, and wrong. Nothing in a prose answer could have said “this is not in the document.” This is the hallucination readers report, and it happened at the last brick, with good context in hand.

The fix is a typed generation contract. The upgraded brick does not ask for prose; it asks for a schema with a complete_answer_found field the model must set, an evidence span it must cite, and a confidence it must justify. Faced with a value that is not in the lines, the model cannot quietly fill the gap: it sets complete_answer_found: false and returns “the 2026 forecast is not provided; the latest is 2025.” The generation brick does not make the answer smarter. It makes a missing or partial answer visible, so a wrong one cannot ship as done. The same complete_answer_found field guards partial answers in general: whenever retrieval surfaces only part of what the question asked, it is the difference between shipping a fragment as if it were whole and flagging the gap.

6. One root, four doors

The four failures are one thing seen four ways. In none of them did the model invent from nothing. Each time it answered the context it was handed, faithfully, and the context was wrong: a table the parser scrambled, pages found for a word the document never uses, the answering page left below the cutoff, or a value that was never there and got filled in anyway. The label hallucination points at the model; the cause was a brick upstream.

The common fix is not a better prompt, a bigger model, or a larger top-k. It is context engineering, one contract per brick: keep the document’s relational shape (parsing), search in the document’s own vocabulary (question), route on the document’s own map (retrieval), and bind the answer to a typed, checkable contract (generation). Get the context right and a confident wrong answer has nowhere to come from, because the model is no longer being asked to answer the wrong context.

Two honest caveats. First, naive RAG is not always wrong: on short, clean, prose documents it keeps up, and the honest figure in Article 9 shows it. The gap opens exactly where enterprise documents live: tables, house vocabulary, length, structure. Second, these four crosses are the ones that held up. We ran the naive baseline and the upgraded pipeline on many more (document, question) pairs, and where naive did fine we say so rather than manufacture a failure. Each cross above is a real run, not a manufactured one.

The upgraded pipeline is rung 2 of 5; getting the context right is what every rung above builds on – Image by author

7. Sources and further reading

The failure cases are real runs of the naive baseline (pdf_qa_baseline, plus a flat-chunk parser and a free-text generator for the parsing and generation bricks) against the upgraded pdf_qa (Article 9); each one is a real run, reproducible in the companion notebook, not an assumed result. The responses.parse(text_format=Schema) pattern behind the typed answer uses OpenAI’s Structured Outputs.

Earlier in the series:

Documents used (all openly licensed):