Skip to content

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

7.4 KB
Raw Blame
"""Compile clip performance into a knowledge-base file Claude reads when
picking shorts. Structured (no LLM): regenerated whenever metrics sync.

The clip-picking skills glob .podcli/knowledge/*.md, so writing the digest
here is what closes the loop: the next suggest_clips run is informed by what
actually performed.
"""
from __future__ import annotations

import os
import statistics
from collections import defaultdict
from datetime import datetime, timezone
from typing import Any, Callable, Optional

# Below this, one viral or one flop clip swings the bucket's number enough
# that it reads as a trend. Hide it until there's enough data to trust.
MIN_BUCKET_SIZE = 4

from config.paths import paths
from services.clips_history import load_clips_history

LEARNINGS_FILE = "13-performance-learnings.md"
AI_START = "<!-- AI-ANALYSIS-START -->"
AI_END = "<!-- AI-ANALYSIS-END -->"


def _existing_ai_block(path: str) -> str:
    if not os.path.exists(path):
        return ""
    txt = open(path, encoding="utf-8").read()
    i, j = txt.find(AI_START), txt.find(AI_END)
    return txt[i:j + len(AI_END)] if (i != -1 and j != -1) else ""


def _has_perf(c: dict) -> bool:
    m = c.get("metrics") or {}
    return m.get("views") is not None or m.get("retention") is not None


def _agg(clips: list[dict], key: Callable[[dict], Any]) -> list[dict]:
    """Group clips by `key` and report the median (not mean) of each metric,
    since one viral or one flop clip would otherwise swing a small bucket's
    average far past what's typical. Buckets under MIN_BUCKET_SIZE are
    dropped: too little data to call it a trend."""
    groups: dict[str, list[dict]] = defaultdict(list)
    for c in clips:
        groups[key(c) or "unknown"].append(c)
    out = []
    for k, cs in groups.items():
        if len(cs) < MIN_BUCKET_SIZE:
            continue
        vals = lambda f: [c["metrics"][f] for c in cs if (c.get("metrics") or {}).get(f) is not None]
        ret, ctr, views = vals("retention"), vals("ctr"), vals("views")
        out.append({
            "key": k, "n": len(cs),
            "ret": round(statistics.median(ret), 1) if ret else None,
            "ctr": round(statistics.median(ctr), 1) if ctr else None,
            "views": int(statistics.median(views)) if views else None,
        })
    return out


def _length_bucket(c: dict) -> str:
    d = c.get("duration") or 0
    return "<25s" if d < 25 else "25-35s" if d < 35 else "35-45s" if d < 45 else "45s+"


def write_learnings(min_clips: int = 3, ai_block: Optional[str] = None) -> Optional[str]:
    """Regenerate the performance-learnings knowledge file. None if too little data.

    The structured 'what's working' section is rebuilt every call; any AI-analysis
    block is preserved (or replaced when ai_block is passed)."""
    clips = [c for c in load_clips_history() if _has_perf(c)]
    if len(clips) < min_clips:
        return None

    by_type = sorted(_agg(clips, lambda c: c.get("content_type")), key=lambda r: r["ret"] or 0, reverse=True)
    by_caption = sorted(_agg(clips, lambda c: c.get("caption_style")), key=lambda r: r["ctr"] or 0, reverse=True)
    by_length = sorted(_agg(clips, _length_bucket), key=lambda r: r["ret"] or 0, reverse=True)
    top = sorted(clips, key=lambda c: (c.get("metrics") or {}).get("views") or 0, reverse=True)[:5]
    now = datetime.now(timezone.utc).strftime("%Y-%m-%d")

    L: list[str] = [
        "# Performance learnings",
        "",
        "<!-- AUTO-GENERATED by `podcli youtube sync`. The 'What's working now' section is",
        "     regenerated each sync: edits there are overwritten. -->",
        "",
        f"## What's working now (updated {now} · {len(clips)} published clips)",
        "",
        "Retention = content quality (did it hold viewers). CTR = packaging (title/thumbnail). Views = reach.",
        "",
        "**By moment type (retention):**",
    ]
    L += [f"- {r['key']}: {r['ret']}% retention · {r['ctr']}% CTR · ~{r['views']} views (n={r['n']})" for r in by_type]
    L += ["", "**By caption style (CTR):**"]
    L += [f"- {r['key']}: {r['ctr']}% CTR · {r['ret']}% retention (n={r['n']})" for r in by_caption]
    L += ["", "**By length (retention):**"]
    L += [f"- {r['key']}: {r['ret']}% retention (n={r['n']})" for r in by_length]
    L += ["", "**Top performers:**"]
    L += [f"- \"{c['title']}\": {(c.get('metrics') or {}).get('views')} views, {(c.get('metrics') or {}).get('retention')}% retention [{c.get('content_type', '?')}]" for c in top]
    L += ["", "## Guidance for picking shorts", ""]
    if by_type:
        L.append(f"- Prioritize **{by_type[0]['key']}** moments: highest retention ({by_type[0]['ret']}%).")
    best_ctr = next((r for r in by_caption if r["ctr"]), None)
    if best_ctr:
        L.append(f"- **{best_ctr['key']}** captions earn the most clicks ({best_ctr['ctr']}% CTR).")
    if by_length:
        L.append(f"- Target **{by_length[0]['key']}** clips for retention.")
    L.append("")

    os.makedirs(paths["knowledge"], exist_ok=True)
    path = os.path.join(paths["knowledge"], LEARNINGS_FILE)
    block = ai_block if ai_block is not None else _existing_ai_block(path)
    content = "\n".join(L)
    if block:
        content += "\n\n" + block + "\n"
    with open(path, "w", encoding="utf-8") as f:
        f.write(content)
    return path


def _clip_line(c: dict) -> str:
    m = c.get("metrics") or {}
    return (f"- [{c.get('content_type', '?')} · {c.get('caption_style', '?')} · {round(c.get('duration', 0))}s · "
            f"{m.get('retention')}% retention · {m.get('ctr')}% CTR] \"{c.get('title')}\"\n"
            f"  transcript: {c.get('transcript_slice', '')[:400]}")


def write_semantic_learnings(top_n: int = 4, min_total: int = 6) -> Optional[str]:
    """Token-frugal LLM pass: contrast top vs bottom clips by retention and write
    a qualitative 'why winners win' block. Returns the file path, or None if there
    isn't enough data or no AI CLI is available."""
    clips = [c for c in load_clips_history()
             if _has_perf(c) and c.get("transcript_slice") and (c.get("metrics") or {}).get("retention") is not None]
    if len(clips) < min_total:
        return None
    ranked = sorted(clips, key=lambda c: c["metrics"]["retention"], reverse=True)
    top_performers, underperformers = ranked[:top_n], ranked[-top_n:]

    try:
        from services import ai_provider
    except Exception:
        return None
    if not ai_provider.available():
        return None

    prompt = (
        "You analyze short-form video performance to guide future clip selection.\n"
        "Below are the highest- and lowest-retention clips from one podcast channel.\n\n"
        "TOP PERFORMERS:\n" + "\n".join(_clip_line(c) for c in top_performers) +
        "\n\nUNDERPERFORMERS:\n" + "\n".join(_clip_line(c) for c in underperformers) +
        "\n\nIn 4-6 concise markdown bullets, state the concrete content patterns that distinguish "
        "the top performers from the underperformers (hooks, topic, emotional beat, structure) and give "
        "actionable guidance for picking future shorts. No preamble, just the bullets."
    )
    result = ai_provider.generate(prompt, timeout=180, project_dir=paths["project_root"])
    if not result.ok:
        return None
    text = result.text
    now = datetime.now(timezone.utc).strftime("%Y-%m-%d")
    block = f"{AI_START}\n## What separates top performers (AI analysis · {now})\n\n{text}\n{AI_END}"
    return write_learnings(ai_block=block)