Document-to-Graph Pipeline (docling-graph)#

docling-graph transforms documents (PDF, DOCX, PPTX, images, Markdown, HTML, DocLang, and everything else Docling supports) into validated, queryable knowledge graphs 1. It targets high-precision use cases — chemistry, finance, legal — where exact entity relationships matter more than text embeddings 1.

Two extraction backends are available 2:

• LLM — routed through LiteLLM; works with OpenAI, Gemini, Mistral, IBM watsonx, vLLM, Ollama, and more
• VLM — local Docling-native visual language model extraction

Install:

pip install docling-graph # core + LLM backend
pip install "docling-graph[vlm]" # adds VLM backend

3

The main entry points are run_pipeline(config) (Python) and docling-graph convert (CLI), both returning a PipelineContext with knowledge_graph, extracted_models, and graph_metadata 4.

Pipeline Stages#

All stages are defined in docling_graph/pipeline/stages.py as independent PipelineStage subclasses that pass a PipelineContext forward:

Short-circuit for pre-parsed inputs: When the source is a DoclingDocument JSON or DocLang file, InputNormalizationStage sets skip_document_conversion=True and ExtractionStage routes directly to extract_from_document() — no OCR or layout models are invoked 12 13. This is the recommended way to re-extract with a different template without re-paying the conversion cost 14.

Extraction — Docling Conversion & LLM Backends#

ExtractionStage delegates to ExtractorFactory.create_extractor(), configured by the backend, extraction_contract, and processing_mode settings 15.

Docling conversion (OCR, layout, table structure, formula/code extraction) produces a DoclingDocument — a schema-versioned JSON carrying all text, tables, figures, and page-level bounding boxes. The LLM then receives this structured representation rather than raw bytes.

Extraction contracts (set via extraction_contract) control how document content is sent to the LLM:

• "auto" (default) — selects direct or dense per-document based on size
• "direct" — single LLM call over the full document; optional gleaning pass for recall
• "dense" — two-phase skeleton→fill for large or complex documents

See Document Extraction Strategies for the complete comparison 16.

LLM input format (llm_input_format): "doclang-geo" (DocLang XML with bounding-box geometry) pairs with direct; "doclang" (without geometry) pairs with dense; "auto" resolves automatically 17.

Remote Docling conversion: Setting docling_serve_url delegates the conversion step to a running docling-serve instance while keeping LLM extraction local 18.

Graph Construction & Provenance#

GraphConversionStage calls GraphConverter.pydantic_list_to_graph() to turn the list of extracted Pydantic models into a NetworkX DiGraph. Each Pydantic model class annotated is_entity=True becomes a node type; fields declared with edge("REL_TYPE", ...) become directed edges 19.

Stable node IDs are derived deterministically from graph_id_fields in the template's model_config 20.

Provenance is attached by default (provenance="standard") to every node as a __provenance__ attribute pointing to the source chunk and page — no extra LLM calls 21. The full provenance ledger is written to provenance.json alongside the graph outputs 22. Setting provenance="detailed" additionally embeds character spans directly on node attributes 23.

Alias reconciliation collapses duplicate entity mentions after extraction using an LLM identity call 24; the VLM backend skips this step.

Export Formats & Neo4j Integration#

ExportStage writes to the docling_graph/ subdirectory of the output folder. JSON (graph.json) is always written; export_format selects whether CSV or Cypher is also emitted 25.

26

Cypher Export#

CypherExporter generates ;-terminated, self-contained Cypher statements ready for cypher-shell. It emits per-label UNIQUE constraints at the top of the script so every MERGE/MATCH is index-backed 27. Property types are preserved: numbers, booleans, and homogeneous scalar lists become Cypher literals; dicts (including __provenance__) become JSON strings 28.

Two styles:

• "merge" (default) — idempotent; re-running updates properties in place without duplicating nodes 29
• "create" — plain CREATE statements; faster for a one-shot bulk load into an empty database 29

Importing into Neo4j#

Three options 30:

# Recommended: cypher-shell
cypher-shell -u neo4j -p password -f outputs/graph.cypher

# Python neo4j driver (statement-by-statement)
from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
code = "\n".join(l for l in cypher_script.splitlines() if not l.startswith("//"))
with driver.session() as session:
    for stmt in code.split(";\n"):
        if stmt.strip():
            session.run(stmt)

Or paste into the Neo4j Browser at http://localhost:7474.

In-Memory Round-Trip (no files)#

Use graph_to_dict() / load_graph_from_dict() to avoid writing to disk when serving graphs over HTTP or in tests 31.

Key Files & References#

Related KB articles:

• Document Extraction Strategies — direct / dense / auto extraction contracts in depth
• Docling Python Library Reference — DocumentConverter, DoclingDocument, chunking