inspect Command¶

Overview¶

The inspect command creates interactive HTML visualizations of your knowledge graphs that open in your browser.

Key Features: - Interactive node/edge exploration - CSV and JSON import - Self-contained HTML output - Automatic browser opening - Shareable visualizations

Basic Usage¶

uv run docling-graph inspect PATH [OPTIONS]

Required Arguments¶

Argument	Description
`PATH`	Path to graph data (directory for CSV, file for JSON)

Example¶

# Visualize CSV output
uv run docling-graph inspect outputs/

# Visualize JSON output
uv run docling-graph inspect outputs/graph.json --format json

Input Formats¶

CSV Format (Default)¶

For CSV format, provide a directory containing: - nodes.csv - Node data - edges.csv - Edge data

uv run docling-graph inspect outputs/

Directory structure:

outputs/
├── nodes.csv
├── edges.csv
└── ... (other files)

JSON Format¶

For JSON format, provide a file path to the graph JSON:

uv run docling-graph inspect outputs/graph.json --format json

Options¶

Input Format¶

--format {csv|json}

Default: csv

Example:

# CSV format (default)
uv run docling-graph inspect outputs/

# JSON format
uv run docling-graph inspect outputs/graph.json --format json

Output File¶

--output PATH

Specify where to save the HTML visualization.

Default: Temporary file

Example:

# Save to specific location
uv run docling-graph inspect outputs/ \
    --output visualization.html

# Save with timestamp
uv run docling-graph inspect outputs/ \
    --output "viz_$(date +%Y%m%d_%H%M%S).html"

Browser Control¶

--open / --no-open

Control whether to automatically open the visualization in your browser.

Default: --open (opens automatically)

Example:

# Open automatically (default)
uv run docling-graph inspect outputs/

# Don't open browser
uv run docling-graph inspect outputs/ \
    --no-open \
    --output visualization.html

Complete Examples¶

📍 Quick Visualization¶

# Convert document
uv run docling-graph convert invoice.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/invoice"

# Visualize immediately
uv run docling-graph inspect outputs/invoice/

📍 Save for Later¶

# Create visualization without opening
uv run docling-graph inspect outputs/ \
    --output graph_viz.html \
    --no-open

# Open later
open graph_viz.html  # macOS
xdg-open graph_viz.html  # Linux
start graph_viz.html  # Windows

📍 JSON Format¶

# Visualize JSON graph
uv run docling-graph inspect outputs/graph.json \
    --format json \
    --output interactive_graph.html

📍 Batch Visualization¶

# Create visualizations for multiple outputs
for dir in outputs/*/; do
    name=$(basename "$dir")
    uv run docling-graph inspect "$dir" \
        --output "visualizations/${name}.html" \
        --no-open
done

echo "Created visualizations in visualizations/"

# Create self-contained HTML
uv run docling-graph inspect outputs/ \
    --output shared_graph.html \
    --no-open

# Share the HTML file
# The file contains all data and can be opened anywhere

Interactive Features¶

Node Exploration¶

Click on a node to: - View node properties - Highlight connected edges - See relationship details - Filter by node type

Edge Exploration¶

Click on an edge to: - View relationship type - See source and target nodes - View edge properties

Controls: - Zoom: Mouse wheel or pinch - Pan: Click and drag - Reset: Double-click background - Search: Use search box to find nodes

Layout Options¶

Available layouts: - Force-directed: Automatic positioning - Hierarchical: Top-down structure - Circular: Nodes in a circle - Grid: Regular grid layout

Output Structure¶

HTML File Contents¶

The generated HTML file is self-contained and includes: - Complete graph data - Interactive visualization library - Styling and controls - No external dependencies

File size: Typically 100KB - 2MB depending on graph size

# Create visualization
uv run docling-graph inspect outputs/ \
    --output graph.html \
    --no-open

# Share via email, cloud storage, or web hosting
# Recipients can open directly in any modern browser

Validation¶

CSV Validation¶

The command validates that required files exist:

uv run docling-graph inspect outputs/

Checks: - Directory exists - nodes.csv exists - edges.csv exists

Error if missing:

[bold red]Error:[/bold red] nodes.csv not found in outputs/

JSON Validation¶

uv run docling-graph inspect graph.json --format json

Checks: - File exists - File has .json extension - Valid JSON format

Error if invalid:

[bold red]Error:[/bold red] For JSON format, path must be a .json file

Troubleshooting¶

🐛 Files Not Found¶

Error:

[bold red]Error:[/bold red] nodes.csv not found in outputs/

Solution:

# Check directory contents
ls outputs/

# Ensure convert completed successfully
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs"

# Then inspect
uv run docling-graph inspect outputs/

🐛 Browser Doesn't Open¶

Error:

Browser failed to open

Solution:

# Save to file and open manually
uv run docling-graph inspect outputs/ \
    --output graph.html \
    --no-open

# Open manually
open graph.html  # macOS
xdg-open graph.html  # Linux
start graph.html  # Windows

🐛 Large Graph Performance¶

Visualization is slow with large graphs

Solution:

# Filter graph before visualization
# Use Python to create smaller subset

# Or use Neo4j for large graphs
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-format cypher

# Import to Neo4j and use Neo4j Browser

Integration Workflows¶

Workflow 1: Development Cycle¶

# 1. Convert document
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "test_output"

# 2. Inspect results
uv run docling-graph inspect test_output/

# 3. Iterate on template
# Edit templates/billing_document.py

# 4. Re-convert and inspect
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "test_output"

uv run docling-graph inspect test_output/

Workflow 2: Batch Processing with Visualization¶

#!/bin/bash
# process_and_visualize.sh

INPUT_DIR="documents"
OUTPUT_BASE="outputs"
VIZ_DIR="visualizations"

mkdir -p "$VIZ_DIR"

for pdf in "$INPUT_DIR"/*.pdf; do
    name=$(basename "$pdf" .pdf)
    output_dir="$OUTPUT_BASE/$name"

    echo "Processing: $name"

    # Convert
    uv run docling-graph convert "$pdf" \
        --template "templates.BillingDocument" \
        --output-dir "$output_dir"

    # Visualize
    uv run docling-graph inspect "$output_dir" \
        --output "$VIZ_DIR/${name}.html" \
        --no-open

    echo "Completed: $name"
done

echo "All visualizations saved to $VIZ_DIR/"

Workflow 3: Quality Assurance¶

# Convert with verbose logging
uv run docling-graph --verbose convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "qa_output"

# Inspect graph structure
uv run docling-graph inspect qa_output/

# Check statistics
cat qa_output/graph_stats.json

# Review markdown report
cat qa_output/markdown_report.md

Comparison with Other Tools¶

inspect vs Neo4j Browser¶

Feature	inspect	Neo4j Browser
Setup	No setup required	Requires Neo4j installation
Sharing	Self-contained HTML	Requires Neo4j access
Performance	Good for small/medium graphs	Excellent for large graphs
Querying	Basic filtering	Full Cypher queries
Best for	Quick visualization, sharing	Production, complex queries

When to Use inspect¶

✅ Use inspect for: - Quick visualization during development - Sharing results with non-technical users - Small to medium graphs (<1000 nodes) - No database setup required

❌ Use Neo4j for: - Large graphs (>1000 nodes) - Complex queries - Production deployments - Team collaboration

Best Practices¶

👍 Save Important Visualizations¶

# ✅ Good - Save with descriptive name
uv run docling-graph inspect outputs/ \
    --output "invoice_001_graph.html" \
    --no-open

# ❌ Avoid - Temporary files get lost
uv run docling-graph inspect outputs/

👍 Organize Visualizations¶

# ✅ Good - Organized structure
mkdir -p visualizations/invoices
uv run docling-graph inspect outputs/invoice_001/ \
    --output "visualizations/invoices/invoice_001.html" \
    --no-open

# ❌ Avoid - Cluttered directory
uv run docling-graph inspect outputs/ \
    --output "viz1.html" \
    --no-open

👍 Use for Development¶

# ✅ Good - Quick feedback loop
uv run docling-graph convert test.pdf -t "templates.BillingDocument" -o "test"
uv run docling-graph inspect test/

# ✅ Good - Iterate quickly
# Edit template, re-run, inspect

Next Steps¶

CLI Recipes → - Common CLI patterns
Visualization Guide → - Advanced visualization
Neo4j Integration → - Database visualization

inspect Command¶

Overview¶

Basic Usage¶

Required Arguments¶

Example¶

Input Formats¶

CSV Format (Default)¶

JSON Format¶

Options¶

Input Format¶

Output File¶

Browser Control¶

Complete Examples¶

📍 Quick Visualization¶

📍 Save for Later¶

📍 JSON Format¶

📍 Batch Visualization¶

📍 Share Visualization¶

Interactive Features¶

Node Exploration¶

Edge Exploration¶

Graph Navigation¶

Layout Options¶

Output Structure¶

HTML File Contents¶

Sharing¶

Validation¶

CSV Validation¶

JSON Validation¶

Troubleshooting¶

🐛 Files Not Found¶

🐛 Browser Doesn't Open¶

🐛 Large Graph Performance¶

Integration Workflows¶

Workflow 1: Development Cycle¶

Workflow 2: Batch Processing with Visualization¶

Workflow 3: Quality Assurance¶

Comparison with Other Tools¶

inspect vs Neo4j Browser¶

When to Use inspect¶

Best Practices¶

👍 Save Important Visualizations¶

👍 Organize Visualizations¶

👍 Use for Development¶

Next Steps¶