ltcai 11.9.0 → 12.0.0

package/latticeai/core/vector_index/sidecar.py

@@ -0,0 +1,329 @@
+"""Load, refresh, and query the HNSW sidecar next to a brain database.
+
+The live graph is cached per ``(db_path, model_id, dim)``. A missing sidecar
+is ``index: "none"``. When the store has vectors the cache (or a rebuild from
+``vector_embeddings``) can serve, the reply is ``index: "hnsw"``. Staleness is
+sidecar size vs ``COUNT(*)`` for that identity — reported honestly, and
+refreshed through :meth:`HnswIndex.add_items` so an ingest append does not
+rebuild the whole graph.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import struct
+import threading
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from latticeai.core.config import default_data_dir
+
+from .hnsw import HnswIndex, hnswlib_available, sidecar_paths
+
+GRAPH_DB_NAME = "knowledge_graph.sqlite"
+VECTOR_QUERY_K_CAP = 200
+
+_CACHE: Dict[Tuple[str, str, int], HnswIndex] = {}
+_LOCK = threading.Lock()
+
+
+def resolve_graph_db(workspace: Optional[str] = None) -> Path:
+    """Brain sqlite path: explicit file, a data dir, or ``LATTICEAI_DATA_DIR``."""
+    if workspace:
+        raw = Path(str(workspace)).expanduser()
+        if raw.is_file():
+            return raw
+        if raw.suffix.lower() == ".sqlite":
+            return raw
+        return raw / GRAPH_DB_NAME
+    return default_data_dir() / GRAPH_DB_NAME
+
+
+def decode_f32le(blob: bytes, dim: int) -> List[float]:
+    """Little-endian f32 payload — the same layout Rust ``encode`` writes."""
+    if not blob:
+        return []
+    count = dim if dim > 0 else len(blob) // 4
+    if len(blob) != count * 4:
+        count = len(blob) // 4
+    if count <= 0:
+        return []
+    return list(struct.unpack(f"<{count}f", blob[: count * 4]))
+
+
+def sidecar_fingerprint(model_id: str, dim: int, size: int) -> str:
+    """Identity the ``.hnsw.meta.json`` file is keyed on."""
+    return f"{model_id}|{int(dim)}|{int(size)}"
+
+
+def store_vector_count(conn: sqlite3.Connection, model_id: str, dim: int) -> int:
+    row = conn.execute(
+        "SELECT COUNT(*) FROM vector_embeddings "
+        "WHERE embedding_model=? AND embedding_dim=?",
+        (model_id, int(dim)),
+    ).fetchone()
+    return int(row[0]) if row else 0
+
+
+def load_store_items(
+    conn: sqlite3.Connection, model_id: str, dim: int
+) -> List[Tuple[str, List[float], Dict[str, Any]]]:
+    items: List[Tuple[str, List[float], Dict[str, Any]]] = []
+    for item_id, blob in conn.execute(
+        "SELECT item_id, embedding FROM vector_embeddings "
+        "WHERE embedding_model=? AND embedding_dim=? ORDER BY indexed_at ASC, item_id ASC",
+        (model_id, int(dim)),
+    ):
+        vector = decode_f32le(bytes(blob or b""), int(dim))
+        if len(vector) != int(dim):
+            continue
+        items.append((str(item_id), vector, {}))
+    return items
+
+
+def sidecar_meta_size(db_path: Path) -> Optional[int]:
+    """Label count from the sidecar meta file, or ``None`` when it is absent."""
+    _, meta_path = sidecar_paths(db_path)
+    try:
+        import json
+
+        meta = json.loads(meta_path.read_text(encoding="utf-8"))
+        labels = meta.get("labels") or []
+        return len(labels)
+    except Exception:  # noqa: BLE001 — absent/corrupt meta is "no sidecar"
+        return None
+
+
+def _open_readonly(db_path: Path) -> Optional[sqlite3.Connection]:
+    if not db_path.is_file():
+        return None
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+    except sqlite3.Error:
+        try:
+            conn = sqlite3.connect(str(db_path))
+        except sqlite3.Error:
+            return None
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def _none_reply(
+    *,
+    size: int = 0,
+    store_size: int = 0,
+    stale: bool = False,
+    detail: Optional[str] = None,
+) -> Dict[str, Any]:
+    return {
+        "ids": [],
+        "scores": [],
+        "index": "none",
+        "size": int(size),
+        "store_size": int(store_size),
+        "stale": bool(stale),
+        "detail": detail,
+        "refreshed": None,
+    }
+
+
+def _hnsw_reply(
+    ids: Sequence[str],
+    scores: Sequence[float],
+    *,
+    size: int,
+    store_size: int,
+    stale: bool,
+    detail: Optional[str],
+    refreshed: Optional[str],
+) -> Dict[str, Any]:
+    return {
+        "ids": [str(item) for item in ids],
+        "scores": [float(score) for score in scores],
+        "index": "hnsw",
+        "size": int(size),
+        "store_size": int(store_size),
+        "stale": bool(stale),
+        "detail": detail,
+        "refreshed": refreshed,
+    }
+
+
+def _refresh_index(
+    index: HnswIndex,
+    items: Sequence[Tuple[str, List[float], Dict[str, Any]]],
+    model_id: str,
+    dim: int,
+) -> str:
+    return index.add_items(items, dim=dim, model_id=model_id)
+
+
+def query_sidecar(
+    *,
+    workspace: Optional[str],
+    embedding_model: str,
+    embedding_dim: int,
+    vector: Sequence[float],
+    k: int,
+    db_path: Optional[Path] = None,
+) -> Dict[str, Any]:
+    """Serve one ANN query from the sidecar (or say the index is absent)."""
+    dim = int(embedding_dim)
+    model_id = str(embedding_model or "")
+    wanted = max(1, min(int(k), VECTOR_QUERY_K_CAP))
+    path = Path(db_path) if db_path is not None else resolve_graph_db(workspace)
+    if not hnswlib_available():
+        return _none_reply(detail="hnswlib is not available in this worker")
+    if dim <= 0 or len(vector) != dim:
+        return _none_reply(
+            detail=(
+                f"query vector width {len(vector)} does not match embedding_dim {dim}"
+                if dim > 0
+                else "embedding_dim must be a positive integer"
+            )
+        )
+    if not model_id:
+        return _none_reply(detail="embedding_model is required")
+
+    conn = _open_readonly(path)
+    store_size = 0
+    items: List[Tuple[str, List[float], Dict[str, Any]]] = []
+    if conn is not None:
+        try:
+            store_size = store_vector_count(conn, model_id, dim)
+            if store_size > 0:
+                items = load_store_items(conn, model_id, dim)
+                store_size = len(items)
+        finally:
+            conn.close()
+
+    key = (str(path), model_id, dim)
+    with _LOCK:
+        index = _CACHE.get(key)
+        refreshed: Optional[str] = None
+        if index is None:
+            index = HnswIndex(dim=dim, model_id=model_id)
+            loaded = index.load(path, fingerprint=sidecar_fingerprint(model_id, dim, store_size))
+            if not loaded:
+                if not items:
+                    return _none_reply(
+                        store_size=store_size,
+                        detail="no HNSW sidecar for this embedding identity",
+                    )
+                refreshed = _refresh_index(index, items, model_id, dim)
+                index.save(path, fingerprint=sidecar_fingerprint(model_id, dim, len(items)))
+            _CACHE[key] = index
+
+        cached_size = int(index.stats().get("size") or 0)
+        stale = cached_size != store_size
+        if stale:
+            if not items and store_size > 0:
+                conn = _open_readonly(path)
+                if conn is not None:
+                    try:
+                        items = load_store_items(conn, model_id, dim)
+                    finally:
+                        conn.close()
+            if items:
+                refreshed = _refresh_index(index, items, model_id, dim)
+                index.save(path, fingerprint=sidecar_fingerprint(model_id, dim, len(items)))
+                cached_size = int(index.stats().get("size") or 0)
+                stale = cached_size != len(items)
+            elif store_size == 0:
+                _CACHE.pop(key, None)
+                return _none_reply(
+                    store_size=0,
+                    detail="vector store is empty for this embedding identity",
+                )
+
+        if cached_size <= 0:
+            return _none_reply(
+                store_size=store_size,
+                stale=stale,
+                detail="HNSW sidecar has no labels for this identity",
+            )
+
+        index._ef_search = max(index._ef_search, wanted * 2, 200)
+        hits = index.search(list(vector), top_k=min(wanted, cached_size))
+        ids = [item_id for item_id, _ in hits]
+        scores = [score for _, score in hits]
+        detail = None
+        if stale:
+            detail = (
+                f"sidecar size {cached_size} != store count {store_size} "
+                "for this embedding identity"
+            )
+        return _hnsw_reply(
+            ids,
+            scores,
+            size=cached_size,
+            store_size=store_size,
+            stale=stale,
+            detail=detail,
+            refreshed=refreshed,
+        )
+
+
+def sidecar_freshness(
+    *,
+    workspace: Optional[str] = None,
+    embedding_model: Optional[str] = None,
+    embedding_dim: Optional[int] = None,
+    db_path: Optional[Path] = None,
+) -> Dict[str, Any]:
+    """Cheap on-disk vs store comparison — no ANN query, no rebuild."""
+    path = Path(db_path) if db_path is not None else resolve_graph_db(workspace)
+    meta_size = sidecar_meta_size(path)
+    store_size = 0
+    conn = _open_readonly(path)
+    if conn is not None:
+        try:
+            if embedding_model and embedding_dim:
+                store_size = store_vector_count(conn, embedding_model, int(embedding_dim))
+            else:
+                row = conn.execute("SELECT COUNT(*) FROM vector_embeddings").fetchone()
+                store_size = int(row[0]) if row else 0
+        except sqlite3.Error:
+            store_size = 0
+        finally:
+            conn.close()
+    if meta_size is None:
+        return {
+            "index": "none",
+            "size": 0,
+            "store_size": store_size,
+            "stale": store_size > 0,
+            "detail": "no HNSW sidecar next to the brain database",
+        }
+    stale = meta_size != store_size
+    return {
+        "index": "hnsw",
+        "size": meta_size,
+        "store_size": store_size,
+        "stale": stale,
+        "detail": (
+            f"sidecar size {meta_size} != store count {store_size}"
+            if stale
+            else "sidecar matches the vector store"
+        ),
+    }
+
+
+def reset_sidecar_cache() -> None:
+    """Drop the process cache — tests only."""
+    with _LOCK:
+        _CACHE.clear()
+
+
+__all__ = [
+    "GRAPH_DB_NAME",
+    "VECTOR_QUERY_K_CAP",
+    "decode_f32le",
+    "query_sidecar",
+    "reset_sidecar_cache",
+    "resolve_graph_db",
+    "sidecar_fingerprint",
+    "sidecar_freshness",
+    "sidecar_meta_size",
+    "store_vector_count",
+]

package/latticeai/models/router/generation.py

@@ -18,9 +18,57 @@ from latticeai.core.quiet import quiet
 
 from ._contract import RouterCore as _Core
 from .branding import SYSTEM_PROMPT, _compose_system, normalize_branding
+
+
+def _system_for(context, cite_sources: bool) -> str:
+    """The system prompt for one completion.
+
+    ``cite_sources`` is what tells the two kinds of **caller** apart, and
+    v12.0.0 added it because nothing did.
+
+    A *chat* caller sends retrieved passages, and gets this product's own
+    system prompt with the Context block and
+    :data:`~latticeai.models.router.branding.CITATION_INSTRUCTION` appended.
+    :func:`_compose_system` used to do that for any non-empty context, which is
+    right there and wrong for the agent seam, whose context is the loop's own
+    executor prompt: every agent turn was being told its instructions were
+    "retrieved sources" to "cite inline as [1], [2]". A large model ignores
+    that. A small one obeys it — the acid-test 0.5B wrote
+    ``[1] 인사말을 쓸 예시 코드: …`` into a file, and a 2B answered a tool call
+    with the citation instruction itself.
+
+    A *worker* caller sends **its own whole prompt**, and gets exactly that.
+    Same fact, one flag: a context that is not a corpus is an instruction, and
+    an instruction the caller wrote is the only instruction that turn should
+    carry. Until now the chat persona was still prepended to it, so six lines
+    of "You are Lattice AI … You are a Vision-Language Model … Be concise" sat
+    in front of every guided micro-turn — including the one that asks a model to
+    write a file's contents. Small models answer the nearest instruction: a live
+    2B asked to summarise a README wrote "I am a local AI assistant that can run
+    on Apple Silicon" into the file, and a gemma-4-e2b opened two of its three
+    files with "Identity: Lattice AI (Vision-Language Model on Apple Silicon)".
+    Nothing leaked verbatim; the *subject* leaked, which is the same defect one
+    paraphrase further on. The document path has always worked this way — its
+    own system prompt replaces the chat identity entirely — so this is the
+    existing rule reaching the second caller that has a prompt of its own.
+
+    Both agent prompts still say who they are (``You are the executor of an
+    agent loop``) and every guided block still carries the run's own answer
+    language, so nothing the loop depends on is being removed — only a second,
+    competing identity. Branding normalisation is untouched: it runs over the
+    context here and over every generated string on the way out.
+
+    A worker call with **no** context still gets the product prompt. A bare
+    completion carrying no instruction at all is the one case where the identity
+    is the only thing there is to say.
+    """
+    context = normalize_branding(context)
+    if cite_sources:
+        return _compose_system(SYSTEM_PROMPT, context)
+    return context or SYSTEM_PROMPT
 from .catalog import CloudModel
 from .errors import ModelStreamError, _stream_failure
-from .loading import _mlx_sampler, apply_stop_strings, executor
+from .loading import _mlx_sampler, apply_prefix, apply_stop_strings, executor
 
 
 def _stream_until_stop(
@@ -65,9 +113,10 @@ def _stream_until_stop(
 class _GenerationMixin(_Core):
     """The chat generation half of :class:`LLMRouter`."""
 
-    def _build_prompt(self, message: str, context: Optional[str], tokenizer) -> str:
-        context = normalize_branding(context)
-        system = _compose_system(SYSTEM_PROMPT, context)
+    def _build_prompt(
+        self, message: str, context: Optional[str], tokenizer, cite_sources: bool = True
+    ) -> str:
+        system = _system_for(context, cite_sources)
         if hasattr(tokenizer, "apply_chat_template"):
             try:
                 msgs = [{"role": "system", "content": system}, {"role": "user", "content": message}]
@@ -76,9 +125,8 @@ class _GenerationMixin(_Core):
                 quiet()
         return f"<|im_start|>system\n{system}<|im_end|>\n<|im_start|>user\n{message}<|im_end|>\n<|im_start|>assistant\n"
 
-    def _build_vlm_prompt(self, model, processor, message: str, context: Optional[str], num_images: int) -> str:
-        context = normalize_branding(context)
-        system = _compose_system(SYSTEM_PROMPT, context)
+    def _build_vlm_prompt(self, model, processor, message: str, context: Optional[str], num_images: int, cite_sources: bool = True) -> str:
+        system = _system_for(context, cite_sources)
         try:
             from mlx_vlm import apply_chat_template
 
@@ -94,7 +142,7 @@ class _GenerationMixin(_Core):
             )
         except Exception as e:
             print(f"⚠️ VLM chat template fallback: {e}")
-            return self._build_prompt(message, context, processor)
+            return self._build_prompt(message, context, processor, cite_sources)
 
     async def generate_as(
         self,
@@ -105,6 +153,8 @@ class _GenerationMixin(_Core):
         temperature: float = 0.2,
         image_data: Optional[str] = None,
         stop: Optional[List[str]] = None,
+        prefix: Optional[str] = None,
+        cite_sources: bool = True,
     ) -> str:
         """Generate with a request-scoped model without changing the default.
 
@@ -113,12 +163,23 @@ class _GenerationMixin(_Core):
         after the stop are never produced rather than merely trimmed; the cloud
         path forwards the list to the provider, which stops server-side. Absent
         or empty means what it always meant — generate to ``max_tokens``.
+
+        ``prefix`` **starts** the reply (v12.0.0): the characters are put in the
+        model's mouth rather than requested of it, so a caller that needs the
+        answer to begin ``{"thoughts": "`` gets that by construction instead of
+        by asking nicely and repairing the result. Locally this is a real
+        prefill — the text is appended to the templated prompt after the
+        generation marker, so the model continues from mid-token rather than
+        starting a fresh turn. The returned text always begins with it; see
+        :func:`~latticeai.models.router.loading.apply_prefix` for how the three
+        backends are reconciled.
         """
         _selected, cached = self._model_snapshot(model_id)
         if cached is None:
             return "No model."
         return await self._generate_cached(
-            cached, message, context, max_tokens, temperature, image_data, stop
+            cached, message, context, max_tokens, temperature, image_data, stop, prefix,
+            cite_sources,
         )
 
     async def generate(
@@ -129,9 +190,12 @@ class _GenerationMixin(_Core):
         temperature: float = 0.2,
         image_data: Optional[str] = None,
         stop: Optional[List[str]] = None,
+        prefix: Optional[str] = None,
+        cite_sources: bool = True,
     ) -> str:
         return await self.generate_as(
-            None, message, context, max_tokens, temperature, image_data, stop
+            None, message, context, max_tokens, temperature, image_data, stop, prefix,
+            cite_sources,
         )
 
     async def _generate_cached(
@@ -143,19 +207,28 @@ class _GenerationMixin(_Core):
         temperature: float,
         image_data: Optional[str],
         stop: Optional[List[str]] = None,
+        prefix: Optional[str] = None,
+        cite_sources: bool = True,
     ) -> str:
         if isinstance(cached, CloudModel):
             return await self._cloud_generate(
-                cached, message, context, max_tokens, temperature, stop
+                cached, message, context, max_tokens, temperature, stop, prefix, cite_sources
             )
 
         model, tokenizer, draft_model, loader_kind = self._unpack_local_cache(cached)
         use_vlm = loader_kind == "mlx_vlm"
         prompt = (
-            self._build_vlm_prompt(model, tokenizer, message, context, 1 if image_data else 0)
+            self._build_vlm_prompt(
+                model, tokenizer, message, context, 1 if image_data else 0, cite_sources
+            )
             if use_vlm
-            else self._build_prompt(message, context, tokenizer)
+            else self._build_prompt(message, context, tokenizer, cite_sources)
         )
+        # The prefill. Appended *after* the chat template's generation marker,
+        # so the first sampled token continues these characters instead of
+        # opening a reply. Nothing else in the pipeline changes.
+        if prefix:
+            prompt = f"{prompt}{prefix}"
         stops = [marker for marker in (stop or []) if marker]
 
         loop = asyncio.get_event_loop()
@@ -181,27 +254,33 @@ class _GenerationMixin(_Core):
         result = await loop.run_in_executor(executor, _gen)
         # mlx-vlm might return a GenerationResult object; extract the text
         text = result.text if hasattr(result, "text") else str(result)
-        return normalize_branding(apply_stop_strings(text, stops))
+        return apply_prefix(prefix, normalize_branding(apply_stop_strings(text, stops)))
 
-    async def _cloud_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float, stop: Optional[List[str]] = None) -> str:
-        context = normalize_branding(context)
-        system = _compose_system(SYSTEM_PROMPT, context)
+    async def _cloud_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float, stop: Optional[List[str]] = None, prefix: Optional[str] = None, cite_sources: bool = True) -> str:
+        system = _system_for(context, cite_sources)
         stops = [marker for marker in (stop or []) if marker]
         extra = {"stop": stops} if stops else {}
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": message},
+        ]
+        # Assistant prefill: the OpenAI-compatible way to say "continue this".
+        # Local servers (vLLM, llama.cpp, LM Studio, Ollama) honour it; a
+        # provider that does not simply reads it as context, and `apply_prefix`
+        # makes both answers the same shape for the caller.
+        if prefix:
+            messages.append({"role": "assistant", "content": prefix})
         try:
             response = await cloud.client.chat.completions.create(
                 model=cloud.model,
-                messages=[
-                    {"role": "system", "content": system},
-                    {"role": "user", "content": message},
-                ],
+                messages=messages,
                 max_tokens=max_tokens,
                 temperature=temperature,
                 **extra,
             )
         except Exception as e:
             raise RuntimeError(self._local_server_error_hint(cloud, e)) from e
-        return normalize_branding(response.choices[0].message.content or "")
+        return apply_prefix(prefix, normalize_branding(response.choices[0].message.content or ""))
 
     async def stream_generate_as(
         self,

package/latticeai/models/router/loading.py

@@ -148,6 +148,104 @@ def _mlx_sampler(temperature: float):
         return None
 
 
+def _declares_vision(model_id: str) -> bool:
+    """Whether this checkpoint's own config says it is multimodal.
+
+    Read from ``config.json`` rather than decided from the model's *name*: a
+    list of known vision families is a list that is wrong about every model
+    published after it was written, and "which models work" is exactly the
+    question this product must not answer with a hardcoded roster.
+
+    The three markers are the ones every MLX-VLM architecture carries — a
+    nested ``vision_config``, a ``vision_tower``, or an ``image_token_index``
+    for the placeholder the processor substitutes. A config that carries none
+    of them describes a text model.
+    """
+    import json as _json
+    from pathlib import Path as _Path
+
+    from .local_models import hf_model_dir
+
+    raw = str(model_id or "").strip()
+    candidates = []
+    explicit = _Path(raw).expanduser()
+    if raw and explicit.exists():
+        candidates.append(explicit / "config.json")
+    try:
+        candidates.append(hf_model_dir(raw) / "config.json")
+    except Exception as error:  # noqa: BLE001 — an unresolvable id is not a claim
+        quiet(f"vision probe skipped for {raw}: {error}")
+    for config_path in candidates:
+        try:
+            if not config_path.exists():
+                continue
+            data = _json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception as error:  # noqa: BLE001 — an unreadable config is not a claim
+            quiet(f"vision probe skipped for {config_path}: {error}")
+            continue
+        if any(key in data for key in ("vision_config", "vision_tower", "image_token_index")):
+            return True
+    return False
+
+
+def _text_fallback_allowed(
+    model_id: str, target_model_id: str, model_type: Optional[str]
+) -> bool:
+    """Whether a failed multimodal load may be retried as a text load.
+
+    Every local model is routed to MLX-VLM first, because the recommended
+    defaults are multimodal. Until v12.0.0 the retry on the text path was
+    gated on the model *id* matching Gemma 4 — so a plain text model MLX-VLM
+    cannot open (a 0.5B Qwen, an AWQ checkpoint, any fine-tune with a text-only
+    architecture) failed to load at all, with MLX-LM sitting right there able
+    to open it. That is a roster deciding what runs, and the roster was one
+    family long. "Every small model works" cannot be true while loading is
+    gated on a name.
+
+    So the rule is now two rules, and the second is **additive**:
+
+    * the v11.9.0 Gemma 4 rule, unchanged — a Gemma 4 that is not the unified
+      (vision) architecture may always retry as text;
+    * and, new, **any model whose own ``config.json`` does not declare
+      vision.** Read from the checkpoint rather than decided from the name, so
+      a model published tomorrow is judged the same way as one published last
+      year.
+
+    A config that *does* declare vision is never silently downgraded: answering
+    an image request from a text-only load is worse than refusing it.
+    """
+    if lm_load is None:
+        return False
+    if (model_type or "").strip().lower() == "gemma4_unified":
+        return False
+    if _is_gemma4_model_id(model_id):
+        return True
+    return not _declares_vision(target_model_id)
+
+
+def apply_prefix(prefix: Optional[str], text: str) -> str:
+    """Guarantee ``text`` begins with ``prefix``, without doubling it.
+
+    The seam's contract for a forced prefix (v12.0.0) is one sentence: *the
+    reply starts with these characters*. How it got there differs by backend —
+    the local path really does prefill the prompt with them, so the model never
+    generated them and they have to be put back; a cloud provider handed an
+    assistant prefill message may echo them, may not, and may ignore the
+    message entirely. One normalisation covers all three, so the caller parses
+    one shape whichever answered.
+
+    Leading whitespace is dropped when the reply already carries the prefix:
+    a chat template that emits ``"\\n"`` before the continuation would otherwise
+    make ``startswith`` false for a reply that plainly does start with it.
+    """
+    if not prefix:
+        return text
+    stripped = text.lstrip()
+    if stripped.startswith(prefix):
+        return stripped
+    return f"{prefix}{text}"
+
+
 def apply_stop_strings(text: str, stop: Optional[List[str]]) -> str:
     """Cut ``text`` at the earliest stop string, if any is present.
 
@@ -206,7 +304,6 @@ class _LoadingMixin(_Core):
         
         def _load():
             mx.set_default_device(mx.gpu)
-            is_gemma4 = _is_gemma4_model_id(model_id)
             model_type = _local_model_type(target_model_id) or _local_model_type(model_id)
             loader_kind = "mlx_vlm"
 
@@ -216,11 +313,19 @@ class _LoadingMixin(_Core):
                 print(f"🔄 Loading Target (VLM Mode): {target_model_id}...")
                 model, tokenizer = vlm_load(target_model_id)
             except Exception as vlm_error:
-                if not (is_gemma4 and model_type != "gemma4_unified" and lm_load is not None):
+                if not _text_fallback_allowed(model_id, target_model_id, model_type):
                     raise
-                print(f"⚠️ Gemma 4 MLX-VLM load failed; retrying MLX-LM text path: {vlm_error}")
+                print(f"⚠️ MLX-VLM load failed; retrying the MLX-LM text path: {vlm_error}")
                 print(f"🔄 Loading Target (LM Mode): {target_model_id}...")
-                model, tokenizer = lm_load(target_model_id)
+                try:
+                    model, tokenizer = lm_load(target_model_id)
+                except Exception:
+                    # The text path is a *fallback*: when it fails too, the
+                    # useful diagnosis is the first failure, from the loader
+                    # this model was routed to. Raising the second one would
+                    # tell an operator their multimodal model is not a text
+                    # model, which they knew.
+                    raise vlm_error from None
                 loader_kind = "mlx_lm"
 
             draft_model = None