Document parsing

Read these first

• Naive RAG end to end, built once by hand without a framework

What you will know

• Parse a born-digital PDF, a scanned one, and one with tables

  The text layer can still contain incorrect reading order, while OCR introduces recognition errors and tables add structural ambiguity.

• Show a parser destroying a table's meaning

  Flattened cells can detach headers from values, shift row relationships, and produce plausible-looking but incorrect answers.

• Choose between parsers with a measured comparison

  Evaluate representative documents using extraction accuracy, reading order, table fidelity, latency, and operating cost rather than vendor examples.

• Instrument a parsing pipeline to report per-document OCR use, extraction failures, page counts, and latency

  These signals expose scan-heavy workloads, pathological files, and cost spikes that aggregate ingestion metrics hide.

• Trace a retrieval miss to a parsing defect and patch the parser or ingestion path

  Missing text, malformed reading order, or flattened tables can make relevant content unretrievable even when the retriever itself is working.

Chapters

1. 1

   A PDF stores glyph placements, not paragraphs or columns

   The content stream is a run of draw operations in whatever order the producer chose, and nothing in the format means column, paragraph or heading. That is why a LaTeX two-column report extracts with every character spelled correctly and sentences interleaved left to right, and why sorting by y then x across the page makes it worse. Reading a raw extraction beside the rendered page teaches you to treat reading order as reconstruction.

   Read chapter
2. 2

   A text layer guarantees characters, never their order

   Two 40-page PDFs in one queue, one yielding 96,000 characters and one yielding 31: characters per page classifies them with no human involved, and the loud failure turns out to be the safe one. A scan without a text layer breaks visibly in week one. The born-digital file returns well-spelled prose in scrambled order with footnotes glued into the body, and nothing downstream flags it, which is why OCR-everything discards a working text layer.

   Read chapter
3. 3

   OCR errors cluster exactly where context cannot repair them

   A reported 98.5% character accuracy is fully compatible with confident falsehoods, because recognition errors are not spread evenly across meaning. They concentrate in rare strings such as policy numbers, dates and dollar amounts, where no surrounding language constrains the guess, so a chunk holding one corrupted digit embeds and retrieves exactly as well as a correct one while stating a wrong figure. Per-token confidence and targeted hand-checks are what you have.

   Read chapter
4. 4

   Flattening a table deletes the binding between header and cell

   Six columns, one row per region, a merged two-level header, and a parser emitting whitespace-separated numbers: every figure survives and is spelled right, yet nothing ties 41.2 to EMEA or to Q3, so the model infers alignment from adjacency. Holding the whole table in one chunk cannot help, since the binding was gone before chunking, and asking for a row citation yields a fabricated one. The repair is a representation the retriever can actually store: the two-level header resolved into fully-qualified column labels, then each row emitted as a self-contained record carrying its labels inline — 'EMEA, Q3 FY2023 revenue: 41.2' — before anything is chunked, with a regression check that asks for that cell by name.

   Read chapter
5. 5

   HTML, DOCX and slides fail by yielding too much, not too little

   Away from PDF the problem inverts: the structure is present and the risk is what comes with it. HTML hands you headings and real table cells, and also navigation, cookie banners, sidebars and script text that enter the chunk unless boilerplate is stripped. DOCX is a zip of XML with genuine headings, cells and styles, plus two traps — tracked changes and comments, where deleted text extracts and indexes as though it were current, and embedded objects that carry no text at all. Slide exports have shape order unrelated to reading order, substance sitting in speaker notes, and a large share of the content living as text inside images.

   Read chapter
6. 6

   Retrieval cannot return text the parser never emitted

   When one clause is missing from results and k, the embedder and every other query behave, pull every chunk the index holds for that document id and search them for the phrase. If it is absent, this was never retrieval, and the next artifact to open is what the parser produced for page 12. The same logic disqualifies swapping embedders to see whether the number moves: a reranker gains points over a corpus with holes in it. It also shapes what you promise: commit to a fixed-cost characterisation — a stratified sample, hand-checked, with a defect rate per source — and to fixing named sources, never to a corpus-wide quality number or a date for a corpus nobody has read. Some classes are better left out of the index, with the gap stated to users rather than answered around.

   Read chapter
7. 7

   Per-document OCR rate reveals a vendor that started scanning

   Aggregate ingestion success hides the day a supplier swaps born-digital contracts for scanned printouts, because every file still reports fine. What surfaces it is the share of pages per document with no usable text layer routed through OCR, tracked per source, next to extraction failures, page counts, per-page latency and cost. Here you build those signals and learn the shapes they take for scan-heavy workloads and single pathological files.

   Read chapter
8. 8

   Parser choice is a per-source decision, not one standard

   A hosted layout-aware parser at $0.012 a page versus a free pipeline on hardware you already own gets settled on a stratified sample of your own corpus — born-digital, scanned, table-heavy, slide export — with hand-checked ground truth and separate scores for extraction completeness, reading order and table fidelity, plus latency and cost per page. Vendor demos are not evidence. The output then routes source by source instead of crowning one winner.

   Read chapter