ltcai 11.2.0 → 11.4.0

package/lattice_brain/multimodal.py

@@ -1,1258 +0,0 @@
-"""Images and audio as first-class memories (v11.1.0, Track 3).
-
-Before this module the Brain could only remember things that arrived as text.
-A screenshot of a whiteboard, a photo of a receipt, a voice memo — all of them
-either bounced off the ingestion pipeline or landed as an opaque ``Document``
-node whose only searchable content was its filename.
-
-What routes here
-----------------
-:func:`detect_modality` reads the MIME type first and the extension second, and
-answers with one of ``text`` / ``image`` / ``audio`` / ``video``. ``video`` is
-deliberately a *recognized but unsupported* answer in this release: keyframe
-extraction needs a decoder this project does not ship, and returning "video,
-out of scope" is worth more than pretending a ``.mov`` is a picture.
-
-What an image memory contains
------------------------------
-:func:`extract_image_facts` gathers only what it can actually observe:
-
-* **dimensions/format** from Pillow (a core dependency);
-* **ocr_text** from ``pytesseract`` when it is installed — otherwise
-  ``ocr_status="unavailable"`` and no text, never an empty string dressed up as
-  a successful read;
-* **caption** from an injected vision-language port, and *only* from there. No
-  VLM means ``caption is None``. Composing "Image IMG_2381.png (JPEG 3024x4032)"
-  and storing it in the caption field would make metadata indistinguishable
-  from a model's description forever after;
-* **embedding** from an injected vision port, which lives in its own vector
-  space (see :mod:`latticeai.core.embedding_providers`) and therefore its own
-  index — text queries reach images through OCR/caption text, not by scoring a
-  BGE vector against CLIP vectors.
-
-Brain Core owns none of those models. Every heavy dependency arrives as an
-injected callable (:class:`MultimodalPorts`), which is also why this module
-imports nothing from ``latticeai``.
-"""
-
-from __future__ import annotations
-
-import base64
-import hashlib
-import io
-import mimetypes
-import re
-import shutil
-import subprocess  # noqa: S404 — one fixed binary, argv list, never a shell
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional
-
-from .quiet import quiet
-from .utils import utc_now_iso
-
-# ── modality taxonomy ────────────────────────────────────────────────────────
-MODALITY_TEXT = "text"
-MODALITY_IMAGE = "image"
-MODALITY_AUDIO = "audio"
-MODALITY_VIDEO = "video"
-
-IMAGE_EXTENSIONS = frozenset(
-    {".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ".tif", ".tiff", ".heic"}
-)
-# Containers that are *only* ever audio. ``.mp4``/``.webm`` are deliberately
-# absent: by extension alone they are video, and a voice memo recorded in one
-# of them arrives through an explicit audio MIME type (or through
-# ``VoiceCaptureService``, where the user already said "this is a memo").
-# ``.mid``/``.midi`` are listed for a second reason: CPython's *built-in* mime
-# table has neither, so ``mimetypes`` answers "audio/midi" only on a host that
-# ships a system mime file (macOS reads /etc/apache2/mime.types; a slim Linux
-# container has nothing). Leaving them to the fallback let the platform decide
-# what a MIDI file is — a module table exists precisely so it does not.
-AUDIO_EXTENSIONS = frozenset(
-    {".m4a", ".mp3", ".wav", ".aac", ".flac", ".ogg", ".opus", ".mid", ".midi"}
-)
-VIDEO_EXTENSIONS = frozenset({".mp4", ".webm", ".mov", ".mkv", ".avi", ".m4v"})
-#: Subtitle/caption files a video may arrive with. Same basename, so a
-#: ``standup.mp4`` next to a ``standup.srt`` is one memory, not two.
-SUBTITLE_EXTENSIONS = ("srt", "vtt")
-
-#: Why a video is recognized and still refused — surfaced to the caller. In
-#: 11.1.0 the reason was *scope* (nothing was implemented). Since 11.2.0 the
-#: implementation exists and the only remaining reason is a **runtime** one:
-#: this machine has no ``ffmpeg``, and inventing frames is not an option.
-VIDEO_UNAVAILABLE_DETAIL = (
-    "video ingestion needs ffmpeg on this machine and none was found; the file "
-    "was not stored (install ffmpeg to enable keyframe extraction)"
-)
-#: Kept under its 11.1.0 name so existing importers keep working; the reason it
-#: carries has changed from "out of scope" to "unavailable on this machine".
-VIDEO_OUT_OF_SCOPE = VIDEO_UNAVAILABLE_DETAIL
-
-#: Longest OCR/caption body kept on the node (a screenshot is not a novel).
-MAX_INDEX_TEXT_CHARS = 20_000
-#: Summary column budget, matching every other ingest door in the graph.
-SUMMARY_CHARS = 500
-#: Fixed-width chunking for OCR bodies that outgrow the summary.
-IMAGE_CHUNK_CHARS = 900
-#: Longest edge of the stored thumbnail, in pixels.
-THUMBNAIL_EDGE = 96
-#: A thumbnail is a UI affordance, not an archive — drop it past this size.
-MAX_THUMBNAIL_CHARS = 24_000
-
-
-def detect_modality(
-    path: Optional[str] = None, mime_type: Optional[str] = None
-) -> str:
-    """``text`` | ``image`` | ``audio`` | ``video`` for one candidate file.
-
-    The declared MIME type wins when it carries a usable top-level type: the
-    capture surface saw the bytes, this function only sees a name. Otherwise
-    the extension decides, and an unknown extension is ``text`` so existing
-    behaviour is untouched.
-    """
-    declared = str(mime_type or "").strip().lower().split(";")[0].split("/")[0]
-    if declared in {MODALITY_IMAGE, MODALITY_AUDIO, MODALITY_VIDEO}:
-        return declared
-    # The extension tables come before ``mimetypes`` on purpose: they are where
-    # this module's decisions live (``.mp4`` is video unless someone who saw
-    # the bytes says otherwise), and the stdlib table varies by platform.
-    suffix = Path(str(path or "")).suffix.lower()
-    if suffix in IMAGE_EXTENSIONS:
-        return MODALITY_IMAGE
-    if suffix in AUDIO_EXTENSIONS:
-        return MODALITY_AUDIO
-    if suffix in VIDEO_EXTENSIONS:
-        return MODALITY_VIDEO
-    if path:
-        guessed, _ = mimetypes.guess_type(str(path))
-        top = str(guessed or "").split("/")[0]
-        if top in {MODALITY_IMAGE, MODALITY_AUDIO, MODALITY_VIDEO}:
-            return top
-    return MODALITY_TEXT
-
-
-# ── injected capability ports ────────────────────────────────────────────────
-@dataclass
-class MultimodalPorts:
-    """The optional model-backed capabilities Brain Core cannot ship itself.
-
-    Every field is a plain callable so the app layer can build it from
-    ``latticeai.core.embedding_providers`` without Brain Core ever importing
-    that package. ``None`` everywhere is the honest default: OCR still runs
-    (``pytesseract`` is a local binary, not a model download), and everything
-    else reports itself as unavailable.
-    """
-
-    #: ``(image_path) -> caption or None`` — a loaded VLM, or nothing.
-    captioner: Optional[Callable[[str], Optional[str]]] = None
-    #: ``(image_path) -> vector`` in the image space (raises when it cannot).
-    vision_embedder: Optional[Callable[[str], List[float]]] = None
-    #: ``(audio_path) -> transcript`` (raises/returns empty when it cannot).
-    transcriber: Optional[Callable[[str], str]] = None
-    #: ``(video_path, dest_dir, count) -> [frame paths]`` (v11.2.0). ``None``
-    #: falls back to ffmpeg on PATH; absent ffmpeg is reported, never faked.
-    keyframe_extractor: Optional[Callable[..., Any]] = None
-    #: ``(query_text) -> vector`` in the *image* space (v11.2.0). Only a
-    #: genuinely shared-space vision model can supply one, which is why it is
-    #: its own port instead of being assumed from ``vision_embedder``.
-    text_to_image_embedder: Optional[Callable[[str], List[float]]] = None
-    #: Identity of the vision model, recorded next to every image vector.
-    vision_model_id: str = ""
-    #: ``image`` (own index + late fusion) or ``shared`` (same space as text).
-    vision_space: str = MODALITY_IMAGE
-
-    def describe(self) -> Dict[str, Any]:
-        """What this install can honestly do with a picture or a recording."""
-        return {
-            "caption": self.captioner is not None,
-            "vision_embedding": self.vision_embedder is not None,
-            "transcription": self.transcriber is not None,
-            "keyframes": self.keyframe_extractor is not None or ffmpeg_available(),
-            "text_to_image_query": self.text_to_image_embedder is not None,
-            "vision_model_id": self.vision_model_id,
-            "vision_space": self.vision_space,
-        }
-
-
-# ── image facts ──────────────────────────────────────────────────────────────
-@dataclass
-class ImageFacts:
-    """Everything observed about one image, and the status of each attempt."""
-
-    path: str
-    width: Optional[int] = None
-    height: Optional[int] = None
-    image_format: Optional[str] = None
-    mode: Optional[str] = None
-    #: ``ok`` | ``empty`` | ``unavailable`` | ``failed`` | ``skipped``
-    ocr_status: str = "skipped"
-    ocr_text: str = ""
-    ocr_detail: str = ""
-    #: ``ok`` | ``unavailable``
-    caption_status: str = "unavailable"
-    caption: Optional[str] = None
-    #: ``ok`` | ``unavailable`` | ``failed``
-    embedding_status: str = "unavailable"
-    embedding: Optional[List[float]] = None
-    embedding_detail: str = ""
-    thumbnail: Optional[str] = None
-    #: Set when the file could not be opened as an image at all.
-    error: str = ""
-
-    @property
-    def readable(self) -> bool:
-        return not self.error
-
-    def index_text(self) -> str:
-        """The text a search engine can actually match this image on."""
-        parts = [part for part in (self.caption, self.ocr_text) if part]
-        return "\n".join(parts).strip()[:MAX_INDEX_TEXT_CHARS]
-
-    def as_metadata(self) -> Dict[str, Any]:
-        """Flat, JSON-safe view stored on the graph node."""
-        payload: Dict[str, Any] = {
-            "modality": MODALITY_IMAGE,
-            "width": self.width,
-            "height": self.height,
-            "format": self.image_format,
-            "mode": self.mode,
-            "ocr_status": self.ocr_status,
-            "ocr_chars": len(self.ocr_text),
-            "caption_status": self.caption_status,
-            "vision_embedding": self.embedding_status,
-        }
-        if self.ocr_text:
-            payload["ocr_text"] = self.ocr_text
-        if self.ocr_detail:
-            payload["ocr_detail"] = self.ocr_detail
-        if self.caption:
-            payload["caption"] = self.caption
-        if self.embedding_detail:
-            payload["vision_embedding_detail"] = self.embedding_detail
-        if self.thumbnail:
-            payload["thumbnail"] = self.thumbnail
-        if self.error:
-            payload["image_error"] = self.error
-        return payload
-
-
-def _open_image(path: str) -> Any:
-    """Pillow's ``Image.open`` behind a guarded import."""
-    from PIL import Image  # local import: keeps the module importable without it
-
-    return Image.open(str(path))
-
-
-def _thumbnail_data_uri(image: Any, edge: int = THUMBNAIL_EDGE) -> Optional[str]:
-    """A tiny inline PNG the Evidence panel can render with no new route.
-
-    Serving the original file would mean either a new static route over the
-    user's disk or reusing ``/local/serve``, which exists precisely to make
-    every read pass an explicit approval. A 96px data URI on the node dodges
-    both: it is already inside the graph the user is looking at.
-    """
-    try:
-        small = image.copy()
-        small.thumbnail((edge, edge))
-        if small.mode not in {"RGB", "L"}:
-            small = small.convert("RGB")
-        buffer = io.BytesIO()
-        small.save(buffer, format="PNG")
-    except Exception:  # noqa: BLE001 — a missing thumbnail is not a failed ingest
-        quiet()
-        return None
-    encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
-    if len(encoded) > MAX_THUMBNAIL_CHARS:
-        return None
-    return f"data:image/png;base64,{encoded}"
-
-
-def _run_ocr(image: Any) -> Dict[str, str]:
-    """OCR through ``pytesseract`` when it is installed, honestly otherwise."""
-    try:
-        import pytesseract  # optional local binary + wrapper
-    except Exception as exc:  # noqa: BLE001 — absence is a state, not an error
-        return {"status": "unavailable", "text": "", "detail": str(exc)}
-    try:
-        text = str(pytesseract.image_to_string(image) or "").strip()
-    except Exception as exc:  # noqa: BLE001 — a broken OCR runtime is a state
-        return {"status": "failed", "text": "", "detail": str(exc)}
-    if not text:
-        return {"status": "empty", "text": "", "detail": "no text found in the image"}
-    return {"status": "ok", "text": text[:MAX_INDEX_TEXT_CHARS], "detail": ""}
-
-
-def extract_image_facts(
-    path: str,
-    *,
-    ports: Optional[MultimodalPorts] = None,
-    ocr: bool = True,
-    thumbnail: bool = True,
-) -> ImageFacts:
-    """Observe one image: size, OCR, caption, vector — each with its status.
-
-    Never raises. An unreadable file returns ``ImageFacts(error=...)`` so the
-    caller can record "we saw this file and could not read it" instead of
-    losing the memory entirely.
-    """
-    ports = ports or MultimodalPorts()
-    facts = ImageFacts(path=str(path))
-    try:
-        with _open_image(path) as image:
-            facts.width = int(image.width)
-            facts.height = int(image.height)
-            facts.image_format = image.format
-            facts.mode = image.mode
-            if ocr:
-                result = _run_ocr(image)
-                facts.ocr_status = result["status"]
-                facts.ocr_text = result["text"]
-                facts.ocr_detail = result["detail"]
-            if thumbnail:
-                facts.thumbnail = _thumbnail_data_uri(image)
-    except Exception as exc:  # noqa: BLE001 — an unreadable image is a state
-        facts.error = str(exc)
-        return facts
-
-    if ports.captioner is not None:
-        caption = _safe_caption(ports.captioner, facts.path)
-        if caption:
-            facts.caption = caption
-            facts.caption_status = "ok"
-
-    if ports.vision_embedder is not None:
-        _apply_vision_embedding(facts, ports.vision_embedder)
-    return facts
-
-
-def _safe_caption(
-    captioner: Callable[[str], Optional[str]], path: str
-) -> Optional[str]:
-    """Ask the VLM; a failure means *no caption*, never an invented one."""
-    try:
-        caption = captioner(path)
-    except Exception:  # noqa: BLE001 — a broken captioner must not fail an ingest
-        quiet()
-        return None
-    cleaned = str(caption or "").strip()
-    return cleaned or None
-
-
-def _apply_vision_embedding(
-    facts: ImageFacts, embedder: Callable[[str], List[float]]
-) -> None:
-    try:
-        vector = [float(value) for value in embedder(facts.path)]
-    except Exception as exc:  # noqa: BLE001 — an absent model is not a failed ingest
-        facts.embedding_status = "failed"
-        facts.embedding_detail = str(exc)
-        return
-    if not vector:
-        facts.embedding_status = "failed"
-        facts.embedding_detail = "vision provider returned an empty vector"
-        return
-    facts.embedding = vector
-    facts.embedding_status = "ok"
-
-
-# ── extraction quality for pictures ──────────────────────────────────────────
-def image_quality_score(facts: ImageFacts) -> Dict[str, Any]:
-    """``{"score": float, "reasons": [...]}`` for an image memory.
-
-    Deliberately *not* a judgement about the photograph: it scores how much of
-    this image the Brain can actually retrieve later. Pixels alone are worth
-    little to a text query, OCR text is worth the most, a caption is worth a
-    lot, and a vector is worth something even without either.
-    """
-    if not facts.readable:
-        return {"score": 0.0, "reasons": ["image_unreadable"]}
-    reasons: List[str] = []
-    score = 0.15  # we know it is an image and how big it is
-    if facts.ocr_text:
-        # 400+ characters of recognized text is a page, not a label.
-        score += 0.45 * min(1.0, len(facts.ocr_text) / 400.0)
-        reasons.append("ocr_text")
-    elif facts.ocr_status == "unavailable":
-        reasons.append("ocr_unavailable")
-    elif facts.ocr_status == "skipped":
-        reasons.append("ocr_skipped")
-    else:
-        reasons.append("no_ocr_text")
-    if facts.caption:
-        score += 0.3
-        reasons.append("vision_caption")
-    else:
-        reasons.append("no_vision_caption")
-    if facts.embedding_status == "ok":
-        score += 0.1
-        reasons.append("vision_embedding")
-    return {"score": round(max(0.0, min(1.0, score)), 4), "reasons": reasons}
-
-
-# ── graph write ──────────────────────────────────────────────────────────────
-def _sha256_file(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for block in iter(lambda: handle.read(1024 * 1024), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def _sha256_text(text: str) -> str:
-    return hashlib.sha256(str(text).encode("utf-8", "ignore")).hexdigest()
-
-
-def _split_index_text(text: str) -> List[str]:
-    """Fixed-width split for OCR bodies — no markdown or code structure here."""
-    body = str(text or "").strip()
-    if len(body) <= SUMMARY_CHARS:
-        return []
-    return [
-        body[start : start + IMAGE_CHUNK_CHARS]
-        for start in range(0, len(body), IMAGE_CHUNK_CHARS)
-    ]
-
-
-def image_node_id(content_hash: str, workspace_id: Optional[str] = None) -> str:
-    """Workspace-scoped, content-addressed id — re-ingesting is idempotent."""
-    scoped = f"{workspace_id or 'legacy-global'}|{content_hash}"
-    return f"image:{_sha256_text(scoped)[:24]}"
-
-
-def write_image_memory(
-    store: Any,
-    *,
-    path: Path,
-    facts: ImageFacts,
-    title: str,
-    source_type: str = MODALITY_IMAGE,
-    source_uri: Optional[str] = None,
-    owner: Optional[str] = None,
-    workspace_id: Optional[str] = None,
-    conversation_id: Optional[str] = None,
-    captured_at: Optional[str] = None,
-    modified_at: Optional[str] = None,
-    permissions: Optional[Dict[str, Any]] = None,
-    extra_metadata: Optional[Dict[str, Any]] = None,
-) -> Dict[str, Any]:
-    """Write one ``Image`` node (plus ``ImageText``/chunks) into the graph.
-
-    The node is the image itself rather than a ``Document`` that happens to be
-    a picture, because that is what the rest of the product reasons about: the
-    graph already declares ``Image``/``ImageText``/``CONTAINS_IMAGE``, and
-    ``hybrid_search`` already ranks ``Image`` as a first-class result type.
-
-    Uses the same cross-mixin write door (``_upsert_node``/``_upsert_edge``/
-    ``_upsert_chunk``) that every other ingest path uses — the store exposes no
-    public node writer, and inventing a second one for images would be a
-    parallel write path to keep in sync forever.
-    """
-    captured_at = captured_at or utc_now_iso()
-    content_hash = _sha256_file(path)
-    node_id = image_node_id(content_hash, workspace_id)
-    index_text = facts.index_text()
-    metadata: Dict[str, Any] = {
-        "filename": path.name,
-        "file_path": str(path),
-        "ext": path.suffix.lower(),
-        "bytes": path.stat().st_size,
-        "sha256": content_hash,
-        "content_hash": content_hash,
-        "source_type": source_type,
-        "source_uri": source_uri or str(path),
-        "captured_at": captured_at,
-        "modified_at": modified_at,
-        "owner": owner,
-        "workspace_id": workspace_id,
-        "permissions": permissions or {},
-        "conversation_id": conversation_id,
-        **facts.as_metadata(),
-        **(extra_metadata or {}),
-    }
-    # Honest summary: when nothing could be read out of the picture, say so
-    # rather than leaving a blank card that looks like a failed render.
-    summary = index_text[:SUMMARY_CHARS] or f"[{MODALITY_IMAGE}] {path.name}"
-    chunk_ids: List[str] = []
-
-    with store._connect() as conn:
-        duplicate = (
-            conn.execute("SELECT 1 FROM nodes WHERE id=? LIMIT 1", (node_id,)).fetchone()
-            is not None
-        )
-        store._upsert_node(
-            conn,
-            node_id,
-            "Image",
-            title or path.name,
-            summary=summary,
-            metadata=metadata,
-            raw=metadata,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-        if facts.ocr_text:
-            image_text_id = f"imagetext:{_sha256_text(f'{node_id}:ocr')[:24]}"
-            store._upsert_node(
-                conn,
-                image_text_id,
-                "ImageText",
-                f"{path.name} OCR",
-                summary=facts.ocr_text[:700],
-                metadata={
-                    "source_node": node_id,
-                    "chars": len(facts.ocr_text),
-                    "workspace_id": workspace_id,
-                },
-                owner=owner,
-                workspace_id=workspace_id,
-            )
-            store._upsert_edge(
-                conn,
-                node_id,
-                image_text_id,
-                "포함함",
-                weight=0.8,
-                metadata={"source": "ocr", "workspace_id": workspace_id},
-            )
-        for index, piece in enumerate(_split_index_text(index_text)):
-            chunk_id = f"chunk:{_sha256_text(f'{node_id}:{index}:{piece}')[:24]}"
-            chunk_ids.append(chunk_id)
-            chunk_meta = {
-                "index": index,
-                "source_node": node_id,
-                "workspace_id": workspace_id,
-                "modality": MODALITY_IMAGE,
-            }
-            store._upsert_node(
-                conn,
-                chunk_id,
-                "Chunk",
-                f"{path.name} chunk {index + 1}",
-                summary=piece[:SUMMARY_CHARS],
-                metadata=chunk_meta,
-                owner=owner,
-                workspace_id=workspace_id,
-            )
-            store._upsert_chunk(
-                conn,
-                chunk_id=chunk_id,
-                source_node=node_id,
-                text=piece,
-                metadata=chunk_meta,
-            )
-            store._upsert_edge(conn, node_id, chunk_id, "포함함")
-        # Concepts come from what is *in* the picture, never from its name:
-        # "IMG_2381" is not a topic, and turning filenames into concept nodes
-        # would fill the graph with hubs that mean nothing.
-        concept_ids = _attach_concepts(
-            store,
-            conn,
-            node_id=node_id,
-            text=index_text,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-        source_node_id = _attach_source(
-            store,
-            conn,
-            node_id=node_id,
-            source_type=source_type,
-            source_uri=source_uri or str(path),
-            title=title or path.name,
-            content_hash=content_hash,
-            captured_at=captured_at,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-    metadata["concepts"] = concept_ids
-    return {
-        "node_id": node_id,
-        "type": "Image",
-        "title": title or path.name,
-        "sha256": content_hash,
-        "content_hash": content_hash,
-        "source_node_id": source_node_id,
-        "chunk_ids": chunk_ids,
-        "chunk_count": len(chunk_ids),
-        "duplicate": duplicate,
-        "captured_at": captured_at,
-        "metadata": metadata,
-    }
-
-
-def _attach_concepts(
-    store: Any,
-    conn: Any,
-    *,
-    node_id: str,
-    text: str,
-    owner: Optional[str],
-    workspace_id: Optional[str],
-) -> List[str]:
-    """Pull concepts out of the caption/OCR so the picture joins the graph.
-
-    This is what "the caption contributes to the graph" means concretely: the
-    same extractor every text door uses, over the same text, producing the same
-    ``Concept``/``Feature``/… nodes and ``포함함`` edges — so a photo of a
-    whiteboard about Q3 planning is one hop from every note about Q3 planning,
-    instead of being an island that only exact search can reach.
-
-    An image with nothing readable in it yields no concepts, which is correct:
-    there is nothing to say about it.
-    """
-    body = str(text or "").strip()
-    if not body:
-        return []
-    from .graph._kg_common import (  # local: keeps this module's import light
-        _classify_node_type,
-        _extract_concepts,
-    )
-
-    # The id derivation is imported rather than re-derived: two copies of a
-    # node-id rule diverge, and a diverged id is a duplicate concept nobody
-    # can see.
-    from .graph.ingest import _scoped_slug_id
-
-    concept_ids: List[str] = []
-    for concept in _extract_concepts(body, limit=10):
-        node_type = _classify_node_type(concept, body)
-        concept_id = _scoped_slug_id(node_type.lower(), concept, workspace_id)
-        store._upsert_node(
-            conn,
-            concept_id,
-            node_type,
-            concept,
-            metadata={
-                "auto_extracted": True,
-                "source_node": node_id,
-                "modality": MODALITY_IMAGE,
-                "workspace_id": workspace_id,
-            },
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-        store._upsert_edge(conn, node_id, concept_id, "포함함", weight=0.8)
-        concept_ids.append(concept_id)
-    return concept_ids
-
-
-def _attach_source(
-    store: Any,
-    conn: Any,
-    *,
-    node_id: str,
-    source_type: str,
-    source_uri: str,
-    title: str,
-    content_hash: str,
-    captured_at: str,
-    owner: Optional[str],
-    workspace_id: Optional[str],
-) -> Optional[str]:
-    """Link the image to a ``Source`` node when the store can make one."""
-    attach = getattr(store, "_attach_source_node", None)
-    if not callable(attach):
-        return None
-    return str(
-        attach(
-            conn,
-            node_id,
-            source_type=source_type,
-            source_uri=source_uri,
-            title=title,
-            content_hash=content_hash,
-            captured_at=captured_at,
-            extra={"owner": owner, "workspace_id": workspace_id, "modality": MODALITY_IMAGE},
-        )
-    )
-
-
-# ── audio ────────────────────────────────────────────────────────────────────
-@dataclass
-class AudioFacts:
-    """A recording, its transcript, and how honestly we got one."""
-
-    path: str
-    #: ``ok`` | ``unavailable`` | ``failed`` | ``supplied``
-    transcription_status: str = "unavailable"
-    transcript: str = ""
-    detail: str = ""
-    segments: List[Dict[str, Any]] = field(default_factory=list)
-
-    @property
-    def searchable(self) -> bool:
-        return bool(self.transcript)
-
-
-def transcribe_audio(
-    path: str,
-    *,
-    ports: Optional[MultimodalPorts] = None,
-    transcript: Optional[str] = None,
-) -> AudioFacts:
-    """Transcribe a recording through the injected port, or say why not.
-
-    ``transcript`` lets a caller that already has text (a phone's own
-    dictation, ``VoiceCaptureService``) skip the local model entirely. An
-    absent transcriber yields ``transcription_status="unavailable"`` and an
-    empty transcript — the recording is still remembered by title and path,
-    and the result never claims it is searchable.
-    """
-    ports = ports or MultimodalPorts()
-    supplied = str(transcript or "").strip()
-    if supplied:
-        return AudioFacts(path=str(path), transcription_status="supplied", transcript=supplied)
-    if ports.transcriber is None:
-        return AudioFacts(
-            path=str(path),
-            transcription_status="unavailable",
-            detail="no local transcriber is configured",
-        )
-    try:
-        text = str(ports.transcriber(str(path)) or "").strip()
-    except Exception as exc:  # noqa: BLE001 — a broken transcriber is a state
-        return AudioFacts(path=str(path), transcription_status="failed", detail=str(exc))
-    if not text:
-        return AudioFacts(
-            path=str(path),
-            transcription_status="failed",
-            detail="the transcriber returned no text",
-        )
-    return AudioFacts(path=str(path), transcription_status="ok", transcript=text)
-
-
-def audio_quality_score(facts: AudioFacts) -> Dict[str, Any]:
-    """How much of this recording is actually retrievable later."""
-    if not facts.transcript:
-        return {"score": 0.0, "reasons": ["no_transcript"]}
-    # A transcript is text: length is the only honest extra signal here, and
-    # the text pipeline scores the wording itself downstream.
-    score = 0.5 + 0.5 * min(1.0, len(facts.transcript) / 400.0)
-    return {"score": round(score, 4), "reasons": ["transcript"]}
-
-
-# ── video (v11.2.0) ──────────────────────────────────────────────────────────
-#: The decoder. Looked up by name on PATH and never bundled — a product that
-#: cannot decode a ``.mov`` says so instead of shipping a codec pack.
-FFMPEG_BINARY = "ffmpeg"
-#: Keyframes kept per video. Four is a memory of a video, not a copy of it.
-DEFAULT_KEYFRAMES = 4
-#: Frames ffmpeg's ``thumbnail`` filter considers before picking one. Larger
-#: windows mean more representative frames and a slower pass.
-KEYFRAME_WINDOW = 300
-KEYFRAME_TIMEOUT_SECONDS = 120
-#: Graph node type for a video. ``NodeType.VIDEO`` normalizes this on the KG v2
-#: write side; the legacy tables keep the label verbatim, like ``Audio``.
-VIDEO_NODE_TYPE = "Video"
-#: Source type stamped on the extracted stills so a keyframe is never mistaken
-#: for a photograph the user took.
-VIDEO_FRAME_SOURCE_TYPE = "video_keyframe"
-VIDEO_FRAME_RELATION = "CONTAINS_IMAGE"
-#: Longest subtitle body kept, matching the OCR/caption ceiling.
-MAX_SUBTITLE_CHARS = MAX_INDEX_TEXT_CHARS
-
-_SRT_INDEX_RE = re.compile(r"^\d+$")
-_TIMECODE_RE = re.compile(r"\d{1,2}:\d{2}:\d{2}[.,]\d{1,3}\s*-->")
-_CUE_TAG_RE = re.compile(r"</?[a-zA-Z][^>]*>")
-
-
-def _which_ffmpeg() -> Optional[str]:
-    """Absolute path to ffmpeg, or ``None``. The one probe, seamed for tests."""
-    return shutil.which(FFMPEG_BINARY)
-
-
-def ffmpeg_available() -> bool:
-    """Whether this machine can decode a video at all (honest, never assumed)."""
-    return _which_ffmpeg() is not None
-
-
-def _run_ffmpeg(binary: str, args: List[str]) -> int:
-    """Run one fixed binary with an argv list — no shell, no user strings."""
-    completed = subprocess.run(  # noqa: S603 — argv list, fixed binary, no shell
-        [binary, *args],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-        timeout=KEYFRAME_TIMEOUT_SECONDS,
-        check=False,
-    )
-    return int(completed.returncode)
-
-
-def find_subtitle(path: Any) -> Optional[Path]:
-    """The ``.srt``/``.vtt`` sitting next to a video under the same basename."""
-    video = Path(str(path))
-    for suffix in SUBTITLE_EXTENSIONS:
-        candidate = video.with_suffix(f".{suffix}")
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def parse_subtitles(text: str) -> str:
-    """Strip SRT/WebVTT scaffolding down to the words that were said.
-
-    Cue numbers, timecodes, ``WEBVTT`` headers, ``NOTE`` blocks and inline
-    ``<c>``/``<i>`` tags carry no recall value and would otherwise dominate a
-    chunk. Consecutive duplicate lines (the usual rolling-caption artefact) are
-    collapsed. Deliberately a small parser, not a dependency: the format is two
-    rules deep and a library here would sit in the ingest path forever.
-    """
-    lines: List[str] = []
-    for raw in str(text or "").splitlines():
-        line = raw.strip().lstrip("")
-        if not line or line.upper().startswith("WEBVTT") or line.startswith("NOTE"):
-            continue
-        if _SRT_INDEX_RE.match(line) or _TIMECODE_RE.search(line):
-            continue
-        cleaned = _CUE_TAG_RE.sub("", line).strip()
-        if not cleaned:
-            continue
-        if lines and lines[-1] == cleaned:
-            continue
-        lines.append(cleaned)
-    return "\n".join(lines)[:MAX_SUBTITLE_CHARS]
-
-
-@dataclass
-class VideoFacts:
-    """What could actually be observed in one video, and how each attempt went."""
-
-    path: str
-    #: ``ok`` | ``unavailable`` | ``failed`` | ``empty``
-    keyframe_status: str = "unavailable"
-    keyframes: List[str] = field(default_factory=list)
-    keyframe_detail: str = ""
-    #: ``ok`` | ``absent`` | ``unreadable`` | ``empty``
-    subtitle_status: str = "absent"
-    subtitle_path: Optional[str] = None
-    subtitle_text: str = ""
-
-    @property
-    def searchable(self) -> bool:
-        """Whether anything in this video can be matched by a typed question."""
-        return bool(self.subtitle_text)
-
-    def as_metadata(self) -> Dict[str, Any]:
-        payload: Dict[str, Any] = {
-            "modality": MODALITY_VIDEO,
-            "video_path": self.path,
-            "keyframes": len(self.keyframes),
-            "keyframe_status": self.keyframe_status,
-            "subtitles": self.subtitle_status,
-            "searchable": self.searchable,
-        }
-        if self.keyframe_detail:
-            payload["keyframe_detail"] = self.keyframe_detail
-        if self.subtitle_path:
-            payload["subtitle_path"] = self.subtitle_path
-        return payload
-
-
-def extract_keyframes(
-    path: Any,
-    dest_dir: Any,
-    *,
-    count: int = DEFAULT_KEYFRAMES,
-    ports: Optional[MultimodalPorts] = None,
-) -> Dict[str, Any]:
-    """Pull up to ``count`` representative stills out of a video.
-
-    An injected ``ports.keyframe_extractor`` wins outright — that is the seam
-    an install with its own decoder (or a test) uses. Otherwise ffmpeg's
-    ``thumbnail`` filter picks the most representative frame from each window
-    of :data:`KEYFRAME_WINDOW` frames, which is one pass and no probing.
-
-    Never raises. A missing decoder, a non-zero exit, and a video too short to
-    yield a single frame are three different states and each says so.
-    """
-    ports = ports or MultimodalPorts()
-    video = Path(str(path))
-    dest = Path(str(dest_dir))
-    wanted = max(1, int(count))
-    if ports.keyframe_extractor is not None:
-        return _injected_keyframes(ports.keyframe_extractor, video, dest, wanted)
-    binary = _which_ffmpeg()
-    if binary is None:
-        return {"status": "unavailable", "frames": [], "detail": VIDEO_UNAVAILABLE_DETAIL}
-    dest.mkdir(parents=True, exist_ok=True)
-    args = [
-        "-nostdin", "-loglevel", "error", "-y",
-        "-i", str(video),
-        "-vf", f"thumbnail={KEYFRAME_WINDOW}",
-        "-frames:v", str(wanted),
-        "-vsync", "vfr",
-        str(dest / "keyframe-%03d.jpg"),
-    ]
-    try:
-        code = _run_ffmpeg(binary, args)
-    except Exception as exc:  # noqa: BLE001 — a broken decoder is a state
-        return {"status": "failed", "frames": [], "detail": f"ffmpeg failed: {exc}"}
-    frames = sorted(str(p) for p in dest.glob("keyframe-*.jpg"))
-    if code != 0 and not frames:
-        return {
-            "status": "failed",
-            "frames": [],
-            "detail": f"ffmpeg exited with status {code}",
-        }
-    if not frames:
-        return {
-            "status": "empty",
-            "frames": [],
-            "detail": "ffmpeg produced no frames from this video",
-        }
-    return {"status": "ok", "frames": frames[:wanted], "detail": ""}
-
-
-def _injected_keyframes(
-    extractor: Callable[..., Any], video: Path, dest: Path, wanted: int
-) -> Dict[str, Any]:
-    """Run a caller-supplied extractor; a failure is reported, never raised."""
-    try:
-        produced = extractor(str(video), str(dest), wanted)
-    except Exception as exc:  # noqa: BLE001 — an injected port is not trusted more
-        return {"status": "failed", "frames": [], "detail": f"keyframe port failed: {exc}"}
-    frames = [str(item) for item in (produced or [])][:wanted]
-    if not frames:
-        return {
-            "status": "empty",
-            "frames": [],
-            "detail": "the keyframe port produced no frames",
-        }
-    return {"status": "ok", "frames": frames, "detail": ""}
-
-
-def read_video_facts(
-    path: Any,
-    dest_dir: Any,
-    *,
-    count: int = DEFAULT_KEYFRAMES,
-    ports: Optional[MultimodalPorts] = None,
-    subtitle_text: Optional[str] = None,
-) -> VideoFacts:
-    """Observe one video: its keyframes and its companion subtitles."""
-    facts = VideoFacts(path=str(path))
-    outcome = extract_keyframes(path, dest_dir, count=count, ports=ports)
-    facts.keyframe_status = str(outcome["status"])
-    facts.keyframes = list(outcome["frames"])
-    facts.keyframe_detail = str(outcome["detail"])
-    supplied = str(subtitle_text or "").strip()
-    if supplied:
-        facts.subtitle_status = "ok"
-        facts.subtitle_text = parse_subtitles(supplied)
-        return facts
-    companion = find_subtitle(path)
-    if companion is None:
-        return facts
-    facts.subtitle_path = str(companion)
-    try:
-        raw = companion.read_text(encoding="utf-8", errors="ignore")
-    except OSError as exc:
-        facts.subtitle_status = "unreadable"
-        facts.keyframe_detail = (facts.keyframe_detail or "").strip()
-        facts.subtitle_text = ""
-        quiet()
-        facts.subtitle_path = f"{companion} ({exc.strerror or 'unreadable'})"
-        return facts
-    parsed = parse_subtitles(raw)
-    facts.subtitle_status = "ok" if parsed else "empty"
-    facts.subtitle_text = parsed
-    return facts
-
-
-def video_quality_score(facts: VideoFacts) -> Dict[str, Any]:
-    """How much of this video the Brain can actually retrieve later.
-
-    Same principle as :func:`image_quality_score`: not a judgement about the
-    footage. Subtitles are worth the most (they are the words), keyframes are
-    worth something (they can be OCR'd and seen), and a video with neither is
-    a filename.
-    """
-    reasons: List[str] = []
-    score = 0.1  # we know it is a video and where it lives
-    if facts.subtitle_text:
-        score += 0.55 * min(1.0, len(facts.subtitle_text) / 400.0)
-        reasons.append("subtitles")
-    else:
-        reasons.append(f"no_subtitles_{facts.subtitle_status}")
-    if facts.keyframes:
-        score += min(0.35, 0.1 * len(facts.keyframes))
-        reasons.append("keyframes")
-    else:
-        reasons.append(f"no_keyframes_{facts.keyframe_status}")
-    return {"score": round(max(0.0, min(1.0, score)), 4), "reasons": reasons}
-
-
-def video_node_id(content_hash: str, workspace_id: Optional[str] = None) -> str:
-    """Workspace-scoped, content-addressed id — re-ingesting is idempotent."""
-    scoped = f"{workspace_id or 'legacy-global'}|{content_hash}"
-    return f"video:{_sha256_text(scoped)[:24]}"
-
-
-def video_frame_dir(blob_dir: Any, content_hash: str) -> Path:
-    """Where this video's stills live: content-addressed, stable across runs.
-
-    Deliberately under the Brain's own blob directory rather than a temp dir.
-    A frame referenced by an ``Image`` node has to still be there the next time
-    someone opens that memory, and a backup that copies the blobs copies these.
-    """
-    return Path(str(blob_dir)) / "video_frames" / str(content_hash)[:32]
-
-
-def write_video_memory(
-    store: Any,
-    *,
-    path: Path,
-    facts: VideoFacts,
-    title: str,
-    source_type: str = MODALITY_VIDEO,
-    source_uri: Optional[str] = None,
-    owner: Optional[str] = None,
-    workspace_id: Optional[str] = None,
-    conversation_id: Optional[str] = None,
-    captured_at: Optional[str] = None,
-    modified_at: Optional[str] = None,
-    permissions: Optional[Dict[str, Any]] = None,
-    extra_metadata: Optional[Dict[str, Any]] = None,
-    ports: Optional[MultimodalPorts] = None,
-) -> Dict[str, Any]:
-    """Write one ``Video`` node, its keyframes, and its subtitles.
-
-    Each keyframe goes through the **existing image path** — the same
-    :func:`extract_image_facts` and :func:`write_image_memory` a photograph
-    uses — so a still from a video is OCR'd, captioned, vectorized and made
-    searchable by exactly the machinery that already does that, and joined to
-    its video by ``CONTAINS_IMAGE``. Subtitles ride the ordinary text index as
-    chunks. Nothing about video gets its own retrieval path.
-
-    The frames are written before the video node so their (short-lived) write
-    transactions never nest inside the video's.
-    """
-    ports = ports or MultimodalPorts()
-    captured_at = captured_at or utc_now_iso()
-    content_hash = _sha256_file(path)
-    node_id = video_node_id(content_hash, workspace_id)
-    frames = _write_keyframes(
-        store,
-        facts=facts,
-        title=title,
-        owner=owner,
-        workspace_id=workspace_id,
-        conversation_id=conversation_id,
-        captured_at=captured_at,
-        permissions=permissions,
-        ports=ports,
-    )
-    body = facts.subtitle_text or (
-        f"[{MODALITY_VIDEO}] {title}\n"
-        "이 영상에는 자막이 없어 말의 내용은 검색되지 않습니다 — "
-        "대신 대표 장면 이미지로 찾을 수 있습니다."
-    )
-    metadata: Dict[str, Any] = {
-        "filename": path.name,
-        "file_path": str(path),
-        "ext": path.suffix.lower(),
-        "bytes": path.stat().st_size,
-        "sha256": content_hash,
-        "content_hash": content_hash,
-        "source_type": source_type,
-        "source_uri": source_uri or str(path),
-        "captured_at": captured_at,
-        "modified_at": modified_at,
-        "owner": owner,
-        "workspace_id": workspace_id,
-        "permissions": permissions or {},
-        "conversation_id": conversation_id,
-        "keyframe_nodes": [frame["node_id"] for frame in frames],
-        **facts.as_metadata(),
-        **(extra_metadata or {}),
-    }
-    # Honest card: a video nobody captioned says so, rather than rendering as a
-    # blank summary that looks like a failed read.
-    summary = body[:SUMMARY_CHARS]
-    chunk_ids: List[str] = []
-    with store._connect() as conn:
-        duplicate = (
-            conn.execute("SELECT 1 FROM nodes WHERE id=? LIMIT 1", (node_id,)).fetchone()
-            is not None
-        )
-        store._upsert_node(
-            conn,
-            node_id,
-            VIDEO_NODE_TYPE,
-            title or path.name,
-            summary=summary,
-            metadata=metadata,
-            raw=metadata,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-        for frame in frames:
-            store._upsert_edge(
-                conn,
-                node_id,
-                frame["node_id"],
-                VIDEO_FRAME_RELATION,
-                weight=0.8,
-                metadata={
-                    "source": VIDEO_FRAME_SOURCE_TYPE,
-                    "index": frame["index"],
-                    "workspace_id": workspace_id,
-                },
-            )
-        for index, piece in enumerate(_split_index_text(facts.subtitle_text)):
-            chunk_id = f"chunk:{_sha256_text(f'{node_id}:{index}:{piece}')[:24]}"
-            chunk_ids.append(chunk_id)
-            chunk_meta = {
-                "index": index,
-                "source_node": node_id,
-                "workspace_id": workspace_id,
-                "modality": MODALITY_VIDEO,
-            }
-            store._upsert_node(
-                conn,
-                chunk_id,
-                "Chunk",
-                f"{path.name} chunk {index + 1}",
-                summary=piece[:SUMMARY_CHARS],
-                metadata=chunk_meta,
-                owner=owner,
-                workspace_id=workspace_id,
-            )
-            store._upsert_chunk(
-                conn,
-                chunk_id=chunk_id,
-                source_node=node_id,
-                text=piece,
-                metadata=chunk_meta,
-            )
-            store._upsert_edge(conn, node_id, chunk_id, "포함함")
-        concept_ids = _attach_concepts(
-            store,
-            conn,
-            node_id=node_id,
-            text=facts.subtitle_text,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-        source_node_id = _attach_source(
-            store,
-            conn,
-            node_id=node_id,
-            source_type=source_type,
-            source_uri=source_uri or str(path),
-            title=title or path.name,
-            content_hash=content_hash,
-            captured_at=captured_at,
-            owner=owner,
-            workspace_id=workspace_id,
-        )
-    metadata["concepts"] = concept_ids
-    return {
-        "node_id": node_id,
-        "type": VIDEO_NODE_TYPE,
-        "title": title or path.name,
-        "sha256": content_hash,
-        "content_hash": content_hash,
-        "source_node_id": source_node_id,
-        "chunk_ids": chunk_ids,
-        "chunk_count": len(chunk_ids),
-        "duplicate": duplicate,
-        "captured_at": captured_at,
-        "keyframes": frames,
-        "metadata": metadata,
-    }
-
-
-def _write_keyframes(
-    store: Any,
-    *,
-    facts: VideoFacts,
-    title: str,
-    owner: Optional[str],
-    workspace_id: Optional[str],
-    conversation_id: Optional[str],
-    captured_at: str,
-    permissions: Optional[Dict[str, Any]],
-    ports: MultimodalPorts,
-) -> List[Dict[str, Any]]:
-    """Every extracted still, through the ordinary image door."""
-    written: List[Dict[str, Any]] = []
-    for index, frame_path in enumerate(facts.keyframes):
-        frame = Path(frame_path)
-        image_facts = extract_image_facts(str(frame), ports=ports)
-        if not image_facts.readable:
-            # A frame ffmpeg wrote that Pillow cannot open is a state worth
-            # skipping, not worth failing the whole video over.
-            continue
-        result = write_image_memory(
-            store,
-            path=frame,
-            facts=image_facts,
-            title=f"{title} · 장면 {index + 1}",
-            source_type=VIDEO_FRAME_SOURCE_TYPE,
-            source_uri=str(frame),
-            owner=owner,
-            workspace_id=workspace_id,
-            conversation_id=conversation_id,
-            captured_at=captured_at,
-            permissions=permissions,
-            extra_metadata={
-                "modality": MODALITY_IMAGE,
-                "video_path": facts.path,
-                "keyframe_index": index,
-            },
-        )
-        written.append({
-            "node_id": result["node_id"],
-            "index": index,
-            "path": str(frame),
-            "ocr_status": image_facts.ocr_status,
-            "vision_embedding": image_facts.embedding_status,
-        })
-    return written
-
-
-__all__ = [
-    "AUDIO_EXTENSIONS",
-    "DEFAULT_KEYFRAMES",
-    "FFMPEG_BINARY",
-    "IMAGE_CHUNK_CHARS",
-    "IMAGE_EXTENSIONS",
-    "MAX_INDEX_TEXT_CHARS",
-    "MAX_SUBTITLE_CHARS",
-    "MAX_THUMBNAIL_CHARS",
-    "MODALITY_AUDIO",
-    "MODALITY_IMAGE",
-    "MODALITY_TEXT",
-    "MODALITY_VIDEO",
-    "SUBTITLE_EXTENSIONS",
-    "SUMMARY_CHARS",
-    "THUMBNAIL_EDGE",
-    "VIDEO_EXTENSIONS",
-    "VIDEO_FRAME_RELATION",
-    "VIDEO_FRAME_SOURCE_TYPE",
-    "VIDEO_NODE_TYPE",
-    "VIDEO_OUT_OF_SCOPE",
-    "VIDEO_UNAVAILABLE_DETAIL",
-    "AudioFacts",
-    "ImageFacts",
-    "MultimodalPorts",
-    "VideoFacts",
-    "audio_quality_score",
-    "detect_modality",
-    "extract_image_facts",
-    "extract_keyframes",
-    "ffmpeg_available",
-    "find_subtitle",
-    "image_node_id",
-    "image_quality_score",
-    "parse_subtitles",
-    "read_video_facts",
-    "transcribe_audio",
-    "video_frame_dir",
-    "video_node_id",
-    "video_quality_score",
-    "write_image_memory",
-    "write_video_memory",
-]