diff --git a/scene_search/overviews.py b/scene_search/overviews.py new file mode 100644 index 0000000..0ea2db4 --- /dev/null +++ b/scene_search/overviews.py @@ -0,0 +1,366 @@ +"""Preview, publish and restore opt-in Jellyfin visual overviews. + +Existing canonical caption windows are used as evidence. No frame extraction, +re-captioning or Meilisearch change is required. Metadata publishing is +explicit and the original Jellyfin overview is retained for restoration. +""" +from __future__ import annotations + +import hashlib +import json +import re +from pathlib import Path +from typing import Any + +import requests + +from .config import settings +from .database import connect, init_db +from .jellyfin import JellyfinClient + + +AI_OVERVIEW_HEADING = "AI visual overview (from sampled video frames; may include spoilers)" +MAX_CAPTIONS = 64 +MAX_CAPTION_CHARS = 20000 +ALLOWED_KINDS = {"Movie", "Episode", "Video"} + + +def _media(db_path: Path, *, media_id: str | None, title: str | None) -> dict: + if bool(media_id) == bool(title): + raise ValueError("Specify exactly one of --media-id or --title") + + init_db(db_path) + with connect(db_path) as con: + if media_id: + rows = con.execute( + "SELECT * FROM media WHERE id = ? AND source_kind = 'jellyfin'", + (media_id,), + ).fetchall() + else: + rows = con.execute( + "SELECT * FROM media WHERE title = ? AND source_kind = 'jellyfin'", + (title,), + ).fetchall() + if not rows: + raise ValueError("No indexed Jellyfin video matches that ID/title") + if len(rows) > 1: + raise ValueError( + f"Title is ambiguous ({len(rows)} videos). Use --media-id instead." + ) + row = dict(rows[0]) + if not row.get("jellyfin_item_id"): + raise ValueError("The indexed video has no Jellyfin item ID") + return row + + +def _caption_evidence(db_path: Path, media_id: str) -> list[tuple[int, str]]: + with connect(db_path) as con: + rows = con.execute( + """ + SELECT cw.start_ms AS timestamp_ms, cw.caption + FROM caption_windows cw + WHERE cw.media_id = ? + AND cw.caption IS NOT NULL AND TRIM(cw.caption) != '' + + UNION ALL + + SELECT f.timestamp_ms, f.caption + FROM frames f + WHERE f.media_id = ? + AND f.caption IS NOT NULL AND TRIM(f.caption) != '' + AND NOT EXISTS ( + SELECT 1 + FROM caption_window_frames cwf + WHERE cwf.frame_id = f.id + ) + ORDER BY timestamp_ms + """, + (media_id, media_id), + ).fetchall() + return [ + (int(row["timestamp_ms"]), " ".join(str(row["caption"]).split())) + for row in rows + ] + + +def _sample(evidence: list[tuple[int, str]], limit: int) -> list[tuple[int, str]]: + """Sample throughout the title so we don't only describe its opening scenes.""" + limit = max(1, min(int(limit), MAX_CAPTIONS)) + if len(evidence) <= limit: + return evidence + if limit == 1: + return [evidence[len(evidence) // 2]] + indices = [ + (position * (len(evidence) - 1)) // (limit - 1) + for position in range(limit) + ] + return [evidence[index] for index in dict.fromkeys(indices)] + + +def _chat_overview( + captions: list[tuple[int, str]], + *, + model: str, + ollama_url: str, + timeout_seconds: int, +) -> str: + snippets: list[str] = [] + budget = MAX_CAPTION_CHARS + for timestamp_ms, caption in captions: + total_seconds = timestamp_ms // 1000 + hours, remainder = divmod(total_seconds, 3600) + minutes, seconds = divmod(remainder, 60) + line = f"[{hours:02d}:{minutes:02d}:{seconds:02d}] {caption}" + if len(line) > budget: + break + snippets.append(line) + budget -= len(line) + 1 + + if not snippets: + raise ValueError("Not enough usable caption evidence") + + prompt = ( + "Create a concise, natural-language visual overview for a video " + "using ONLY the following time-ordered descriptions generated from " + "sampled Trickplay images. Aim for 80–130 words, in one paragraph. " + "Describe the recurring setting, visible people, actions and broad " + "progression if supported. Do not invent character names, dialogue, " + "motives, backstory, a plot, a genre or an ending. Avoid graphic detail. " + "Do not treat individual disconnected frames as proof of a continuous " + "event. If the descriptions are uncertain or inconsistent, be general. " + "Do not include introductory labels, quotes or commentary.\n\n" + + "\n".join(snippets) + ) + response = requests.post( + f"{ollama_url.rstrip('/')}/api/chat", + json={ + "model": model, + "stream": False, + "messages": [{"role": "user", "content": prompt}], + "options": {"temperature": 0.0, "num_predict": 300}, + }, + timeout=timeout_seconds, + ) + if not response.ok: + raise RuntimeError( + f"Ollama {response.status_code}: {response.text[:300]}" + ) + data = response.json() + result = (data.get("message") or {}).get("content") + if not isinstance(result, str) or not result.strip(): + raise RuntimeError("Ollama returned an empty visual overview") + + cleaned = re.sub(r"\s+", " ", result).strip().strip('"') + if len(cleaned) > 2200: + raise RuntimeError( + "LLM response was unusually long; review the prompt/model instead " + "of silently truncating the description" + ) + return cleaned + + +def _draft(db_path: Path, media_id: str) -> dict | None: + with connect(db_path) as con: + row = con.execute( + "SELECT * FROM jellyfin_overview_drafts WHERE media_id = ?", + (media_id,), + ).fetchone() + return dict(row) if row is not None else None + + +def preview( + *, + db_path: Path, + media_id: str | None = None, + title: str | None = None, + model: str | None = None, + max_captions: int = MAX_CAPTIONS, + regenerate: bool = False, + chat_fn=None, +) -> dict[str, Any]: + """Generate/cache one reviewable visual overview, never update Jellyfin.""" + media = _media(db_path, media_id=media_id, title=title) + existing = _draft(db_path, media["id"]) + if existing and existing["applied_overview"] is not None: + raise ValueError( + "This video's AI overview is already applied. Restore it " + "before generating a new version." + ) + + evidence = _caption_evidence(db_path, media["id"]) + if not evidence: + raise ValueError("No saved Trickplay captions exist for this video") + chosen = _sample(evidence, max_captions) + fingerprint = hashlib.sha256( + json.dumps(chosen, ensure_ascii=False).encode("utf-8") + ).hexdigest() + + if ( + existing + and not regenerate + and existing["caption_fingerprint"] == fingerprint + ): + return {**existing, "title": media["title"], "total_captions": len(evidence)} + + selected_model = model or settings.overview_model + if not selected_model: + raise ValueError("OVERVIEW_MODEL is not configured") + produce = chat_fn or _chat_overview + generated = produce( + chosen, + model=selected_model, + ollama_url=settings.ollama_url, + timeout_seconds=settings.overview_timeout_seconds, + ) + if not isinstance(generated, str) or not generated.strip(): + raise ValueError("LLM returned an empty overview") + + with connect(db_path) as con: + con.execute( + """ + INSERT INTO jellyfin_overview_drafts ( + media_id, jellyfin_item_id, overview, model, + caption_fingerprint, sampled_captions, updated_at + ) + VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP) + ON CONFLICT(media_id) DO UPDATE SET + jellyfin_item_id = excluded.jellyfin_item_id, + overview = excluded.overview, + model = excluded.model, + caption_fingerprint = excluded.caption_fingerprint, + sampled_captions = excluded.sampled_captions, + updated_at = CURRENT_TIMESTAMP + """, + ( + media["id"], media["jellyfin_item_id"], generated.strip(), + selected_model, fingerprint, len(chosen), + ), + ) + result = _draft(db_path, media["id"]) + assert result is not None + return {**result, "title": media["title"], "total_captions": len(evidence)} + + +def _jellyfin_client() -> JellyfinClient: + return JellyfinClient( + settings.jellyfin_url, + settings.jellyfin_api_key, + settings.jellyfin_timeout_seconds, + ) + + +def _validate_remote(media: dict, item: dict) -> None: + if str(item.get("Id") or "").replace("-", "").lower() != str( + media["jellyfin_item_id"] + ).replace("-", "").lower(): + raise RuntimeError("Jellyfin returned a different item ID: refusing metadata update") + if str(item.get("Type") or "") not in ALLOWED_KINDS: + raise RuntimeError( + f"Cannot update unsupported Jellyfin type {item.get('Type')!r}" + ) + + +def _write_and_verify(client: JellyfinClient, item: dict, overview: str) -> None: + client.update_item_overview(item, overview) + after = client.item_for_update(str(item["Id"])) + if (after.get("Overview") or "") != overview: + raise RuntimeError( + "Jellyfin accepted the metadata update but the Overview did not " + "match on readback; review this item manually" + ) + + +def publish( + *, + db_path: Path, + media_id: str | None = None, + title: str | None = None, + client: JellyfinClient | None = None, +) -> dict[str, Any]: + """Append a labelled AI summary while retaining the original synopsis.""" + media = _media(db_path, media_id=media_id, title=title) + draft = _draft(db_path, media["id"]) + if not draft: + raise ValueError("Generate and review a draft before using --apply") + if str(draft["jellyfin_item_id"]) != str(media["jellyfin_item_id"]): + raise ValueError("Draft no longer matches the indexed Jellyfin item") + + api = client or _jellyfin_client() + item = api.item_for_update(str(media["jellyfin_item_id"])) + _validate_remote(media, item) + current = str(item.get("Overview") or "") + if draft["applied_overview"] is not None: + if current == draft["applied_overview"]: + return {**draft, "title": media["title"], "status": "already_applied"} + raise RuntimeError("Jellyfin Overview changed since we applied it; refusing to overwrite") + + if AI_OVERVIEW_HEADING in current: + raise RuntimeError( + "Jellyfin Overview already contains an AI visual overview; " + "refusing to append a duplicate" + ) + + addition = AI_OVERVIEW_HEADING + "\n\n" + draft["overview"] + proposed = current.rstrip() + ("\n\n" if current.strip() else "") + addition + + # Backup the unmodified synopsis and intended replacement *before* the + # external API call, so interrupted writes can still be restored. + with connect(db_path) as con: + con.execute( + """ + UPDATE jellyfin_overview_drafts + SET original_overview = ?, applied_overview = ?, + updated_at = CURRENT_TIMESTAMP + WHERE media_id = ? + """, + (current, proposed, media["id"]), + ) + _write_and_verify(api, item, proposed) + with connect(db_path) as con: + con.execute( + """ + UPDATE jellyfin_overview_drafts + SET applied_at = CURRENT_TIMESTAMP + WHERE media_id = ? + """, + (media["id"],), + ) + return {**_draft(db_path, media["id"]), "title": media["title"], "status": "applied"} + + +def restore( + *, + db_path: Path, + media_id: str | None = None, + title: str | None = None, + client: JellyfinClient | None = None, +) -> dict[str, Any]: + """Restore the exact old Overview only when the item is unchanged.""" + media = _media(db_path, media_id=media_id, title=title) + draft = _draft(db_path, media["id"]) + if not draft or draft["applied_overview"] is None: + raise ValueError("No previous Jellyfin Overview backup exists for this video") + + api = client or _jellyfin_client() + item = api.item_for_update(str(media["jellyfin_item_id"])) + _validate_remote(media, item) + current = str(item.get("Overview") or "") + original = str(draft["original_overview"] or "") + if current != draft["applied_overview"] and current != original: + raise RuntimeError( + "Jellyfin Overview was edited after publishing; refusing to overwrite " + "those changes automatically" + ) + if current != original: + _write_and_verify(api, item, original) + with connect(db_path) as con: + con.execute( + """ + UPDATE jellyfin_overview_drafts + SET original_overview = NULL, applied_overview = NULL, + applied_at = NULL, updated_at = CURRENT_TIMESTAMP + WHERE media_id = ? + """, + (media["id"],), + ) + return {**_draft(db_path, media["id"]), "title": media["title"], "status": "restored"}