Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
Read the knowledge base the suggestions claimed to be reading (#162)
Nika Siradzed6997e9fcb6f
diff --git a/backend/cli.py b/backend/cli.pyindex 68ce24f..5cd12a7 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -16,6 +16,7 @@ import osimport shutilimport subprocessimport sys+import uuidimport textwrapimport timefrom pathlib import Path@@ -100,15 +101,35 @@ def _suggestions_session_path(cache_hash: str) -> str:def _selection_signature(config: dict) -> str:- """Flags that change which clips get selected. A cached session is only- valid for a re-run with the same signature, otherwise it would serve clips- that ignore the new --no-ai / --min-duration / --max-duration flags."""- return "|".join(str(x) for x in (- bool(config.get("ai_select", True)),+ """Everything that changes which clips get selected.++ A cached session is only replayed for a re-run with the same signature.+ The knowledge base is in here because editing it and re-running is the+ whole iteration loop, and serving the previous picks under the new rules+ teaches people the knowledge base does nothing. It is folded in only for+ AI selection, since the saliency and heuristic engines never read it and+ would otherwise throw away sessions that cost real audio analysis.+ """+ ai_select = bool(config.get("ai_select", True))+ parts = [+ ai_select,config.get("min_clip_duration", MIN_CLIP_DURATION),config.get("max_clip_duration", MAX_CLIP_DURATION),config.get("format", "vertical"),- ))+ config.get("profile") or "",+ bool(config.get("energy_boost", True)),+ ]+ if ai_select:+ try:+ from services.claude_suggest import kb_signature+ parts.append(kb_signature())+ except Exception:+ # Unique per call, so a run that could not read the knowledge base+ # neither replays an older session nor becomes one. A constant here+ # would make two failed lookups compare equal and serve stale picks+ # across a knowledge-base edit.+ parts.append("kb-unavailable-" + uuid.uuid4().hex)+ return "|".join(str(x) for x in parts)def _load_suggestions_session(cache_hash: str, top_n: int, signature: str) -> list | None:diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.pyindex 499489e..a33d68f 100644--- a/backend/services/claude_suggest.py+++ b/backend/services/claude_suggest.py@@ -7,9 +7,11 @@ Delegates moment selection to an AI CLI, which uses the PodStack knowledge basePriority: Claude Code → Codex → heuristic fallback."""+import hashlibimport jsonimport mathimport os+import reimport subprocessimport sysfrom typing import Optional, Callable@@ -19,7 +21,7 @@ from services.audio_analyzer import compute_energy_scoresfrom services.audio_events import compute_event_scores, dominant_reactionsys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))-from presets import MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX+from presets import DEFAULT_PRESET, MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAXfrom utils.text import clean_titlefrom services import ai_provider, podcli_cloudfrom services.ai_cli import (@@ -34,29 +36,104 @@ from services.ai_cli import (def _load_existing_shorts(episodes_path: str) -> list[str]:- """Extract existing short titles from episode database to avoid duplicates."""+ """Titles of shorts already published, so they are not suggested again.++ Reads the shipped table shape and the older numbered-list shape. Cells left+ as `[placeholder]` are not titles.+ """if not os.path.exists(episodes_path):return []try:with open(episodes_path, encoding="utf-8") as f:content = f.read()- # Parse lines that look like shorts entries: "1. [title] — [category]"- shorts = []- for line in content.split("\n"):- line = line.strip()- if line and (line.startswith("1.") or line.startswith("2.") or- line.startswith("3.") or line.startswith("4.") or- line.startswith("5.") or line.startswith("6.") or- line.startswith("7.") or line.startswith("8.") or- line.startswith("9.")):- # Extract title between brackets or after number- title = line.split("—")[0].strip().lstrip("0123456789.").strip()- if title and title != "[Short title]":- shorts.append(title)- return shorts- except Exception:+ except OSError:return []+ shorts: list[str] = []+ for raw in content.split("\n"):+ line = raw.strip()+ if not line:+ continue+ title = ""+ if line.startswith("|"):+ cells = [c.strip() for c in line.strip("|").split("|")]+ # | # | Moment | Title | Platform | Status |+ if len(cells) >= 3 and cells[0].lower() not in ("#", "num", "no"):+ if not all(set(c) <= set("-: ") for c in cells):+ status = cells[4].lower() if len(cells) >= 5 else ""+ # A dropped moment was considered and passed over, and the+ # template says it can be reconsidered. Anything else that+ # reached this table is a clip that exists.+ if "drop" not in status:+ title = cells[2]+ elif re.match(r"^\d+[.)]\s", line):+ title = re.split(r"\s[-\u2013\u2014]\s", line, maxsplit=1)[0]+ title = re.sub(r"^\d+[.)]\s*", "", title).strip()++ title = title.strip().strip("*`").strip()+ if title and not (title.startswith("[") and title.endswith("]")):+ shorts.append(title)+ return shorts+++# (filename, max_chars) that reach the selection prompt, highest priority first.+# Shared with kb_signature so the suggestion cache and the prompt cannot drift.+KB_FILES = [+ ("04-shorts-creation-guide.md", 4000), # moment selection criteria, content types+ ("05-title-formulas.md", 3000), # title rules, shapes, banned openers+ ("02-voice-and-tone.md", 3000), # banned words, voice fingerprint, coffee test+ ("01-brand-identity.md", 1500), # show context, positioning, audience+ ("11-inspiration-channels.md", 2000), # viral hook patterns, reference styles+ ("12-quick-reference.md", 2000), # hook bank, title formulas, hashtags+ ("08-topics-themes.md", 1000), # topic areas, audience interest map+ ("00-master-instructions.md", 1500), # quality gate, auto-detection rules+]+++def kb_signature() -> str:+ """Fingerprint of exactly what the knowledge base contributes to the prompt.++ Hashes the assembled text rather than file mtimes, so it survives a git+ checkout that rewrites timestamps without changing content, and it already+ accounts for per-file truncation and for files skipped as unfilled.+ """+ from services.knowledge_base import load_kb_context++ kb_dir = paths["knowledge"]+ parts = [load_kb_context(KB_FILES, kb_dir) or ""]+ parts.extend(_load_existing_shorts(os.path.join(kb_dir, "03-episodes-database.md")))+ return hashlib.sha256("\u0000".join(parts).encode("utf-8")).hexdigest()[:16]+++CAPTION_STYLES = ("branded", "hormozi", "karaoke", "subtle")+++def _preferred_caption_style(kb_dir: str) -> str:+ """The show's caption style, from the knowledge base or the preset default.++ 04-shorts-creation-guide.md carries a "Caption style:" line that nothing+ read, so every suggestion arrived asking for hormozi regardless of what the+ show had written down or set as its preset.+ """+ path = os.path.join(kb_dir, "04-shorts-creation-guide.md")+ try:+ with open(path, encoding="utf-8") as fh:+ for line in fh:+ m = re.match(r"^\s*[-*]?\s*caption style\s*:\s*(.+)$", line, re.I)+ if not m:+ continue+ value = m.group(1).strip().strip("*`").lower()+ # Still the shipped "[branded / hormozi / karaoke / subtle]" list.+ if value.startswith("["):+ break+ for style in CAPTION_STYLES:+ if value == style:+ return style+ break+ except OSError:+ pass+ return DEFAULT_PRESET.get("caption_style", "branded")+MAX_REACTION_ANCHORS = 40@@ -94,18 +171,7 @@ def _build_prompt(from services.knowledge_base import load_kb_context, warn_missing_contextkb_dir = paths["knowledge"]- # (filename, max_chars) — higher priority files get more budget- _kb_files = [- ("04-shorts-creation-guide.md", 4000), # moment selection criteria, content types- ("05-title-formulas.md", 3000), # title rules, shapes, banned openers- ("02-voice-and-tone.md", 3000), # banned words, voice fingerprint, coffee test- ("01-brand-identity.md", 1500), # show context, positioning, audience- ("11-inspiration-channels.md", 2000), # viral hook patterns, reference styles- ("12-quick-reference.md", 2000), # hook bank, title formulas, hashtags- ("08-topics-themes.md", 1000), # topic areas, audience interest map- ("00-master-instructions.md", 1500), # quality gate, auto-detection rules- ]- kb_context = load_kb_context(_kb_files, kb_dir)+ kb_context = load_kb_context(KB_FILES, kb_dir)if not kb_context:warn_missing_context("clip scoring")@@ -163,7 +229,7 @@ MOMENT SELECTION (think like a TikTok editor):{f"KNOWLEDGE BASE:{kb_context}" if kb_context else ""}-{f"EXISTING SHORTS (avoid duplicating these moments):{chr(10).join('- ' + s for s in existing_shorts)}" if existing_shorts else ""}+{f"ALREADY PUBLISHED (do NOT suggest these moments again):{chr(10)}{chr(10).join('- ' + s for s in existing_shorts)}" if existing_shorts else ""}{excluded_ranges}{_format_reaction_anchors(reaction_times)}Score each moment on 4 dimensions (1-5 each):@@ -399,6 +465,7 @@ Transcript:if progress_callback:progress_callback(40, f"Searching transcript with {label}...")+ caption_style = _preferred_caption_style(paths["knowledge"])try:data, _result = ai_provider.generate_json(prompt, timeout=900, project_dir=project_dir, on_attempt=announce,@@ -434,7 +501,7 @@ Transcript:"content_type": c.get("content_type", "unknown"),"reasoning": c.get("why", ""),"preview_text": c.get("quote", "")[:120],- "suggested_caption_style": "hormozi",+ "suggested_caption_style": caption_style,"quote": c.get("quote", ""),"why": c.get("why", ""),"reasons": [c.get("content_type", "")],@@ -597,6 +664,7 @@ def suggest_with_claude(for alternate in attempt.alternates:clips.extend(records(ai_provider.extract_json(alternate)))+ caption_style = _preferred_caption_style(paths["knowledge"])normalized = []for c in clips:scores = c.get("scores")@@ -634,7 +702,7 @@ def suggest_with_claude("content_type": c.get("content_type", "unknown"),"reasoning": c.get("why", ""),"preview_text": c.get("quote", "")[:120],- "suggested_caption_style": "hormozi",+ "suggested_caption_style": caption_style,"quote": c.get("quote", ""),"why": c.get("why", ""),"reasons": [c.get("content_type", "")],diff --git a/tests/test_claude_suggest_helpers.py b/tests/test_claude_suggest_helpers.pyindex 0e0246a..d0ffb22 100644--- a/tests/test_claude_suggest_helpers.py+++ b/tests/test_claude_suggest_helpers.py@@ -6,8 +6,10 @@ or any external tools."""import os+import tempfileimport sysimport unittest+from unittest import mockROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))BACKEND_ROOT = os.path.join(ROOT, "backend")@@ -261,3 +263,106 @@ class BlendSignalScoresTests(unittest.TestCase):if __name__ == "__main__":unittest.main()+++class ExistingShortsTests(unittest.TestCase):+ def _write(self, body):+ path = os.path.join(self.tmp.name, "03-episodes-database.md")+ with open(path, "w", encoding="utf-8") as fh:+ fh.write(body)+ return path++ def setUp(self):+ self.tmp = tempfile.TemporaryDirectory()+ self.addCleanup(self.tmp.cleanup)++ def test_the_shipped_template_yields_nothing(self):+ shipped = os.path.join(+ ROOT, "backend", "templates", "knowledge", "03-episodes-database.md"+ )+ self.assertEqual(cs._load_existing_shorts(shipped), [])++ def test_titles_come_out_of_the_shipped_table_shape(self):+ path = self._write(+ "| # | Moment (timestamps) | Title | Platform | Status |\n"+ "|---|---------------------|-------|----------|--------|\n"+ "| 1 | [00:14:20-00:15:05] | The pricing mistake | YouTube Shorts | published |\n"+ "| 2 | [00:31:02-00:31:40] | Why we fired our best engineer | TikTok | published |\n"+ )+ self.assertEqual(+ cs._load_existing_shorts(path),+ ["The pricing mistake", "Why we fired our best engineer"],+ )++ def test_the_older_numbered_shape_still_reads(self):+ path = self._write("1. An older entry — hot take\n2. Another one — story\n")+ self.assertEqual(cs._load_existing_shorts(path), ["An older entry", "Another one"])++ def test_a_dropped_moment_stays_available(self):+ path = self._write(+ "| # | Moment | Title | Platform | Status |\n"+ "|---|--------|-------|----------|--------|\n"+ "| 1 | [00:01-00:30] | Shipped one | YouTube Shorts | published |\n"+ "| 2 | [00:40-01:10] | Considered and cut | - | dropped |\n"+ "| 3 | [02:00-02:30] | Queued one | TikTok | scheduled |\n"+ )+ self.assertEqual(cs._load_existing_shorts(path), ["Shipped one", "Queued one"])++ def test_unfilled_cells_are_not_titles(self):+ path = self._write(+ "| # | Moment | Title | Platform | Status |\n"+ "|---|--------|-------|----------|--------|\n"+ "| 1 | [00:00-00:30] | [published title] | [YouTube Shorts] | [published] |\n"+ )+ self.assertEqual(cs._load_existing_shorts(path), [])++ def test_published_titles_reach_the_prompt_one_per_line(self):+ with mock.patch.object(+ cs, "_load_existing_shorts", return_value=["First short", "Second short"]+ ):+ prompt = cs._build_prompt(+ transcript_text="[0.0s] hello",+ segment_count=1,+ duration_min=1.0,+ top_n=3,+ )+ self.assertIn("ALREADY PUBLISHED", prompt)+ self.assertIn("\n- First short\n- Second short", prompt)++ def test_no_published_titles_means_no_heading(self):+ with mock.patch.object(cs, "_load_existing_shorts", return_value=[]):+ prompt = cs._build_prompt(+ transcript_text="[0.0s] hello",+ segment_count=1,+ duration_min=1.0,+ top_n=3,+ )+ self.assertNotIn("ALREADY PUBLISHED", prompt)+++class CaptionStyleTests(unittest.TestCase):+ def setUp(self):+ self.tmp = tempfile.TemporaryDirectory()+ self.addCleanup(self.tmp.cleanup)++ def _guide(self, line):+ with open(+ os.path.join(self.tmp.name, "04-shorts-creation-guide.md"), "w", encoding="utf-8"+ ) as fh:+ fh.write("# Guide\n\n" + line + "\n")+ return self.tmp.name++ def test_an_unfilled_placeholder_falls_back_to_the_preset(self):+ kb = self._guide("- Caption style: [branded / hormozi / karaoke / subtle]")+ self.assertEqual(cs._preferred_caption_style(kb), "branded")++ def test_a_chosen_style_wins(self):+ kb = self._guide("- Caption style: karaoke")+ self.assertEqual(cs._preferred_caption_style(kb), "karaoke")++ def test_an_unknown_style_falls_back_rather_than_shipping_garbage(self):+ kb = self._guide("- Caption style: neon")+ self.assertEqual(cs._preferred_caption_style(kb), "branded")++ def test_a_missing_knowledge_base_falls_back(self):+ self.assertEqual(cs._preferred_caption_style("/nonexistent"), "branded")diff --git a/tests/test_cli_helpers.py b/tests/test_cli_helpers.pyindex 047f67a..2ec5ab8 100644--- a/tests/test_cli_helpers.py+++ b/tests/test_cli_helpers.py@@ -55,3 +55,42 @@ class SharedWavTests(unittest.TestCase):if __name__ == "__main__":unittest.main()+++class SelectionSignatureTests(unittest.TestCase):+ """The suggestions cache is only allowed to replay picks made under the+ same rules."""++ def _sig(self, config, kb="kb-a"):+ with mock.patch("services.claude_suggest.kb_signature", return_value=kb):+ return cli_mod._selection_signature(config)++ def test_editing_the_knowledge_base_invalidates_an_ai_session(self):+ cfg = {"ai_select": True}+ self.assertNotEqual(self._sig(cfg, kb="kb-a"), self._sig(cfg, kb="kb-b"))++ def test_editing_the_knowledge_base_leaves_a_saliency_session_alone(self):+ cfg = {"ai_select": False}+ self.assertEqual(self._sig(cfg, kb="kb-a"), self._sig(cfg, kb="kb-b"))++ def test_changing_profile_invalidates(self):+ a = self._sig({"ai_select": True, "profile": "party"})+ b = self._sig({"ai_select": True})+ self.assertNotEqual(a, b)++ def test_turning_energy_off_invalidates(self):+ a = self._sig({"ai_select": True, "energy_boost": False})+ b = self._sig({"ai_select": True, "energy_boost": True})+ self.assertNotEqual(a, b)++ def test_an_unreadable_knowledge_base_does_not_raise(self):+ with mock.patch("services.claude_suggest.kb_signature", side_effect=OSError("boom")):+ self.assertIn("kb-unavailable", cli_mod._selection_signature({"ai_select": True}))++ def test_two_failed_lookups_never_compare_equal(self):+ # Otherwise a session saved during one failure replays during the next,+ # after the knowledge base has changed underneath it.+ with mock.patch("services.claude_suggest.kb_signature", side_effect=OSError("boom")):+ a = cli_mod._selection_signature({"ai_select": True})+ b = cli_mod._selection_signature({"ai_select": True})+ self.assertNotEqual(a, b)