ltcai 11.0.1 → 11.2.0

package/latticeai/services/model_catalog.py

@@ -94,64 +94,83 @@ _RAW_ENGINE_MODEL_CATALOG: Dict[str, List[Dict[str, Any]]] = _build_engine_model
 # are all defined; declared here so the public name exists for static readers.
 ENGINE_MODEL_CATALOG: Dict[str, List[Dict[str, Any]]] = {}
 
-# Historical aliases preserved (used by _recommended_with_engine_options and resolution).
-# These can be enriched later from registry if needed; kept verbatim for safety.
-MODEL_ENGINE_ALIASES = {
-    "gemma-4-12b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-12b-it-4bit",
-        "ollama": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
-        "vllm": "google/gemma-4-12b-it",
-        "lmstudio": "ggml-org/gemma-4-12B-it-GGUF",
-        "llamacpp": "ggml-org/gemma-4-12B-it-GGUF",
-    },
-    "mlx-community/gemma-4-12b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-12b-it-4bit",
-        "ollama": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
-        "vllm": "google/gemma-4-12b-it",
-        "lmstudio": "ggml-org/gemma-4-12B-it-GGUF",
-        "llamacpp": "ggml-org/gemma-4-12B-it-GGUF",
-    },
-    "gemma-4-26b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-26b-a4b-it-4bit",
-    },
-    "mlx-community/gemma-4-26b-a4b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-26b-a4b-it-4bit",
-    },
-    "gemma-4-31b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-31b-it-4bit",
-        "ollama": "hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M",
-        "vllm": "suitch/gemma-4-31B-it-4bit",
-        "lmstudio": "ggml-org/gemma-4-31B-it-GGUF",
-        "llamacpp": "ggml-org/gemma-4-31B-it-GGUF",
-    },
-    "suitch/gemma-4-31b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-31b-it-4bit",
-        "ollama": "hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M",
-        "vllm": "suitch/gemma-4-31B-it-4bit",
-        "lmstudio": "ggml-org/gemma-4-31B-it-GGUF",
-        "llamacpp": "ggml-org/gemma-4-31B-it-GGUF",
-    },
-    "mlx-community/gemma-4-31b-it-4bit": {
-        "local_mlx": "mlx-community/gemma-4-31b-it-4bit",
-        "ollama": "hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M",
-        "vllm": "suitch/gemma-4-31B-it-4bit",
-        "lmstudio": "ggml-org/gemma-4-31B-it-GGUF",
-        "llamacpp": "ggml-org/gemma-4-31B-it-GGUF",
+# Per-engine repo ids for the recommended catalog. Every repo below was resolved
+# through the HF API on 2026-08-10 and is stored in the Hub's canonical casing
+# (`google/gemma-4-12b-it` answers as `google/gemma-4-12B-it`; `ggml-org/
+# gemma-4-26b-a4b-it-GGUF` answers as `ggml-org/gemma-4-26B-A4B-it-GGUF`).
+# Lookups are lowercase, so each model is keyed by both its short name and its
+# full mlx repo id — see `_normalize_engine_entry` and `ModelResolution`.
+#
+# Removed in 11.2.0: `qwen3-vl-8b` and `llama-4-scout`. Their vllm/lmstudio
+# targets pointed at `meta-llama/Llama-4-Scout-17B-16E-Instruct`, which is
+# gated — the download could never succeed without Hub credentials.
+
+
+def _gguf_routes(mlx_repo: str, gguf_repo: str, hf_repo: str) -> Dict[str, str]:
+    """One model's engine map: MLX weights, a GGUF repo, and the upstream HF repo."""
+    return {
+        "local_mlx": mlx_repo,
+        "ollama": f"hf.co/{gguf_repo}:Q4_K_M",
+        "vllm": hf_repo,
+        "lmstudio": gguf_repo,
+        "llamacpp": gguf_repo,
+    }
+
+
+_ENGINE_ROUTES: Dict[str, Dict[str, str]] = {
+    "mlx-community/LFM2.5-2.6B-4bit": _gguf_routes(
+        "mlx-community/LFM2.5-2.6B-4bit", "LiquidAI/LFM2.5-2.6B-GGUF", "LiquidAI/LFM2.5-2.6B",
+    ),
+    "mlx-community/gemma-4-e2b-it-4bit": _gguf_routes(
+        "mlx-community/gemma-4-e2b-it-4bit", "ggml-org/gemma-4-E2B-it-GGUF", "google/gemma-4-E2B-it",
+    ),
+    "mlx-community/gemma-4-e4b-it-4bit": _gguf_routes(
+        "mlx-community/gemma-4-e4b-it-4bit", "ggml-org/gemma-4-E4B-it-GGUF", "google/gemma-4-E4B-it",
+    ),
+    "mlx-community/gemma-4-12B-it-4bit": _gguf_routes(
+        "mlx-community/gemma-4-12B-it-4bit", "ggml-org/gemma-4-12B-it-GGUF", "google/gemma-4-12B-it",
+    ),
+    "mlx-community/gemma-4-26b-a4b-it-4bit": _gguf_routes(
+        "mlx-community/gemma-4-26b-a4b-it-4bit", "ggml-org/gemma-4-26B-A4B-it-GGUF",
+        "google/gemma-4-26B-A4B-it",
+    ),
+    "mlx-community/gemma-4-31b-it-4bit": _gguf_routes(
+        "mlx-community/gemma-4-31b-it-4bit", "ggml-org/gemma-4-31B-it-GGUF", "google/gemma-4-31B-it",
+    ),
+    "mlx-community/Qwen3.6-27B-4bit": _gguf_routes(
+        "mlx-community/Qwen3.6-27B-4bit", "ggml-org/Qwen3.6-27B-GGUF", "Qwen/Qwen3.6-27B",
+    ),
+    "mlx-community/gpt-oss-20b-MXFP4-Q8": _gguf_routes(
+        "mlx-community/gpt-oss-20b-MXFP4-Q8", "ggml-org/gpt-oss-20b-GGUF", "openai/gpt-oss-20b",
+    ),
+    # No community GGUF build verified for these two, so they offer the MLX
+    # weights and the upstream repo only rather than a route that would 404.
+    "mlx-community/Qwen3.5-9B-MLX-4bit": {
+        "local_mlx": "mlx-community/Qwen3.5-9B-MLX-4bit",
+        "vllm": "Qwen/Qwen3.5-9B",
     },
-    "qwen3-vl-8b": {
-        "local_mlx": "mlx-community/Qwen3-VL-8B-Instruct-4bit",
-        "ollama": "qwen3-vl:8b",
-        "vllm": "Qwen/Qwen3-VL-8B-Instruct",
-        "lmstudio": "Qwen/Qwen3-VL-8B-Instruct",
-        "llamacpp": "Qwen/Qwen3-VL-8B-Instruct-GGUF",
+    "mlx-community/Qwen3.6-35B-A3B-4bit": {
+        "local_mlx": "mlx-community/Qwen3.6-35B-A3B-4bit",
+        "vllm": "Qwen/Qwen3.6-35B-A3B",
     },
-    "llama-4-scout": {
-        "local_mlx": "mlx-community/Llama-4-Scout-17B-16E-Instruct-4bit",
-        "ollama": "hf.co/ggml-org/Llama-4-Scout-17B-16E-Instruct-GGUF:Q4_K_M",
-        "vllm": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
-        "lmstudio": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
-        "llamacpp": "ggml-org/Llama-4-Scout-17B-16E-Instruct-GGUF",
+}
+
+# Names people actually type that are not the repo's own short name. Kept
+# because a user who asks for "gemma-4-26b-it-4bit" means the A4B build — there
+# is no other Gemma 4 26B — and resolving that to nothing would be pedantry.
+_COMMON_MISNAMES: Dict[str, str] = {
+    "gemma-4-26b-it-4bit": "mlx-community/gemma-4-26b-a4b-it-4bit",
+}
+
+# Keyed by both the lowercase short name ("gemma-4-12b-it-4bit") and the
+# lowercase full repo id, because callers reach this map from both directions.
+MODEL_ENGINE_ALIASES: Dict[str, Dict[str, str]] = {
+    **{
+        key: routes
+        for repo, routes in _ENGINE_ROUTES.items()
+        for key in (repo.split("/")[-1].lower(), repo.lower())
     },
+    **{alias: _ENGINE_ROUTES[repo] for alias, repo in _COMMON_MISNAMES.items()},
 }
 
 # Also expose registry helpers directly from here for consumers who want the rich objects
@@ -181,7 +200,14 @@ def _model_family_version(model: Dict[str, Any]) -> Optional[tuple[str, tuple[in
             # Every pattern captures at least one decimal digit and no other
             # character but ``.``, so the parsed tuple is never empty — the
             # old ``if version:`` guard could not fire and is gone.
-            return family, _version_tuple(match.group(1))
+            #
+            # Compared at *major* granularity only (``[:1]``). The filter exists
+            # to hide superseded generations — Qwen 2.5 behind Qwen 3, Gemma 3
+            # behind Gemma 4 — not to pick a winner inside one generation.
+            # Comparing minors made Qwen3.5 9B (the mid VLM) vanish the moment
+            # Qwen3.6 27B joined the catalog, even though they fill different
+            # RAM tiers and ship side by side.
+            return family, _version_tuple(match.group(1))[:1]
     return None
 
 
@@ -202,16 +228,24 @@ def filter_lower_family_versions(models: List[Dict[str, Any]]) -> List[Dict[str,
     ]
 
 
-# ── 5.2.0 user-facing catalog assembly ────────────────────────────────────────
-# Legacy/text-only generations stay in the capability registry (for transparency
-# and HF verification) but must never be surfaced in the model picker. Anything
-# whose id contains one of these fragments is dropped from ENGINE_MODEL_CATALOG.
+# ── User-facing catalog assembly ──────────────────────────────────────────────
+# The capability registry already keeps superseded generations out of the
+# catalog by lifecycle (they live in its LEGACY list, recognised but never
+# offered). This blocklist is the second lock: a regression guard so a retired
+# generation cannot creep back into the model picker through a hand-edited
+# entry. Anything whose id contains one of these fragments is dropped from
+# ENGINE_MODEL_CATALOG.
+#
+# 11.2.0 removed ``gpt-oss`` from this list — GPT-OSS 20B is now a recommended
+# entry, not a retired one — and added the generations retired this release.
 _BLOCKED_CATALOG_FRAGMENTS = (
     "gemma-3", "gemma3", "gemma-2", "gemma2",
     "qwen2.5", "qwen-2.5", "qwen2-5",
+    "qwen3-vl", "qwen3vl",
     "llama-3", "llama3.2", "llama-3.2",
+    "llama-4", "llama4",
     "pixtral", "mistral",
-    "smollm", "gpt-oss", "phi-",
+    "smollm", "phi-", "moondream",
 )
 
 

package/latticeai/services/model_recommendation.py

@@ -3,8 +3,8 @@
 Given a detected system profile (from :func:`auto_setup.probe`) this module
 classifies every model in :data:`model_catalog.ENGINE_MODEL_CATALOG` into one of
 three states — **recommended**, **compatible**, or **not_recommended** — and
-groups the result by current multimodal model family (Gemma 4, Qwen3-VL,
-Llama 4).
+groups the result by current model family (Gemma 4, Qwen3.6, Qwen3.5, GPT-OSS,
+LFM2.5).
 
 It is intentionally pure and dependency-light: the only input is a plain dict
 describing the machine, so it is fully unit-testable without touching real
@@ -30,18 +30,25 @@ NOT_RECOMMENDED = "not_recommended"
 # Apple-Silicon only.  Used to decide platform availability before sizing.
 _APPLE_ONLY_ENGINES = {"local_mlx"}
 
-# Family display order for the grouped view (newest multimodal generations first).
+# Family display order for the grouped view (current generations, largest
+# lineup first). Superseded families are not listed because the capability
+# registry never lets them reach the catalog — they are recognised for loading
+# only. A family missing from this list still renders, it just sorts last.
 _FAMILY_ORDER = [
     "Gemma 4",
-    "Qwen3-VL",
-    "Qwen2.5-VL",
-    "Llama 4",
-    "Llama 3.2 Vision",
-    "Phi Vision",
-    "Moondream",
-    "Pixtral",
+    "Qwen3.6",
+    "Qwen3.5",
+    "GPT-OSS",
+    "LFM2.5",
 ]
 
+# Modalities the recommender will surface. Text-only models earn their place —
+# LFM2.5 is the only thing that runs comfortably on 8GB, and GPT-OSS 20B is the
+# most-downloaded entry in the catalog — so filtering to `multimodal` would have
+# hidden two of the tiers. Each row still reports its own `modality`, so a UI
+# that wants to badge "reads pictures" can, honestly.
+_RECOMMENDABLE_MODALITIES = {"multimodal", "text"}
+
 _SIZE_RE = re.compile(r"([\d.]+)\s*(TB|GB|MB)", re.IGNORECASE)
 _UNIT_GB = {"TB": 1024.0, "GB": 1.0, "MB": 1.0 / 1024.0}
 
@@ -165,7 +172,7 @@ def recommend_catalog(profile: Dict[str, Any], *, engine: str = "local_mlx") ->
     """
     models = [
         model for model in ENGINE_MODEL_CATALOG.get(engine, [])
-        if str(model.get("modality") or "").lower() == "multimodal"
+        if str(model.get("modality") or "").lower() in _RECOMMENDABLE_MODALITIES
     ]
     engine_available = _engine_available(engine, profile)
     ram_gb = _ram_gb(profile)

package/latticeai/services/model_runtime.py

@@ -138,7 +138,7 @@ class ModelRuntimeState:
     ALLOW_PLAINTEXT_API_KEYS: bool = False
     CORS_ALLOW_NETWORK: bool = False
     PUBLIC_MODEL: str = "openai:gpt-4o-mini"
-    LOCAL_MODEL: str = "mlx-community/gemma-4-12b-it-4bit"
+    LOCAL_MODEL: str = "mlx-community/gemma-4-12B-it-4bit"
     IS_PUBLIC_MODE: bool = False
     keyring: Any = None
     get_current_user: Callable[[Any], Optional[str]] = _missing_current_user

package/latticeai/services/multimodal_ports.py

@@ -0,0 +1,112 @@
+"""Where the app decides what it can actually see and hear (v11.1.0).
+
+Brain Core owns the *shape* of a multi-modal memory; it deliberately owns none
+of the models. This module is the one place that turns configuration into the
+plain callables :class:`lattice_brain.multimodal.MultimodalPorts` accepts, so
+the ingestion pipeline never learns that ``latticeai`` exists.
+
+Everything here is off by default and costs nothing when off: with no vision
+provider configured, :func:`build_multimodal_ports` does no model loading, no
+imports of optional packages, and no network calls — it returns a bundle whose
+every capability is honestly ``None``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Dict, List, Optional
+
+from lattice_brain.ingestion import ALLOW_MULTIMODAL_ENV
+from lattice_brain.multimodal import MODALITY_IMAGE, MultimodalPorts
+from latticeai.core.embedding_providers import (
+    VISION_CAPTION_TARGET_ENV,
+    resolve_vision_captioner,
+    resolve_vision_embedder,
+    vision_caption_port,
+)
+
+#: ``mlx`` | ``custom`` | "" (off). Never defaulted to something that loads.
+VISION_PROVIDER_ENV = "LATTICEAI_VISION_PROVIDER"
+VISION_MODEL_ENV = "LATTICEAI_VISION_MODEL"
+#: ``image`` (own index + late fusion) or ``shared`` (same space as text).
+VISION_SPACE_ENV = "LATTICEAI_VISION_SPACE"
+VISION_CAPTION_PROVIDER_ENV = "LATTICEAI_VISION_CAPTION_PROVIDER"
+VISION_CAPTION_MODEL_ENV = "LATTICEAI_VISION_CAPTION_MODEL"
+
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def multimodal_enabled() -> bool:
+    """Whether pictures and recordings may be ingested at all (default no)."""
+    return os.getenv(ALLOW_MULTIMODAL_ENV, "0").strip().lower() in _TRUE
+
+
+def build_multimodal_ports(
+    *, transcriber: Optional[Callable[[str], str]] = None
+) -> MultimodalPorts:
+    """Resolve the vision/audio capabilities this install really has.
+
+    ``transcriber`` comes from :class:`~latticeai.services.voice_capture.
+    VoiceCaptureService` so a voice memo and a scanned ``.m4a`` are transcribed
+    by the same thing — or, far more often, by the same nothing.
+    """
+    resolved = resolve_vision_embedder(
+        os.getenv(VISION_PROVIDER_ENV, ""),
+        model=os.getenv(VISION_MODEL_ENV, ""),
+        space=os.getenv(VISION_SPACE_ENV, MODALITY_IMAGE),
+    )
+    captioner = resolve_vision_captioner(
+        os.getenv(VISION_CAPTION_PROVIDER_ENV, ""),
+        model=os.getenv(VISION_CAPTION_MODEL_ENV, ""),
+        target=os.getenv(VISION_CAPTION_TARGET_ENV, ""),
+    )
+    provider = resolved.provider
+    return MultimodalPorts(
+        captioner=vision_caption_port(captioner),
+        vision_embedder=resolved.as_port(),
+        transcriber=transcriber,
+        text_to_image_embedder=text_to_image_port(provider),
+        vision_model_id=provider.model_id if provider is not None else "",
+        vision_space=resolved.space,
+    )
+
+
+def text_to_image_port(
+    provider: Any,
+) -> Optional[Callable[[str], List[float]]]:
+    """A *query-text* → image-space vector port, only from a shared-space model.
+
+    This is what lets a typed question reach a picture through the image index
+    instead of only through its OCR text. It exists as its own port precisely
+    because most vision models cannot do it: a CLIP image vector and a BGE text
+    vector are not comparable, and `VisionEmbeddingProvider.embed_batch` refuses
+    outright unless the model declares a shared space. An image-space model
+    therefore yields ``None`` here — the honest answer, and the one the search
+    surface reports rather than silently ranking on a meaningless number.
+    """
+    if provider is None or not getattr(provider, "shares_text_space", False):
+        return None
+
+    def _embed(query: str) -> List[float]:
+        vectors = provider.embed_batch([str(query or "")])
+        return [float(value) for value in (vectors[0] if vectors else [])]
+
+    return _embed
+
+
+def describe_multimodal(ports: MultimodalPorts) -> Dict[str, Any]:
+    """Operator-facing status: enabled, plus what is actually wired."""
+    return {"enabled": multimodal_enabled(), **ports.describe()}
+
+
+__all__ = [
+    "VISION_CAPTION_MODEL_ENV",
+    "VISION_CAPTION_PROVIDER_ENV",
+    "VISION_MODEL_ENV",
+    "VISION_PROVIDER_ENV",
+    "VISION_SPACE_ENV",
+    "build_multimodal_ports",
+    "describe_multimodal",
+    "multimodal_enabled",
+    "text_to_image_port",
+]

package/latticeai/services/obsidian_bridge.py

@@ -35,7 +35,6 @@ be a lie in the summary.
 
 from __future__ import annotations
 
-import json
 import os
 import re
 from dataclasses import dataclass, field
@@ -48,6 +47,7 @@ from urllib.parse import unquote
 # store-extracted topic the same node instead of two nodes with one label.
 from lattice_brain.graph.ingest import _scoped_slug_id
 from lattice_brain.ingestion import IngestionItem
+from latticeai.services.interop_bridges import edge_row, topic_row
 
 SOURCE_TYPE = "obsidian"
 NOTE_EXTENSIONS = frozenset({".md", ".markdown"})
@@ -567,15 +567,9 @@ class ObsidianVaultBridge:
             "index": outcome.get("index"),
         }
 
-    @staticmethod
-    def _edge_row(from_id: str, to_id: str, relation: str, metadata: Dict[str, Any]) -> Dict[str, Any]:
-        return {
-            "from_node": from_id,
-            "to_node": to_id,
-            "type": relation,
-            "weight": 1.0,
-            "metadata_json": json.dumps(metadata, ensure_ascii=False),
-        }
+    # Row shapes are shared with every other bridge (v11.2.0): two copies of
+    # "what an edge row looks like" is two places to forget an encoding.
+    _edge_row = staticmethod(edge_row)
 
     @staticmethod
     def _topic_row(
@@ -586,21 +580,18 @@ class ObsidianVaultBridge:
         owner: Optional[str],
         workspace_id: Optional[str],
     ) -> Dict[str, Any]:
-        metadata = {
-            "topic": tag,
-            "source": SOURCE_TYPE,
-            "vault": vault,
-            "owner": owner,
-            "workspace_id": workspace_id,
-        }
-        return {
-            "id": topic_id,
-            "type": TOPIC_NODE_TYPE,
-            "title": tag,
-            "summary": f"Obsidian tag #{tag}",
-            "metadata_json": json.dumps(metadata, ensure_ascii=False),
-            "raw_json": "{}",
-        }
+        return topic_row(
+            topic_id,
+            tag,
+            summary=f"Obsidian tag #{tag}",
+            metadata={
+                "topic": tag,
+                "source": SOURCE_TYPE,
+                "vault": vault,
+                "owner": owner,
+                "workspace_id": workspace_id,
+            },
+        )
 
 
 __all__ = [

package/latticeai/services/product_readiness.py

@@ -18,7 +18,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "11.0.1"
+PRODUCT_VERSION_TARGET = "11.2.0"
 
 
 @dataclass(frozen=True)

package/latticeai/services/search_service.py

@@ -8,9 +8,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime
-from typing import Any, Dict, List, Mapping, Optional
+from typing import Any, Dict, List, Mapping, Optional, Tuple
 
+from lattice_brain.gates import FeatureGate
 from lattice_brain.graph._kg_fsutil import _parse_iso, _recency_score
+from lattice_brain.graph.image_vectors import DEFAULT_IMAGE_FUSION_WEIGHT
 from lattice_brain.graph.retrieval_policy import resolve_policy
 
 DEFAULT_HYBRID_WEIGHTS = {
@@ -19,6 +21,33 @@ DEFAULT_HYBRID_WEIGHTS = {
     "graph": 0.25,
 }
 
+# ── text query → image space (v11.2.0) ───────────────────────────────────────
+# 11.1.0 shipped image late fusion as API-only, because the two vector spaces
+# are not comparable and nothing produced a query vector for the image index.
+# A *shared-space* vision model can produce one, and this is the switch that
+# lets the search API do it automatically. Off by default and resolved when
+# asked, so a settings toggle can move it without a restart; with it off the
+# hybrid response is byte-identical to 11.1.0's.
+TEXT_IMAGE_FUSION_ENV = "LATTICEAI_TEXT_IMAGE_FUSION"
+IMAGE_QUERY_FUSION_GATE = FeatureGate(
+    TEXT_IMAGE_FUSION_ENV,
+    default=False,
+    name="text_image_fusion",
+    detail=(
+        "Typed questions can also be scored against the image index when a "
+        "shared-space vision model is configured."
+    ),
+)
+IMAGE_FUSION_UNAVAILABLE = (
+    "no shared-space vision model is configured, so a typed question cannot be "
+    "scored against image vectors; pictures are still found through their OCR "
+    "text and captions"
+)
+IMAGE_FUSION_DISABLED = (
+    "automatic image fusion is off for this install "
+    f"({TEXT_IMAGE_FUSION_ENV}); the caller may still supply an image vector"
+)
+
 
 def _clean(text: Any, limit: int = 1000) -> str:
     return " ".join(str(text or "").split())[:limit]
@@ -31,6 +60,115 @@ def _result_key(result: Mapping[str, Any]) -> str:
 @dataclass
 class SearchService:
     graph_store: Any
+    #: ``(query_text) -> image-space vector``. Defaults to the port the store
+    #: already carries (``multimodal_ports.text_to_image_embedder``), so no new
+    #: wiring is needed; the field exists so a test — or an install with its
+    #: own encoder — can supply one directly.
+    image_query_embedder: Any = None
+
+    # ── image-space query channel (v11.2.0) ──────────────────────────────
+    def image_query_status(self) -> Dict[str, Any]:
+        """Whether a typed question can reach the image index here, and why not."""
+        port, detail = self._image_query_port()
+        return {
+            "available": port is not None,
+            "gate": IMAGE_QUERY_FUSION_GATE.describe(),
+            "detail": detail,
+        }
+
+    def _image_query_port(self) -> Tuple[Any, Optional[str]]:
+        """The text→image port and, when there is none, the honest reason."""
+        if self.image_query_embedder is not None:
+            return self.image_query_embedder, None
+        ports = getattr(self.graph_store, "multimodal_ports", None)
+        port = getattr(ports, "text_to_image_embedder", None)
+        return (port, None) if port is not None else (None, IMAGE_FUSION_UNAVAILABLE)
+
+    def _image_query_vector(self, query: str) -> Tuple[Optional[List[float]], Optional[str]]:
+        port, detail = self._image_query_port()
+        if port is None:
+            return None, detail
+        try:
+            vector = [float(value) for value in (port(query) or [])]
+        except Exception as exc:  # noqa: BLE001 — a broken encoder never fails a search
+            return None, f"the vision model could not embed the query: {exc}"
+        if not vector:
+            return None, "the vision model returned an empty query vector"
+        return vector, None
+
+    def _image_channel(
+        self, query: str, matches: List[Dict[str, Any]], *, requested: bool, limit: int
+    ) -> Optional[Dict[str, Any]]:
+        """Late-fuse the image index into an already-ranked match list.
+
+        Returns ``None`` when the caller did not ask, which is what keeps the
+        response byte-identical for everyone who did not opt in. When it *was*
+        asked for and could not run, it returns the reason rather than silently
+        producing the same answer as before.
+        """
+        if not requested:
+            return None
+        report: Dict[str, Any] = {
+            "requested": True,
+            "applied": False,
+            "weight": DEFAULT_IMAGE_FUSION_WEIGHT,
+            "candidates": 0,
+            "fused": 0,
+            "detail": None,
+        }
+        if not IMAGE_QUERY_FUSION_GATE.enabled():
+            report["detail"] = IMAGE_FUSION_DISABLED
+            return {"image_fusion": report}
+        vector, detail = self._image_query_vector(query)
+        if vector is None:
+            report["detail"] = detail
+            return {"image_fusion": report}
+        from lattice_brain.graph.image_vectors import image_similarity_search
+
+        try:
+            found = image_similarity_search(
+                self.graph_store, vector, top_k=max(1, int(limit) * 2)
+            )
+        except Exception as exc:  # noqa: BLE001 — the text answer must survive
+            report["detail"] = f"image index unavailable: {exc}"
+            return {"image_fusion": report}
+        report["candidates"] = int(found.get("candidates") or 0)
+        scores = {
+            str(match["node_id"]): float(match["score"])
+            for match in found.get("matches") or []
+        }
+        report["fused"] = self._blend_image_scores(matches, scores)
+        report["applied"] = True
+        report["detail"] = found.get("detail")
+        return {"image_fusion": report}
+
+    @staticmethod
+    def _blend_image_scores(
+        matches: List[Dict[str, Any]],
+        scores: Dict[str, float],
+        *,
+        weight: float = DEFAULT_IMAGE_FUSION_WEIGHT,
+    ) -> int:
+        """The graph layer's blend, over this layer's ``source_scores`` shape.
+
+        Late fusion by construction: the two rankings were produced
+        independently and only the final numbers meet, so neither space is ever
+        asked to interpret the other's.
+        """
+        touched = 0
+        for match in matches:
+            raw = scores.get(_result_key(match))
+            if raw is None:
+                continue
+            touched += 1
+            match.setdefault("source_scores", {})["image"] = round(raw, 6)
+            blended = (1.0 - weight) * float(match.get("score") or 0.0) + weight * raw
+            match["score"] = round(blended, 6)
+        if touched:
+            matches.sort(key=lambda item: float(item.get("score") or 0.0), reverse=True)
+            for rank, match in enumerate(matches, start=1):
+                match["rank"] = rank
+        return touched
 
     def _require_graph(self) -> Any:
         if self.graph_store is None:
@@ -410,6 +548,7 @@ class SearchService:
         weights: Optional[Mapping[str, float]] = None,
         allowed_workspaces=None,
         include_legacy_global: bool = False,
+        image_fusion: bool = False,
     ) -> Dict[str, Any]:
         # Single retrieval policy (review Wave 0.2): when the caller does not
         # pin explicit weights, resolve the query class + per-class channel
@@ -513,7 +652,10 @@ class SearchService:
             }
             if query_class is not None:
                 match["fusion"]["query_class"] = query_class
-        return {
+        multimodal = self._image_channel(
+            query, matches, requested=image_fusion, limit=limit,
+        )
+        report: Dict[str, Any] = {
             "query": query,
             "mode": "hybrid",
             "query_class": query_class,
@@ -529,6 +671,11 @@ class SearchService:
             },
             "matches": matches,
         }
+        # Additive key only when the caller asked, so an untouched response is
+        # the one 11.1.0 returned.
+        if multimodal is not None:
+            report["multimodal"] = multimodal
+        return report
 
     def graph(
         self,