Extraction pipeline and output
extractit FILE and extractit.extract() run the whole core in-process — no database, no
service, only the parse cache under $DX_HOME:
ingest → parse (T04) → extract (T06 on to_anchored_markdown) → normalize → verify (T07)
→ rules (T09) → confidence → assemble
extractit tests/fixtures/digital/invoice.pdf --schema examples/invoice.schema.json \
--model fake:tests/cassettes/pipeline -o out.json
extractit invoice.pdf --schema examples/invoice.schema.json --format table --tier agentic \
--rules rules.json --fail-on-review
import extractit
out = extractit.extract("invoice.pdf", "examples/invoice.schema.json", model="gemini")
out.data["total"], out.requires_review
The fake model of the first command answers from the synthetic cassettes in
tests/cassettes/pipeline/extract/ (regenerate them with tests/pipeline/make_cassettes.py).
Command line
| Option | Meaning |
|---|---|
--schema S |
JSON schema file, or module:Class of a Pydantic model (the current directory is importable). |
--model M |
Backend as in DX_MODEL: gemini[:alias], codex[:model], fake[:cassette dir]. |
--tier T |
fast, standard (default) or agentic; anything else exits with 2 and the list. |
--rules R |
Validation rules file (T09). |
-o OUT |
Write the JSON here (atomically, only after a successful run). |
--format |
json (default; printed when there is no -o) or table. |
--no-cache |
Parse again even if the parse cache has the document. |
--deterministic |
Durations zero and model call ids derived from the document hash: two runs with the fake model give byte-identical files. |
--fail-on-review |
Exit with 3 when requires_review is true. |
Exit codes: 0 done (also when requires_review is true), 1 execution error (the message
names the step, e.g. extract: GatewayError … [step=extract, kind=model]), 2 incorrect usage
or unsupported input (unknown tier, invalid schema or rules, not a PDF, image or Office file,
encrypted PDF, larger than DX_MAX_FILE_MB — 25 MB by default), 3 --fail-on-review with a
review pending. Error messages and logs never contain document text.
The table shows field, value, confidence with band, verification of the primary evidence, the
rules that cite the field, and a footer with the document confidence, requires_review, tokens,
cost and time.
Tiers
Tiers are configuration (src/extractit/extract/tiers.toml), not separate pipelines:
| Tier | Model alias | Passes | Self-consistency |
|---|---|---|---|
fast |
fast |
1 | no |
standard |
standard |
1 | no |
agentic |
strong |
1 | k = 3 on fields in bands low/medium, at most 30 % of the fields, temperature 0.3, max_usd_extra 0.25 USD |
--model/DX_MODEL choose the provider and the tier the alias; a spec that names a snapshot
(gemini:<snapshot>) wins over the alias. With Codex the aliases do not select different models,
so tiers only differ in the extra passes.
Selective self-consistency (agentic): after the first pass is verified and scored, the
fields in the doubtful bands are re-extracted k − 1 times each with only_field_ids, lowest
score first and at most floor(0.3 × fields) of them (warning sc_capped beyond). Every sample
is normalized and verified; the final value is the plurality by normalized value, ties broken by
the best verification and then by the first pass. signals.sample_agreement is the fraction of
the k samples equal to the final value. Seeds are recorded in reproducibility.seeds. Once
max_usd_extra is spent the first pass is kept (warning extra_passes_budget_exhausted). The
voting report with the stochastic fake model is in bench/reports/self-consistency-voting.md.
Field states
| State | When | value |
confidence |
|---|---|---|---|
extracted |
the value was normalized and (if the field requires it) verified | typed | score |
not_found |
the model said the document does not contain it | null |
null |
abstained |
the model abstained; normalization failed (ambiguous number, invalid date… — raw_text is kept and the readings go to alternatives); or evidence: required and the citation is unverified (the candidate becomes an alternative) |
null |
null |
conflict |
T07 found contradicting evidence; the primary value is kept | typed | score × 0.70 |
derived, looked_up, from_metadata |
resolved by a source kind (extending) | typed | score |
review_state is needs_review for a low band, abstained, conflict or a required field
without value, auto_approved otherwise. requires_review is true when a required field is in
the low band, absent, abstained or in conflict, or when a blocking rule fails or is
inconclusive (unless the rule says on_inconclusive: ignore).
Heuristic confidence
Without a calibrator confidence.kind is heuristic: the score ranks fields by how much support
they have, it is not a calibrated probability. With an active calibrator of the run's model
snapshot and prompt (T39, PipelineOptions.confidence_post) a field reports
kind: calibrated_probability; with a calibrator of another snapshot or prompt it stays heuristic
with reason: calibrator_stale. See Calibrated confidence.
score = base(grounding) × validation × OCR × agreement × conflict × corrected × logprobs
| Signal | Factor |
|---|---|
| grounding (base) | verified 0.95 · partial 0.75 · block_only 0.60 · unverified 0.30 · contradicted 0.10 |
| validation | an error rule on the field fails 0.50 · inconclusive 0.90 · pass or no rule 1.0 |
| OCR | max(0.5, ocr_min_conf) of the cited words; 1.0 for native text |
| sample agreement | 0.6 + 0.4 × sample_agreement (self-consistency only) |
| conflict | 0.70 |
| citation corrected by T07 | 0.90 |
| token log-probabilities | 0.7 + 0.3 × exp(token_logprob_mean) when the provider offers them (neither Gemini nor Codex today) |
The score is clamped to [0, 1] and rounded to 4 decimals. Bands: high ≥ 0.9, medium ≥ 0.7,
low below. Examples: verified + pass = 0.95; partial + fail = 0.375; verified with
OCR 0.85 = 0.8075.
Rules see a pre-confidence without the validation factor (so a confidence rule does not depend
on its own verdict); the final score applies it. A rule touches the fields whose evidence it cites
(evidence_ids) or that it names in compared_values; warning and info failures do not lower the
score.
Document confidence: minimum of the required fields with a value (every field with a value
when the schema has no required field) and the parse_confidence of T05 when present; a required
field absent or abstained caps it at 0.5. Operator confidence: parse (DocIR
parse_confidence; native pages 1.0, pages without text 0.0), extract (mean of the field
scores) and validate (pass / (pass + fail), null without rules).
Scanned documents
The pipeline never imports OCR modules: parse returns whatever the parse engine produces. A page
without a text layer carries the DocIR warning needs_ocr; if the document has no text at all,
no model is called, every field is not_found and the output warns no_text. With T05 integrated
the same command reads scanned pages through OCR.
Output
schema_version, extraction{mode, tier, model}, document, typed nested data, flat
fields with evidence down to words, document_confidence, operator_confidence,
requires_review, validations, usage (model calls of the T03 ledger, plus one row per step
with its duration, calls, tokens and cost), reproducibility, warnings, strategy
(single_pass or long_document), coverage (only for long documents) and table_stats (only
when an x-dx.table field was extracted: the rows seen, extracted, excluded and merged per table).
It validates against
schemas/output-1.2.json. Shortened output of the first command above with --deterministic
(one field shown in full; words and rows trimmed):
{
"schema_version": "1.2",
"extraction": {"mode": "llm", "tier": "standard", "model": "fake:standard", "agent": null},
"document": {
"sha256": "c5685f1a77f8d530a93a5a97b97199854c99140d9f5f5ac9d016316b51dfc431",
"pages": 1,
"routes": {"1": "text_layer"},
"pdoc_id": "pdoc_455hhthv8ne9bba0vsdsqt3s1y",
"filename": "invoice.pdf"
},
"data": {
"invoice_number": "INV-2026-0042",
"issue_date": "2026-03-15",
"due_date": "2026-04-14",
"currency": "EUR",
"supplier_name": "ACME Industrial Supplies S.L.",
"supplier_vat_id": "B12345678",
"supplier_iban": null,
"total": 372,
"tax_amount": null,
"paid": null,
"line_items": [
{"description": "Steel bracket 40mm", "quantity": 10, "unit_price": 12.5, "amount": 125}
]
},
"fields": [
{
"path": "invoice_number",
"field_id": "fld_0fjsqq6cs4ebga3vxcyj4r6jg9",
"value": "INV-2026-0042",
"raw_text": "INV-2026-0042",
"status": "extracted",
"confidence": {
"score": 0.95,
"kind": "heuristic",
"band": "high",
"signals": {
"grounding": "verified", "validation": null, "ocr_min_conf": null,
"parse_route": "text_layer", "page_quality": null, "sample_agreement": null,
"token_logprob_mean": null, "verbalized": null, "conflict": null,
"citation_corrected": null
},
"calibrator": null,
"threshold_policy_id": null
},
"evidence": [
{
"id": "ev_2wfp0vt991e0rt5y2b5yyd5fw7",
"kind": "document_span",
"role": "primary",
"page": 1,
"anchor": "p1_l2",
"quote": "INV-2026-0042",
"char_span": [8, 21],
"word_range": {"start": 8, "end": 9},
"words": [
{"text": "INV-2026-0042", "bbox": {"x0": 0.2833, "y0": 0.0712, "x1": 0.5341, "y1": 0.0955}, "word_idx": 8}
],
"regions": [
{"page": 1, "bbox": {"x0": 0.2833, "y0": 0.0712, "x1": 0.5341, "y1": 0.0955}, "polygon": null}
],
"table_ref": null,
"verification": "verified",
"match": {"method": "exact", "score": 1.0, "normalized_value": "INV-2026-0042"},
"citation_corrected": false,
"produced_by": {"model_call_id": "mc_b71efd090e9db772ab1a", "aligner_version": "dx-ground/1"}
}
],
"alternatives": [],
"review_state": "auto_approved"
},
{
"path": "supplier_iban",
"field_id": "fld_0m5rky8g34f4srr4ypzd2bta8a",
"value": null,
"raw_text": null,
"status": "not_found",
"confidence": null,
"evidence": [],
"alternatives": [],
"review_state": "auto_approved"
}
],
"document_confidence": {"score": 0.95, "kind": "heuristic", "band": "high", "signals": {}, "calibrator": null, "threshold_policy_id": null},
"operator_confidence": {"parse": 1.0, "extract": 0.95, "validate": null},
"requires_review": false,
"validations": [],
"usage": {
"model": "standard",
"model_snapshot": "fake-1",
"billing": "none",
"input_tokens": 100,
"output_tokens": 20,
"cost_usd": null,
"duration_ms": 0,
"steps": [
{"step": "ingest", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "parse", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "extract", "duration_ms": 0, "model_calls": 1, "input_tokens": 100, "output_tokens": 20, "cost_usd": null},
{"step": "normalize", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "verify", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "rules", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "confidence", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null},
{"step": "assemble", "duration_ms": 0, "model_calls": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": null}
]
},
"reproducibility": {
"schema_hash": "65d7d5406149df67f4ce546e7df69e281f3595e8b83ada34a2d3df2470fb5e6d",
"prompt_hash": "a6c5a13afaeeb61e90f6f0e8686edfbe596c50caa01dd28c1fc0a9d655592257",
"model_snapshot": "fake-1",
"engine_versions": {
"docling-parse": "7.25.0", "pypdfium2": "5.15.2", "docling-heron": "8f39ad3c0b4c",
"docling-tableformer": "fast", "docling": "2.149.0"
},
"parse_cache_key": "8fd66fac6236685462e6dddb50a51a8ed91b9c4380b23cd948ce4c58f60f7d8e",
"docir_version": "1.0",
"tier": "standard",
"seeds": [],
"deterministic": true
},
"warnings": [],
"strategy": "single_pass",
"coverage": null,
"table_stats": null
}
Library API
| Function | Purpose |
|---|---|
extract(source, schema, *, model=None, tier='standard', rules=None, parse_profile=None, options=PipelineOptions()) |
The whole pipeline; extract_async is the coroutine. |
finalize(doc, schema, candidates, *, rules=None, extraction=ExtractionMeta(mode='llm'), options) |
Normalize, verify, validate, score and assemble candidates obtained elsewhere (agent mode, T10). |
build_extraction_request(source, schema, *, options, tier) |
Parse, render and build the harness request without calling a model (extractit task, T10). |
PipelineOptions{deterministic, max_file_mb, cache, fail_on_review, engine, validator, seed, locale_hint} |
Knobs; cache is True, False or a ParseCache. |
Errors: PipelineError{step, kind, cause} (kind = 'input' for unusable input,
UnsupportedInputError for files that are not PDFs), UnknownTierError, SchemaValidationError.
Pipeline extension points are described in Extending the pipeline.