--use-struct-tree silently disables --hybrid for tagged PDFs: backend never called, no warning, precedence undocumented

[namest504]

Bug

When --use-struct-tree and --hybrid <backend> are combined on a document that has a structure tree, the struct-tree path wins and the hybrid backend is never called — with no warning and no mention of the precedence in --help for either option.

DocumentProcessor.extractContents checks isUseStructTree() before isHybridEnabled():

if (StaticLayoutContainers.isUseStructTree()) {
    contents = TaggedDocumentProcessor.processDocument(inputPdfName, config, pagesToProcess);
} else if (config.isHybridEnabled()) {
    contents = HybridDocumentProcessor.processDocument(inputPdfName, config, pagesToProcess);
}

Preferring an explicitly requested struct tree may well be the intended precedence — the problem is that it is silent, and only in this direction. The opposite case is already handled well: for a document without a structure tree, preprocessing logs "The document has no structure tree. The 'use-struct-tree' option will be ignored." and falls through to the hybrid path. The tagged case has no symmetric warning, so the user believes the backend processed the document when it did not.

Real-world impact: in #584 the reporter passed both flags while comparing hybrid backends (four different server configurations) and concluded the backend choice made no difference — the backends were in fact never invoked.

Steps to reproduce

Controlled A/B on the same tagged PDF, same jar, same running server (opendataloader-pdf-hybrid --port 5002):

# A: both flags — exit 0, output produced, server log shows ZERO POST /v1/convert/file
java -jar opendataloader-pdf-cli.jar --hybrid docling-fast --hybrid-mode full \
    --use-struct-tree -f markdown -o out-a tagged.pdf

# B: drop --use-struct-tree — server log shows one POST /v1/convert/file
java -jar opendataloader-pdf-cli.jar --hybrid docling-fast --hybrid-mode full \
    -f markdown -o out-b tagged.pdf

Run A's client output contains no warning of any kind.

Expected behavior

Either of the following (or both):

1. Log a warning when the struct tree suppresses the hybrid backend, symmetric to the existing no-struct-tree warning.
2. Document the precedence in the --use-struct-tree and --hybrid help texts.

Rejecting the combination outright would also work but may break existing scripts, so a warning seems the safer default.

Version

main @ 1b4f0c4

Java version

openjdk version "21.0.10" 2026-01-20 LTS
OpenJDK Runtime Environment Microsoft-13106404 (build 21.0.10+7-LTS)
OpenJDK 64-Bit Server VM Microsoft-13106404 (build 21.0.10+7-LTS, mixed mode, sharing)

[hyunhee-jo]

Thanks for the report — the precise root-cause and the controlled A/B repro made this straightforward to fix.

Both requested behaviors are now shipped in #638 (merged).

1. "it is silent … the tagged case has no symmetric warning" → warning added
When --use-struct-tree and --hybrid are both set on a document that has a structure tree, opendataloader-pdf now logs a warning that the structure tree takes precedence and the hybrid backend was not called — symmetric to the existing "no structure tree" warning. Run A of your A/B repro now emits this instead of producing silent output.

2. "no mention of the precedence in --help for either option" → documented
The precedence is now stated in both the --use-struct-tree and --hybrid help texts (and regenerated for the Python/Node wrappers), in the README (Hybrid Mode + Tagged PDF sections), and on the hybrid-mode docs page.

As you anticipated, the precedence itself is intended and unchanged: a well-tagged PDF already carries reading order and structure, so pairing it with --hybrid is redundant — drop --use-struct-tree when you want the backend. This also clears up the confound you flagged in #584 (backends looking identical because they were never invoked).