Document Extraction Strategies#

docling-graph offers three values for extraction_contract — "direct", "dense", and "auto" (default) — that control how the pipeline sends document content to the LLM for entity extraction. The choice affects latency, token cost, and accuracy for documents of different sizes.

Extraction Contracts#

Auto (default)#

"auto" makes a per-document decision after the document's actual size is known 1. It resolves to direct when both conditions hold:

1. The estimated input + output budget fits the model's context window.
2. The document is small enough that a single response can represent it (input within DIRECT_OVERFLOW_RATIO = 1.0 × output character capacity).

Otherwise it resolves to dense. If chunking is disabled, direct is always used regardless of document size 2. The decision is logged per document. The in-code rationale explains the motivation: a 36k-character paper run with direct scored node-F1 0.04 vs 0.14 with dense 3.

Token estimation uses a conservative CHARS_PER_TOKEN = 4 4.

Direct#

"direct" performs best-effort extraction in a single LLM call over the full (or chunked) document 5. It suits small documents where everything fits within the model's context window.

An optional gleaning pass (gleaning_enabled=True, default) runs after the primary call: it shows the LLM what was already extracted and asks "what did you miss?", then merges any additional entities into the result 6. The llm_input_format defaults to "doclang-geo" (DocLang XML with geometry) when direct is resolved 7.

Dense#

"dense" uses a two-phase skeleton → fill orchestration designed for large or complex documents 8:

• Phase 1 (skeleton): Chunks the document into batches (default dense_skeleton_batch_tokens=2048) and runs entity-discovery prompts over each batch. Nodes are tracked with batch-local integer handles (i for self, p for parent) to minimize output tokens. If the model truncates a batch's output, the batch is recursively split in half (up to 4 levels) 9.
• Phase 2 (fill): Populates entity attributes. Each fill call is scoped to the document regions where the skeleton node was observed (dense_fill_context="scoped", default), keeping token cost proportional to entities being filled — not to document length 10. Up to dense_fill_nodes_cap=5 node instances are packed per fill call 11.

After Phase 1, a deduplication step reconciles aliases (dense_dedupe="standard" by default runs one LLM reconciliation call to collapse same-entity aliases; "aggressive" also merges near-identical strings from OCR noise) 12.

The llm_input_format defaults to "doclang" (DocLang XML without geometry) when dense is resolved 7.

The entry point is run_dense_orchestrator(), which returns a root result, run stats, and a provenance ledger.

Quick Reference: When to Use Each#

Reusing Pre-Parsed DoclingDocument Objects#

Docling conversion (OCR, layout analysis, segmentation) is the most expensive step in the pipeline. docling-graph lets you skip it on subsequent runs by reusing an already-parsed document.

Workflow:

1. Run the pipeline with export_docling_json=True (default). This writes the DoclingDocument as a JSON file alongside other outputs 13 14.
2. In a subsequent run, set source to the exported .json path and provide a new template.
3. InputTypeDetector recognizes the JSON as InputType.DOCLING_DOCUMENT by inspecting for fields like "schema_name", "pages", and "main_text".
4. The DoclingDocumentHandler loads the JSON via DoclingDocument.from_dict() and stores it in context.docling_document; context.normalized_source is set to None 15 16.
5. ExtractionStage detects the pre-loaded document and routes directly to _extract_from_docling_document() with the new template — no conversion models are invoked 17.

DocLang files (.dclg, .dclg.xml, .dclx) follow the same bypass path via DoclangInputHandler 18 19.

This pattern is the recommended way to experiment with multiple templates on the same document without paying the conversion cost each time. The exported JSON from a first run becomes the reusable artifact for all subsequent extractions 20.

Key Configuration Fields (PipelineConfig)#