perf: let callers pass pre-rendered PDF pages so hi_res renders each page once
What
DocumentLayout.from_file and process_file_with_model accept image_paths: page images the caller already rendered from the PDF. When given, the PDF is not rendered again, and each page keeps its path, so later page operations (such as annotate) read the caller's image instead of re-rendering.
Nothing changes for callers that don't pass it. Pages rendered internally still keep no path, since their temporary directory is deleted on return.
Why
A hi_res request renders every page of the PDF several times: once here for layout inference, then again in unstructured for OCR and once more per extracted image type. Each render is the same work (same dpi, same pages), so the only way to stop paying for it twice is to let the caller hand the pages in.
before: inference render → OCR render → image-extraction render → table-extraction render (4 × pages)
after: one render, shared by all four (1 × pages)
Release
Listed under 1.6.18, which is on main and not yet released. The paired unstructured PR (https://github.com/Unstructured-IO/unstructured/pull/4530) can pin it after 1.6.18 is published.
Validation
- New tests:
image_pathsskips the render and is kept on each page;process_file_with_modelforwards it; internally rendered pages keep no path. The path test fails without the change. - Unit suite: 429 passed. Ruff clean.
- End-to-end measurements (up to 24% faster when extracting images/tables) are in the paired
unstructuredPR.