davinci-resolve-mcp 2.42.0 → 2.43.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.43.0
+
+Embeddings + similarity search — Phase C of the analysis + edit-engine
+program. "Find clips/shots like this," locally, with no vendor token cost.
+
+- **Added** `src/utils/embeddings.py` and schema v10 (`embeddings` table:
+  one float32 vector per entity/kind/model, with content hashes so re-runs
+  only re-embed what changed). Brute-force cosine — numpy when present.
+- **Added** `media_analysis` actions `build_embeddings` (idempotent; clip
+  summaries, shot descriptions + deep field groups, transcript segments,
+  sampled frames with per-shot mean vectors) and `find_similar` (query by
+  free text, clip, or shot; `kind="text"|"visual"`; free-text visual queries
+  go through the CLIP text encoder).
+- **Added** backend detection, never installation (the whisper pattern):
+  text = ollama `nomic-embed-text` (serving probe) or sentence-transformers;
+  visual = open_clip ViT-B-32. Capabilities and the Diagnostics → Tools page
+  list availability with install guidance.
+- **Added** a `Semantic` toggle on the panel's Review search (shown only
+  when a text backend is detected) backed by `/api/search/semantic`, which
+  returns rows in the existing search-card shape.
+- **Validation**: full offline suite (1095 tests; 14 new, backends mocked).
+  Live on the 2026-05-17 sample root: 54 text vectors in 1.2s via ollama
+  with correct top hits for three editorial queries; 27 CLIP vectors with
+  "cracked broken windshield glass" ranking the shattered-windshield frame
+  first; panel endpoint verified and screenshots regenerated.
+
 ## What's New in v2.42.0
 
 Deep shot-level vision tier — Phase B of the analysis + edit-engine program.

package/README.md

@@ -1,6 +1,6 @@
 # DaVinci Resolve MCP Server
 
-[![Version](https://img.shields.io/badge/version-2.42.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.43.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-33%20(341%20full)-blue.svg)](#server-modes)

package/docs/SKILL.md

@@ -495,8 +495,24 @@ Key actions: `capabilities`, `install_guidance`, `resolve_output_root`, `plan`,
 `cleanup_artifacts`, `db_status`, `db_ingest`, `get_panel_state`,
 `set_panel_state`, `session_start_context`, `update_clip_field`,
 `update_shot_field`, `get_field_history`, `revert_field`,
-`list_corrections`, `deepen`, `commit_shot_vision`, and
-`vision_pending_sweep`.
+`list_corrections`, `deepen`, `commit_shot_vision`, `vision_pending_sweep`,
+`build_embeddings`, and `find_similar`.
+
+**Embeddings + similarity (v2.43.0+).** Local-compute semantic search; no
+vendor tokens, so nothing here touches the caps ledger. Backends are
+detected, never installed (capabilities lists them with install guidance):
+text = ollama serving `nomic-embed-text` or sentence-transformers; visual =
+open_clip (ViT-B-32, needs torch).
+- `build_embeddings(kinds=["text","visual"]?, clip_id?)` — idempotent;
+  embeds clip summaries, shot descriptions (+ deep field groups), transcript
+  segments, and sampled frames (per-shot visual vector = mean of its
+  frames'). Only re-embeds entities whose content changed.
+- `find_similar(text=… | clip_id=… | clip_id+shot_index, kind="text"|"visual",
+  entity_types?, limit?)` — brute-force cosine over the project's vectors.
+  Free-text visual queries use the CLIP text encoder ("cracked windshield"
+  finds the frame). Results carry scores plus clip/shot/segment context.
+The panel search box gains a `Semantic` toggle when a text backend is
+detected. Vectors live in the per-project DB (schema v10).
 
 **Deep shot-level vision tier (v2.42.0+).** Opt-in, estimate-first. Two
 entry points share one per-shot schema (Visual / Content / Production /

package/docs/guides/control-panel.md

@@ -78,7 +78,11 @@ evidence base (analyzed / superseded / vision-pending / warnings) with
 humanized source-trust and analysis-layer chips. Cards show a representative
 thumbnail, duration, shot count, status, and summary one-liner; grid and list
 layouts are available, and full-text search covers clips, summaries, tags, and
-transcripts once the search index is built.
+transcripts once the search index is built. When a local text-embedding
+backend is detected (ollama with `nomic-embed-text`, or
+sentence-transformers), a `Semantic` toggle appears next to the search box —
+it searches by meaning instead of exact words, ranking clips, shots, and
+transcript lines by similarity to your query.
 
 ### Clip detail
 

package/install.py

@@ -35,7 +35,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.42.0"
+VERSION = "2.43.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.42.0",
+  "version": "2.43.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -4065,6 +4065,9 @@ HTML = r"""<!doctype html>
         </div>
         <div class="review-bin-filters">
           <input id="reviewSearchInput" type="search" placeholder="Search clips, summaries, tags, transcripts…" autocomplete="off">
+          <label id="reviewSemanticToggle" class="review-semantic-toggle" style="display:none" title="Search by meaning using local text embeddings instead of exact words.">
+            <input id="reviewSemanticCheckbox" type="checkbox"> Semantic
+          </label>
           <select id="reviewBinFilter" aria-label="Filter by bin">
             <option value="">All bins</option>
           </select>
@@ -6201,6 +6204,13 @@ HTML = r"""<!doctype html>
       syncPreferencesPanel();
       applyPreferencesToControls(prefs);
       renderVersionBadge();
+      // Semantic search rides on a local text-embedding backend; only show
+      // the toggle when one is detected (ollama nomic-embed-text or
+      // sentence-transformers).
+      if (state.boot?.capabilities?.embeddings?.text?.available) {
+        const toggle = $('reviewSemanticToggle');
+        if (toggle) toggle.style.display = '';
+      }
       // Paint the previous inventory immediately (stale) so a slow first
       // /api/resolve/media — common with network source media — doesn't leave the
       // panel blank. The live fetch below replaces it and clears the stale flag.
@@ -8258,7 +8268,11 @@ HTML = r"""<!doctype html>
         renderReviewBin();
         return;
       }
-      const payload = await api(`/api/index/query?q=${encodeURIComponent(query)}&limit=40`)
+      const semantic = !!$('reviewSemanticCheckbox')?.checked;
+      const endpoint = semantic
+        ? `/api/search/semantic?q=${encodeURIComponent(query)}&limit=40`
+        : `/api/index/query?q=${encodeURIComponent(query)}&limit=40`;
+      const payload = await api(endpoint)
         .catch(err => ({ success: false, error: String(err) }));
       state.review.searchResults = payload;
       renderReviewBin();
@@ -11083,6 +11097,11 @@ HTML = r"""<!doctype html>
         runReviewSearch(q).catch(alertError);
       }, 250);
     });
+    // Semantic toggle re-runs the current query through the embeddings index.
+    $('reviewSemanticCheckbox')?.addEventListener('change', () => {
+      const q = $('reviewSearchInput').value.trim();
+      if (q) runReviewSearch(q).catch(alertError);
+    });
     // Bin dropdown.
     $('reviewBinFilter').addEventListener('change', event => {
       state.review.binFilter = event.target.value || '';
@@ -12470,6 +12489,57 @@ def _v2_load_analysis_db_first(project_root: str, clip_dir: str) -> Optional[Dic
     return _v2_load_analysis(clip_dir)
 
 
+def _v2_semantic_search(project_root: str, q: str, *, limit: int = 20) -> Dict[str, Any]:
+    """Semantic search over the embeddings index, shaped like /api/index/query
+    rows so the existing search-card renderer works unchanged."""
+    text = (q or "").strip()
+    if not text:
+        return {"success": True, "results": []}
+    try:
+        from src.utils import embeddings, timeline_brain_db as tbd
+
+        found = embeddings.find_similar(project_root, text=text, kind="text", limit=limit)
+        if not found.get("success"):
+            return found
+        conn = tbd.connect(project_root)
+        resolve_ids: Dict[str, Optional[str]] = {}
+
+        def resolve_clip_id(clip_uuid: Optional[str]) -> Optional[str]:
+            if not clip_uuid:
+                return None
+            if clip_uuid not in resolve_ids:
+                row = conn.execute(
+                    "SELECT resolve_clip_id, clip_dir FROM clips WHERE clip_uuid = ?",
+                    (clip_uuid,),
+                ).fetchone()
+                resolve_ids[clip_uuid] = (row["resolve_clip_id"] or row["clip_dir"]) if row else None
+            return resolve_ids[clip_uuid]
+
+        rows: List[Dict[str, Any]] = []
+        for hit in found.get("results") or []:
+            entity_type = hit.get("entity_type")
+            clip_uuid = hit.get("clip_uuid") or (hit.get("entity_uuid") if entity_type == "clip" else None)
+            row: Dict[str, Any] = {
+                "result_type": "transcript" if entity_type == "segment" else "semantic",
+                "score": hit.get("score"),
+                "clip_id": resolve_clip_id(clip_uuid),
+                "clip_name": hit.get("clip_name"),
+            }
+            if entity_type == "shot":
+                row["start_seconds"] = hit.get("time_seconds_start")
+                row["summary"] = hit.get("description")
+            elif entity_type == "segment":
+                row["start_seconds"] = hit.get("start_seconds")
+                row["summary"] = hit.get("text")
+            else:
+                row["summary"] = hit.get("summary")
+            rows.append(row)
+        rows = _v2_enrich_search_results(project_root, rows)
+        return {"success": True, "query": text, "model": found.get("model"), "results": rows}
+    except Exception as exc:  # noqa: BLE001 — search must fail soft in the panel
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+
+
 def _v2_clip_duration(report: Dict[str, Any]) -> Optional[float]:
     marker_plan = report.get("clip_analysis_markers") if isinstance(report.get("clip_analysis_markers"), dict) else {}
     duration = marker_plan.get("duration_seconds")
@@ -14316,6 +14386,14 @@ class Handler(BaseHTTPRequestHandler):
                 payload["results"] = _v2_enrich_search_results(self.state.project_root, payload["results"])
             self._json(payload)
             return
+        if path == "/api/search/semantic":
+            q = (query.get("q") or [""])[0]
+            try:
+                limit = int((query.get("limit") or ["20"])[0])
+            except (TypeError, ValueError):
+                limit = 20
+            self._json(_v2_semantic_search(self.state.project_root, q, limit=limit))
+            return
         # ─── C6 timeline-history surface ───────────────────────────────
         if path == "/api/timeline_versions":
             self._json(list_timelines_with_versions(self.state.project_root))

package/src/granular/common.py

@@ -80,7 +80,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.42.0"
+VERSION = "2.43.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 341-tool granular server instead
 """
 
-VERSION = "2.42.0"
+VERSION = "2.43.0"
 
 import base64
 import os
@@ -15024,6 +15024,9 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "deepen",
         "commit_shot_vision",
         "vision_pending_sweep",
+        # Phase C — embeddings + similarity.
+        "build_embeddings",
+        "find_similar",
     }:
         root = resolve_media_analysis_output_root(
             project_name=project_name,
@@ -15119,6 +15122,34 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
                 max_age_days=p.get("max_age_days") or p.get("maxAgeDays"),
                 reoffer=_media_analysis_bool(p.get("reoffer"), False),
             )
+        # Phase C — embeddings + similarity (local compute; no token caps).
+        if action == "build_embeddings":
+            from src.utils import embeddings
+            kinds = p.get("kinds") or p.get("kind") or ["text"]
+            if isinstance(kinds, str):
+                kinds = [kinds]
+            return embeddings.build_embeddings(
+                project_root,
+                kinds=[str(k).strip().lower() for k in kinds],
+                clip_ref=p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir"),
+                include_segments=_media_analysis_bool(p.get("include_segments", p.get("includeSegments")), True),
+                max_frames_per_clip=int(p.get("max_frames_per_clip") or p.get("maxFramesPerClip") or 16),
+            )
+        if action == "find_similar":
+            from src.utils import embeddings
+            entity_types = p.get("entity_types") or p.get("entityTypes")
+            if isinstance(entity_types, str):
+                entity_types = [entity_types]
+            return embeddings.find_similar(
+                project_root,
+                text=p.get("text") or p.get("query"),
+                clip_ref=p.get("clip_id") or p.get("clipId") or p.get("clip_dir") or p.get("clipDir"),
+                shot_index=p.get("shot_index") if p.get("shot_index") is not None else p.get("shotIndex"),
+                shot_uuid=p.get("shot_uuid") or p.get("shotUuid"),
+                kind=p.get("kind") or "text",
+                entity_types=entity_types,
+                limit=int(p.get("limit") or 10),
+            )
         if action in {"build_index", "rebuild_index"}:
             return build_analysis_index(project_root, index_path=p.get("index_path") or p.get("indexPath"))
         if action == "index_status":
@@ -15533,6 +15564,8 @@ async def media_analysis(action: str, params: Optional[Dict[str, Any]] = None, c
         "deepen",
         "commit_shot_vision",
         "vision_pending_sweep",
+        "build_embeddings",
+        "find_similar",
         "get_caps",
         "set_caps_preset",
         "get_usage",

package/src/utils/embeddings.py

@@ -0,0 +1,668 @@
+"""Embeddings + similarity search (Phase C of the analysis program).
+
+Text vectors over clip/shot summaries and transcript segments, CLIP image
+vectors over sampled frames. Backends are detected, never installed (the
+whisper pattern):
+
+- text: ollama serving ``nomic-embed-text`` (preferred — works on Apple
+  Silicon via Metal), or ``sentence_transformers`` when installed.
+- visual: ``open_clip_torch`` (ViT-B-32) when installed alongside torch.
+
+Vectors live in the per-project DB (schema v10 ``embeddings`` table) as
+float32 BLOBs, one row per (entity, kind, model). Similarity is brute-force
+cosine — numpy when present, pure Python otherwise; this is thousands of
+vectors, not millions. Embedding is local compute, so nothing here touches
+the vision-token caps ledger; responses report wall-clock + counts instead.
+"""
+
+from __future__ import annotations
+
+import array
+import hashlib
+import importlib.util
+import json
+import math
+import os
+import shutil
+import sqlite3
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+from src.utils import timeline_brain_db
+
+OLLAMA_URL = os.environ.get("DAVINCI_RESOLVE_MCP_OLLAMA_URL", "http://127.0.0.1:11434")
+OLLAMA_TEXT_MODEL = os.environ.get("DAVINCI_RESOLVE_MCP_EMBED_MODEL", "nomic-embed-text")
+SENTENCE_TRANSFORMERS_MODEL = "all-MiniLM-L6-v2"
+OPEN_CLIP_MODEL = ("ViT-B-32", "laion2b_s34b_b79k")
+
+_PROBE_TIMEOUT_SECONDS = 2.0
+_EMBED_TIMEOUT_SECONDS = 120.0
+
+# Lazy singletons for heavyweight local models.
+_ST_MODEL = None
+_CLIP_STATE: Optional[Tuple[Any, Any, Any]] = None  # (model, preprocess, torch)
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _content_hash(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]
+
+
+def pack_vector(vector: Sequence[float]) -> bytes:
+    return array.array("f", vector).tobytes()
+
+
+def unpack_vector(blob: bytes) -> List[float]:
+    arr = array.array("f")
+    arr.frombytes(blob)
+    return list(arr)
+
+
+def cosine_similarity(a: Sequence[float], b: Sequence[float]) -> float:
+    try:
+        import numpy as np
+
+        va, vb = np.asarray(a, dtype="float32"), np.asarray(b, dtype="float32")
+        denom = float(np.linalg.norm(va) * np.linalg.norm(vb))
+        if denom == 0.0:
+            return 0.0
+        return float(np.dot(va, vb) / denom)
+    except ImportError:
+        dot = sum(x * y for x, y in zip(a, b))
+        na = math.sqrt(sum(x * x for x in a))
+        nb = math.sqrt(sum(y * y for y in b))
+        if na == 0.0 or nb == 0.0:
+            return 0.0
+        return dot / (na * nb)
+
+
+# ── backend detection (no installs, ever) ────────────────────────────────────
+
+
+def _ollama_state() -> Dict[str, Any]:
+    binary = shutil.which("ollama")
+    state: Dict[str, Any] = {
+        "binary": binary,
+        "serving": False,
+        "model_present": False,
+        "model": OLLAMA_TEXT_MODEL,
+    }
+    if not binary:
+        return state
+    try:
+        with urllib.request.urlopen(f"{OLLAMA_URL}/api/tags", timeout=_PROBE_TIMEOUT_SECONDS) as resp:
+            payload = json.load(resp)
+        state["serving"] = True
+        models = [str(m.get("name") or "") for m in payload.get("models") or []]
+        state["model_present"] = any(
+            name == OLLAMA_TEXT_MODEL or name.startswith(f"{OLLAMA_TEXT_MODEL}:")
+            for name in models
+        )
+    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+        pass
+    return state
+
+
+def detect_embedding_capabilities() -> Dict[str, Any]:
+    """Availability of text/visual embedding backends, with install guidance."""
+    ollama = _ollama_state()
+    st_available = importlib.util.find_spec("sentence_transformers") is not None
+    torch_available = importlib.util.find_spec("torch") is not None
+    open_clip_available = importlib.util.find_spec("open_clip") is not None
+
+    text_backends = []
+    if ollama["binary"] and ollama["serving"] and ollama["model_present"]:
+        text_backends.append("ollama")
+    if st_available:
+        text_backends.append("sentence_transformers")
+
+    guidance: Dict[str, str] = {}
+    if not text_backends:
+        if ollama["binary"] and ollama["serving"] and not ollama["model_present"]:
+            guidance["text"] = f"Ask the user before running: ollama pull {OLLAMA_TEXT_MODEL}"
+        elif ollama["binary"] and not ollama["serving"]:
+            guidance["text"] = f"Start ollama (ollama serve), then: ollama pull {OLLAMA_TEXT_MODEL}"
+        else:
+            guidance["text"] = (
+                f"Install ollama (https://ollama.com) and pull {OLLAMA_TEXT_MODEL}, "
+                "or pip install sentence-transformers."
+            )
+    visual_available = torch_available and open_clip_available
+    if not visual_available:
+        guidance["visual"] = (
+            "pip install open_clip_torch"
+            if torch_available
+            else "pip install torch open_clip_torch"
+        )
+
+    return {
+        "success": True,
+        "no_auto_install": True,
+        "text": {
+            "available": bool(text_backends),
+            "backends": text_backends,
+            "ollama": ollama,
+            "model": OLLAMA_TEXT_MODEL if "ollama" in text_backends else (
+                SENTENCE_TRANSFORMERS_MODEL if st_available else None
+            ),
+        },
+        "visual": {
+            "available": visual_available,
+            "backends": ["open_clip"] if visual_available else [],
+            "model": "-".join(OPEN_CLIP_MODEL) if visual_available else None,
+        },
+        "install_guidance": guidance,
+    }
+
+
+# ── embedding calls ──────────────────────────────────────────────────────────
+
+
+def _embed_texts_ollama(texts: List[str]) -> Tuple[List[List[float]], str]:
+    body = json.dumps({"model": OLLAMA_TEXT_MODEL, "input": texts}).encode("utf-8")
+    request = urllib.request.Request(
+        f"{OLLAMA_URL}/api/embed",
+        data=body,
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(request, timeout=_EMBED_TIMEOUT_SECONDS) as resp:
+        payload = json.load(resp)
+    vectors = payload.get("embeddings")
+    if not isinstance(vectors, list) or len(vectors) != len(texts):
+        raise ValueError(f"ollama returned {len(vectors or [])} embeddings for {len(texts)} inputs")
+    return vectors, f"ollama:{OLLAMA_TEXT_MODEL}"
+
+
+def _embed_texts_sentence_transformers(texts: List[str]) -> Tuple[List[List[float]], str]:
+    global _ST_MODEL
+    if _ST_MODEL is None:
+        from sentence_transformers import SentenceTransformer
+
+        _ST_MODEL = SentenceTransformer(SENTENCE_TRANSFORMERS_MODEL)
+    vectors = _ST_MODEL.encode(texts, convert_to_numpy=True)
+    return [list(map(float, v)) for v in vectors], f"sentence_transformers:{SENTENCE_TRANSFORMERS_MODEL}"
+
+
+def embed_texts(texts: List[str], *, backend: Optional[str] = None) -> Dict[str, Any]:
+    """Embed a batch of texts with the best available local backend."""
+    if not texts:
+        return {"success": True, "vectors": [], "model": None}
+    caps = detect_embedding_capabilities()
+    backends = caps["text"]["backends"]
+    chosen = backend or (backends[0] if backends else None)
+    if chosen not in backends:
+        return {
+            "success": False,
+            "error": "No text-embedding backend available",
+            "install_guidance": caps["install_guidance"].get("text"),
+        }
+    try:
+        if chosen == "ollama":
+            vectors, model = _embed_texts_ollama(texts)
+        else:
+            vectors, model = _embed_texts_sentence_transformers(texts)
+    except Exception as exc:  # noqa: BLE001 — backend failures surface as data
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}", "backend": chosen}
+    return {"success": True, "vectors": vectors, "model": model, "backend": chosen}
+
+
+def _clip_model():
+    global _CLIP_STATE
+    if _CLIP_STATE is None:
+        import open_clip
+        import torch
+
+        model, _, preprocess = open_clip.create_model_and_transforms(
+            OPEN_CLIP_MODEL[0], pretrained=OPEN_CLIP_MODEL[1]
+        )
+        model.eval()
+        _CLIP_STATE = (model, preprocess, torch)
+    return _CLIP_STATE
+
+
+def embed_images(paths: List[str]) -> Dict[str, Any]:
+    """Embed image files with open_clip. Skips missing files."""
+    caps = detect_embedding_capabilities()
+    if not caps["visual"]["available"]:
+        return {
+            "success": False,
+            "error": "No visual-embedding backend available",
+            "install_guidance": caps["install_guidance"].get("visual"),
+        }
+    try:
+        from PIL import Image
+
+        model, preprocess, torch = _clip_model()
+        vectors: List[Optional[List[float]]] = []
+        with torch.no_grad():
+            for path in paths:
+                if not path or not os.path.isfile(path):
+                    vectors.append(None)
+                    continue
+                image = preprocess(Image.open(path).convert("RGB")).unsqueeze(0)
+                features = model.encode_image(image)
+                features = features / features.norm(dim=-1, keepdim=True)
+                vectors.append([float(x) for x in features[0].tolist()])
+    except Exception as exc:  # noqa: BLE001
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+    return {"success": True, "vectors": vectors, "model": f"open_clip:{'-'.join(OPEN_CLIP_MODEL)}"}
+
+
+def embed_text_for_visual_query(text: str) -> Dict[str, Any]:
+    """CLIP text encoder — lets a free-text query search visual vectors."""
+    caps = detect_embedding_capabilities()
+    if not caps["visual"]["available"]:
+        return {
+            "success": False,
+            "error": "No visual-embedding backend available",
+            "install_guidance": caps["install_guidance"].get("visual"),
+        }
+    try:
+        import open_clip
+
+        model, _preprocess, torch = _clip_model()
+        tokenizer = open_clip.get_tokenizer(OPEN_CLIP_MODEL[0])
+        with torch.no_grad():
+            features = model.encode_text(tokenizer([text]))
+            features = features / features.norm(dim=-1, keepdim=True)
+        return {
+            "success": True,
+            "vector": [float(x) for x in features[0].tolist()],
+            "model": f"open_clip:{'-'.join(OPEN_CLIP_MODEL)}",
+        }
+    except Exception as exc:  # noqa: BLE001
+        return {"success": False, "error": f"{type(exc).__name__}: {exc}"}
+
+
+# ── content builders ─────────────────────────────────────────────────────────
+
+
+def _shot_embed_text(shot: Dict[str, Any]) -> str:
+    parts: List[str] = []
+    if shot.get("description"):
+        parts.append(str(shot["description"]))
+    extra = shot.get("extra_json")
+    if extra:
+        try:
+            groups = json.loads(extra)
+        except (TypeError, ValueError):
+            groups = {}
+        for group in ("visual", "content", "editorial", "cuttability", "production"):
+            block = groups.get(group)
+            if isinstance(block, dict):
+                for key, value in sorted(block.items()):
+                    if value in (None, "", [], {}):
+                        continue
+                    parts.append(f"{key}: {json.dumps(value, sort_keys=True, default=str)}")
+    return "\n".join(parts).strip()
+
+
+def _clip_embed_text(clip: Dict[str, Any], conn: sqlite3.Connection) -> str:
+    parts: List[str] = []
+    for key in ("clip_name", "summary"):
+        if clip.get(key):
+            parts.append(str(clip[key]))
+    row = conn.execute(
+        """
+        SELECT value_json FROM subjective_fields
+        WHERE entity_type='clip' AND entity_uuid=? AND field_path='clip_summary'
+          AND superseded_at IS NULL
+        """,
+        (clip["clip_uuid"],),
+    ).fetchone()
+    if row:
+        try:
+            parts.append(str(json.loads(row["value_json"])))
+        except (TypeError, ValueError):
+            pass
+    tags = conn.execute(
+        """
+        SELECT value_json FROM subjective_fields
+        WHERE entity_type='clip' AND entity_uuid=? AND field_path='editing_notes.search_tags'
+          AND superseded_at IS NULL
+        """,
+        (clip["clip_uuid"],),
+    ).fetchone()
+    if tags:
+        try:
+            parts.append("tags: " + ", ".join(map(str, json.loads(tags["value_json"]) or [])))
+        except (TypeError, ValueError):
+            pass
+    return "\n".join(parts).strip()
+
+
+# ── build ────────────────────────────────────────────────────────────────────
+
+
+def _existing_rows(conn: sqlite3.Connection, kind: str) -> Dict[Tuple[str, str], str]:
+    rows = conn.execute(
+        "SELECT entity_type, entity_uuid, content_hash FROM embeddings WHERE embedding_kind = ?",
+        (kind,),
+    ).fetchall()
+    return {(str(r["entity_type"]), str(r["entity_uuid"])): str(r["content_hash"] or "") for r in rows}
+
+
+def _store_vectors(
+    project_root: str,
+    kind: str,
+    model: str,
+    items: List[Tuple[str, str, str, List[float]]],
+) -> int:
+    """items: (entity_type, entity_uuid, content_hash, vector)."""
+    if not items:
+        return 0
+    now = _now()
+    with timeline_brain_db.transaction(project_root) as conn:
+        for entity_type, entity_uuid, content_hash, vector in items:
+            conn.execute(
+                """
+                INSERT INTO embeddings
+                    (entity_type, entity_uuid, embedding_kind, model_name,
+                     dimension, vector, content_hash, computed_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(entity_type, entity_uuid, embedding_kind, model_name)
+                DO UPDATE SET vector=excluded.vector, dimension=excluded.dimension,
+                              content_hash=excluded.content_hash, computed_at=excluded.computed_at
+                """,
+                (entity_type, entity_uuid, kind, model, len(vector), pack_vector(vector), content_hash, now),
+            )
+    return len(items)
+
+
+def build_embeddings(
+    project_root: str,
+    *,
+    kinds: Sequence[str] = ("text",),
+    clip_ref: Any = None,
+    include_segments: bool = True,
+    max_frames_per_clip: int = 16,
+) -> Dict[str, Any]:
+    """Build/refresh embeddings for a project (or one clip). Idempotent:
+    entities whose content hash is unchanged are skipped."""
+    from src.utils import analysis_store
+
+    started = time.time()
+    conn = timeline_brain_db.connect(project_root)
+    clip_filter: Optional[str] = None
+    if clip_ref:
+        clip_filter = analysis_store.resolve_clip_uuid(conn, clip_ref)
+        if not clip_filter:
+            return {"success": False, "error": f"clip not found in DB: {clip_ref!r} (run db_ingest first)"}
+
+    result: Dict[str, Any] = {"success": True, "project_root": project_root, "kinds": list(kinds)}
+    where = " WHERE clip_uuid = ?" if clip_filter else ""
+    args: Tuple[Any, ...] = (clip_filter,) if clip_filter else ()
+
+    if "text" in kinds:
+        texts: List[str] = []
+        meta: List[Tuple[str, str, str]] = []  # (entity_type, uuid, hash)
+        existing = _existing_rows(conn, "text")
+        for clip in conn.execute(f"SELECT * FROM clips{where}", args).fetchall():
+            clip = dict(clip)
+            text = _clip_embed_text(clip, conn)
+            if text:
+                h = _content_hash(text)
+                if existing.get(("clip", clip["clip_uuid"])) != h:
+                    texts.append(text)
+                    meta.append(("clip", clip["clip_uuid"], h))
+        for shot in conn.execute(
+            f"SELECT * FROM shots{where} ORDER BY clip_uuid, shot_index", args
+        ).fetchall():
+            shot = dict(shot)
+            text = _shot_embed_text(shot)
+            if text:
+                h = _content_hash(text)
+                if existing.get(("shot", shot["shot_uuid"])) != h:
+                    texts.append(text)
+                    meta.append(("shot", shot["shot_uuid"], h))
+        if include_segments:
+            for seg in conn.execute(
+                f"SELECT * FROM transcript_segments{where} ORDER BY clip_uuid, segment_index", args
+            ).fetchall():
+                seg = dict(seg)
+                text = str(seg.get("text") or "").strip()
+                if len(text) < 8:
+                    continue
+                uuid = f"{seg['clip_uuid']}:{seg['segment_index']}"
+                h = _content_hash(text)
+                if existing.get(("segment", uuid)) != h:
+                    texts.append(text)
+                    meta.append(("segment", uuid, h))
+        if texts:
+            embedded = embed_texts(texts)
+            if not embedded.get("success"):
+                result["text"] = embedded
+                result["success"] = False
+                return result
+            stored = _store_vectors(
+                project_root,
+                "text",
+                str(embedded["model"]),
+                [(m[0], m[1], m[2], v) for m, v in zip(meta, embedded["vectors"])],
+            )
+            result["text"] = {"success": True, "embedded": stored, "skipped_unchanged": None, "model": embedded["model"]}
+        else:
+            result["text"] = {"success": True, "embedded": 0, "note": "all up to date"}
+
+    if "visual" in kinds:
+        existing = _existing_rows(conn, "visual")
+        frame_rows = conn.execute(
+            f"SELECT * FROM frames{where} ORDER BY clip_uuid, frame_index", args
+        ).fetchall()
+        by_clip: Dict[str, List[Dict[str, Any]]] = {}
+        for row in frame_rows:
+            by_clip.setdefault(str(row["clip_uuid"]), []).append(dict(row))
+        paths: List[str] = []
+        meta_v: List[Tuple[str, str, str]] = []
+        frame_shot: List[Optional[str]] = []
+        for clip_uuid, rows in by_clip.items():
+            on_disk = [r for r in rows if r.get("frame_path") and os.path.isfile(str(r["frame_path"]))]
+            if len(on_disk) > max_frames_per_clip:
+                step = len(on_disk) / float(max_frames_per_clip)
+                on_disk = [on_disk[int(i * step)] for i in range(max_frames_per_clip)]
+            for r in on_disk:
+                uuid = f"{clip_uuid}:{r['frame_index']}"
+                h = _content_hash(str(r["frame_path"]))
+                if existing.get(("frame", uuid)) == h:
+                    continue
+                paths.append(str(r["frame_path"]))
+                meta_v.append(("frame", uuid, h))
+                frame_shot.append(str(r["shot_uuid"]) if r.get("shot_uuid") else None)
+        if paths:
+            embedded = embed_images(paths)
+            if not embedded.get("success"):
+                result["visual"] = embedded
+                result["success"] = False
+                return result
+            items = []
+            shot_acc: Dict[str, List[List[float]]] = {}
+            for m, shot_uuid, vector in zip(meta_v, frame_shot, embedded["vectors"]):
+                if vector is None:
+                    continue
+                items.append((m[0], m[1], m[2], vector))
+                if shot_uuid:
+                    shot_acc.setdefault(shot_uuid, []).append(vector)
+            # Per-shot visual vector = mean of its frames'.
+            for shot_uuid, vectors in shot_acc.items():
+                dim = len(vectors[0])
+                mean = [sum(v[i] for v in vectors) / len(vectors) for i in range(dim)]
+                items.append(("shot", shot_uuid, _content_hash(json.dumps(sorted(len(v) for v in vectors)) + shot_uuid), mean))
+            stored = _store_vectors(project_root, "visual", str(embedded["model"]), items)
+            result["visual"] = {"success": True, "embedded": stored, "model": embedded["model"]}
+        else:
+            result["visual"] = {"success": True, "embedded": 0, "note": "all up to date"}
+
+    result["wall_clock_ms"] = int((time.time() - started) * 1000)
+    counts = conn.execute(
+        "SELECT embedding_kind, COUNT(*) AS n FROM embeddings GROUP BY embedding_kind"
+    ).fetchall()
+    result["totals"] = {str(r["embedding_kind"]): int(r["n"]) for r in counts}
+    return result
+
+
+# ── similarity search ────────────────────────────────────────────────────────
+
+
+def _hydrate(conn: sqlite3.Connection, entity_type: str, entity_uuid: str) -> Dict[str, Any]:
+    if entity_type == "clip":
+        row = conn.execute(
+            "SELECT clip_uuid, clip_name, clip_dir, summary FROM clips WHERE clip_uuid = ?",
+            (entity_uuid,),
+        ).fetchone()
+        return dict(row) if row else {}
+    if entity_type == "shot":
+        row = conn.execute(
+            """
+            SELECT s.shot_uuid, s.clip_uuid, s.shot_index, s.time_seconds_start,
+                   s.time_seconds_end, s.description, c.clip_name
+            FROM shots s LEFT JOIN clips c ON c.clip_uuid = s.clip_uuid
+            WHERE s.shot_uuid = ?
+            """,
+            (entity_uuid,),
+        ).fetchone()
+        return dict(row) if row else {}
+    if entity_type == "segment":
+        clip_uuid, _, seg_index = entity_uuid.rpartition(":")
+        row = conn.execute(
+            """
+            SELECT t.clip_uuid, t.segment_index, t.start_seconds, t.end_seconds,
+                   t.text, c.clip_name
+            FROM transcript_segments t LEFT JOIN clips c ON c.clip_uuid = t.clip_uuid
+            WHERE t.clip_uuid = ? AND t.segment_index = ?
+            """,
+            (clip_uuid, int(seg_index) if seg_index.isdigit() else -1),
+        ).fetchone()
+        return dict(row) if row else {}
+    if entity_type == "frame":
+        clip_uuid, _, frame_index = entity_uuid.rpartition(":")
+        row = conn.execute(
+            """
+            SELECT f.clip_uuid, f.frame_index, f.time_seconds, f.frame_path,
+                   f.shot_uuid, c.clip_name
+            FROM frames f LEFT JOIN clips c ON c.clip_uuid = f.clip_uuid
+            WHERE f.clip_uuid = ? AND f.frame_index = ?
+            """,
+            (clip_uuid, int(frame_index) if frame_index.lstrip("-").isdigit() else -1),
+        ).fetchone()
+        return dict(row) if row else {}
+    return {}
+
+
+def find_similar(
+    project_root: str,
+    *,
+    text: Optional[str] = None,
+    clip_ref: Any = None,
+    shot_index: Optional[int] = None,
+    shot_uuid: Optional[str] = None,
+    kind: str = "text",
+    entity_types: Optional[Sequence[str]] = None,
+    limit: int = 10,
+) -> Dict[str, Any]:
+    """Brute-force cosine search. Query by free text, a clip, or a shot."""
+    from src.utils import analysis_store
+
+    conn = timeline_brain_db.connect(project_root)
+    kind = (kind or "text").strip().lower()
+    if kind not in ("text", "visual"):
+        return {"success": False, "error": f"kind must be 'text' or 'visual', got {kind!r}"}
+
+    exclude: Optional[Tuple[str, str]] = None
+    query_vector: Optional[List[float]] = None
+    query_model: Optional[str] = None
+
+    if text:
+        if kind == "text":
+            embedded = embed_texts([str(text)])
+            if not embedded.get("success"):
+                return embedded
+            query_vector = embedded["vectors"][0]
+            query_model = str(embedded["model"])
+        else:
+            encoded = embed_text_for_visual_query(str(text))
+            if not encoded.get("success"):
+                return encoded
+            query_vector = encoded["vector"]
+            query_model = str(encoded["model"])
+    else:
+        entity_type: Optional[str] = None
+        entity_uuid: Optional[str] = None
+        if shot_uuid:
+            entity_type, entity_uuid = "shot", str(shot_uuid)
+        elif clip_ref is not None and shot_index is not None:
+            clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
+            if not clip_uuid:
+                return {"success": False, "error": f"clip not found in DB: {clip_ref!r}"}
+            row = conn.execute(
+                "SELECT shot_uuid FROM shots WHERE clip_uuid = ? AND shot_index = ?",
+                (clip_uuid, int(shot_index)),
+            ).fetchone()
+            if not row:
+                return {"success": False, "error": f"shot_index {shot_index} not found"}
+            entity_type, entity_uuid = "shot", str(row["shot_uuid"])
+        elif clip_ref is not None:
+            clip_uuid = analysis_store.resolve_clip_uuid(conn, clip_ref)
+            if not clip_uuid:
+                return {"success": False, "error": f"clip not found in DB: {clip_ref!r}"}
+            entity_type, entity_uuid = "clip", clip_uuid
+        else:
+            return {"success": False, "error": "find_similar requires text, clip_id/clip_dir, or shot"}
+        row = conn.execute(
+            """
+            SELECT vector, model_name FROM embeddings
+            WHERE entity_type = ? AND entity_uuid = ? AND embedding_kind = ?
+            """,
+            (entity_type, entity_uuid, kind),
+        ).fetchone()
+        if not row:
+            return {
+                "success": False,
+                "error": (
+                    f"No {kind} embedding for that {entity_type} yet — run "
+                    "media_analysis(action='build_embeddings') first."
+                ),
+            }
+        query_vector = unpack_vector(row["vector"])
+        query_model = str(row["model_name"])
+        exclude = (entity_type, entity_uuid)
+
+    where = "embedding_kind = ? AND model_name = ?"
+    args: List[Any] = [kind, query_model]
+    if entity_types:
+        placeholders = ",".join("?" for _ in entity_types)
+        where += f" AND entity_type IN ({placeholders})"
+        args.extend(entity_types)
+    rows = conn.execute(
+        f"SELECT entity_type, entity_uuid, vector FROM embeddings WHERE {where}", args
+    ).fetchall()
+
+    scored: List[Tuple[float, str, str]] = []
+    for row in rows:
+        key = (str(row["entity_type"]), str(row["entity_uuid"]))
+        if exclude and key == exclude:
+            continue
+        score = cosine_similarity(query_vector, unpack_vector(row["vector"]))
+        scored.append((score, key[0], key[1]))
+    scored.sort(key=lambda item: item[0], reverse=True)
+
+    results = []
+    for score, entity_type, entity_uuid in scored[: max(1, int(limit))]:
+        entry = {
+            "score": round(score, 4),
+            "entity_type": entity_type,
+            "entity_uuid": entity_uuid,
+        }
+        entry.update(_hydrate(conn, entity_type, entity_uuid))
+        results.append(entry)
+    return {
+        "success": True,
+        "kind": kind,
+        "model": query_model,
+        "candidates_scanned": len(rows),
+        "results": results,
+    }

package/src/utils/media_analysis.py

@@ -1436,6 +1436,28 @@ TOOL_INSTALL: Dict[str, Dict[str, Any]] = {
         "verify": "whisper --help",
         "notes": "Pure-Python reference implementation. Choose this OR whisper_cpp OR mlx_whisper.",
     },
+    "ollama_embeddings": {
+        "label": "ollama + nomic-embed-text",
+        "bundle": "embeddings",
+        "required_for": ["semantic search (text embeddings)", "find_similar"],
+        "commands": {
+            "macos": "brew install ollama && ollama pull nomic-embed-text",
+            "linux": "curl -fsSL https://ollama.com/install.sh | sh && ollama pull nomic-embed-text",
+            "windows": "winget install Ollama.Ollama, then: ollama pull nomic-embed-text",
+        },
+        "verify": "ollama list",
+        "notes": "Local embedding model (~270 MB). sentence-transformers is an alternative text backend.",
+    },
+    "open_clip": {
+        "label": "open_clip (CLIP visual embeddings)",
+        "bundle": "embeddings",
+        "required_for": ["visual similarity (find_similar kind=visual)", "cross-clip entity clustering"],
+        "commands": {
+            "all": "pip install open_clip_torch",
+        },
+        "verify": "python -c \"import open_clip\"",
+        "notes": "Needs torch. Model weights (~350 MB) download on first use.",
+    },
     "whisper_cpp": {
         "label": "whisper.cpp",
         "bundle": "transcription",
@@ -1585,6 +1607,17 @@ def detect_capabilities(env: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
 
     sync_events = detect_sync_event_capabilities()
 
+    # Phase C — embedding backends (detected like the whisper backends; the
+    # ollama probe is a short local HTTP call and fails fast when not serving).
+    try:
+        from src.utils import embeddings as _embeddings
+
+        embedding_caps = _embeddings.detect_embedding_capabilities()
+    except Exception:  # noqa: BLE001 — detection must never break capabilities
+        embedding_caps = {"text": {"available": False, "backends": []},
+                          "visual": {"available": False, "backends": []},
+                          "install_guidance": {}}
+
     platform_id, machine = _runtime_platform_id()
 
     def _tool_entry(name: str, available: bool, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
@@ -1607,7 +1640,18 @@ def detect_capabilities(env: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
             "whisper_cpp": _tool_entry("whisper_cpp", bool(whisper_cpp), {"path": whisper_cpp}),
             "mlx_whisper": _tool_entry("mlx_whisper", bool(mlx_whisper), {"python_module": "mlx_whisper"}),
             "opencv": _tool_entry("opencv", bool(cv2), {"python_module": "cv2"}),
+            "ollama_embeddings": _tool_entry(
+                "ollama_embeddings",
+                bool(embedding_caps.get("text", {}).get("available")),
+                {"backends": embedding_caps.get("text", {}).get("backends", [])},
+            ),
+            "open_clip": _tool_entry(
+                "open_clip",
+                bool(embedding_caps.get("visual", {}).get("available")),
+                {"python_module": "open_clip"},
+            ),
         },
+        "embeddings": embedding_caps,
         "transcription": {
             "available": bool(whisper_cli or whisper_cpp or mlx_whisper),
             "backends": [

package/src/utils/timeline_brain_db.py

@@ -29,7 +29,7 @@ from typing import Callable, Dict, Iterator, Optional, Tuple
 
 logger = logging.getLogger("resolve-mcp.timeline-brain-db")
 
-SCHEMA_VERSION = 9
+SCHEMA_VERSION = 10
 DB_FILENAME = "timeline_brain.sqlite"
 SOUL_DIRNAME = "_soul"
 
@@ -687,6 +687,38 @@ def _migrate_v9_analysis_core(conn: sqlite3.Connection) -> None:
     )
 
 
+@register_migration(10)
+def _migrate_v10_embeddings(conn: sqlite3.Connection) -> None:
+    """C3 — embeddings for similarity search (Phase C of the analysis program).
+
+    One row per (entity, kind, model). Vectors are float32 BLOBs; similarity
+    is brute-force cosine in the app layer (thousands of rows, not millions).
+    `content_hash` fingerprints the embedded content so re-runs only re-embed
+    entities whose text/frames changed.
+    """
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS embeddings (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            entity_type TEXT NOT NULL CHECK(entity_type IN ('clip', 'shot', 'frame', 'segment')),
+            entity_uuid TEXT NOT NULL,
+            embedding_kind TEXT NOT NULL,        -- 'text' | 'visual'
+            model_name TEXT NOT NULL,
+            dimension INTEGER NOT NULL,
+            vector BLOB NOT NULL,
+            content_hash TEXT,
+            computed_at TEXT NOT NULL,
+            UNIQUE(entity_type, entity_uuid, embedding_kind, model_name)
+        );
+
+        CREATE INDEX IF NOT EXISTS ix_embeddings_kind
+            ON embeddings(embedding_kind, model_name);
+        CREATE INDEX IF NOT EXISTS ix_embeddings_entity
+            ON embeddings(entity_type, entity_uuid);
+        """
+    )
+
+
 def latest_version(conn: sqlite3.Connection, timeline_name: str) -> Optional[int]:
     """Return the highest archived version number for `timeline_name`, or None."""
     row = conn.execute(