LLM-Assisted Chapter Titling from Transcripts

WARN  title_ground  ep=142  chapter=4  title="Kubernetes autoscaling deep dive"  span_has_terms=false
WARN  title_length  ep=142  chapter=6  title="A wide-ranging and thoughtful conversation about the future of..."  chars=78  max=72
INFO  title_accept  ep=142  chapter=1  title="Why we rebuilt the transcoder"  chars=29  grounded=true

# anthropic==0.69.0   python 3.10+
import os
import re
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

MODEL = "claude-sonnet-5"
MAX_TITLE_CHARS = 72

SYSTEM = (
    "You write chapter titles for podcast episodes. Given the transcript of one "
    "chapter, output a single title of at most 8 words that names only what is "
    "actually discussed in that transcript. Do not add topics, names, or facts "
    "that are not present in the text. No quotation marks, no trailing "
    "punctuation, no preamble — output the title and nothing else."
)

def build_prompt(span_text: str) -> str:
    # Cap the span so a long chapter can't blow the input budget; the head and
    # tail of a chapter carry most of its topical signal.
    span = span_text.strip()
    if len(span) > 6000:
        span = span[:3000] + " […] " + span[-3000:]
    return f"Chapter transcript:\n\n{span}\n\nChapter title:"

def title_chapter(span_text: str) -> str | None:
    """Return a grounded, constrained title, or None if the model output fails the gate."""
    resp = client.messages.create(
        model=MODEL,
        max_tokens=40,                        # a title needs very few tokens
        temperature=0,                        # greedy decoding for stable titles
        system=SYSTEM,
        messages=[{"role": "user", "content": build_prompt(span_text)}],
    )
    text_blocks = [b.text for b in resp.content if b.type == "text"]
    if not text_blocks:
        return None
    return clean_title(text_blocks[0])

def clean_title(raw: str) -> str:
    title = raw.strip().strip('"“”').rstrip(".!?")
    return re.sub(r"\s+", " ", title)

# python 3.10+
_STOP = {"the","a","an","and","or","of","to","in","on","for","with","how",
         "why","what","we","our","is","are","this","that","about"}

def content_words(text: str) -> set[str]:
    return {w for w in re.findall(r"[a-z']+", text.lower()) if w not in _STOP and len(w) > 2}

def is_grounded(title: str, span_text: str, min_overlap: float = 0.6) -> bool:
    tw = content_words(title)
    if not tw:
        return False
    span_words = content_words(span_text)
    covered = sum(1 for w in tw if w in span_words)
    return covered / len(tw) >= min_overlap

def extractive_title(span_text: str) -> str:
    # Deterministic fallback: the first reasonably long sentence, truncated.
    sentences = re.split(r"(?<=[.!?])\s+", span_text.strip())
    pick = next((s for s in sentences if len(s) > 25), sentences[0] if sentences else "Chapter")
    return clean_title(pick)[:MAX_TITLE_CHARS]

def resolve_title(span_text: str) -> tuple[str, bool]:
    """Return (title, llm_used). Falls back to extractive on any failure."""
    candidate = title_chapter(span_text)
    if candidate and len(candidate) <= MAX_TITLE_CHARS and is_grounded(candidate, span_text):
        return candidate, True
    return extractive_title(span_text), False

# python 3.10+
from concurrent.futures import ThreadPoolExecutor

def title_all(spans: list[str], workers: int = 8) -> list[tuple[str, bool]]:
    with ThreadPoolExecutor(max_workers=workers) as pool:
        return list(pool.map(resolve_title, spans))

# 1. A clean span yields a short, grounded, LLM-generated title.
python -c "
from titler import resolve_title
t, used = resolve_title(open('span_clean.txt').read())
print(repr(t), 'llm=', used, 'len=', len(t))
assert used and len(t) <= 72
"

# 2. A low-signal span (filler / crosstalk) must fall back, never fabricate.
python -c "
from titler import resolve_title
t, used = resolve_title('um yeah so anyway right exactly totally yeah for sure')
print(repr(t), 'llm=', used)
assert used is False   # grounding gate rejected any invented title
"

# 3. Every emitted title fits the length limit across a whole episode.
jq -e 'all(.[]; (.title | length) <= 72 and (.title | length) > 0)' chapters.json