feat: Enable pipeline override and reuse with compatible options

[cau-git]

Summary

This PR adds per-call pipeline option overrides in DocumentConverter and enforces compatibility-based reuse of initialized pipelines. The main scenario this covers is:

• User code initializes a DocumentConverter once with pipeline options for each desired format.
• Subsequent calls to DocumentConverter.convert can provide modified pipeline options within very tight constraints, only to disable a model that was enabled in the initialization (e.g. turn off OCR, turn off table structure etc. in the standard pipeline)
• This avoids expensive, redundant re-initializations of full pipelines just because a particular convert call is requesting to disable a model. Previously it would have required to initialize another DocumentConverter with different options.

What’s Included

• Adds format_options override support to:
  • DocumentConverter.convert(...)
  • DocumentConverter.convert_all(...)
• Adds compatibility checks for override options. Compatibility is only given if:
  • All fields accepting options instances are of the same type as the pre-initialized pipeline
  • All fields carry equal values with the exception of booleando_... flags
  • The boolean do_... flags can only be relaxed (True -> False). Hence, one can override to not use an "enabled" model, but not enable a model that was disabled in the pre-initialized pipeline.
• Applies compatible overrides at execution time without creating a new pipeline instance.
• Extends pipeline option models with compatibility/runtime-toggle payload helpers.
• Updates enrichment/stage execution paths (including threaded PDF pipeline) so runtime do_* overrides are respected safely.
• Adds focused tests for override compatibility behavior in tests/test_options.py.
• Updates converter docstrings to match the enforced compatibility semantics.

Behavior

• Compatible overrides are accepted and applied for the current execution.
• Incompatible overrides fail conversion (raise or return failure depending on raises_on_error).

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[github-actions]

✅ DCO Check Passed

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

[codecov]

Codecov Report

❌ Patch coverage is 90.08264% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/document_converter.py	74.19%	8 Missing ⚠️
docling/pipeline/base_pipeline.py	93.10%	2 Missing ⚠️
docling/datamodel/pipeline_options.py	95.65%	1 Missing ⚠️
docling/pipeline/standard_pdf_pipeline.py	97.36%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[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)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Docling

What are the detailed pipeline options and processing behaviors for PDF, DOCX, PPTX, and XLSX files in the Python SDK?

View Suggested Changes

@@ -8,9 +8,8 @@
     - `generate_page_images`, `generate_picture_images`: Extract page/picture images
     - `force_backend_text`: Force backend text extraction
     - Additional options for OCR engine, layout model, table extraction, etc.
-- **Notes**: Only PDF supports image resolution adjustment. For more details, see [pipeline options code](https://github.com/docling-project/docling/blob/ae4fdbbb09fd377bb271e9b2efe541873eeb2990/docling/datamodel/pipeline_options.py#L891-L1336) and [example](https://app.dosu.dev/documents/9640186d-61e1-4ca1-9d8a-b82b3ee6bff8).
-
----
+- **Pipeline Option Overrides**: The Python API allows you to override pipeline options at conversion time for a given format using the `format_options` argument. Only `do_*` flags (such as `do_ocr`, `do_table_structure`, `do_code_enrichment`, `do_formula_enrichment`, etc.) can be changed, and only from `True` to `False`. All other options must remain identical to those used at pipeline initialization. Attempting to enable a do_* flag or change other fields will result in an error. This enables per-call disabling of enrichment features without reinitializing the pipeline.
+- **Notes**: Only PDF supports image resolution adjustment. For more details, see [pipeline options code](https://github.com/docling-project/docling/blob/ae4fdbbb09fd377bb271e9b2efe541873eeb2990/docling/datamodel/pipeline_options.py#L891-L1336) and [example](https://app.dosu.dev/documents/9640186d-61e1-4ca1-9d8a-b82b3ee6bff8). Refer to the Python SDK documentation for usage of `format_options`.
 
 ### DOCX
 - **Pipeline/Backend**: `SimplePipeline` + `MsWordDocumentBackend`
@@ -52,5 +51,4 @@
 - Only PDF supports image resolution adjustment (`images_scale`).
 - DOCX header/footer export is only available via Python API.
 - PPTX/XLSX support enrichment options and pagination (slide/sheet level).
-
-For further details, refer to the provided code links and examples.
+- **Pipeline Option Overrides**: For all formats, the Python API supports disabling enrichment-related `do_*` flags at conversion time using the `format_options` argument. Only disabling (True → False) is allowed; all other options must remain unchanged. See the PDF section above for details.

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[cau-git]

Not the coolest thing to put here. Ideas for improvements are welcome.

[dolfim-ibm]

Currently the approach was to always list the models, but to set the enabled argument in the __init__. Do we have to change it?