Skip to content

claude-world/notebooklm-skill

notebooklm-research

Verified

Automate source-grounded research with Google NotebookLM. Create notebooks from URLs, text, or local files; ask cited questions; run fast or deep web research; create articles and social drafts; and generate or download audio, video, cinematic video, slides, reports, study guides, quizzes, flashcards, mind maps, infographics, and data tables. Use when a user asks for NotebookLM, cited source analysis, research-to-content workflows, podcasts, slides, study material, artifact generation, RSS digests, or trend research.

FileKindSize
SKILL.mdskill md7.3 KB
examples/research-to-article/README.mdmarkdown1.9 KB
examples/research-to-threads/README.mdmarkdown1.4 KB
examples/trend-to-content/README.mdmarkdown2.0 KB
references/api_surface.mdmarkdown6.4 KB
references/output_formats.mdmarkdown3.2 KB
references/pipeline_recipes.mdmarkdown3.5 KB
scripts/__init__.pyscript0 B
scripts/auth_helper.pyexecutablescript6.0 KB
scripts/common.pyscript26.5 KB
scripts/make_video.shexecutablescript3.7 KB
scripts/notebooklm_client.pyexecutablescript20.2 KB
scripts/pipeline.pyexecutablescript26.1 KB
scripts/skill_installer.pyexecutablescript4.5 KB

scripts/common.py

View on GitHub
"""Shared NotebookLM operations for the CLI, pipelines, and MCP server.

This module is the compatibility boundary for ``notebooklm-py``.  Keeping API
adaptation here prevents the three public interfaces from drifting apart.
"""

from __future__ import annotations

import asyncio
import json
import os
import shlex
from collections.abc import Mapping, Sequence
from contextlib import asynccontextmanager
from dataclasses import dataclass, fields, is_dataclass
from datetime import date, datetime
from enum import Enum
from pathlib import Path
from typing import Any
from urllib.parse import urlparse

from dotenv import load_dotenv

load_dotenv()


class UsageError(ValueError):
    """Raised when a caller supplies an invalid or ambiguous argument."""


class AuthenticationRequired(RuntimeError):
    """Raised when no usable NotebookLM browser session is available."""


def storage_path(profile: str | None = None) -> Path:
    """Return the active notebooklm-py storage path, including profiles."""
    try:
        from notebooklm.paths import get_storage_path

        return get_storage_path(profile)
    except (ImportError, RuntimeError):
        return Path.home() / ".notebooklm" / "storage_state.json"


def authentication_message() -> str:
    """Return actionable authentication guidance without exposing cookies."""
    return (
        "[AUTH_REQUIRED] NotebookLM authentication is missing or expired. "
        "Run `uvx --from notebooklm-py notebooklm login` (or "
        "`python3 -m notebooklm login` after installation), then retry. "
        f"Active session path: {storage_path()}"
    )


@asynccontextmanager
async def get_client():
    """Yield an authenticated client and normalize authentication failures."""
    from notebooklm import AuthError, AuthExtractionError, NotebookLMClient

    try:
        async with NotebookLMClient.from_storage() as client:
            try:
                yield client
            except (AuthError, AuthExtractionError) as exc:
                raise AuthenticationRequired(authentication_message()) from exc
    except (AuthError, AuthExtractionError) as exc:
        raise AuthenticationRequired(authentication_message()) from exc
    except FileNotFoundError as exc:
        # Do not turn a missing upload file into an authentication error.
        if not storage_path().exists() and not os.getenv("NOTEBOOKLM_AUTH_JSON"):
            raise AuthenticationRequired(authentication_message()) from exc
        raise


def normalize_language(language: str | None) -> str:
    """Normalize common BCP-47 aliases to NotebookLM language identifiers."""
    if not language:
        return "en"
    aliases = {
        "zh-tw": "zh_Hant",
        "zh-hant": "zh_Hant",
        "zh_tw": "zh_Hant",
        "zh-cn": "zh_Hans",
        "zh-hans": "zh_Hans",
        "zh_cn": "zh_Hans",
        "pt-br": "pt_BR",
        "pt-pt": "pt_PT",
        "es-mx": "es_MX",
        "fr-ca": "fr_CA",
    }
    return aliases.get(language.casefold(), language)


def serialize(value: Any) -> Any:
    """Convert typed notebooklm-py results to JSON-compatible values."""
    if value is None or isinstance(value, (str, int, float, bool)):
        return value
    if isinstance(value, Enum):
        return serialize(value.value)
    if isinstance(value, (Path, date, datetime)):
        return value.isoformat() if hasattr(value, "isoformat") else str(value)
    if isinstance(value, Mapping):
        return {str(key): serialize(item) for key, item in value.items()}
    if isinstance(value, (list, tuple, set, frozenset)):
        return [serialize(item) for item in value]
    if is_dataclass(value) and not isinstance(value, type):
        return {
            field.name: serialize(getattr(value, field.name))
            for field in fields(value)
            if not field.name.startswith("_")
        }
    if hasattr(value, "__dict__"):
        return {key: serialize(item) for key, item in vars(value).items() if not key.startswith("_")}
    return str(value)


def serialize_notebook(notebook: Any) -> dict[str, Any]:
    """Serialize stable, useful notebook metadata."""
    result = {"id": notebook.id, "title": getattr(notebook, "title", "")}
    for attribute in ("created_at", "sources_count", "is_owner"):
        value = getattr(notebook, attribute, None)
        if value is not None:
            result[attribute] = serialize(value)
    return result


def serialize_source(source: Any) -> dict[str, Any]:
    """Serialize a source using the current ``kind`` API."""
    result = {"id": getattr(source, "id", None)}
    for attribute in ("title", "url", "kind", "status", "created_at"):
        value = getattr(source, attribute, None)
        if value is not None:
            result[attribute] = serialize(value)
    return result


def serialize_artifact(artifact: Any) -> dict[str, Any]:
    """Serialize artifact metadata without exposing signed download URLs."""
    result = {
        "id": getattr(artifact, "id", None),
        "title": getattr(artifact, "title", ""),
    }
    for attribute in ("kind", "status", "created_at"):
        value = getattr(artifact, attribute, None)
        if value is not None:
            result[attribute] = serialize(value)
    return result


async def resolve_notebook(client: Any, identifier: str) -> Any:
    """Resolve an ID or unique title/substring to a notebook object."""
    query = identifier.strip()
    if not query:
        raise UsageError("Notebook name or ID cannot be empty.")

    notebooks = list(await client.notebooks.list() or [])
    id_matches = [item for item in notebooks if item.id == query]
    if id_matches:
        return id_matches[0]

    folded = query.casefold()
    exact = [item for item in notebooks if item.title.casefold() == folded]
    if len(exact) == 1:
        return exact[0]
    if len(exact) > 1:
        raise UsageError(f"Notebook title '{query}' is ambiguous. Use an ID: " + ", ".join(item.id for item in exact))

    partial = [item for item in notebooks if folded in item.title.casefold()]
    if len(partial) == 1:
        return partial[0]
    if len(partial) > 1:
        choices = ", ".join(f"{item.title} ({item.id})" for item in partial[:10])
        raise UsageError(f"Notebook '{query}' is ambiguous. Matches: {choices}")
    raise UsageError(f"Notebook '{query}' was not found.")


def validate_url(url: str) -> str:
    """Validate a web/YouTube source URL."""
    candidate = url.strip()
    parsed = urlparse(candidate)
    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
        raise UsageError(f"Invalid source URL: {url!r}")
    return candidate


async def fetch_trends(geo: str, count: int) -> list[dict[str, Any]]:
    """Fetch and normalize trend-pulse JSON without invoking a shell or npx."""
    if not 1 <= count <= 20:
        raise UsageError("Trend count must be between 1 and 20.")
    command = shlex.split(os.getenv("TREND_PULSE_CMD", "trend-pulse"))
    if not command:
        raise UsageError("TREND_PULSE_CMD cannot be empty.")
    try:
        process = await asyncio.create_subprocess_exec(
            *command,
            "trending",
            "--geo",
            geo,
            "--count",
            str(count),
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=60)
    except FileNotFoundError as exc:
        raise RuntimeError("trend-pulse is not installed. Install it or set TREND_PULSE_CMD.") from exc
    except TimeoutError as exc:
        raise RuntimeError("trend-pulse timed out after 60 seconds.") from exc
    if process.returncode != 0:
        detail = stderr.decode(errors="replace").strip()[:300]
        raise RuntimeError(f"trend-pulse failed: {detail or f'exit {process.returncode}'}")
    try:
        payload = json.loads(stdout)
    except json.JSONDecodeError as exc:
        raise RuntimeError("trend-pulse returned invalid JSON.") from exc
    if isinstance(payload, dict):
        payload = payload.get("merged") or payload.get("trends") or payload.get("items") or []
    if not isinstance(payload, list):
        raise RuntimeError("trend-pulse JSON must contain a list of trends.")

    trends: list[dict[str, Any]] = []
    for item in payload:
        if isinstance(item, str):
            normalized = {"title": item}
        elif isinstance(item, dict):
            normalized = dict(item)
            normalized["title"] = (
                item.get("title") or item.get("keyword") or item.get("name") or item.get("query") or ""
            )
        else:
            continue
        if str(normalized["title"]).strip():
            normalized["title"] = str(normalized["title"]).strip()
            trends.append(normalized)
    return trends[:count]


async def fetch_rss_entries(
    url: str, *, max_entries: int = 20, timeout: float = 30, max_bytes: int = 5_000_000
) -> list[dict[str, str]]:
    """Fetch an HTTP(S) RSS/Atom feed with time and size limits."""
    if not 1 <= max_entries <= 100:
        raise UsageError("RSS max entries must be between 1 and 100.")
    if timeout <= 0 or max_bytes <= 0:
        raise UsageError("RSS timeout and maximum bytes must be positive.")
    feed_url = validate_url(url)
    try:
        import feedparser
        import httpx
    except ImportError as exc:
        raise RuntimeError("RSS support requires feedparser and httpx.") from exc

    chunks: list[bytes] = []
    received = 0
    async with httpx.AsyncClient(follow_redirects=True, timeout=timeout) as http:
        async with http.stream("GET", feed_url) as response:
            response.raise_for_status()
            async for chunk in response.aiter_bytes():
                received += len(chunk)
                if received > max_bytes:
                    raise RuntimeError(f"RSS feed exceeds the {max_bytes}-byte safety limit.")
                chunks.append(chunk)
    parsed = feedparser.parse(b"".join(chunks))
    if getattr(parsed, "bozo", False) and not getattr(parsed, "entries", None):
        detail = getattr(parsed, "bozo_exception", "unknown parse error")
        raise RuntimeError(f"RSS feed could not be parsed: {detail}")
    entries: list[dict[str, str]] = []
    for entry in list(getattr(parsed, "entries", ()))[:max_entries]:
        entries.append(
            {
                "title": str(getattr(entry, "title", "Untitled")),
                "link": str(getattr(entry, "link", "")),
                "summary": str(getattr(entry, "summary", ""))[:2000],
                "published": str(getattr(entry, "published", "")),
            }
        )
    return entries


async def ingest_sources(
    client: Any,
    notebook_id: str,
    *,
    urls: Sequence[str] = (),
    texts: Sequence[str] = (),
    files: Sequence[str | Path] = (),
    wait_timeout: float = 180,
    concurrency: int = 4,
) -> list[dict[str, Any]]:
    """Add mixed sources concurrently while preserving result order."""
    if concurrency < 1:
        raise UsageError("Source concurrency must be at least 1.")
    if wait_timeout <= 0:
        raise UsageError("Source timeout must be positive.")

    jobs: list[tuple[str, str, Any]] = []
    for url in urls:
        jobs.append(("url", url, validate_url(url)))
    for index, text in enumerate(texts, 1):
        if not text.strip():
            raise UsageError(f"Text source {index} cannot be empty.")
        jobs.append(("text", f"Text Source {index}", text))
    for raw_path in files:
        path = Path(raw_path).expanduser()
        jobs.append(("file", str(path), path))

    semaphore = asyncio.Semaphore(concurrency)

    async def add_one(source_type: str, label: str, payload: Any) -> dict[str, Any]:
        async with semaphore:
            try:
                if source_type == "url":
                    source = await client.sources.add_url(notebook_id, payload, wait=True, wait_timeout=wait_timeout)
                elif source_type == "text":
                    source = await client.sources.add_text(
                        notebook_id,
                        title=label,
                        content=payload,
                        wait=True,
                        wait_timeout=wait_timeout,
                    )
                else:
                    if not payload.is_file():
                        raise FileNotFoundError(f"Source file not found: {payload}")
                    source = await client.sources.add_file(
                        notebook_id,
                        file_path=payload,
                        wait=True,
                        wait_timeout=wait_timeout,
                    )
                return {
                    "status": "ok",
                    "source_type": source_type,
                    "input": label,
                    "source": serialize_source(source),
                }
            except Exception as exc:
                return {
                    "status": "failed",
                    "source_type": source_type,
                    "input": label,
                    "error": str(exc),
                }

    return await asyncio.gather(*(add_one(*job) for job in jobs))


def source_result_summary(results: Sequence[Mapping[str, Any]]) -> dict[str, int]:
    """Count successful and failed source ingestion attempts."""
    succeeded = sum(item.get("status") == "ok" for item in results)
    return {
        "requested": len(results),
        "succeeded": succeeded,
        "failed": len(results) - succeeded,
    }


@dataclass(frozen=True)
class ArtifactSpec:
    """Canonical artifact behavior shared by every interface."""

    generator: str
    downloader: str
    extension: str
    language: bool = True
    instructions_parameter: str | None = "instructions"
    immediate: bool = False
    output_formats: tuple[str, ...] = ()
    timeout: float = 1800


ARTIFACT_SPECS: dict[str, ArtifactSpec] = {
    "audio": ArtifactSpec("generate_audio", "download_audio", "m4a", timeout=1800),
    "video": ArtifactSpec("generate_video", "download_video", "mp4", timeout=3600),
    "cinematic": ArtifactSpec("generate_cinematic_video", "download_video", "mp4", timeout=3600),
    "slides": ArtifactSpec(
        "generate_slide_deck",
        "download_slide_deck",
        "pdf",
        output_formats=("pdf", "pptx"),
    ),
    "report": ArtifactSpec("generate_report", "download_report", "md", instructions_parameter="extra_instructions"),
    "study-guide": ArtifactSpec(
        "generate_study_guide",
        "download_report",
        "md",
        instructions_parameter="extra_instructions",
    ),
    "quiz": ArtifactSpec(
        "generate_quiz",
        "download_quiz",
        "json",
        language=False,
        output_formats=("json", "markdown", "html"),
    ),
    "flashcards": ArtifactSpec(
        "generate_flashcards",
        "download_flashcards",
        "json",
        language=False,
        output_formats=("json", "markdown", "html"),
    ),
    "mind-map": ArtifactSpec("generate_mind_map", "download_mind_map", "json", immediate=True),
    "infographic": ArtifactSpec("generate_infographic", "download_infographic", "png", timeout=2400),
    "data-table": ArtifactSpec("generate_data_table", "download_data_table", "csv"),
}


_GENERATION_OPTIONS: dict[str, dict[str, tuple[str | None, str]]] = {
    "audio": {
        "audio_format": ("AudioFormat", "audio_format"),
        "audio_length": ("AudioLength", "audio_length"),
    },
    "video": {
        "video_format": ("VideoFormat", "video_format"),
        "video_style": ("VideoStyle", "video_style"),
        "style_prompt": (None, "style_prompt"),
    },
    "slides": {
        "slide_format": ("SlideDeckFormat", "slide_format"),
        "slide_length": ("SlideDeckLength", "slide_length"),
    },
    "report": {
        "report_format": ("ReportFormat", "report_format"),
        "custom_prompt": (None, "custom_prompt"),
    },
    "quiz": {
        "quantity": ("QuizQuantity", "quantity"),
        "difficulty": ("QuizDifficulty", "difficulty"),
    },
    "flashcards": {
        "quantity": ("QuizQuantity", "quantity"),
        "difficulty": ("QuizDifficulty", "difficulty"),
    },
    "infographic": {
        "orientation": ("InfographicOrientation", "orientation"),
        "detail_level": ("InfographicDetail", "detail_level"),
        "style": ("InfographicStyle", "style"),
    },
}


def _enum_option(enum_name: str, raw_value: str) -> Any:
    import notebooklm

    enum_type = getattr(notebooklm, enum_name)
    normalized = raw_value.strip().casefold().replace("-", "_")
    for member in enum_type:
        if member.name.casefold() == normalized:
            return member
        if isinstance(member.value, str) and member.value.casefold() == normalized:
            return member
    choices = ", ".join(member.name.casefold().replace("_", "-") for member in enum_type)
    raise UsageError(f"Invalid {enum_name} value '{raw_value}'. Choose: {choices}")


def build_generation_kwargs(
    artifact_type: str,
    *,
    language: str = "en",
    instructions: str | None = None,
    source_ids: Sequence[str] | None = None,
    options: Mapping[str, str | None] | None = None,
) -> dict[str, Any]:
    """Build validated notebooklm-py generation keyword arguments."""
    spec = ARTIFACT_SPECS.get(artifact_type)
    if spec is None:
        raise UsageError(f"Unknown artifact type '{artifact_type}'. Supported: " + ", ".join(ARTIFACT_SPECS))

    kwargs: dict[str, Any] = {}
    if source_ids:
        kwargs["source_ids"] = list(source_ids)
    if spec.language:
        kwargs["language"] = normalize_language(language)
    if instructions and spec.instructions_parameter:
        kwargs[spec.instructions_parameter] = instructions

    supplied = {key: value for key, value in (options or {}).items() if value is not None}
    rules = _GENERATION_OPTIONS.get(artifact_type, {})
    unsupported = sorted(set(supplied) - set(rules))
    if unsupported:
        raise UsageError(f"Options not supported for {artifact_type}: {', '.join(unsupported)}")
    for option_name, raw_value in supplied.items():
        enum_name, api_name = rules[option_name]
        assert raw_value is not None
        kwargs[api_name] = _enum_option(enum_name, raw_value) if enum_name else raw_value

    report_format = kwargs.get("report_format")
    if report_format is not None and getattr(report_format, "name", "") == "CUSTOM":
        if not kwargs.get("custom_prompt"):
            raise UsageError("--custom-prompt is required for a custom report.")
    video_style = kwargs.get("video_style")
    style_prompt = kwargs.get("style_prompt")
    if video_style is not None and getattr(video_style, "name", "") == "CUSTOM":
        if not style_prompt or not str(style_prompt).strip():
            raise UsageError("--style-prompt is required for a custom video style.")
    elif style_prompt:
        raise UsageError("--style-prompt requires --video-style custom.")
    video_format = kwargs.get("video_format")
    if video_format is not None and getattr(video_format, "name", "") == "CINEMATIC" and style_prompt:
        raise UsageError("A cinematic video does not support --style-prompt.")
    if video_format is not None and getattr(video_format, "name", "") == "SHORT":
        if style_prompt or getattr(video_style, "name", "AUTO_SELECT") != "AUTO_SELECT":
            raise UsageError("A short video has a fixed style; --video-style and --style-prompt are not supported.")
    return kwargs


def serialize_generation_status(status: Any) -> dict[str, Any]:
    """Serialize a generation status without its signed URL."""
    return {
        key: serialize(getattr(status, key))
        for key in ("task_id", "status", "error", "error_code", "metadata")
        if getattr(status, key, None) is not None
    }


async def generate_artifact(
    client: Any,
    notebook_id: str,
    artifact_type: str,
    *,
    language: str = "en",
    instructions: str | None = None,
    source_ids: Sequence[str] | None = None,
    options: Mapping[str, str | None] | None = None,
    wait: bool = True,
    timeout: float | None = None,
) -> dict[str, Any]:
    """Generate an artifact and optionally wait for terminal completion."""
    spec = ARTIFACT_SPECS.get(artifact_type)
    if spec is None:
        raise UsageError(f"Unknown artifact type '{artifact_type}'.")
    if timeout is not None and timeout <= 0:
        raise UsageError("Artifact timeout must be positive.")

    method = getattr(client.artifacts, spec.generator)
    kwargs = build_generation_kwargs(
        artifact_type,
        language=language,
        instructions=instructions,
        source_ids=source_ids,
        options=options,
    )
    started = await method(notebook_id, **kwargs)
    if spec.immediate:
        return {
            "status": "ok",
            "state": "completed",
            "artifact_type": artifact_type,
            "result": serialize(started),
        }

    task_id = getattr(started, "task_id", None)
    if not task_id:
        message = getattr(started, "error", None) or "NotebookLM did not create a task."
        raise RuntimeError(f"Failed to generate {artifact_type}: {message}")
    result = {
        "status": "started" if not wait else "ok",
        "state": serialize(getattr(started, "status", "in_progress")),
        "artifact_type": artifact_type,
        "task_id": task_id,
    }
    if not wait:
        return result

    final = await client.artifacts.wait_for_completion(notebook_id, task_id, timeout=timeout or spec.timeout)
    final_state = str(getattr(final, "status", "")).casefold()
    if final_state != "completed":
        message = getattr(final, "error", None) or f"terminal state: {final_state or 'unknown'}"
        raise RuntimeError(f"{artifact_type} generation failed: {message}")
    result["state"] = "completed"
    result["result"] = serialize_generation_status(final)
    return result


def check_output_path(output_path: str | Path, *, force: bool = False) -> Path:
    """Validate a download path without touching the filesystem."""
    path = Path(output_path).expanduser()
    if path.is_symlink():
        raise UsageError(f"Refusing to write through a symlink: {path}")
    if path.is_dir():
        raise UsageError(f"Output path is a directory: {path}")
    if path.exists() and not force:
        raise UsageError(f"Output already exists: {path}. Pass --force to overwrite it.")
    return path


def prepare_output_path(output_path: str | Path, *, force: bool = False) -> Path:
    """Validate a download path and create its parent directory."""
    path = check_output_path(output_path, force=force)
    path.parent.mkdir(parents=True, exist_ok=True)
    return path


def validate_download(
    artifact_type: str,
    output_path: str | Path,
    *,
    output_format: str | None = None,
    force: bool = False,
) -> ArtifactSpec:
    """Validate a download request, so callers can fail before long generations."""
    spec = ARTIFACT_SPECS.get(artifact_type)
    if spec is None:
        raise UsageError(f"Unknown artifact type '{artifact_type}'.")
    if output_format and output_format not in spec.output_formats:
        choices = ", ".join(spec.output_formats) or "none"
        raise UsageError(f"Output format '{output_format}' is not valid for {artifact_type}. Choices: {choices}")
    check_output_path(output_path, force=force)
    return spec


async def download_artifact(
    client: Any,
    notebook_id: str,
    artifact_type: str,
    output_path: str | Path,
    *,
    artifact_id: str | None = None,
    output_format: str | None = None,
    force: bool = False,
) -> str:
    """Download one artifact with type/format/path validation."""
    spec = validate_download(artifact_type, output_path, output_format=output_format, force=force)
    path = prepare_output_path(output_path, force=force)
    method = getattr(client.artifacts, spec.downloader)
    kwargs: dict[str, Any] = {}
    if artifact_id:
        kwargs["artifact_id"] = artifact_id
    if output_format:
        kwargs["output_format"] = output_format
    downloaded = await method(notebook_id, str(path), **kwargs)
    return str(downloaded)


_ARTIFACT_FILTERS = {
    "audio": "AUDIO",
    "video": "VIDEO",
    "cinematic": "VIDEO",
    "slides": "SLIDE_DECK",
    "report": "REPORT",
    "study-guide": "REPORT",
    "quiz": "QUIZ",
    "flashcards": "FLASHCARDS",
    "mind-map": "MIND_MAP",
    "infographic": "INFOGRAPHIC",
    "data-table": "DATA_TABLE",
}


async def list_artifacts(client: Any, notebook_id: str, artifact_type: str | None = None) -> list[dict[str, Any]]:
    """List actual generated artifacts, optionally filtered by type."""
    filter_value = None
    if artifact_type:
        enum_name = _ARTIFACT_FILTERS.get(artifact_type)
        if not enum_name:
            raise UsageError(f"Unknown artifact type '{artifact_type}'.")
        from notebooklm import ArtifactType

        filter_value = getattr(ArtifactType, enum_name)
    artifacts = await client.artifacts.list(notebook_id, filter_value)
    return [serialize_artifact(item) for item in artifacts]


async def run_research(
    client: Any,
    notebook_id: str,
    query: str,
    *,
    mode: str = "fast",
    wait: bool = True,
    timeout: float = 1800,
    import_results: bool = True,
    max_sources: int = 10,
) -> dict[str, Any]:
    """Start, wait for, and optionally import a NotebookLM research task."""
    if not query.strip():
        raise UsageError("Research query cannot be empty.")
    if mode not in {"fast", "deep"}:
        raise UsageError("Research mode must be 'fast' or 'deep'.")
    if timeout <= 0:
        raise UsageError("Research timeout must be positive.")
    if max_sources < 0:
        raise UsageError("Maximum imported sources cannot be negative.")

    started = await client.research.start(notebook_id, query=query.strip(), source="web", mode=mode)
    task_id = getattr(started, "task_id", None)
    if started is None or not task_id:
        raise RuntimeError("NotebookLM did not create a research task.")
    output: dict[str, Any] = {
        "status": "started" if not wait else "ok",
        "task_id": task_id,
        "mode": mode,
        "query": query.strip(),
    }
    if not wait:
        return output

    final = await client.research.wait_for_completion(notebook_id, task_id=task_id, timeout=timeout)
    state = str(getattr(final, "status", "")).casefold()
    if state != "completed":
        raise RuntimeError(f"Research task ended in state '{state or 'unknown'}'.")

    sources = list(getattr(final, "sources", ()) or ())
    imported: list[Any] = []
    if import_results and max_sources and sources:
        imported = await client.research.import_sources(notebook_id, task_id, sources[:max_sources])
    output.update(
        {
            "state": "completed",
            "result": serialize(final),
            "sources_found": len(sources),
            "sources_imported": len(imported),
            "imported": serialize(imported),
        }
    )
    return output
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall