# docling-serve-client

Python SDK for Docling Serve API v1.14.0

[![Python](https://img.shields.io/badge/python-%3E%3D3.8.1-blue)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/docling-serve-client)](https://pypi.org/project/docling-serve-client/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

## What is Docling Serve?

[Docling Serve](https://github.com/docling-project/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

```bash
pip install docling-serve-client

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

## Quick Start

```python
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](https://www.python-httpx.org/), 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

```bash
# 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
