RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
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.pyindex 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 = 0self.page_to = MAXIMUM_PAGE_NUMBERself.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,+ }@staticmethoddef _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"] += 1section = (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"] += 1section = (section.strip("\n") + "\n" + vlm_description).strip("\n") if section.strip() else vlm_descriptioncase 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_coveragereturn sectionsdef _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 = Noneimage_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"] += 1continue+ # 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, tablesfinally: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.pyindex 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