Hybrid mode drops text docling labels as page_header/page_footer; --include-header-footer does not restore it

[gsnunes]

Bug

In hybrid mode (--hybrid docling-fast), any text the docling backend classifies as a page header or footer (content_layer: furniture) is silently missing from the final output, even though the backend extracted it. Passing --include-header-footer makes no difference for these items — the output is byte-identical with and without the flag.

On cover/title pages this loses real content: layout models routinely classify the authors line, document number, and date in the margin zones as page_header/page_footer even though they are unique, meaningful text. The native Java pipeline extracts the same text fine.

Steps to reproduce

1. Test file: page 1 (cover) of a public European Parliament study — a digital PDF with a clean text layer:
   ECTI_STU(2025)778579_EN-page1.pdf

2. Baseline, native pipeline — all cover text present:

   opendataloader-pdf cover.pdf -f json --pages 1
   

   The JSON contains paragraphs STUDY, Requested by the ENVI committee, Policy Department for Transformation, Innovation and Health Directorate-General for Economy, Transformation and Industry Authors: Lorenz Moosmann et al. PE 778.579 – November 2025, and EN.

3. Hybrid — those four items vanish:

   opendataloader-pdf-hybrid --port 5002 --force-ocr --enrich-picture-description
   opendataloader-pdf cover.pdf -f json --pages 1 --hybrid docling-fast --hybrid-mode full
   

   Only the body items survive (The COP30 Climate Change Conference, November 2025, Belém, Brazil, the images, plus OCR text from the logo). Same result with --hybrid-mode auto, since triage routes this image-heavy page to the backend.

4. Adding --include-header-footer to the hybrid run changes nothing — output is byte-identical to step 3.

5. The backend did extract the missing text. POSTing the same PDF directly to the server (POST /v1/convert/file) returns a DoclingDocument containing:

   label=page_header  content_layer=furniture  text='STUDY'
   label=page_header  content_layer=furniture  text='Requested by the ENVI committee'
   label=page_footer  content_layer=furniture  text='Policy Department for Transformation, Innovation and Health …'
   label=page_footer  content_layer=furniture  text='EN'
   

   So the items are dropped in the client-side merge of the backend response, not by OCR/layout.

Expected behavior

Hybrid results should honor --include-header-footer: docling furniture items mapped into the output when the flag is set, matching the native pipeline's flag semantics (#523). Failing that, the docs should state that hybrid mode discards docling page headers/footers unconditionally.

Version

opendataloader-pdf 2.4.7 (PyPI, [hybrid] extra), docling 2.108.0, docling-core 2.85.0, Python 3.12.13. Client and server in Docker (Debian 13 base), server on CUDA. Host: Linux (WSL2).

Java version

openjdk version "21.0.11" 2026-04-21
OpenJDK Runtime Environment (build 21.0.11+10-1-deb13u2-Debian)
OpenJDK 64-Bit Server VM (build 21.0.11+10-1-deb13u2-Debian, mixed mode, sharing)