DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
fix(rag): cache successful image batches with complete request identity
Bingxi Zhao (Frank)be2936873360
diff --git a/deeptutor/services/llm/image_caption_batch.py b/deeptutor/services/llm/image_caption_batch.pyindex 930439144..e4fb03e9e 100644--- a/deeptutor/services/llm/image_caption_batch.py+++ b/deeptutor/services/llm/image_caption_batch.py@@ -12,6 +12,7 @@ from .exceptions import (LLMRateLimitError,ProviderContextWindowError,)+from .image_caption_cache import complete_image_caption_batchlogger = logging.getLogger(__name__)_BATCH_INSTRUCTIONS = (@@ -71,6 +72,15 @@ class ImageCaptionBatcher:async def describe(self, images: list[dict[str, str]]) -> list[str | None]:if not images or self.halted:return [None] * len(images)+ return await complete_image_caption_batch(+ self.client,+ images,+ prompt=self.prompt,+ system_prompt=self.system_prompt + (_BATCH_INSTRUCTIONS if len(images) > 1 else ""),+ generate=lambda: self._describe_uncached(images),+ )++ async def _describe_uncached(self, images: list[dict[str, str]]) -> list[str | None]:try:if len(images) == 1:image = images[0]diff --git a/deeptutor/services/llm/image_caption_cache.py b/deeptutor/services/llm/image_caption_cache.pyindex 5cc909e0e..e51e286ab 100644--- a/deeptutor/services/llm/image_caption_cache.py+++ b/deeptutor/services/llm/image_caption_cache.py@@ -1,4 +1,4 @@-"""Best-effort, workspace-scoped caching for individual image descriptions.+"""Best-effort, workspace-scoped caching for image descriptions.Only successful, nonempty captions are cached. The digest covers the completerequest and model identity; only the digest and caption are written to disk,@@ -9,6 +9,7 @@ never image bytes, prompts, endpoint URLs, headers, or credentials. Removingfrom __future__ import annotationsimport asyncio+from collections.abc import Awaitable, Callableimport hashlibimport jsonimport logging@@ -126,3 +127,72 @@ async def complete_image_caption(if path is not None and caption:await asyncio.to_thread(_write_caption, path, caption)return caption+++def _read_batch_captions(path: Path, count: int) -> list[str] | None:+ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ if not isinstance(payload, dict) or payload.get("version") != _CACHE_VERSION:+ return None+ captions = payload.get("captions")+ if (+ isinstance(captions, list)+ and len(captions) == count+ and all(isinstance(caption, str) and caption.strip() for caption in captions)+ ):+ return [caption.strip() for caption in captions]+ except (OSError, ValueError, UnicodeError):+ pass+ return None+++def _write_batch_captions(path: Path, captions: list[str]) -> None:+ try:+ atomic_write_json(path, {"version": _CACHE_VERSION, "captions": captions})+ except OSError:+ logger.debug("Image caption batch cache write failed; retaining generated captions")+++async def complete_image_caption_batch(+ client: Any,+ images: list[dict[str, str]],+ *,+ prompt: str,+ system_prompt: str,+ generate: Callable[[], Awaitable[list[str | None]]],+) -> list[str | None]:+ """Cache complete successful groups using their exact request identity.++ Image order and metadata, the structured prompt, and the bounded retry+ policy are part of the digest. Batch entries remain separate from ordinary+ single-image captions. Partial failures, errors and cancellation are never+ cached; split groups can independently reuse their successful entries.+ """+ request = {+ "prompt": prompt,+ "system_prompt": system_prompt,+ "image_data": json.dumps(+ [{key: image[key] for key in ("base64", "mimetype", "filename")} for image in images],+ sort_keys=True,+ ensure_ascii=True,+ separators=(",", ":"),+ ),+ "batch_format": "id_checked_v1",+ "max_retries": "0",+ "allow_image_fallback": "false",+ }+ path = await asyncio.to_thread(_cache_path, client, request)+ if path is not None:+ cached = await asyncio.to_thread(_read_batch_captions, path, len(images))+ if cached is not None:+ return cached+ captions = await generate()+ if (+ path is not None+ and len(captions) == len(images)+ and all(isinstance(caption, str) and caption.strip() for caption in captions)+ ):+ await asyncio.to_thread(+ _write_batch_captions, path, [caption.strip() for caption in captions]+ )+ return captionsdiff --git a/docs-for-user/SOURCE_VISUALS.md b/docs-for-user/SOURCE_VISUALS.mdindex 6a583dc65..9a9a00326 100644--- a/docs-for-user/SOURCE_VISUALS.md+++ b/docs-for-user/SOURCE_VISUALS.md@@ -49,7 +49,10 @@ limits stop queued groups in the job; other API/transport errors do not split.This only affects subsequently processed images in the existing LlamaIndexdescription pass. It does not enable descriptions for structured source visualsor alter reading-material captions. Batches use a different structured prompt-and do not reuse the independent single-image caption cache. Setting the size+and cache complete, successful groups separately from independent single-image+captions. The digest includes ordered image contents and metadata, prompts,+model identity, and retry policy. Failed, incomplete, or canceled groups are+not cached; successful split groups can be reused. Setting the sizeback to `1` restores the normal single-image path. The model must supportmultiple image blocks; unsupported API responses are reported without a burstof fallback requests.diff --git a/tests/services/llm/test_image_caption_batch.py b/tests/services/llm/test_image_caption_batch.pyindex b4905967d..ebc316fa9 100644--- a/tests/services/llm/test_image_caption_batch.py+++ b/tests/services/llm/test_image_caption_batch.py@@ -161,3 +161,84 @@ async def test_settings_roundtrip_clamps_and_preserves_omitted_fields(tmp_path,knowledge.LlamaIndexConfigUpdate(image_description_batch_size=0))assert rag_config.image_description_batch_size() == 1+++def batch_cache(tmp_path, monkeypatch):+ from types import SimpleNamespace++ 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),+ )+ return tmp_path+++def cached_client(mode="valid"):+ from deeptutor.services.llm.config import LLMConfig++ client = Client(mode)+ client.config = LLMConfig(+ model="vision", api_key="test-secret", base_url="https://example.test/v1"+ )+ return client+++async def test_batch_cache_preserves_request_identity_and_contains_only_captions(batch_cache):+ client = cached_client()+ group = images(2)+ expected = ["IMAGE_0 caption", "IMAGE_1 caption"]+ assert await batcher(client).describe(group) == expected+ assert await batcher(client).describe(group) == expected+ assert len(client.calls) == 1+ for path in batch_cache.rglob("*.json"):+ payload = path.read_text()+ assert json.loads(payload) == {"version": 1, "captions": expected}+ assert not any(+ secret in payload + str(path)+ for secret in ("test-secret", "example.test", "data0", "Be factual")+ )+ await batcher(client).describe(list(reversed(group)))+ client.config.model = "other-vision"+ await batcher(client).describe(group)+ await ImageCaptionBatcher(client, prompt="Read labels", system_prompt="Be factual").describe(+ group+ )+ assert len(client.calls) == 4+++async def test_successful_split_result_is_reused_without_new_provider_requests(batch_cache):+ client = cached_client("invalid")+ expected = [f"single {i}.png" for i in range(4)]+ assert await batcher(client).describe(images(4)) == expected+ assert len(client.calls) == 7+ assert await batcher(client).describe(images(4)) == expected+ assert len(client.calls) == 7+++ "error",+ [+ LLMAuthenticationError(),+ LLMRateLimitError(),+ LLMAPIError("down", status_code=503),+ asyncio.CancelledError(),+ ],+)+async def test_failed_or_canceled_batch_is_retried_on_next_job(batch_cache, error):+ client = cached_client(error)+ if isinstance(error, asyncio.CancelledError):+ with pytest.raises(asyncio.CancelledError):+ await batcher(client).describe(images(2))+ else:+ assert await batcher(client).describe(images(2)) == [None, None]+ assert not list(batch_cache.rglob("*.json"))+ client.mode = "valid"+ assert await batcher(client).describe(images(2)) == ["IMAGE_0 caption", "IMAGE_1 caption"]+ assert len(client.calls) == 2diff --git a/tests/services/rag/test_llamaindex_image_description.py b/tests/services/rag/test_llamaindex_image_description.pyindex 4838876d3..8db5c5303 100644--- a/tests/services/rag/test_llamaindex_image_description.py+++ b/tests/services/rag/test_llamaindex_image_description.py@@ -274,3 +274,49 @@ async def test_batch_deadline_covers_split_fallback(tmp_path, monkeypatch):assert len(calls) == 2 # canceled first single fallback; second is never sentassert time.monotonic() - start < 0.8assert progress == [1, 2]+++async def test_cached_batch_ingestion_keeps_source_alignment_and_reports_all_progress(+ tmp_path, monkeypatch+):+ from types import SimpleNamespace++ from deeptutor.services.llm import image_caption_cache+ from deeptutor.services.llm.config import LLMConfig+ from deeptutor.services.rag.pipelines.llamaindex import document_loader as loader_module++ calls = []++ async def complete(prompt, **kwargs):+ calls.append(kwargs)+ return json.dumps(+ {+ "captions": [+ {"image_id": "IMAGE_1", "caption": "second"},+ {"image_id": "IMAGE_0", "caption": "first"},+ ]+ }+ )++ _install_multimodal_clients(monkeypatch, complete_fn=complete)+ client = loader_module.get_image_description_client()+ client.config = LLMConfig(model="vision", api_key="test", base_url="https://example.test/v1")+ monkeypatch.setattr(loader_module, "get_image_description_client", lambda: client)+ monkeypatch.setattr(loader_module, "image_description_batch_size", lambda: 2)+ monkeypatch.setattr(+ image_caption_cache,+ "get_path_service",+ lambda: SimpleNamespace(get_parse_cache_root=lambda: tmp_path / "cache"),+ )+ paths = _make_images(tmp_path, ["a.png", "b.png"])+ for _ in range(2):+ progress = []+ docs = await loader_module.LlamaIndexDocumentLoader().load(+ [str(p) for p in paths],+ image_progress_callback=lambda n, total: progress.append((n, total)),+ )+ assert [d.metadata["file_name"] for d in docs] == ["a.png", "b.png"]+ assert [d.text for d in docs] == ["[Image] a.png\n\nfirst", "[Image] b.png\n\nsecond"]+ assert progress == [(1, 2), (2, 2)]+ assert len(calls) == 1