fix(parsers): warn that VLM is text-only and on silent parser downgrade (#77)

Author: KylinMountain

README.md

@@ -313,6 +313,10 @@ Each parser handles a subset of formats — `mineru` covers PDF, Word, PPT, Exce
 and HTML; `mistral` and `vlm` cover PDF. `.md` and any unsupported format always
 fall back to the local parser.
 
+The `vlm` parser is **text-only**: it transcribes a document's text via a vision
+LLM but does **not** extract embedded figures/images. Use `mineru`, `mistral`, or
+`local` if you need image extraction.
+
 > **Note:** Long PDFs (≥ `pageindex_threshold` pages, default 20) continue to be
 > indexed with PageIndex and are **not** affected by the `parser` setting. The
 > parser governs the file → Markdown step for shorter documents and non-PDF files.

openkb/converter.py

@@ -103,6 +103,11 @@ def convert_document(src: Path, kb_dir: Path, parser_override: str | None = None
         source_dir=src.parent,
     )
     if not parser.supports(src.suffix):
+        if parser.name != "local":
+            logger.warning(
+                "Parser %r does not support %r; falling back to the local parser for %s.",
+                parser.name, src.suffix, src.name,
+            )
         parser = LocalParser(doc_name=doc_name, images_dir=images_dir, source_dir=src.parent)
 
     parse_result = parser.parse(src)

openkb/parsers/vlm.py

@@ -34,4 +34,9 @@ def supports(self, suffix: str) -> bool:
 
     def parse(self, src: Path) -> ParseResult:
         markdown = transcribe_to_markdown(src, model=self.model)
+        logger.warning(
+            "VLM parser transcribes %s to text only; embedded figures/images are "
+            "not extracted. Use a parser like 'mineru' if you need figure extraction.",
+            src.name,
+        )
         return ParseResult(markdown=markdown)

tests/test_converter.py

@@ -177,3 +177,18 @@ def test_local_parser_skips_redundant_localize(self, kb_dir):
             result = convert_document(src, kb_dir)
         li.assert_not_called()                      # local path skips localize_images
         assert result.source_path.read_text(encoding="utf-8") == "# md final"
+
+    def test_warns_on_silent_downgrade(self, kb_dir, caplog):
+        import logging as _logging
+        src = kb_dir / "raw" / "notes.md"
+        src.write_text("# md", encoding="utf-8")
+        online = MagicMock()
+        online.name = "mistral"
+        online.supports.return_value = False
+        with patch("openkb.converter.get_parser", return_value=online), \
+             patch("openkb.converter.LocalParser") as LP:
+            LP.return_value.name = "local"
+            LP.return_value.parse.return_value = ParseResult(markdown="# md")
+            with caplog.at_level(_logging.WARNING):
+                convert_document(src, kb_dir)
+        assert any("falling back to the local parser" in r.message for r in caplog.records)

tests/test_parsers_vlm.py

@@ -45,3 +45,14 @@ def test_no_warning_when_vlm_model_set(caplog):
     with caplog.at_level(_logging.WARNING):
         VLMParser({"model": "gemini/gemini-2.5-pro"}, model="gpt-5.4-mini")
     assert not any("parsers.vlm.model" in r.message for r in caplog.records)
+
+
+def test_parse_warns_text_only(tmp_path, caplog):
+    import logging as _logging
+    from unittest.mock import patch
+    src = tmp_path / "d.pdf"; src.write_bytes(b"%PDF")
+    p = VLMParser({"model": "gemini/gemini-2.5-pro"})
+    with patch("openkb.parsers.vlm.transcribe_to_markdown", return_value="# md"):
+        with caplog.at_level(_logging.WARNING):
+            p.parse(src)
+    assert any("text only" in r.message for r in caplog.records)