docling-graph 1.5.0

A tool to convert documents into knowledge graphs using Docling.

Docling Graph

Docling-Graph turns documents into validated Pydantic objects, then builds a directed knowledge graph with explicit semantic relationships.

This transformation enables high-precision use cases in chemistry, finance, and legal domains, where AI must capture exact entity connections (compounds and reactions, instruments and dependencies, properties and measurements) rather than rely on approximate text embeddings.

This toolkit supports two extraction paths: local VLM extraction via Docling, and LLM-based extraction routed through LiteLLM for local runtimes (vLLM, Ollama) and API providers (Mistral, OpenAI, Gemini, IBM WatsonX), all orchestrated through a flexible, config-driven pipeline.

Key Capabilities

• ✍🏻 Input formats: Docling’s supported inputs: PDF, images, markdown, Office, HTML, and more.

• 🧠 Extraction: LLM or VLM backends, with chunking and processing modes.

• 💎 Graphs: Pydantic → NetworkX directed graphs with stable IDs and edge metadata.

• 📦 Export: CSV, Cypher, and other KG-friendly formats.

• 🔍 Visualization: Interactive HTML and Markdown reports.

Latest Changes

• 🪜 Multi-pass extraction: Delta and staged contracts (experimental).

• 📐 Structured extraction: LLM output is schema-enforced by default; see CLI and API to disable.

• ✨ LiteLLM: Single interface for vLLM, OpenAI, Mistral, WatsonX, and more.

• 🐛 Trace capture: Debug exports for extraction and fallback diagnostics.

Coming Soon

• 🧩 Interactive Template Builder: Guided workflows for building Pydantic templates.

• 🧲 Ontology-Based Templates: Match content to the best Pydantic template using semantic similarity.

• 💾 Graph Database Integration: Export data straight into Neo4j, ArangoDB, and similar databases.

Quick Start

Requirements

• Python 3.10 or higher

Installation

pip install docling-graph

This installs the core package with VLM support and LiteLLM for LLM providers. For detailed installation instructions (including optional extras and GPU setup), see Installation Guide.

API Key Setup (Remote Inference)

export OPENAI_API_KEY="..."        # OpenAI
export MISTRAL_API_KEY="..."       # Mistral
export GEMINI_API_KEY="..."        # Google Gemini

# IBM WatsonX
export WATSONX_API_KEY="..."       # IBM WatsonX API Key
export WATSONX_PROJECT_ID="..."    # IBM WatsonX Project ID
export WATSONX_URL="..."           # IBM WatsonX URL (optional)

Basic Usage

CLI

# Initialize configuration
docling-graph init

# Convert document from URL (each line except the last must end with \)
docling-graph convert "https://arxiv.org/pdf/2207.02720" \
    --template "docs.examples.templates.rheology_research.ScholarlyRheologyPaper" \
    --processing-mode "many-to-one" \
    --extraction-contract "staged" \
    --debug

# Visualize results
docling-graph inspect outputs

Python API - Default Behavior

from docling_graph import run_pipeline, PipelineContext
from docs.examples.templates.rheology_research import ScholarlyRheologyPaper

# Create configuration
config = {
    "source": "https://arxiv.org/pdf/2207.02720",
    "template": ScholarlyRheologyPaper,
    "backend": "llm",
    "inference": "remote",
    "processing_mode": "many-to-one",
    "extraction_contract": "staged",  # robust for smaller models
    "provider_override": "mistral",
    "model_override": "mistral-medium-latest",
    "structured_output": True,  # default
    "use_chunking": True,
}

# Run pipeline - returns data directly, no files written to disk
context: PipelineContext = run_pipeline(config)

# Access results
graph = context.knowledge_graph
models = context.extracted_models
metadata = context.graph_metadata

print(f"Extracted {len(models)} model(s)")
print(f"Graph: {graph.number_of_nodes()} nodes, {graph.number_of_edges()} edges")

For debugging, use --debug with the CLI to save intermediate artifacts to disk; see Trace Data & Debugging. For more examples, see Examples.

Pydantic Templates

Templates define both the extraction schema and the resulting graph structure.

from pydantic import BaseModel, Field
from docling_graph.utils import edge

class Person(BaseModel):
    """Person entity with stable ID."""
    model_config = {
        'is_entity': True,
        'graph_id_fields': ['last_name', 'date_of_birth']
    }
    
    first_name: str = Field(description="Person's first name")
    last_name: str = Field(description="Person's last name")
    date_of_birth: str = Field(description="Date of birth (YYYY-MM-DD)")

class Organization(BaseModel):
    """Organization entity."""
    model_config = {'is_entity': True}
    
    name: str = Field(description="Organization name")
    employees: list[Person] = edge("EMPLOYS", description="List of employees")

For complete guidance, see:

• Schema Definition Guide
• Template Basics
• Example Templates

Documentation

Comprehensive documentation can be found on Docling Graph's Page.

Documentation Structure

The documentation follows the docling-graph pipeline stages:

1. Introduction - Overview and core concepts
2. Installation - Setup and environment configuration
3. Schema Definition - Creating Pydantic templates
4. Pipeline Configuration - Configuring the extraction pipeline
5. Extraction Process - Document conversion and extraction
6. Graph Management - Exporting and visualizing graphs
7. CLI Reference - Command-line interface guide
8. Python API - Programmatic usage
9. Examples - Working code examples
10. Advanced Topics - Performance, testing, error handling
11. API Reference - Detailed API documentation
12. Community - Contributing and development guide

Contributing

We welcome contributions! Please see:

• Contributing Guidelines - How to contribute
• Development Guide - Development setup

Development Setup

# Clone and setup
git clone https://github.com/docling-project/docling-graph
cd docling-graph

# Install with dev dependencies
uv sync --extra dev

# Run Execute pre-commit checks
uv run pre-commit run --all-files

License

MIT License - see LICENSE for details.

Acknowledgments

Docling Graph builds on outstanding open-source projects:

• Docling - document conversion and VLM extraction
• Pydantic - schema definition and validation
• NetworkX - graph construction and analysis
• LiteLLM - unified LLM provider interface
• SpaCy - semantic entity resolution in delta extraction
• Cytoscape - interactive graph visualization

IBM ❤️ Open Source AI

Docling Graph has been brought to you by IBM.