The Right Number Under the Wrong Table Header

An operations assistant reads an inventory PDF and reports 160 available units at the east warehouse. Every digit it used appears on the page. That is reassuring until someone asks which warehouse heading governed those cells, whether “reserved” was already deducted, and how many units a box contained.

This guide uses a constructed inventory example, not a customer incident. It addresses a decision for document-pipeline engineers and reporting owners: when may an extracted table support a numerical answer, when should the system reconstruct its context, and when must it leave the answer unresolved? The useful output is a value with its relationships intact, not a tidy grid alone.

A page can look tabular without carrying table semantics

A PDF often describes where marks appear, rather than supplying the original spreadsheet. The PyMuPDF text-extraction guide explains that plain extracted text may not follow natural reading order and that a visible table is commonly positioned text, not an embedded table object. Its table-detection tools reconstruct structure from the page. Recovering words and recovering their relationships are different operations.

Separate three questions. Did recognition recover the characters? Did structural extraction identify the cells, spans and header relationships? Did interpretation assign the right business meaning? A clean “20” can survive the first question and fail either of the others. Increasing image resolution helps only when the problem actually lies in recognition or capture.

The broader document-intelligence guide covers acquisition, evidence and multilingual processing. Here the narrower concern is the boundary between a table cell and a claim. A parser's successful response, a model's fluent explanation and a plausible total are not substitutes for checking that boundary.

Give each value a complete header path

“Actual” is not a complete column identity when it appears beneath both 2025 and 2026. Nor is “On hand” complete when two warehouses share that label. Represent a value through its table, row identity and ordered header path: for example, warehouse east → on hand. Preserve the source labels as well as any normalized business names.

There is a useful representation lesson in W3C's multi-level table guidance: complex data cells can have several associated headers, and explicit associations remove dependence on a reader guessing from position. This is accessibility guidance, not certification of an AI extractor. The transferable design principle is to retain the relationships instead of preserving only the nearest label.

A merged heading belongs to every column in its span, but that does not make every visually empty cell a copy of its neighbor. A blank data cell might mean missing, inapplicable or deliberately omitted. Expand a confirmed header span into explicit paths; do not fill down or sideways across the entire table indiscriminately.

Assign stable cell identifiers within one extraction version. Keep row and column indices, spans, page coordinates and header-cell references separately. Coordinates help a reviewer find evidence; they should not become permanent business identifiers. A supplier can move a column without changing its meaning, or leave it in place while changing its label.

Work through one inventory question without guessing

Consider this synthetic source. Its original top row groups two columns under each warehouse. For readability, the reconstruction below repeats those group names in every column heading. All stock counts are in boxes. A note states that each box of part B contains ten units, and that reserved boxes are included in on-hand counts. “Available” is defined for this example as on hand minus reserved.

The question is: how many units of part B are available at east? The supported calculation is (20 − 4) × 10 = 160. Selecting west's cells instead yields (8 − 1) × 10 = 70. Returning 16 loses the box-to-unit conversion; returning 200 ignores reservations. All four answers can be assembled from correctly recognized source numbers.

The answer record should point to part B's row, both east cells, the merged east heading, the two measure headings, and the pack-size and reservation notes. Its derived value should carry the formula and input cell identifiers. The model can explain that calculation; deterministic arithmetic should execute it after the inputs and definitions are accepted.

Now remove the reservation note. The system no longer knows whether on hand is gross or already net of reservations. Subtracting again could be wrong. Remove the pack-size note and the system may still report 16 available boxes under the stated availability definition, but not 160 units. A partial answer is useful when it names the supported unit and the unresolved assumption.

This is a fixture with stipulated facts, not a warehouse policy or a measured model result. Real “available to promise” may also depend on quality holds, allocations and timing. The workflow owner must supply that definition. The quantity-contract guide develops the separate rules for units, scale and numerical normalization.

The table's bounding box is not its whole context

A crop around the grid can exclude the title that names the period, the caption that states the unit, or the footnote that changes a subtotal's scope. Azure Document Intelligence's layout documentation describes row/column positions, spans and table-cell geometry. It also specifies that, for the 2024-11-30 API, table and figure bounding regions cover core content and exclude associated captions and footnotes. A correct crop can therefore be an incomplete evidence package.

Keep the original authorized page available and associate surrounding context deliberately. Search for caption and note references, but do not attach every nearby paragraph automatically. Two tables on one page may use different units. A footnote marker can apply to one row rather than the whole grid. Store the scope of the association and distinguish a verified link from an unresolved candidate.

Page breaks deserve their own treatment. Repeated headers are not stock rows; a page subtotal is not necessarily an additional item. A continuation can inherit context only after checking table identity, column structure and any intervening unit or period changes. When that check fails, retain separate fragments rather than silently joining them into one authoritative table.

Preserve the provider's structure before normalizing it

Different extractors represent the same layout differently. Amazon Textract's table guide exposes relationships for child cells, merged cells, titles and footers. Its ordinary cell blocks have unit row/column spans, while merged-cell blocks express the larger span. Flattening only ordinary cell text would discard information the service actually returned.

Build a versioned adapter for the provider response. Preserve the raw structural evidence under appropriate access and retention controls; then map it into your own cell/header representation. Record which API and adapter versions produced the mapping. Do not assume that a similarly named field from another provider has identical scope or confidence semantics.

Run structural checks before answering: references must resolve, spans must fit the reconstructed grid, and the selected value must have an unambiguous relevant header path. Flag conflicting assignments rather than choosing the first match. Arithmetic reconciliation adds evidence, but two swapped cells can preserve a grand total. Test the relationships themselves.

For Persian documents, separate visual coordinates from logical column order. Mixed-direction identifiers and numbers do not justify reversing every row. Preserve the original digit string alongside its normalized value, and test actual Persian layouts, fonts and separators. These are local evaluation requirements, not claims that any cited extractor handles every language or template correctly.

Retrieve a table fragment with its interpretive context

A retrieval system may undo good extraction by cutting the reconstructed table into fixed-length text chunks. The selected row survives; the group header and notes land elsewhere. The answer model then sees a fragment that appears self-contained because its missing context is invisible.

Our recommended retrieval unit is the requested row or cell set plus its required header paths, table identity, relevant units and applicable notes. Keep the full table addressable. For a large table, retrieve relevant rows with repeated explicit context rather than stuffing every row into the prompt. A generated table summary can help discovery, but it is not the numerical source of truth.

The RAG knowledge-quality guide explains why extraction and chunking belong in answer evaluation. For this case, test the final retrieved package, not only the parser's stored output. Confirm that its permissions remain those of the source, and avoid copying whole sensitive tables into general-purpose diagnostic logs.

There is a cost tradeoff. Repeating headers and notes uses more context; retrieving fewer rows can omit a relevant qualifier. Prefer explicit dependency selection and a bounded fallback to the full authorized page. If the dependency cannot be resolved, say which part of the interpretation remains unknown rather than asking a larger model to invent the missing relationship.

Measure relationships as well as characters

The original PubTables-1M paper separates detection, structure recognition and functional analysis, and describes nearly a million tables from scientific articles with detailed annotations. That task separation is useful. That corpus, by itself, does not establish performance on Persian inventory scans or a particular supplier's forms.

The GriTS paper evaluates tables as grids and distinguishes topology, location and content. It provides a reason to look beyond text similarity. An application still needs an additional check: does the extracted value belong to the correct entity, measure, period and unit, with the applicable qualification? A high structural score is not an authorization to act on every derived answer.

Create a held-out sample from the actual authorized document population. Include borderless grids, merged headers, wrapped row labels, multi-page continuations, repeated totals, blank cells, negative values and mixed scripts. Have reviewers establish expected cell relationships and note scopes, not just a flat answer string. Keep genuinely ambiguous cases labeled ambiguous instead of manufacturing ground truth.

Report distinct outcomes: cell text correctness, header-path correctness, unit/note attachment correctness, and complete numerical-claim correctness. For accepted claims, count how many are fully correct; also report the share of requests accepted automatically and the time spent reviewing the rest. Accuracy can look excellent if a system declines nearly everything. Break results down by document family and language.

Use controlled mutations alongside real samples. Reorder columns with their headers and the answer should stay the same. Change only a group header and the answer's warehouse identity should change. Remove an essential note and the answer should become qualified or unresolved. Changing typography alone should not silently change the quantity. These are proposed tests, not evaluations ZharfAI has run on the named services.

Make the acceptance decision visible

Use a disposition that tells the next component what it may do. “Extracted” should not automatically mean “approved for reporting,” and “approved for reporting” should not authorize a stock movement. Keep interpretation and action permissions separate.

This table is ZharfAI's integration recommendation, not a vendor feature. Give reviewers the selected cells, their headers, the applicable note and the proposed calculation together. Let them correct a relationship without rewriting the source. Store the correction as a new version so downstream reports can be identified and refreshed when necessary.

Watch for rising header repairs, unit corrections, unresolved continuations and accepted claims later overturned. Revisit the tests when suppliers change templates, an extractor changes versions, or the application begins asking a new class of question. The decisive improvement is not that the exported spreadsheet looks cleaner. It is that the team can explain why this number belongs to this claim—and identify when it cannot.

Source notes — reviewed September 24, 2026

Provider documentation describes representation and API behavior, not guaranteed extraction accuracy. The workflow and acceptance tests above are our analysis; the inventory figures are synthetic. Research claims here are limited to the papers' stated task, dataset and metric definitions.

• PyMuPDF text recipes — documentation for 1.28.2, updated September 3, 2026; reading order and table extraction.
• W3C multi-level tables — updated July 27, 2019; explicit header relationships in accessible tables.
• Azure Document Intelligence layout — updated May 1, 2026; the cited behavior concerns v4.0, API 2024-11-30.
• Amazon Textract tables — undated rolling developer guide; cells, merged regions, titles and footers.
• PubTables-1M — first submitted September 30, 2021; version 3 November 18, 2021; CVPR 2022 research.
• GriTS — first submitted March 23, 2022; version 3 May 23, 2023; grid-based table evaluation.