Skip to content

Long documents and contradictions

A document of dozens of pages does not fit one request without losing what sits in the middle of the context. From DX_LONG_DOC_PAGES pages (12 by default) the pipeline stops sending the whole text: the long-document handler (extractit.extract.longdoc) locates where each field may be, reads only those pages in small windows, and consolidates what the windows return. Two anchored values that disagree are not resolved silently: the field becomes conflict.

from extractit import extract

out = extract("contract-100p.pdf", "contract.schema.json", model="codex")
out.strategy  # 'long_document'  ('single_pass' up to 12 pages)
out.coverage  # pages_covered=100 pages_total=100 pages_read=19 failed_windows=()
[f for f in out.fields if f.status == "conflict"]  # value + alternatives + contradicting evidence

The output schema is the same in both strategies; strategy and coverage (output contract 1.1) say which one ran and what was read.

When it runs

The handler (kind long_document, priority 5, registered through the extractit.field_handlers entry point) claims a field when

  • the document has more than DX_LONG_DOC_PAGES pages (default 12: a 12-page document is one pass, a 13-page one takes the long path), or
  • the whole text does not fit the context budget of the model (DX_MAX_CONTEXT_TOKENS or the backend capabilities), whatever the page count.

It claims scalar fields and arrays of primitives that the model extracts from the document. Tables (x-dx.table, arrays of objects) and fields whose x-dx.source is not document are left to their own handlers (tables: T22; lookup and derived: T24). Claiming a field twice raises FieldClaimConflict. If the one-pass harness still reports DocumentTooLongError for the rest of the schema, the pipeline delegates those fields to this handler too (it skips tables with the warning long_document_fields_skipped).

How it works

  1. Index. One BM25 index over the plain text of the pages (Okapi, k1 = 1.5, b = 0.75, no third-party dependency; NFKD folding so Importe = importé).
  2. Locate. Per field the query is its name, title, description, instructions and enum values (minus a small multilingual stop-word list). The 5 best pages by BM25 are candidates, provided their score is at least bm25_min_rel (0.2) of the field's best page. One call per batch of 20 fields to a low-tier model (purpose = "extract", phase locate) shows, for each field, a summary of its 8 best pages (section headers of the outline and 200 characters around the best match) and asks on which of them the value appears. The model can only pick among the pages it was shown and only for fields of the batch; everything else in its answer is dropped. The candidates are the union of both. If the call fails the run goes on with BM25 only (warning locate_failed).
  3. Windows. Candidate pages closer than 2 pages form a cluster; its edges move to the start of a section (outline level 1 or 2) up to 2 pages away; a span longer than 12 pages or than the token budget is cut into windows that share 1 page, preferably right before a section start. A field goes to every window that holds one of its candidates. Fields with no candidate page get a full pass: contiguous windows of 12 pages over the whole document.
  4. Extract. The harness of T06 runs once per window (phase window, at most 4 in parallel, one retry), with the global anchors p{n}_l{m}, so a citation in a window is valid in the document. Every candidate goes through the normalizers and the word-level verifier of T07 before it is consolidated.
  5. Consolidate. See below. A field appears exactly once in the result.

The content of the pages is data in every prompt (delimited block, look-alike delimiters neutralized); logs and warnings never contain document text.

Consolidation and the conflict status

Scalar fields: occurrences are grouped by normalized value. The equal ones merge and the extra occurrences become supporting evidence, so 1.974,96 EUR and 1974.96, 15 de marzo de 2026 and 15/03/2026, or Acme S.L. and ACME SL are support, not conflict. The group whose best occurrence ranks first wins, by this total order:

verified > partial > block_only > unverified > contradicted, then location score (BM25 relative to the field's best page, plus 1 if the model picked the page), then the lower page, then the value and the anchors. It never depends on the order the windows finish in.

If there are two or more distinct values and at least two of them have verification partial or better, the field is a conflict:

  • status = "conflict", review_state = "needs_review", value is the winner's;
  • alternatives has the other values (with the id of their evidence);
  • the evidence has role = "primary" for the winner and role = "contradicting" for the best occurrence of each other value.

A different value that is not anchored (block_only or worse) is only an alternative. Equality rules are configurable per type (EqualityConfig: absolute and relative tolerance for numbers, folded or exact for text). Resolving a conflict is a human decision (T32).

Arrays of primitives are the union without duplicates, in order of first appearance, never a conflict. A field with no usable occurrence ends not_found (every window said so) or abstained.

Failures and coverage

A window that fails is retried once. If it fails again, the fields that could only be there are abstained with the warning window_failed(páginas a-b), and coverage.pages_covered drops below pages_total (coverage.failed_windows lists the windows). A page counts as covered when it was read in a window that succeeded or when location screened it out for every field; pages_read is how many pages were actually sent. A complete-looking result is never returned over a lost window.

Configuration

Knob Default Effect
DX_LONG_DOC_PAGES 12 Pages above which the long path runs.
DX_MAX_CONTEXT_TOKENS model capabilities Also triggers the long path and caps every window.
LongDocConfig.max_pages, .overlap 12, 1 Window size and shared pages.
LongDocConfig.concurrency 4 (and the backend's) Parallel windows.
LongDocConfig.bm25_k, .llm_k, .bm25_min_rel 5, 8, 0.2 Candidates per field.
LongDocConfig.use_llm_locate True False: BM25 plus the full pass only.
LongDocConfig.equality exact numbers, folded text When two values are the same value.

register_field_handler(LongDocumentHandler(LongDocConfig(...)), priority=1) replaces the built-in configuration.

What it costs and where it can fail

On long-docs-v0 (10 contracts of 30 to 120 pages, 100 fields) the input tokens are 0.20 to 0.37 of reading everything by windows from 60 pages on, and about 0.5 to 0.7 below 48 pages (reading 17 of 30 pages is not much of a saving); see the report bench/reports/long-docs-v0.md. The saving depends on how precise the candidates are: with a filler that reuses the words of the labels ("importe", "plazo", "fecha"…) in 2 % of its sentences the worst ratio at 60 pages went from 0.37 to 0.55, and at 8 % to 0.71, because BM25 then proposes many wrong pages. If that is your case, lower bm25_k or raise bm25_min_rel, or trust the model's pick more.

BM25 over whole pages loses precision when a page is very long, and a value stated with other words than the schema's (a paraphrase) may land outside the 8 pages the model sees: that field is not_found rather than invented. The measured location recall is in the report.