ltcai 11.2.0 → 11.4.0

package/lattice_brain/ingestion/quality.py

@@ -0,0 +1,209 @@
+"""Advisory extraction-quality scoring, and the capture CTA built on it.
+
+Pure heuristics over already-extracted text — no model call, no network, and
+deterministic. The score never blocks an ingest; it annotates the result so a
+capture surface can say "this capture is thin" and offer a way to fix it
+instead of silently storing junk.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+# ── Extraction quality heuristics (v9.8.0 A1) ────────────────────────────────
+# Pure heuristics over the extracted text — no model calls, no network. The
+# score is *advisory*: it never blocks an ingest, it only annotates the result
+# so capture surfaces (browser, folder scan) can surface low-quality warnings.
+QUALITY_HIGH_THRESHOLD = 0.7
+QUALITY_LOW_THRESHOLD = 0.4
+QUALITY_LOW_WARNING = "추출 품질이 낮습니다 — 원문 확인을 권장합니다."
+_WEB_SOURCE_TYPES = frozenset({"web_url", "browser_tab"})
+# Standalone short lines that smell like leftover site chrome (nav/menu/footer).
+_BOILERPLATE_LINE_MARKERS = frozenset(
+    {
+        "home", "menu", "nav", "navigation", "login", "log in", "sign in",
+        "sign up", "register", "subscribe", "search", "about", "about us",
+        "contact", "contact us", "privacy policy", "terms of service",
+        "cookie policy", "accept cookies", "accept all cookies", "share",
+        "skip to content", "copyright", "all rights reserved", "sitemap",
+        "back to top", "footer", "read more", "next", "previous",
+    }
+)
+
+
+def _quality_level(score: float) -> str:
+    if score >= QUALITY_HIGH_THRESHOLD:
+        return "high"
+    if score >= QUALITY_LOW_THRESHOLD:
+        return "medium"
+    return "low"
+
+
+def assess_extraction_quality(
+    text: Optional[str],
+    *,
+    source_type: Optional[str] = None,
+    upstream_confidence: Optional[Any] = None,
+) -> Dict[str, Any]:
+    """Score extracted text 0..1 with reasons (pure heuristic, deterministic).
+
+    Signals: text length, whitespace ratio, character/word diversity
+    (repetition), sentence structure, and — for web sources — leftover
+    nav/menu boilerplate. When the upstream extractor supplies its own
+    confidence (``upstream_confidence``), that value wins verbatim: the
+    extractor saw the raw document, this function only sees its output.
+    """
+    if upstream_confidence is not None:
+        try:
+            score = max(0.0, min(1.0, float(upstream_confidence)))
+        except (TypeError, ValueError):
+            score = None
+        if score is not None:
+            return {
+                "score": round(score, 4),
+                "level": _quality_level(score),
+                "reasons": ["upstream_confidence"],
+            }
+
+    raw = str(text or "")
+    stripped = raw.strip()
+    if not stripped:
+        return {"score": 0.0, "level": "low", "reasons": ["empty_text"]}
+
+    reasons: List[str] = []
+    length = len(stripped)
+    sample = stripped[:4000]
+    lines = [ln.strip() for ln in stripped.splitlines() if ln.strip()]
+    words = stripped.split()
+
+    # 1) Length — very short extractions rarely carry recall value.
+    if length < 40:
+        length_factor = 0.35
+        reasons.append("very_short_text")
+    elif length < 120:
+        length_factor = 0.6
+        reasons.append("short_text")
+    elif length < 300:
+        length_factor = 0.85
+    else:
+        length_factor = 1.0
+
+    # 2) Sentence structure — prose has sentence-ending punctuation.
+    sentence_marks = sum(sample.count(mark) for mark in (".", "!", "?", "…", "。", "！", "？"))
+    if sentence_marks > 0:
+        structure_factor = 1.0
+    elif length < 200:
+        structure_factor = 0.75  # titles/snippets legitimately lack periods
+    else:
+        structure_factor = 0.45
+        reasons.append("no_sentence_structure")
+
+    # 3) Diversity — repeated characters/lines/words indicate extraction junk.
+    diversity_factor = 1.0
+    distinct_chars = len(set(sample.lower()))
+    if distinct_chars < 10:
+        diversity_factor *= 0.2
+        reasons.append("low_character_diversity")
+    elif distinct_chars < 20:
+        diversity_factor *= 0.7
+    if len(lines) >= 6:
+        top_count = max(lines.count(ln) for ln in set(lines))
+        if top_count >= max(3, len(lines) // 4):
+            diversity_factor *= 0.5
+            reasons.append("repetitive_lines")
+    if len(words) >= 30 and (len(set(w.lower() for w in words)) / len(words)) < 0.25:
+        diversity_factor *= 0.5
+        reasons.append("repetitive_words")
+
+    # 4) Cleanliness — whitespace floods, fragmented lines, site chrome.
+    cleanliness_factor = 1.0
+    whitespace_ratio = sum(1 for ch in raw if ch.isspace()) / max(1, len(raw))
+    if whitespace_ratio > 0.45:
+        cleanliness_factor *= 0.6
+        reasons.append("high_whitespace_ratio")
+    if len(lines) >= 8:
+        short_lines = sum(1 for ln in lines if len(ln.split()) <= 3)
+        if short_lines / len(lines) > 0.6:
+            cleanliness_factor *= 0.6
+            reasons.append("fragmented_lines")
+    boilerplate_hits = sum(
+        1 for ln in lines if ln.lower().strip(" .:>|•·-–—*") in _BOILERPLATE_LINE_MARKERS
+    )
+    if lines and boilerplate_hits >= 3 and (boilerplate_hits / len(lines)) > 0.2:
+        cleanliness_factor *= 0.35
+        if str(source_type or "").lower() in _WEB_SOURCE_TYPES:
+            reasons.append("nav_menu_remnants")
+        else:
+            reasons.append("boilerplate_markers")
+
+    score = length_factor * structure_factor * diversity_factor * cleanliness_factor
+    score = max(0.0, min(1.0, score))
+    if not reasons:
+        reasons.append("clean_extraction")
+    return {"score": round(score, 4), "level": _quality_level(score), "reasons": reasons}
+
+
+# ── capture quality CTA (backlog #9, review §7.2 C) ──────────────────────────
+# Structured verdict over the same extraction-quality schema the rest of the
+# pipeline uses, so capture surfaces (browser extension, read-url) can render
+# an honest "this capture is thin" CTA instead of silently storing junk.
+CAPTURE_SUGGESTIONS_THIN = ["recapture", "paste_manually", "highlight_source"]
+_CAPTURE_REASON_LABELS = {
+    "empty_text": "추출된 본문이 비어 있습니다",
+    "very_short_text": "추출된 본문이 매우 짧습니다",
+    "short_text": "추출된 본문이 짧습니다",
+    "no_sentence_structure": "문장 구조가 거의 없습니다",
+    "low_character_diversity": "반복 문자가 대부분입니다",
+    "repetitive_lines": "같은 줄이 반복됩니다",
+    "repetitive_words": "같은 단어가 반복됩니다",
+    "high_whitespace_ratio": "공백이 지나치게 많습니다",
+    "fragmented_lines": "줄이 잘게 조각나 있습니다",
+    "nav_menu_remnants": "메뉴/내비게이션 잔여물이 많습니다",
+    "boilerplate_markers": "상용구 텍스트가 많습니다",
+    "no_extracted_text": "추출된 텍스트가 없습니다",
+}
+
+
+def capture_quality_verdict(
+    extraction_quality: Optional[Dict[str, Any]],
+    *,
+    source_type: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Structured CTA verdict from a pipeline ``extraction_quality`` dict.
+
+    ``{"status": "thin"|"ok", "reason": str|None, "suggestions": [...],
+    "score": float|None, "level": str|None}``. ``thin`` (level == "low", the
+    same threshold as the ingest warning) carries actionable suggestions —
+    ``recapture`` / ``paste_manually`` / ``highlight_source`` — so the UI can
+    offer the user a way to fix the capture instead of hiding the problem.
+    Deterministic and never raises; ``None`` input yields an honest ``thin``.
+    """
+    if not isinstance(extraction_quality, dict):
+        return {
+            "status": "thin",
+            "reason": _CAPTURE_REASON_LABELS["no_extracted_text"],
+            "reason_codes": ["no_extracted_text"],
+            "suggestions": list(CAPTURE_SUGGESTIONS_THIN),
+            "score": None,
+            "level": None,
+        }
+    level = str(extraction_quality.get("level") or "")
+    score = extraction_quality.get("score")
+    reasons = [str(item) for item in (extraction_quality.get("reasons") or [])]
+    thin = level == "low"
+    reason = None
+    if thin:
+        labeled = [
+            _CAPTURE_REASON_LABELS[code]
+            for code in reasons
+            if code in _CAPTURE_REASON_LABELS
+        ]
+        reason = "; ".join(labeled) if labeled else QUALITY_LOW_WARNING
+    return {
+        "status": "thin" if thin else "ok",
+        "reason": reason,
+        "reason_codes": reasons if thin else [],
+        "suggestions": list(CAPTURE_SUGGESTIONS_THIN) if thin else [],
+        "score": score,
+        "level": level or None,
+    }

package/lattice_brain/ingestion/routing.py

@@ -0,0 +1,295 @@
+"""One door per kind of thing: text, chat, memory record, picture, film, file.
+
+Every method here returns the raw store payload that ``IngestionPipeline.\
+ingest`` normalizes; none of them decide *whether* to run. Modality routing
+(:meth:`IngestionRoutingMixin._modality_for`) answers ``"text"`` for everything
+while multi-modal is off, which is what makes "off" mean *unchanged* rather than
+*slightly different*.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict
+
+from ..multimodal import (
+    MODALITY_AUDIO,
+    MODALITY_IMAGE,
+    MODALITY_VIDEO,
+    ImageFacts,
+    audio_quality_score,
+    detect_modality,
+    extract_image_facts,
+    image_quality_score,
+    read_video_facts,
+    transcribe_audio,
+    video_frame_dir,
+    video_quality_score,
+    write_image_memory,
+    write_video_memory,
+)
+from ..utils import utc_now_iso
+from ._contract import IngestionCore as _Core
+from .constants import (
+    _MEMORY_NODE_TYPES,
+    AUDIO_NODE_TYPE,
+    AUDIO_SOURCE_TYPES,
+    IMAGE_SOURCE_TYPES,
+    VIDEO_SOURCE_TYPES,
+)
+from .hashing import _file_digest
+from .models import IngestionItem
+from .quality import _quality_level
+
+
+class IngestionRoutingMixin(_Core):
+    """The per-source-type ingest doors. Mixed into ``IngestionPipeline``."""
+
+    # ── routing helpers ──────────────────────────────────────────────────────
+    def _ingest_text(self, item, *, source_type, owner, captured_at) -> Dict[str, Any]:
+        text = item.text or ""
+        if not text.strip():
+            raise ValueError(
+                f"Empty content: {source_type} ingestion requires non-empty text."
+            )
+        if len(text.encode("utf-8", "ignore")) > self._max_text_bytes:
+            raise ValueError(
+                f"Text payload exceeds the {self._max_text_bytes // (1024 * 1024)}MB ingestion limit."
+            )
+        title = item.title or item.source_uri or source_type
+        return self._kg.ingest_source(
+            source_type=source_type,
+            title=title,
+            text=text,
+            source_uri=item.source_uri,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            conversation_id=item.conversation_id,
+            metadata={"mime_type": item.mime_type, **(item.metadata or {})},
+        )
+
+    def _ingest_chat(self, item, *, source_type, owner) -> Dict[str, Any]:
+        text = item.text or ""
+        meta = item.metadata or {}
+        role = str(meta.get("role") or "user")
+        result = self._kg.ingest_message(
+            role,
+            text,
+            user_email=owner,
+            user_nickname=meta.get("user_nickname"),
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            workspace_id=item.workspace_id,
+            raw=meta.get("raw"),
+        )
+        # ingest_message reports message/response node ids; normalize the keys
+        # the provenance step expects.
+        result.setdefault("node_id", result.get("node_id") or result.get("message_node_id") or result.get("id"))
+        result.setdefault("title", item.title or text[:80])
+        return result
+
+    def _ingest_memory_record(self, item, *, source_type, owner) -> Dict[str, Any]:
+        node_type = _MEMORY_NODE_TYPES[source_type]
+        meta = item.metadata or {}
+        result = self._kg.ingest_event(
+            node_type,
+            item.title or (item.text or node_type)[:120],
+            user_email=owner,
+            source=meta.get("source") or source_type,
+            conversation_id=item.conversation_id,
+            workspace_id=item.workspace_id,
+            metadata={**meta, "detail": (item.text or "")[:2000]},
+        )
+        result.setdefault("node_id", result.get("node_id") or result.get("id"))
+        result.setdefault("title", item.title)
+        return result
+
+    # ── 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)
+        if not path.exists():
+            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,
+            mime_type=item.mime_type,
+            uploader=owner,
+            conversation_id=item.conversation_id,
+            extracted=item.metadata.get("extracted") if item.metadata else None,
+            source_type=source_type,
+            source_uri=item.source_uri or str(path),
+            captured_at=captured_at,
+            modified_at=item.modified_at,
+            owner=owner,
+            workspace_id=item.workspace_id,
+            permissions=item.permissions,
+        )

package/lattice_brain/multimodal/__init__.py

@@ -0,0 +1,164 @@
+"""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``.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``common``
+(taxonomy + shared helpers), ``ports`` (injected capabilities + the ffmpeg
+fallback), ``images``, ``audio``, ``video``. This module re-exports every name
+the single file exposed, so ``lattice_brain.multimodal.X`` keeps working.
+"""
+
+from __future__ import annotations
+
+# Internals that predate the split. They are not public API, but they were
+# reachable as ``lattice_brain.multimodal.<name>`` before it and callers (and
+# tests) still reach them that way, so they are re-exported explicitly. The
+# redundant-alias form says "this is a re-export", not a leftover import.
+#
+# Stubbing note: replacing one of these *here* rebinds only this module's name.
+# The submodule that calls it holds its own reference, so a test that wants to
+# stand in for ``_which_ffmpeg`` patches ``lattice_brain.multimodal.ports``.
+from ..quiet import quiet as quiet
+from ..utils import utc_now_iso as utc_now_iso
+from .audio import AudioFacts, audio_quality_score, transcribe_audio
+from .common import (
+    AUDIO_EXTENSIONS,
+    IMAGE_CHUNK_CHARS,
+    IMAGE_EXTENSIONS,
+    MAX_INDEX_TEXT_CHARS,
+    MAX_THUMBNAIL_CHARS,
+    MODALITY_AUDIO,
+    MODALITY_IMAGE,
+    MODALITY_TEXT,
+    MODALITY_VIDEO,
+    SUBTITLE_EXTENSIONS,
+    SUMMARY_CHARS,
+    THUMBNAIL_EDGE,
+    VIDEO_EXTENSIONS,
+    VIDEO_OUT_OF_SCOPE,
+    VIDEO_UNAVAILABLE_DETAIL,
+    detect_modality,
+)
+from .common import _sha256_file as _sha256_file
+from .common import _sha256_text as _sha256_text
+from .common import _split_index_text as _split_index_text
+from .images import (
+    ImageFacts,
+    extract_image_facts,
+    image_node_id,
+    image_quality_score,
+    write_image_memory,
+)
+from .images import _apply_vision_embedding as _apply_vision_embedding
+from .images import _attach_concepts as _attach_concepts
+from .images import _attach_source as _attach_source
+from .images import _open_image as _open_image
+from .images import _run_ocr as _run_ocr
+from .images import _safe_caption as _safe_caption
+from .images import _thumbnail_data_uri as _thumbnail_data_uri
+from .ports import (
+    DEFAULT_KEYFRAMES,
+    FFMPEG_BINARY,
+    MultimodalPorts,
+    extract_keyframes,
+    ffmpeg_available,
+)
+from .ports import KEYFRAME_TIMEOUT_SECONDS as KEYFRAME_TIMEOUT_SECONDS
+from .ports import KEYFRAME_WINDOW as KEYFRAME_WINDOW
+from .ports import _injected_keyframes as _injected_keyframes
+from .ports import _run_ffmpeg as _run_ffmpeg
+from .ports import _which_ffmpeg as _which_ffmpeg
+from .video import _CUE_TAG_RE as _CUE_TAG_RE
+from .video import _SRT_INDEX_RE as _SRT_INDEX_RE
+from .video import _TIMECODE_RE as _TIMECODE_RE
+from .video import (
+    MAX_SUBTITLE_CHARS,
+    VIDEO_FRAME_RELATION,
+    VIDEO_FRAME_SOURCE_TYPE,
+    VIDEO_NODE_TYPE,
+    VideoFacts,
+    find_subtitle,
+    parse_subtitles,
+    read_video_facts,
+    video_frame_dir,
+    video_node_id,
+    video_quality_score,
+    write_video_memory,
+)
+from .video import _write_keyframes as _write_keyframes
+
+__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",
+]