docling-project / docling-project/docling
Feat: Add per-page progress callback support to DocumentConverter
- 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
Assessment
This issue has not been assessed yet.