ltcai 11.0.1 → 11.2.0

package/lattice_brain/graph/schema.py

@@ -128,6 +128,17 @@ class NodeType(str, Enum):
     PREFERENCE = "PREFERENCE"  # 선호 (좋아함/싫어함/선호 방식)
     HABIT = "HABIT"  # 습관 (반복되는 행동)
     RELATIONSHIP = "RELATIONSHIP"  # 관계 (동료/친구/멘토 등)
+    # v11.1.0 Multi-modal (Track 3) — a recording is its own noun. It used to
+    # enter through the text door as a DOCUMENT because "a transcript *is*
+    # text"; that is true of the transcript and false of the recording, which
+    # exists whether or not anyone could hear it. IMAGE has been first-class
+    # since 3.6.0 for the same reason, and AUDIO now sits beside it.
+    AUDIO = "AUDIO"  # 녹음 / 음성 메모
+    # v11.2.0 — a video is its own noun for the same reason a recording is:
+    # keyframes and subtitles are *derived* from it (IMAGE children, text
+    # chunks), and calling the thing they came from a DOCUMENT would make the
+    # source of a memory indistinguishable from one of its pieces.
+    VIDEO = "VIDEO"  # 영상 / 화면 녹화
 
     @classmethod
     def from_legacy(cls, label: str) -> "NodeType":
@@ -276,6 +287,13 @@ _LEGACY_NODE_MAP: Dict[str, NodeType] = {
     "relationship": NodeType.RELATIONSHIP,
     "관계": NodeType.RELATIONSHIP,
     "결정": NodeType.DECISION,
+    # v11.1.0 Multi-modal — recordings as a first-class noun.
+    "audio": NodeType.AUDIO,
+    "오디오": NodeType.AUDIO,
+    # v11.2.0 — videos likewise.
+    "video": NodeType.VIDEO,
+    "영상": NodeType.VIDEO,
+    "동영상": NodeType.VIDEO,
 }
 
 _LEGACY_EDGE_MAP: Dict[str, EdgeType] = {

package/lattice_brain/graph/store.py

@@ -241,6 +241,15 @@ class KnowledgeGraphStore(
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_type ON vector_embeddings(item_type);
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_source ON vector_embeddings(source_node);
                     CREATE INDEX IF NOT EXISTS idx_vector_embeddings_model ON vector_embeddings(embedding_model);
+                    -- v11.2.0: the ANN sidecar's freshness fingerprint is
+                    -- COUNT(*) + MAX(indexed_at) filtered by (embedding_model,
+                    -- embedding_dim), and it runs on *every* approximate
+                    -- search. Against the single-column model index that was a
+                    -- table scan of every row for the current model; this
+                    -- covering index answers both aggregates from the index
+                    -- alone. Additive and idempotent — no data is rewritten.
+                    CREATE INDEX IF NOT EXISTS idx_vector_embeddings_model_dim_indexed
+                      ON vector_embeddings(embedding_model, embedding_dim, indexed_at);
                     CREATE INDEX IF NOT EXISTS idx_vector_index_operations_requested ON vector_index_operations(requested_at);
                     CREATE INDEX IF NOT EXISTS idx_provenance_node ON ingestion_provenance(node_id);
                     CREATE INDEX IF NOT EXISTS idx_provenance_source_type ON ingestion_provenance(source_type);

package/lattice_brain/graph/vector_index/selector.py

@@ -11,13 +11,21 @@ exactly like "search is a bit worse today":
 
 Both resolve to the exact brute-force scan and carry a ``detail`` string
 naming the cause, which ``index_status()`` and the search result surface.
+
+The backend is a *choice*, not a switch, so it cannot ride a
+:class:`~lattice_brain.gates.FeatureGate` (which answers booleans). It gets the
+same shape of seam instead: :func:`bind_vector_index_resolver` installs a
+caller-supplied resolver that is consulted ahead of the environment, which is
+what lets the settings panel change the backend without a restart. With nothing
+bound — the default — the environment variable is still the whole control
+surface, exactly as before.
 """
 
 from __future__ import annotations
 
 import os
 from dataclasses import dataclass
-from typing import Any, Dict, Optional
+from typing import Any, Callable, Dict, Optional
 
 from .base import Similarity, VectorIndex
 from .brute_force import BRUTE_FORCE_BACKEND, BruteForceIndex
@@ -37,6 +45,23 @@ _BACKEND_LABELS = {
 _APPROX = {"brute": False, "quantized": True, "hnsw": True}
 _EXHAUSTIVE = {"brute": True, "quantized": True, "hnsw": False}
 
+#: App-layer resolver, consulted before the environment. ``None`` (the default)
+#: leaves this module reading exactly the env var it always read.
+_RESOLVER: Optional[Callable[[], Optional[str]]] = None
+
+
+def bind_vector_index_resolver(
+    resolver: Optional[Callable[[], Optional[str]]],
+) -> None:
+    """Delegate backend selection to a callable (``None`` hands it back to env).
+
+    A resolver that returns ``None`` also falls through to the environment, so
+    "the settings service has no opinion" and "there is no settings service"
+    reach the same answer instead of two.
+    """
+    global _RESOLVER
+    _RESOLVER = resolver
+
 
 @dataclass(frozen=True)
 class BackendSelection:
@@ -79,7 +104,11 @@ def _selection(name: str, *, requested: str, detail: Optional[str]) -> BackendSe
 
 def resolve_vector_index(requested: Optional[str] = None) -> BackendSelection:
     """Resolve the configured backend (never raises, always falls back safe)."""
-    raw = requested if requested is not None else os.getenv(VECTOR_INDEX_ENV, "")
+    raw = requested
+    if raw is None and _RESOLVER is not None:
+        raw = _RESOLVER()
+    if raw is None:
+        raw = os.getenv(VECTOR_INDEX_ENV, "")
     name = str(raw or "").strip().lower() or DEFAULT_VECTOR_INDEX
     if name not in VECTOR_INDEX_CHOICES:
         return _selection(
@@ -126,6 +155,7 @@ __all__ = [
     "VECTOR_INDEX_CHOICES",
     "VECTOR_INDEX_ENV",
     "BackendSelection",
+    "bind_vector_index_resolver",
     "build_index",
     "resolve_vector_index",
 ]

package/lattice_brain/ingestion.py

@@ -46,7 +46,31 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, Iterable, List, Optional, Tuple
 
+from .gates import FeatureGate
 from .graph.vector_index import DEFAULT_TICK_LIMIT as VECTOR_TICK_LIMIT
+from .multimodal import (
+    AUDIO_EXTENSIONS,
+    DEFAULT_KEYFRAMES,
+    IMAGE_EXTENSIONS,
+    MODALITY_AUDIO,
+    MODALITY_IMAGE,
+    MODALITY_VIDEO,
+    VIDEO_EXTENSIONS,
+    VIDEO_UNAVAILABLE_DETAIL,
+    ImageFacts,
+    MultimodalPorts,
+    audio_quality_score,
+    detect_modality,
+    extract_image_facts,
+    ffmpeg_available,
+    image_quality_score,
+    read_video_facts,
+    transcribe_audio,
+    video_frame_dir,
+    video_quality_score,
+    write_image_memory,
+    write_video_memory,
+)
 from .runtime.hooks import dispatch_tool
 from .utils import utc_now_iso
 
@@ -111,6 +135,59 @@ DEFAULT_MAX_FILE_BYTES = 4_000_000  # matches the local-index text/code budget
 LATTICEIGNORE_FILENAME = ".latticeignore"
 # Opt-out escape hatch for the post-ingest incremental vector sync.
 AUTO_VECTOR_INDEX_ENV = "LATTICEAI_AUTO_VECTOR_INDEX"
+#: Default *on*, unlike every other gate here: new material has always been made
+#: searchable straight away, and this exists so a settings surface can turn that
+#: off (batch reindex later) without a restart. ``FeatureGate`` parses the env
+#: var with the same words the hand-written opt-out check used, so an untouched
+#: install — including one with a nonsense value — answers exactly as before.
+AUTO_VECTOR_INDEX_GATE = FeatureGate(
+    AUTO_VECTOR_INDEX_ENV,
+    default=True,
+    name="auto_vector_index",
+    detail="New material is prepared for semantic search as soon as it lands.",
+)
+
+# ── Multi-modal ingestion (v11.1.0 Track 3) ──────────────────────────────────
+# Opt-in, default off, on purpose. Turning it on changes what a folder scan
+# *stores* (pictures and recordings, with OCR and — if a model is loaded —
+# captions and vectors), and that is the user's call, not a default. With the
+# flag off every routing decision below is skipped and behaviour is byte-for-
+# byte what it was before this release.
+ALLOW_MULTIMODAL_ENV = "LATTICEAI_ALLOW_MULTIMODAL"
+#: The multi-modal switch, resolved when it is asked rather than frozen into
+#: ``self`` at construction (v11.2.0). The environment variable is still the
+#: answer for an untouched install — same var, same words, same default off —
+#: but a settings surface can bind a resolver and move it without a restart.
+MULTIMODAL_GATE = FeatureGate(
+    ALLOW_MULTIMODAL_ENV,
+    default=False,
+    name="allow_multimodal",
+    detail="Pictures and recordings are only ingested when this is turned on.",
+)
+#: Video is a *sub-switch* of the one above: with multi-modal off nothing about
+#: video happens at all, and with it on video is included unless this is
+#: explicitly turned off. The effective default is therefore still "no video",
+#: and the seam exists so a settings screen can offer pictures without films.
+ALLOW_VIDEO_ENV = "LATTICEAI_ALLOW_VIDEO"
+VIDEO_GATE = FeatureGate(
+    ALLOW_VIDEO_ENV,
+    default=True,
+    name="allow_video",
+    detail="Videos are ingested as keyframes plus subtitles when multi-modal is on.",
+)
+#: Source types that name a modality outright (a caller who already knows).
+IMAGE_SOURCE_TYPES = frozenset({"image", "screenshot", "photo"})
+AUDIO_SOURCE_TYPES = frozenset({"audio", "voice_memo", "recording"})
+VIDEO_SOURCE_TYPES = frozenset({"video", "screen_recording", "movie"})
+#: Added to the folder-scan allow-list only while multimodal is enabled.
+FOLDER_MULTIMODAL_EXTENSIONS = IMAGE_EXTENSIONS | AUDIO_EXTENSIONS
+#: Videos join the folder allow-list only when this machine can decode one —
+#: scanning a folder into a pile of refusals is not a feature.
+FOLDER_VIDEO_EXTENSIONS = VIDEO_EXTENSIONS
+#: Graph node type for a recording. ``NodeType.AUDIO`` normalizes this on the
+#: KG v2 write side; the legacy tables keep the label verbatim, which is what
+#: every type-aware read (graph view, context sections, doc-gen) matches on.
+AUDIO_NODE_TYPE = "Audio"
 
 # ── Extraction quality heuristics (v9.8.0 A1) ────────────────────────────────
 # Pure heuristics over the extracted text — no model calls, no network. The
@@ -448,6 +525,8 @@ class IngestionPipeline:
         pipeline_name: str = "unified-ingestion",
         bg_queue: Optional[BackgroundIngestionQueue] = None,
         auto_vector_index: bool = True,
+        allow_multimodal: bool = False,
+        multimodal: Optional[MultimodalPorts] = None,
     ) -> None:
         self._kg = knowledge_graph
         self._hooks = hooks
@@ -464,16 +543,79 @@ class IngestionPipeline:
             db_path=getattr(knowledge_graph, "db_path", None)
         )
         # Incremental vector sync after each successful non-duplicate ingest.
-        # Constructor opt-out AND env opt-out (LATTICEAI_AUTO_VECTOR_INDEX=0)
-        # both disable it; a vector failure never fails the ingest.
-        env_flag = os.getenv(AUTO_VECTOR_INDEX_ENV, "1").strip().lower() not in {
-            "0", "false", "no", "off",
-        }
-        self._auto_vector_index = bool(auto_vector_index) and env_flag
+        # Constructor opt-out AND gate opt-out (LATTICEAI_AUTO_VECTOR_INDEX=0,
+        # or the settings toggle bound to it) both disable it; a vector failure
+        # never fails the ingest. The gate half is asked per ingest rather than
+        # frozen here, so turning it off takes effect on the next item.
+        self._auto_vector_index_opt_in = bool(auto_vector_index)
+        # Multi-modal routing. Off unless the caller asks for it *or* the gate
+        # says yes — the env behind that gate is the escape hatch for an
+        # install with no code path to the constructor (CLI, background
+        # worker), and the gate is now asked per call so a runtime toggle can
+        # reach it. A constructor ``True`` is still a permanent yes.
+        self._multimodal_opt_in = bool(allow_multimodal)
+        self._multimodal = multimodal or MultimodalPorts()
+        self._keyframes = DEFAULT_KEYFRAMES
+
+    @property
+    def _auto_vector_index(self) -> bool:
+        """Whether a landed ingest also syncs its vector, asked *now*."""
+        return self._auto_vector_index_opt_in and AUTO_VECTOR_INDEX_GATE.enabled()
+
+    @property
+    def _allow_multimodal(self) -> bool:
+        """Whether pictures and recordings route by modality, asked *now*."""
+        return self._multimodal_opt_in or MULTIMODAL_GATE.enabled()
+
+    @property
+    def _allow_video(self) -> bool:
+        """Video needs multi-modal on, its own sub-switch on, and a decoder."""
+        return self._allow_multimodal and VIDEO_GATE.enabled() and self._can_decode_video()
+
+    def _can_decode_video(self) -> bool:
+        """An injected keyframe port counts as a decoder; otherwise, ffmpeg."""
+        return self._multimodal.keyframe_extractor is not None or ffmpeg_available()
 
     def available(self) -> bool:
         return self._enable and self._kg is not None
 
+    def multimodal_status(self) -> Dict[str, Any]:
+        """What this pipeline will do with a picture or a recording, honestly.
+
+        ``enabled`` is the flag; the rest is which model-backed capabilities
+        were actually injected. Video reports whether it can really run — the
+        answer is no on a machine with no ffmpeg, and it says which of the two
+        reasons applies rather than leaving the surface to guess.
+        """
+        allowed = self._allow_multimodal
+        video = self._allow_video
+        return {
+            "enabled": allowed,
+            "image": allowed,
+            "audio": allowed,
+            "video": video,
+            "video_detail": None if video else self._video_refusal(),
+            "gates": {
+                "multimodal": MULTIMODAL_GATE.describe(),
+                "video": VIDEO_GATE.describe(),
+            },
+            **self._multimodal.describe(),
+        }
+
+    def _video_refusal(self) -> str:
+        """Why a video would be refused right now — never a stale reason."""
+        if not self._allow_multimodal:
+            return (
+                "multi-modal ingestion is off; pictures, recordings and videos "
+                f"are only stored when {ALLOW_MULTIMODAL_ENV} is on"
+            )
+        if not VIDEO_GATE.enabled():
+            return (
+                "video ingestion is turned off for this install "
+                f"({ALLOW_VIDEO_ENV}); pictures and recordings are unaffected"
+            )
+        return VIDEO_UNAVAILABLE_DETAIL
+
     # ── public API ───────────────────────────────────────────────────────────
     def ingest(self, item: IngestionItem, *, user_email: Optional[str] = None) -> IngestionResult:
         """Normalize, hash, route through dispatch_tool, and record provenance."""
@@ -485,6 +627,18 @@ class IngestionPipeline:
                 detail="Knowledge Graph is disabled (LATTICEAI_ENABLE_GRAPH).",
             )
 
+        # Modality routing is a no-op while the flag is off: ``modality`` stays
+        # "text" and every branch below behaves exactly as it did before.
+        modality = self._modality_for(item, source_type)
+        if modality == MODALITY_VIDEO and not self._allow_video:
+            # Recognized and refused, with the reason that actually applies
+            # right now — a missing decoder is not the same answer as a
+            # switched-off feature, and the caller can act on the difference.
+            return IngestionResult(
+                status="unavailable", source_type=source_type,
+                indexing_status="skipped", detail=self._video_refusal(),
+            )
+
         captured_at = item.captured_at or utc_now_iso()
         owner = item.owner or user_email
         tool_name = f"kg_ingest.{source_type}"
@@ -501,6 +655,12 @@ class IngestionPipeline:
                 return self._ingest_chat(item, source_type=source_type, owner=owner)
             if source_type in MEMORY_SOURCE_TYPES:
                 return self._ingest_memory_record(item, source_type=source_type, owner=owner)
+            if modality == MODALITY_IMAGE:
+                return self._ingest_image(item, source_type=source_type, owner=owner, captured_at=captured_at)
+            if modality == MODALITY_AUDIO:
+                return self._ingest_audio(item, source_type=source_type, owner=owner, captured_at=captured_at)
+            if modality == MODALITY_VIDEO:
+                return self._ingest_video(item, source_type=source_type, owner=owner, captured_at=captured_at)
             if source_type in FILE_SOURCE_TYPES or (item.path and not item.text):
                 return self._ingest_file(item, source_type=source_type, owner=owner, captured_at=captured_at)
             return self._ingest_text(item, source_type=source_type, owner=owner, captured_at=captured_at)
@@ -590,7 +750,11 @@ class IngestionPipeline:
             except Exception:  # noqa: BLE001 — audit must never break ingestion
                 quiet()
 
-        extraction_quality = self._assess_item_quality(
+        # A modality-aware door scores its own extraction (a picture's quality
+        # is "how much of it can be retrieved", not "does the text read well"),
+        # so its verdict wins. Text/file doors never set the key and keep the
+        # historical scoring untouched.
+        extraction_quality = raw.get("extraction_quality") or self._assess_item_quality(
             item, source_type=source_type, text=quality_text, chunk_ids=chunk_ids,
         )
         warnings: List[str] = []
@@ -980,7 +1144,7 @@ class IngestionPipeline:
         allowed_exts = (
             frozenset(str(e).lower() if str(e).startswith(".") else f".{str(e).lower()}" for e in extensions)
             if extensions
-            else DEFAULT_FOLDER_EXTENSIONS
+            else self._folder_extensions()
         )
         patterns = _load_latticeignore(root)
         errors: List[Dict[str, Any]] = summary["errors"]
@@ -1036,7 +1200,11 @@ class IngestionPipeline:
                     summary["truncated"] = True
                     break
                 item_metadata: Dict[str, Any] = {"relative_path": rel}
-                if ext in FOLDER_DOCUMENT_EXTENSIONS:
+                if ext in (FOLDER_MULTIMODAL_EXTENSIONS | FOLDER_VIDEO_EXTENSIONS) and self._allow_multimodal:
+                    # Routed by modality inside ``ingest``; reading the bytes as
+                    # UTF-8 here would only produce mojibake.
+                    source_type = "file"
+                elif ext in FOLDER_DOCUMENT_EXTENSIONS:
                     source_type = "pdf"
                 else:
                     source_type = "file"
@@ -1080,6 +1248,19 @@ class IngestionPipeline:
         summary["status"] = "ok" if summary["failed"] == 0 else "partial"
         return summary
 
+    def _folder_extensions(self) -> frozenset:
+        """Folder-scan allow-list — pictures, recordings and films when enabled.
+
+        Video joins only when this machine can actually decode one, so a scan
+        never fills the error list with files it was always going to refuse.
+        """
+        if not self._allow_multimodal:
+            return DEFAULT_FOLDER_EXTENSIONS
+        allowed = DEFAULT_FOLDER_EXTENSIONS | FOLDER_MULTIMODAL_EXTENSIONS
+        if self._allow_video:
+            return allowed | FOLDER_VIDEO_EXTENSIONS
+        return allowed
+
     # ── routing helpers ──────────────────────────────────────────────────────
     def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
         text = item.text or ""
@@ -1142,7 +1323,26 @@ class IngestionPipeline:
         result.setdefault("title", item.title)
         return result
 
-    def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+    # ── multi-modal routing (v11.1.0 Track 3) ────────────────────────────────
+    def _modality_for(self, item: IngestionItem, source_type: str) -> str:
+        """``image`` / ``audio`` / ``video`` / ``text`` for this item.
+
+        Always ``"text"`` while the flag is off, which is what makes "off" mean
+        *unchanged* rather than *slightly different*.
+        """
+        if not self._allow_multimodal:
+            return "text"
+        if source_type in IMAGE_SOURCE_TYPES:
+            return MODALITY_IMAGE
+        if source_type in AUDIO_SOURCE_TYPES:
+            return MODALITY_AUDIO
+        if source_type in VIDEO_SOURCE_TYPES:
+            return MODALITY_VIDEO
+        if not item.path:
+            return "text"
+        return detect_modality(item.path, item.mime_type)
+
+    def _resolve_file_path(self, item: IngestionItem) -> Path:
         if not item.path:
             raise ValueError("File ingestion requires a path.")
         path = Path(item.path)
@@ -1150,6 +1350,150 @@ class IngestionPipeline:
             raise FileNotFoundError(f"File not found: {path}")
         if path.is_dir():
             raise ValueError(f"File ingestion requires a file, got a directory: {path}")
+        return path
+
+    def _ingest_image(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        """Store one picture as an ``Image`` node — OCR, caption, vector.
+
+        The image vector (when a vision model produced one) goes to its own
+        index; the OCR/caption text rides the ordinary text index. That split
+        is what lets a typed question find a screenshot without ever comparing
+        a text vector to an image vector.
+        """
+        path = self._resolve_file_path(item)
+        facts = extract_image_facts(str(path), ports=self._multimodal)
+        result = write_image_memory(
+            self._kg,
+            path=path,
+            facts=facts,
+            title=item.title or path.name,
+            source_type=source_type if source_type in IMAGE_SOURCE_TYPES else MODALITY_IMAGE,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            conversation_id=item.conversation_id,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            permissions=item.permissions,
+            extra_metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+        )
+        self._record_image_vector(result["node_id"], facts)
+        quality = image_quality_score(facts)
+        result["extraction_quality"] = {
+            "score": quality["score"],
+            "level": _quality_level(quality["score"]),
+            "reasons": quality["reasons"],
+        }
+        return result
+
+    def _record_image_vector(self, node_id: str, facts: ImageFacts) -> None:
+        """File the image-space vector, if a vision model actually made one."""
+        if facts.embedding is None:
+            return
+        from .graph.image_vectors import record_image_vector
+
+        record_image_vector(
+            self._kg,
+            node_id=node_id,
+            vector=facts.embedding,
+            model_id=self._multimodal.vision_model_id or "vision:unnamed",
+            space=self._multimodal.vision_space,
+            updated_at=utc_now_iso(),
+        )
+
+    def _ingest_audio(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        """Store one recording as an ``Audio`` node, transcribed when possible.
+
+        The transcript is text and rides the ordinary text index — chunks,
+        concepts, provenance, dedupe all unchanged — but the node itself is a
+        recording, because that is what it is whether or not anyone could hear
+        it. The recording's own facts stay in the metadata (``modality``,
+        ``audio_path``, ``transcription``, ``searchable``). Without a
+        transcriber the memory is still kept, and its body says plainly that
+        the words were never recognized instead of leaving a blank note.
+        """
+        path = self._resolve_file_path(item)
+        facts = transcribe_audio(str(path), ports=self._multimodal, transcript=item.text)
+        title = item.title or path.stem
+        body = facts.transcript or (
+            f"[{MODALITY_AUDIO}] {title}\n"
+            "이 녹음은 아직 글로 바뀌지 않았습니다 — 음성 인식기가 없어 내용 검색은 되지 않습니다."
+        )
+        result = self._kg.ingest_source(
+            source_type=source_type,
+            title=title,
+            text=body,
+            source_uri=item.source_uri or str(path),
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            conversation_id=item.conversation_id,
+            node_type=AUDIO_NODE_TYPE,
+            metadata={
+                "mime_type": item.mime_type,
+                "modality": MODALITY_AUDIO,
+                "audio_path": str(path),
+                "audio_bytes": path.stat().st_size,
+                "transcription": facts.transcription_status,
+                "searchable": facts.searchable,
+                **({"transcription_detail": facts.detail} if facts.detail else {}),
+                **(item.metadata or {}),
+            },
+        )
+        result.setdefault("title", title)
+        quality = audio_quality_score(facts)
+        result["extraction_quality"] = {
+            "score": quality["score"],
+            "level": _quality_level(quality["score"]),
+            "reasons": quality["reasons"],
+        }
+        return result
+
+    def _ingest_video(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        """Store one video as keyframes through the image door plus subtitles.
+
+        Nothing here is a new retrieval path: the stills become ordinary
+        ``Image`` nodes (OCR, caption, vector, thumbnail) joined by
+        ``CONTAINS_IMAGE``, and the subtitle text becomes ordinary chunks. What
+        the ``Video`` node adds is the thing they belong to — and an honest
+        body when there were no subtitles to read.
+        """
+        path = self._resolve_file_path(item)
+        facts = read_video_facts(
+            str(path),
+            video_frame_dir(getattr(self._kg, "blob_dir", path.parent), _file_digest(path)),
+            count=self._keyframes,
+            ports=self._multimodal,
+            subtitle_text=item.text,
+        )
+        result = write_video_memory(
+            self._kg,
+            path=path,
+            facts=facts,
+            title=item.title or path.stem,
+            source_type=source_type if source_type in VIDEO_SOURCE_TYPES else MODALITY_VIDEO,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            conversation_id=item.conversation_id,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            permissions=item.permissions,
+            extra_metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+            ports=self._multimodal,
+        )
+        quality = video_quality_score(facts)
+        result["extraction_quality"] = {
+            "score": quality["score"],
+            "level": _quality_level(quality["score"]),
+            "reasons": quality["reasons"],
+        }
+        return result
+
+    def _ingest_file(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        path = self._resolve_file_path(item)
         return self._kg.ingest_document(
             path,
             original_filename=item.title or path.name,
@@ -1170,3 +1514,12 @@ class IngestionPipeline:
 def content_hash_text(text: str) -> str:
     """Canonical content hash for a text payload (matches store hashing scheme)."""
     return hashlib.sha256((text or "").encode("utf-8", "ignore")).hexdigest()
+
+
+def _file_digest(path: Path) -> str:
+    """Streaming sha256 of a file — the key a video's frame folder is named by."""
+    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()