Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

Read the knowledge base the suggestions claimed to be reading (#162)

Nika Siradzed6997e9fcb6f
diff --git a/backend/cli.py b/backend/cli.py
index 68ce24f..5cd12a7 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -16,6 +16,7 @@ import os
import shutil
import subprocess
import sys
+import uuid
import textwrap
import time
from 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.py
index 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 base
Priority: Claude Code → Codex → heuristic fallback.
"""
+import hashlib
import json
import math
import os
+import re
import subprocess
import sys
from typing import Optional, Callable
@@ -19,7 +21,7 @@ from services.audio_analyzer import compute_energy_scores
from services.audio_events import compute_event_scores, dominant_reaction
sys.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_MAX
from utils.text import clean_title
from services import ai_provider, podcli_cloud
from 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_context
kb_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.py
index 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 tempfile
import sys
import unittest
+from unittest import mock
ROOT = 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.py
index 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)