convert Command¶

Overview¶

The convert command transforms documents into knowledge graphs using configurable extraction pipelines.

Key Features:

Multiple backend support (LLM/VLM)
Flexible processing modes
Configurable chunking
Multiple export formats
Batch processing support

Basic Usage¶

uv run docling-graph convert SOURCE --template TEMPLATE [OPTIONS]

Required Arguments¶

Argument	Description
`SOURCE`	Path to document (PDF, JPG, PNG, TXT, MD), URL, or DoclingDocument JSON
`--template`, `-t`	Dotted path to Pydantic template

Examples¶

# PDF document
uv run docling-graph convert invoice.pdf \
    --template "templates.BillingDocument"

# Text file
uv run docling-graph convert notes.txt \
    --template "templates.Report" \
    --backend llm

# URL
uv run docling-graph convert https://example.com/doc.pdf \
    --template "templates.BillingDocument"

# Markdown file
uv run docling-graph convert README.md \
    --template "templates.Documentation" \
    --backend llm

Core Options¶

Debug Mode¶

--debug

Enable debug mode to save all intermediate extraction artifacts for debugging and analysis.

When to use:

Debugging extraction issues
Analyzing extraction quality
Performance profiling
Development and testing

Output: All debug artifacts saved to outputs/{document}_{timestamp}/debug/

Example:

# Enable debug mode
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --debug

# Debug artifacts will be in:
# outputs/document_pdf_20260206_094500/debug/

See Debug Mode Documentation for details on debug artifacts.

Backend Selection¶

--backend {llm|vlm}

LLM (Language Model):

Best for text-heavy documents
Supports chunking and consolidation
Works with local and remote providers

VLM (Vision-Language Model):

Best for forms and structured layouts
Processes images directly
Local inference only

Example:

# Use LLM backend
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm

# Use VLM backend
uv run docling-graph convert form.jpg \
    --template "templates.IDCard" \
    --backend vlm

Inference Mode¶

--inference {local|remote}

Local:

Run models on your machine
Requires GPU for best performance
No API costs

Remote:

Use cloud API providers
Requires API key
Pay per request

Example:

# Local inference
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference local

# Remote inference
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference remote

Processing Mode¶

--processing-mode {one-to-one|many-to-one}

many-to-one (recommended):

Merge all pages into single graph
Better for multi-page documents
Enables consolidation

one-to-one:

Create separate graph per page
Better for independent pages
Faster processing

Example:

# Merge all pages
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one

# Process pages separately
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode one-to-one

Model Configuration¶

Provider Override¶

--provider PROVIDER

Available providers:

Local: vllm, ollama, lmstudio
Remote: mistral, openai, gemini, watsonx, bedrock

Model Override¶

--model MODEL

Example:

# Use specific model
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --provider mistral \
    --model mistral-large-latest

LLM connection overrides¶

Use --llm-base-url to point to a custom endpoint (e.g. on-prem OpenAI-compatible server). API keys are set via environment variables or config.yaml (llm_overrides.connection), not CLI. See LLM Model Configuration for the full list of overrides and on-prem setup.

For LM Studio (--provider lmstudio): override the base URL with LM_STUDIO_API_BASE or --llm-base-url; when the server requires auth, set LM_STUDIO_API_KEY or llm_overrides.connection.api_key in config.

For the on-prem flow (openai-compatible), use fixed env vars:

export CUSTOM_LLM_BASE_URL="https://your-llm.example.com/v1"
export CUSTOM_LLM_API_KEY="your-api-key"

Extraction Options¶

Chunking¶

--use-chunking / --no-use-chunking

Enable chunking for:

Large documents (>5 pages)
Documents exceeding context limits
Better extraction accuracy

Disable chunking for:

Small documents
When full context is needed
Faster processing

Example:

# Enable chunking (default)
uv run docling-graph convert large_doc.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --use-chunking

# Disable chunking
uv run docling-graph convert small_doc.pdf \
    --template "templates.BillingDocument" \
    --no-use-chunking

Extraction contract¶

--extraction-contract accepts auto (default), direct, or dense:

auto (default) — resolves to direct or dense per document once its converted size is known: direct only when a single call fits both the model's context window and its output-token budget. The decision is logged as [AutoContract] Resolved contract=... (...) with the token estimates that drove it.
direct — always a single full-document call, fastest for documents that fit the model.
dense — always two-phase skeleton-then-flesh over chunks; scales to documents far beyond the model's context window.

Dense extraction¶

Use --extraction-contract dense for two-phase skeleton-then-flesh extraction (many-to-one, chunking required). Phase 1 discovers all entity instances per catalog path; Phase 2 fills each instance with full schema data from the document. See Dense Extraction and Configuration reference.

Dense options map 1:1 to CLI flags:

--dense-skeleton-batch-tokens INT   # max tokens per Phase 1 skeleton batch (default: 2048)
--dense-fill-nodes-cap INT          # max node instances per Phase 2 fill call (default: 5)
--dense-fill-context [scoped|full]  # document context per fill call (default: scoped)
--dense-dedupe [off|standard|aggressive]  # skeleton dedupe intensity (default: standard)

Gleaning (direct contract)¶

Optional second-pass extraction ("what did you miss?") to improve recall on the direct contract. Enabled by default.

--gleaning / --no-gleaning

Example (dense with tuned batching):

uv run docling-graph convert document.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --processing-mode many-to-one \
    --extraction-contract dense \
    --use-chunking \
    --dense-dedupe aggressive \
    --parallel-workers 2

Example (basic dense):

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one \
    --extraction-contract dense \
    --use-chunking \
    --parallel-workers 2

Provenance¶

Deterministic data grounding — maps every graph node back to its source chunk(s) and page(s). No LLM involvement; applies to both direct and dense contracts. Enabled by default.

--provenance {off|standard|detailed}

standard (default): __provenance__ node attribute + provenance.json export.
detailed: also embeds character-offset spans in the node attribute.
off: disables grounding entirely (output is byte-identical to the feature not existing).

Example:

uv run docling-graph convert document.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --processing-mode many-to-one \
    --extraction-contract dense \
    --provenance detailed

See Data Grounding & Provenance for the node attribute shape and the full provenance.json schema.

Structured Output Mode¶

Structured output is enabled by default for LLM extraction and enforces schema through LiteLLM response_format=json_schema.

--schema-enforced-llm / --no-schema-enforced-llm
--structured-sparse-check / --no-structured-sparse-check

Use --schema-enforced-llm (default) for strict schema-constrained output.
Use --no-schema-enforced-llm to fall back to legacy prompt-embedded schema mode.
Use --no-structured-sparse-check to disable the sparse structured-result quality guard.
When schema mode fails at runtime (unsupported backend/model or malformed request), Docling Graph logs the error and automatically retries once using legacy prompt-schema mode.
Even when schema mode succeeds technically, Docling Graph can trigger the same fallback once if the structured payload is detected as obviously sparse for the target schema.

Example:

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one \
    --extraction-contract dense \
    --use-chunking \
    --parallel-workers 4

LLM Streaming¶

--llm-streaming / --no-llm-streaming

Enable or disable streaming responses from the LLM.

Default: --no-llm-streaming (disabled)

Use case: Streaming helps avoid timeout issues in infrastructure environments with strict connection timeout constraints. When enabled, the LLM response is received incrementally as chunks, keeping the connection alive even during long-running extractions.

When to use:

✅ Constrained infrastructure with strict timeouts
✅ Long-running extractions that may exceed connection limits
✅ Environments with aggressive proxy/gateway timeouts
✅ Large documents with extended processing times

Note: The current implementation accumulates all streaming chunks before parsing, so there is no latency benefit. The primary benefit is maintaining connection liveness in timeout-constrained environments.

Example:

# Enable streaming to avoid timeouts
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --llm-streaming

# Explicitly disable streaming (default behavior)
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --no-llm-streaming

See Also:

Streaming Responses Recipe - CLI examples
Python API Streaming - Programmatic usage
LLM Clients Reference - Streaming API details

Docling Configuration¶

Pipeline Selection¶

--docling-pipeline {ocr|vision}

OCR Pipeline:

Traditional OCR approach
Most accurate for standard documents
Faster processing

Vision Pipeline:

Uses Granite-Docling VLM
Better for complex layouts
Handles tables and figures better

Example:

# Use OCR pipeline (default)
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --docling-pipeline ocr

# Use vision pipeline
uv run docling-graph convert complex_doc.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --docling-pipeline vision

Remote Conversion (docling-serve)¶

--docling-serve-url URL

Delegates document conversion to a remote docling-serve instance instead of running Docling locally. No local conversion models are loaded; the rest of the pipeline (chunking, extraction, export) is unchanged.

Example:

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --docling-serve-url http://localhost:5001

Also configurable via docling.serve.url in config.yaml or the DOCLING_SERVE_URL environment variable; the API key (if the server requires one) is read from DOCLING_SERVE_API_KEY. See Docling-Serve Integration.

Export Options¶

Export Format¶

--export-format {csv|cypher}

CSV:

For Neo4j import
Separate nodes.csv and edges.csv
Easy to analyze

Cypher:

Direct Neo4j execution
Single .cypher file
Ready to import

Example:

# Export as CSV
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-format csv

# Export as Cypher
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-format cypher

Docling Exports¶

--export-docling-json / --no-docling-json
--export-markdown / --no-markdown
--export-doclang / --no-doclang
--export-per-page / --no-per-page

--export-doclang writes docling/document.dclg — the document as DocLang (content + geometry). See Export Configuration.

Example:

# Export all Docling outputs
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-docling-json \
    --export-markdown \
    --export-doclang \
    --export-per-page

# Minimal exports
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --no-docling-json \
    --no-markdown \
    --no-doclang \
    --no-per-page

LLM Input Format¶

--llm-format {markdown|doclang|doclang-geo|auto}

Controls how the document text is serialized for the LLM during extraction (default markdown). DocLang formats preserve structure and (with doclang-geo) page geometry, at a higher token cost — see Document Conversion.

auto pairs the serialization to the resolved extraction contract, per document: direct → doclang-geo (geometry helps a single full-document call recover footers and table matrices), dense → doclang (structure without geometry keeps chunk batches content-dense), raw-text inputs → markdown. The resolution is logged as [AutoContract]. The direct-vs-dense decision itself measures content characters (markup stripped), so changing --llm-format never flips the contract.

Example:

# Send DocLang (structure only) to the LLM; raise the chunk budget to compensate
uv run docling-graph convert invoice.pdf \
    --template "templates.BillingDocument" \
    --llm-format doclang \
    --chunk-max-tokens 768

Graph Options¶

Reverse Edges¶

--reverse-edges

Creates bidirectional relationships in the graph.

Example:

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --reverse-edges

Output Options¶

Output Directory¶

--output-dir PATH

Default: outputs/

Example:

# Custom output directory
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "results/invoice_001"

# Organize by date
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/$(date +%Y-%m-%d)"

Complete Examples¶

📍 Simple Invoice (VLM)¶

uv run docling-graph convert invoice.jpg \
    --template "templates.BillingDocument" \
    --backend vlm \
    --processing-mode one-to-one \
    --output-dir "outputs/invoice"

📍 Rheology Research (Remote LLM)¶

export MISTRAL_API_KEY="your-key"

uv run docling-graph convert research.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --backend llm \
    --inference remote \
    --provider mistral \
    --model mistral-large-latest \
    --processing-mode many-to-one \
    --use-chunking \
    --output-dir "outputs/research"

📍 Debug Mode Enabled¶

# Enable debug mode for troubleshooting
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --debug \
    --output-dir "outputs/debug_run"

# Debug artifacts will be saved to:
# outputs/debug_run/document_pdf_20260206_094500/debug/

📍 Local Processing (Ollama)¶

# Start Ollama server first
ollama serve

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference local \
    --provider ollama \
    --model llama3:8b \
    --processing-mode many-to-one \
    --use-chunking \
    --output-dir "outputs/local"

📍 Cypher Export for Neo4j¶

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference remote \
    --export-format cypher \
    --output-dir "outputs/neo4j"

# Import to Neo4j
cat outputs/neo4j/graph.cypher | cypher-shell

📍 Minimal Processing¶

uv run docling-graph convert small_doc.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference local \
    --no-use-chunking \
    --no-docling-json \
    --no-markdown \
    --output-dir "outputs/minimal"

Batch Processing¶

Process Multiple Files¶

# Bash loop
for pdf in documents/*.pdf; do
    uv run docling-graph convert "$pdf" \
        --template "templates.BillingDocument" \
        --output-dir "outputs/$(basename $pdf .pdf)"
done

Parallel Processing¶

# Using GNU parallel
ls documents/*.pdf | parallel -j 4 \
    uv run docling-graph convert {} \
        --template "templates.BillingDocument" \
        --output-dir "outputs/{/.}"

Batch Script¶

#!/bin/bash
# batch_convert.sh

TEMPLATE="templates.BillingDocument"
INPUT_DIR="documents"
OUTPUT_BASE="outputs"

for file in "$INPUT_DIR"/*.pdf; do
    filename=$(basename "$file" .pdf)
    echo "Processing: $filename"

    uv run docling-graph convert "$file" \
        --template "$TEMPLATE" \
        --output-dir "$OUTPUT_BASE/$filename" \
        --backend llm \
        --inference remote

    echo "Completed: $filename"
done

Configuration Priority¶

Options are resolved in this order (highest to lowest):

Command-line arguments
config.yaml (from init)
Built-in defaults

Example¶

# config.yaml
defaults:
  backend: llm
  inference: local
  processing_mode: many-to-one

# This uses remote inference (CLI overrides config)
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference remote

Output Structure¶

outputs/
├── metadata.json                # Pipeline metadata
├── docling/                     # Docling conversion output
│   ├── document.json            # Docling format
│   └── document.md              # Markdown export
└── docling_graph/               # Graph outputs
    ├── graph.json               # Complete graph (nodes carry __provenance__)
    ├── nodes.csv                # Node data
    ├── edges.csv                # Edge data
    ├── provenance.json          # Grounding ledger (unless --provenance off)
    ├── graph.html               # Interactive visualization
    └── report.md                # Summary report
    └── ...

Error Handling¶

Configuration Errors¶

[red]Configuration Error:[/red] Invalid backend type: 'invalid'

Solution: Use llm or vlm

Extraction Errors¶

[red]Extraction Error:[/red] Template not found: 'templates.Missing'

Solution: Check template path and ensure it's importable

API Errors¶

[red]Pipeline Error:[/red] API key not found for provider: mistral

Solution:

export MISTRAL_API_KEY="your-key"

Troubleshooting¶

🐛 Template Not Found¶

Error:

ModuleNotFoundError: No module named 'templates'

Solution:

# Ensure template is in Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Or use absolute path
uv run docling-graph convert document.pdf \
    --template "my_project.templates.BillingDocument"

🐛 Out of Memory¶

Error:

CUDA out of memory

Solution:

# Enable chunking
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --use-chunking

# Or use smaller model
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --model "ibm-granite/granite-4.0-1b"

🐛 Slow Processing¶

Solution:

# Disable chunking for small documents to speed up
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --no-use-chunking

Best Practices¶

👍 Use Configuration Files¶

# ✅ Good - Reusable configuration
uv run docling-graph init
uv run docling-graph convert document.pdf -t "templates.BillingDocument"

# ❌ Avoid - Repeating options
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm --inference remote --provider mistral

👍 Organize Outputs¶

# ✅ Good - Organized by document
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/invoice_001"

# ❌ Avoid - Overwriting outputs
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument"

👍 Use Appropriate Backend¶

# ✅ Good - VLM for forms
uv run docling-graph convert id_card.jpg \
    --template "templates.IDCard" \
    --backend vlm

# ✅ Good - LLM for documents
uv run docling-graph convert research.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --backend llm

Next Steps¶

inspect Command - Visualize results
CLI Recipes - Common patterns
Examples - Real-world examples