docling-project / docling-project/docling

Feat: Add per-page progress callback support to DocumentConverter

Open
#3,493 2 comments 0 reactions 1 assignee Claimed by @assinscreedFC View on GitHub
enhancement
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

## Summary

Add support for a `progress_callback` (or similar hook) directly on `DocumentConverter` to expose per-page conversion progress events during document processing.

## Motivation

Currently, the core SDK exposes conversion progress only at the document level. While `docling-jobkit` provides higher-level progress reporting for service workflows, there is no equivalent mechanism in the core `DocumentConverter` API to receive page-by-page progress updates.

This makes it difficult to:

* Build responsive UIs with live progress indicators
* Track long-running conversions
* Emit granular telemetry/logging
* Support cancellation or timeout logic based on conversion state
* Stream partial progress updates in backend services

For large PDFs, users currently have no visibility into which page is being processed or how far the conversion has progressed.

## Current State

Today, conversion is essentially a black box from the perspective of the caller:

```python
converter = DocumentConverter()
result = converter.convert(path)
```

There is no callback/event system for monitoring progress at the page level.

## Proposed API

Example proposal:

```python
def on_progress(event: ConversionProgressEvent):
print(
f"Processing page {event.page_number}/{event.total_pages}"
)

converter = DocumentConverter(
progress_callback=on_progress
)
```

Possible event payload fields:

```python
@dataclass
class ConversionProgressEvent:
document_name: str
page_number: int
total_pages: int
stage: str
```

Potential stages could include:

* `page_started`
* `ocr_started`
* `ocr_completed`
* `page_completed`
* `document_completed`

## Benefits

* Enables real-time progress bars
* Improves observability/debugging
* Allows tighter integration into async processing systems
* Aligns the core SDK with capabilities already conceptually present in `docling-jobkit`
* Makes the SDK easier to integrate into production services and desktop/web applications

## Additional Notes

A lightweight callback-based design would likely be sufficient and would avoid introducing heavy async/event infrastructure into the core API.

Happy to contribute or help test if this direction makes sense.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.