Sync from GitHub via hub-sync

content_pipeline.py

@@ -108,6 +108,109 @@ def generate_deck(text: str, n: int = 12) -> list[Card]:
     return _dedupe(cards)[:n]
 
 
+# ---- Image-only / scanned PDFs (multimodal model) --------------------------
+# When a PDF has no extractable text layer (scanned/photographed), there's
+# nothing to chunk — so render the pages to images and let the multimodal model
+# (MiniCPM-V) read them directly. Additive to the text path above (unchanged);
+# only meaningful with a vision model (RECALL_MODEL=v46, RECALL_STUB=0).
+
+MAX_PDF_IMAGE_PAGES = int(os.getenv("RECALL_MAX_PDF_PAGES", "8"))
+
+
+def is_image_only_pdf(file) -> bool:
+    """True if `file` is a PDF whose pages have no selectable text (scanned/
+    image-only) — the case extract_text() rejects and this module renders
+    instead. False for non-PDFs / unreadable files (let extract_text surface the
+    real error)."""
+    path = getattr(file, "name", file)
+    if not str(path).lower().endswith(".pdf") or not os.path.isfile(path):
+        return False
+    try:
+        from pypdf import PdfReader
+        reader = PdfReader(path)
+        text = "".join((page.extract_text() or "") for page in reader.pages)
+    except Exception:
+        return False
+    return not _normalize(text)
+
+
+def render_pdf_images(file, max_pages: int = MAX_PDF_IMAGE_PAGES) -> list:
+    """Render up to `max_pages` PDF pages to RGB PIL.Images for the vision model.
+    Returns [] for a non-PDF. Requires PyMuPDF + Pillow (real-model deps)."""
+    path = getattr(file, "name", file)
+    if not str(path).lower().endswith(".pdf"):
+        return []
+    import io
+
+    import fitz  # PyMuPDF
+    from PIL import Image
+
+    images = []
+    with fitz.open(path) as doc:
+        for page in list(doc)[:max_pages]:
+            pix = page.get_pixmap(dpi=150)
+            images.append(Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB"))
+    return images
+
+
+def generate_deck_from_images(images: list, n: int = 12) -> list[Card]:
+    """Generate question cards from PDF page images via the multimodal model —
+    the image-only/scanned-PDF counterpart to generate_deck(text). Always returns
+    valid Cards (bad model output is skipped, never crashes).
+
+    NEEDS GPU VERIFICATION: the real path needs a vision model + GPU and can't be
+    exercised locally. Stub returns the canned demo deck so the flow still runs.
+    """
+    if llm.STUB:
+        return generate_deck("")  # canned demo deck — no model/GPU
+    if not images:
+        return []
+    messages = [
+        {"role": "system", "content": (
+            "You are a quiz generator. You are given the page images of a study "
+            "document. Produce 3 to 5 quiz questions that test different aspects of "
+            "the material at varying difficulty levels.\n\n"
+            "GROUNDING RULES (critical):\n"
+            "- Every question AND its answer must be answerable using ONLY what is "
+            "visible in the page images.\n"
+            "- Do NOT introduce facts, names, numbers, or examples not in the images.\n"
+            "- If the pages are too thin for a question, write fewer rather than "
+            "inventing content.\n\n"
+            "Return ONLY a JSON array. Each element must have exactly these keys:\n"
+            "  question   — the question text (clear, specific, one sentence)\n"
+            "  answer     — a concise reference answer (1-3 sentences)\n"
+            "  topic      — a short tag naming the concept (e.g. 'Cell Biology')\n"
+            "  difficulty — integer: 1 (recall), 2 (application), 3 (synthesis)\n\n"
+            "No prose, no markdown fences, no text outside the JSON array."
+        )},
+        {"role": "user", "content": list(images) + [
+            "Generate quiz questions from these document page images."]},
+    ]
+    # Same defensive strict-JSON + repair pass as the text path; images ride along
+    # in the message content and llm.chat() routes them to the vision model.
+    data = llm.chat_json(messages, max_tokens=900, retries=1)
+    if not isinstance(data, list):
+        return []
+    out: list[Card] = []
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        try:
+            difficulty = max(1, min(3, int(item.get("difficulty") or 1)))
+        except (ValueError, TypeError):
+            difficulty = 1
+        card = new_card(
+            question=str(item.get("question", "")).strip(),
+            answer=str(item.get("answer", "")).strip(),
+            topic=str(item.get("topic", "General")).strip() or "General",
+            source_chunk="[scanned PDF page]",
+            difficulty=difficulty,
+        )
+        if validate_card(card):
+            out.append(card)
+    return _dedupe(out)[:n]
+
+
 # ---- Internals (Frank implements) ------------------------------------------
 
 def _normalize(text: str) -> str:

server.py

@@ -197,6 +197,9 @@ async def api_generate(
                  "notes or pick a PDF, and I'll build your deck.")
 
     source = ""
+    # Set when a scanned/image-only PDF is turned into a deck by the vision model
+    # (no text to chunk); `None` means "fall through to the text path below".
+    deck_from_images = None
     if text and text.strip():
         source = text.strip()[:MAX_TEXT_CHARS]  # cap to bound chunking work
         if len(source) < 40:
@@ -228,22 +231,34 @@ async def api_generate(
             # Extraction (PDF parsing) is blocking — keep it off the event loop.
             source = await run_in_threadpool(cp.extract_text, tmp_path)
         except cp.ExtractionError as e:
-            return JSONResponse({"error": str(e)}, status_code=422)
+            # A scanned/image-only PDF has no text to chunk — render its pages and
+            # let the multimodal model read them directly. Fall back to the
+            # original error if it's not image-only or no pages render.
+            if await run_in_threadpool(cp.is_image_only_pdf, tmp_path):
+                images = await run_in_threadpool(cp.render_pdf_images, tmp_path)
+                if images:
+                    deck_from_images = await run_in_threadpool(
+                        cp.generate_deck_from_images, images)
+            if deck_from_images is None:
+                return JSONResponse({"error": str(e)}, status_code=422)
         finally:
             os.unlink(tmp_path)
     else:
         return JSONResponse({"error": need_more}, status_code=400)
 
-    try:
-        # Deck generation hits the model — run it in a worker thread so a slow
-        # call doesn't block every other request on the event loop.
-        deck = await run_in_threadpool(cp.generate_deck, source)
-    except Exception as e:  # noqa: BLE001 — surface as friendly copy, never crash
-        return JSONResponse(
-            {"error": f"Couldn't build a deck from that ({type(e).__name__}). "
-                      "Try different material."},
-            status_code=422,
-        )
+    if deck_from_images is not None:
+        deck = deck_from_images
+    else:
+        try:
+            # Deck generation hits the model — run it in a worker thread so a slow
+            # call doesn't block every other request on the event loop.
+            deck = await run_in_threadpool(cp.generate_deck, source)
+        except Exception as e:  # noqa: BLE001 — surface as friendly copy, never crash
+            return JSONResponse(
+                {"error": f"Couldn't build a deck from that ({type(e).__name__}). "
+                          "Try different material."},
+                status_code=422,
+            )
     if not deck:
         return JSONResponse(
             {"error": "Couldn't generate questions from that. Try different material."},

test_grade_answer.py

@@ -15,6 +15,13 @@ import llm
 import learning_engine as le
 from schema import new_card
 
+# `llm.STUB` is read once at import. Under the full pytest run another test file
+# imports `llm` first (with stub on), so the env flip above wouldn't take — and
+# grade_answer would silently use the heuristic instead of the patched chat.
+# Pin it off here so these tests are robust to import order. (Downstream test
+# files either reload llm or don't depend on STUB.)
+llm.STUB = False
+
 
 def _card():
     return new_card(

test_image_pdf.py

@@ -0,0 +1,113 @@
+"""
+Image-only / scanned-PDF path: detect no-text PDFs, render pages to images, and
+build a deck from them. The render/detect plumbing is testable without a GPU;
+the model call is exercised only in stub mode here (real vision inference is
+covered by the deploy, not locally). Skips when the real-model image deps
+(PyMuPDF + Pillow) aren't installed — they live in requirements-model.txt.
+
+    RECALL_STUB=1 python3 -m pytest test_image_pdf.py
+"""
+import io
+import os
+import tempfile
+
+import pytest
+
+os.environ.setdefault("RECALL_STUB", "1")
+
+fitz = pytest.importorskip("fitz", reason="needs PyMuPDF (real-model dep)")
+PIL_Image = pytest.importorskip("PIL.Image", reason="needs Pillow (real-model dep)")
+from PIL import Image, ImageDraw  # noqa: E402
+
+import content_pipeline as cp  # noqa: E402
+
+
+def _make_scanned_pdf(pages: int = 2) -> str:
+    """A PDF with no text layer — each page is a rasterized image."""
+    fd, path = tempfile.mkstemp(suffix=".pdf")
+    os.close(fd)
+    doc = fitz.open()
+    for i in range(pages):
+        img = Image.new("RGB", (600, 800), "white")
+        ImageDraw.Draw(img).text((40, 40), f"Scanned page {i + 1}", fill="black")
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        page = doc.new_page(width=600, height=800)
+        page.insert_image(fitz.Rect(0, 0, 600, 800), stream=buf.getvalue())
+    doc.save(path)
+    doc.close()
+    return path
+
+
+def _make_text_pdf() -> str:
+    fd, path = tempfile.mkstemp(suffix=".pdf")
+    os.close(fd)
+    doc = fitz.open()
+    doc.new_page().insert_text((72, 72), "Selectable text about photosynthesis.")
+    doc.save(path)
+    doc.close()
+    return path
+
+
+def test_is_image_only_pdf_detects_scanned():
+    path = _make_scanned_pdf()
+    try:
+        assert cp.is_image_only_pdf(path) is True
+    finally:
+        os.unlink(path)
+
+
+def test_text_pdf_is_not_image_only():
+    path = _make_text_pdf()
+    try:
+        assert cp.is_image_only_pdf(path) is False
+    finally:
+        os.unlink(path)
+
+
+def test_non_pdf_is_not_image_only_and_renders_nothing():
+    assert cp.is_image_only_pdf("notes.txt") is False
+    assert cp.render_pdf_images("notes.txt") == []
+
+
+def test_render_pdf_images_returns_pages():
+    path = _make_scanned_pdf(pages=3)
+    try:
+        images = cp.render_pdf_images(path)
+        assert len(images) == 3
+        assert all(isinstance(im, Image.Image) for im in images)
+    finally:
+        os.unlink(path)
+
+
+def test_render_pdf_images_respects_max_pages():
+    path = _make_scanned_pdf(pages=5)
+    try:
+        assert len(cp.render_pdf_images(path, max_pages=2)) == 2
+    finally:
+        os.unlink(path)
+
+
+def test_generate_deck_from_images_stub():
+    # STUB returns the canned demo deck regardless of the images passed. Pin
+    # llm.STUB explicitly (and restore) so this is robust to other test files'
+    # import-order / STUB mutations rather than relying on ambient state.
+    import llm
+    prev = llm.STUB
+    llm.STUB = True
+    try:
+        deck = cp.generate_deck_from_images([object(), object()])
+    finally:
+        llm.STUB = prev
+    assert isinstance(deck, list) and len(deck) >= 1
+    assert all(c.get("question") and c.get("answer") for c in deck)
+
+
+if __name__ == "__main__":
+    test_is_image_only_pdf_detects_scanned()
+    test_text_pdf_is_not_image_only()
+    test_non_pdf_is_not_image_only_and_renders_nothing()
+    test_render_pdf_images_returns_pages()
+    test_render_pdf_images_respects_max_pages()
+    test_generate_deck_from_images_stub()
+    print("All image-PDF tests passed.")