feat!: Public threaded PDF parser and rendering API

[cau-git]

Summary

Redesigns the threaded PDF parser public API to remove C++ internals from user code, unify parse-only and parse-and-render workflows behind one public parser, and add a more Pythonic result iteration model.

Before:

# Required a dummy PdfDocument hack to convert C++ decoders
dummy_doc = PdfDocument.__new__(PdfDocument)
dummy_doc._boundary_type = PdfPageBoundaryType.CROP_BOX

while parser.has_tasks():
    task = parser.get_task()
    page_decoder, timings = task.get()  # C++ object exposed to user code
    seg_page = dummy_doc._to_segmented_page_from_decoder(page_decoder)

After:

for result in parser.iterate_results():
    seg_page = result.get_page()       # lazy, cached
    timings = result.get_timings()     # typed Timings
    image = result.get_image()         # only when render_config is set

Changes

• PageParseResult replaces the old raw threaded result types with a Python-facing result object:
  • 1-indexed page_number
  • lazy, cached get_page()
  • typed get_timings()
  • get_image(...) / has_image
  • page_width / page_height without full page conversion
  • error_message
• DoclingThreadedPdfParser is now the single public threaded entry point:
  • render_config=None means parse-only
  • render_config=RenderConfig(...) means parse-and-render
  • separate public DoclingThreadedPdfRenderer / ThreadedPdfRendererConfig are removed
• ThreadedPdfParserConfig now includes:
  • boundary_type
  • render_config
• segmented_page_from_decoder() is now a public module-level helper; PdfDocument._to_segmented_page_from_decoder() delegates to it
• Threaded document lifecycle and scheduling are now public:
  • load(..., page_numbers=...)
  • page_count(doc_key)
  • scheduled_page_count(doc_key)
  • unload(doc_key)
  • unload_all()
• iterate_results() is added for normal consumption; has_tasks() / get_task() remain for manual control
• C++ number_of_pages() / scheduled page count plumbing is exposed through the threaded parser API
• DoclingThreadedPdfParser.__init__() copies decode_config before mutating page_boundary, so caller-owned config objects are not modified in place
• Rendered image access now supports:
  • default image reuse
  • rerendering at arbitrary scale
  • rerendering at canvas_size
  • Python-side cropbox cropping
• The C++ rerender path releases the GIL during render instruction replay
• Tests and perf scripts were updated to the new API shape

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

✅ DCO Check Passed

Thanks @cau-git, all your commits are properly signed off. 🎉

[PeterStaar-IBM]

lgtm!

[PeterStaar-IBM]

lovely!