Skip to content

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

9.8 KB
Raw Blame
"""Tests for vision-model image captions on reading materials.

The vision client is stubbed so no network call is made; the store, the media
index round-trip and the refresh guard are exercised for real on a tmp store.
"""

from __future__ import annotations

import io
import json
from pathlib import Path
import random

from PIL import Image as PILImage
import pytest

from deeptutor.reading import captions as captions_module
from deeptutor.reading.models import ReadingError
from deeptutor.reading.store import ReadingStore

_MATERIAL_ID = "a" * 16


class _StubClient:
    """Minimal stand-in for the LLM facade used by the caption pass."""

    def __init__(self, *, vision: bool = True, fail: set[str] | None = None) -> None:
        self._vision = vision
        self._fail = fail or set()
        self.calls: list[str] = []

    def supports_multimodal_images(self) -> bool:
        return self._vision

    async def complete(
        self, prompt: str, system_prompt: str | None = None, **kwargs: object
    ) -> str:
        name = str(kwargs.get("image_filename") or "")
        self.calls.append(name)
        if name in self._fail:
            raise RuntimeError("vision call failed")
        return f"a chart labelled {name}"


@pytest.fixture(autouse=True)
def _fast_limits(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.setattr(captions_module, "image_description_limits", lambda: (4, 5.0))


@pytest.fixture
def store(tmp_path: Path) -> ReadingStore:
    root = tmp_path / "reading"
    root.mkdir()
    store = ReadingStore(root)
    store.ingest_units(
        _MATERIAL_ID,
        filename="deck.pptx",
        unit="slide",
        units=["Slide one text", "Slide two text"],
    )
    media_dir = root / _MATERIAL_ID / "media"
    media_dir.mkdir()
    rows = []
    for index in range(3):
        name = f"image-{index:02d}.png"
        (media_dir / name).write_bytes(b"png-bytes")
        rows.append({"name": name, "locator": 1, "mime": "image/png", "bytes": 9})
    (root / _MATERIAL_ID / "media.json").write_text(json.dumps(rows), encoding="utf-8")
    return store


@pytest.mark.asyncio
async def test_caption_material_media_writes_back(
    store: ReadingStore, monkeypatch: pytest.MonkeyPatch
) -> None:
    stub = _StubClient()
    monkeypatch.setattr(captions_module, "get_image_description_client", lambda: stub)

    written = await captions_module.caption_material_media(_MATERIAL_ID, store=store)

    assert written == 3
    assert len(stub.calls) == 3
    rows = store.media_items(_MATERIAL_ID)
    assert all(str(row.get("caption") or "") for row in rows)


@pytest.mark.asyncio
async def test_existing_captions_are_skipped(
    store: ReadingStore, monkeypatch: pytest.MonkeyPatch
) -> None:
    stub = _StubClient()
    monkeypatch.setattr(captions_module, "get_image_description_client", lambda: stub)

    assert await captions_module.caption_material_media(_MATERIAL_ID, store=store) == 3
    stub.calls.clear()

    again = await captions_module.caption_material_media(_MATERIAL_ID, store=store)

    assert again == 0
    assert stub.calls == []


@pytest.mark.asyncio
async def test_missing_captions_reuse_cache_but_force_refreshes(store, monkeypatch, tmp_path):
    from types import SimpleNamespace

    from deeptutor.services.llm import image_caption_cache
    from deeptutor.services.llm.config import LLMConfig

    stub = _StubClient()
    stub.config = LLMConfig(model="vision-test", api_key="test-key")
    monkeypatch.setattr(captions_module, "get_image_description_client", lambda: stub)
    monkeypatch.setattr(
        image_caption_cache,
        "get_path_service",
        lambda: SimpleNamespace(get_parse_cache_root=lambda: tmp_path / "cache"),
    )
    rows = store.media_items(_MATERIAL_ID)
    index = tmp_path / "reading" / _MATERIAL_ID / "media.json"
    assert await captions_module.caption_material_media(_MATERIAL_ID, store=store) == 3
    index.write_text(json.dumps(rows))  # Retry ingest with the same source images.
    assert await captions_module.caption_material_media(_MATERIAL_ID, store=store) == 3
    assert len(stub.calls) == 3
    # The stub returns identical text, so the store reports no changed rows.
    assert await captions_module.caption_material_media(_MATERIAL_ID, store=store, force=True) == 0
    assert len(stub.calls) == 6


@pytest.mark.asyncio
async def test_single_failure_keeps_the_rest(
    store: ReadingStore, monkeypatch: pytest.MonkeyPatch
) -> None:
    stub = _StubClient(fail={"image-01.png"})
    monkeypatch.setattr(captions_module, "get_image_description_client", lambda: stub)

    written = await captions_module.caption_material_media(_MATERIAL_ID, store=store)

    assert written == 2
    captions = {row["name"]: row.get("caption") for row in store.media_items(_MATERIAL_ID)}
    assert captions["image-00.png"]
    assert captions["image-02.png"]
    assert not captions.get("image-01.png")


@pytest.mark.asyncio
async def test_text_only_client_makes_no_calls(
    store: ReadingStore, monkeypatch: pytest.MonkeyPatch
) -> None:
    stub = _StubClient(vision=False)
    monkeypatch.setattr(captions_module, "get_image_description_client", lambda: stub)

    written = await captions_module.caption_material_media(_MATERIAL_ID, store=store)

    assert written == 0
    assert stub.calls == []


def test_update_media_captions_ignores_unknown_names(store: ReadingStore) -> None:
    changed = store.update_media_captions(
        _MATERIAL_ID, {"missing.png": "ghost", "image-00.png": "hello"}
    )

    assert changed == 1
    captions = {row["name"]: row.get("caption") for row in store.media_items(_MATERIAL_ID)}
    assert captions["image-00.png"] == "hello"
    assert not captions.get("image-01.png")
    # An empty value never erases an existing caption nor counts as a change.
    assert store.update_media_captions(_MATERIAL_ID, {"image-01.png": ""}) == 0


# ---------------------------------------------------------------------------
# refresh_document
# ---------------------------------------------------------------------------


def _png_bytes(seed: int = 11) -> bytes:
    rng = random.Random(seed)
    data = bytes(rng.randrange(256) for _ in range(400 * 300 * 3))
    buf = io.BytesIO()
    PILImage.frombytes("RGB", (400, 300), data).save(buf, format="PNG")
    return buf.getvalue()


def _pdf_with_image(path: Path) -> None:
    import pymupdf

    doc = pymupdf.open()
    page = doc.new_page()
    prose = "Figure one shows the measured throughput across three configurations. " * 8
    page.insert_textbox(pymupdf.Rect(72, 72, 520, 280), prose, fontsize=9)
    page.insert_image(pymupdf.Rect(72, 320, 300, 520), stream=_png_bytes(seed=11))
    page.insert_image(pymupdf.Rect(320, 320, 540, 520), stream=_png_bytes(seed=23))
    doc.save(str(path))
    doc.close()


def test_refresh_document_preserves_state_and_captions(tmp_path: Path) -> None:
    store = ReadingStore(tmp_path / "reading")
    pdf = tmp_path / "deck.pdf"
    _pdf_with_image(pdf)
    manifest = store.ingest(pdf)
    names = [str(row["name"]) for row in store.media_items(manifest.material_id)]
    assert manifest.unit_count >= 1
    assert len(names) >= 2  # one figure kept, one re-appearing uncaptioned

    content_dir = tmp_path / "reading" / manifest.material_id
    annotation_file = content_dir / "annotations" / f"{manifest.material_id}.json"
    annotation_file.parent.mkdir(parents=True, exist_ok=True)
    annotation_file.write_text("[]", encoding="utf-8")
    position_file = content_dir / "positions" / f"{manifest.material_id}.json"
    position_file.parent.mkdir(parents=True, exist_ok=True)
    position_file.write_text("{}", encoding="utf-8")

    # Generated rasters must survive a re-extraction untouched.
    asset_file = content_dir / "assets" / "cover.png"
    asset_file.parent.mkdir(parents=True, exist_ok=True)
    asset_file.write_bytes(b"poster-bytes")

    # The same image gets a different old filename, while the other old
    # filename now holds different bytes. Only the matching image may keep
    # its caption when extraction assigns ordinal names again.
    kept_name = names[0]
    new_name = names[1]
    legacy_name = "legacy-figure.png"
    media_dir = content_dir / "media"
    (media_dir / kept_name).rename(media_dir / legacy_name)
    (media_dir / new_name).write_bytes(_png_bytes(seed=77))
    media_index = content_dir / "media.json"
    rows = [
        {
            "name": legacy_name,
            "locator": 1,
            "mime": "image/png",
            "bytes": 9,
            "caption": f"kept caption for {kept_name}",
        },
        {
            "name": new_name,
            "locator": 1,
            "mime": "image/png",
            "bytes": 9,
            "caption": "stale caption for replaced bytes",
        },
    ]
    rows.append(
        {
            "name": "ghost.png",
            "locator": 1,
            "mime": "image/png",
            "bytes": 9,
            "caption": "ghost caption",
        }
    )
    media_index.write_text(json.dumps(rows), encoding="utf-8")

    refreshed = store.refresh_document(manifest.material_id)

    assert refreshed.unit_count == manifest.unit_count
    assert refreshed.revision == manifest.revision + 1
    assert annotation_file.is_file()
    assert position_file.is_file()
    assert asset_file.read_bytes() == b"poster-bytes"
    captions = {row["name"]: row.get("caption") for row in store.media_items(manifest.material_id)}
    assert captions.get(kept_name) == f"kept caption for {kept_name}"
    assert new_name in captions and not captions.get(new_name)
    assert "ghost.png" not in captions
    assert legacy_name not in captions


def test_refresh_document_requires_raw_bytes(tmp_path: Path) -> None:
    store = ReadingStore(tmp_path / "reading")
    store.ingest_units("b" * 16, filename="notes.txt", units=["Some notes"])

    with pytest.raises(ReadingError):
        store.refresh_document("b" * 16)

    assert store.unit_text("b" * 16, 1) == "Some notes"