Upload 12 files

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+.venv/

GUIDE.md

@@ -0,0 +1,252 @@
+# Step-by-Step Setup and Usage Guide
+
+Author: algorembrant
+
+---
+
+## Prerequisites
+
+| Requirement          | Minimum Version | Notes                                      |
+|----------------------|-----------------|--------------------------------------------|
+| Python               | 3.8             | 3.10+ recommended                          |
+| pip                  | 21.0            |                                            |
+| Anthropic API Key    | --              | Required for clean and summarize commands  |
+
+You need an Anthropic API key to use the `clean`, `summarize`, and `pipeline` commands.
+Obtain one at: https://console.anthropic.com
+
+---
+
+## Step 1 — Get the Code
+
+**Option A: Git clone**
+```bash
+git clone https://github.com/algorembrant/youtube-transcript-toolkit.git
+cd youtube-transcript-toolkit
+```
+
+**Option B: Download ZIP**
+Download and unzip, then open a terminal inside the project folder.
+
+---
+
+## Step 2 — Create a Virtual Environment
+
+**macOS / Linux**
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+**Windows (Command Prompt)**
+```cmd
+python -m venv .venv
+.venv\Scripts\activate.bat
+```
+
+**Windows (PowerShell)**
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+```
+
+You should see `(.venv)` at the start of your terminal prompt.
+
+---
+
+## Step 3 — Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+Verify:
+```bash
+pip show anthropic
+pip show youtube-transcript-api
+```
+
+---
+
+## Step 4 — Set Your Anthropic API Key
+
+**macOS / Linux (current session)**
+```bash
+export ANTHROPIC_API_KEY="sk-ant-your-key-here"
+```
+
+**macOS / Linux (permanent — add to shell profile)**
+```bash
+echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Windows (Command Prompt)**
+```cmd
+set ANTHROPIC_API_KEY=sk-ant-your-key-here
+```
+
+**Windows (PowerShell)**
+```powershell
+$env:ANTHROPIC_API_KEY = "sk-ant-your-key-here"
+```
+
+**Windows (permanent via System Settings)**
+1. Search "Environment Variables" in Start Menu
+2. Click "Edit the system environment variables"
+3. Add a new variable: `ANTHROPIC_API_KEY` = your key
+
+The `fetch` and `list` commands do NOT require an API key.
+Only `clean`, `summarize`, and `pipeline` need it.
+
+---
+
+## Step 5 — Run Your First Commands
+
+### Fetch a raw transcript (no API key needed)
+
+```bash
+python main.py fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+```
+
+### See what languages are available
+
+```bash
+python main.py list dQw4w9WgXcQ
+```
+
+### Clean the transcript into paragraphs
+
+```bash
+python main.py clean dQw4w9WgXcQ
+```
+
+### Summarize the transcript
+
+```bash
+python main.py summarize dQw4w9WgXcQ -m brief
+python main.py summarize dQw4w9WgXcQ -m detailed
+python main.py summarize dQw4w9WgXcQ -m bullets
+python main.py summarize dQw4w9WgXcQ -m outline
+```
+
+### Run the full pipeline (fetch + clean + summarize)
+
+```bash
+python main.py pipeline dQw4w9WgXcQ -m bullets
+```
+
+---
+
+## Step 6 — Save Output to Files
+
+### Single video — specify a file path
+
+```bash
+python main.py clean dQw4w9WgXcQ -o cleaned.txt
+python main.py summarize dQw4w9WgXcQ -m detailed -o summary.txt
+```
+
+### Pipeline — specify a directory (creates 3 files per video)
+
+```bash
+python main.py pipeline dQw4w9WgXcQ -o ./output/
+```
+
+Files created:
+```
+./output/
+  dQw4w9WgXcQ_transcript.txt
+  dQw4w9WgXcQ_cleaned.txt
+  dQw4w9WgXcQ_summary.txt
+```
+
+### Batch — multiple videos at once
+
+```bash
+python main.py pipeline VIDEO_ID_1 VIDEO_ID_2 VIDEO_ID_3 -o ./batch_output/
+```
+
+---
+
+## Step 7 — Advanced Options
+
+### Use the higher-quality model
+
+```bash
+python main.py clean dQw4w9WgXcQ --quality
+python main.py summarize dQw4w9WgXcQ -m detailed --quality
+```
+
+Default model: `claude-haiku-4-5` (fast, cost-efficient)
+Quality model: `claude-sonnet-4-6` (better for complex or long transcripts)
+
+### Disable streaming (show output only after completion)
+
+```bash
+python main.py clean dQw4w9WgXcQ --no-stream
+```
+
+### Request a non-English transcript
+
+```bash
+python main.py clean dQw4w9WgXcQ -l ja       # Japanese only
+python main.py clean dQw4w9WgXcQ -l es en    # Spanish, fall back to English
+```
+
+### Fetch raw transcript as SRT or JSON
+
+```bash
+python main.py fetch dQw4w9WgXcQ -f srt -o captions.srt
+python main.py fetch dQw4w9WgXcQ -f json -o transcript.json
+python main.py fetch dQw4w9WgXcQ -f vtt -o captions.vtt
+```
+
+### Fetch with timestamps
+
+```bash
+python main.py fetch dQw4w9WgXcQ -t
+python main.py pipeline dQw4w9WgXcQ -t -o ./output/
+```
+
+### Pipeline — skip individual steps
+
+```bash
+# Fetch and summarize without cleaning
+python main.py pipeline dQw4w9WgXcQ --skip-clean -m bullets
+
+# Fetch and clean without summarizing
+python main.py pipeline dQw4w9WgXcQ --skip-summary
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `TranscriptsDisabled` error | Video owner disabled captions | Use a different video |
+| `VideoUnavailable` error | Private, deleted, or region-locked | Check URL; try VPN if region-locked |
+| `NoTranscriptFound` | Requested language missing | Run `list` to see available languages |
+| `AuthenticationError` | API key missing or wrong | Check `ANTHROPIC_API_KEY` env variable |
+| `ModuleNotFoundError` | Dependencies not installed | Run `pip install -r requirements.txt` |
+| Chunking messages in stderr | Transcript very long | Normal — multi-pass processing is automatic |
+| Output cuts off mid-sentence | max_tokens limit hit | This is rare; open an issue if it occurs |
+
+---
+
+## Project File Reference
+
+```
+main.py          CLI entry point — all five commands
+fetcher.py       YouTube direct caption API (no scraping)
+cleaner.py       AI paragraph reformatter
+summarizer.py    AI summarizer (4 modes)
+pipeline.py      Orchestrates the full fetch -> clean -> summarize chain
+ai_client.py     Anthropic API wrapper with chunking and streaming
+config.py        Constants: model names, chunk size, summary modes
+requirements.txt Two dependencies
+README.md        Full project documentation
+GUIDE.md         This file
+LICENSE          MIT License
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rembrant Oyangoren Albeos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,244 @@
+license: mit
+sdk: static
+colorFrom: blue
+colorTo: red
+tags:
+  - youtube
+  - transcript
+  - api
+  - fetch
+  - clean
+  - summarize
+  - python
+  - tools
+
+![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square&logo=python&logoColor=white)
+![Anthropic](https://img.shields.io/badge/Powered%20by-Anthropic%20Claude-blueviolet?style=flat-square)
+![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
+![No Scraping](https://img.shields.io/badge/No%20Scraping-Direct%20API-brightgreen?style=flat-square)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square)
+![Author](https://img.shields.io/badge/Author-algorembrant-orange?style=flat-square)
+
+---
+
+# YouTube Transcript Toolkit
+
+A fast, zero-scraping command-line toolkit that fetches YouTube transcripts
+directly via the caption API, then uses the Anthropic Claude API to reformat
+them into clean paragraphs and produce multi-mode summaries.
+
+No Selenium. No BeautifulSoup. No headless browsers. Two AI-powered
+post-processing features built on top of direct caption API access.
+
+---
+
+## Architecture
+
+```
+main.py          CLI entry point — five commands (fetch, list, clean, summarize, pipeline)
+fetcher.py       Direct YouTube caption API — no HTML parsing
+cleaner.py       AI paragraph reformatter (Anthropic Claude)
+summarizer.py    AI summarizer with 4 output modes (Anthropic Claude)
+pipeline.py      Orchestrates fetch -> clean -> summarize in one pass
+ai_client.py     Shared Anthropic API wrapper with chunking and streaming
+config.py        Model names, limits, summary modes, defaults
+```
+
+---
+
+## Features
+
+- Direct caption API — transcript fetch is near-instant regardless of video length
+- Paragraph Cleaner — reformats fragmented auto-captions into readable prose (no content removed)
+- Summarizer — four modes: brief, detailed, bullet points, hierarchical outline
+- Full pipeline — fetch + clean + summarize in a single command
+- Token streaming — see AI output in real time as it generates
+- Automatic chunking — handles transcripts of any length by splitting and merging
+- Fast model by default (claude-haiku), quality model available via --quality flag
+- Batch processing — multiple video IDs/URLs in one command
+- Output formats — plain text, JSON, SRT, WebVTT for the raw transcript
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/algorembrant/youtube-transcript-toolkit.git
+cd youtube-transcript-toolkit
+python -m venv .venv
+source .venv/bin/activate       # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+export ANTHROPIC_API_KEY="sk-ant-..."   # Windows: set ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Commands
+
+### fetch — raw transcript only (no AI)
+
+```bash
+python main.py fetch "https://www.youtube.com/watch?v=VIDEO_ID"
+python main.py fetch VIDEO_ID -f srt -o transcript.srt
+python main.py fetch VIDEO_ID -f json -o transcript.json
+python main.py fetch VIDEO_ID -t                          # with timestamps
+python main.py fetch VIDEO_ID -l es en                   # Spanish, fall back to English
+```
+
+### list — available languages
+
+```bash
+python main.py list VIDEO_ID
+```
+
+### clean — reformat into paragraphs
+
+```bash
+python main.py clean VIDEO_ID
+python main.py clean VIDEO_ID -o cleaned.txt
+python main.py clean VIDEO_ID --quality                  # use higher-quality model
+python main.py clean VIDEO_ID --no-stream                # disable live token output
+```
+
+### summarize — AI-generated summary
+
+```bash
+python main.py summarize VIDEO_ID                        # brief (default)
+python main.py summarize VIDEO_ID -m detailed
+python main.py summarize VIDEO_ID -m bullets
+python main.py summarize VIDEO_ID -m outline
+python main.py summarize VIDEO_ID -m detailed --quality -o summary.txt
+```
+
+### pipeline — fetch + clean + summarize
+
+```bash
+python main.py pipeline VIDEO_ID
+python main.py pipeline VIDEO_ID -m bullets -o ./output/
+python main.py pipeline VIDEO_ID --skip-clean            # fetch + summarize only
+python main.py pipeline VIDEO_ID --skip-summary          # fetch + clean only
+python main.py pipeline ID1 ID2 ID3 -o ./batch/          # batch
+```
+
+---
+
+## Summary Modes
+
+| Mode       | Description                                      |
+|------------|--------------------------------------------------|
+| `brief`    | 3-5 sentence executive summary                   |
+| `detailed` | Multi-section prose: Overview, Key Points, etc.  |
+| `bullets`  | Key takeaways grouped under bold thematic headers|
+| `outline`  | Hierarchical Roman-numeral topic outline         |
+
+---
+
+## Model Selection
+
+| Flag        | Model Used                  | Best For                          |
+|-------------|-----------------------------|------------------------------------|
+| (default)   | claude-haiku-4-5            | Speed, short-to-medium transcripts |
+| `--quality` | claude-sonnet-4-6           | Long transcripts, deep summaries   |
+
+---
+
+## CLI Reference
+
+```
+usage: main.py {fetch,list,clean,summarize,pipeline} [options] video [video ...]
+
+commands:
+  fetch       Fetch raw transcript (no AI)
+  list        List available transcript languages
+  clean       Fetch + AI paragraph formatting
+  summarize   Fetch + AI summarization
+  pipeline    Fetch + clean + summarize in one pass
+
+shared options:
+  -l, --languages LANG [LANG ...]    Language codes, in order of preference
+  -o, --output PATH                  Output file (single) or directory (batch)
+  --quality                          Use higher-quality Claude model
+  --no-stream                        Disable live token streaming
+
+fetch / pipeline options:
+  -f, --format {text,json,srt,vtt}   Raw transcript format (default: text)
+  -t, --timestamps                   Add timestamps to plain-text output
+
+clean / summarize / pipeline options:
+  -m, --mode {brief,detailed,bullets,outline}   Summary mode (default: brief)
+
+pipeline options:
+  --skip-clean     Skip paragraph cleaning step
+  --skip-summary   Skip summarization step
+```
+
+---
+
+## Output Files (pipeline with -o)
+
+When using `pipeline -o ./output/`, three files are saved per video:
+
+```
+./output/
+  VIDEO_ID_transcript.txt    Raw transcript
+  VIDEO_ID_cleaned.txt       Paragraph-cleaned transcript
+  VIDEO_ID_summary.txt       Summary
+```
+
+---
+
+## Chunking Strategy
+
+Transcripts larger than 60,000 characters are automatically split into chunks
+at paragraph or sentence boundaries. Each chunk is processed independently,
+then the partial results are merged in a final synthesis pass. This allows
+the toolkit to handle full-length lecture recordings, long-form interviews,
+and documentary transcripts without hitting token limits.
+
+---
+
+## Supported URL Formats
+
+```
+https://www.youtube.com/watch?v=VIDEO_ID
+https://youtu.be/VIDEO_ID
+https://www.youtube.com/shorts/VIDEO_ID
+https://www.youtube.com/embed/VIDEO_ID
+VIDEO_ID  (raw 11-character ID)
+```
+
+---
+
+## Error Reference
+
+| Error                   | Cause                                            |
+|-------------------------|--------------------------------------------------|
+| `TranscriptsDisabled`   | Video owner has disabled captions                |
+| `VideoUnavailable`      | Video is private, deleted, or region-locked      |
+| `NoTranscriptFound`     | Requested language does not exist                |
+| `NoTranscriptAvailable` | No captions of any kind exist for this video     |
+| `AuthenticationError`   | ANTHROPIC_API_KEY is missing or invalid          |
+
+---
+
+## Dependencies
+
+| Package                | Version    | Purpose                              |
+|------------------------|------------|--------------------------------------|
+| anthropic              | >=0.40.0   | Claude API (clean + summarize)       |
+| youtube-transcript-api | 0.6.2      | Direct YouTube caption API access    |
+
+---
+
+## License
+
+MIT License. See `LICENSE` for details.
+
+---
+
+## Disclaimer
+
+This tool uses YouTube's publicly accessible caption endpoint and the Anthropic
+API for personal, educational, and research use. An Anthropic API key is required
+for the clean and summarize features. Review YouTube's Terms of Service before
+using this tool in a production or commercial context.

ai_client.py

@@ -0,0 +1,170 @@
+"""
+ai_client.py
+Thin wrapper around the Anthropic API with chunked processing and streaming.
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Iterator, Optional
+
+import anthropic
+
+from config import DEFAULT_MODEL, MAX_TOKENS, CHUNK_SIZE
+
+
+# ---------------------------------------------------------------------------
+# Module-level client (lazy init, reused across calls)
+# ---------------------------------------------------------------------------
+_client: Optional[anthropic.Anthropic] = None
+
+
+def _get_client() -> anthropic.Anthropic:
+    global _client
+    if _client is None:
+        _client = anthropic.Anthropic()
+    return _client
+
+
+# ---------------------------------------------------------------------------
+# Core helpers
+# ---------------------------------------------------------------------------
+
+def complete(
+    system: str,
+    user: str,
+    model: str = DEFAULT_MODEL,
+    max_tokens: int = MAX_TOKENS,
+    stream: bool = True,
+) -> str:
+    """
+    Run a single completion and return the full response text.
+    Streams tokens to stderr if `stream=True` so the user sees progress.
+    """
+    client = _get_client()
+
+    if stream:
+        result_parts: list[str] = []
+        with client.messages.stream(
+            model=model,
+            max_tokens=max_tokens,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        ) as stream_ctx:
+            for text in stream_ctx.text_stream:
+                print(text, end="", flush=True, file=sys.stderr)
+                result_parts.append(text)
+        print(file=sys.stderr)  # newline after stream
+        return "".join(result_parts)
+    else:
+        response = client.messages.create(
+            model=model,
+            max_tokens=max_tokens,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+        )
+        return response.content[0].text
+
+
+def _split_into_chunks(text: str, chunk_size: int = CHUNK_SIZE) -> list[str]:
+    """
+    Split text into chunks of at most `chunk_size` characters,
+    breaking on paragraph or sentence boundaries where possible.
+    """
+    if len(text) <= chunk_size:
+        return [text]
+
+    chunks: list[str] = []
+    start = 0
+    while start < len(text):
+        end = start + chunk_size
+        if end >= len(text):
+            chunks.append(text[start:])
+            break
+
+        # Try to break at a paragraph boundary (\n\n)
+        split_at = text.rfind("\n\n", start, end)
+        if split_at == -1:
+            # Fall back to sentence boundary
+            split_at = text.rfind(". ", start, end)
+        if split_at == -1:
+            # Fall back to whitespace
+            split_at = text.rfind(" ", start, end)
+        if split_at == -1:
+            split_at = end  # hard split
+
+        chunks.append(text[start : split_at + 1])
+        start = split_at + 1
+
+    return chunks
+
+
+def complete_long(
+    system: str,
+    user_prefix: str,
+    text: str,
+    user_suffix: str = "",
+    model: str = DEFAULT_MODEL,
+    max_tokens: int = MAX_TOKENS,
+    merge_system: Optional[str] = None,
+    stream: bool = True,
+) -> str:
+    """
+    Process a potentially long text by splitting it into chunks,
+    running a completion on each, then optionally merging the results.
+
+    Args:
+        system:       System prompt.
+        user_prefix:  Text prepended before each chunk in the user message.
+        text:         The main content to process (may be chunked).
+        user_suffix:  Text appended after each chunk in the user message.
+        model:        Anthropic model identifier.
+        max_tokens:   Max output tokens per call.
+        merge_system: If provided and there are multiple chunks, a final
+                      merge pass is run with this system prompt.
+        stream:       Whether to stream tokens to stderr.
+
+    Returns:
+        Final processed text (merged if multi-chunk).
+    """
+    chunks = _split_into_chunks(text)
+    n = len(chunks)
+
+    if n == 1:
+        user_msg = f"{user_prefix}\n\n{chunks[0]}"
+        if user_suffix:
+            user_msg += f"\n\n{user_suffix}"
+        return complete(system, user_msg, model=model, max_tokens=max_tokens, stream=stream)
+
+    # Multi-chunk processing
+    print(
+        f"[info] Text is large ({len(text):,} chars). Processing in {n} chunks.",
+        file=sys.stderr,
+    )
+    partial_results: list[str] = []
+    for i, chunk in enumerate(chunks, 1):
+        print(f"\n[chunk {i}/{n}]", file=sys.stderr)
+        user_msg = (
+            f"{user_prefix}\n\n"
+            f"[Part {i} of {n}]\n\n{chunk}"
+        )
+        if user_suffix:
+            user_msg += f"\n\n{user_suffix}"
+        result = complete(system, user_msg, model=model, max_tokens=max_tokens, stream=stream)
+        partial_results.append(result)
+
+    combined = "\n\n".join(partial_results)
+
+    # Optional merge/synthesis pass
+    if merge_system and n > 1:
+        print(f"\n[merging {n} chunks into final output]", file=sys.stderr)
+        combined = complete(
+            merge_system,
+            f"Merge and unify the following {n} sections into a single cohesive output:\n\n{combined}",
+            model=model,
+            max_tokens=max_tokens,
+            stream=stream,
+        )
+
+    return combined

cleaner.py

@@ -0,0 +1,77 @@
+"""
+cleaner.py
+Reformats raw YouTube transcript text into clean, readable paragraphs.
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+from config import DEFAULT_MODEL, MAX_TOKENS
+from ai_client import complete_long
+
+# ---------------------------------------------------------------------------
+# Prompts
+# ---------------------------------------------------------------------------
+
+_CLEAN_SYSTEM = """You are a professional transcript editor.
+Your task is to reformat raw, fragmented YouTube transcript text into clean,
+readable paragraphs that preserve the speaker's words and intent exactly.
+
+Rules:
+- Do NOT paraphrase, summarize, or omit any content.
+- Fix only punctuation, capitalization, and paragraph breaks.
+- Group related sentences into coherent paragraphs of 3-6 sentences each.
+- Remove filler words only when they impede readability (e.g. repeated "um", "uh", "like").
+- Remove duplicate lines caused by auto-captioning overlap.
+- Preserve proper nouns, technical terms, and speaker style.
+- Output clean, flowing prose — no bullet points, no headers, no markdown.
+- Do not add any commentary, preamble, or notes of your own.
+"""
+
+_CLEAN_USER_PREFIX = (
+    "Reformat the following raw YouTube transcript into clean, readable paragraphs. "
+    "Preserve all content. Fix punctuation and capitalization only.\n\n"
+    "RAW TRANSCRIPT:"
+)
+
+_CLEAN_MERGE_SYSTEM = """You are a professional transcript editor.
+You will receive several already-cleaned transcript sections.
+Merge them into a single, seamless, well-paragraphed document.
+Do not summarize or omit any content. Output clean flowing prose only.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def clean(
+    raw_text: str,
+    model: str = DEFAULT_MODEL,
+    max_tokens: int = MAX_TOKENS,
+    stream: bool = True,
+) -> str:
+    """
+    Reformat a raw transcript into clean paragraphs.
+
+    Args:
+        raw_text:   Plain-text transcript (output of fetcher.TranscriptResult.plain_text).
+        model:      Anthropic model to use.
+        max_tokens: Max output tokens per API call.
+        stream:     Whether to stream progress tokens to stderr.
+
+    Returns:
+        Cleaned, paragraph-formatted transcript as a string.
+    """
+    if not raw_text or not raw_text.strip():
+        raise ValueError("Cannot clean an empty transcript.")
+
+    return complete_long(
+        system=_CLEAN_SYSTEM,
+        user_prefix=_CLEAN_USER_PREFIX,
+        text=raw_text.strip(),
+        model=model,
+        max_tokens=max_tokens,
+        merge_system=_CLEAN_MERGE_SYSTEM,
+        stream=stream,
+    )

config.py

@@ -0,0 +1,48 @@
+"""
+config.py
+Central configuration for the YouTube Transcript Toolkit.
+Author: algorembrant
+"""
+
+# ---------------------------------------------------------------------------
+# Model settings
+# ---------------------------------------------------------------------------
+# claude-haiku-4-5 is used by default for speed.
+# Switch to claude-sonnet-4-6 for higher quality at the cost of latency.
+DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+QUALITY_MODEL = "claude-sonnet-4-6"
+
+MAX_TOKENS = 8192          # Maximum tokens to request from the model
+CHUNK_SIZE = 60_000        # Characters per chunk for very long transcripts
+
+# ---------------------------------------------------------------------------
+# Transcript defaults
+# ---------------------------------------------------------------------------
+DEFAULT_LANGUAGES = ["en"]
+
+# ---------------------------------------------------------------------------
+# Summary modes
+# ---------------------------------------------------------------------------
+SUMMARY_MODES = {
+    "brief": {
+        "label": "Brief",
+        "description": "3-5 sentence executive summary",
+    },
+    "detailed": {
+        "label": "Detailed",
+        "description": "Comprehensive multi-section breakdown",
+    },
+    "bullets": {
+        "label": "Bullet Points",
+        "description": "Key takeaways as a structured bullet list",
+    },
+    "outline": {
+        "label": "Outline",
+        "description": "Hierarchical topic outline",
+    },
+}
+
+# ---------------------------------------------------------------------------
+# Output formats
+# ---------------------------------------------------------------------------
+OUTPUT_FORMATS = ["text", "json", "srt", "vtt"]

fetcher.py

@@ -0,0 +1,200 @@
+"""
+fetcher.py
+Fetches YouTube transcripts directly via the caption API — no HTML parsing.
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from typing import Optional
+
+from youtube_transcript_api import YouTubeTranscriptApi
+from youtube_transcript_api.formatters import (
+    JSONFormatter,
+    SRTFormatter,
+    TextFormatter,
+    WebVTTFormatter,
+)
+from youtube_transcript_api._errors import (
+    NoTranscriptAvailable,
+    NoTranscriptFound,
+    TranscriptsDisabled,
+    VideoUnavailable,
+)
+
+from config import DEFAULT_LANGUAGES
+
+
+# ---------------------------------------------------------------------------
+# URL / ID helpers
+# ---------------------------------------------------------------------------
+
+_ID_PATTERNS = [
+    r"(?:youtube\.com/watch\?.*v=)([a-zA-Z0-9_-]{11})",
+    r"(?:youtu\.be/)([a-zA-Z0-9_-]{11})",
+    r"(?:youtube\.com/shorts/)([a-zA-Z0-9_-]{11})",
+    r"(?:youtube\.com/embed/)([a-zA-Z0-9_-]{11})",
+]
+
+
+def extract_video_id(url_or_id: str) -> str:
+    """Return the 11-character YouTube video ID from a URL or raw ID."""
+    for pattern in _ID_PATTERNS:
+        match = re.search(pattern, url_or_id)
+        if match:
+            return match.group(1)
+
+    if re.fullmatch(r"[a-zA-Z0-9_-]{11}", url_or_id):
+        return url_or_id
+
+    raise ValueError(
+        f"Cannot extract a valid YouTube video ID from: {url_or_id!r}\n"
+        "Accepted: full YouTube URL, youtu.be link, Shorts URL, embed URL, or raw 11-char ID."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Language listing
+# ---------------------------------------------------------------------------
+
+def list_available_transcripts(video_id: str) -> None:
+    """Print all available transcript languages for a video."""
+    tlist = YouTubeTranscriptApi.list_transcripts(video_id)
+
+    manual = list(tlist._manually_created_transcripts.values())
+    auto   = list(tlist._generated_transcripts.values())
+
+    print(f"\nAvailable transcripts  --  video: {video_id}\n")
+    if manual:
+        print("Manually created:")
+        for t in manual:
+            print(f"  [{t.language_code:8s}] {t.language}")
+    if auto:
+        print("Auto-generated:")
+        for t in auto:
+            print(f"  [{t.language_code:8s}] {t.language}")
+    if not manual and not auto:
+        print("  (none found)")
+
+
+# ---------------------------------------------------------------------------
+# Core fetch
+# ---------------------------------------------------------------------------
+
+class TranscriptResult:
+    """Container for a fetched transcript."""
+
+    def __init__(
+        self,
+        video_id: str,
+        raw_data: list[dict],
+        language_code: str,
+        language: str,
+        is_generated: bool,
+    ) -> None:
+        self.video_id      = video_id
+        self.raw_data      = raw_data          # list of {text, start, duration}
+        self.language_code = language_code
+        self.language      = language
+        self.is_generated  = is_generated
+
+    # ------------------------------------------------------------------
+    # Convenience properties
+    # ------------------------------------------------------------------
+
+    @property
+    def plain_text(self) -> str:
+        """Plain transcript text without timestamps."""
+        return TextFormatter().format_transcript(self.raw_data)
+
+    def timestamped_text(self) -> str:
+        """Plain text with [MM:SS.ss] prefixes."""
+        lines = []
+        for entry in self.raw_data:
+            m = int(entry["start"] // 60)
+            s = entry["start"] % 60
+            lines.append(f"[{m:02d}:{s:05.2f}] {entry['text']}")
+        return "\n".join(lines)
+
+    def as_json(self) -> str:
+        return JSONFormatter().format_transcript(self.raw_data, indent=2)
+
+    def as_srt(self) -> str:
+        return SRTFormatter().format_transcript(self.raw_data)
+
+    def as_vtt(self) -> str:
+        return WebVTTFormatter().format_transcript(self.raw_data)
+
+    def formatted(self, fmt: str, timestamps: bool = False) -> str:
+        """Return transcript in the requested format string."""
+        if fmt == "json":
+            return self.as_json()
+        if fmt == "srt":
+            return self.as_srt()
+        if fmt == "vtt":
+            return self.as_vtt()
+        # default: text
+        return self.timestamped_text() if timestamps else self.plain_text
+
+    def __len__(self) -> int:
+        return len(self.plain_text)
+
+
+def fetch(
+    video_id: str,
+    languages: Optional[list[str]] = None,
+) -> TranscriptResult:
+    """
+    Fetch a YouTube transcript directly via the caption API.
+
+    Args:
+        video_id:  11-character YouTube video ID.
+        languages: Ordered list of preferred language codes.
+
+    Returns:
+        TranscriptResult instance.
+
+    Raises:
+        SystemExit on unrecoverable errors (TranscriptsDisabled, VideoUnavailable, etc.)
+    """
+    if languages is None:
+        languages = DEFAULT_LANGUAGES
+
+    try:
+        tlist = YouTubeTranscriptApi.list_transcripts(video_id)
+
+        try:
+            transcript_obj = tlist.find_transcript(languages)
+        except NoTranscriptFound:
+            all_t = (
+                list(tlist._manually_created_transcripts.values())
+                + list(tlist._generated_transcripts.values())
+            )
+            if not all_t:
+                raise NoTranscriptAvailable(video_id)
+            transcript_obj = all_t[0]
+            print(
+                f"[warn] Requested language(s) not found. "
+                f"Using [{transcript_obj.language_code}] {transcript_obj.language}.",
+                file=sys.stderr,
+            )
+
+        raw = transcript_obj.fetch()
+        return TranscriptResult(
+            video_id=video_id,
+            raw_data=raw,
+            language_code=transcript_obj.language_code,
+            language=transcript_obj.language,
+            is_generated=transcript_obj.is_generated,
+        )
+
+    except TranscriptsDisabled:
+        sys.exit(f"[error] Transcripts are disabled for video '{video_id}'.")
+    except VideoUnavailable:
+        sys.exit(f"[error] Video '{video_id}' is unavailable (private, deleted, or region-locked).")
+    except NoTranscriptAvailable:
+        sys.exit(f"[error] No transcript found for video '{video_id}'.")
+    except Exception as exc:
+        sys.exit(f"[error] Unexpected error while fetching transcript: {exc}")

main.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""
+main.py
+YouTube Transcript Toolkit — CLI entry point.
+
+Commands:
+  fetch       Fetch and print/save raw transcript
+  clean       Fetch transcript and reformat into paragraphs
+  summarize   Fetch transcript and summarize
+  pipeline    Fetch, clean, and summarize in one pass
+  list        List available transcript languages for a video
+
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from config import DEFAULT_MODEL, QUALITY_MODEL, SUMMARY_MODES, OUTPUT_FORMATS
+from fetcher import extract_video_id, list_available_transcripts, fetch
+from cleaner import clean
+from summarizer import summarize
+from pipeline import run, run_batch
+
+
+# ---------------------------------------------------------------------------
+# Shared argument groups
+# ---------------------------------------------------------------------------
+
+def _add_video_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "video",
+        nargs="+",
+        help="YouTube video URL(s) or ID(s).",
+    )
+
+def _add_lang_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "-l", "--languages",
+        nargs="+",
+        default=["en"],
+        metavar="LANG",
+        help="Language codes in order of preference (default: en). Example: --languages en es",
+    )
+
+def _add_output_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "-o", "--output",
+        metavar="PATH",
+        help="Output file (single video) or directory (multiple videos).",
+    )
+
+def _add_ai_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--quality",
+        action="store_true",
+        help=f"Use the higher-quality model ({QUALITY_MODEL}) instead of the default fast model.",
+    )
+    p.add_argument(
+        "--no-stream",
+        action="store_true",
+        help="Disable token streaming (collect full response before printing).",
+    )
+
+def _add_format_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "-f", "--format",
+        choices=OUTPUT_FORMATS,
+        default="text",
+        help="Raw transcript output format (default: text).",
+    )
+    p.add_argument(
+        "-t", "--timestamps",
+        action="store_true",
+        help="Include timestamps in plain-text transcript output.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="yttool",
+        description=(
+            "YouTube Transcript Toolkit\n"
+            "Fetch, clean, and summarize YouTube transcripts. No HTML parsing.\n"
+            "Author: algorembrant"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # ---- fetch ----
+    p_fetch = subparsers.add_parser(
+        "fetch",
+        help="Fetch the raw transcript of a YouTube video.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_video_args(p_fetch)
+    _add_lang_args(p_fetch)
+    _add_format_args(p_fetch)
+    _add_output_args(p_fetch)
+
+    # ---- list ----
+    p_list = subparsers.add_parser(
+        "list",
+        help="List all available transcript languages for a video.",
+    )
+    _add_video_args(p_list)
+
+    # ---- clean ----
+    p_clean = subparsers.add_parser(
+        "clean",
+        help="Fetch a transcript and reformat it into clean paragraphs.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_video_args(p_clean)
+    _add_lang_args(p_clean)
+    _add_ai_args(p_clean)
+    _add_output_args(p_clean)
+
+    # ---- summarize ----
+    p_sum = subparsers.add_parser(
+        "summarize",
+        help="Fetch a transcript and summarize it.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_video_args(p_sum)
+    _add_lang_args(p_sum)
+    p_sum.add_argument(
+        "-m", "--mode",
+        choices=list(SUMMARY_MODES.keys()),
+        default="brief",
+        help=(
+            "Summary mode (default: brief):\n"
+            + "\n".join(
+                f"  {k:10s} {v['description']}"
+                for k, v in SUMMARY_MODES.items()
+            )
+        ),
+    )
+    _add_ai_args(p_sum)
+    _add_output_args(p_sum)
+
+    # ---- pipeline ----
+    p_pipe = subparsers.add_parser(
+        "pipeline",
+        help="Fetch, clean, and summarize in one pass.",
+        formatter_class=argparse.RawTextHelpFormatter,
+    )
+    _add_video_args(p_pipe)
+    _add_lang_args(p_pipe)
+    _add_format_args(p_pipe)
+    p_pipe.add_argument(
+        "-m", "--mode",
+        choices=list(SUMMARY_MODES.keys()),
+        default="brief",
+        help="Summary mode (default: brief).",
+    )
+    p_pipe.add_argument(
+        "--skip-clean",
+        action="store_true",
+        help="Skip the cleaning step; summarize raw transcript directly.",
+    )
+    p_pipe.add_argument(
+        "--skip-summary",
+        action="store_true",
+        help="Skip the summarization step; only fetch and clean.",
+    )
+    _add_ai_args(p_pipe)
+    _add_output_args(p_pipe)
+
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+def cmd_list(args: argparse.Namespace) -> None:
+    for v in args.video:
+        vid = extract_video_id(v)
+        list_available_transcripts(vid)
+
+
+def cmd_fetch(args: argparse.Namespace) -> None:
+    import os
+
+    video_ids = [extract_video_id(v) for v in args.video]
+    single    = len(video_ids) == 1
+
+    for vid in video_ids:
+        result = fetch(vid, languages=args.languages)
+        text   = result.formatted(args.format, timestamps=args.timestamps)
+
+        if args.output:
+            if single:
+                out_path = args.output
+            else:
+                ext_map = {"text": "txt", "json": "json", "srt": "srt", "vtt": "vtt"}
+                os.makedirs(args.output, exist_ok=True)
+                out_path = os.path.join(args.output, f"{vid}.{ext_map.get(args.format, 'txt')}")
+
+            with open(out_path, "w", encoding="utf-8") as f:
+                f.write(text)
+            print(f"[saved] {out_path}", file=sys.stderr)
+        else:
+            if not single:
+                print(f"\n{'='*60}\nVideo: {vid}\n{'='*60}")
+            print(text)
+
+
+def cmd_clean(args: argparse.Namespace) -> None:
+    import os
+
+    video_ids = [extract_video_id(v) for v in args.video]
+    single    = len(video_ids) == 1
+    model     = QUALITY_MODEL if args.quality else DEFAULT_MODEL
+    stream    = not args.no_stream
+
+    for vid in video_ids:
+        result   = fetch(vid, languages=args.languages)
+        cleaned  = clean(result.plain_text, model=model, stream=stream)
+
+        if args.output:
+            if single:
+                out_path = args.output
+            else:
+                os.makedirs(args.output, exist_ok=True)
+                out_path = os.path.join(args.output, f"{vid}_cleaned.txt")
+            with open(out_path, "w", encoding="utf-8") as f:
+                f.write(cleaned)
+            print(f"\n[saved] {out_path}", file=sys.stderr)
+        else:
+            if not single:
+                print(f"\n{'='*60}\nVideo: {vid}\n{'='*60}")
+            print(cleaned)
+
+
+def cmd_summarize(args: argparse.Namespace) -> None:
+    import os
+
+    video_ids = [extract_video_id(v) for v in args.video]
+    single    = len(video_ids) == 1
+    model     = QUALITY_MODEL if args.quality else DEFAULT_MODEL
+    stream    = not args.no_stream
+
+    for vid in video_ids:
+        result  = fetch(vid, languages=args.languages)
+        summary = summarize(result.plain_text, mode=args.mode, model=model, stream=stream)
+
+        if args.output:
+            if single:
+                out_path = args.output
+            else:
+                os.makedirs(args.output, exist_ok=True)
+                out_path = os.path.join(args.output, f"{vid}_summary.txt")
+            with open(out_path, "w", encoding="utf-8") as f:
+                f.write(summary)
+            print(f"\n[saved] {out_path}", file=sys.stderr)
+        else:
+            if not single:
+                print(f"\n{'='*60}\nVideo: {vid}\n{'='*60}")
+            print(summary)
+
+
+def cmd_pipeline(args: argparse.Namespace) -> None:
+    video_ids = [extract_video_id(v) for v in args.video]
+    model     = QUALITY_MODEL if args.quality else DEFAULT_MODEL
+    stream    = not args.no_stream
+
+    kwargs = dict(
+        languages         = args.languages,
+        do_clean          = not args.skip_clean,
+        do_summarize      = not args.skip_summary,
+        summary_mode      = args.mode,
+        model             = model,
+        quality           = args.quality,
+        stream            = stream,
+        output_dir        = args.output,
+        transcript_format = args.format,
+        timestamps        = args.timestamps,
+    )
+
+    if len(video_ids) == 1:
+        r = run(video_ids[0], **kwargs)
+        if not args.output:
+            _print_pipeline_result(r)
+    else:
+        results = run_batch(video_ids, **kwargs)
+        if not args.output:
+            for r in results:
+                print(f"\n{'='*60}\nVideo: {r.video_id}\n{'='*60}")
+                _print_pipeline_result(r)
+
+    # Report errors
+    all_errors = []
+    if isinstance(r if len(video_ids) == 1 else None, object):
+        pass  # handled per-result below
+
+
+def _print_pipeline_result(r) -> None:
+    sections = []
+    if r.raw:
+        sections.append(("RAW TRANSCRIPT", r.raw))
+    if r.cleaned:
+        sections.append(("CLEANED TRANSCRIPT", r.cleaned))
+    if r.summary:
+        sections.append(("SUMMARY", r.summary))
+
+    for title, content in sections:
+        print(f"\n{'='*60}")
+        print(f"  {title}")
+        print(f"{'='*60}\n")
+        print(content)
+
+    if r.errors:
+        print(f"\n[errors]", file=sys.stderr)
+        for err in r.errors:
+            print(f"  {err}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = build_parser()
+    args   = parser.parse_args()
+
+    dispatch = {
+        "list":      cmd_list,
+        "fetch":     cmd_fetch,
+        "clean":     cmd_clean,
+        "summarize": cmd_summarize,
+        "pipeline":  cmd_pipeline,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler:
+        handler(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pipeline.py

@@ -0,0 +1,173 @@
+"""
+pipeline.py
+Orchestrates fetch -> clean -> summarize in a single pipeline call.
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import Optional
+
+from fetcher import TranscriptResult, fetch, extract_video_id
+from cleaner import clean
+from summarizer import summarize
+from config import DEFAULT_MODEL, QUALITY_MODEL
+
+
+# ---------------------------------------------------------------------------
+# Result container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PipelineResult:
+    video_id:   str
+    raw:        str          = ""
+    cleaned:    str          = ""
+    summary:    str          = ""
+    errors:     list[str]    = field(default_factory=list)
+
+    @property
+    def success(self) -> bool:
+        return not self.errors
+
+
+# ---------------------------------------------------------------------------
+# Single-video pipeline
+# ---------------------------------------------------------------------------
+
+def run(
+    url_or_id: str,
+    languages: list[str] | None     = None,
+    do_clean: bool                  = False,
+    do_summarize: bool              = False,
+    summary_mode: str               = "brief",
+    model: str                      = DEFAULT_MODEL,
+    quality: bool                   = False,
+    stream: bool                    = True,
+    output_dir: str | None          = None,
+    transcript_format: str          = "text",
+    timestamps: bool                = False,
+) -> PipelineResult:
+    """
+    Full pipeline for one video.
+
+    Args:
+        url_or_id:         YouTube URL or video ID.
+        languages:         Language preference list.
+        do_clean:          Run paragraph cleaner.
+        do_summarize:      Run summarizer.
+        summary_mode:      One of 'brief', 'detailed', 'bullets', 'outline'.
+        model:             Anthropic model identifier.
+        quality:           Use the higher-quality model instead of the default fast one.
+        stream:            Stream AI tokens to stderr.
+        output_dir:        Directory to write output files (optional).
+        transcript_format: Raw transcript format: 'text', 'json', 'srt', 'vtt'.
+        timestamps:        Include timestamps in plain-text transcript.
+
+    Returns:
+        PipelineResult with all produced artifacts.
+    """
+    chosen_model = QUALITY_MODEL if quality else model
+    result       = PipelineResult(video_id="")
+
+    # 1. Extract ID
+    try:
+        video_id      = extract_video_id(url_or_id)
+        result.video_id = video_id
+    except ValueError as exc:
+        result.errors.append(str(exc))
+        return result
+
+    # 2. Fetch
+    print(f"\n[fetch] {video_id}", file=sys.stderr)
+    transcript: TranscriptResult = fetch(video_id, languages=languages)
+    result.raw = transcript.formatted(transcript_format, timestamps=timestamps)
+    plain_text  = transcript.plain_text   # always used as AI input
+
+    # 3. Clean
+    if do_clean:
+        print(f"\n[clean] Running paragraph cleaner...", file=sys.stderr)
+        try:
+            result.cleaned = clean(plain_text, model=chosen_model, stream=stream)
+        except Exception as exc:
+            result.errors.append(f"Cleaner error: {exc}")
+
+    # 4. Summarize
+    if do_summarize:
+        print(f"\n[summarize] Mode: {summary_mode}", file=sys.stderr)
+        # Prefer cleaned text if available
+        source_text = result.cleaned if result.cleaned else plain_text
+        try:
+            result.summary = summarize(
+                source_text, mode=summary_mode, model=chosen_model, stream=stream
+            )
+        except Exception as exc:
+            result.errors.append(f"Summarizer error: {exc}")
+
+    # 5. Save to disk
+    if output_dir:
+        _save(result, output_dir, transcript_format)
+
+    return result
+
+
+def _save(result: PipelineResult, output_dir: str, fmt: str) -> None:
+    """Write all non-empty artifacts to output_dir."""
+    os.makedirs(output_dir, exist_ok=True)
+    vid = result.video_id
+
+    ext_map = {"text": "txt", "json": "json", "srt": "srt", "vtt": "vtt"}
+    ext = ext_map.get(fmt, "txt")
+
+    files_written = []
+
+    if result.raw:
+        p = os.path.join(output_dir, f"{vid}_transcript.{ext}")
+        _write(p, result.raw)
+        files_written.append(p)
+
+    if result.cleaned:
+        p = os.path.join(output_dir, f"{vid}_cleaned.txt")
+        _write(p, result.cleaned)
+        files_written.append(p)
+
+    if result.summary:
+        p = os.path.join(output_dir, f"{vid}_summary.txt")
+        _write(p, result.summary)
+        files_written.append(p)
+
+    for path in files_written:
+        print(f"[saved] {path}", file=sys.stderr)
+
+
+def _write(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+
+# ---------------------------------------------------------------------------
+# Batch pipeline
+# ---------------------------------------------------------------------------
+
+def run_batch(
+    urls_or_ids: list[str],
+    **kwargs,
+) -> list[PipelineResult]:
+    """
+    Run the pipeline for multiple videos sequentially.
+    All keyword arguments are forwarded to `run()`.
+
+    Returns a list of PipelineResult, one per video.
+    """
+    results = []
+    total   = len(urls_or_ids)
+    for i, url_or_id in enumerate(urls_or_ids, 1):
+        print(f"\n{'='*60}", file=sys.stderr)
+        print(f"[{i}/{total}] Processing: {url_or_id}", file=sys.stderr)
+        print(f"{'='*60}", file=sys.stderr)
+        r = run(url_or_id, **kwargs)
+        results.append(r)
+    return results

requirements.txt

@@ -0,0 +1,2 @@
+anthropic>
+youtube-transcript-api

summarizer.py

@@ -0,0 +1,125 @@
+"""
+summarizer.py
+Summarizes YouTube transcript text in multiple modes via the Anthropic API.
+Author: algorembrant
+"""
+
+from __future__ import annotations
+
+from config import DEFAULT_MODEL, MAX_TOKENS, QUALITY_MODEL
+from ai_client import complete_long
+
+# ---------------------------------------------------------------------------
+# Per-mode prompts
+# ---------------------------------------------------------------------------
+
+_SYSTEM_BASE = """You are an expert content analyst specializing in video transcripts.
+Your summaries are accurate, concise, and written in clear professional prose.
+Never hallucinate or add information not present in the transcript.
+Do not add a preamble or closing statement — output only the requested summary.
+"""
+
+_MODE_PROMPTS: dict[str, dict[str, str]] = {
+
+    "brief": {
+        "system": _SYSTEM_BASE + (
+            "Write a brief 3-5 sentence executive summary that captures the core message, "
+            "key argument, and main conclusion of the transcript."
+        ),
+        "user_prefix": (
+            "Write a brief 3-5 sentence executive summary of the following transcript.\n\n"
+            "TRANSCRIPT:"
+        ),
+    },
+
+    "detailed": {
+        "system": _SYSTEM_BASE + (
+            "Write a detailed, multi-section summary with clearly labeled sections. "
+            "Sections should include: Overview, Key Points, Supporting Details, and Conclusion. "
+            "Each section should be written as flowing prose paragraphs — no bullet points."
+        ),
+        "user_prefix": (
+            "Write a detailed multi-section summary (Overview, Key Points, Supporting Details, Conclusion) "
+            "of the following transcript. Use flowing prose — no bullet points.\n\n"
+            "TRANSCRIPT:"
+        ),
+    },
+
+    "bullets": {
+        "system": _SYSTEM_BASE + (
+            "Extract the most important takeaways as a structured bullet list. "
+            "Group bullets under 3-5 thematic headings. Each bullet should be one clear sentence. "
+            "Use markdown bold for headings."
+        ),
+        "user_prefix": (
+            "Extract the key takeaways from the following transcript as a structured bullet list "
+            "grouped under bold thematic headings.\n\n"
+            "TRANSCRIPT:"
+        ),
+    },
+
+    "outline": {
+        "system": _SYSTEM_BASE + (
+            "Create a hierarchical topic outline of the transcript. "
+            "Use Roman numerals for top-level topics, capital letters for sub-topics, "
+            "and Arabic numerals for specific points. Keep entries concise (one line each)."
+        ),
+        "user_prefix": (
+            "Create a hierarchical outline (Roman numerals, sub-letters, sub-numbers) "
+            "of the following transcript.\n\n"
+            "TRANSCRIPT:"
+        ),
+    },
+}
+
+_MERGE_SYSTEM = """You are an expert content analyst.
+You will receive several summary sections from different parts of a long transcript.
+Merge them into a single cohesive, unified summary in the same format.
+Remove duplicate points. Maintain a logical flow. Output only the final merged summary.
+"""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def summarize(
+    text: str,
+    mode: str = "brief",
+    model: str = DEFAULT_MODEL,
+    max_tokens: int = MAX_TOKENS,
+    stream: bool = True,
+) -> str:
+    """
+    Summarize a transcript in the specified mode.
+
+    Args:
+        text:       Transcript text (raw or already cleaned).
+        mode:       One of 'brief', 'detailed', 'bullets', 'outline'.
+        model:      Anthropic model to use.
+        max_tokens: Max output tokens per API call.
+        stream:     Stream progress tokens to stderr.
+
+    Returns:
+        Formatted summary string.
+    """
+    if not text or not text.strip():
+        raise ValueError("Cannot summarize an empty transcript.")
+
+    if mode not in _MODE_PROMPTS:
+        valid = ", ".join(_MODE_PROMPTS.keys())
+        raise ValueError(f"Unknown summary mode: {mode!r}. Valid modes: {valid}")
+
+    prompts = _MODE_PROMPTS[mode]
+
+    # Detailed and outline summaries benefit from higher-quality model
+    # but we keep the user's choice; they can override via --quality flag
+    return complete_long(
+        system=prompts["system"],
+        user_prefix=prompts["user_prefix"],
+        text=text.strip(),
+        model=model,
+        max_tokens=max_tokens,
+        merge_system=_MERGE_SYSTEM,
+        stream=stream,
+    )