feat: add progress_callback support for real-time conversion tracking

[echavet]

Summary

Adds a progress_callback mechanism to MarkItDown converters, enabling callers to receive real-time progress updates during document conversion.

Problem Solved

When converting large documents (e.g. a 213-page PDF), convert() blocks for several minutes with no way to report progress to the user. Server-side applications, worker processes, and UIs cannot display meaningful feedback during long conversions.

Design

Two new public types in _base_converter.py:

• ConversionProgress — a frozen @dataclass carrying current, total, unit (page/slide/chapter/sheet), and source (converter class name).
• ProgressCallback — a @runtime_checkable Protocol that any callable matching (ConversionProgress) -> None satisfies (structural subtyping / duck typing).

The callback is passed through the existing **kwargs chain (convert() → _convert() → converter.convert()). Converters that do not support progress simply ignore the kwarg.

Converters Updated

Converter	Unit	Loop
PdfConverter	page	per-page in pdfplumber loop
PptxConverter	slide	per-slide
EpubConverter	chapter	per-spine-item
XlsxConverter	sheet	per-sheet
XlsConverter	sheet	per-sheet

Usage Example

from markitdown import MarkItDown, ConversionProgress

def on_progress(p: ConversionProgress) -> None:
    print(f"[{p.source}] {p.current}/{p.total} {p.unit}s")

md = MarkItDown()
result = md.convert("large_report.pdf", progress_callback=on_progress)
# Output:
# [PdfConverter] 1/213 pages
# [PdfConverter] 2/213 pages
# ...

Backward Compatibility

• ✅ All existing functionality unchanged
• ✅ Callback is optional — omitting it preserves current behavior
• ✅ No new dependencies
• ✅ No changes to existing method signatures
• ✅ graphrag-input and other consumers work without modification

Type of Change

• New feature (non-breaking change)

Testing

• All existing tests pass (no modifications needed)
• Manual verification with PDF, PPTX, and EPUB files
• ConversionProgress dataclass and ProgressCallback Protocol validated at runtime

[echavet]

@microsoft-github-policy-service agree