Sync from GitHub via hub-sync

.gitignore

@@ -1,37 +0,0 @@
-# Secrets / env
-.env
-.env.*
-!.env.example
-
-# Temp
-.tmp/
-
-# Python
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-build/
-dist/
-*.egg-info/
-.eggs/
-
-# Virtual environments
-.venv/
-venv/
-env/
-ENV/
-
-# Test / coverage
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-
-# OS / editor
-.DS_Store
-*.swp
-.idea/
-.vscode/

llm.py

@@ -32,16 +32,30 @@ STUB = os.getenv("RECALL_STUB", "1") == "1"
 
 # Known models, keyed by short alias so swapping is a single env-var flip.
 MODELS = {
-    "8b": "openbmb/MiniCPM4.1-8B",   # default / primary
-    "1b": "openbmb/MiniCPM5-1B",     # fast fallback if the Space is slow / OOM
-    "4b": "openbmb/MiniCPM3-4B",     # mid fallback (Tiny Titan badge)
+    "v46": "openbmb/MiniCPM-V-4.6",  # default / primary — multimodal (text + image)
+    "8b": "openbmb/MiniCPM4.1-8B",   # legacy text-only (needs transformers<5.0)
+    "1b": "openbmb/MiniCPM5-1B",     # legacy fast fallback
+    "4b": "openbmb/MiniCPM3-4B",     # legacy mid fallback (Tiny Titan badge)
 }
-_requested = os.getenv("RECALL_MODEL", "8b")
-# Accept an alias ("1b") or a full HF id ("org/model") passed through verbatim.
+# Default is the multimodal MiniCPM-V 4.6 so the same model grades text AND reads
+# image-only / scanned PDFs. The legacy text aliases need transformers<5.0 and no
+# longer load against the pinned transformers 5.x — keep them only for reference.
+_requested = os.getenv("RECALL_MODEL", "v46")
+# Accept an alias ("v46") or a full HF id ("org/model") passed through verbatim.
 MODEL_ID = MODELS.get(_requested, _requested)
 
+
+def _is_vision_model(model_id: str) -> bool:
+    """MiniCPM-V (vision) ids load via a different class + processor than the
+    text-only MiniCPM models. Detect by the '-V' family marker."""
+    return "minicpm-v" in model_id.lower()
+
+
+VISION = _is_vision_model(MODEL_ID)
+
 _model = None
 _tokenizer = None
+_processor = None  # MiniCPM-V uses an AutoProcessor (image+text) instead of a tokenizer
 
 
 def active_model() -> str:
@@ -93,6 +107,103 @@ def _load():
     )
 
 
+# ---- MiniCPM-V (multimodal) path -------------------------------------------
+# NEEDS GPU VERIFICATION: the calls below mirror the official MiniCPM-V-4.6 demo
+# Space (openbmb/MiniCPM-V-4.6-Demo) but can't be exercised without a GPU + the
+# ~9B model. The stub and legacy text paths are unchanged and remain testable.
+
+
+def _maybe_gpu(fn):
+    """Wrap with HF ZeroGPU's @spaces.GPU when available; otherwise a no-op.
+    `spaces` ships only in the real-model deps and is effect-free off a ZeroGPU
+    Space, so this is safe in stub/local environments where it isn't installed.
+    Registering a @spaces.GPU function is ALSO what keeps a ZeroGPU Space healthy
+    (a ZeroGPU Space with none flips to RUNTIME_ERROR — see server.py)."""
+    try:
+        import spaces
+    except Exception:  # noqa: BLE001 — not installed (stub/local): run un-wrapped
+        return fn
+    return spaces.GPU(duration=120)(fn)
+
+
+def _load_vision() -> None:
+    """Lazy-load the MiniCPM-V model + processor once. Only called when STUB is
+    off and the active model is a vision model."""
+    global _model, _processor
+    if _model is not None:
+        return
+    import torch
+    from transformers import AutoProcessor, MiniCPMV4_6ForConditionalGeneration
+
+    dtype = getattr(torch, _resolve_dtype_name())
+    device_map = _resolve_device_map()
+    print(f"[recall] loading vision model: {MODEL_ID} (dtype={_resolve_dtype_name()}, "
+          f"device_map={device_map})")
+    _processor = AutoProcessor.from_pretrained(MODEL_ID, trust_remote_code=True)
+    _model = MiniCPMV4_6ForConditionalGeneration.from_pretrained(
+        MODEL_ID,
+        torch_dtype=dtype,
+        attn_implementation="sdpa",
+        trust_remote_code=True,
+        device_map=device_map,
+    ).eval()
+
+
+def _to_vision_content(content):
+    """Normalize a message's `content` to MiniCPM-V parts. Accepts a plain string
+    (text-only) or a list mixing strings and PIL.Image objects (image+text)."""
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    parts = []
+    for item in content:
+        if isinstance(item, str):
+            parts.append({"type": "text", "text": item})
+        else:  # a PIL.Image (or anything image-like the processor accepts)
+            parts.append({"type": "image", "image": item})
+    return parts
+
+
+@_maybe_gpu
+def _chat_vision(messages: list[dict], max_tokens: int) -> str:
+    """MiniCPM-V 4.6 inference, mirroring the official demo's processor+generate
+    call (non-streaming). enable_thinking=False keeps the tight token budget for
+    the JSON answer instead of a <think> preamble."""
+    _load_vision()
+    import torch
+
+    msgs = [{"role": m["role"], "content": _to_vision_content(m["content"])}
+            for m in messages]
+    inputs = _processor.apply_chat_template(
+        msgs,
+        add_generation_prompt=True,
+        tokenize=True,
+        return_dict=True,
+        return_tensors="pt",
+        enable_thinking=False,
+        processor_kwargs={
+            "downsample_mode": "16x",
+            "max_slice_nums": 9,
+            "use_image_id": True,
+        },
+    ).to(_model.device)
+    # MiniCPM-V wants floating inputs (e.g. pixel_values) in the model dtype.
+    for k, v in inputs.items():
+        if isinstance(v, torch.Tensor) and torch.is_floating_point(v):
+            inputs[k] = v.to(dtype=getattr(torch, _resolve_dtype_name()))
+
+    with torch.no_grad():
+        out = _model.generate(
+            **inputs,
+            max_new_tokens=max_tokens,
+            do_sample=True,
+            temperature=0.7,
+            top_p=0.9,
+            downsample_mode="16x",
+        )
+    gen = out[0][inputs["input_ids"].shape[1]:]
+    return _processor.tokenizer.decode(gen, skip_special_tokens=True).strip()
+
+
 def _render_prompt(messages: list[dict]) -> str:
     """Build the prompt string. MiniCPM4.1/MiniCPM5 are hybrid reasoning models;
     we pass enable_thinking=False so they answer directly instead of spending the
@@ -118,12 +229,19 @@ def chat(messages: list[dict], max_tokens: int = 512) -> str:
     messages: [{"role": "system"|"user"|"assistant", "content": str}, ...]
     Returns the assistant's text.
 
-    On a HF ZeroGPU Space, wrap the *callers'* entrypoints (or this function)
-    with @spaces.GPU. Keep max_tokens tight — latency is the demo killer.
+    `content` is normally a str. For the multimodal model it may also be a list
+    mixing strings and PIL.Image objects (image+text) — e.g. for image-only PDFs.
+
+    GPU work is wrapped with @spaces.GPU inside the vision path; that decorator is
+    also what keeps a ZeroGPU Space healthy. Keep max_tokens tight — latency is
+    the demo killer.
     """
     if STUB:
         return _stub_reply(messages)
 
+    if VISION:
+        return _chat_vision(messages, max_tokens)
+
     _load()
     text = _render_prompt(messages)
     inputs = _tokenizer(text, return_tensors="pt").to(_model.device)
@@ -232,9 +350,19 @@ def chat_json(messages: list[dict], max_tokens: int = 256, retries: int = 1):
 
 # ---- Stub replies so the app runs with no model ----------------------------
 
+def _msg_text(content) -> str:
+    """Text of a message's content, ignoring any images (content may be a str or
+    a list mixing strings and PIL.Image objects)."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return " ".join(p for p in content if isinstance(p, str))
+    return ""
+
+
 def _stub_reply(messages: list[dict]) -> str:
     """Cheap deterministic-ish replies keyed off the caller's intent tag."""
-    content = " ".join(m.get("content", "") for m in messages).lower()
+    content = " ".join(_msg_text(m.get("content", "")) for m in messages).lower()
     if "generate" in content and "question" in content:
         return json.dumps([
             {"question": "[stub] What is the main idea of the source text?",

requirements-model.txt

@@ -2,21 +2,47 @@
 # Superset of the light demo set. Install with:
 #     pip install -r requirements-model.txt
 #
-# NOTE for HF deploy: a Gradio Space installs `requirements.txt`, not this file.
-# To serve the real model on the Space, point the Space at these deps (e.g. fold
-# them back into requirements.txt for the model deploy) — see NAH-7.
+# Target: openbmb/MiniCPM-V-4.6 (multimodal, ~9B) to read image-only / scanned
+# PDFs. Aligned with the official Space (openbmb/MiniCPM-V-4.6-Demo), which runs
+# the same custom-frontend gradio.Server + ZeroGPU pattern as this app.
+#
+# DEPLOY (real model on the Space):
+#   * Fold these into requirements.txt for the model deploy (a Gradio Space
+#     installs requirements.txt, not this file) — see NAH-7.
+#   * Switch hardware back to ZeroGPU AND register the inference under @spaces.GPU,
+#     and name the gradio.Server `demo` — a ZeroGPU Space with no @spaces.GPU fn
+#     flips to RUNTIME_ERROR (that's why the stub demo runs on CPU; see server.py).
 -r requirements.txt
-# transformers is pinned to the last 4.x line: MiniCPM4.1-8B's trust_remote_code
-# imports symbols removed in transformers 5.0 (is_torch_fx_available,
-# is_torch_greater_or_equal_than_1_13) while also needing the newer cache API
-# (CacheLayerMixin) — only 4.55–4.57 satisfy both. transformers<5.0 in turn
-# requires huggingface-hub<1.0, which requirements.txt's gradio==6.10.0 allows
-# (hub <2.0,>=0.33.5), whereas gradio 6.18 needs hub>=1.2. gradio 6.10.0 is also
-# the version that runs the custom gradio.Server cleanly on a Space. Resolvable
-# together: gradio 6.10.0 + hub 0.36 + transformers 4.57 + torch 2.12.
-transformers>=4.55,<5.0
+
+# --- transformers / model ---
+# MiniCPM-V 4.6 is a NATIVE transformers architecture
+# (`from transformers import MiniCPMV4_6ForConditionalGeneration`), so it needs a
+# recent transformers (5.x) — NOT the old trust_remote_code path. The official
+# demo declares `transformers>=4.44.0` and relies on latest providing the class.
+#
+# NOTE: this DROPS the previous `transformers<5.0` cap. That cap existed only for
+# the old MiniCPM4.1-8B *text* model (its trust_remote_code broke on 5.x, forcing
+# huggingface-hub<1.0). 4.6 uses new transformers (hub>=1.0), and gradio==6.10.0
+# allows hub<2.0, so gradio 6.10.0 + transformers 5.x + hub 1.x resolve together.
+# Moving to 4.6 therefore RETIRES the old MiniCPM4.1-8B / hub<1.0 constraint.
+transformers>=4.44.0
 torch
+torchvision           # vision tower; must match the installed torch
 accelerate
+sentencepiece         # tokenizer backend the MiniCPM-V processor uses
+
+# --- image + PDF handling ---
+pillow                # images are passed to the model as PIL.Image objects
+# Render image-only / scanned PDF pages -> PIL images to feed the vision model.
+# PyMuPDF is a pure wheel (no poppler/ffmpeg system dep) — works on a Space as-is.
+# (Neither MiniCPM demo does PDFs; this is our addition for image-based PDFs.)
+PyMuPDF
+
+# --- video (OPTIONAL) ---
+# Only needed if you later accept video input. Requires the `ffmpeg` system package
+# (add a packages.txt with `ffmpeg`). Not needed for image-based PDFs, so left out:
+# av
+
 # HF ZeroGPU GPU decorator (effect-free off-Space). Pulls in gradio, so it must
-# resolve against the 6.10.0 pin above — not the latest gradio.
+# resolve against the gradio pin in requirements.txt — not the latest gradio.
 spaces

requirements.txt

@@ -7,15 +7,18 @@
 # the Space build stays fast — nothing heavy is imported at module load in stub mode
 # (llm.py imports torch/transformers only inside _load(); pypdf is imported lazily).
 #
-# gradio is pinned to 6.10.0 on purpose, for TWO reasons:
-#   1. The custom-frontend server (server.py) uses `gradio.Server`. On newer gradio
-#      (6.17.x) a custom gradio.Server breaks under the Space's hot-reloader — the
-#      app starts but the process exits → RUNTIME_ERROR. 6.10.0 is the version
-#      gradio's own ZeroGPU `Server` reference example ships and runs cleanly.
-#   2. Real-model compatibility: 6.10.0 allows huggingface-hub<1.0
-#      (`<2.0,>=0.33.5`), which the real model's transformers<5.0 requires
-#      (MiniCPM trust_remote_code breaks on transformers 5.x). gradio 6.18 would
-#      force hub>=1.2 and break that.
+# gradio is pinned to 6.10.0 because the custom-frontend server (server.py) uses
+# `gradio.Server`. On newer gradio (6.17.x) a custom gradio.Server breaks under the
+# Space runtime — the app starts but the Space flips to RUNTIME_ERROR. 6.10.0 is a
+# version gradio's `Server` examples ship and runs cleanly here. (The official
+# MiniCPM-V-4.6 demo uses 6.14.0 with the same pattern, so 6.10–6.14 is the known-
+# good band; 6.10.0 is what we verified.)
+#
+# It also resolves with the real model: 6.10.0 allows huggingface-hub <2.0,>=0.33.5,
+# i.e. hub 1.x, which MiniCPM-V 4.6's modern transformers (5.x) wants. (The old
+# huggingface-hub<1.0 constraint was specific to the retired MiniCPM4.1-8B text
+# model and no longer applies — see requirements-model.txt.)
+#
 # A gradio-SDK Space force-installs sdk_version's gradio for the WHOLE Space, so
 # stub + real-model share one gradio. Keep this in lockstep with the README
 # `sdk_version` and requirements-model.txt.

test_model_config.py

@@ -19,10 +19,11 @@ def _reload_with(model_env):
     return importlib.reload(llm)
 
 
-def test_default_is_8b():
+def test_default_is_v46():
     llm = _reload_with(None)
-    assert llm.MODEL_ID == "openbmb/MiniCPM4.1-8B"
-    print("ok  default -> MiniCPM4.1-8B")
+    assert llm.MODEL_ID == "openbmb/MiniCPM-V-4.6"
+    assert llm.VISION is True, "default is the multimodal model"
+    print("ok  default -> MiniCPM-V-4.6 (multimodal)")
 
 
 def test_1b_alias():
@@ -40,9 +41,18 @@ def test_4b_alias():
 def test_full_id_passthrough():
     llm = _reload_with("some-org/Custom-Model-7B")
     assert llm.MODEL_ID == "some-org/Custom-Model-7B"
+    assert llm.VISION is False, "a non MiniCPM-V id is not a vision model"
     print("ok  unknown value passed through as a literal HF id")
 
 
+def test_vision_detection():
+    llm = _reload_with("v46")
+    assert llm.MODEL_ID == "openbmb/MiniCPM-V-4.6" and llm.VISION is True
+    llm = _reload_with("8b")
+    assert llm.MODEL_ID == "openbmb/MiniCPM4.1-8B" and llm.VISION is False
+    print("ok  vision detection: -V ids -> VISION, text ids -> not")
+
+
 def test_active_model_reports_stub():
     llm = _reload_with("1b")
     assert llm.active_model() == "stub", "STUB on -> active_model() is 'stub'"
@@ -50,9 +60,10 @@ def test_active_model_reports_stub():
 
 
 if __name__ == "__main__":
-    test_default_is_8b()
+    test_default_is_v46()
     test_1b_alias()
     test_4b_alias()
     test_full_id_passthrough()
+    test_vision_detection()
     test_active_model_reports_stub()
     print("\nAll NAH-9 model-config tests passed.")