Skip to content

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.