ltcai 11.0.1 → 11.1.0

package/README.md

@@ -11,7 +11,7 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v11.0.1 Living Brain walkthrough](output/release/v11.0.1/gifs/v11.0.1-living-brain-walkthrough.gif)
+![v11.1.0 Living Brain walkthrough](output/release/v11.1.0/gifs/v11.1.0-living-brain-walkthrough.gif)
 
 Chat, files, folders, notes, and web pages all flow into one durable knowledge
 graph on your computer. Any model — local MLX or cloud — can speak with that
@@ -24,10 +24,10 @@ memory. Nothing leaves your machine without explicit consent.
 
 | | |
 | --- | --- |
-| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.0.1/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.0.1/screenshots/05-memory-graph.png) |
-| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.0.1/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.0.1/screenshots/12-review-center.png) |
-| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.0.1/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v11.0.1/screenshots/10-admin-console.png) |
-| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.0.1/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words; dangerous actions stay blocked either way ![Settings](output/release/v11.0.1/screenshots/08-system.png) |
+| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v11.1.0/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v11.1.0/screenshots/05-memory-graph.png) |
+| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v11.1.0/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v11.1.0/screenshots/12-review-center.png) |
+| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v11.1.0/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v11.1.0/screenshots/10-admin-console.png) |
+| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v11.1.0/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words; dangerous actions stay blocked either way ![Settings](output/release/v11.1.0/screenshots/08-system.png) |
 
 ## Why Lattice AI
 
@@ -58,53 +58,64 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v11.0.1/screenshots/01-login.png) | ![Model install](output/release/v11.0.1/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.0.1/screenshots/07-model-library.png) |
+| ![Login](output/release/v11.1.0/screenshots/01-login.png) | ![Model install](output/release/v11.1.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v11.1.0/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v11.0.1/SCREENSHOT_INDEX.md](output/release/v11.0.1/SCREENSHOT_INDEX.md)
+[output/release/v11.1.0/SCREENSHOT_INDEX.md](output/release/v11.1.0/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **11.0.1 — Both Branches**:
-
-11.0.0 put every line under test and documented, unfixed, the defects that
-work surfaced. 11.0.1 is the settling of that account: **all eleven
-documented defects are fixed, the code they proved dead is gone, and the CI
-floor now holds 100% of branch arcs as well as lines.**
-
-- **Every 11.0.0 finding is fixed.** The Telegram helper that sent the local
-  server's auth header to api.telegram.org, the unload-all that fabricated
-  success, the HTML inspector whose stylesheet collection could never fire,
-  the review-item id that collided within one second, the vLLM zombie that
-  read as "already running", the security dashboard's listing/detail
-  redaction gaps and invalid-JSON exports, the embedding `model_id` frozen at
-  the wrong dimension, the fast-path model-name mismatch, and the workspace
-  routes' dead literal and unreachable 404 arms. Each fix flipped the test
-  that had pinned the broken behaviour and gained a regression test.
-- **Branch coverage joined the floor.** `branch = true` is now in the
-  coverage config: both directions of all 9,828 conditionals execute under
-  the suite (5,798 tests, up from 5,426), and `fail_under = 100` fails CI on
-  a single missed arc. Exclusions stay honest: eight reasoned
-  `pragma: no cover` lines and two reasoned `pragma: no branch` lines.
-- **Dead code left the tree.** The unused auto-approved write-policy factory,
-  an unused snapshot-import normalizer, the workspace 404 arms shadowed by
-  the anti-enumeration 403, a provably-dead version guard, a provably-dead
-  MLX condition, and the vLLM silent-success recheck — each removal proved by
-  AST/reference scan before deletion.
-- **Verified where CI runs.** The full suite passes with the branch gate on
-  macOS 3.14, a fresh-resolve python 3.11 environment (fastapi 0.141), and a
-  clean linux python:3.14 container — the three environments that caught
-  11.0.0's release-day failures.
+The current release is **11.1.0 — Product Intelligence**:
+
+The v9–v11.0 line hardened the foundation — proposal-first trust, honest
+signals, a 100% line-and-branch test floor. 11.1.0 builds the intelligence
+layer on top of it: **the Brain gets fast at scale, notices things on its
+own, remembers pictures and recordings, learns who you are, and connects to
+the tools you already use.**
+
+- **Fast at scale.** A pluggable vector-index layer (brute-force default,
+  int8 quantized and HNSW opt-in via the `hnsw` extra) plus a durable
+  background embed queue. Measured on Apple Silicon: hybrid search p50 at
+  10k vectors went from 299 ms to **10.1 ms**, and stays at 43.9 ms at 50k
+  (recall@10 0.987) — the plan's <50 ms target met at 5× the target corpus.
+  Approximate results say `approx: true`; quantized's honest verdict (no RAM
+  win here, ~2.2× slower) is printed, not hidden.
+- **Alive, not just searchable.** Contradiction detection now files
+  review-queue proposals with plain-language resolutions; approving one
+  stamps the temporal model (`valid_from`/`valid_to`/`superseded_by`, with
+  `as_of(timestamp)` slicing). Event-driven synthesis proposes parent
+  concepts, missing links and a proactive Brain Brief after every 25th
+  ingest — every write goes through the proposal path, asserted by tests.
+- **Pictures and recordings are memories.** Behind `allow_multimodal`
+  (default off, off ⇒ byte-identical): images become first-class `Image`
+  nodes with OCR text, real captions only when a vision model produced one
+  (the caption-fabricating stub was deleted), separate image vectors with
+  late fusion, and inline thumbnails in the Evidence panel that never bypass
+  the local-file approval gate. Recordings are first-class `Audio` nodes
+  with honest transcription degradation.
+- **It knows you — transparently.** A Self-Model subgraph (Self /
+  Preference / Decision / Habit / Relationship) built only from proposals
+  you approve, injected into answer context under a strict token budget,
+  fully listable and deletable. Agents can propose whole-folder
+  reorganizations — structurally incapable of proposing deletions.
+- **Connected, selectively.** An approval-gated Obsidian vault bridge
+  (wikilinks become edges, idempotent re-runs) and a signed, encrypted
+  subgraph-share prototype where received knowledge arrives as proposals —
+  off by default behind `LATTICEAI_BRAIN_NETWORK`.
+
+All of it lands with the floor intact: **6,261 tests, 100.00% of 37,590
+statements and 10,658 branches**, verified on macOS 3.14, a fresh-resolve
+python 3.11 environment, and a clean linux python:3.14 container.
 
 Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
-Expected artifacts for 11.0.1 release must use exact filenames:
+Expected artifacts for 11.1.0 release must use exact filenames:
 
-- `dist/ltcai-11.0.1-py3-none-any.whl`
-- `dist/ltcai-11.0.1.tar.gz`
-- `ltcai-11.0.1.tgz`
-- `dist/ltcai-11.0.1.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_11.0.1_aarch64.dmg`
+- `dist/ltcai-11.1.0-py3-none-any.whl`
+- `dist/ltcai-11.1.0.tar.gz`
+- `ltcai-11.1.0.tgz`
+- `dist/ltcai-11.1.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_11.1.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
@@ -139,6 +150,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 
 | Version | Theme |
 | --- | --- |
+| 11.1.0 | Product Intelligence |
 | 11.0.1 | Both Branches |
 | 11.0.0 | Full Measure |
 | 10.10.0 | Quiet Station |

package/docs/CHANGELOG.md

@@ -4,6 +4,34 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [11.1.0] - 2026-08-10 — Product Intelligence Layer
+
+### Added
+- 플러그형 벡터 인덱스 레이어(`lattice_brain/graph/vector_index/`):
+  BruteForce 기본, int8 Quantized·HNSW(`ltcai[hnsw]`) 옵트인, 영속 배경
+  임베딩 큐(`vector_jobs`), `vector_freshness_breakdown()`, RRF 융합·이웃
+  후보 확장 옵션. 하이브리드 p50 10k 299ms → 10.1ms, 50k 43.9ms
+  (recall@10 0.987, docs/PERFORMANCE.md).
+- Temporal 지식 모델: `valid_from`/`valid_to`/`superseded_by`(멱등 제자리
+  승급, NULL 규약) + `as_of(timestamp)` 슬라이스. 모순 감지 → 리뷰 제안
+  → 승인 시 temporal 스탬프. 이벤트 기반 합성(상위 개념·누락 엣지·
+  proactive Brief 제안, 25개 인제스트마다, 격리 배선) + 중요도/정리 제안.
+  새 API: `/api/brain/proactive-brief|importance|synthesize|contradictions/*`.
+- 멀티모달 1등 시민(`allow_multimodal`, 기본 꺼짐 — 꺼짐=바이트 동일):
+  Image/Audio 1등 노드, OCR·실캡션만(`caption_status`), 별도 이미지 벡터
+  공간+late fusion, Evidence 인라인 썸네일(승인 게이트 비우회), 비디오는
+  정직 거부.
+- Self-Model 서브그래프(제안-우선 생성, 사용자 직접 소유), 컨텍스트
+  예산 주입, 삭제 불가능 구조의 폴더 재구성 제안,
+  `/api/memory/self-model*` 5종.
+- Obsidian vault 브릿지(`POST /api/ingestion/obsidian`, 승인 게이트,
+  위키링크→엣지, 멱등) + 서명·암호화 선택적 서브그래프 공유 프로토타입
+  (`LATTICEAI_BRAIN_NETWORK` 기본 꺼짐, 수신=리뷰 제안).
+
+### Removed
+- `VisionStub`/`get_vision_embedder` — 파일명으로 캡션을 합성하고 그
+  문자열의 해시를 이미지 임베딩으로 저장하던 경로(정직성 위반) 삭제.
+
 ## [11.0.1] - 2026-08-10
 
 ### Fixed

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -3,7 +3,7 @@
 > **Status: canonical** — current contributor guidance, kept in sync with the
 > current release.
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v11.0.1)
+# Lattice AI — Operations Guide (v11.1.0)
 
 > **Status: canonical** — kept in sync with the current release. Storage layout
 > below reflects the SQLite live Brain store and workspace scoping, not the

package/docs/PERFORMANCE.md

@@ -110,6 +110,10 @@ Methodology, and what it does not cover:
 - Latency and memory are measured in separate passes. tracemalloc roughly
   triples Python allocation cost, so timing under it would measure the
   profiler — the `peak MB` column comes from one extra traced query.
+- `peak MB` counts **Python** allocations only. hnswlib keeps its graph in C++
+  memory, which tracemalloc cannot see, so that column understates HNSW by the
+  size of the graph itself. Read it as "what the query costs the interpreter",
+  not as the process's resident size.
 - `first ms` is the *first* query after the corpus changed. For `hnsw` that is
   where the graph gets built and the `.hnsw` sidecar written; for the other two
   it is an ordinary query.
@@ -135,27 +139,27 @@ Run it:
 ### Measured, 2026-08-10 — 10 000 vectors, 30 queries, top_k 10
 
 macOS 27 (arm64, Apple Silicon), Python 3.14.5, SQLite 3.53.1,
-hnswlib 0.8.0, uncapped candidates, corpus build 2.12 s.
+hnswlib 0.8.0, uncapped candidates, corpus build 2.19 s.
 
 | backend | p50 ms | p95 ms | first ms | peak MB | recall@10 | hybrid p50 ms |
 |-----------|-------:|-------:|---------:|--------:|----------:|--------------:|
-| brute     | 288.89 | 291.95 |   290.68 |   39.72 |    1.000  |        296.63 |
-| quantized | 639.47 | 645.93 |   653.31 |   38.38 |    0.987  |        639.83 |
-| hnsw      |  21.53 |  22.11 |   795.84 |    0.74 |    0.953  |         24.37 |
+| brute     | 293.25 | 299.31 |   293.91 |   39.72 |    1.000  |        299.17 |
+| quantized | 640.58 | 650.15 |   636.87 |   38.38 |    0.987  |        653.33 |
+| hnsw      |   7.01 |   7.50 |   799.95 |    0.05 |    0.953  |         10.07 |
 
 What the table says, plainly:
 
-- **The default is exact and slow.** 289 ms per query at 10k, and hybrid
-  inherits nearly all of it (297 ms) — the vector channel *is* the cost.
-- **HNSW meets the 11.1.0 target and prices it.** Hybrid p50 **24.4 ms** at 10k
-  (target: < 50 ms), a 12x improvement, in exchange for **4.7% of the exact
+- **The default is exact and slow.** 293 ms per query at 10k, and hybrid
+  inherits nearly all of it (299 ms) — the vector channel *is* the cost.
+- **HNSW meets the 11.1.0 target and prices it.** Hybrid p50 **10.1 ms** at 10k
+  (target: < 50 ms), a 30x improvement, in exchange for **4.7% of the exact
   top-10 going missing**. That is the trade, stated as a number rather than as
-  the word "approximate". Its 0.74 MB peak is the two-phase lookup: it reads
-  only the ten rows it returns, where the exact scan reads all 10 000.
-- **The 796 ms first query is the graph build**, paid once per index generation
-  and then persisted to the `.hnsw` sidecar. Any write to `vector_embeddings`
-  invalidates the fingerprint and buys that cost again, which is why `brute`
-  stays the default for a continuously-ingesting brain.
+  the word "approximate".
+- **The 800 ms first query is the graph build**, paid once per index generation
+  and then persisted to the `.hnsw` sidecar (and held in memory for the rest of
+  the process). Any write to `vector_embeddings` invalidates the fingerprint
+  and buys that cost again, which is why `brute` stays the default for a
+  continuously-ingesting brain.
 - **Quantized is currently the wrong choice on every axis.** ~2.2x the latency
   for 0.987 recall, and its RAM advantage does not materialise (38.4 vs
   39.7 MB): the exact scan already feeds the index in bounded batches, so
@@ -163,16 +167,65 @@ What the table says, plainly:
   It ships as an honest, exhaustive backend and as the representation a held
   cross-query index would need. It is not a recommendation.
 
+### Measured, 2026-08-10 — 50 000 vectors, 15 queries, top_k 10
+
+Same machine and settings; corpus build 11.19 s.
+
+| backend | p50 ms | p95 ms | first ms | peak MB | recall@10 | hybrid p50 ms |
+|-----------|--------:|--------:|---------:|--------:|----------:|--------------:|
+| brute     | 1515.31 | 1522.94 |  1520.89 |  194.92 |    1.000  |       1514.75 |
+| quantized | 3254.76 | 3275.69 |  3253.54 |  195.05 |    0.967  |       3441.13 |
+| hnsw      |   35.58 |   38.19 |  6114.60 |    0.04 |    0.987  |         43.90 |
+
+- **The exact scan is linear and unusable at this size**: 1.5 s per query, and
+  ~195 MB of Python allocation to score one question.
+- **HNSW still clears the 50 ms budget at 5x the target corpus** — hybrid p50
+  43.9 ms — and its recall here is 0.987, higher than the 10k run's 0.953
+  (15 queries is a small sample; treat the two as "around 0.95–0.99", not as a
+  trend).
+- **The remaining HNSW cost is not the search.** 7 ms at 10k → 36 ms at 50k is
+  suspiciously linear for a graph index, and it is: every query first runs the
+  freshness check (`SELECT COUNT(*), MAX(indexed_at) FROM vector_embeddings
+  WHERE embedding_model=? AND embedding_dim=?`), which has no covering index
+  and walks the table. A named follow-up, not a mystery: an index on
+  `(embedding_model, embedding_dim)` would remove it. The budget is met either
+  way, so it was not worth a schema change in this release.
+- **The 6.1 s first query is the 50k graph build.** It is paid once per index
+  generation, and the sidecar means a restart does not pay it again.
+
+### A measurement mistake worth keeping
+
+The first 50k run reported HNSW recall of **0.18** and was wrong. The default
+candidate cap (10 000) was still in force, so the "exact" baseline had scored
+only the newest 10 000 of 50 000 rows while HNSW searched all of them — the
+disagreement was the baseline's blind spot, not the ANN's error. The bench now
+lifts the cap by default and prints a `trunc` column. Recorded here because
+the failure mode is generic: *any* recall number measured against a truncated
+baseline is measuring the truncation.
+
+### Not measured
+
+- **100k+ vectors.** Nothing is claimed beyond the 50k run above.
+- **sqlite-vec ANN.** The optional `ann` extra was not installed, so
+  `vector_search_backend` reported `bruteforce-cosine` throughout. Its numbers
+  are unknown, not zero.
+- **A real embedding provider.** Everything here uses the deterministic hash
+  embedder. With a model- or network-backed embedder, query-embedding cost
+  moves into the foreground and these ratios change.
+- **Resident process memory.** See the tracemalloc caveat above: the HNSW graph
+  lives outside Python's allocator and is not in the `peak MB` column.
+
 ## Observations
 
 - Keyword `search()` / `context_for_query()` stay low-millisecond thanks to
   the FTS5 trigram index; they are not the scaling bottleneck.
 - `traverse(depth=2)` cost grows with edge fan-out (synthetic corpus creates
   dense shared-concept hubs); p95 is ~5 ms at 500 sources and ~16 ms at 5000.
-- `vector_search()` is a brute-force scan over every stored embedding
-  (O(index size) per query). It is the dominant cost at scale and the first
-  candidate for an ANN/pruning optimization if vector recall becomes a hot
-  path. The profiler caps vector queries at 10 for this reason.
+- `vector_search()` on the default backend is a brute-force scan over every
+  stored embedding (O(index size) per query). It is the dominant cost at scale
+  — which is what the 11.1.0 backend table above measures, and what
+  `LATTICEAI_VECTOR_INDEX=hnsw` addresses. `profile_kg.py` still caps vector
+  queries at 10 for this reason.
 - `rebuild_vector_index(full=True)` embeds documents and chunks with the hash
   embedder; with a real embedding provider expect this phase to be slower by
   the provider's per-call latency times the item count.

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **11.0.1 — Both Branches**.
+Current release: **11.1.0 — Product Intelligence**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `lattice_brain/graph/schema.py`

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "11.0.1"
+__version__ = "11.1.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/embeddings.py

@@ -8,7 +8,7 @@ import os
 import re
 import struct
 from dataclasses import dataclass
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Iterable, List
 
 DEFAULT_EMBEDDING_DIM = int(os.getenv("LATTICEAI_VECTOR_DIM", "384"))
 EMBEDDING_MODEL_ID = f"lattice-local-hash-v1:{DEFAULT_EMBEDDING_DIM}"
@@ -97,40 +97,15 @@ class LocalEmbeddingModel:
         return list(struct.unpack(f"<{count}f", payload[: count * 4]))
 
 
-# --- Large candidate #2 slice: multimodal (vision) stubs ---
-# Schema already defines IMAGE / IMAGE_TEXT / CONTAINS_IMAGE.
-# These stubs allow ingestion + retrieval paths to carry image signals without
-# requiring heavy deps at core. Real impl can swap in local vision (e.g. via
-# ollama vision or onnx CLIP) behind the same interface.
-@dataclass(frozen=True)
-class VisionStub:
-    """Offline vision describe + embed stubs for multimodal Brain.
-
-    describe: returns a short textual caption derived from metadata/filename.
-    embed: produces a vector from image meta (size+format) + optional caption hash.
-    Later: replace with real embedding model that accepts image bytes/path.
-    """
-    dim: int = DEFAULT_EMBEDDING_DIM
-
-    def describe(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None) -> str:
-        meta = meta or {}
-        w = meta.get("width") or meta.get("w") or "?"
-        h = meta.get("height") or meta.get("h") or "?"
-        fmt = meta.get("format") or meta.get("ext") or "img"
-        name = (path or "").split("/")[-1] or "image"
-        # deterministic caption stub (no external call)
-        return f"Image {name} ({fmt} {w}x{h})"
-
-    def embed_image(self, path: str | None = None, meta: Optional[Dict[str, Any]] = None, caption: str = "") -> List[float]:
-        meta = meta or {}
-        basis = f"{path or ''}|{meta.get('width',0)}x{meta.get('height',0)}|{meta.get('format','')}|{caption[:120]}"
-        # reuse text embedder for determinism (image content hash would be better with real vision)
-        model = LocalEmbeddingModel(dim=self.dim)
-        return model.embed(basis)
-
-
-def get_vision_embedder(dim: int | None = None) -> VisionStub:
-    return VisionStub(dim=dim or DEFAULT_EMBEDDING_DIM)
-
+# Removed in v11.1.0: ``VisionStub`` / ``get_vision_embedder``.
+#
+# They produced a "caption" (``Image pic.png (PNG 12x8)``) and an "image
+# embedding" (a hash of the filename and pixel dimensions) with no model
+# involved, and ``discovery_index`` stored both. Once in the graph neither was
+# distinguishable from something a vision model had actually said, which is the
+# one property a caption must have. The honest seam is now
+# :class:`lattice_brain.multimodal.MultimodalPorts`: a caption exists only when
+# a vision-language model produced it, an image vector only when a vision model
+# produced it, and their absence is recorded as an absence.
 
-__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id", "VisionStub", "get_vision_embedder"]
+__all__ = ["DEFAULT_EMBEDDING_DIM", "EMBEDDING_MODEL_ID", "LocalEmbeddingModel", "embedding_model_id"]

package/lattice_brain/graph/discovery_index.py

@@ -111,40 +111,38 @@ class KnowledgeGraphLocalIndexMixin(_Core):
             meta["text_slides"] = len(slides_text)
             text = "\n\n".join(slides_text)
         elif category == "image":
-            from PIL import Image
+            text = self._extract_image_signals(path, meta, include_ocr=include_ocr)
+        return text[:200_000], meta
 
-            with Image.open(str(path)) as image:
-                meta.update(
-                    {
-                        "width": image.width,
-                        "height": image.height,
-                        "format": image.format,
-                        "mode": image.mode,
-                        "ocr_enabled": bool(include_ocr),
-                    }
-                )
-                if include_ocr:
-                    try:
-                        import pytesseract
+    def _extract_image_signals(
+        self, path: Path, meta: Dict[str, Any], *, include_ocr: bool
+    ) -> str:
+        """Dimensions, OCR text, and — only if a VLM exists — a caption.
 
-                        text = pytesseract.image_to_string(image)
-                        meta["ocr_chars"] = len(text)
-                    except (
-                        Exception
-                    ) as exc:  # pragma: no cover - depends on local OCR runtime
-                        meta["ocr_error"] = str(exc)
-                        text = ""
-                # Large candidate #2 slice: always attach vision stub describe for IMAGE node evidence
-                try:
-                    from ..embeddings import get_vision_embedder
-                    v = get_vision_embedder()
-                    cap = v.describe(str(path), meta)
-                    meta["vision_caption"] = cap
-                    if not text:
-                        text = cap  # fallback text signal for retrieval
-                except Exception:
-                    meta["vision_caption"] = meta.get("vision_caption") or f"image:{path}"
-        return text[:200_000], meta
+        Until v11.1.0 this path always attached a ``vision_caption`` built out
+        of the filename and the pixel dimensions (``Image pic.png (PNG 12x8)``)
+        and used it as the retrieval text. Nothing downstream could tell that
+        string apart from something a vision model had actually said about the
+        picture, so every screenshot in the graph carried a fake description.
+
+        Now the caption comes from the injected port and from nowhere else. A
+        picture with no OCR text and no model still gets indexed — under its
+        filename, which is a fact — and ``caption_status`` says why there is no
+        caption.
+        """
+        from ..multimodal import MultimodalPorts, extract_image_facts
+
+        ports = getattr(self, "multimodal_ports", None) or MultimodalPorts()
+        facts = extract_image_facts(str(path), ports=ports, ocr=include_ocr)
+        meta.update(facts.as_metadata())
+        meta["ocr_enabled"] = bool(include_ocr)
+        if facts.ocr_text:
+            meta["ocr_chars"] = len(facts.ocr_text)
+        if facts.ocr_status == "failed":
+            meta["ocr_error"] = facts.ocr_detail
+        if not facts.readable:
+            return ""
+        return facts.index_text() or path.name
 
     def _ensure_local_hierarchy(
         self,