docling-serve-client 1.14.0

A Python SDK for interacting with Docling Serve API using Pydantic models

docling-serve-client

Python SDK for Docling Serve API v1.14.0

What is Docling Serve?

Docling Serve is an open-source REST API by IBM Research that converts PDFs, DOCX, PPTX, HTML, images, and other document formats into structured output — Markdown, JSON, HTML, or plain text. This SDK provides a fully typed Python client with sync and async support, automatic retries, chunking, and async task management.

Installation

pip install docling-serve-client

# With development dependencies
pip install "docling-serve-client[dev]"

Quick Start

from docling_serve_sdk import (
    DoclingClient,
    ConvertDocumentsRequest,
    ConvertDocumentsRequestOptions,
    HttpSourceRequest,
    OutputFormat,
)

with DoclingClient("http://localhost:5001") as client:
    # Health check
    health = client.health_check()
    print(health.status)  # "ok"

    # Convert a URL to Markdown
    request = ConvertDocumentsRequest(
        sources=[HttpSourceRequest(url="https://arxiv.org/pdf/2408.09869")],
        options=ConvertDocumentsRequestOptions(to_formats=[OutputFormat.MD]),
    )
    result = client.convert_source(request)
    print(result.document.md_content)

Features

• Sync and async HTTP — built on httpx, every method has an _async variant
• Fully typed Pydantic v2 models — all request and response types are validated at construction time
• Retry with exponential backoff + jitter — transient 5xx and connection errors are retried automatically
• Async task lifecycle — submit, poll, wait, and retrieve results for long-running conversions
• Hybrid chunking — split documents using HybridChunkerOptions with configurable token limits
• Hierarchical chunking — split documents using HierarchicalChunkerOptions with heading-aware segmentation
• Event hooks — on_request, on_response, on_error callbacks for telemetry and logging
• Request ID tracking — every HTTP request carries a unique X-Request-ID header for distributed tracing
• Context manager support — with and async with for deterministic connection pool lifecycle
• S3 source and target — S3SourceRequest and S3Target with SecretStr credential handling (redacted in logs)
• ZIP and in-body output targets — ZipTarget for archives, InBodyTarget for inline JSON responses
• Forward-compatible responses — response models use extra="allow" to tolerate new server fields
• Strict requests — request models use extra="forbid" to catch typos at construction time
• API key authentication — sent via X-Api-Key header, redacted in repr()

Compatibility

SDK version	Docling Serve API	Python	Dependencies
1.14.0	v1.14.0	>=3.8.1	httpx>=0.24.0, pydantic>=2.0.0

The SDK version tracks the Docling Serve API version. When Docling Serve releases v1.15.0, the SDK will be updated to 1.15.0.

Running Tests

# Unit tests (no server needed)
pytest tests/test_sdk.py -v

# Integration tests (requires Docling Serve on localhost:5001)
pytest tests/test_integration.py -v

License

MIT