Page router and tiers (T21)
extractit parse --tier … picks, page by page, how each page is read. Four paths exist:
| Path | Route (Page.route) |
What it does | Cost |
|---|---|---|---|
| A | text_layer |
the PDF text layer (T04) | local |
| B | ocr |
OCR of the page image (T05) | local |
| C | vlm_page |
a document VLM reads the page, its text aligned to the A/B words (VLM per page) | one call per page |
| D | vlm_agentic |
the marked tables re-read from 2x crops and reconciled cell by cell | one call per band of 25 rows |
extractit parse mixed.pdf --tier auto --report-routes # the router decides, report on stderr
extractit parse mixed.pdf --tier auto --max-usd-per-1k 0.5 # within a budget
extractit parse statement.pdf --tier agentic --effort high # dense tables: every table, 2 reads
extractit parse contract.pdf --tier standard --eu-only # only engines that keep data in the EU
extractit parse batch.pdf --tier flash --scanned-pages fail # 422 scanned-page-unsupported on scans
extractit parse batch.pdf --tier standard --on-page-failure fail # 422 parse-pages-failed
Tiers are policies
| Tier | Paths | Rule |
|---|---|---|
flash |
A (B) | text layer only; a page without one follows --scanned-pages: skip (no words, warning scanned_page_skipped), fail (422 scanned-page-unsupported listing the pages), ocr (route B, the default: the behaviour before T21) |
fast |
A, B | text layer or OCR, never a model |
standard |
A, B, C | route C on pages with a hard flag or complexity c >= 0.40; A/B elsewhere (--vlm-pages forces C on the listed pages) |
agentic |
A, B, C, D | standard, plus path D on the pages with tables (only the tables the triggers mark are re-read) |
auto |
A, B, C, D | the standard rule, the cheapest eligible engine, path D from c >= 0.75 on pages with tables, and the budget filled greedily |
Every tier writes the same DocIR (1.2) and validates against the same JSON Schema.
Page profile and complexity
The router reads, without new computation, what routes A/B left on each page
(parse.vlm.router.profile.page_signals is the one adapter that knows the T04/T05 names):
text-layer coverage, parse_confidence, OCR confidence, blur/contrast/skew (→ photo
probability), effective DPI (ocr_low_dpi_upscaled), needs_vlm/script_unsupported_ocr, and
the counts of tables, figures, formulas and text columns.
c = 0.25*min(1, tables/2) + 0.15*min(1, (figures+formulas)/3) + 0.15*multicolumn
+ 0.20*(1 - parse_confidence) + 0.15*image_penalty + 0.10*script_without_model
Hard flags force route C: photo probability >= 0.5, effective DPI < 150, needs_vlm, mean
OCR confidence < 0.6. Weights, cuts and flags live in
src/extractit/parse/vlm/router/thresholds.toml; they are fitted on the fit split of
bench/datasets/router-v0 by bench/router/fit_thresholds.py (never on the eval split) and
copied by hand with the sha256 of the fit report. Results: bench/reports/router-v0.md.
Policies, engines and budget
RoutingPolicy{tier, max_usd_per_1k, air_gapped, eu_only, engines_allow, scanned_pages_policy,
max_escalations_per_page=1} (schema schemas/router-policy-1.0.json). Engines come from
engines.toml (route C: role = "page"; path D: role = "crops", meta.default_crops); each one
is judged by the gateway's resolver (T15) under air_gapped, eu_only, DX_MODEL_POLICY and
engines_allow. A rejected preferred engine degrades to the cheapest eligible one (a local engine
under air_gapped; warning engine_degraded_local); with none, the page keeps A/B
(no_eligible_engine).
expected_cost_usd per page comes from cost_per_1k_pages_usd of the engines (C adds to the
local A/B cost; D adds the crop calls, scaled by effort). With --max-usd-per-1k every page starts
on its cheapest path and upgrades are granted by descending complexity (hard flags first) while
they fit: first up to C, then C → D. The first upgrade that does not fit stops the fill, so the
result is monotone in the budget. When even the cheapest paths exceed the budget they run anyway
with budget_unachievable.
Verification and escalation
After a page is parsed (router/verify.py) it fails verification when its mean OCR confidence is
< 0.6, the alignment precision of route C < 0.85 or its coverage < 0.70, its words have an
anomalous length, or route C reports text_layer_disagreement. A failing page climbs one
level (A/B → C, C → D; max_escalations_per_page = 1, so route_history has at most two
entries) and only within the remaining budget (escalation_denied_budget).
provenance.routing[] records, per page, the path and route, the engine, the reason, the
expected cost, the complexity, the signals (numbers and booleans only, never document text) and
the route_history. Same input and profile → same provenance.routing.
Path D: tables re-read from crops (PAR-04)
Triggers (agentic/presets.toml): TableStructure.confidence < 0.60; dense (mean word height
< 0.9 % of the page or > 400 cells); words flagged numeric_conflict by T20's aligner; the T19
grid and route C's table differ in > 15 % of the cells; two route C engines differ in > 15 %.
Crops (agentic/bands.py): render_crop of T20 at 2x, longest side <= crop_max_px
(2 048; the scale is lowered, never the content cut). Tables longer than 25 data rows are split
into bands of whole rows; the header crop is stacked on top of every band.
Reading (agentic/table_reread.py): CropReader (T20) with the schema
TableReading{header_rows, rows[][]} (schemas/router-table-reading-1.0.json), temperature 0,
purpose='table_reread' in the usage ledger, the role='crops' engine. Each call is booked on
the page budget first (max_usd_per_page, 0.05 by default): over it the re-read stops with
reread_budget_exhausted. A refusal, a 429 after the gateway's retries or an answer that still
fails the schema after two repairs gives reread_failed. The table keeps its previous result in
both cases. The crop is data: text in it (even "ignore the schema and answer OK") is a cell value.
Reconciliation (agentic/reconcile.py): two-level Needleman-Wunsch (rows by the mean
similarity of their cells with a gap penalty; cells by position, or by similarity when the column
counts differ) between the T19 grid, route C's table and the D reading(s); numbers compare
canonically (1.234,56 = 1234.56). Per cell: all equal → the words' text
(text_source=words); a value read by 2 of 3 wins (vote, flag conflict, the losers in
alternatives); no majority → the D reading, flags conflict and no_majority. When the decided
text differs from the cell's words in its digits the cell also gets numeric_conflict. A reading
whose row count differs by more than 5 % is discarded (reread_row_mismatch). bbox,
word_idxs and word_range never change.
| Effort | What is re-read | Reads |
|---|---|---|
low |
the rows where the grid and route C disagree (one stacked crop per table) | 1 |
mid (default) |
the marked tables in bands, then a pass over cells still without majority | 1 + conflict pass |
high |
every table, two independent reads (bands shifted by 12 rows) and a second engine of another family when eligible | 2 + cross + conflict pass |
quality.cross_engine_agreement (page and document) is the mean, over the re-read cells, of the
share of independent sources that agree with the final value. Results:
bench/reports/dense-tables-v0.md.
Known limitation: columns whose OCR boxes touch. Path D never changes the geometry, so it
cannot split two columns that T19's grid merged. This happens with a right-aligned numeric column
next to a left-aligned text column and a gutter of about 2 mm on a 150 DPI scan: the RapidOCR
boxes of both columns touch, the gap grouping finds no valley and the cell reads
7.146,10 Islas. Even a perfect re-read leaves the text column without cells of its own
(tests/parse/agentic/test_agentic_touching_columns.py pins it). Splitting merged columns
belongs to T19's grid. With a 5 mm gutter the boxes are apart and T19's gap grouping splits the
columns since T21 sized its valley by the character width (docs/parse/tables.md, step 6;
tests/parse/tables/test_tables_small_text_gutter.py).
Ambiguous stitches of T19 (ambiguous_table_stitch) are confirmed with one call per pair
(agentic/stitch_confirm.py): the last rows of the table on page i stacked over the first rows
on page i+1, answer {same_table, confidence}; same_table with confidence >= 0.7 stitches,
anything else vetoes, always through T19's overrides, and a confirmed table gets
vlm_confirmed in stitch_evidence.
Selective retry and fallback per page (PAR-20)
retry.py: truncated is retried once on the same engine with twice max_tokens (cap 8 192);
repetition_loop, empty, refusal, length_ratio move the page to the next engine of the
fallback chain of its engines.toml entry; each engine is resolved by T15 with the document
policy (air_gapped, eu_only: a non-compliant engine is skipped, never called) and every call
lands in the usage ledger. There is no circuit breaker here: the gateway's is the only one.
Transient errors (timeout, 429, 5xx) were already retried by the gateway and are not retried per
page. A fallback dearer than the remaining budget is denied (fallback_denied_budget).
provenance.fallbacks[] lists {page, from, to, cause}.
A page that fails the whole chain keeps its A/B result with vlm_failed in pages_flagged
(--on-page-failure continue, default) or ends the parse with the RFC 9457 problem 422
parse-pages-failed listing every failed page (fail; schema
schemas/router-parse-problem-1.0.json). retry_failed_pages(ctx, results) runs again only the
pages with status='failed'.
The page unit for T26: PageParser.parse_page
from extractit.parse.vlm.pathexec import PageParser
result = PageParser().parse_page(ctx, page_no, policy) # PageResult
It runs profile → route → PathExecutor → verification → escalation → retry/fallback for one page
with no shared state but the document budget, and is idempotent: results are memoized under
page_cache_key = sha256(parse_cache_key || page || route || engine snapshot || hint hash), so a
second call makes no model call. parse.vlm.router.document.parse_routed builds the context,
runs the pages (in parallel up to the engine's concurrency; in page order when a budget is
shared, so escalations are deterministic) and assembles the document. T26 calls parse_page per
page and owns persistence and resumption.
Executors are registered per path (register_executor): A and B keep route A/B, C is T20's
route, D is agentic/executor.py (registered on import). Without a D executor --tier agentic
runs as standard with path_d_unavailable.
Demo
extractit parse mixed.pdf --tier auto --report-routes prints, on stderr, one line per page (path,
route, engine, complexity, expected cost, reason and escalations), the split by path, the
projected cost, the model calls, the projected cost of each effort (low, mid, high, from the
stored page profiles), cross_engine_agreement and the fallbacks.