Loop Engineering with Adaptive PDF Parsing: Start Cheap, Pay for a Heavier Parser Only When the Page Needs It

Adaptive parsing runs in two phases. Phase one is initialisation: pick a baseline parser per document, based on what the document is (native PDF, scan, Word export). In a platform context this fires at ingestion: every new document gets its baseline parse on arrival, so the system always has a first textual layer to work with, even for scanned PDFs where the baseline has to be an OCR engine because PyMuPDF would return empty. Phase two is the cascade: run cheap deterministic checks on the baseline’s output and escalate the pages that fail to a deeper parser. Most pages stay on the baseline; the few that fail a check get the richer treatment they actually need.

The pipeline always starts cheap on phase one. PyMuPDF on native PDFs, a free OCR engine on scans. Both produce the same line_df shape, so the rest of the pipeline (question parsing, retrieval, generation) does not know which parser ran. That works most of the time. It fails on a small but predictable set of content shapes, and phase two has several places to catch the failure, ordered from cheap deterministic checks on the parser’s outputs to a final-line-of-defence LLM call at generation time.

Cheap parsing is fast and free, and it leaves a recognisable set of content invisible or scrambled. Five shapes come up regularly:

• Flattened tables: The most common failure on native PDFs. PyMuPDF returns each cell as a separate line, in geometric order, with column structure erased. “Self-Attention” and “O(n² · d)” sit on lines 9 and 10 of the page with nothing connecting them: the LLM cannot pair the row label with its value. Detected at parsing-time by the flat-table fingerprint (Section 3.2.2); walked end-to-end in the second part.
• Figures and diagrams: PyMuPDF extracts the page text around an image but the image itself is opaque to it. “Figure 1 shows the encoder-decoder architecture” survives; the architecture diagram does not. Detected at parsing-time by the opaque-figure check (Section 3.2.3); walked end-to-end in the second part.
• Multi-column layouts: A two-column page where the parser walks columns geometrically instead of logically produces interleaved sentences from both columns. The text is technically there; the reading order is broken.
• Degraded OCR: Scanned pages with low resolution, skew, or compression artefacts produce character-level errors: l/I/1 confusion, fragmented words, missing punctuation. The LLM can sometimes recover the meaning, sometimes hallucinates around the noise.
• Embedded objects: Equations rendered as vector paths, signatures as images, checkboxes, watermarks: objects the parser may return as placeholders, garbled text, or nothing at all.

This part picks two of these (flattened tables, figures) for the worked walkthroughs the second part develops, because they have the cleanest reproductions on a public document. The mechanism is the same for the other three. The parsing-time deterministic checks (document parsing brick, section 3) flag the failure shape, and the pipeline routes the page to the right deeper parser. The LLM signal at generation time (generation brick, in the second part) is the safety net for the cases the deterministic checks did not catch upstream.

One more reason to parse lazily, in numbers. An enterprise corpus averages 30 to 100 pages per document, 1 to 3 pages relevant to any given question, and fewer than 10 questions per document over its lifetime. Multiply these out and roughly 90% of any page parsed at ingestion is never consumed by any answer. Deep-parsing every page upfront pays the bill for pages no one will ever read.

Here is the whole article in one picture. The rest of the text walks each piece of this cascade, but it helps to have the full map first.

Parsing quality is a multi-check decision. The pipeline starts cheap and asks, at each check, whether the parser produced enough for the question. Every check has a cost; every check that flags a problem can route the affected page to a deeper parser. The pipeline pays only for the quality the question needed.

The pipeline’s four bricks (document parsing, question parsing, retrieval, generation, introduced in Articles 5 to 8) each own one to three of the nine evaluation checks. The grouping makes the cascade legible: every check belongs to a brick, every brick has its own cost profile and its own characteristic check. The cascade diagram in section 1 shows the full mapping.

The two recurring examples make the cascade concrete.

• Table 3 on page 9 of the Attention paper is a flat-parsed grid: every cell on its own line with no column anchor surviving. Text density alone misses it at check 1; the deterministic check-2 fingerprint catches it cleanly (flat-table signature), and check 7 (the LLM flag) confirms it, with the caveats developed in the second part.
• Figure 1 on page 3 is a diagram body that PyMuPDF returns empty. Catchable at check 1 (lower-than-average text density combined with an embedded image), at check 2 (opaque figure region with zero extracted chars), and at check 7.

The cheapest check that fires wins, and the pipeline never asks the slower checks a question the faster checks already answered.

The data model that supports it: Whatever check triggers escalation, the schema for the rerun is the same. Add one column, parsing_method, to the relational tables from Article 5. The escalation logic becomes: write new rows with a deeper method on the affected pages. Mixed documents, audit trail, and caching all fall out of the schema for free.

page_df is the canonical place because parsing always happens per page. After a typical adaptive run on the Transformer paper, where the cascade flagged page 6 (Table 1, Maximum path lengths, caught by the check-2 flat-table fingerprint) and page 3 (Figure 1, caught by the char-density signal at check 1 and the opaque-figure signal at check 2), page_df looks like this. This section uses Table 1 to show the shape of the escalated tables; the full end-to-end walkthrough in the second part takes a second flat table, Table 3 on page 9 (Variations on the Transformer architecture), so you see the pattern on two different real tables rather than one.

Two design decisions are baked in. First, escalation adds new rows, it does not replace. The PyMuPDF row for page 6 stays alongside the Azure row: “PyMuPDF tried, the cascade flagged the parse, Azure was called and succeeded”. Second, the context_structured column on page_df lets downstream queries pick the right row: SELECT * FROM page_df WHERE page_num=6 AND context_structured=True returns the trusted parse without any re-run.

line_df also carries parsing_method. Lines from PyMuPDF coexist with lines from the deeper parser on the same page. PyMuPDF produced the prose around Table 1; Azure produced the markdown rows of the table itself; both stay in line_df. The retrieval brick reads line_df and sees a uniform shape, regardless of which parser produced which row.

Images live in line_df too, as rows with type='image' and a placeholder text. This is the bit that makes the figure case (in the second part) work mechanically the same as the table case. The opaque-figure signal at check 2 already flags such pages from line_df alone (image present, zero extractable chars inside its bbox). When the cascade flags page 3, the pipeline picks the row from image_df, sees parsing_method='not_parsed', and calls a vision LLM. The vision output gets appended to line_df as new text rows with parsing_method='vision_gpt4o', and the image_df row is updated.

Targeted re-parsing is one function call, method-agnostic, that returns new rows with parsing_method=method already populated:

def enrich(pdf_path, line_df, page_df, pages, method):
    """Add layer-2 rows for `pages` using `method` ; keep existing rows for audit."""
    if method == "azure_layout":
        from docintel.parsing.pdf.azure_layout import azure_layout_pdf_to_line_df
        new_lines = azure_layout_pdf_to_line_df(pdf_path, pages=pages)
    elif method == "vision_gpt4o":
        new_lines = vision_extract(pdf_path, pages=pages)
    # new_lines already carries parsing_method=method
    line_df = pd.concat([line_df, new_lines], ignore_index=True)
    page_df = append_page_rows(page_df, pages, method)
    return line_df, page_df

The line_df schema from Article 5 is unchanged for downstream bricks: retrieval and generation read line_df, group by page_num, and never need to know which parser produced which line. The only contract that changed is “the parser identity travels with the row”.

Document parsing owns three of the nine checks: pre-parsing (check 1, before any extraction runs), parsing-time (check 2, on PyMuPDF’s own outputs), and post-parsing (check 3, on chunks downstream of line_df). All three are deterministic, free, and produce a verdict in milliseconds without any LLM call. Together they catch most of the failure shapes the article cares about, including both Case A (the flat table, Table 3 on page 9) and Case B (the opaque figure, Figure 1 on page 3), the two cases the second part walks end to end.

The cheapest evaluation point sits before any text-extraction call runs. PyMuPDF can already report per-page metadata in milliseconds: how many characters it can extract, how many embedded images each page carries, what producer string the PDF declares. These signals route most of the corpus before the parsing decision becomes interesting.

A native-PDF page typically extracts 2000-4000 characters of text. Pages that come in well below that, paired with one or more embedded images, are signalling that “the page is mostly a figure” without any deeper inspection.

For Figure 1 on page 3, this signal alone is enough to flag: 1827 chars vs the document’s 2633-char mean, plus one embedded image. The pipeline could route page 3 to a vision LLM without ever calling Azure or running a generation pass. For Table 3 on page 9, the same signal does not fire: 2973 chars (above mean), zero embedded images. Check 1 catches one of the two examples for free; check 2 will catch the other.

The PDF metadata adds a second cheap classifier. The Attention paper’s producer is pdfTeX-1.40.25, which says LaTeX-authored, native, no OCR needed. A scanner-produced PDF would say Adobe Scan, Canon, OmniPage. That single string routes 80% of an enterprise corpus to the right tier before any text extraction runs. The creation date, the embedded font list, and the presence of an XMP block add coarse but useful classifiers.

pre = pre_parse_signals("data/paper/1706.03762v7.pdf")

pre["producer"]            # -> "pdfTeX-1.40.25"
pre["is_scanner_output"]   # -> False
pre["pages"].head()
# page_num  char_count  image_count  image_bboxes
#        1        2858            0  []
#        2        4256            0  []
#        3        1827            1  [(196.6, 72.0, 415.4, 394.4)]   <-- Figure 1
#        4        2508            2  [(175.0, 94.0, 239.0, 221.3),
#                                     (346.8, 82.7, 467.0, 267.3)]   <-- Figure 2
#        5        3193            0  []

The result of this check is not the answer to a question. It is a per-page judgment: “this page is normal”, “this page has a missing image body”, “this whole document is scanned and needs OCR upfront”. The judgment is free and it ships with the parsing_method column on page_df.

PyMuPDF runs next. Its outputs already carry deterministic signals about the layout it just walked. Three checks fire from line_df alone, none of them needing an LLM call.

PyMuPDF extracts every line with bounding-box coordinates. Clustering line x-coordinates per page produces a column count. A well-structured document has a stable column count from page to page. Variance is the routing signal.

The anomaly on page 10 is itself a parsing-quality signal. The detector did not produce a wrong count by accident, it produced it because the table broke the column model. That is information the pipeline can use to route page 10 to a layout-aware parser.

When PyMuPDF flattens a table, the cells fall on their own lines with narrow bboxes immediately following the “Table N: …” caption.

The fingerprint is concrete: on page 9, lines 5-20 hold the table headers split across two physical rows of bboxes, and lines 21-33 hold the 13 cells of the base row each on its own line. The cells are short (1-4 chars), narrow (under 30 PDF points wide), and clustered vertically in a tight band right after a “Table 3: …” caption. A check that counts those properties on line_df[page_num=9] and trips a boolean flag runs in O(n_lines) without any LLM call. Table 3 is caught at this check.

PyMuPDF reports image bboxes at extraction time via page.get_image_info(). If a page has an image and the text extracted inside its bbox is empty, the figure body did not survive the parse.

The check is the same as the pre-parsing density check but more precise: instead of noticing the page has fewer characters, it pinpoints a specific rectangle with zero characters. Figure 1 is caught at this check. (Pre-parsing also catches it, more cheaply; check 2 confirms it and adds the bbox the next parser will need.)

The Attention paper is single-column, so it cannot illustrate this check. We swap in BERT (1810.04805) which is the standard ACL two-column format. assign_column_positions clusters line x-coordinates per page and labels each line “left” / “right” / “single” / “multi”. No hardcoded midpoint, the split is computed from the actual line distribution. When PyMuPDF walks such a page geometrically, it can interleave sentences across the column boundary; the column labels let the pipeline (or a deeper parser) restore the correct reading order.

pre     = pre_parse_signals("data/paper/1706.03762v7.pdf")
line_df = fitz_pdf_to_line_df("data/paper/1706.03762v7.pdf")

# Three pages, three signals, no LLM call
page_level_parsing_signals(line_df, page_num=3, pre_signals=pre)
# {'page_num': 3, 'flat_table': False, 'opaque_figure': True,
#  'col_anomaly': False, 'reasons': ['opaque_figure'], 'escalate': True}

page_level_parsing_signals(line_df, page_num=9, pre_signals=pre)
# {'page_num': 9, 'flat_table': True, 'opaque_figure': False,
#  'col_anomaly': False, 'reasons': ['flat_table'], 'escalate': True}

page_level_parsing_signals(line_df, page_num=10, pre_signals=pre)
# {'page_num': 10, 'flat_table': True, 'opaque_figure': False,
#  'col_anomaly': True, 'reasons': ['flat_table', 'col_anomaly_3'],
#  'escalate': True}

At the end of check 2, both Table 3 and Figure 1 are flagged for escalation without a single LLM call. The pipeline could enrich both pages with the right deeper parser now, before retrieval even starts. The remaining checks of the pipeline (retrieval, generation, post-gen) become last-resort safety nets, not the primary detection mechanism.

After line_df is built, the pipeline chunks it for retrieval. A chunk that cuts mid-sentence or mid-table-row carries a low chunk_integrity_score that downstream prompts can read. Surya and PaddleStructure expose this directly; with line_df alone we can compute it from line numbers and bboxes (sentence-end punctuation in the last line, table-row alignment within the chunk).

The score is deterministic, cheap, and fires before any retrieval call. The article does not develop a worked example for check 3 because both Case A and Case B are already caught at checks 1 and 2; we mention it here so the panorama is complete.

Question parsing turns the question into a typed parsed_question (Article 6) and uses that to route the cascade. Two checks live here: check 4 (intent routing, one small LLM call on the question) and check 9 (user feedback, a slow human-driven loop that refines check 4 over time).

“In Table 3”, “what percentage”, “according to article 5” signal that the answer lives in a structured region. Route directly to table-aware retrieval, skip prose embeddings. Article 6 made the case for parsing the question into a typed object; routing by intent is one of its payoffs. The cost of this check is one small LLM call on the question (a few cents per thousand questions). The quality gain: the pipeline routes Table 3 questions to a table-aware parser without ever needing the LLM at check 7 to notice the table was flattened.

Check 9 is the long-loop check: a question that the user re-asks with slightly different wording, a golden set drift over time, an expert flagging a wrong answer. None of these fire inside a single pipeline run, but they refine the question parser (and, indirectly, every check that follows). Concretely: a recurring rewording captured in expert_keywords_df (Article 6) gets added to the question router, and the next question that uses that phrasing is correctly classified without the user having to retype it. The cost of this check is human time spent on golden-set curation; the quality gain compounds.

Retrieval takes the parsed question and the parsed corpus, and returns a small set of candidate chunks. Two checks fire here, both deterministic and both running on quantities the retrieval brick already computed.

Top-1 cosine of 0.45 is a poor anchor. Top-1 of 0.85 with top-2 at 0.83 is ambiguity. Both deterministic, both fire before generation. Reranker disagreement with the bi-encoder is itself a second-order signal. The cost is the cosine computation already done by retrieval; the quality gain is catching questions that landed nowhere clean.

Once the candidate chunks are picked, a last deterministic check compares them to the question’s parsed scope. Question covers 2020-2024, chunks cover 2020-2022: the gap is detectable before the LLM call. Same for chunks that contradict each other on a key fact. These checks run in milliseconds and are skipped only at the cost of fabrication-prone answers downstream.

The same cheap-then-rich logic the cascade applies to parsing also applies to embedding. Parsing produced page_df and line_df (Article 5 Section 3.2 said “line_df keeps the door open” on this); retrieval now decides which granularity to embed, and when.

The cascade turns parsing quality into a sequence of cheap questions. Pre-parsing metadata routes most of the corpus before any extraction runs. Parsing-time fingerprints flag flat tables and opaque figures from PyMuPDF’s own output. Intent routing and the retrieval score-gap catch cases the parser’s output alone cannot. Every check is deterministic, free, and runs in milliseconds, and every one that fires can route a single page to a deeper parser.

One column, parsing_method, makes the whole thing auditable: escalation adds rows, it never overwrites, so a page can carry its PyMuPDF parse and its Azure parse side by side. What none of these cheap checks can catch is the failure that only shows up when the LLM tries to use the text. That last line of defence, and the two escalations walked end to end (a flat table to Azure, a figure to a vision LLM), are the second part: Loop engineering with adaptive parsing in action: parsing flat tables with Azure and figures with a vision LLM (link to come).