Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

27.2 KB
Raw Blame
"""Tests for LlamaIndex document loading.

Parser-backed files (PDF / Office / e-book) are routed through the shared
parse layer, so these tests exercise the *routing* — that the loader turns a
``ParsedDocument`` into text ``Document``s and feeds engine-extracted images
into the multimodal ``ImageNode`` path. Real per-format text extraction is
covered by ``tests/utils/test_document_extractor.py`` and the parse-engine
tests under ``tests/services/parsing/``.
"""

from __future__ import annotations

import asyncio
from pathlib import Path
import threading
from types import SimpleNamespace

import pytest


@pytest.fixture(autouse=True)
def isolated_caption_cache(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    """Provider stubs must not read or write a persistent workspace cache."""
    from deeptutor.services.llm import image_caption_cache

    monkeypatch.setattr(
        image_caption_cache,
        "get_path_service",
        lambda: SimpleNamespace(get_parse_cache_root=lambda: tmp_path / "parse_cache"),
    )


def _install_stub_parse_service(monkeypatch, results: dict[str, "object"]) -> None:
    """Point ``get_parse_service`` at a stub keyed by source file name.

    ``results`` maps a file name to either a ``ParsedDocument`` to return or an
    exception instance to raise (e.g. ``ParserError``).
    """
    import deeptutor.services.parsing as parsing

    class _StubService:
        def parse(self, source_path, **_kwargs):
            outcome = results[Path(source_path).name]
            if isinstance(outcome, Exception):
                raise outcome
            return outcome

    monkeypatch.setattr(parsing, "get_parse_service", lambda: _StubService())


def _install_sequential_parse_service(
    monkeypatch: pytest.MonkeyPatch,
    outcomes: list["object"],
) -> list[tuple[str, str | None]]:
    """Record ``(file_name, engine)`` calls and return one outcome per call."""
    import deeptutor.services.parsing as parsing

    calls: list[tuple[str, str | None]] = []

    class _SequentialStubService:
        def parse(self, source_path, engine=None, **_kwargs):  # noqa: ANN001
            calls.append((Path(source_path).name, engine))
            outcome = outcomes[len(calls) - 1]
            if isinstance(outcome, Exception):
                raise outcome
            return outcome

    monkeypatch.setattr(parsing, "get_parse_service", lambda: _SequentialStubService())
    return calls


def test_loader_routes_parser_files_through_active_parse_engine(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    docx_path = tmp_path / "notes.docx"
    docx_path.write_bytes(b"stub")
    pdf_path = tmp_path / "paper.pdf"
    pdf_path.write_bytes(b"stub")

    _install_stub_parse_service(
        monkeypatch,
        {
            "notes.docx": ParsedDocument(markdown="Docx body text"),
            # No markdown, only structured blocks -> block-text fallback.
            "paper.pdf": ParsedDocument(
                markdown="",
                blocks=[{"type": "text", "text": "Block one"}, {"content": "Block two"}],
            ),
        },
    )

    documents = asyncio.run(LlamaIndexDocumentLoader().load([str(docx_path), str(pdf_path)]))

    by_name = {doc.metadata["file_name"]: doc.text for doc in documents}
    assert by_name["notes.docx"] == "Docx body text"
    assert "Block one" in by_name["paper.pdf"]
    assert "Block two" in by_name["paper.pdf"]


def test_loader_routes_images_through_active_parser_when_supported(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    import deeptutor.services.parsing as parsing
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    image_path = tmp_path / "diagram.png"
    image_path.write_bytes(b"\x89PNG\r\n")
    calls: list[Path] = []

    class _StubService:
        def supports(self, path: Path) -> bool:
            return path.suffix == ".png"

        def parse(self, path: Path, **_kwargs):
            calls.append(path)
            return ParsedDocument(markdown="OCR and layout from MinerU", engine="mineru")

    service = _StubService()
    monkeypatch.setattr(parsing, "get_parse_service", lambda: service)

    documents = asyncio.run(LlamaIndexDocumentLoader().load([str(image_path)]))

    assert calls == [image_path]
    assert len(documents) == 1
    assert documents[0].text == "OCR and layout from MinerU"


def test_loader_keeps_event_loop_responsive_while_parser_blocks(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    import deeptutor.services.parsing as parsing
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    pdf_path = tmp_path / "slow.pdf"
    pdf_path.write_bytes(b"stub")
    parse_started = threading.Event()
    allow_parse_to_finish = threading.Event()

    class _BlockingService:
        def parse(self, _source_path, **_kwargs):
            parse_started.set()
            assert allow_parse_to_finish.wait(timeout=2)
            return ParsedDocument(markdown="Parsed without blocking the loop")

    monkeypatch.setattr(parsing, "get_parse_service", lambda: _BlockingService())

    async def _exercise() -> list[object]:
        load_task = asyncio.create_task(LlamaIndexDocumentLoader().load([str(pdf_path)]))
        deadline = asyncio.get_running_loop().time() + 1
        while not parse_started.is_set():
            assert asyncio.get_running_loop().time() < deadline
            await asyncio.sleep(0.001)

        # Reaching this line while parse() is still waiting proves that the
        # parser is not occupying the event-loop thread.
        assert not load_task.done()
        allow_parse_to_finish.set()
        return await asyncio.wait_for(load_task, timeout=1)

    documents = asyncio.run(_exercise())
    assert [document.text for document in documents] == ["Parsed without blocking the loop"]


def test_loader_skips_document_when_active_engine_cannot_parse(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParserError
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    docx_path = tmp_path / "unsupported.docx"
    docx_path.write_bytes(b"stub")

    _install_stub_parse_service(
        monkeypatch,
        {"unsupported.docx": ParserError("the 'pymupdf4llm' engine doesn't support .docx files")},
    )

    with caplog.at_level("WARNING"):
        documents = asyncio.run(LlamaIndexDocumentLoader().load([str(docx_path)]))

    assert documents == []
    assert "Skipped unsupported.docx" in caplog.text
    assert "Settings" in caplog.text


def test_loader_continues_after_mineru_task_failure(tmp_path, monkeypatch):
    """#1982: a failed CLI document cannot prevent later documents from loading."""
    pytest.importorskip("llama_index.core")
    from deeptutor.knowledge.indexing_run import IndexingRun
    from deeptutor.services.parsing.engines.mineru.config import MinerUError
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import LlamaIndexDocumentLoader

    failed = tmp_path / "failed.pdf"
    good = tmp_path / "next.docx"
    failed.write_bytes(b"fixture")
    good.write_bytes(b"fixture")
    _install_stub_parse_service(
        monkeypatch,
        {
            failed.name: MinerUError(
                "1 task(s) failed while processing documents: Timed out waiting for result"
            ),
            good.name: ParsedDocument(markdown="The next document is still usable."),
        },
    )
    with IndexingRun(tmp_path, [str(failed), str(good)]) as run:
        documents = asyncio.run(LlamaIndexDocumentLoader().load([str(failed), str(good)]))
        assert [doc.metadata["file_name"] for doc in documents] == [good.name]
        assert run.data["documents"][run.source_key(failed)]["status"] == "failed"
        assert run.data["documents"][run.source_key(good)]["status"] == "embedding"


@pytest.mark.parametrize("encrypted", [False, True])
def test_unusable_pdf_evidence_does_not_abort_other_documents(tmp_path, monkeypatch, encrypted):
    """A parser success is not a guarantee that the PDF can supply page evidence."""
    import pymupdf

    from deeptutor.knowledge.indexing_run import IndexingRun
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import LlamaIndexDocumentLoader

    raw = tmp_path / "raw"
    raw.mkdir()
    bad = raw / "bad.pdf"
    if encrypted:
        with pymupdf.open() as pdf:
            pdf.new_page().insert_text((72, 72), "Private source")
            pdf.save(
                bad, encryption=pymupdf.PDF_ENCRYPT_AES_256, owner_pw="owner", user_pw="reader"
            )
    else:
        bad.write_bytes(b"%PDF-1.7\ntruncated")
    good = raw / "good.docx"
    good.write_bytes(b"parser fixture")
    _install_stub_parse_service(
        monkeypatch,
        {
            bad.name: ParsedDocument(markdown="Parser supplied text", engine="mineru"),
            good.name: ParsedDocument(markdown="Usable next document"),
        },
    )
    with IndexingRun(tmp_path, [str(bad), str(good)]) as run:
        documents = asyncio.run(
            LlamaIndexDocumentLoader().load([str(bad), str(good)], kb_dir=tmp_path)
        )
        assert [doc.metadata["file_name"] for doc in documents] == [good.name]
        failure = run.data["documents"][run.source_key(bad)]
        assert failure["status"] == "failed"
        assert failure["reason"] == "invalid_source"
        assert failure["detail"]
        assert run.data["documents"][run.source_key(good)]["status"] == "embedding"


def test_loader_explains_scanned_pdf_when_parser_yields_images_only(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    pdf_path = tmp_path / "scan.pdf"
    pdf_path.write_bytes(b"stub")
    asset_dir = tmp_path / "assets"
    asset_dir.mkdir()
    (asset_dir / "page-1.png").write_bytes(b"\x89PNG\r\n")

    _install_stub_parse_service(
        monkeypatch,
        {
            "scan.pdf": ParsedDocument(
                markdown="",
                engine="pymupdf4llm",
                asset_dir=asset_dir,
            )
        },
    )

    class _TextOnlyClient:
        config = type("Config", (), {"binding": "openai", "model": "text-embedding"})()

        def supports_multimodal_contents(self) -> bool:
            return False

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _TextOnlyClient())

    with caplog.at_level("WARNING"):
        documents = asyncio.run(LlamaIndexDocumentLoader().load([str(pdf_path)]))

    assert documents == []
    assert "pymupdf4llm engine extracted 1 image(s) but no text" in caplog.text
    assert "scanned PDF" in caplog.text
    assert "OCR-capable" in caplog.text
    assert "Settings, Document Parsing" in caplog.text


def _text_only_embedding_client():
    class _TextOnlyClient:
        config = type("Config", (), {"binding": "openai", "model": "text-embedding"})()

        def supports_multimodal_contents(self) -> bool:
            return False

    return _TextOnlyClient()


def test_loader_falls_back_to_installed_liteparse_for_scanned_pdf(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    pdf_path = tmp_path / "scan.pdf"
    pdf_path.write_bytes(b"stub")
    asset_dir = tmp_path / "assets"
    asset_dir.mkdir()
    (asset_dir / "page-1.png").write_bytes(b"\x89PNG\r\n")

    calls = _install_sequential_parse_service(
        monkeypatch,
        [
            ParsedDocument(markdown="", engine="pymupdf4llm", asset_dir=asset_dir),
            ParsedDocument(markdown="Recovered scanned text", engine="liteparse"),
        ],
    )
    monkeypatch.setattr(
        loader_module,
        "get_embedding_client",
        lambda: _text_only_embedding_client(),
    )

    documents = asyncio.run(LlamaIndexDocumentLoader().load([str(pdf_path)]))

    assert calls == [("scan.pdf", None), ("scan.pdf", "liteparse")]
    assert [document.text for document in documents] == ["Recovered scanned text"]


def test_loader_reports_scanned_pdf_when_ocr_fallback_is_unavailable(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
    caplog: pytest.LogCaptureFixture,
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument, ParserError
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    pdf_path = tmp_path / "scan.pdf"
    pdf_path.write_bytes(b"stub")
    asset_dir = tmp_path / "assets"
    asset_dir.mkdir()
    (asset_dir / "page-1.png").write_bytes(b"\x89PNG\r\n")

    calls = _install_sequential_parse_service(
        monkeypatch,
        [
            ParsedDocument(markdown="", engine="pymupdf4llm", asset_dir=asset_dir),
            ParserError("liteparse isn't installed"),
        ],
    )
    monkeypatch.setattr(
        loader_module,
        "get_embedding_client",
        lambda: _text_only_embedding_client(),
    )

    with caplog.at_level("WARNING"):
        documents = asyncio.run(LlamaIndexDocumentLoader().load([str(pdf_path)]))

    assert calls == [("scan.pdf", None), ("scan.pdf", "liteparse")]
    assert documents == []
    assert "Automatic OCR fallback failed for scan.pdf" in caplog.text
    assert "Skipped scanned PDF: scan.pdf" in caplog.text
    assert "Install LiteParse" in caplog.text


def test_loader_does_not_fallback_when_liteparse_already_ran(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    pdf_path = tmp_path / "scan.pdf"
    pdf_path.write_bytes(b"stub")
    asset_dir = tmp_path / "assets"
    asset_dir.mkdir()
    (asset_dir / "page-1.png").write_bytes(b"\x89PNG\r\n")

    calls = _install_sequential_parse_service(
        monkeypatch,
        [ParsedDocument(markdown="", engine="liteparse", asset_dir=asset_dir)],
    )
    monkeypatch.setattr(
        loader_module,
        "get_embedding_client",
        lambda: _text_only_embedding_client(),
    )

    documents = asyncio.run(LlamaIndexDocumentLoader().load([str(pdf_path)]))

    assert calls == [("scan.pdf", None)]
    assert documents == []


def test_loader_keeps_generic_empty_warning_for_non_pdf(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import (
        LlamaIndexDocumentLoader,
    )

    docx_path = tmp_path / "blank.docx"
    docx_path.write_bytes(b"stub")
    _install_stub_parse_service(
        monkeypatch,
        {"blank.docx": ParsedDocument(markdown="", engine="markitdown")},
    )

    with caplog.at_level("WARNING"):
        documents = asyncio.run(LlamaIndexDocumentLoader().load([str(docx_path)]))

    assert documents == []
    assert caplog.text.count("Skipped empty document: blank.docx") == 1
    assert "scanned PDF" not in caplog.text


def test_loader_indexes_images_extracted_from_parsed_document(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    from llama_index.core.schema import ImageNode

    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    pdf_path = tmp_path / "paper.pdf"
    pdf_path.write_bytes(b"stub")
    asset_dir = tmp_path / "assets"
    asset_dir.mkdir()
    (asset_dir / "figure-1.png").write_bytes(b"\x89PNG\r\n")
    (asset_dir / "notes.txt").write_text("not an image", encoding="utf-8")  # ignored

    _install_stub_parse_service(
        monkeypatch,
        {"paper.pdf": ParsedDocument(markdown="Paper body", asset_dir=asset_dir)},
    )

    class _MultimodalEmbeddingClient:
        config = type("Config", (), {"binding": "siliconflow", "model": "qwen3-vl"})()

        def supports_multimodal_contents(self) -> bool:
            return True

        async def embed_contents(self, contents):
            return [[0.4, 0.5, 0.6] for _ in contents]

    class _VisionClient:
        config = type("Config", (), {"binding": "openai", "model": "gpt-4o"})()

        def supports_multimodal_images(self) -> bool:
            return True

        async def complete(self, prompt, **kwargs):
            return "Figure showing a bar chart."

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _MultimodalEmbeddingClient())
    monkeypatch.setattr(loader_module, "get_image_description_client", lambda: _VisionClient())

    documents = asyncio.run(loader_module.LlamaIndexDocumentLoader().load([str(pdf_path)]))

    text_docs = [doc for doc in documents if not isinstance(doc, ImageNode)]
    image_nodes = [doc for doc in documents if isinstance(doc, ImageNode)]

    assert len(text_docs) == 1
    assert text_docs[0].text == "Paper body"

    assert len(image_nodes) == 1
    node = image_nodes[0]
    assert node.embedding == [0.4, 0.5, 0.6]
    assert node.metadata["content_type"] == "image"
    # Provenance: the extracted image cites the source document, not the cache asset.
    assert node.metadata["file_name"] == "paper.pdf"
    assert node.image_path == str(asset_dir / "figure-1.png")
    assert "Figure showing a bar chart." in node.text


def test_loader_skips_images_when_embedding_provider_is_text_only(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    image_path = tmp_path / "photo.png"
    image_path.write_bytes(b"\x89PNG\r\n")

    class _TextOnlyClient:
        config = type("Config", (), {"binding": "openai", "model": "text-embedding-3-small"})()

        def supports_multimodal_contents(self) -> bool:
            return False

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _TextOnlyClient())

    def _unexpected_llm_client():
        pytest.fail("text-only embedding must not initialize the LLM client")

    monkeypatch.setattr(loader_module, "get_image_description_client", _unexpected_llm_client)

    documents = asyncio.run(loader_module.LlamaIndexDocumentLoader().load([str(image_path)]))

    assert documents == []


def test_loader_embeds_images_with_qwen38_max_vision_capability(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    from llama_index.core.schema import ImageNode

    from deeptutor.services.llm.client import LLMClient
    from deeptutor.services.llm.config import LLMConfig
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    image_path = tmp_path / "photo.png"
    image_path.write_bytes(b"\x89PNG\r\n")
    captured: dict[str, object] = {}

    class _MultimodalClient:
        config = type("Config", (), {"binding": "siliconflow", "model": "qwen3-vl"})()

        def supports_multimodal_contents(self) -> bool:
            return True

        async def embed_contents(self, contents):
            captured["contents"] = contents
            return [[0.1, 0.2, 0.3]]

    vision_client = LLMClient(
        LLMConfig(
            binding="dashscope",
            model="qwen3.8-max",
            api_key="test-key",
            base_url="https://example.invalid/v1",
        )
    )

    async def _complete(prompt: str, **kwargs: object) -> str:
        captured["llm_prompt"] = prompt
        captured["llm_kwargs"] = kwargs
        return "A logo image with visible HKU text."

    monkeypatch.setattr(vision_client, "complete", _complete)

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _MultimodalClient())
    monkeypatch.setattr(loader_module, "get_image_description_client", lambda: vision_client)

    documents = asyncio.run(loader_module.LlamaIndexDocumentLoader().load([str(image_path)]))

    assert len(documents) == 1
    assert isinstance(documents[0], ImageNode)
    assert documents[0].embedding == [0.1, 0.2, 0.3]
    assert documents[0].metadata["content_type"] == "image"
    assert documents[0].metadata["image_description"] == "A logo image with visible HKU text."
    assert "A logo image with visible HKU text." in documents[0].text
    assert captured["contents"][0]["image"].startswith("data:image/png;base64,")
    assert captured["llm_kwargs"]["image_mime_type"] == "image/png"


def test_loader_logs_and_continues_when_image_progress_callback_fails(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
    caplog: pytest.LogCaptureFixture,
) -> None:
    pytest.importorskip("llama_index.core")
    from llama_index.core.schema import ImageNode

    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    image_paths = []
    for name in ("photo-1.png", "photo-2.png"):
        path = tmp_path / name
        path.write_bytes(b"\x89PNG\r\n")
        image_paths.append(path)

    class _MultimodalEmbeddingClient:
        config = type("Config", (), {"binding": "siliconflow", "model": "qwen3-vl"})()

        def supports_multimodal_contents(self) -> bool:
            return True

        async def embed_contents(self, contents):
            return [[0.1, 0.2, 0.3] for _ in contents]

    class _VisionClient:
        config = type("Config", (), {"binding": "openai", "model": "gpt-4o"})()

        def supports_multimodal_images(self) -> bool:
            return True

        async def complete(self, prompt, **kwargs):
            return "Stub description."

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _MultimodalEmbeddingClient())
    monkeypatch.setattr(loader_module, "get_image_description_client", lambda: _VisionClient())

    calls: list[tuple[int, int]] = []

    def _flaky_callback(completed: int, total: int) -> None:
        calls.append((completed, total))
        if completed == 1:
            raise RuntimeError("progress sink is down")

    with caplog.at_level("WARNING"):
        documents = asyncio.run(
            loader_module.LlamaIndexDocumentLoader().load(
                [str(path) for path in image_paths],
                image_progress_callback=_flaky_callback,
            )
        )

    # The callback stays invoked for every image even after one failure.
    assert calls == [(1, 2), (2, 2)]
    # A failing callback must not abort the batch: both images still load.
    assert len(documents) == 2
    assert all(isinstance(doc, ImageNode) for doc in documents)
    assert "Image progress callback failed" in caplog.text
    assert "progress sink is down" in caplog.text


def test_loader_skips_images_when_llm_is_text_only(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    image_path = tmp_path / "photo.png"
    image_path.write_bytes(b"\x89PNG\r\n")

    class _MultimodalEmbeddingClient:
        config = type("Config", (), {"binding": "siliconflow", "model": "qwen3-vl"})()

        def supports_multimodal_contents(self) -> bool:
            return True

    class _TextOnlyLLMClient:
        config = type("Config", (), {"binding": "openai", "model": "gpt-3.5-turbo"})()

        def supports_multimodal_images(self) -> bool:
            return False

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _MultimodalEmbeddingClient())
    monkeypatch.setattr(loader_module, "get_image_description_client", lambda: _TextOnlyLLMClient())

    documents = asyncio.run(loader_module.LlamaIndexDocumentLoader().load([str(image_path)]))

    assert documents == []


def test_loader_skips_images_when_llm_client_is_unavailable(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module

    image_path = tmp_path / "photo.png"
    image_path.write_bytes(b"\x89PNG\r\n")

    class _MultimodalEmbeddingClient:
        config = type("Config", (), {"binding": "siliconflow", "model": "qwen3-vl"})()

        def supports_multimodal_contents(self) -> bool:
            return True

    def _unavailable_llm_client():
        raise RuntimeError("no LLM configured")

    monkeypatch.setattr(loader_module, "get_embedding_client", lambda: _MultimodalEmbeddingClient())
    monkeypatch.setattr(loader_module, "get_image_description_client", _unavailable_llm_client)

    with caplog.at_level("WARNING"):
        documents = asyncio.run(loader_module.LlamaIndexDocumentLoader().load([str(image_path)]))

    assert documents == []
    assert "requires both multimodal embedding and multimodal LLM support" in caplog.text
    assert "LLM client is unavailable" in caplog.text
    assert "no LLM configured" in caplog.text


def test_loader_falls_back_to_ocr_when_scanned_pdf_has_no_extracted_assets(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    pytest.importorskip("llama_index.core")
    from deeptutor.services.parsing.types import ParsedDocument
    from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module
    from deeptutor.services.rag.pipelines.llamaindex.document_loader import LlamaIndexDocumentLoader

    pdf_path = tmp_path / "scan.pdf"
    pdf_path.write_bytes(b"stub")
    calls = _install_sequential_parse_service(
        monkeypatch,
        [
            ParsedDocument(markdown="", engine="pymupdf4llm"),
            ParsedDocument(markdown="Recovered scan", engine="liteparse"),
        ],
    )
    monkeypatch.setattr(
        loader_module, "get_embedding_client", lambda: _text_only_embedding_client()
    )
    documents = asyncio.run(LlamaIndexDocumentLoader().load([str(pdf_path)]))
    assert calls == [("scan.pdf", None), ("scan.pdf", "liteparse")]
    assert [item.text for item in documents] == ["Recovered scan"]