studyctl 2.0.0__py3-none-any.whl

studyctl/content/notebooklm_client.py

@@ -0,0 +1,434 @@
+"""NotebookLM integration module for uploading chapters and generating overviews."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from studyctl.content.models import NotebookInfo, SourceInfo, UploadResult
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from notebooklm import NotebookLMClient
+
+logger = logging.getLogger(__name__)
+
+
+def _import_notebooklm():
+    """Lazy-import notebooklm-py, raising a clear error if not installed."""
+    try:
+        import notebooklm
+    except ImportError as exc:
+        raise ImportError(
+            "notebooklm-py is required for NotebookLM integration. "
+            "Install with: uv pip install notebooklm-py"
+        ) from exc
+    return notebooklm
+
+
+async def upload_chapters(
+    chapter_pdfs: list[Path],
+    book_name: str,
+    notebook_id: str | None = None,
+) -> UploadResult:
+    """Upload chapter PDFs to a NotebookLM notebook.
+
+    If no notebook_id is given, checks for an existing notebook with a
+    matching title before creating a new one.
+    """
+    nlm = _import_notebooklm()
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        if notebook_id:
+            nb_id = notebook_id
+            nb_title = book_name
+            logger.info("Using existing notebook: %s", nb_id)
+        else:
+            notebooks = await client.notebooks.list()
+            existing = next((nb for nb in notebooks if nb.title == book_name), None)
+            if existing:
+                nb_id = existing.id
+                nb_title = existing.title
+                logger.info("Found existing notebook: %s (%s)", nb_title, nb_id)
+            else:
+                notebook = await client.notebooks.create(title=book_name)
+                nb_id = notebook.id
+                nb_title = notebook.title
+                logger.info("Created notebook: %s (%s)", nb_title, nb_id)
+
+        for pdf_path in chapter_pdfs:
+            await client.sources.add_file(nb_id, pdf_path)
+            logger.info("Uploaded %s", pdf_path.name)
+            await asyncio.sleep(2)
+
+    return UploadResult(id=nb_id, title=nb_title, chapters=len(chapter_pdfs))
+
+
+async def list_notebooks() -> list[NotebookInfo]:
+    """List all NotebookLM notebooks with source counts."""
+    nlm = _import_notebooklm()
+    results: list[NotebookInfo] = []
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        notebooks = await client.notebooks.list()
+        for nb in notebooks:
+            sources = await client.sources.list(nb.id)
+            results.append(NotebookInfo(id=nb.id, title=nb.title, sources_count=len(sources)))
+    return results
+
+
+async def list_sources(notebook_id: str) -> list[SourceInfo]:
+    """List all sources in a notebook."""
+    nlm = _import_notebooklm()
+    results: list[SourceInfo] = []
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        sources = await client.sources.list(notebook_id)
+        for src in sources:
+            results.append(SourceInfo(id=src.id, title=src.title))
+    return results
+
+
+MAX_RETRIES = 3
+
+
+async def _request_chapter_artifact(
+    client: NotebookLMClient,
+    notebook_id: str,
+    label: str,
+    source_ids: list[str],
+    instructions: str,
+) -> str:
+    """Fire off a single chapter generation request. Returns task_id.
+
+    Raises:
+        RuntimeError: If the API returns a failed status (rate limit, quota, etc.)
+    """
+    nlm = _import_notebooklm()
+    if label == "audio":
+        status = await client.artifacts.generate_audio(
+            notebook_id,
+            source_ids=source_ids,
+            instructions=instructions,
+            audio_format=nlm.AudioFormat.DEEP_DIVE,
+        )
+    elif label == "video":
+        status = await client.artifacts.generate_video(
+            notebook_id,
+            source_ids=source_ids,
+            instructions=instructions,
+            video_style=nlm.VideoStyle.WHITEBOARD,
+        )
+    else:
+        raise ValueError(f"Unknown artifact type: {label}")
+
+    if status.is_failed or not status.task_id:
+        error_msg = status.error or "unknown error"
+        error_code = status.error_code or ""
+        raise RuntimeError(
+            f"{label} generation rejected by API: {error_msg}"
+            + (f" (code: {error_code})" if error_code else "")
+        )
+
+    return status.task_id
+
+
+async def generate_for_chapters(
+    notebook_id: str,
+    chapter_range: tuple[int, int],
+    generate_audio: bool = True,
+    generate_video: bool = True,
+    timeout: int = 900,
+) -> None:
+    """Generate audio/video overviews for a chapter range.
+
+    Fires off requests concurrently, polls every 30s. Retries failed
+    artifacts up to MAX_RETRIES times.
+    """
+    nlm = _import_notebooklm()
+    start, end = chapter_range
+    range_label = f"ch{start}-{end}"
+
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        sources = await client.sources.list(notebook_id)
+        sources.sort(key=lambda s: s.title)
+        selected = sources[start - 1 : end]
+
+        if not selected:
+            logger.warning("No sources found in the specified range")
+            return
+
+        selected_ids = [s.id for s in selected]
+        logger.info(
+            "Generating for chapters %d-%d (%d sources): %s",
+            start,
+            end,
+            len(selected),
+            ", ".join(s.title for s in selected),
+        )
+
+        tasks: dict[str, str] = {}
+        retries: dict[str, int] = {}
+        instructions = {
+            "audio": f"Create an engaging audio overview covering chapters {start} to {end}",
+            "video": f"Create a visual explainer covering chapters {start} to {end}",
+        }
+
+        for label, should_gen in [("audio", generate_audio), ("video", generate_video)]:
+            if not should_gen:
+                continue
+            retries[label] = 0
+            try:
+                logger.info("Requesting %s (%s)...", label, range_label)
+                tasks[label] = await _request_chapter_artifact(
+                    client, notebook_id, label, selected_ids, instructions[label]
+                )
+            except Exception as e:
+                logger.error("Failed to request %s: %s", label, e)
+
+        pending = dict(tasks)
+        elapsed = 0
+        poll_interval = 30
+
+        logger.info(
+            "Timeout: %ds (%dmin), max retries: %d",
+            timeout,
+            timeout // 60,
+            MAX_RETRIES,
+        )
+
+        while pending and elapsed < timeout:
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+
+            for label, task_id in list(pending.items()):
+                try:
+                    result = await client.artifacts.poll_status(notebook_id, task_id)
+                except Exception as e:
+                    logger.warning("Poll error for %s: %s", label, e)
+                    continue
+
+                if result.is_complete:
+                    logger.info("%s ready (%s)", label.capitalize(), range_label)
+                    del pending[label]
+                elif result.is_failed:
+                    retries[label] += 1
+                    if retries[label] <= MAX_RETRIES:
+                        logger.warning(
+                            "%s failed (%s) -- retrying (%d/%d)...",
+                            label.capitalize(),
+                            result.error or "unknown error",
+                            retries[label],
+                            MAX_RETRIES,
+                        )
+                        try:
+                            pending[label] = await _request_chapter_artifact(
+                                client,
+                                notebook_id,
+                                label,
+                                selected_ids,
+                                instructions[label],
+                            )
+                        except Exception as e:
+                            logger.error("Retry failed: %s", e)
+                            del pending[label]
+                    else:
+                        logger.error(
+                            "%s failed after %d retries: %s",
+                            label.capitalize(),
+                            MAX_RETRIES,
+                            result.error,
+                        )
+                        del pending[label]
+                else:
+                    logger.debug("%s still generating (%ds elapsed)", label, elapsed)
+
+        for label in pending:
+            logger.error("%s timed out (%s)", label.capitalize(), range_label)
+
+    logger.info("Generation complete for %s", range_label)
+
+
+async def download_artifacts(
+    notebook_id: str,
+    output_dir: Path,
+    chapter_range: tuple[int, int] | None = None,
+) -> None:
+    """Download audio and video artifacts from a notebook.
+
+    If chapter_range is given, files are named by range (e.g. audio_ch1-3.mp3).
+    Otherwise, files are numbered sequentially.
+    """
+    nlm = _import_notebooklm()
+    output_dir = output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        range_tag = f"_ch{chapter_range[0]}-{chapter_range[1]}" if chapter_range else ""
+
+        audios = await client.artifacts.list_audio(notebook_id)
+        for i, artifact in enumerate(audios, 1):
+            name = f"audio{range_tag}_{i:02d}.mp3"
+            path = str(output_dir / name)
+            await client.artifacts.download_audio(notebook_id, path, artifact_id=artifact.id)
+            logger.info("Downloaded %s", path)
+
+        videos = await client.artifacts.list_video(notebook_id)
+        for i, artifact in enumerate(videos, 1):
+            name = f"video{range_tag}_{i:02d}.mp4"
+            path = str(output_dir / name)
+            await client.artifacts.download_video(notebook_id, path, artifact_id=artifact.id)
+            logger.info("Downloaded %s", path)
+
+    logger.info("Files saved to %s", output_dir)
+
+
+async def delete_notebook(notebook_id: str) -> None:
+    """Delete a notebook and all its contents."""
+    nlm = _import_notebooklm()
+    async with await nlm.NotebookLMClient.from_storage() as client:
+        await client.notebooks.delete(notebook_id)
+        logger.info("Deleted notebook %s", notebook_id)
+
+
+async def delete_artifact(
+    client: NotebookLMClient,
+    notebook_id: str,
+    artifact_id: str,
+) -> None:
+    """Delete an artifact by ID. Best-effort, logs warning on failure."""
+    try:
+        await client.artifacts.delete(notebook_id, artifact_id)
+        logger.info("Deleted artifact %s", artifact_id)
+    except Exception as e:
+        logger.warning("Failed to delete artifact %s: %s", artifact_id, e)
+
+
+async def download_episode_audio(
+    client: NotebookLMClient,
+    notebook_id: str,
+    artifact_id: str,
+    output_path: Path,
+) -> None:
+    """Download a single audio artifact to the specified path.
+
+    Args:
+        client: An open NotebookLM client.
+        notebook_id: The notebook ID.
+        artifact_id: The audio artifact ID (same as task_id).
+        output_path: Full path to save the file (e.g. downloads/01-title.mp3).
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    await client.artifacts.download_audio(notebook_id, str(output_path), artifact_id=artifact_id)
+    logger.info("Downloaded %s", output_path)
+
+
+async def create_syllabus(
+    client: NotebookLMClient,
+    notebook_id: str,
+    prompt: str,
+) -> str:
+    """Send syllabus prompt to NotebookLM chat.
+
+    Args:
+        client: An open NotebookLM client.
+        notebook_id: The notebook ID.
+        prompt: The syllabus generation prompt.
+
+    Returns:
+        Raw AI response text.
+    """
+    result = await client.chat.ask(notebook_id, prompt)
+    return result.answer
+
+
+def _build_instructions(episode_title: str, chapter_titles: list[str] | None) -> dict[str, str]:
+    """Build scoped instructions referencing specific chapter titles."""
+    if chapter_titles:
+        ch_list = ", ".join(chapter_titles)
+        return {
+            "audio": (
+                f"Focus ONLY on these specific chapters: {ch_list}. "
+                f"Create an engaging audio deep-dive covering: {episode_title}. "
+                "Do not discuss content from other chapters."
+            ),
+            "video": (
+                f"Focus ONLY on these specific chapters: {ch_list}. "
+                f"Create a visual explainer covering: {episode_title}. "
+                "Do not discuss content from other chapters."
+            ),
+        }
+    return {
+        "audio": f"Create an engaging audio overview: {episode_title}",
+        "video": f"Create a visual explainer: {episode_title}",
+    }
+
+
+async def start_chunk_generation(
+    client: NotebookLMClient,
+    notebook_id: str,
+    source_ids: list[str],
+    episode_title: str,
+    generate_audio: bool = True,
+    generate_video: bool = True,
+    chapter_titles: list[str] | None = None,
+) -> dict[str, str]:
+    """Fire off generation requests without polling. Returns {label: task_id}.
+
+    Args:
+        client: An open NotebookLM client.
+        notebook_id: The notebook ID.
+        source_ids: Source IDs for this chunk's chapters.
+        episode_title: Title for the episode.
+        generate_audio: Whether to generate audio.
+        generate_video: Whether to generate video.
+        chapter_titles: Actual chapter titles for scoped instructions.
+
+    Returns:
+        Mapping of label ("audio"/"video") -> task_id for started tasks.
+    """
+    instructions = _build_instructions(episode_title, chapter_titles)
+    tasks: dict[str, str] = {}
+    for label, should_gen in [("audio", generate_audio), ("video", generate_video)]:
+        if not should_gen:
+            continue
+        try:
+            logger.info("Requesting %s for '%s'...", label, episode_title)
+            tasks[label] = await _request_chapter_artifact(
+                client, notebook_id, label, source_ids, instructions[label]
+            )
+        except Exception as e:
+            logger.error("Failed to request %s: %s", label, e)
+    return tasks
+
+
+async def poll_chunk_status(
+    client: NotebookLMClient,
+    notebook_id: str,
+    tasks: dict[str, str],
+) -> dict[str, str]:
+    """Single poll of artifact generation status. Returns {label: status_str}.
+
+    Args:
+        client: An open NotebookLM client.
+        notebook_id: The notebook ID.
+        tasks: Mapping of label -> task_id.
+
+    Returns:
+        Mapping of label -> status string ("completed", "failed", "in_progress", "pending").
+    """
+    results: dict[str, str] = {}
+    for label, task_id in tasks.items():
+        try:
+            status = await client.artifacts.poll_status(notebook_id, task_id)
+            if status.is_complete:
+                results[label] = "completed"
+            elif status.is_failed:
+                results[label] = "failed"
+            elif status.is_in_progress:
+                results[label] = "in_progress"
+            else:
+                results[label] = "pending"
+        except Exception as e:
+            logger.warning("Poll error for %s: %s", label, e)
+            results[label] = "unknown"
+    return results

studyctl/content/splitter.py

@@ -0,0 +1,159 @@
+"""PDF splitting module using PyMuPDF.
+
+Splits a PDF into per-chapter files based on its Table of Contents
+bookmarks. Requires pymupdf (install via studyctl[content] extra).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING
+
+import pymupdf
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def sanitize_filename(name: str) -> str:
+    """Clean a chapter title for use as a filename.
+
+    Removes special characters, replaces whitespace with underscores,
+    truncates to 80 characters, and lowercases the result.
+    """
+    name = re.sub(r"[^\w\s-]", "", name)
+    name = re.sub(r"[\s]+", "_", name.strip())
+    return name[:80].strip("_").lower()
+
+
+def split_pdf_by_chapters(
+    input_path: Path,
+    output_dir: Path,
+    book_name: str,
+    level: int = 1,
+) -> list[Path]:
+    """Split a PDF into per-chapter files based on its TOC bookmarks.
+
+    Args:
+        input_path: Path to the source PDF.
+        output_dir: Directory to write chapter PDFs into.
+        book_name: Base name used in output filenames.
+        level: TOC depth level to split on (1 = top-level chapters).
+
+    Returns:
+        List of paths to the generated chapter PDF files.
+
+    Raises:
+        ValueError: If the PDF contains no TOC / bookmarks.
+    """
+    with pymupdf.open(input_path) as doc:
+        toc = doc.get_toc()
+
+        if not toc:
+            raise ValueError(
+                f"'{input_path.name}' has no bookmarks/TOC. Cannot split without chapter markers."
+            )
+
+        # Filter to requested level entries: each entry is [level, title, page]
+        chapters = [(title, page) for lvl, title, page in toc if lvl == level]
+
+        if not chapters:
+            raise ValueError(
+                f"No TOC entries at level {level}. Available levels: {sorted({e[0] for e in toc})}"
+            )
+
+        output_dir = output_dir.resolve()
+        output_dir.mkdir(parents=True, exist_ok=True)
+        total_pages = doc.page_count
+        output_paths: list[Path] = []
+
+        logger.info(
+            "Splitting '%s' into %d chapters (level %d)",
+            input_path.name,
+            len(chapters),
+            level,
+        )
+
+        for i, (title, start_page) in enumerate(chapters):
+            start = start_page - 1  # TOC pages are 1-indexed
+            end = chapters[i + 1][1] - 2 if i + 1 < len(chapters) else total_pages - 1
+
+            safe_title = sanitize_filename(title)
+            filename = f"{book_name}_chapter_{i + 1:02d}_{safe_title}.pdf"
+            out_path = output_dir / filename
+
+            with pymupdf.open() as chapter_doc:
+                chapter_doc.insert_pdf(doc, from_page=start, to_page=end)
+
+                # Rebuild TOC for this chunk
+                chunk_toc = [
+                    [lvl, t, p - start_page + 1] for lvl, t, p in toc if start_page <= p <= end + 1
+                ]
+                if chunk_toc:
+                    min_lvl = min(entry[0] for entry in chunk_toc)
+                    if min_lvl > 1:
+                        chunk_toc = [[lvl - min_lvl + 1, t, p] for lvl, t, p in chunk_toc]
+                    chapter_doc.set_toc(chunk_toc)
+
+                chapter_doc.ez_save(str(out_path))
+            output_paths.append(out_path)
+
+            logger.info(
+                "Chapter %02d: %s (pages %d-%d)",
+                i + 1,
+                title,
+                start + 1,
+                end + 1,
+            )
+
+    logger.info("%d files written to %s", len(output_paths), output_dir)
+    return output_paths
+
+
+def split_pdf_by_ranges(
+    input_path: Path,
+    output_dir: Path,
+    book_name: str,
+    ranges: str,
+) -> list[Path]:
+    """Split a PDF by explicit page ranges (for PDFs without TOC).
+
+    Args:
+        input_path: Path to the source PDF.
+        output_dir: Directory to write chapter PDFs into.
+        book_name: Base name used in output filenames.
+        ranges: Comma-separated page ranges, e.g. "1-30,31-60,61-90".
+
+    Returns:
+        List of paths to the generated chapter PDF files.
+    """
+    output_dir = output_dir.resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_paths: list[Path] = []
+
+    with pymupdf.open(input_path) as doc:
+        for i, range_str in enumerate(ranges.split(",")):
+            range_str = range_str.strip()
+            if "-" in range_str:
+                start_s, end_s = range_str.split("-", 1)
+                start = int(start_s) - 1
+                end = min(int(end_s) - 1, doc.page_count - 1)
+            else:
+                start = int(range_str) - 1
+                end = start
+
+            filename = f"{book_name}_part_{i + 1:02d}.pdf"
+            out_path = output_dir / filename
+
+            with pymupdf.open() as chapter_doc:
+                chapter_doc.insert_pdf(doc, from_page=start, to_page=end)
+                chapter_doc.ez_save(str(out_path))
+
+            output_paths.append(out_path)
+            logger.info("Part %02d: pages %d-%d", i + 1, start + 1, end + 1)
+
+    logger.info("%d files written to %s", len(output_paths), output_dir)
+    return output_paths

studyctl/content/storage.py

@@ -0,0 +1,105 @@
+"""Course-centric storage management.
+
+Each course has a directory under ``content.base_path`` with a standard
+subdirectory layout for chapters, audio, flashcards, quizzes, video,
+and slides. A ``metadata.json`` file tracks notebook IDs, syllabus
+state, and generation history.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+COURSE_SUBDIRS = ("chapters", "audio", "flashcards", "quizzes", "video", "slides")
+
+
+def get_course_dir(base_path: Path, slug: str) -> Path:
+    """Return course directory, creating subdirs if needed."""
+    course_dir = base_path / slug
+    for subdir in COURSE_SUBDIRS:
+        (course_dir / subdir).mkdir(parents=True, exist_ok=True)
+    return course_dir
+
+
+def slugify(title: str) -> str:
+    """Convert a book/course title to a filesystem-safe slug."""
+    slug = title.lower().strip()
+    slug = re.sub(r"[^\w\s-]", "", slug)
+    slug = re.sub(r"[\s_]+", "-", slug)
+    return slug[:60].strip("-")
+
+
+def list_courses(base_path: Path) -> list[dict]:
+    """List all courses under the base path.
+
+    Returns a list of dicts with keys: slug, path, metadata.
+    """
+    if not base_path.is_dir():
+        return []
+
+    courses = []
+    for child in sorted(base_path.iterdir()):
+        if not child.is_dir() or child.name.startswith("."):
+            continue
+        meta = load_course_metadata(child)
+        courses.append(
+            {
+                "slug": child.name,
+                "path": child,
+                "metadata": meta,
+            }
+        )
+    return courses
+
+
+def load_course_metadata(course_dir: Path) -> dict:
+    """Load metadata.json (notebook IDs, syllabus state, generation history)."""
+    meta_path = course_dir / "metadata.json"
+    if not meta_path.exists():
+        return {}
+    try:
+        return json.loads(meta_path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Failed to read %s: %s", meta_path, exc)
+        return {}
+
+
+def save_course_metadata(course_dir: Path, metadata: dict) -> None:
+    """Save metadata.json atomically (write to .tmp, rename)."""
+    meta_path = course_dir / "metadata.json"
+    course_dir.mkdir(parents=True, exist_ok=True)
+
+    # Atomic write: write to temp file in same dir, then rename
+    fd, tmp_path = tempfile.mkstemp(dir=course_dir, prefix=".metadata-", suffix=".tmp")
+    try:
+        tmp = Path(tmp_path)
+        tmp.write_text(json.dumps(metadata, indent=2, default=str))
+        tmp.replace(meta_path)
+    except Exception:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise
+    finally:
+        import os
+
+        os.close(fd)
+
+
+def check_content_dependencies() -> list[str]:
+    """Check pandoc, mmdc, typst availability.
+
+    Returns list of missing tools with install instructions.
+    """
+    import shutil
+
+    missing = []
+    if not shutil.which("pandoc"):
+        missing.append("pandoc (install: brew install pandoc)")
+    if not shutil.which("mmdc"):
+        missing.append("mmdc / mermaid-cli (install: npm install -g @mermaid-js/mermaid-cli)")
+    return missing