Skip to content

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.