Skip to content

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

53.7 KB
Raw Blame
"""
Clip suggestion via AI CLI (Claude Code or Codex).

Delegates moment selection to an AI CLI, which uses the PodStack knowledge base
(.podcli/knowledge/) and CLAUDE.md for context-aware clip extraction.

Priority: podcli Pro cloud, then Claude Code or Codex, then the Anthropic API, then the heuristic fallback.
"""

import hashlib
import json
import math
import os
import re
import subprocess
import sys
from typing import Optional, Callable

from config.paths import paths
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 DEFAULT_PRESET, MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX
from services.formats import get_format
from services.opening_hook import HOOK_MODES, validate_hook
from utils.text import clean_title
from services import ai_provider, podcli_cloud
from services.ai_cli import (
    _engine_label,
    _find_ai_cli,
    _find_ai_cli_candidates,
    _format_timeout_label,
    _run_ai_command,
    classify_cli_error,
    get_ai_cli_status,
)


def _title_key(title: str) -> str:
    return re.sub(r"[^a-z0-9]+", " ", title.lower()).strip()


def drop_published(clips: list[dict], episodes_path: str | None = None) -> list[dict]:
    """Remove suggestions whose title matches a short already in the episode database.

    The prompt asks the AI not to repeat published moments, but that is advice
    and the heuristic fallback never reads the database at all. This runs after
    whichever engine answered. Titles are the only thing the database records,
    so the match is a normalised title comparison with a small similarity margin.
    """
    from difflib import SequenceMatcher

    path = episodes_path or os.path.join(paths["knowledge"], "03-episodes-database.md")
    published = [k for k in (_title_key(t) for t in _load_existing_shorts(path)) if k]
    if not published or not clips:
        return clips

    kept = []
    for clip in clips:
        key = _title_key(str(clip.get("title", "")))
        if key and any(
            key == p or SequenceMatcher(None, key, p).ratio() >= 0.9 for p in published
        ):
            continue
        kept.append(clip)
    return kept


def _load_existing_shorts(episodes_path: str) -> list[str]:
    """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()
    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.
class ClipBounds:
    """Duration bounds and prompt framing for one output format.

    formats.py calls itself the single source of truth for duration bounds and
    every consumer honoured that except the one deciding which moments get
    picked. Explicit overrides still win, so a Studio slider or a preset can
    narrow a format without redefining it.
    """

    __slots__ = ("dur_min", "dur_max", "target_min", "target_max", "editor", "pacing", "lens")

    def __init__(self, spec, dur_min=None, dur_max=None):
        self.dur_min = int(dur_min) if dur_min else spec.dur_min
        self.dur_max = int(dur_max) if dur_max else spec.dur_max
        if self.dur_max < self.dur_min:
            self.dur_min, self.dur_max = spec.dur_min, spec.dur_max
        self.target_min = max(spec.target_min, self.dur_min)
        self.target_max = min(spec.target_max, self.dur_max)
        if self.target_max < self.target_min:
            self.target_min, self.target_max = self.dur_min, self.dur_max
        self.editor = spec.editor
        self.pacing = spec.pacing
        self.lens = spec.lens

    @classmethod
    def of(cls, fmt=None, dur_min=None, dur_max=None) -> "ClipBounds":
        return cls(get_format(fmt), dur_min, dur_max)

    def keeps(self, seconds: float) -> bool:
        return self.dur_min <= seconds <= self.dur_max


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
]


# Bump when the selection rules in _build_prompt change. Folded into the
# suggestion cache key for the same reason the knowledge base is: replaying old
# picks under new rules teaches people the rules do nothing.
PROMPT_VERSION = 6


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")


# Codex receives its prompt as an argv argument and silently truncates a long
# one. Truncating the tail drops the end of the episode, which is exactly how a
# run ends up with every clip in the opening minutes, so the transcript is
# sampled across the whole timeline instead.
CODEX_TRANSCRIPT_LIMIT = 48000


def _sample_transcript(transcript_text: str, limit: int = CODEX_TRANSCRIPT_LIMIT) -> str:
    """Thin a transcript to roughly `limit` characters, keeping its full span."""
    if len(transcript_text) <= limit:
        return transcript_text
    lines = transcript_text.split("\n")
    if len(lines) < 3:
        return transcript_text[:limit]
    keep_every = max(2, -(-len(transcript_text) // limit))
    sampled = lines[::keep_every]
    # The last line anchors the end of the timeline, which is the half a tail
    # truncation would have thrown away.
    if lines[-1] not in sampled[-1:]:
        sampled.append(lines[-1])
    return "\n".join(sampled)


def _codex_adapter(transcript_text: str):
    """An `adapt` callback that thins the transcript for Codex only."""
    def adapt(engine: str, prompt: str) -> str:
        if engine != "codex" or not transcript_text:
            return prompt
        sampled = _sample_transcript(transcript_text)
        if sampled == transcript_text:
            return prompt
        note = (
            "\n\nNOTE: this transcript is sampled across the full episode, so "
            "consecutive lines may skip ahead. Timestamps remain exact.\n"
        )
        return prompt.replace(transcript_text, note + sampled, 1)

    return adapt


def _total_score(clip: dict) -> float:
    """Sum the model's per-dimension scores, tolerating a malformed one.

    The values are whatever the model emitted. A single string in there used to
    raise TypeError inside the normalization loop and take down the whole
    suggestion run rather than costing one clip.
    """
    scores = clip.get("scores")
    if isinstance(scores, dict) and scores:
        total = 0.0
        usable = False
        for value in scores.values():
            if isinstance(value, bool) or not isinstance(value, (int, float)):
                try:
                    value = float(value)
                except (TypeError, ValueError):
                    continue
            total += float(value)
            usable = True
        if usable:
            return total
    fallback = clip.get("total_score", 0)
    try:
        return float(fallback)
    except (TypeError, ValueError):
        return 0.0


MAX_REACTION_ANCHORS = 40


def _suggested_hook(clip: dict, start: float, end: float, segments: list[dict]) -> Optional[dict]:
    """The opening hook the model proposed for this clip, or None.

    A hook that is malformed or falls outside the clip it opens is dropped
    rather than failing the clip: the moment is still worth rendering without it.
    """
    raw = clip.get("hook")
    if not isinstance(raw, dict) or raw.get("mode") not in HOOK_MODES:
        return None
    try:
        hook = {
            "start": round(float(raw.get("start")), 1),
            "end": round(float(raw.get("end")), 1),
            "mode": raw["mode"],
        }
        return validate_hook(hook, start, end, segments)
    except (TypeError, ValueError):
        return None


def _format_reaction_anchors(reaction_times: list[float] | None) -> str:
    """Prompt block listing detected laughter/reaction peaks as anchor moments."""
    if not reaction_times:
        return ""
    anchors = sorted({round(float(t), 1) for t in reaction_times})[:MAX_REACTION_ANCHORS]
    times = ", ".join(f"{t:.1f}s" for t in anchors)
    return (
        "\nAUDIENCE REACTION ANCHORS (detected laughter/cheering peaks, in seconds):\n"
        f"{times}\n"
        "The moment that CAUSED each reaction sits just before its anchor. "
        "Clips that contain or lead into an anchor are strong candidates, so "
        "prefer them when quality is otherwise equal.\n"
    )


def _build_prompt(
    transcript_text: str,
    segment_count: int,
    duration_min: float,
    top_n: int,
    exclude_clips: list[dict] | None = None,
    reaction_times: list[float] | None = None,
    bounds: "ClipBounds | None" = None,
) -> str:
    """Build the prompt for Claude to extract clips.

    Inlines key rules from the knowledge base since Claude --print mode
    can't read project files.
    """

    # Load knowledge base files inline: prioritized by relevance to clip selection
    from services.knowledge_base import load_kb_context, warn_missing_context

    kb_dir = paths["knowledge"]
    kb_context = load_kb_context(KB_FILES, kb_dir)
    if not kb_context:
        warn_missing_context("clip scoring")

    # Load existing shorts from episode database for duplicate avoidance
    episodes_path = os.path.join(kb_dir, "03-episodes-database.md")
    existing_shorts = _load_existing_shorts(episodes_path)

    excluded_ranges = ""
    if exclude_clips:
        lines = []
        for clip in exclude_clips[:24]:
            start = round(float(clip.get("start_second", 0)), 1)
            end = round(float(clip.get("end_second", 0)), 1)
            title = str(clip.get("title", "Untitled")).strip()
            if end > start:
                lines.append(f"- {start:.1f}s to {end:.1f}s: {title[:80]}")
        if lines:
            excluded_ranges = (
                "\nALREADY SELECTED CLIPS (do NOT return overlapping moments with these):\n"
                + "\n".join(lines)
            )

    b = bounds or ClipBounds.of()
    return f"""You are {b.editor}. Find the {top_n} most scroll-stopping moments in this podcast transcript.

IMPORTANT: Return ONLY valid JSON. No markdown, no explanation, no code fences.

TIMESTAMP FORMAT: All timestamps in the transcript are in SECONDS (e.g., [123.4s]).
All timestamps you return MUST be in SECONDS as numbers (e.g., 123.4), NOT minutes:seconds.

DURATION RULES (CRITICAL):
- Target: {b.target_min}-{b.target_max} seconds (this is the sweet spot)
- Maximum: {b.dur_max} seconds (anything longer still renders, but gets flagged as over target)
- Minimum: {b.dur_min} seconds (too short = no payoff)
- {b.pacing}
- If a thought takes longer than {b.target_max}s, use segments to cut the filler in the middle

CUTTING RULES (CRITICAL):
- Cut TIGHT. Every second must earn its place.
- Start at the exact moment the hook hits, no preamble, no "so", no "well"
- ONE EXCEPTION: if the moment is an ANSWER, start on the QUESTION that prompted it.
  A question is not preamble, it is the setup the viewer needs. Only leave it out when
  it rambles past ~8 seconds, and then cut the rambling with "segments" or skip the moment.
- End the MOMENT the point lands with a complete thought: don't trail off
- NEVER cut mid-sentence or mid-thought. The viewer must feel closure.
- The last sentence must feel like a natural ending, a punchline, or a mic-drop
- If there's filler/tangent in the middle, use multiple segments to skip it
- A tight clip with zero dead weight beats a {b.dur_max}s clip with fluff

MOMENT SELECTION ({b.lens}):
- Would YOU stop scrolling for this? If no, skip it.
- First 3 seconds must HOOK: a bold claim, shocking number, or provocative question
- Must make complete sense standalone: no "as I mentioned" or "going back to"
- Must not OPEN on a word pointing back before the cut: "that", "it", "they", "yeah",
  "so", "exactly", "right", "which is why". Widen the start until it is inside the clip.
- Must end on a COMPLETE THOUGHT, sentence boundary, natural pause, or mic-drop moment
- Single focused idea: one concept, fully delivered, no loose threads
- Prioritize: controversial takes, surprising numbers, founder war stories, "wait what?" moments, emotional peaks
- Skip: generic advice, obvious statements, context-dependent references
- On long episodes, search the ENTIRE timeline and diversify the picks. Do not cluster all clips in one section if later sections contain strong standalone moments.

{f"KNOWLEDGE BASE:{kb_context}" if kb_context 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)}

CONTEXT RULES (CRITICAL):
- State the PAYOFF first: one sentence, second person, on what the viewer walks away with.
  If you cannot state it in one sentence, the moment is not a clip. Skip it.
- WRITE the title from the payoff. Never copy the first sentence of the moment into
  it. A transcript fragment is not a title: "Is it having a big?" and "Was not working
  so well" are what copying produces, and they promise the viewer nothing.
- The title must be a complete thought that reads on its own, under 60 characters.
- In "needs", name what the viewer must already know. Write "nothing" when the clip
  carries its own setup.
- If "needs" is anything other than "nothing", move start_second back until the clip
  covers it on camera. "context_line" is a note for the editor, not a fix: nothing burns
  it into the video, so a clip that leans on it still ships with no setup.

Score each moment on 4 dimensions (1-5 each):
- standalone: Makes sense without episode context?
- hook: Grabs attention in first 3 seconds?
- relevance: Matters to target audience?
- quotability: Memorable, shareable phrasing?

Classify each as: guest_story | technical_insight | market_landscape | business_strategy | hot_take

Return this exact JSON structure:
{{
  "clips": [
    {{
      "title": "Written from the payoff, never copied from the transcript",
      "start_second": 123.4,
      "end_second": 168.4,
      "segments": [
        {{"start": 123.4, "end": 140.0}},
        {{"start": 145.2, "end": 168.4}}
      ],
      "duration": 40,
      "content_type": "guest_story",
      "scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},
      "total_score": 16,
      "quote": "The key quote from this moment",
      "payoff": "What the viewer walks away with, one sentence, second person",
      "needs": "nothing",
      "context_line": "",
      "why": "One sentence on why this earns 30 seconds of a stranger's attention"
    }}
  ]
}}

SEGMENTS RULES:
- "segments" is an array of keep-ranges within the clip. Use it to CUT OUT dead weight.
- If the moment is clean with no filler, use a single segment: [{{"start": X, "end": Y}}]
- If there's a ramble/tangent/filler in the middle, split into multiple segments that skip it
- Each segment must start and end on sentence boundaries
- The rendered video will stitch these segments together seamlessly
- "duration" = total kept time (sum of all segment lengths), NOT end - start
- "start_second" / "end_second" = outer bounds (first segment start, last segment end)
- Example: speaker makes great point (10s), rambles (8s), delivers punchline (12s) → 2 segments, 22s total

HOOK (optional):
- If the sharpest line sits mid-clip, add "hook": {{"start": X, "end": Y, "mode": "repeat"}} so it plays first.
- It must be 1-15 seconds of words actually spoken inside the clip's segments. Never invent text.
- "repeat" plays it again where it belongs. "move" lifts it out of the body.
- Leave "hook" out when the clip already opens on its strongest line.

Rules:
- Final clip duration (sum of segments) MUST be {b.dur_min}-{b.dur_max} seconds (target {b.target_min}-{b.target_max}s)
- Each segment must start and end on COMPLETE SENTENCES: never mid-thought
- The LAST segment must end on a sentence that feels like a natural conclusion
- Must make sense standalone when stitched together
- Sort clips by timestamp order

Transcript ({segment_count} segments, ~{duration_min:.0f} min):

{transcript_text}"""


def _split_prompt_for_cache(prompt: str, transcript_text: str) -> tuple[str, str]:
    """Separate the transcript from the ask, for backends that cache prefixes.

    Returns (stable_prefix, instruction). The transcript is the only large
    thing here and it is identical across every pass on an episode, so caching
    it turns four full reads into one read and three cache hits.
    """
    marker = f"\n\n{transcript_text}"
    if not transcript_text or not prompt.endswith(marker):
        return "", prompt
    return transcript_text, prompt[: -len(marker)]


def _build_transcript_text(segments: list[dict]) -> str:
    """Serialize transcript segments into the prompt-friendly text format."""
    lines = []
    for seg in segments:
        speaker = seg.get("speaker", "")
        speaker_label = f"[{speaker}] " if speaker else ""
        start = seg.get("start", 0)
        text = seg.get("text", "").strip()
        if text:
            lines.append(f"[{start:.1f}s] {speaker_label}{text}")
    return "\n".join(lines)


def _segments_duration_seconds(segments: list[dict]) -> float:
    """Estimate total covered duration from transcript segments."""
    if not segments:
        return 0.0
    return max(0.0, float(segments[-1].get("end", segments[-1].get("start", 0))) - float(segments[0].get("start", 0)))


def _should_bucket_initial_selection(segments: list[dict]) -> bool:
    """
    Use bucketed AI search for long or dense transcripts.

    This keeps initial clip discovery from spending many minutes on a single
    whole-episode prompt for long podcasts.
    """
    if not segments:
        return False

    duration_seconds = _segments_duration_seconds(segments)
    transcript_chars = sum(len(str(seg.get("text", ""))) for seg in segments)

    return bool(
        duration_seconds >= 45 * 60
        or len(segments) >= 180
        or transcript_chars >= 18000
    )


def _dedupe_clips_by_range(clips: list[dict]) -> list[dict]:
    """Collapse overlapping clip suggestions (>50% of the shorter clip), keeping
    the higher-scored one, sorted by start time. Exact-range matching would miss
    near-duplicates like 100.0-140.0 vs 102.5-141.5."""
    kept: list[dict] = []
    # Highest-scored first so the survivor of an overlap is the better clip.
    for clip in sorted(clips, key=lambda c: c.get("score", 0), reverse=True):
        start = float(clip.get("start_second", 0))
        end = float(clip.get("end_second", 0))
        dur = max(0.0, end - start)
        duplicate = False
        for k in kept:
            k_start = float(k.get("start_second", 0))
            k_end = float(k.get("end_second", 0))
            overlap = max(0.0, min(end, k_end) - max(start, k_start))
            shorter = min(dur, max(0.0, k_end - k_start)) or 1.0
            if overlap / shorter > 0.5:
                duplicate = True
                break
        if not duplicate:
            kept.append(clip)
    return sorted(kept, key=lambda c: c.get("start_second", 0))


def _drop_clips_overlapping(clips: list[dict], exclude_clips: list[dict]) -> list[dict]:
    """Drop clips that overlap an excluded range by >50% of the shorter clip.
    The prompt already asks the AI to skip these; this enforces it if it doesn't."""
    if not exclude_clips:
        return clips
    kept = []
    for clip in clips:
        start = float(clip.get("start_second", 0))
        end = float(clip.get("end_second", 0))
        dur = max(0.0, end - start)
        overlaps = False
        for ex in exclude_clips:
            ex_start = float(ex.get("start_second", 0))
            ex_end = float(ex.get("end_second", 0))
            overlap = max(0.0, min(end, ex_end) - max(start, ex_start))
            shorter = min(dur, max(0.0, ex_end - ex_start)) or 1.0
            if overlap / shorter > 0.5:
                overlaps = True
                break
        if not overlaps:
            kept.append(clip)
    return kept


def _select_top_by_score(clips: list[dict], top_n: int) -> list[dict]:
    """Keep the best `top_n` clips, then order them by start time.

    An explicit `rank` wins over the score, but only when every clip has one.
    """
    if len(clips) <= top_n:
        return sorted(clips, key=lambda c: c.get("start_second", 0))
    if clips and all(isinstance(c.get("rank"), int) for c in clips):
        ranked = sorted(clips, key=lambda c: c["rank"])[:top_n]
    else:
        ranked = sorted(clips, key=lambda c: c.get("score", 0), reverse=True)[:top_n]
    return sorted(ranked, key=lambda c: c.get("start_second", 0))


def find_moments_from_text(
    description: str,
    segments: list[dict],
    existing_clips: Optional[list[dict]] = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    max_results: int = 3,
    bounds: ClipBounds | None = None,
) -> list[dict]:
    """Locate the moment(s) the user described/pasted in the transcript.
    Returns clip dicts (same shape as suggest_with_claude). Status goes to
    progress_callback; warnings to stderr: never stdout, which is the task
    runner's JSON-RPC channel."""
    existing_clips = existing_clips or []
    bounds = bounds or ClipBounds.of()
    if not ai_provider.available():
        print("No AI available for moment search", file=sys.stderr, flush=True)
        return []

    if progress_callback:
        progress_callback(15, "Reading transcript...")
    transcript_text = _build_transcript_text(segments)

    existing_desc = ""
    if existing_clips:
        existing_desc = "\n\nALREADY SELECTED (do not re-suggest these):\n"
        for c in existing_clips:
            existing_desc += f"- {c.get('start_second')}s-{c.get('end_second')}s: {c.get('title', '')}\n"

    upper = max(1, int(max_results))
    prompt = f"""Find the moment(s) the user is describing in this podcast transcript. Return ONLY valid JSON.

USER WANTS: "{description}"
{existing_desc}
RULES:
- Find the EXACT moment(s) matching what the user pasted/described
- The user may list several moments. Return one clip per distinct moment they mention
- Return 1-{upper} matching moments (best match first)
- All timestamps in SECONDS as numbers
- Duration target: {bounds.target_min}-{bounds.target_max} seconds, max {bounds.dur_max} seconds
- Cut tight: start at the hook, end when the point lands
- Use segments to cut filler if needed
- If the moment is an ANSWER, start on the QUESTION that prompted it. A question is
  not preamble. If it rambles past ~8 seconds, cut the rambling with "segments".
- State the PAYOFF: one sentence, second person, on what the viewer walks away with.
  Write the title from it. Never copy the first sentence of the moment into the title.
- In "needs", name what the viewer must already know, or "nothing". If it is anything
  else, move start_second back until the clip covers it. "context_line" is a note for
  the editor, not a fix: nothing burns it into the video.
- Optional "hook": {{"start": X, "end": Y, "mode": "repeat" or "move"}}, 1-15 seconds of
  words spoken inside the clip, played first. Leave it out when the clip opens strong.

Return this JSON:
{{
  "clips": [
    {{
      "title": "Written for the viewer, never copied from the transcript",
      "start_second": 123.4,
      "end_second": 158.4,
      "segments": [{{"start": 123.4, "end": 158.4}}],
      "duration": 35,
      "content_type": "guest_story",
      "scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},
      "total_score": 16,
      "quote": "The key quote",
      "payoff": "What the viewer walks away with, one sentence, second person",
      "needs": "nothing",
      "context_line": "",
      "why": "Why this matches what the user asked for"
    }}
  ]
}}

Transcript:
{transcript_text}"""

    project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")

    def announce(label: str) -> None:
        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,
            adapt=_codex_adapter(transcript_text),
        )
        if data:
            found = []
            for c in data.get("clips", []):
                total = _total_score(c)
                keep_segments = []
                for seg in c.get("segments", []):
                    s = round(float(seg.get("start", 0)), 1)
                    e = round(float(seg.get("end", 0)), 1)
                    if e > s:
                        keep_segments.append({"start": s, "end": e})

                start_sec = round(float(c.get("start_second", 0)), 1)
                end_sec = round(float(c.get("end_second", 0)), 1)
                if not keep_segments and end_sec > start_sec:
                    keep_segments = [{"start": start_sec, "end": end_sec}]

                kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)
                if not bounds.keeps(kept_duration):
                    continue

                clip_start = keep_segments[0]["start"] if keep_segments else start_sec
                clip_end = keep_segments[-1]["end"] if keep_segments else end_sec
                found.append({
                    "title": clean_title(c.get("title", "Untitled")),
                    "start_second": clip_start,
                    "end_second": clip_end,
                    "segments": keep_segments,
                    "hook": _suggested_hook(c, clip_start, clip_end, keep_segments),
                    "duration": round(kept_duration),
                    "score": total,
                    "content_type": c.get("content_type", "unknown"),
                    "reasoning": c.get("why", ""),
                    "payoff": c.get("payoff", ""),
                    "standalone": c.get("needs", ""),
                    "context_line": c.get("context_line", ""),
                    "preview_text": c.get("quote", "")[:120],
                    "suggested_caption_style": caption_style,
                    "quote": c.get("quote", ""),
                    "why": c.get("why", ""),
                    "reasons": [c.get("content_type", "")],
                    "preview": c.get("quote", "")[:120],
                })

            if found:
                return _dedupe_clips_by_range(found)

        return []

    except Exception as e:
        print(f"Moment search error: {e}", file=sys.stderr, flush=True)
        return []


def suggest_with_claude(
    segments: list[dict],
    top_n: int = 5,
    exclude_clips: list[dict] | None = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    timeout: int = 900,
    error_sink: Optional[list[str]] = None,
    reaction_times: list[float] | None = None,
    bounds: ClipBounds | None = None,
) -> Optional[list[dict]]:
    """
    Use an AI CLI (Claude Code or Codex) to extract the best clip moments.

    Tries available AI CLIs in preference order and retries on runtime failure.
    Returns None if neither succeeds.
    """
    providers = ai_provider.status()["providers"]
    if not providers:
        return None
    bounds = bounds or ClipBounds.of()

    if progress_callback:
        progress_callback(0, f"Preparing transcript for {providers[0]['label']}...")

    transcript_text = _build_transcript_text(segments)

    # Estimate duration
    duration_min = 0
    if segments:
        duration_min = (segments[-1].get("end", 0) - segments[0].get("start", 0)) / 60

    prompt = _build_prompt(
        transcript_text,
        len(segments),
        duration_min,
        top_n,
        exclude_clips=exclude_clips,
        reaction_times=reaction_times,
        bounds=bounds,
    )

    project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")

    def _parse_seconds(val) -> float:
        """Parse a timestamp value: handles both 123.4 and '2:03' formats."""
        if isinstance(val, (int, float)):
            return float(val)
        s = str(val).strip()
        if ":" in s:
            parts = s.split(":")
            try:
                return float(parts[0]) * 60 + float(parts[1])
            except (ValueError, IndexError):
                return 0.0
        try:
            return float(s)
        except ValueError:
            return 0.0

    attempted: list[str] = []
    current = {"label": ""}

    def announce(label: str) -> None:
        current["label"] = label
        if attempted and progress_callback:
            progress_callback(0, f"Retrying with {label}...")
        if progress_callback:
            progress_callback(20, f"Asking {label} to analyze transcript...")
        attempted.append(label)

    def usable(text: str):
        """Reject a response that parses but has nothing in it, so the next
        engine gets a turn rather than the user getting an empty result."""
        label = current["label"]
        if progress_callback:
            progress_callback(80, f"Parsing {label}'s suggestions...")
        parsed = ai_provider.extract_json(text)
        if not isinstance(parsed, dict):
            return f"{label} returned output that wasn't valid JSON"
        if not isinstance(parsed.get("clips"), list) or not parsed["clips"]:
            return f"{label} ran but found no clips in the transcript"
        return True

    cached_prefix, instruction = _split_prompt_for_cache(prompt, transcript_text)

    # What this channel's own published clips say about what works, plus the
    # house style learned from edits the team made to earlier output. Empty for
    # everyone else, so the free path is unchanged.
    learned = podcli_cloud.prompt_block()
    if learned:
        instruction = f"{learned}\n\n{instruction}"
        # local_prompt replaces the prompt outright, so local backends need it too.
        prompt = f"{learned}\n\n{prompt}"

    attempt = ai_provider.generate(
        instruction,
        timeout=timeout,
        project_dir=project_dir,
        on_attempt=announce,
        accept=usable,
        purpose="select_moments",
        stable_prefix=cached_prefix or None,
        # Local backends keep the prompt exactly as it has always been built;
        # only the cloud sees the split form.
        local_prompt=prompt,
        adapt=_codex_adapter(transcript_text),
    )

    if not attempt.ok:
        if progress_callback:
            progress_callback(0, attempt.error)
        if error_sink is not None:
            # Classified only for a CLI failure. The advice it adds is "run
            # `claude` once in a terminal", which is right for a local CLI and
            # wrong for a workspace session or an API key, and `classify_cli_error`
            # matches on "unauthorized" so it rewrote those too.
            # The CLI path tags the attempt with its engine name, not "cli",
            # so this asks the question the other way round.
            error_sink.append(
                attempt.error
                if attempt.provider in ("cloud", "api")
                else classify_cli_error(attempt.error)
            )
        return None

    label = attempt.label

    # Several independent searches over the same transcript find overlapping but
    # not identical moments. Keeping the union and re-ranking beats picking one
    # set, and the dedupe/scoring below already exists for exactly this shape.
    def records(payload: object) -> list[dict]:
        """
        The clip objects in a response, and only those.

        `usable` checked the primary response is a non-empty list, which still
        admits a null or a string inside it, and the alternates are not checked
        at all: `.get` on any of those is an AttributeError out of a code path
        with nothing above it to catch.
        """
        if not isinstance(payload, dict):
            return []
        found = payload.get("clips")
        if not isinstance(found, list):
            return []
        return [c for c in found if isinstance(c, dict)]

    clips = records(ai_provider.extract_json(attempt.text))
    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:
        total = _total_score(c)

        raw_segments = c.get("segments")
        raw_segments = raw_segments if isinstance(raw_segments, list) else []
        keep_segments = []
        for seg in raw_segments:
            if not isinstance(seg, dict):
                continue
            s = round(_parse_seconds(seg.get("start", 0)), 1)
            e = round(_parse_seconds(seg.get("end", 0)), 1)
            if e > s:
                keep_segments.append({"start": s, "end": e})

        start_sec = round(_parse_seconds(c.get("start_second", 0)), 1)
        end_sec = round(_parse_seconds(c.get("end_second", 0)), 1)

        if not keep_segments and end_sec > start_sec:
            keep_segments = [{"start": start_sec, "end": end_sec}]

        kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)
        if not bounds.keeps(kept_duration):
            continue

        clip_start = keep_segments[0]["start"] if keep_segments else start_sec
        clip_end = keep_segments[-1]["end"] if keep_segments else end_sec
        normalized.append({
            "title": clean_title(c.get("title", "Untitled")),
            "start_second": clip_start,
            "end_second": clip_end,
            "segments": keep_segments,
            "hook": _suggested_hook(c, clip_start, clip_end, keep_segments),
            "duration": round(kept_duration),
            "score": total,
            "content_type": c.get("content_type", "unknown"),
            "reasoning": c.get("why", ""),
            "payoff": c.get("payoff", ""),
            "standalone": c.get("needs", ""),
            "context_line": c.get("context_line", ""),
            "preview_text": c.get("quote", "")[:120],
            "suggested_caption_style": caption_style,
            "quote": c.get("quote", ""),
            "why": c.get("why", ""),
            "reasons": [c.get("content_type", "")],
            "preview": c.get("quote", "")[:120],
            "_ai_engine": attempt.provider,
        })

    # Dedupe within the pool as well as against already-selected clips: several
    # attempts routinely surface the same strong moment, and without this the
    # top N would be the same clip repeated.
    selected = _select_top_by_score(
        _drop_clips_overlapping(_dedupe_clips_by_range(normalized), exclude_clips or []),
        top_n,
    )

    if selected:
        if progress_callback:
            progress_callback(100, f"{label} suggested {len(selected)} clips")
        return selected

    if progress_callback:
        progress_callback(0, f"{label} returned no usable clips")
    if error_sink is not None:
        error_sink.append(
            f"{label} returned clips but none were usable (wrong length or format)"
        )
    return None


def suggest_initial_with_claude(
    segments: list[dict],
    top_n: int = 5,
    exclude_clips: list[dict] | None = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    error_sink: Optional[list[str]] = None,
    reaction_times: list[float] | None = None,
    bounds: ClipBounds | None = None,
) -> Optional[list[dict]]:
    """
    Initial clip discovery entry point.

    For long podcasts, search transcript buckets first so the AI can return
    quickly and cover the full timeline instead of timing out on one giant
    prompt.
    """
    exclude_clips = exclude_clips or []
    if not _should_bucket_initial_selection(segments):
        return suggest_with_claude(
            segments=segments,
            top_n=top_n,
            exclude_clips=exclude_clips,
            progress_callback=progress_callback,
            error_sink=error_sink,
            timeout=180,
            reaction_times=reaction_times,
            bounds=bounds,
        )

    start_bound = float(segments[0].get("start", 0))
    end_bound = float(segments[-1].get("end", segments[-1].get("start", 0)))
    duration = max(0.0, end_bound - start_bound)
    if duration <= 0:
        return None

    bucket_count = min(6, max(3, math.ceil((duration / 60.0) / 25.0)))
    bucket_size = duration / bucket_count
    buckets = []
    for idx in range(bucket_count):
        bucket_start = start_bound + idx * bucket_size
        bucket_end = end_bound if idx == bucket_count - 1 else start_bound + (idx + 1) * bucket_size
        bucket_segments = _slice_segments_for_range(segments, bucket_start, bucket_end)
        if len(bucket_segments) < 3:
            continue
        buckets.append({
            "start": bucket_start,
            "end": bucket_end,
            "segments": bucket_segments,
        })

    if not buckets:
        return suggest_with_claude(
            segments=segments,
            top_n=top_n,
            exclude_clips=exclude_clips,
            progress_callback=progress_callback,
            error_sink=error_sink,
            timeout=180,
            reaction_times=reaction_times,
            bounds=bounds,
        )

    if progress_callback:
        progress_callback(0, f"Long episode detected: searching {len(buckets)} timeline buckets...")

    aggregated: list[dict] = []
    per_bucket_top_n = max(2, math.ceil(top_n / max(1, len(buckets))))

    for idx, bucket in enumerate(buckets):
        bucket_label = (
            f"bucket {idx + 1}/{len(buckets)} "
            f"[{int(bucket['start'] // 60)}:{int(bucket['start'] % 60):02d}-"
            f"{int(bucket['end'] // 60)}:{int(bucket['end'] % 60):02d}]"
        )
        if progress_callback:
            progress_callback(0, f"Searching {bucket_label}...")

        bucket_clips = suggest_with_claude(
            segments=bucket["segments"],
            top_n=per_bucket_top_n,
            exclude_clips=exclude_clips + aggregated,
            progress_callback=(
                None if progress_callback is None
                else lambda pct, msg, bucket_label=bucket_label: progress_callback(
                    pct,
                    f"{bucket_label}: {msg}" if msg else msg,
                )
            ),
            error_sink=error_sink,
            timeout=90,
            reaction_times=[
                t for t in (reaction_times or []) if bucket["start"] <= t <= bucket["end"]
            ] or None,
            bounds=bounds,
        )
        if not bucket_clips:
            continue

        aggregated.extend(bucket_clips)

    deduped = _dedupe_clips_by_range(aggregated)
    if len(deduped) >= top_n:
        return _select_top_by_score(deduped, top_n)

    fallback_clips = suggest_with_claude(
        segments=segments,
        top_n=top_n,
        exclude_clips=exclude_clips + deduped,
        progress_callback=(
            None if progress_callback is None
            else lambda pct, msg: progress_callback(
                pct,
                f"global pass: {msg}" if msg else msg,
            )
        ),
        error_sink=error_sink,
        timeout=120,
        reaction_times=reaction_times,
        bounds=bounds,
    )
    if fallback_clips:
        deduped = _dedupe_clips_by_range(deduped + fallback_clips)

    return _select_top_by_score(deduped, top_n) if deduped else None


REACTION_BLEND_WEIGHT = 0.2
ENERGY_BLEND_WEIGHT = 0.1


def blend_signal_scores(
    clips: list[dict],
    energy_data: list[dict] | None = None,
    events_data: list[dict] | None = None,
    reaction_weight: float = REACTION_BLEND_WEIGHT,
    energy_weight: float = ENERGY_BLEND_WEIGHT,
) -> list[dict]:
    """Blend per-clip reaction/energy peaks into AI-selected clip scores.

    The AI score (0-20) stays primary: the 0-10 signal scores are added at
    modest weight (max +3 combined), so laughter or an energy spike breaks
    ties rather than overruling editorial judgment. Mutates and returns
    `clips`, preserving their order.
    """
    if not clips or (not energy_data and not events_data):
        return clips

    ranges = [
        {"start": float(c.get("start_second", 0)), "end": float(c.get("end_second", 0))}
        for c in clips
    ]
    reaction_scores = compute_event_scores(events_data or [], ranges)
    energy_scores = compute_energy_scores(energy_data or [], ranges)

    for clip, rng, r_score, e_score in zip(clips, ranges, reaction_scores, energy_scores):
        boost = round(reaction_weight * r_score + energy_weight * e_score, 2)
        if boost <= 0:
            continue
        clip["signal_boost"] = boost
        clip["score"] = round(float(clip.get("score", 0)) + boost, 2)
        if r_score > 3:
            label = dominant_reaction(events_data or [], rng["start"], rng["end"]) or "reaction"
            if label not in (clip.get("reasons") or []):
                clip.setdefault("reasons", []).append(label)
    return clips


MIN_RANKABLE_SURPLUS = 2


def rank_clips_with_ai(
    clips: list[dict],
    top_n: int,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    timeout: int = 45,
) -> list[dict]:
    """Compare a whole candidate pool in one transcript-free pass.

    Mutates and returns `clips`, writing a 1-based `rank` and leaving `score`
    untouched. Falls back to score ordering on any failure.
    """
    if len(clips) < top_n + MIN_RANKABLE_SURPLUS:
        return clips

    lines = []
    for idx, clip in enumerate(clips):
        boost = clip.get("signal_boost")
        lines.append(
            f'{idx}. "{clip.get("title", "Untitled")}" '
            f'[{clip.get("duration", 0)}s, {clip.get("content_type", "unknown")}, '
            f'score {clip.get("score", 0)}'
            + (f', audience reaction +{boost}' if boost else "")
            + "]\n"
            f'   quote: {str(clip.get("quote", ""))[:200]}\n'
            f'   why: {str(clip.get("why", ""))[:200]}'
        )

    learned = podcli_cloud.prompt_block()
    prompt = f"""You are choosing which {top_n} of these {len(clips)} podcast clips to publish.

IMPORTANT: Return ONLY valid JSON. No markdown, no explanation, no code fences.

Each candidate was found by a separate pass over one stretch of the episode, so
their scores are not comparable to each other. Rank them against each other now.

Rank on:
- Would a stranger stop scrolling for this? That is the whole job.
- Does it stand alone, with no missing setup?
- Does it end on a complete thought rather than trailing off?
- Variety across the set: {top_n} clips that make the same point is one clip.

{f"{learned}{chr(10)}{chr(10)}" if learned else ""}CANDIDATES:
{chr(10).join(lines)}

Return this exact JSON structure, best first, every candidate listed exactly once:
{{
  "ranked": [
    {{"id": 3, "why": "One sentence on why this outranks the rest"}},
    {{"id": 0, "why": "..."}}
  ]
}}"""

    label = {"value": "AI"}

    def announce(name: str) -> None:
        label["value"] = name
        if progress_callback:
            progress_callback(0, f"Ranking {len(clips)} candidates with {name}...")

    project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")
    payload, result = ai_provider.generate_json(
        prompt,
        timeout=timeout,
        project_dir=project_dir,
        on_attempt=announce,
        purpose="rank_moments",
    )

    def give_up(reason: str) -> list[dict]:
        if progress_callback:
            progress_callback(100, f"Ranking unavailable, using scores ({reason})")
        print(f"Clip ranking skipped: {reason}", file=sys.stderr, flush=True)
        return clips

    if not result.ok:
        return give_up(result.error or "ranking pass produced no response")
    if not isinstance(payload, dict) or not isinstance(payload.get("ranked"), list):
        return give_up(f"{label['value']} returned a ranking in an unreadable shape")

    order: list[int] = []
    for entry in payload["ranked"]:
        if not isinstance(entry, dict):
            continue
        idx = entry.get("id")
        if isinstance(idx, int) and 0 <= idx < len(clips) and idx not in order:
            order.append(idx)

    if len(order) < len(clips):
        return give_up(
            f"{label['value']} ranked {len(order)} of {len(clips)} candidates"
        )

    for position, idx in enumerate(order, start=1):
        clips[idx]["rank"] = position
    if progress_callback:
        progress_callback(100, f"{label['value']} ranked {len(clips)} candidates")
    return clips


def select_clips_with_signal_scores(
    clips: list[dict],
    top_n: int,
    energy_data: list[dict] | None = None,
    events_data: list[dict] | None = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
) -> list[dict]:
    """Blend the audio signals in, rank against each other, cut to `top_n`."""
    blended = blend_signal_scores(clips, energy_data=energy_data, events_data=events_data)
    ranked = rank_clips_with_ai(blended, top_n, progress_callback=progress_callback)
    return _select_top_by_score(ranked, top_n)


def _bucket_coverage_seconds(existing_clips: list[dict], start: float, end: float) -> float:
    """Total selected-clip overlap inside a time bucket."""
    covered = 0.0
    for clip in existing_clips:
        overlap_start = max(start, float(clip.get("start_second", 0)))
        overlap_end = min(end, float(clip.get("end_second", 0)))
        if overlap_end > overlap_start:
            covered += overlap_end - overlap_start
    return covered


def _slice_segments_for_range(segments: list[dict], start: float, end: float) -> list[dict]:
    """Return transcript segments that overlap a bucket range."""
    return [
        seg for seg in segments
        if float(seg.get("end", seg.get("start", 0))) > start
        and float(seg.get("start", 0)) < end
    ]


def suggest_more_with_claude(
    segments: list[dict],
    existing_clips: list[dict],
    top_n: int = 8,
    progress_callback: Optional[Callable[[int, str], None]] = None,
    bounds: ClipBounds | None = None,
) -> Optional[list[dict]]:
    """
    Ask the AI for more clips by searching under-covered time buckets first.

    This prevents the common failure mode where repeated whole-episode prompts
    keep returning the same few obvious moments.
    """
    if not segments:
        return None

    start_bound = float(segments[0].get("start", 0))
    end_bound = float(segments[-1].get("end", segments[-1].get("start", 0)))
    duration = max(0.0, end_bound - start_bound)
    if duration <= 0:
        return None

    bucket_count = min(6, max(3, math.ceil((duration / 60.0) / 25.0)))
    bucket_size = duration / bucket_count
    buckets = []
    for idx in range(bucket_count):
        bucket_start = start_bound + idx * bucket_size
        bucket_end = end_bound if idx == bucket_count - 1 else start_bound + (idx + 1) * bucket_size
        bucket_segments = _slice_segments_for_range(segments, bucket_start, bucket_end)
        if len(bucket_segments) < 3:
            continue
        coverage_seconds = _bucket_coverage_seconds(existing_clips, bucket_start, bucket_end)
        bucket_duration = max(1.0, bucket_end - bucket_start)
        buckets.append({
            "start": bucket_start,
            "end": bucket_end,
            "segments": bucket_segments,
            "coverage_ratio": coverage_seconds / bucket_duration,
            "coverage_seconds": coverage_seconds,
        })

    if not buckets:
        return suggest_with_claude(
            segments=segments,
            top_n=top_n,
            exclude_clips=existing_clips,
            progress_callback=progress_callback,
            bounds=bounds,
        )

    buckets.sort(key=lambda b: (b["coverage_ratio"], b["coverage_seconds"], b["start"]))
    target_bucket_count = min(len(buckets), max(2, min(4, math.ceil(top_n / 3.0))))
    selected_buckets = buckets[:target_bucket_count]
    remaining_buckets = buckets[target_bucket_count:]
    per_bucket_top_n = max(2, math.ceil(top_n / max(1, len(selected_buckets))))

    aggregated: list[dict] = []
    for idx, bucket in enumerate(selected_buckets):
        bucket_label = f"bucket {idx + 1}/{len(selected_buckets)} [{int(bucket['start'] // 60)}:{int(bucket['start'] % 60):02d}-{int(bucket['end'] // 60)}:{int(bucket['end'] % 60):02d}]"
        if progress_callback:
            progress_callback(0, f"Searching {bucket_label}...")

        bucket_clips = suggest_with_claude(
            segments=bucket["segments"],
            top_n=per_bucket_top_n,
            exclude_clips=existing_clips + aggregated,
            progress_callback=(
                None if progress_callback is None
                else lambda pct, msg, bucket_label=bucket_label: progress_callback(
                    pct,
                    f"{bucket_label}: {msg}" if msg else msg,
                )
            ),
            bounds=bounds,
        )
        if not bucket_clips:
            continue

        aggregated.extend(bucket_clips)
        if len(aggregated) >= top_n:
            break

    if len(aggregated) < top_n and remaining_buckets:
        for idx, bucket in enumerate(remaining_buckets, start=len(selected_buckets) + 1):
            bucket_label = f"bucket {idx}/{len(buckets)} [{int(bucket['start'] // 60)}:{int(bucket['start'] % 60):02d}-{int(bucket['end'] // 60)}:{int(bucket['end'] % 60):02d}]"
            if progress_callback:
                progress_callback(0, f"Searching {bucket_label}...")

            bucket_clips = suggest_with_claude(
                segments=bucket["segments"],
                top_n=max(1, min(per_bucket_top_n, top_n - len(aggregated))),
                exclude_clips=existing_clips + aggregated,
                progress_callback=(
                    None if progress_callback is None
                    else lambda pct, msg, bucket_label=bucket_label: progress_callback(
                        pct,
                        f"{bucket_label}: {msg}" if msg else msg,
                    )
                ),
                bounds=bounds,
            )
            if not bucket_clips:
                continue

            aggregated.extend(bucket_clips)
            if len(aggregated) >= top_n:
                break

    if len(aggregated) < max(2, min(top_n, 4)):
        fallback_clips = suggest_with_claude(
            segments=segments,
            top_n=top_n,
            exclude_clips=existing_clips + aggregated,
            progress_callback=(
                None if progress_callback is None
                else lambda pct, msg: progress_callback(
                    pct,
                    f"global pass: {msg}" if msg else msg,
                )
            ),
            bounds=bounds,
        )
        if fallback_clips:
            aggregated.extend(fallback_clips)

    deduped = _dedupe_clips_by_range(aggregated)
    return _select_top_by_score(deduped, top_n) if deduped else None