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_PAGESpages (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_TOKENSor 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
- Index. One BM25 index over the plain text of the pages (Okapi,
k1 = 1.5,b = 0.75, no third-party dependency; NFKD folding soImporte=importé). - 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", phaselocate) 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 (warninglocate_failed). - 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.
- Extract. The harness of T06 runs once per window (phase
window, at most 4 in parallel, one retry), with the global anchorsp{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. - 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",valueis the winner's;alternativeshas the other values (with the id of their evidence);- the evidence has
role = "primary"for the winner androle = "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.