[PeterStaar-IBM]

Summary

• Add repeatable --ocr-option, --layout-option and --table-structure-option KEY=VALUE to docling convert. Each one fills the options of the engine selected with --ocr-engine, --layout-engine or --table-structure-engine, so plugin engines work with no extra code.

  docling convert --ocr-engine rapidocr --ocr-option model_size=tiny --ocr-option text_score=0.6 doc.pdf

• Values are read as JSON when possible (0.6, false, ["en","de"]), else as strings. Pydantic validates them against the engine's options class.
• Unknown keys fail with the list of valid keys. A key that a dedicated flag also sets (--ocr-lang, --ocr-mode, --table-mode) fails too.
• Add docling options {ocr,layout,table-structure} [ENGINE] to list the keys, types, defaults and descriptions of an engine.
• Deprecate --psm in favor of --ocr-option psm=N.
• Show the available choices as metavars in CLI help.
• Hide RapidOCR INFO logs by default while keeping warnings visible.

The new options are for local convert only. convert-remote does not forward them, because some fields hold paths or commands. docling-tools models download --rapidocr-model-size is unchanged.

[github-actions]

✅ DCO Check Passed

Thanks @PeterStaar-IBM, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

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]

AI triage (advisory)

Checked commit 718e333bc1. The analysis read the diff only. It did not run code from this pull request.

Adds repeatable --ocr-option, --layout-option, and --table-structure-option KEY=VALUE flags to docling convert so plugin engines can be configured without extra code, and adds a docling options {ocr,layout,table-structure} [ENGINE] command that lists an engine's keys, types, and defaults. It also suppresses RapidOCR INFO logs by default and deprecates --psm in favour of --ocr-option psm=N.

CI safety: no concern found. A maintainer must still approve CI.

4 related pull request(s) in the same code

PR	State	Signal	Assessment
#4709	open	changes the same code	related: Both modify the same params dict in rapid_ocr_model.py and add sections to docs/concepts/OCR.md, but PR 4709 adds detect_orientation support while this PR adds Global.log_level log suppression and removes a commented-out line; they solve different problems.
#4888	open	changes the same code	related: Both modify docling/cli/main.py and tests/test_cli.py in nearby areas, but PR 4888 makes the CLI exit with code 1 on conversion failure, which is a different fix from the engine-option flags added here.
#4654	open	changes the same code	related: Both modify docling/cli/main.py, references/cli.md, and docs/concepts/OCR.md, but PR 4654 adds a --replace-broken-text-layer flag for a different OCR feature; no overlapping hunks.
#4496	open	changes the same code	related: Both modify docling/cli/main.py, references/cli.md, and tests/test_cli.py, but PR 4496 adds AcroForm field extraction; no overlapping hunks and a different feature entirely.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[codecov]

Codecov Report

❌ Patch coverage is 88.59649% with 13 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/cli/main.py	84.78%	4 Missing and 3 partials ⚠️
docling/cli/engine_options.py	91.17%	4 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!

[dolfim-ibm]

Let's not add --rapidocr-model-size to convert. Every engine-specific setting would need its own flag, and the prefix repeats what --ocr-engine already selects. Can we remove that part from this PR and merge the rest (metavars, -h, RapidOCR log level)? Model size then goes through a generic option in a follow-up:

docling convert --ocr-engine rapidocr --ocr-option model_size=tiny --ocr-option text_score=0.6 doc.pdf

Proposed spec:

• Options: add repeatable --ocr-option KEY=VALUE, --layout-option KEY=VALUE and --table-structure-option KEY=VALUE. Each one fills the kwargs of the existing factory.create_options(kind=<engine>, **kwargs) call for its stage. Plugin engines work with no extra code.
• Values: split on the first =. Try json.loads(value). If it fails, use the raw string. Pydantic validates the result against the selected engine's options class, so model_size=tiny, text_score=0.6, use_gpu=false and lang=["en","de"] all work.
• Unknown keys: the OCR option models ignore extra fields, so a typo like model_sise=tiny would pass without an error. Check each key against type(options).model_fields and raise BadParameter with the valid keys, for example --ocr-option: unknown key 'model_sise' for engine 'rapidocr'; valid keys: backend, lang, model_size, ....
• Validation errors: convert each ValidationError to BadParameter(param_hint="--ocr-option") and include the key in the message.
• Dedicated flags: keep them only for settings that most engines share (--ocr-mode, --ocr-lang). If both forms set the same field, for example --ocr-lang en with --ocr-option lang=["de"], fail. Keep --psm as a deprecated alias for --ocr-option psm=N.
• Discoverability: --help can't list fields that depend on the engine. Add docling options {ocr,layout,table-structure} <engine>. It prints each field's name, type, default and description from the model. Link to it from the help text of --ocr-option.
• Scope: local convert only. Some fields hold paths or commands (tesseract_cmd, det_model_path, rapidocr_params), so convert-remote and docling-serve must not forward arbitrary keys.

docling-tools models download --rapidocr-model-size stays as it is. That command works on one engine at a time, so the engine prefix is correct there.

[dolfim-ibm]

lgtm