yt-instruct 1.0.0__py3-none-any.whl

yt_instruct/__init__.py

@@ -0,0 +1,3 @@
+"""yt-instruct: Convert YouTube videos into structured markdown instruction documents."""
+
+__version__ = "0.1.0"

yt_instruct/cli.py

@@ -0,0 +1,415 @@
+"""yt-instruct CLI — Download, transcribe, and generate instruction docs from YouTube videos."""
+
+import sys
+import tempfile
+from datetime import date
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .downloader import VideoInfo, download_audio, fetch_info, resolve_urls
+from .generator import generate
+from .transcriber import transcribe
+from .utils import output_path, slugify
+
+
+def _frontmatter(title: str, url: str, description: str, draft: bool) -> str:
+    safe_title = title.replace('"', '\\"')
+    safe_desc = description.replace('"', '\\"')
+    draft_str = "true" if draft else "false"
+    return (
+        "---\n"
+        f'title: "{safe_title}"\n'
+        f"url: {url}\n"
+        f'description: "{safe_desc}"\n'
+        f"date: {date.today().isoformat()}\n"
+        f"draft: {draft_str}\n"
+        "---\n\n"
+    )
+
+
+def _transcript_cache_path(output_dir: Path, title: str) -> Path:
+    """Predictable path for a cached transcript file (used by --keep and --resume)."""
+    return output_dir / f"{slugify(title)}_transcript.txt"
+
+
+def _resolve_input_file(path: Path, output_dir: Path) -> Path:
+    """Resolve an input file path, falling back to output_dir if the file isn't found as-is."""
+    if path.exists():
+        return path
+    candidate = output_dir / path
+    if candidate.exists():
+        return candidate
+    raise click.BadParameter(f"File not found: {path} (also tried {candidate})")
+
+
+@click.command()
+@click.version_option(__version__, prog_name="yt-instruct")
+@click.argument("urls", nargs=-1, metavar="URL...")
+@click.option(
+    "--url-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Text file with one YouTube URL per line.",
+)
+@click.option(
+    "--output-dir",
+    "-o",
+    type=click.Path(file_okay=False, path_type=Path),
+    default=Path("."),
+    show_default=True,
+    help="Directory to write output markdown files.",
+)
+@click.option(
+    "--keep",
+    is_flag=True,
+    default=False,
+    help="Keep intermediate audio and transcript files.",
+)
+@click.option(
+    "--merge",
+    is_flag=True,
+    default=False,
+    help="Merge all videos into a single output document.",
+)
+@click.option(
+    "--content-type",
+    type=click.Choice(["tutorial", "lecture", "ib", "auto"], case_sensitive=False),
+    default="auto",
+    show_default=True,
+    help="Prompt style to use for generation.",
+)
+@click.option(
+    "--backend",
+    type=click.Choice(["anthropic", "llm", "nvidia"], case_sensitive=False),
+    default="anthropic",
+    show_default=True,
+    help="LLM backend to use.",
+)
+@click.option(
+    "--model",
+    default="claude-sonnet-4-6",
+    show_default=True,
+    help="Model name (e.g. 'claude-sonnet-4-6' for anthropic/llm, 'moonshotai/kimi-k2-instruct' for nvidia).",
+)
+@click.option(
+    "--prompt-file",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Custom system prompt file (overrides built-in prompts).",
+)
+@click.option(
+    "--mistral-model",
+    default="voxtral-mini-latest",
+    show_default=True,
+    help="Mistral transcription model.",
+)
+@click.option(
+    "--audio-format",
+    type=click.Choice(["mp3", "m4a"], case_sensitive=False),
+    default="mp3",
+    show_default=True,
+    help="Audio format for intermediate file.",
+)
+@click.option(
+    "--language",
+    default=None,
+    metavar="LANG",
+    help="Output language for the generated document (e.g. 'French', 'Spanish'). Defaults to English.",
+)
+@click.option(
+    "--transcript-file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Use an existing transcript .txt file; skips download and transcription.",
+)
+@click.option(
+    "--audio-file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Use an existing audio file (e.g. MP3); skips download, transcribes directly.",
+)
+@click.option(
+    "--title",
+    default=None,
+    help="Video title to use with --transcript-file or --audio-file (defaults to filename stem).",
+)
+@click.option(
+    "--draft",
+    is_flag=True,
+    default=False,
+    help="Set draft: true in the output frontmatter.",
+)
+@click.option(
+    "--resume",
+    is_flag=True,
+    default=False,
+    help=(
+        "Skip videos that already have a generated output file. "
+        "If a cached transcript (from --keep) exists, skips download and transcription too."
+    ),
+)
+def cli(
+    urls,
+    url_file,
+    output_dir,
+    keep,
+    merge,
+    content_type,
+    backend,
+    model,
+    prompt_file,
+    mistral_model,
+    audio_format,
+    language,
+    transcript_file,
+    audio_file,
+    title,
+    draft,
+    resume,
+):
+    """Convert YouTube videos into structured markdown instruction documents.
+
+    Pipeline: URL → audio download (yt-dlp) → transcription (Mistral voxtral) →
+    LLM document generation (Anthropic / llm / NVIDIA). Each output file is
+    prefixed with YAML frontmatter (title, url, description, date, draft).
+
+    \b
+    REQUIRED ENVIRONMENT VARIABLES
+      MISTRAL_API_KEY      Always required (transcription).
+      ANTHROPIC_API_KEY    Required for --backend anthropic (default).
+      NVIDIA_API_KEY       Required for --backend nvidia.
+
+    \b
+    CONTENT TYPES
+      auto      LLM classifies the video and picks the best template (default).
+      tutorial  Hands-on how-to guides with steps and code.
+      lecture   Tech talks and academic presentations.
+      ib        IB student revision notes.
+
+    \b
+    BACKENDS
+      anthropic  Anthropic Python SDK (default model: claude-sonnet-4-6).
+      llm        Simon Willison's llm CLI library.
+      nvidia     NVIDIA NIM API via OpenAI-compatible endpoint.
+
+    \b
+    FILE RESOLUTION FOR --audio-file AND --transcript-file
+      If the given path does not exist, it is looked up inside --output-dir.
+      Example: --audio-file recording.mp3 --output-dir ./docs
+               resolves to ./docs/recording.mp3 if not found locally.
+
+    \b
+    EXAMPLES
+      yt-instruct https://youtu.be/dQw4w9WgXcQ
+      yt-instruct url1 url2 --output-dir ./docs
+      yt-instruct <URL> --content-type tutorial --backend llm
+      yt-instruct --url-file urls.txt --merge --output-dir ./docs
+      yt-instruct --transcript-file transcript.txt --title "My Video"
+      yt-instruct --audio-file recording.mp3 --output-dir ./docs
+      yt-instruct <URL> --backend nvidia --model moonshotai/kimi-k2-instruct
+      yt-instruct <URL> --language French
+      yt-instruct <URL> --draft
+      yt-instruct --url-file urls.txt --keep --output-dir ./docs
+      yt-instruct --url-file urls.txt --resume --output-dir ./docs
+    """
+    # Fast path: transcript file provided — skip download and transcription
+    if transcript_file:
+        if urls or url_file or audio_file:
+            raise click.UsageError("--transcript-file cannot be combined with URLs, --url-file, or --audio-file.")
+        output_dir.mkdir(parents=True, exist_ok=True)
+        transcript_file = _resolve_input_file(transcript_file, output_dir)
+        transcript = transcript_file.read_text(encoding="utf-8").strip()
+        resolved_title = title or transcript_file.stem
+        video = VideoInfo(title=resolved_title, channel="", url="", duration=None, audio_path=None)
+        lang_note = f", language={language}" if language else ""
+        click.echo(f"\n[yt-instruct] Generating from transcript: {transcript_file.name} ({content_type}, backend={backend}{lang_note})")
+        try:
+            markdown = generate(
+                video=video,
+                transcript=transcript,
+                content_type=content_type,
+                backend=backend,
+                model=model,
+                prompt_file=prompt_file,
+                language=language,
+            )
+        except Exception as e:
+            click.echo(f"  ERROR: {e}", err=True)
+            sys.exit(1)
+        out = output_path(output_dir, resolved_title)
+        out.write_text(_frontmatter(resolved_title, video.url, video.description, draft) + markdown, encoding="utf-8")
+        click.echo(f"  Written: {out}")
+        return
+
+    # Fast path: audio file provided — skip download, transcribe directly
+    if audio_file:
+        if urls or url_file:
+            raise click.UsageError("--audio-file cannot be combined with URLs or --url-file.")
+        output_dir.mkdir(parents=True, exist_ok=True)
+        audio_file = _resolve_input_file(audio_file, output_dir)
+        resolved_title = title or audio_file.stem
+        video = VideoInfo(title=resolved_title, channel="", url="", duration=None, audio_path=audio_file)
+        lang_note = f", language={language}" if language else ""
+        click.echo(f"\n[yt-instruct] Transcribing audio file: {audio_file} ({content_type}, backend={backend}{lang_note})")
+        click.echo("  Transcribing...")
+        try:
+            transcript = transcribe(video.audio_path, mistral_model)
+        except Exception as e:
+            click.echo(f"  ERROR transcribing: {e}", err=True)
+            sys.exit(1)
+        click.echo(f"  Transcript: {len(transcript)} chars")
+        if keep:
+            _transcript_cache_path(output_dir, resolved_title).write_text(transcript, encoding="utf-8")
+        click.echo(f"  Generating ({content_type}, backend={backend}{lang_note})...")
+        try:
+            markdown = generate(
+                video=video,
+                transcript=transcript,
+                content_type=content_type,
+                backend=backend,
+                model=model,
+                prompt_file=prompt_file,
+                language=language,
+            )
+        except Exception as e:
+            click.echo(f"  ERROR generating: {e}", err=True)
+            sys.exit(1)
+        out = output_path(output_dir, resolved_title)
+        out.write_text(_frontmatter(resolved_title, video.url, video.description, draft) + markdown, encoding="utf-8")
+        click.echo(f"  Written: {out}")
+        return
+
+    all_urls = list(urls)
+    if url_file:
+        lines = url_file.read_text(encoding="utf-8").splitlines()
+        all_urls.extend(line.strip() for line in lines if line.strip() and not line.startswith("#"))
+
+    if not all_urls:
+        raise click.UsageError("No URLs provided. Pass URLs as arguments or use --url-file.")
+
+    # Expand playlists to individual video URLs
+    expanded: list[str] = []
+    for raw_url in all_urls:
+        try:
+            resolved = resolve_urls(raw_url)
+            if len(resolved) > 1:
+                click.echo(f"[yt-instruct] Playlist detected: {len(resolved)} videos in {raw_url}")
+            expanded.extend(resolved)
+        except Exception as e:
+            click.echo(f"[yt-instruct] WARNING: could not resolve {raw_url}: {e}", err=True)
+            expanded.append(raw_url)  # try anyway
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Use a persistent temp dir so we can --keep audio if needed
+    tmp_dir = Path(tempfile.mkdtemp(prefix="yt-instruct-"))
+    results: list[tuple[str, str]] = []  # (title, markdown)
+
+    try:
+        for i, url in enumerate(expanded, 1):
+            prefix = f"[{i}/{len(expanded)}]" if len(expanded) > 1 else ""
+            click.echo(f"\n[yt-instruct]{prefix} Processing: {url}")
+
+            video = None
+            transcript = None
+            skip_download = False
+            skip_transcription = False
+
+            # Resume: fetch lightweight metadata, then check for existing output / cached transcript
+            if resume:
+                try:
+                    meta = fetch_info(url)
+                except Exception as e:
+                    click.echo(f"  WARNING: could not fetch metadata for resume check: {e}", err=True)
+                    meta = None
+
+                if meta:
+                    out = output_path(output_dir, meta.title)
+                    if out.exists():
+                        click.echo(f"  [resume] Already done, skipping: {out.name}")
+                        continue
+
+                    cached_transcript = _transcript_cache_path(output_dir, meta.title)
+                    if cached_transcript.exists():
+                        click.echo(f"  [resume] Found cached transcript, skipping download and transcription.")
+                        transcript = cached_transcript.read_text(encoding="utf-8").strip()
+                        video = meta
+                        skip_download = True
+                        skip_transcription = True
+
+            # Step 1: Download
+            if not skip_download:
+                click.echo("  Downloading audio...")
+                try:
+                    video = download_audio(url, tmp_dir, audio_format)
+                except Exception as e:
+                    click.echo(f"  ERROR downloading {url}: {e}", err=True)
+                    if len(expanded) > 1 and i < len(expanded):
+                        if not click.confirm("  Continue with remaining videos?", default=True):
+                            break
+                    continue
+                click.echo(f"  Downloaded: {video.title!r} ({video.channel})")
+
+            # Step 2: Transcribe
+            if not skip_transcription:
+                click.echo("  Transcribing...")
+                try:
+                    transcript = transcribe(video.audio_path, mistral_model)
+                except Exception as e:
+                    click.echo(f"  ERROR transcribing {url}: {e}", err=True)
+                    continue
+                click.echo(f"  Transcript: {len(transcript)} chars")
+                if keep:
+                    _transcript_cache_path(output_dir, video.title).write_text(transcript, encoding="utf-8")
+
+            # Step 3: Generate
+            lang_note = f", language={language}" if language else ""
+            click.echo(f"  Generating ({content_type}, backend={backend}{lang_note})...")
+            try:
+                markdown = generate(
+                    video=video,
+                    transcript=transcript,
+                    content_type=content_type,
+                    backend=backend,
+                    model=model,
+                    prompt_file=prompt_file,
+                    language=language,
+                )
+            except Exception as e:
+                click.echo(f"  ERROR generating for {url}: {e}", err=True)
+                continue
+
+            results.append((video.title, markdown))
+
+            if not merge:
+                out = output_path(output_dir, video.title)
+                out.write_text(_frontmatter(video.title, video.url, video.description, draft) + markdown, encoding="utf-8")
+                click.echo(f"  Written: {out}")
+
+    finally:
+        import shutil
+        if keep:
+            # Move remaining intermediate audio files into output_dir
+            moved = []
+            for f in tmp_dir.iterdir():
+                dest = output_dir / f.name
+                shutil.move(str(f), dest)
+                moved.append(dest.name)
+            if moved:
+                click.echo(f"\nIntermediate audio files moved to {output_dir}/: {', '.join(moved)}")
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    if not results:
+        click.echo("\nNo documents generated.", err=True)
+        sys.exit(1)
+
+    # Merge mode: combine all into one file
+    if merge:
+        combined = "\n\n---\n\n".join(md for _, md in results)
+        merged_path = output_dir / "merged_instructions.md"
+        merged_path.write_text(combined, encoding="utf-8")  # no frontmatter for merged docs
+        click.echo(f"\nMerged document written: {merged_path}")
+    else:
+        click.echo(f"\nDone. {len(results)} document(s) written to {output_dir}/")

yt_instruct/downloader.py

@@ -0,0 +1,105 @@
+"""Audio downloader using yt-dlp."""
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from yt_dlp import YoutubeDL
+
+
+@dataclass
+class VideoInfo:
+    title: str
+    channel: str
+    url: str
+    duration: int | None
+    audio_path: Path | None
+    description: str = ""
+
+
+def _check_ffmpeg() -> None:
+    """Raise a clear error if ffmpeg is not available."""
+    if shutil.which("ffmpeg") is None:
+        raise RuntimeError(
+            "ffmpeg is required but not found. "
+            "Install it with: brew install ffmpeg  (macOS) or apt install ffmpeg  (Linux)"
+        )
+
+
+def fetch_info(url: str) -> "VideoInfo":
+    """Fetch video metadata without downloading audio (lightweight network call)."""
+    opts = {"quiet": True, "no_warnings": True}
+    with YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+    return VideoInfo(
+        title=info.get("title", url),
+        channel=info.get("uploader") or info.get("channel", "Unknown"),
+        url=url,
+        duration=info.get("duration"),
+        audio_path=None,
+        description=info.get("description") or "",
+    )
+
+
+def resolve_urls(url: str) -> list[str]:
+    """Expand a URL to a list of video URLs. Handles playlists and single videos."""
+    opts = {
+        "extract_flat": "in_playlist",
+        "quiet": True,
+        "no_warnings": True,
+    }
+    with YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+
+    if info.get("_type") == "playlist":
+        entries = info.get("entries") or []
+        urls = []
+        for entry in entries:
+            if entry and entry.get("url"):
+                urls.append(entry["url"])
+            elif entry and entry.get("id"):
+                urls.append(f"https://www.youtube.com/watch?v={entry['id']}")
+        return urls
+
+    return [url]
+
+
+def download_audio(url: str, tmp_dir: Path, audio_format: str = "mp3") -> VideoInfo:
+    """Download audio from a YouTube URL. Returns VideoInfo with audio_path set."""
+    _check_ffmpeg()
+
+    opts = {
+        "format": "bestaudio/best",
+        "postprocessors": [
+            {
+                "key": "FFmpegExtractAudio",
+                "preferredcodec": audio_format,
+            }
+        ],
+        "outtmpl": str(tmp_dir / "%(id)s.%(ext)s"),
+        "quiet": True,
+        "no_warnings": True,
+    }
+
+    with YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=True)
+
+    video_id = info["id"]
+    audio_path = tmp_dir / f"{video_id}.{audio_format}"
+
+    if not audio_path.exists():
+        # yt-dlp may have used a different extension
+        candidates = list(tmp_dir.glob(f"{video_id}.*"))
+        if not candidates:
+            raise FileNotFoundError(f"Downloaded audio not found in {tmp_dir}")
+        audio_path = candidates[0]
+
+    return VideoInfo(
+        title=info.get("title", video_id),
+        channel=info.get("uploader") or info.get("channel", "Unknown"),
+        url=url,
+        duration=info.get("duration"),
+        audio_path=audio_path,
+        description=info.get("description") or "",
+    )

yt_instruct/generator.py

@@ -0,0 +1,226 @@
+"""Instruction document generator using Claude (Anthropic SDK or llm library) or NVIDIA NIM."""
+
+import importlib.resources
+import os
+from pathlib import Path
+
+from .downloader import VideoInfo
+from .utils import format_duration
+
+BUILTIN_PROMPTS_PACKAGE = "yt_instruct.prompts"
+
+AUTO_CLASSIFY_PROMPT = """You are classifying a YouTube video. Based on the title and channel below,
+respond with exactly one word — the content type that best fits:
+- tutorial  (how-to, step-by-step, practical skill)
+- lecture   (tech talk, academic, educational presentation)
+- ib        (IB student subject: maths, sciences, humanities, etc.)
+
+Title: {title}
+Channel: {channel}
+
+Respond with one word only."""
+
+
+def _load_builtin_prompt(content_type: str) -> str:
+    """Load a built-in prompt template from the prompts package."""
+    try:
+        ref = importlib.resources.files(BUILTIN_PROMPTS_PACKAGE).joinpath(
+            f"{content_type}.md"
+        )
+        return ref.read_text(encoding="utf-8")
+    except (FileNotFoundError, TypeError):
+        # Fall back to default
+        ref = importlib.resources.files(BUILTIN_PROMPTS_PACKAGE).joinpath("default.md")
+        return ref.read_text(encoding="utf-8")
+
+
+def _load_prompt(content_type: str, prompt_file: Path | None) -> str:
+    """Load prompt template from user file or built-in resource."""
+    if prompt_file:
+        return Path(prompt_file).read_text(encoding="utf-8")
+    return _load_builtin_prompt(content_type)
+
+
+def _build_messages(
+    video: VideoInfo, transcript: str, content_type: str, system_prompt: str,
+    language: str | None = None,
+) -> tuple[str, str]:
+    """Return (system, user) message strings."""
+    system = system_prompt.format(
+        title=video.title,
+        channel=video.channel,
+        content_type=content_type,
+        duration=format_duration(video.duration),
+    )
+    if language:
+        system += f"\n\nWrite the output document in {language}."
+    user = (
+        f"Video: {video.title}\n"
+        f"Channel: {video.channel}\n"
+        f"URL: {video.url}\n"
+        f"Duration: {format_duration(video.duration)}\n\n"
+        f"Transcript:\n{transcript}"
+    )
+    return system, user
+
+
+def _detect_content_type_anthropic(
+    video: VideoInfo, model: str, client
+) -> str:
+    prompt = AUTO_CLASSIFY_PROMPT.format(title=video.title, channel=video.channel)
+    msg = client.messages.create(
+        model=model,
+        max_tokens=10,
+        messages=[{"role": "user", "content": prompt}],
+    )
+    result = msg.content[0].text.strip().lower()
+    return result if result in ("adhd", "tutorial", "lecture", "ib") else "tutorial"
+
+
+def _detect_content_type_llm(video: VideoInfo, model_name: str) -> str:
+    import llm
+
+    prompt = AUTO_CLASSIFY_PROMPT.format(title=video.title, channel=video.channel)
+    model_obj = llm.get_model(model_name)
+    result = model_obj.prompt(prompt).text().strip().lower()
+    return result if result in ("adhd", "tutorial", "lecture", "ib") else "tutorial"
+
+
+def generate_anthropic(
+    video: VideoInfo,
+    transcript: str,
+    content_type: str,
+    model: str,
+    prompt_file: Path | None,
+    language: str | None = None,
+    max_tokens: int = 4096,
+) -> str:
+    """Generate instruction document using Anthropic SDK."""
+    import anthropic
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "ANTHROPIC_API_KEY environment variable is not set."
+        )
+
+    client = anthropic.Anthropic(api_key=api_key)
+
+    # Auto-detect content type if requested
+    resolved_type = content_type
+    if content_type == "auto":
+        resolved_type = _detect_content_type_anthropic(video, model, client)
+
+    system_prompt = _load_prompt(resolved_type, prompt_file)
+    system, user = _build_messages(video, transcript, resolved_type, system_prompt, language)
+
+    msg = client.messages.create(
+        model=model,
+        max_tokens=max_tokens,
+        system=system,
+        messages=[{"role": "user", "content": user}],
+    )
+    return msg.content[0].text
+
+
+def generate_llm(
+    video: VideoInfo,
+    transcript: str,
+    content_type: str,
+    model: str,
+    prompt_file: Path | None,
+    language: str | None = None,
+) -> str:
+    """Generate instruction document using simonw/llm library."""
+    import llm
+
+    resolved_type = content_type
+    if content_type == "auto":
+        resolved_type = _detect_content_type_llm(video, model)
+
+    system_prompt = _load_prompt(resolved_type, prompt_file)
+    system, user = _build_messages(video, transcript, resolved_type, system_prompt, language)
+
+    model_obj = llm.get_model(model)
+    return model_obj.prompt(user, system=system).text()
+
+
+def _detect_content_type_nvidia(video: VideoInfo, model: str, client) -> str:
+    prompt = AUTO_CLASSIFY_PROMPT.format(title=video.title, channel=video.channel)
+    completion = client.chat.completions.create(
+        model=model,
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=10,
+        temperature=0.0,
+    )
+    result = completion.choices[0].message.content.strip().lower()
+    return result if result in ("adhd", "tutorial", "lecture", "ib") else "tutorial"
+
+
+def generate_nvidia(
+    video: VideoInfo,
+    transcript: str,
+    content_type: str,
+    model: str,
+    prompt_file: Path | None,
+    language: str | None = None,
+    max_tokens: int = 4096,
+) -> str:
+    """Generate instruction document using NVIDIA NIM (OpenAI-compatible API)."""
+    from openai import OpenAI
+
+    api_key = os.environ.get("NVIDIA_API_KEY")
+    if not api_key:
+        raise RuntimeError("NVIDIA_API_KEY environment variable is not set.")
+
+    client = OpenAI(
+        base_url="https://integrate.api.nvidia.com/v1",
+        api_key=api_key,
+    )
+
+    resolved_type = content_type
+    if content_type == "auto":
+        resolved_type = _detect_content_type_nvidia(video, model, client)
+
+    system_prompt = _load_prompt(resolved_type, prompt_file)
+    system, user = _build_messages(video, transcript, resolved_type, system_prompt, language)
+
+    chunks = []
+    completion = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        temperature=0.6,
+        top_p=0.9,
+        max_tokens=max_tokens,
+        stream=True,
+    )
+    for chunk in completion:
+        if not getattr(chunk, "choices", None):
+            continue
+        delta = chunk.choices[0].delta.content
+        if delta is not None:
+            chunks.append(delta)
+    return "".join(chunks)
+
+
+def generate(
+    video: VideoInfo,
+    transcript: str,
+    content_type: str,
+    backend: str,
+    model: str,
+    prompt_file: Path | None,
+    language: str | None = None,
+) -> str:
+    """Dispatch to the appropriate backend."""
+    if backend == "anthropic":
+        return generate_anthropic(video, transcript, content_type, model, prompt_file, language)
+    elif backend == "llm":
+        return generate_llm(video, transcript, content_type, model, prompt_file, language)
+    elif backend == "nvidia":
+        return generate_nvidia(video, transcript, content_type, model, prompt_file, language)
+    else:
+        raise ValueError(f"Unknown backend: {backend!r}. Choose 'anthropic', 'llm', or 'nvidia'.")

yt_instruct/prompts/__init__.py

@@ -0,0 +1 @@
+# This package contains built-in prompt templates.

yt_instruct/prompts/adhd.md

@@ -0,0 +1,29 @@
+You are an expert technical writer specialising in academic and conference content. Given the transcript of a tech talk or lecture, produce a structured study document.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+The central thesis or topic of the talk and why it matters. Include the speaker's name and affiliation if mentioned.
+Include a link to the source youtube video.
+
+## Prerequisites
+Background knowledge, concepts, or tools a reader should understand before engaging with this material.
+
+## Main Points
+For each major section or argument in the talk:
+- A short heading summarising the point
+- 2–5 bullet points capturing the key ideas, data, or conclusions
+- Code blocks or diagrams described textually where relevant
+
+## Key Concepts
+Bullet list of terms, frameworks, or tools introduced. One-sentence definition each.
+
+## Summary
+One paragraph: the overall argument, findings, or message the speaker wanted to leave the audience with.
+
+Write in clear, objective prose. Preserve the logical structure of the talk. Do not editorialize beyond what the speaker said.

yt_instruct/prompts/default.md

@@ -0,0 +1,27 @@
+You are an expert technical writer. Given a YouTube video transcript, produce a clear, structured markdown instruction document.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Content type: {content_type}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+What this video is about and what the viewer will learn or be able to do after watching.
+Include a link to the source youtube video.
+
+## Prerequisites
+What the reader needs to know, have installed, or have ready before starting.
+
+## Step-by-step Instructions
+Numbered, clear, actionable steps. Use sub-steps where needed. Include code blocks for any commands or code shown.
+
+## Key Concepts
+Bullet list of important terms, tools, or ideas introduced. Give a one-sentence explanation for each.
+
+## Summary
+A single paragraph recapping what was covered and the main takeaway.
+
+Write in clear, direct prose. Use markdown formatting (headers, bullets, numbered lists, code fences). Do not invent steps not present in the transcript.

yt_instruct/prompts/ib copy.md

@@ -0,0 +1,30 @@
+You are an experienced IB teacher and study guide author. Given the transcript of an IB student video, produce a structured revision document aligned with IB assessment expectations.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+The subject, topic, and IB syllabus point(s) this video addresses. State the IB course and level (SL/HL) if identifiable.
+
+## Prior Knowledge Required
+Concepts and vocabulary the student should already know before studying this topic.
+
+## Core Content
+Numbered steps or structured explanation of the topic, as presented in the video:
+- Include definitions, formulas, or worked examples in code/math blocks where appropriate
+- Flag IB command terms used (e.g., "Evaluate", "Discuss", "Calculate") and what they require
+
+## Key Vocabulary
+Bullet list of subject-specific terms introduced. IB-accurate definitions.
+
+## Exam Tips
+Any advice given in the video about exam technique, common mistakes, or mark-scheme expectations.
+
+## Summary
+One paragraph recap of the key learning for this topic and how it fits into the broader IB syllabus.
+
+Write at a level appropriate for an IB student. Be precise and accurate. Do not invent content not present in the transcript.

yt_instruct/prompts/ib.md

@@ -0,0 +1,37 @@
+You are an experienced IB teacher and study guide author. Given the transcript of an IB student video, produce a structured revision document aligned with IB assessment expectations.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+The subject, topic, and IB syllabus point(s) this video addresses. State the IB course and level (SL/HL) if identifiable.
+Include a link to the source youtube video.
+
+## Prior Knowledge Required
+Concepts and vocabulary the student should already know before studying this topic.
+
+## Step-by-step Instructions
+Numbered steps to accomplish a similar task as demonstrated in the video. For each step:
+- State clearly what to do
+- Include instructions and any IB command terms.
+- Note any common pitfalls or "watch out" moments mentioned
+
+## Core Content
+Numbered steps or structured explanation of the topic, as presented in the video:
+- Include definitions, formulas, or worked examples in code/math blocks where appropriate
+- Flag IB command terms used (e.g., "Evaluate", "Discuss", "Calculate") and what they require
+
+## Key Vocabulary
+Bullet list of subject-specific terms introduced. IB-accurate definitions.
+
+## Exam Tips
+Any advice given in the video about exam technique, common mistakes, or mark-scheme expectations.
+
+## Summary
+One paragraph recap of the key learning for this topic and how it fits into the broader IB syllabus.
+
+Write at a level appropriate for an IB student. Be precise and accurate. Do not invent content not present in the transcript.

yt_instruct/prompts/lecture.md

@@ -0,0 +1,29 @@
+You are an expert technical writer specialising in academic and conference content. Given the transcript of a tech talk or lecture, produce a structured study document.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+The central thesis or topic of the talk and why it matters. Include the speaker's name and affiliation if mentioned.
+Include a link to the source youtube video.
+
+## Prerequisites
+Background knowledge, concepts, or tools a reader should understand before engaging with this material.
+
+## Main Points
+For each major section or argument in the talk:
+- A short heading summarising the point
+- 2–5 bullet points capturing the key ideas, data, or conclusions
+- Code blocks or diagrams described textually where relevant
+
+## Key Concepts
+Bullet list of terms, frameworks, or tools introduced. One-sentence definition each.
+
+## Summary
+One paragraph: the overall argument, findings, or message the speaker wanted to leave the audience with.
+
+Write in clear, objective prose. Preserve the logical structure of the talk. Do not editorialize beyond what the speaker said.

yt_instruct/prompts/tutorial.md

@@ -0,0 +1,29 @@
+You are an expert technical writer specialising in how-to guides and tutorials. Given a YouTube tutorial transcript, produce a precise, hands-on instruction document a reader can follow without watching the video.
+
+Video details:
+- Title: {title}
+- Channel: {channel}
+- Duration: {duration}
+
+Produce the following sections in order:
+
+## Overview
+What task or skill this tutorial teaches and what the finished result looks like.
+Include a link to the source youtube video.
+
+## Prerequisites
+Tools, software, accounts, or prior knowledge required. Be specific about versions where mentioned.
+
+## Step-by-step Instructions
+Numbered steps in the exact order demonstrated. For each step:
+- State clearly what to do
+- Include code blocks (with language tag) for any commands, config, or code
+- Note any common pitfalls or "watch out" moments mentioned
+
+## Key Concepts
+Bullet list of important terms, tools, or techniques introduced. One sentence each.
+
+## Summary
+One paragraph: what was built/accomplished and what the reader should now be able to do independently.
+
+Write in imperative voice ("Click...", "Run...", "Open..."). Do not add steps not present in the transcript.

yt_instruct/transcriber.py

@@ -0,0 +1,30 @@
+"""Audio transcription using Mistral's voxtral API."""
+
+import os
+from pathlib import Path
+
+from mistralai.client import Mistral
+
+
+def transcribe(audio_path: Path, model: str = "voxtral-mini-latest") -> str:
+    """Transcribe audio file using Mistral. Returns transcript as plain text."""
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "MISTRAL_API_KEY environment variable is not set. "
+            "Get your key at https://console.mistral.ai/"
+        )
+
+    client = Mistral(api_key=api_key)
+
+    with open(audio_path, "rb") as f:
+        result = client.audio.transcriptions.complete(
+            model=model,
+            file={"file_name": audio_path.name, "content": f},
+        )
+
+    transcript = result.text
+    if not transcript or not transcript.strip():
+        raise ValueError(f"Empty transcript returned for {audio_path.name}")
+
+    return transcript.strip()

yt_instruct/utils.py

@@ -0,0 +1,34 @@
+"""Utility helpers: slugify, path helpers, metadata formatting."""
+
+import re
+import unicodedata
+from pathlib import Path
+
+
+def slugify(text: str, max_length: int = 80) -> str:
+    """Convert text to a filesystem-safe slug."""
+    text = unicodedata.normalize("NFKD", text)
+    text = text.encode("ascii", "ignore").decode("ascii")
+    text = text.lower()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_-]+", "-", text)
+    text = text.strip("-")
+    return text[:max_length]
+
+
+def output_path(output_dir: Path, title: str, suffix: str = "_instructions.md") -> Path:
+    """Return the output file path for a given video title."""
+    slug = slugify(title)
+    return output_dir / f"{slug}{suffix}"
+
+
+def format_duration(seconds: int) -> str:
+    """Format duration in seconds to HH:MM:SS or MM:SS."""
+    if seconds is None:
+        return "unknown"
+    h = seconds // 3600
+    m = (seconds % 3600) // 60
+    s = seconds % 60
+    if h:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"

yt_instruct-1.0.0.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: yt-instruct
+Version: 1.0.0
+Summary: Convert YouTube videos into structured markdown instruction documents
+License: MIT
+Keywords: youtube,transcription,llm,instructions,mistral
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: yt-dlp>=2024.1
+Requires-Dist: mistralai>=1.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: openai>=1.0
+Requires-Dist: llm>=0.17
+Requires-Dist: llm-anthropic>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+
+# yt-instruct
+
+Convert YouTube videos into structured markdown instruction documents.
+
+Downloads audio via yt-dlp, transcribes with Mistral's voxtral API, then generates a clean how-to document using Claude.
+
+## Quick Start
+
+```bash
+# Run with uvx (no install needed)
+uvx --from . yt-instruct https://www.youtube.com/watch?v=<id>
+
+# Or install
+pip install -e .
+yt-instruct https://www.youtube.com/watch?v=<id>
+```
+
+## Requirements
+
+- `ffmpeg` — `brew install ffmpeg` or `apt install ffmpeg`
+- `MISTRAL_API_KEY` — [console.mistral.ai](https://console.mistral.ai/)
+- `ANTHROPIC_API_KEY` — for default backend
+- `NVIDIA_API_KEY` — only for `--backend nvidia`
+
+## Usage
+
+```
+yt-instruct [OPTIONS] URL [URL...]
+yt-instruct [OPTIONS] --url-file urls.txt
+yt-instruct [OPTIONS] --transcript-file transcript.txt --title "Name"
+yt-instruct [OPTIONS] --audio-file recording.mp3 --title "Name"
+
+Options:
+  --output-dir PATH              Output directory [default: .]
+  --keep                         Keep intermediate audio + transcript files
+  --merge                        Merge all videos into one document
+  --resume                       Skip already-generated outputs; reuse cached transcripts
+  --content-type [tutorial|lecture|ib|auto]
+                                 Prompt style [default: auto]
+  --backend [anthropic|llm|nvidia]
+                                 LLM backend [default: anthropic]
+  --model TEXT                   Model name [default: claude-sonnet-4-6]
+  --prompt-file PATH             Custom system prompt (overrides built-in)
+  --language LANG                Output language (e.g. 'French'). Defaults to English.
+  --transcript-file PATH         Use existing transcript; skips download and transcription
+  --audio-file PATH              Use existing audio file; skips download, transcribes directly
+  --title TEXT                   Video title for --transcript-file or --audio-file
+  --draft                        Set draft: true in the output frontmatter [default: false]
+  --mistral-model TEXT           [default: voxtral-mini-latest]
+  --audio-format [mp3|m4a]       [default: mp3]
+  --version                      Show version and exit
+```
+
+## Output Frontmatter
+
+Every generated file includes YAML frontmatter:
+
+```yaml
+---
+title: "Video Title"
+url: https://youtu.be/...
+description: "YouTube video description"
+date: 2026-04-12
+draft: false
+---
+```
+
+Use `--draft` to set `draft: true` (useful for Hugo, Jekyll, or similar static site generators).
+Merged documents (`--merge`) do not include frontmatter.
+
+## Content Types
+
+| Type | Use for |
+|------|---------|
+| `auto` | Let the LLM detect (default) |
+| `tutorial` | How-to / step-by-step videos |
+| `lecture` | Tech talks, academic presentations |
+| `ib` | IB student subject videos |
+
+## Custom Prompts
+
+Override the built-in prompt with your own file. Template variables:
+`{title}`, `{channel}`, `{content_type}`, `{duration}`
+
+```bash
+yt-instruct <url> --prompt-file my_prompt.md
+```
+
+## Using the `llm` backend
+
+```bash
+pip install llm llm-anthropic
+llm keys set anthropic
+yt-instruct <url> --backend llm --model claude-sonnet-4-6
+```
+
+## Using the `nvidia` backend
+
+```bash
+NVIDIA_API_KEY=... yt-instruct <url> --backend nvidia --model moonshotai/kimi-k2-instruct
+```
+
+## Batch Processing
+
+```bash
+# Multiple URLs
+yt-instruct url1 url2 url3 --output-dir ./docs
+
+# Playlist (automatically expanded)
+yt-instruct https://www.youtube.com/playlist?list=<id> --output-dir ./docs
+
+# From file
+cat urls.txt | yt-instruct --url-file /dev/stdin
+
+# Merge all into one doc
+yt-instruct url1 url2 --merge --output-dir ./docs
+```
+
+## Skip Steps — Use Existing Files
+
+`--audio-file` and `--transcript-file` resolve relative to `--output-dir` if the file isn't found at the given path. This lets you reference files already in the output directory without typing the full path:
+
+```bash
+# Start from an existing transcript (skips download + transcription)
+yt-instruct --transcript-file transcript.txt --title "My Video" --output-dir ./docs
+
+# File not found locally? Looked up in ./docs automatically
+yt-instruct --transcript-file my_transcript.txt --output-dir ./docs
+
+# Start from an existing audio file (skips download, still transcribes)
+yt-instruct --audio-file recording.mp3 --output-dir ./docs
+```
+
+## Resume an Interrupted Run
+
+Use `--keep` to save transcripts alongside output files, then `--resume` to continue from where a previous run stopped:
+
+```bash
+# First run (interrupted partway through)
+yt-instruct --url-file urls.txt --keep --output-dir ./docs
+
+# Resume — skips videos with existing output; reuses cached transcripts
+yt-instruct --url-file urls.txt --resume --output-dir ./docs
+```
+
+`--resume` checks at two levels per video:
+1. Output `.md` already exists → skip entirely
+2. Cached `*_transcript.txt` exists (saved by `--keep`) → skip download and transcription, regenerate only

yt_instruct-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+yt_instruct/__init__.py,sha256=puGUXxk3GrYnjI7p-NMAxj2G7ak2PMN0kaR0VH2d6FU,113
+yt_instruct/cli.py,sha256=2HpM9sSNAq6MHG8AV2l9kbv7ow97K5br7yuaAwFPMz0,15618
+yt_instruct/downloader.py,sha256=ooKZH-oqCWwSd8sAZdrPTtcOYxPrn85Vy-nRXXSEPh8,3100
+yt_instruct/generator.py,sha256=TL-2UwWbRQS1zp-FKSvjeA7gEG-lHnDY1K3FnwOkUCQ,7309
+yt_instruct/transcriber.py,sha256=v6cYbsQUuqJ1zD4HZGtd_FvsNtszR_ksUUbTE-fIXHk,935
+yt_instruct/utils.py,sha256=Rxi71MyxP31Su9oqdThc-WluIp4HoE_qZAXqefaXOiE,1018
+yt_instruct/prompts/__init__.py,sha256=WnDEDYVY8aRBWOKOrshZb51w1Ly6j1wgLzvta3gDgIk,51
+yt_instruct/prompts/adhd.md,sha256=xcTcJVFWba3v03JQsQ8zpbql2PtWurq4GqQovM8uVKY,1164
+yt_instruct/prompts/default.md,sha256=Dk4H8TWLE3QLFk0WKY1YDvEKuR6UVCB0QQrJXECDknQ,1021
+yt_instruct/prompts/ib copy.md,sha256=nOJPcDQEN_eYSMaEwp09zwJ6NuVywO7RP5Vn5jelHwk,1279
+yt_instruct/prompts/ib.md,sha256=u7yTo56yhKatDXC88FI4XuOH2Md247HAZ8aG01kHnC8,1578
+yt_instruct/prompts/lecture.md,sha256=xcTcJVFWba3v03JQsQ8zpbql2PtWurq4GqQovM8uVKY,1164
+yt_instruct/prompts/tutorial.md,sha256=-ebKqa5UDbtfWMTraQmh7-aCtpBko69TnLKKl4hAKgE,1172
+yt_instruct-1.0.0.dist-info/METADATA,sha256=sArVltXvahVBQpr6RBuiBb8dfyvL_i1kQvl1BDpQekQ,5613
+yt_instruct-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+yt_instruct-1.0.0.dist-info/entry_points.txt,sha256=qPxnA0Z4pI31BtK6nHqkj0ht6plyOu0pdRQ1i0CIMl8,52
+yt_instruct-1.0.0.dist-info/top_level.txt,sha256=hxhWCJlZPjBIQ16fG70OuZ8J1n2zTnWpRJqXTr02eGc,12
+yt_instruct-1.0.0.dist-info/RECORD,,

yt_instruct-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yt_instruct-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yt-instruct = yt_instruct.cli:cli

yt_instruct-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yt_instruct