Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

feat(mineru): observability for embedded image loss in chunk stream (#16978) (#18761)

Taranum Wasuccfb61d7de98
diff --git a/deepdoc/parser/mineru_parser.py b/deepdoc/parser/mineru_parser.py
index b77212eef3..2b0d799dc6 100644
--- a/deepdoc/parser/mineru_parser.py
+++ b/deepdoc/parser/mineru_parser.py
@@ -152,6 +152,22 @@ class MinerUParser(RAGFlowPdfParser):
self.page_from = 0
self.page_to = MAXIMUM_PAGE_NUMBER
self.logger = logging.getLogger(self.__class__.__name__)
+ # Initialize the coverage stamp so the attribute exists from
+ # construction regardless of whether parse_pdf has run yet.
+ # ``vlm_configured`` is pre-seeded with ``False``; parse_pdf
+ # overwrites it with the actual vision-model status once it has
+ # the constructor wiring available. Pre-seeding means any
+ # caller that reads ``last_image_coverage[\"vlm_configured\"]``
+ # after _transfer_to_sections (but before parse_pdf fills it in)
+ # doesn't KeyError.
+ self.last_image_coverage: dict = {
+ "images_detected": 0,
+ "images_chunked": 0,
+ "images_described": 0,
+ "images_dropped_no_text": 0,
+ "images_unreadable_resource": 0,
+ "vlm_configured": False,
+ }
@staticmethod
def _is_zipinfo_symlink(member: zipfile.ZipInfo) -> bool:
@@ -855,8 +871,30 @@ class MinerUParser(RAGFlowPdfParser):
def _transfer_to_sections(self, outputs: list[dict[str, Any]], parse_method: str = None, table_enable: bool = False):
sections = []
parse_method = (parse_method or "raw").lower()
+ # Track image coverage so silent loss of embedded PDF/DOCX images is
+ # queryable at the serialization boundary (issue #16978). When an
+ # IMAGE block yields nothing — no caption, no footnote, no VLM
+ # description — the image body is dropped from the chunk stream, so
+ # we surface that gap explicitly instead of letting it disappear.
+ image_coverage = {
+ "images_detected": 0,
+ "images_chunked": 0,
+ "images_dropped_no_text": 0,
+ "images_described": 0,
+ "images_unreadable_resource": 0,
+ # Pre-seeded so callers can read the key after this method
+ # returns without going through parse_pdf first. parse_pdf
+ # overwrites it with the real vision_model status.
+ "vlm_configured": False,
+ }
for output in outputs:
output_type = output.get("type")
+ # Count every visual block we see (IMAGE and CHART — MinerU emits
+ # both as visual content) so the image_coverage stamp reports
+ # "detected" symmetrically with "chunked" / "described" (which
+ # both already include CHART via _transfer_to_tables).
+ if output_type in {MinerUContentType.IMAGE, MinerUContentType.CHART}:
+ image_coverage["images_detected"] += 1
# These chunkers consume tables and images separately, so exclude
# media from their text sections. Raw consumers keep legacy sections.
# Charts are routed the same way as images: MinerU emits them as
@@ -879,11 +917,19 @@ class MinerUParser(RAGFlowPdfParser):
# the chunk so it becomes searchable / retrievable.
vlm_description = (output.get("vlm_description") or "").strip()
if vlm_description:
+ image_coverage["images_described"] += 1
section = (section.strip("\n") + "\n" + vlm_description).strip("\n") if section.strip() else vlm_description
+ # Strip any residual newlines so the empty-after-strip case
+ # ("\n" from empty caption+footnote joined by "\n") is
+ # correctly counted as dropped at the boundary check below
+ # (issue #16978).
+ if not section.strip():
+ section = ""
case MinerUContentType.CHART:
section = "".join(output.get("chart_caption", [])) + "\n" + "".join(output.get("chart_footnote", []))
vlm_description = (output.get("vlm_description") or "").strip()
if vlm_description:
+ image_coverage["images_described"] += 1
section = (section.strip("\n") + "\n" + vlm_description).strip("\n") if section.strip() else vlm_description
case MinerUContentType.EQUATION:
section = output.get("text", "")
@@ -912,15 +958,40 @@ class MinerUParser(RAGFlowPdfParser):
if output_type == MinerUContentType.TABLE and not table_enable:
section = self._sanitize_section_text(section)
if not section:
- self.logger.debug("[MinerU] Skip section after sanitization: type=%s", output.get("type"))
+ if output.get("type") in {MinerUContentType.IMAGE, MinerUContentType.CHART}:
+ image_coverage["images_dropped_no_text"] += 1
+ # DEBUG (not WARNING) because PDFs with many decorative
+ # images would flood the log; the parse_pdf summary
+ # already reports the aggregate dropped_no_text count.
+ self.logger.debug(
+ "[MinerU] Dropped embedded %s at page_idx=%s with no caption, footnote, or VLM description "
+ "(img_path=%s). Configure an IMAGE2TEXT vision model to make embedded visuals retrievable.",
+ "chart" if output.get("type") == MinerUContentType.CHART else "image",
+ output.get("page_idx"),
+ output.get("img_path"),
+ )
+ else:
+ self.logger.debug("[MinerU] Skip section after sanitization: type=%s", output.get("type"))
continue
+ # Mirror the same IMAGE/CHART scope as images_detected at the
+ # top of this loop and as images_chunked in
+ # _transfer_to_tables: a CHART block whose caption/footnote/
+ # vlm_description was emitted into a raw-mode text section is
+ # just as \"chunked\" as a caption-only IMAGE block — not
+ # silently dropped.
+ if output.get("type") in {MinerUContentType.IMAGE, MinerUContentType.CHART}:
+ image_coverage["images_chunked"] += 1
+
if section and parse_method in {"manual", "pipeline"}:
sections.append((section, output["type"], self._line_tag(output)))
elif section and parse_method == "paper":
sections.append((section + self._line_tag(output), output["type"]))
else:
sections.append((section, self._line_tag(output)))
+ # Stash on the instance so callers (and parse_pdf) can inspect the
+ # coverage stamp for the most recent parse.
+ self.last_image_coverage = image_coverage
return sections
def _transfer_to_tables(self, outputs: list[dict[str, Any]], table_enable: bool = True):
@@ -960,6 +1031,12 @@ class MinerUParser(RAGFlowPdfParser):
vlm_description = (output.get("vlm_description") or "").strip()
if vlm_description:
texts.append(vlm_description)
+ # The text payload was non-empty if any of caption / footnote /
+ # vlm_description contributed a non-whitespace string. Use this
+ # to disambiguate "text was there but binary was unreadable"
+ # (images_unreadable_resource) from "text was empty" (text
+ # never made it into the chunk stream — images_dropped_no_text).
+ has_meaningful_text = any(t.strip() for t in texts)
image = None
image_path = output.get("img_path")
@@ -969,11 +1046,34 @@ class MinerUParser(RAGFlowPdfParser):
source.load()
image = source.copy()
except Exception as e:
- self.logger.warning(f"[MinerU] Failed to load image '{image_path}': {e}")
+ self.logger.debug(f"[MinerU] Failed to load image '{image_path}': {e}")
if image is None:
- self.logger.warning("[MinerU] Skip image without a readable resource: %s", image_path)
+ self.logger.debug("[MinerU] Skip image without a readable resource: %s", image_path)
+ # Image.open() couldn't read the resource. Route the
+ # observation to whichever counter matches the underlying
+ # failure mode:
+ # - has_meaningful_text → binary was unreadable; route to
+ # images_unreadable_resource.
+ # - text was empty → the image never made it into the
+ # chunk stream at all; route to
+ # images_dropped_no_text.
+ # The IMAGE block was detected (in _transfer_to_sections)
+ # but never produced an image chunk, so we do NOT count
+ # it as chunked/described here.
+ if has_meaningful_text:
+ self.last_image_coverage["images_unreadable_resource"] += 1
+ else:
+ self.last_image_coverage["images_dropped_no_text"] += 1
continue
+ # Count chunked/described only on confirmed emit (image actually
+ # reached the tables list). This avoids the brittle
+ # increment-then-decrement pattern that depends on every branch
+ # taking the right counter.
+ self.last_image_coverage["images_chunked"] += 1
+ if vlm_description:
+ self.last_image_coverage["images_described"] += 1
+
tables.append(((image, texts or [""]), positions))
return tables
@@ -1107,6 +1207,23 @@ class MinerUParser(RAGFlowPdfParser):
sections = self._transfer_to_sections(outputs, parse_method, enable_table)
tables = self._transfer_to_tables(outputs, enable_table) if (parse_method or "raw").lower() in {"naive", "manual", "paper"} else []
+ # Emit an image_coverage stamp so silent loss of embedded PDF/DOCX
+ # images is visible at the parser boundary (issue #16978). The
+ # vlm_configured flag tells operators whether downstream chunks
+ # could have been enriched by a vision model at all. The
+ # coverage dict is initialized in __init__ so this access is
+ # unconditional — see issue #16978.
+ coverage = self.last_image_coverage
+ coverage["vlm_configured"] = vision_model is not None
+ self.logger.info(
+ "[MinerU] image_coverage final detected=%s chunked=%s described=%s dropped_no_text=%s unreadable=%s vlm_configured=%s",
+ coverage["images_detected"],
+ coverage["images_chunked"],
+ coverage["images_described"],
+ coverage["images_dropped_no_text"],
+ coverage["images_unreadable_resource"],
+ coverage["vlm_configured"],
+ )
return sections, tables
finally:
if temp_pdf and temp_pdf.exists():
diff --git a/test/unit_test/deepdoc/parser/test_mineru_parser.py b/test/unit_test/deepdoc/parser/test_mineru_parser.py
index 5a2d9dddd9..f8ed12784a 100644
--- a/test/unit_test/deepdoc/parser/test_mineru_parser.py
+++ b/test/unit_test/deepdoc/parser/test_mineru_parser.py
@@ -205,6 +205,103 @@ def test_sanitize_section_text_removes_escaped_html_tags(monkeypatch):
assert "</td>" not in sanitized
+def test_parse_pdf_emits_image_coverage_final_log_with_vlm_configured_flag(monkeypatch, tmp_path, caplog):
+ """Regression for issue #16978: parse_pdf must
+ emit the final ``[MinerU] image_coverage final ... vlm_configured=...``
+ log line so operators can see the image-coverage stamp at the parser
+ boundary, including whether a vision model was configured."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ pdf_path = tmp_path / "document.pdf"
+ pdf_path.write_bytes(b"%PDF-1.4 fake")
+ output_dir = tmp_path / "output"
+ # Three images: one captioned, one dropped, one VLM-described.
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Exhibit A"],
+ "image_footnote": [],
+ "img_path": "/tmp/a.jpg",
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/b.jpg",
+ "page_idx": 1,
+ "bbox": (0, 0, 10, 10),
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/c.jpg",
+ "page_idx": 2,
+ "bbox": (0, 0, 10, 10),
+ "vlm_description": "VLM description for image C.",
+ },
+ ]
+
+ monkeypatch.setattr(module, "extract_pdf_outlines", Mock(return_value=[]))
+ monkeypatch.setattr(parser, "__images__", Mock())
+ monkeypatch.setattr(parser, "_run_mineru", Mock(return_value=output_dir))
+ monkeypatch.setattr(parser, "_read_output", Mock(return_value=outputs))
+ monkeypatch.setattr(parser, "_enhance_images_with_vlm", Mock())
+ monkeypatch.setattr(parser, "_transfer_to_tables", Mock(return_value=[]))
+ # Do NOT mock _transfer_to_sections — the real method must run so it
+ # populates parser.last_image_coverage with the actual detected/chunked/
+ # described/dropped counts before the summary log line is emitted.
+
+ with caplog.at_level(logging.INFO, logger=parser.logger.name):
+ parser.parse_pdf(
+ filepath=pdf_path,
+ binary=None,
+ output_dir=str(output_dir),
+ delete_output=False,
+ vision_model=object(), # a configured vision model
+ )
+
+ # The summary log line must include the vlm_configured flag and
+ # reflect the actual coverage the real _transfer_to_sections
+ # accumulated.
+ assert "image_coverage final" in caplog.text
+ assert "vlm_configured=True" in caplog.text
+ assert "detected=3" in caplog.text
+ assert "described=1" in caplog.text
+
+
+def test_parse_pdf_image_coverage_final_log_reflects_no_vision_model(monkeypatch, tmp_path, caplog):
+ """When parse_pdf is called without a vision_model kwarg, the final
+ log must reflect vlm_configured=False so operators know downstream
+ chunks could NOT have been VLM-enriched."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ pdf_path = tmp_path / "document.pdf"
+ pdf_path.write_bytes(b"%PDF-1.4 fake")
+ output_dir = tmp_path / "output"
+
+ monkeypatch.setattr(module, "extract_pdf_outlines", Mock(return_value=[]))
+ monkeypatch.setattr(parser, "__images__", Mock())
+ monkeypatch.setattr(parser, "_run_mineru", Mock(return_value=output_dir))
+ monkeypatch.setattr(parser, "_read_output", Mock(return_value=[]))
+ monkeypatch.setattr(parser, "_enhance_images_with_vlm", Mock())
+ monkeypatch.setattr(parser, "_transfer_to_tables", Mock(return_value=[]))
+
+ with caplog.at_level(logging.INFO, logger=parser.logger.name):
+ parser.parse_pdf(
+ filepath=pdf_path,
+ binary=None,
+ output_dir=str(output_dir),
+ delete_output=False,
+ # no vision_model kwarg
+ )
+
+ assert "image_coverage final" in caplog.text
+ assert "vlm_configured=False" in caplog.text
+
+
def test_transfer_to_sections_logs_sections_dropped_after_sanitization(monkeypatch, caplog):
module = _load_mineru_parser(monkeypatch)
parser = module.MinerUParser()
@@ -998,27 +1095,597 @@ def test_read_output_keeps_original_tag_when_middle_json_has_single_table_positi
]
-def test_mineru_backend_matches_public_api(monkeypatch):
+def test_transfer_to_sections_tracks_image_coverage_for_captioned_image(monkeypatch, caplog):
+ """An IMAGE block with a caption should count as detected and chunked, but
+ not as described (no VLM). The coverage dict should be visible on the
+ parser instance so callers can inspect silent loss (issue #16978)."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Exhibit A: signature page"],
+ "image_footnote": [],
+ "img_path": "/tmp/example.jpg",
+ "page_idx": 0,
+ "bbox": (10, 10, 100, 100),
+ }
+ ]
+
+ with caplog.at_level(logging.INFO, logger=parser.logger.name):
+ sections = parser._transfer_to_sections(outputs, parse_method="raw")
+
+ assert len(sections) == 1
+ # The upstream section construction joins caption + "\n" + footnote, so a
+ # captioned image with no footnote yields a trailing newline; the
+ # substantive text must still be retrievable.
+ assert "Exhibit A: signature page" in sections[0][0]
+ coverage = parser.last_image_coverage
+ assert coverage == {
+ "images_detected": 1,
+ "images_chunked": 1,
+ "images_dropped_no_text": 0,
+ "images_described": 0,
+ "images_unreadable_resource": 0,
+ "vlm_configured": False,
+ }
+ # The intermediate INFO log that used to fire from
+ # _transfer_to_sections has been removed.
+ # The authoritative coverage is now emitted by parse_pdf only,
+ # after both transfer paths have run. The per-method counter
+ # assertions still cover that final path below.
+ assert "image_coverage detected=1 chunked=1 described=0 dropped_no_text=0 unreadable=0" not in caplog.text
+
+
+def test_transfer_to_sections_warns_when_embedded_image_has_no_text(monkeypatch, caplog):
+ """When an embedded PDF image has no caption, no footnote, and no VLM
+ description, it must not silently disappear from the chunk stream —
+ the loss must be visible in logs (DEBUG level, since a PDF can have
+ many decorative images) and in the coverage stamp.
+ """
module = _load_mineru_parser(monkeypatch)
- assert {b.value for b in module.MinerUBackend} == {
- "pipeline",
- "vlm-engine",
- "hybrid-engine",
- "vlm-http-client",
- "hybrid-http-client",
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/silent_drop.jpg",
+ "page_idx": 2,
+ "bbox": (0, 0, 50, 50),
+ }
+ ]
+
+ with caplog.at_level(logging.DEBUG, logger=parser.logger.name):
+ sections = parser._transfer_to_sections(outputs, parse_method="raw")
+
+ assert sections == []
+ coverage = parser.last_image_coverage
+ assert coverage == {
+ "images_detected": 1,
+ "images_chunked": 0,
+ "images_dropped_no_text": 1,
+ "images_described": 0,
+ "images_unreadable_resource": 0,
+ "vlm_configured": False,
}
+ assert "Dropped embedded image" in caplog.text
+ assert "page_idx=2" in caplog.text
+ assert "Configure an IMAGE2TEXT vision model" in caplog.text
-def test_check_installation_requires_server_url_for_hybrid_http_client(monkeypatch):
+def test_transfer_to_sections_counts_vlm_description(monkeypatch):
+ """An IMAGE block enriched by _enhance_images_with_vlm must be counted
+ as described so operators can tell the gap between detected and
+ described."""
module = _load_mineru_parser(monkeypatch)
- parser = module.MinerUParser(mineru_api="http://mineru.local")
- monkeypatch.setattr(
- module.MinerUParser,
- "_is_http_endpoint_valid",
- staticmethod(lambda url, timeout=5: True),
- )
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/described.jpg",
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ "vlm_description": "A scanned signature in cursive.",
+ }
+ ]
+
+ sections = parser._transfer_to_sections(outputs, parse_method="raw")
+
+ assert len(sections) == 1
+ assert "A scanned signature in cursive." in sections[0][0]
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1
+ assert coverage["images_chunked"] == 1
+ assert coverage["images_described"] == 1
+ assert coverage["images_dropped_no_text"] == 0
+ assert coverage["images_unreadable_resource"] == 0
+
+
+def test_transfer_to_sections_mixed_image_lifecycle(monkeypatch, caplog):
+ """Mixed batch: one captioned, one described, one dropped. The coverage
+ stamp must reflect the truth so the regression fixture can assert on
+ the loss invariant (images_detected >= images_chunked)."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Caption 1"],
+ "image_footnote": [],
+ "img_path": "/tmp/c1.jpg",
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/d1.jpg",
+ "page_idx": 1,
+ "bbox": (0, 0, 10, 10),
+ "vlm_description": "Described by VLM.",
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/x1.jpg",
+ "page_idx": 2,
+ "bbox": (0, 0, 10, 10),
+ },
+ {
+ "type": module.MinerUContentType.TEXT,
+ "text": "Body text between images.",
+ "page_idx": 2,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ with caplog.at_level(logging.DEBUG, logger=parser.logger.name):
+ sections = parser._transfer_to_sections(outputs, parse_method="raw")
+
+ assert len(sections) == 3 # captioned + described + text (the dropped image yields no section)
+ coverage = parser.last_image_coverage
+ assert coverage == {
+ "images_detected": 3,
+ "images_chunked": 2,
+ "images_dropped_no_text": 1,
+ "images_described": 1,
+ "images_unreadable_resource": 0,
+ "vlm_configured": False,
+ }
+ # The intermediate INFO log was removed; the authoritative coverage
+ # summary now lives in parse_pdf. The per-image Dropped warning
+ # still fires from _transfer_to_sections.
+ assert "image_coverage detected=3" not in caplog.text
+ assert "Dropped embedded image" in caplog.text
+
+
+# --------------------------------------------------------------------------- #
+# App-media modes (issue #16978): naive/manual/paper coverage invariants
+# --------------------------------------------------------------------------- #
+#
+# Naive/manual/paper route IMAGE blocks through _transfer_to_tables and
+# skip them in _transfer_to_sections. The coverage stamp must still
+# report every IMAGE block the parser saw as `images_detected` so
+# operators can spot the gap between detection and chunking.
- ok, reason = parser.check_installation("hybrid-http-client", server_url=None)
- assert ok is False
- assert "MINERU_SERVER_URL" in reason
+ "parse_method",
+ ["naive", "manual", "paper"],
+)
+def test_transfer_to_sections_counts_images_detected_for_app_media_modes(monkeypatch, tmp_path, parse_method):
+ """App-media modes (issue #16978): naive, manual, and paper all
+ route IMAGE blocks through _transfer_to_tables and skip them in
+ _transfer_to_sections. The image_coverage stamp must still report
+ images_detected correctly for these modes so operators can see how
+ many images the parser saw."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ a_path = tmp_path / "a.jpg"
+ b_path = tmp_path / "b.jpg"
+ module.Image.new("RGB", (2, 2), "red").save(a_path)
+ module.Image.new("RGB", (2, 2), "blue").save(b_path)
+
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["A"],
+ "image_footnote": [],
+ "img_path": str(a_path),
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["B"],
+ "image_footnote": [],
+ "img_path": str(b_path),
+ "page_idx": 1,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ # _transfer_to_sections returns no IMAGE sections for app-media
+ # modes — they go to _transfer_to_tables instead.
+ sections = parser._transfer_to_sections(outputs, parse_method=parse_method)
+ assert sections == []
+
+ # The coverage stamp must report every IMAGE block the parser saw
+ # and emitted via the table path. We invoke _transfer_to_tables to
+ # mirror what parse_pdf does for naive/manual/paper.
+ parser._transfer_to_tables(outputs, table_enable=True)
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 2
+ assert coverage["images_chunked"] == 2
+ assert coverage["images_dropped_no_text"] == 0
+ assert coverage["images_unreadable_resource"] == 0
+
+
+def test_transfer_to_sections_app_media_mode_with_image_dropped_after_sanitization(monkeypatch, caplog):
+ """Regression for #16978: even in naive/manual/paper modes, an IMAGE
+ block whose caption/footnote/VLM description is empty would still
+ register as `images_dropped_no_text` if it ever reached the
+ section-building branch. App-media modes skip IMAGE entirely before
+ the branch, so this case is a no-op — but the helper must not
+ raise or misreport counters."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/silent.jpg",
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ }
+ ]
+
+ with caplog.at_level(logging.WARNING, logger=parser.logger.name):
+ parser._transfer_to_sections(outputs, parse_method="naive")
+
+ coverage = parser.last_image_coverage
+ # Detected is correct (1); the IMAGE block was skipped at the
+ # naive/manual/paper branch, not at the empty-section branch.
+ assert coverage["images_detected"] == 1
+ assert coverage["images_dropped_no_text"] == 0
+ # App-media modes do not warn per-image — _transfer_to_tables handles
+ # them instead, so the warning channel here stays quiet.
+ assert "Dropped embedded image" not in caplog.text
+
+
+def test_mineruparser_initializes_last_image_coverage_in_constructor(monkeypatch):
+ """Regression for issue #16978: the attribute
+ must exist from construction, independent of whether parse_pdf has
+ run yet — no more getattr(self, ..., None) fallback in the
+ caller."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+
+ # Direct attribute access — not a getattr with a default — must work.
+ assert isinstance(parser.last_image_coverage, dict)
+ assert parser.last_image_coverage == {
+ "images_detected": 0,
+ "images_chunked": 0,
+ "images_described": 0,
+ "images_dropped_no_text": 0,
+ "images_unreadable_resource": 0,
+ "vlm_configured": False,
+ }
+
+
+def test_transfer_to_sections_app_media_image_with_only_vlm_description(monkeypatch, caplog):
+ """Even when an IMAGE block has a vlm_description and no
+ caption/footnote, app-media modes (naive/manual/paper) must still
+ register the image as detected so the operator sees the count
+ matches what the VLM model produced."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": "/tmp/vlm.jpg",
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ "vlm_description": "A description from the vision model.",
+ }
+ ]
+
+ sections = parser._transfer_to_sections(outputs, parse_method="naive")
+ assert sections == []
+
+ coverage = parser.last_image_coverage
+ # _transfer_to_sections increments images_detected before it skips
+ # the IMAGE block in app-media modes (naive/manual/paper), so the
+ # detection count is correct even though the section path returned
+ # nothing for the IMAGE. The chunked/described counters advance only
+ # via _transfer_to_tables.
+ assert coverage["images_detected"] == 1
+ assert coverage["images_chunked"] == 0
+ assert coverage["images_described"] == 0
+ assert coverage["images_unreadable_resource"] == 0
+
+
+def test_transfer_to_tables_counts_chunked_and_described(monkeypatch, tmp_path):
+ """_transfer_to_tables is the path that emits IMAGE blocks for
+ naive/manual/paper. The final coverage stamp must reflect that
+ emission (chunked += 1, described += 1 when vlm_description is set)
+ so operators can see the full pipeline outcome — not just the
+ section path."""
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ # Create real image files on disk so PIL.Image.open succeeds.
+ a_path = tmp_path / "a.jpg"
+ b_path = tmp_path / "b.jpg"
+ module.Image.new("RGB", (2, 2), "red").save(a_path)
+ module.Image.new("RGB", (2, 2), "blue").save(b_path)
+
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Caption A"],
+ "image_footnote": [],
+ "img_path": str(a_path),
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ "vlm_description": "VLM description for A.",
+ },
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": str(b_path),
+ "page_idx": 1,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ tables = parser._transfer_to_tables(outputs, table_enable=True)
+ assert len(tables) == 2
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_chunked"] == 2
+ assert coverage["images_described"] == 1 # only the first had a vlm_description
+ assert coverage["images_dropped_no_text"] == 0
+ assert coverage["images_unreadable_resource"] == 0
+
+
+def test_raw_mode_counts_unreadable_resource_in_sections(monkeypatch, tmp_path):
+ """Raw mode (parse_method='raw') does NOT call _transfer_to_tables
+ in production — parse_pdf gates that on naive/manual/paper (see
+ mineru_parser.py:~1201). The unreadable-resource counter in raw
+ mode therefore only gets populated by _transfer_to_sections'
+ raw-mode text path, which never reaches Image.open().
+
+ The realistic raw-mode failure that maps to
+ images_unreadable_resource is the *download-time* one — text got
+ produced but the resource itself never landed. That is a parser
+ upstream of MinerU. In raw mode at this layer the corresponding
+ raw-mode counter stays at 0; the field is present so callers can
+ read it without KeyError (issue #16978 review).
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ good_path = tmp_path / "good.jpg"
+ module.Image.new("RGB", (2, 2), "red").save(good_path)
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Caption A"],
+ "image_footnote": [],
+ "img_path": str(good_path),
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ parser._transfer_to_sections(outputs, parse_method="raw")
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1
+ assert coverage["images_chunked"] == 1 # section emitted, so chunked
+ assert coverage["images_unreadable_resource"] == 0
+ assert coverage["images_dropped_no_text"] == 0
+
+
+def test_app_media_mode_counts_unreadable_resource(monkeypatch, tmp_path):
+ """App-media modes (naive/manual/paper) skip IMAGE blocks in
+ _transfer_to_sections and route them through _transfer_to_tables.
+ An IMAGE with a non-empty caption but a missing/corrupted binary
+ must route to images_unreadable_resource — NOT
+ images_dropped_no_text (which is reserved for textless+unreadable).
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ parser.page_from = 0
+ missing_path = tmp_path / "missing.jpg" # never created on disk
+
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": ["Caption B"],
+ "image_footnote": [],
+ "img_path": str(missing_path),
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ # Mirror parse_pdf's call order: _transfer_to_sections first (app-media
+ # mode skips images), then _transfer_to_tables (handles them).
+ parser._transfer_to_sections(outputs, parse_method="naive")
+ tables = parser._transfer_to_tables(outputs, table_enable=True)
+ # The image is unreadable, so it does not reach tables.
+ assert len(tables) == 0
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1
+ # app-media mode: images_chunked is only incremented in
+ # _transfer_to_tables when the image actually reaches the tables
+ # list — this one doesn't, so chunked stays at 0.
+ assert coverage["images_chunked"] == 0
+ assert coverage["images_unreadable_resource"] == 1 # the missing file
+ assert coverage["images_dropped_no_text"] == 0 # text was non-empty
+
+
+def test_app_media_mode_counts_dropped_no_text_for_unreadable_textless_image(
+ monkeypatch,
+ tmp_path,
+):
+ """App-media IMAGE block whose caption/footnote/vlm_description are
+ all empty AND whose binary can't be read must route to
+ images_dropped_no_text (text was never going to make it), NOT
+ images_unreadable_resource (which is reserved for the case where
+ text WAS there but the binary was unreadable).
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ parser.page_from = 0
+ missing_path = tmp_path / "missing.jpg" # never created on disk
+
+ outputs = [
+ {
+ "type": module.MinerUContentType.IMAGE,
+ "image_caption": [],
+ "image_footnote": [],
+ "img_path": str(missing_path),
+ "page_idx": 0,
+ "bbox": (0, 0, 10, 10),
+ },
+ ]
+
+ parser._transfer_to_sections(outputs, parse_method="naive")
+ parser._transfer_to_tables(outputs, table_enable=True)
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1
+ # The textless + unreadable combo routes to images_dropped_no_text,
+ # NOT images_unreadable_resource.
+ assert coverage["images_dropped_no_text"] == 1
+ assert coverage["images_unreadable_resource"] == 0
+ # chunked is only incremented on confirmed emit — this image
+ # never reached tables, so chunked stays at 0.
+ assert coverage["images_chunked"] == 0
+
+
+def test_images_detected_counts_chart_blocks(monkeypatch):
+ """CHART blocks share the visual pipeline with IMAGE (caption → text
+ section, binary → image chunk via _transfer_to_tables). The detected
+ counter must include them so the detected/chunked/described totals
+ are symmetric — otherwise a chart-only PDF would show detected=0
+ chunked=N which is misleading.
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.CHART,
+ "chart_caption": ["Figure 3"],
+ "chart_footnote": [],
+ "page_idx": 0,
+ "bbox": (0, 0, 1, 1),
+ },
+ ]
+
+ parser._transfer_to_sections(outputs, parse_method="raw")
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1, f"CHART blocks must count toward images_detected; got {coverage!r}"
+
+
+def test_transfer_to_tables_counts_chart_chunked_and_described(monkeypatch, tmp_path):
+ """CHART blocks that survive _transfer_to_tables must be counted
+ symmetrically with IMAGE in chunked and described. VLM
+ descriptions on chart blocks must count too (raw-mode text path
+ also reads vlm_description for charts and now increments described).
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ parser.page_from = 0
+ chart_path = tmp_path / "chart.png"
+ module.Image.new("RGB", (2, 2), "blue").save(chart_path)
+ outputs = [
+ {
+ "type": module.MinerUContentType.CHART,
+ "img_path": str(chart_path),
+ "chart_caption": ["Figure 3"],
+ "chart_footnote": [],
+ "vlm_description": "A blue square",
+ "page_idx": 0,
+ "bbox": (1, 2, 3, 4),
+ },
+ ]
+
+ parser._transfer_to_tables(outputs)
+ coverage = parser.last_image_coverage
+ chart_path.unlink()
+ assert coverage["images_chunked"] == 1
+ assert coverage["images_described"] == 1
+
+
+def test_transfer_to_sections_counts_chart_described_in_raw_mode(monkeypatch):
+ """Raw-mode text path: when a chart has a vlm_description it folds
+ into the chunk text. The described counter must reflect that, the
+ same way IMAGE does on the same code path.
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.CHART,
+ "chart_caption": ["Figure 3"],
+ "chart_footnote": [],
+ "vlm_description": "Trend line rising.",
+ "page_idx": 0,
+ "bbox": (0, 0, 1, 1),
+ },
+ ]
+
+ parser._transfer_to_sections(outputs, parse_method="raw")
+ coverage = parser.last_image_coverage
+ assert coverage["images_described"] == 1, f"CHART with vlm_description must count toward images_described in raw mode; got {coverage!r}"
+
+
+def test_raw_mode_counts_chart_block_as_chunked(monkeypatch):
+ """CHART blocks emitted into a raw-mode text section must count as
+ chunked, the same way IMAGE does. Without this, a chart-only raw
+ PDF reports detected > 0 but chunked = 0, which fires a systematic
+ false positive on the headline detected - chunked gap.
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ outputs = [
+ {
+ "type": module.MinerUContentType.CHART,
+ "chart_caption": ["Figure 3"],
+ "chart_footnote": [],
+ "page_idx": 0,
+ "bbox": (0, 0, 1, 1),
+ },
+ ]
+
+ parser._transfer_to_sections(outputs, parse_method="raw")
+
+ coverage = parser.last_image_coverage
+ assert coverage["images_detected"] == 1
+ assert coverage["images_chunked"] == 1, f"CHART emitted as a raw-mode text section must count as chunked; got {coverage!r}"
+ assert coverage["images_dropped_no_text"] == 0
+
+
+def test_initial_last_image_coverage_has_vlm_configured_key(monkeypatch):
+ """Pre-seed vlm_configured=False on the parser instance so callers
+ that read last_image_coverage["vlm_configured"] after only
+ _transfer_to_sections (without parse_pdf having filled it in) get
+ False instead of KeyError (issue #16978 review).
+ """
+ module = _load_mineru_parser(monkeypatch)
+ parser = module.MinerUParser()
+ assert "vlm_configured" in parser.last_image_coverage
+ assert parser.last_image_coverage["vlm_configured"] is False