bilisum 1.13.2 → 1.13.3

package/runtime/apps/service/src/video_sum_service/integrations.py

@@ -0,0 +1,264 @@
+import io
+import json
+import wave
+
+import httpx
+from fastapi import HTTPException
+
+from video_sum_infra.config import ServiceSettings
+from video_sum_infra.runtime import service_log_path
+
+from video_sum_service.context import COVER_CACHE_DIR, settings_manager
+from video_sum_service.settings_manager import SettingsUpdatePayload
+
+MAX_LOG_CHARS = 20_000
+MAX_LOG_LINE_CHARS = 1_000
+
+
+def trim_log_text(content: str, *, max_chars: int = MAX_LOG_CHARS, max_line_chars: int = MAX_LOG_LINE_CHARS) -> str:
+    lines = content.splitlines()
+    trimmed_lines = [
+        f"{line[:max_line_chars]}... [line truncated]"
+        if len(line) > max_line_chars
+        else line
+        for line in lines
+    ]
+    trimmed = "\n".join(trimmed_lines)
+    if len(trimmed) <= max_chars:
+        return trimmed
+    return f"... [log truncated, showing last {max_chars} chars]\n{trimmed[-max_chars:]}"
+
+
+def read_log_tail(max_lines: int = 200) -> str:
+    log_path = service_log_path()
+    if not log_path.exists():
+        return ""
+    try:
+        lines = log_path.read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError:
+        return ""
+    return trim_log_text("\n".join(lines[-max(1, max_lines) :]))
+
+
+def cache_cover_image(source_url: str, canonical_id: str, referer_url: str | None = None) -> str:
+    if not source_url:
+        return ""
+    normalized_source = source_url.replace("http://", "https://")
+    COVER_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    target = COVER_CACHE_DIR / f"{canonical_id}.jpg"
+    if target.exists():
+        return f"/media/covers/{target.name}"
+    try:
+        headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0 Safari/537.36"
+            ),
+            "Referer": referer_url or "https://www.bilibili.com/",
+        }
+        with httpx.Client(timeout=30, follow_redirects=True, headers=headers) as client:
+            response = client.get(normalized_source)
+            response.raise_for_status()
+        target.write_bytes(response.content)
+        return f"/media/covers/{target.name}"
+    except Exception:
+        return normalized_source
+
+
+def extract_http_error_detail(response: httpx.Response) -> str:
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+
+    if isinstance(payload, dict):
+        for key in ("detail", "message", "error", "msg"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    text = (response.text or "").strip()
+    return text or f"HTTP {response.status_code}"
+
+
+def extract_llm_message_content(body: dict[str, object] | None) -> str:
+    if not isinstance(body, dict):
+        return ""
+    choices = body.get("choices")
+    if not isinstance(choices, list) or not choices:
+        return ""
+    first = choices[0]
+    if not isinstance(first, dict):
+        return ""
+    message = first.get("message")
+    if not isinstance(message, dict):
+        return ""
+    content = message.get("content")
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        text_parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str) and text.strip():
+                    text_parts.append(text.strip())
+        return "\n".join(text_parts).strip()
+    return ""
+
+
+def build_test_wav_bytes(duration_ms: int = 250, sample_rate: int = 16000) -> bytes:
+    frame_count = max(1, int(sample_rate * duration_ms / 1000))
+    buffer = io.BytesIO()
+    with wave.open(buffer, "wb") as wav_file:
+        wav_file.setnchannels(1)
+        wav_file.setsampwidth(2)
+        wav_file.setframerate(sample_rate)
+        wav_file.writeframes(b"\x00\x00" * frame_count)
+    return buffer.getvalue()
+
+
+def probe_llm_connection(payload: SettingsUpdatePayload | None = None) -> dict[str, object]:
+    current_settings = settings_manager.current
+    updates = payload.model_dump(exclude_none=True) if payload is not None else {}
+    effective_settings = ServiceSettings.model_validate(
+        {**current_settings.model_dump(mode="json"), **updates}
+    )
+
+    base_url = str(effective_settings.llm_base_url or "").strip().rstrip("/")
+    api_key = str(effective_settings.llm_api_key or "").strip()
+    model = str(effective_settings.llm_model or "").strip()
+
+    if not base_url:
+        raise HTTPException(status_code=400, detail="请先填写 API Base URL。")
+    if not api_key:
+        raise HTTPException(status_code=400, detail="请先填写 API Key。")
+    if not model:
+        raise HTTPException(status_code=400, detail="请先填写模型名称。")
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    request_payload = {
+        "model": model,
+        "messages": [
+            {
+                "role": "system",
+                "content": "你是一个 JSON 测试助手。你只能返回合法 JSON，不能输出任何额外文字。",
+            },
+            {
+                "role": "user",
+                "content": (
+                    "请只返回一个合法 JSON 对象，不要带 markdown 代码块，不要带解释。"
+                    '格式必须是：{"ok":true,"message":"test"}'
+                ),
+            },
+        ],
+        "temperature": 0,
+        "max_tokens": 64,
+    }
+
+    try:
+        with httpx.Client(timeout=20, follow_redirects=True) as client:
+            response = client.post(
+                f"{base_url}/chat/completions",
+                headers=headers,
+                json=request_payload,
+            )
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail=f"LLM 连接失败：{exc}") from exc
+
+    if response.status_code >= 400:
+        detail = extract_http_error_detail(response)
+        raise HTTPException(
+            status_code=response.status_code,
+            detail=f"LLM 测试失败：{detail}",
+        )
+
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    preview = extract_llm_message_content(body)
+    if not preview:
+        raise HTTPException(status_code=502, detail="LLM 测试失败：接口已连通，但没有返回可读取的消息内容。")
+
+    try:
+        parsed_json = json.loads(preview)
+    except json.JSONDecodeError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"LLM 测试失败：接口可访问，但当前模型未返回合法 JSON。{exc.msg}",
+        ) from exc
+
+    preview = preview[:200]
+    return {
+        "ok": True,
+        "message": f"LLM 连接与 JSON 输出测试成功：{model}",
+        "model": model,
+        "baseUrl": base_url,
+        "responsePreview": preview,
+        "jsonOutputAvailable": True,
+        "jsonPreview": json.dumps(parsed_json, ensure_ascii=False)[:200],
+    }
+
+
+def probe_asr_connection(payload: SettingsUpdatePayload | None = None) -> dict[str, object]:
+    current_settings = settings_manager.current
+    updates = payload.model_dump(exclude_none=True) if payload is not None else {}
+    effective_settings = ServiceSettings.model_validate(
+        {**current_settings.model_dump(mode="json"), **updates}
+    )
+
+    base_url = str(effective_settings.siliconflow_asr_base_url or "").strip().rstrip("/")
+    api_key = str(effective_settings.siliconflow_asr_api_key or "").strip()
+    model = str(effective_settings.siliconflow_asr_model or "").strip()
+
+    if not base_url:
+        raise HTTPException(status_code=400, detail="请先填写 SiliconFlow Base URL。")
+    if not api_key:
+        raise HTTPException(status_code=400, detail="请先填写 SiliconFlow API Key。")
+    if not model:
+        raise HTTPException(status_code=400, detail="请先填写 ASR 模型名称。")
+
+    headers = {"Authorization": f"Bearer {api_key}"}
+    request_url = f"{base_url}/audio/transcriptions"
+    audio_bytes = build_test_wav_bytes()
+
+    try:
+        timeout = httpx.Timeout(connect=20.0, read=90.0, write=90.0, pool=20.0)
+        with httpx.Client(timeout=timeout) as client:
+            response = client.post(
+                request_url,
+                headers=headers,
+                data={"model": model},
+                files={"file": ("bilisum-asr-test.wav", audio_bytes, "audio/wav")},
+            )
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail=f"ASR 连接失败：{exc}") from exc
+
+    if response.status_code in {401, 403}:
+        detail = extract_http_error_detail(response)
+        raise HTTPException(status_code=response.status_code, detail=f"ASR 测试失败：认证失败，{detail}")
+    if response.status_code >= 400:
+        detail = extract_http_error_detail(response)
+        raise HTTPException(status_code=response.status_code, detail=f"ASR 测试失败：{detail}")
+
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    transcript = str(body.get("text") or "").strip() if isinstance(body, dict) else ""
+    return {
+        "ok": True,
+        "message": (
+            f"ASR 连接测试成功：{model}"
+            if transcript
+            else f"ASR 连接测试成功：{model}（接口已响应，但测试音频未返回文本）"
+        ),
+        "model": model,
+        "baseUrl": base_url,
+        "responsePreview": transcript[:120],
+    }

package/runtime/apps/service/src/video_sum_service/knowledge/__init__.py

@@ -0,0 +1,5 @@
+from video_sum_service.knowledge.index_service import KnowledgeIndexService
+from video_sum_service.knowledge.rag_service import RagService
+from video_sum_service.knowledge.tag_service import TagService
+
+__all__ = ["KnowledgeIndexService", "RagService", "TagService"]

package/runtime/apps/service/src/video_sum_service/knowledge/index_service.py

@@ -0,0 +1,408 @@
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import json
+import logging
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from fastapi import HTTPException
+
+from video_sum_infra.config import ServiceSettings
+from video_sum_infra.runtime import activate_runtime_pythonpath, app_data_root
+from video_sum_service.repository import SqliteTaskRepository
+from video_sum_service.schemas import KnowledgeIndexChunkRecord, KnowledgeSearchResult
+
+logger = logging.getLogger("video_sum_service.knowledge")
+
+
+def format_anchor_seconds(seconds: float | None) -> str | None:
+    if seconds is None:
+        return None
+    total = max(0, int(seconds))
+    minutes, sec = divmod(total, 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours:02d}:{minutes:02d}:{sec:02d}"
+    return f"{minutes:02d}:{sec:02d}"
+
+
+class KnowledgeIndexService:
+    def __init__(
+        self,
+        repository: SqliteTaskRepository,
+        settings: ServiceSettings,
+        chroma_path: str | Path | None = None,
+        model_name: str = "BAAI/bge-small-zh-v1.5",
+    ) -> None:
+        self._repository = repository
+        self._settings = settings
+        self._model_name = model_name
+        self._chroma_path = Path(chroma_path or (app_data_root() / "knowledge_index"))
+        self._embedder = None
+        self._collection = None
+
+    def _ensure_runtime_import_path(self) -> None:
+        activate_runtime_pythonpath(self._settings.runtime_channel)
+
+    def _short_error(self, exc: BaseException, *, limit: int = 500) -> str:
+        message = str(exc).strip() or exc.__class__.__name__
+        return message if len(message) <= limit else f"{message[:limit]}..."
+
+    def _import_runtime_dependency(self, module_name: str, package_label: str, missing_detail: str):
+        self._ensure_runtime_import_path()
+        spec = importlib.util.find_spec(module_name)
+        if spec is None:
+            logger.warning(
+                "knowledge dependency missing package=%s module=%s runtime_channel=%s sys_path_tail=%s",
+                package_label,
+                module_name,
+                self._settings.runtime_channel,
+                sys.path[-5:],
+            )
+            raise HTTPException(status_code=500, detail=missing_detail)
+        try:
+            return importlib.import_module(module_name)
+        except Exception as exc:
+            logger.exception(
+                "knowledge dependency import failed package=%s module=%s runtime_channel=%s origin=%s sys_path_tail=%s",
+                package_label,
+                module_name,
+                self._settings.runtime_channel,
+                getattr(spec, "origin", ""),
+                sys.path[-5:],
+            )
+            raise HTTPException(
+                status_code=500,
+                detail=(
+                    f"{package_label} 已安装但加载失败：{self._short_error(exc)}。"
+                    "请在设置的知识库板块重新安装依赖，或先同步当前 runtime。"
+                ),
+            ) from exc
+
+    def _get_embedder(self):
+        if self._embedder is None:
+            sentence_transformers = self._import_runtime_dependency(
+                "sentence_transformers",
+                "sentence-transformers",
+                "缺少 sentence-transformers 依赖，无法构建知识库索引。",
+            )
+            try:
+                self._embedder = sentence_transformers.SentenceTransformer(self._model_name)
+            except Exception as exc:
+                logger.exception(
+                    "knowledge embedding model load failed model=%s runtime_channel=%s",
+                    self._model_name,
+                    self._settings.runtime_channel,
+                )
+                raise HTTPException(
+                    status_code=500,
+                    detail=(
+                        f"知识库向量模型加载失败：{self._short_error(exc)}。"
+                        "请检查网络 / HuggingFace 缓存，或稍后重试。"
+                    ),
+                ) from exc
+        return self._embedder
+
+    def _get_collection(self):
+        if self._collection is None:
+            chromadb = self._import_runtime_dependency(
+                "chromadb",
+                "chromadb",
+                "缺少 chromadb 依赖，无法构建知识库索引。",
+            )
+            try:
+                self._chroma_path.mkdir(parents=True, exist_ok=True)
+                client = chromadb.PersistentClient(path=str(self._chroma_path))
+                self._collection = client.get_or_create_collection(
+                    name="bilisum_knowledge",
+                    metadata={"hnsw:space": "cosine"},
+                )
+            except Exception as exc:
+                logger.exception(
+                    "knowledge chromadb collection init failed path=%s runtime_channel=%s",
+                    self._chroma_path,
+                    self._settings.runtime_channel,
+                )
+                raise HTTPException(
+                    status_code=500,
+                    detail=f"知识库索引存储初始化失败：{self._short_error(exc)}。",
+                ) from exc
+        return self._collection
+
+    def _embed_texts(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        vectors = self._get_embedder().encode(texts, normalize_embeddings=True)
+        return [list(map(float, vector)) for vector in vectors]
+
+    def _split_markdown_sections(self, markdown: str) -> list[tuple[str, str]]:
+        content = str(markdown or "").strip()
+        if not content:
+            return []
+        sections: list[tuple[str, str]] = []
+        current_title = "知识笔记"
+        current_lines: list[str] = []
+        for line in content.splitlines():
+            if re.match(r"^\s{0,3}#{1,3}\s+", line):
+                if current_lines:
+                    section_body = "\n".join(current_lines).strip()
+                    if section_body:
+                        sections.append((current_title, section_body))
+                current_title = re.sub(r"^\s{0,3}#{1,3}\s+", "", line).strip() or "知识笔记"
+                current_lines = []
+                continue
+            current_lines.append(line)
+        if current_lines:
+            section_body = "\n".join(current_lines).strip()
+            if section_body:
+                sections.append((current_title, section_body))
+        return sections
+
+    def _build_chunks_for_video(self, video_id: str) -> tuple[Any, list[KnowledgeIndexChunkRecord]]:
+        asset = self._repository.get_video_asset(video_id)
+        if asset is None or asset.latest_result is None:
+            return None, []
+        result = asset.latest_result
+        task = self._repository.get_task(asset.latest_task_id) if asset.latest_task_id else None
+        page_title = str(task.page_title or task.task_input.title or "").strip() if task is not None else ""
+        display_title = page_title or asset.title
+        now = datetime.now(timezone.utc)
+        chunk_specs: list[dict[str, object]] = []
+
+        overview_parts = [str(result.overview or "").strip(), *[str(item).strip() for item in result.key_points if str(item).strip()]]
+        overview_text = "\n".join([part for part in overview_parts if part]).strip()
+        if overview_text:
+            chunk_specs.append(
+                {
+                    "index_type": "video_summary",
+                    "segment_order": 0,
+                    "anchor_label": None,
+                    "anchor_seconds": None,
+                    "content": f"{display_title}\n{overview_text}",
+                }
+            )
+
+        for index, chapter in enumerate(result.timeline):
+            if not isinstance(chapter, dict):
+                continue
+            title = str(chapter.get("title") or f"章节 {index + 1}").strip()
+            summary = str(chapter.get("summary") or "").strip()
+            start_raw = chapter.get("start")
+            start = float(start_raw) if isinstance(start_raw, (int, float)) else None
+            content = "\n".join([display_title, title, summary]).strip()
+            if summary:
+                chunk_specs.append(
+                    {
+                        "index_type": "chapter",
+                        "segment_order": index + 1,
+                        "anchor_label": title,
+                        "anchor_seconds": start,
+                        "content": content,
+                    }
+                )
+
+        for index, (title, body) in enumerate(self._split_markdown_sections(result.knowledge_note_markdown)):
+            chunk_specs.append(
+                {
+                    "index_type": "knowledge_note",
+                    "segment_order": index + 1,
+                    "anchor_label": title,
+                    "anchor_seconds": None,
+                    "content": f"{display_title}\n{title}\n{body}".strip(),
+                }
+            )
+
+        chunk_specs = [item for item in chunk_specs if str(item["content"]).strip()]
+        if not chunk_specs:
+            return asset, []
+
+        vectors = self._embed_texts([str(item["content"]) for item in chunk_specs])
+        chunks = [
+            KnowledgeIndexChunkRecord(
+                chunk_id=f"{video_id}:{item['index_type']}:{item['segment_order'] or 0}",
+                video_id=video_id,
+                embedding_json=json.dumps(vectors[index], ensure_ascii=False),
+                indexed_content=str(item["content"]),
+                index_type=str(item["index_type"]),
+                segment_order=int(item["segment_order"]) if item["segment_order"] is not None else None,
+                anchor_label=str(item["anchor_label"]) if item["anchor_label"] else None,
+                anchor_seconds=float(item["anchor_seconds"]) if item["anchor_seconds"] is not None else None,
+                created_at=now,
+                updated_at=now,
+            )
+            for index, item in enumerate(chunk_specs)
+        ]
+        return asset, chunks
+
+    def index_video(self, video_id: str, content: str | None = None) -> bool:
+        del content
+        asset, chunks = self._build_chunks_for_video(video_id)
+        if asset is None:
+            return False
+
+        collection = self._get_collection()
+        try:
+            collection.delete(where={"video_id": video_id})
+        except Exception:
+            pass
+
+        self._repository.replace_knowledge_chunks(video_id, chunks)
+        if not chunks:
+            return True
+
+        tags = [item.tag for item in self._repository.list_video_tags(video_id)]
+        task = self._repository.get_task(asset.latest_task_id) if asset.latest_task_id else None
+        page_number = int(task.page_number) if task is not None and task.page_number is not None else None
+        page_title = str(task.page_title or task.task_input.title or "").strip() if task is not None else ""
+        collection.add(
+            ids=[chunk.chunk_id for chunk in chunks],
+            documents=[chunk.indexed_content for chunk in chunks],
+            embeddings=[json.loads(chunk.embedding_json) for chunk in chunks],
+            metadatas=[
+                {
+                    "video_id": chunk.video_id,
+                    "index_type": chunk.index_type,
+                    "anchor_label": chunk.anchor_label or "",
+                    "anchor_seconds": float(chunk.anchor_seconds) if chunk.anchor_seconds is not None else -1.0,
+                    "title": asset.title,
+                    "page_number": page_number if page_number is not None else -1,
+                    "page_title": page_title,
+                    "display_title": page_title or asset.title,
+                    "cover_url": asset.cover_url or "",
+                    "tags_json": json.dumps(tags, ensure_ascii=False),
+                }
+                for chunk in chunks
+            ],
+        )
+        return True
+
+    def remove_video(self, video_id: str) -> bool:
+        self._repository.delete_knowledge_chunks(video_id)
+        try:
+            self._get_collection().delete(where={"video_id": video_id})
+        except HTTPException:
+            raise
+        except Exception:
+            pass
+        return True
+
+    def rebuild_index(self, force: bool = False) -> int:
+        del force
+        videos = [video for video in self._repository.list_video_assets() if video.latest_result is not None]
+        collection = self._get_collection()
+        try:
+            existing = collection.get()
+            ids = existing.get("ids") if isinstance(existing, dict) else None
+            if ids:
+                collection.delete(ids=ids)
+        except Exception:
+            pass
+
+        self._repository.clear_knowledge_chunks()
+        count = 0
+        for video in videos:
+            if self.index_video(video.video_id):
+                count += 1
+        return count
+
+    def _fetch_candidate_chunks(self, query: str, limit: int = 10, tag_filter: list[str] | None = None) -> list[dict[str, object]]:
+        cleaned_query = str(query or "").strip()
+        if not cleaned_query:
+            return []
+        if self._repository.get_knowledge_chunk_count() == 0:
+            self.rebuild_index()
+
+        effective_limit = max(limit * 4, 12)
+        query_embedding = self._embed_texts([cleaned_query])[0]
+        query_result = self._get_collection().query(
+            query_embeddings=[query_embedding],
+            n_results=effective_limit,
+        )
+        ids = query_result.get("ids", [[]])[0] if isinstance(query_result, dict) else []
+        documents = query_result.get("documents", [[]])[0] if isinstance(query_result, dict) else []
+        metadatas = query_result.get("metadatas", [[]])[0] if isinstance(query_result, dict) else []
+        distances = query_result.get("distances", [[]])[0] if isinstance(query_result, dict) else []
+
+        allowed_video_ids: set[str] | None = None
+        if tag_filter:
+            selected = {tag.strip() for tag in tag_filter if str(tag).strip()}
+            if selected:
+                allowed_video_ids = {
+                    item.video_id
+                    for item in self._repository.list_all_video_tags()
+                    if item.tag in selected
+                }
+
+        candidates: list[dict[str, object]] = []
+        for index, chunk_id in enumerate(ids):
+            metadata = metadatas[index] if index < len(metadatas) and isinstance(metadatas[index], dict) else {}
+            video_id = str(metadata.get("video_id") or "")
+            if allowed_video_ids is not None and video_id not in allowed_video_ids:
+                continue
+            distance = float(distances[index]) if index < len(distances) else 1.0
+            relevance = max(0.0, 1.0 - distance / 2.0)
+            candidates.append(
+                {
+                    "chunk_id": chunk_id,
+                    "video_id": video_id,
+                    "document": documents[index] if index < len(documents) else "",
+                    "metadata": metadata,
+                    "relevance_score": round(relevance, 4),
+                }
+            )
+        return candidates
+
+    def search(self, query: str, limit: int = 10, tag_filter: list[str] | None = None) -> list[KnowledgeSearchResult]:
+        candidates = self._fetch_candidate_chunks(query, limit=limit, tag_filter=tag_filter)
+        if not candidates:
+            return []
+
+        grouped: dict[str, dict[str, object]] = {}
+        for candidate in candidates:
+            video_id = str(candidate["video_id"])
+            current = grouped.get(video_id)
+            if current is None or float(candidate["relevance_score"]) > float(current["relevance_score"]):
+                grouped[video_id] = candidate
+
+        ordered = sorted(grouped.values(), key=lambda item: float(item["relevance_score"]), reverse=True)[: max(1, limit)]
+        results: list[KnowledgeSearchResult] = []
+        for candidate in ordered:
+            video_id = str(candidate["video_id"])
+            asset = self._repository.get_video_asset(video_id)
+            metadata = candidate["metadata"] if isinstance(candidate["metadata"], dict) else {}
+            video_title = asset.title if asset is not None else str(metadata.get("title") or "未知视频")
+            page_title = str(metadata.get("page_title") or metadata.get("display_title") or "").strip()
+            if page_title == video_title:
+                page_title = ""
+            page_number_raw = metadata.get("page_number")
+            page_number = int(page_number_raw) if isinstance(page_number_raw, (int, float)) and int(page_number_raw) > 0 else None
+            snippet = str(candidate["document"]).strip().replace("\n", " ")
+            snippet = snippet[:180].rstrip() + ("..." if len(snippet) > 180 else "")
+            tags = [item.tag for item in self._repository.list_video_tags(video_id)]
+            results.append(
+                KnowledgeSearchResult(
+                    video_id=video_id,
+                    title=page_title or video_title,
+                    relevance_score=float(candidate["relevance_score"]),
+                    snippet=snippet,
+                    tags=tags,
+                    cover_url=asset.cover_url if asset is not None else str(metadata.get("cover_url") or ""),
+                    timestamp=format_anchor_seconds(
+                        float(metadata["anchor_seconds"])
+                        if metadata.get("anchor_seconds") not in {None, "", -1, -1.0}
+                        else None
+                    ),
+                    video_title=video_title,
+                    page_title=page_title or None,
+                    page_number=page_number,
+                )
+            )
+        return results
+
+    def search_chunks(self, query: str, limit: int = 5, tag_filter: list[str] | None = None) -> list[dict[str, object]]:
+        return self._fetch_candidate_chunks(query, limit=limit, tag_filter=tag_filter)[: max(1, limit)]