Skip to content

teng-lin/notebooklm-py

notebooklm

Verified

Install, authenticate, troubleshoot, and operate Gemini Notebook through the notebooklm-py CLI or typed async Python API. Use for notebook and source management, grounded chat and research, and artifact generation or download when the user mentions Gemini Notebook, notebooklm-py, the notebooklm CLI, or its Python API. Do not use for the generic Gemini API or unrelated content creation.

FileKindSize
SKILL.mdskill md16.0 KB
examples/bulk-import.pyscript3.4 KB
examples/chat.pyscript6.9 KB
examples/notes.pyscript9.8 KB
examples/quickstart.pyscript2.3 KB
examples/refresh_browser_cookies.pyscript2.9 KB
examples/research-to-podcast.pyscript3.2 KB
examples/video.pyscript5.9 KB
scripts/__init__.pyscript73 B
scripts/_ci_e2e_notebooks.pyscript19.0 KB
scripts/_ci_progress.pyscript2.5 KB
scripts/_ci_rpc_progress.pyscript7.5 KB
scripts/_live_auth_scenarios/__init__.pyscript2.6 KB
scripts/_live_auth_scenarios/_contract.pyscript1.9 KB
scripts/_live_auth_scenarios/browser_refresh.pyscript3.1 KB
scripts/_live_auth_scenarios/crash_safe_writer.pyscript1.9 KB
scripts/_live_auth_scenarios/master_token_recovery.pyscript3.3 KB
scripts/_live_auth_scenarios/mcp_recovery.pyscript3.0 KB
scripts/_live_auth_scenarios/rest_recovery.pyscript5.9 KB
scripts/_live_auth_scenarios/sibling_concurrent_reload.pyscript3.9 KB
scripts/_live_auth_scenarios/storage_reload.pyscript2.9 KB
scripts/_onetime_rescrub_cookies.pyscript6.6 KB
scripts/_onetime_retarget_cassette_hosts.pyscript8.5 KB
scripts/_strip_audit_refs.pyscript15.9 KB
scripts/_tracked_files.pyscript872 B
scripts/aggregate_ci_e2e_outcomes.pyscript10.8 KB
scripts/android_grpc_canary.pyscript26.6 KB
scripts/api-compat-allowlist.jsonconfig163 B
scripts/audit_auth_import_graph.pyscript7.5 KB
scripts/audit_auth_patch_sites.pyscript83.6 KB
scripts/audit_auth_shared_mutations.pyscript41.7 KB
scripts/audit_backend_coupling.pyscript32.8 KB
scripts/audit_public_api_compat.pyscript47.4 KB
scripts/audit_test_suite.pyscript10.7 KB
scripts/capture_mobile_grpc.jsscript5.1 KB
scripts/capture_rpc_registry.pyscript44.5 KB
scripts/check_action_pinning.pyscript6.7 KB
scripts/check_auth_behavior_scenario_policy.pyscript37.1 KB
scripts/check_auth_coverage_delta.pyscript23.2 KB
scripts/check_auth_lifecycle_cleanup_policy.pyscript11.7 KB
scripts/check_base_wheel.pyscript6.3 KB
scripts/check_ci_install_parity.pyscript8.8 KB
scripts/check_claude_md_freshness.pyscript8.0 KB
scripts/check_coverage_thresholds.pyscript8.4 KB
scripts/check_deprecation_targets.pyscript33.1 KB
scripts/check_docs_module_refs.pyscript14.4 KB
scripts/check_rpc_health.pyscript112.0 KB
scripts/check_workflow_permissions.pyscript5.3 KB
scripts/check_workflow_secret_gates.pyscript40.4 KB
scripts/decode_mobile_grpc.pyscript7.2 KB
scripts/diagnose_get_notebook.pyscript9.1 KB
scripts/extract_blutter_grpc_signatures.pyscript7.6 KB
scripts/live_auth_matrix.pyscript40.2 KB
scripts/manage_ci_e2e_notebooks.pyscript67.4 KB
scripts/materialize_ci_auth.pyscript8.0 KB
scripts/mcp_live_smoke.pyexecutablescript224 B
scripts/parse_pbenums.pyscript8.6 KB
scripts/parse_pbschema.pyscript11.8 KB
scripts/regen_baselines.pyscript2.7 KB
scripts/regenerate_android_protos.pyscript16.3 KB
scripts/rescrub-cassettes.pyscript13.3 KB
scripts/scrub_rpc_har.pyscript9.4 KB
scripts/select_ci_account.pyscript4.8 KB
scripts/stress_fault_server.pyscript20.6 KB
scripts/test_taxonomy_inventory.pyscript16.1 KB
scripts/verify_ci_artifacts.pyscript35.3 KB

scripts/_ci_rpc_progress.py

View on GitHub
"""Live RPC diagnostics on a separate stream from private response reports."""

from __future__ import annotations

import re
import sys
import time
from collections.abc import Awaitable, Callable, Iterator
from contextlib import contextmanager
from contextvars import ContextVar
from datetime import datetime, timezone
from enum import Enum
from functools import wraps
from typing import Any, ParamSpec, TextIO, TypeVar

if __package__:
    from ._ci_progress import open_progress_stream, write_summary
else:
    from _ci_progress import open_progress_stream, write_summary

P = ParamSpec("P")
T = TypeVar("T")

_SKIP_REASONS = {
    "Method always skipped (complex setup or quota)": "complex setup or quota; intentionally not probed",
    "Duplicate method (same ID as another)": "same RPC ID is checked by another method",
    "Requires real resource IDs (placeholder fails)": "requires real resource IDs",
    "Tested in setup/cleanup phases": "handled in setup/cleanup; see those phase results",
    "Requires --full mode (creates/deletes resources)": "requires full mode",
    "No test parameters available": "no safe probe parameters available",
    "No notebook ID provided": "notebook required for this probe",
}


def safe_reason(result: Any, proof: str, detail: str = "") -> str:
    """Classify errors without publishing their bodies or resource handles."""
    status = result.value if isinstance(result, Enum) else result.status.value
    error = getattr(result, "error", None) or getattr(result, "detail", "") or detail
    if status == "SKIPPED":
        return _SKIP_REASONS.get(error, "probe prerequisites unavailable")
    if status == "MISMATCH":
        observed = [
            value
            if isinstance(value, str) and re.fullmatch(r"[A-Za-z0-9]{5,6}", value)
            else "<unexpected ID shape>"
            for value in result.found_ids[:10]
        ]
        return "expected RPC ID absent; observed IDs=" + (", ".join(observed) or "none")
    if "ReadTimeout" in error:
        return "RPC read timeout (transient)"
    if any(
        marker in error
        for marker in (
            "HTTP 429",
            "RateLimitError",
            "API rate limit",
            "Chat rate limit",
            "RESOURCE_EXHAUSTED",
        )
    ):
        return "quota/rate limit (transient)"
    http_status = re.search(r"\bHTTP (\d{3})\b", error)
    if http_status:
        return f"HTTP {int(http_status[1])}; see report"
    for category in ("ConnectTimeout", "WriteTimeout", "PoolTimeout", "ConnectError"):
        if category in error:
            return category
    if "Parse error" in error or "ParseError" in error:
        return "response decoding failed; see report"
    if status == "OK":
        if error:
            return "expected RPC ID observed, but operation rejected; see report"
        return proof
    return {
        "MATCH": "option tables match the checked-in enums",
        "DRIFT": "option-table drift; compare expected/observed values in report",
        "PRESENT": "endpoint response framing recognized",
        "ABSENT": "endpoint unavailable; see report",
        "UNAUTHENTICATED": "authentication rejected",
        "NOT_PROBED": "requires a separate authenticated capture",
        "CURRENT": "build label is current",
        "DRIFTED": "build label changed within the allowed age",
        "STALE": "pinned build label is stale; see report",
        "UNKNOWN": "probe inconclusive; see report",
    }.get(status, "probe failed; see full diagnostic report")


class RPCProgress:
    def __init__(self, stream: TextIO | None) -> None:
        self.stream = stream
        self.phase = "initialization"
        self.rows: list[tuple[str, str, str, float, str]] = []

    def emit(self, message: str) -> None:
        if self.stream is None:
            return
        stamp = datetime.now(timezone.utc).strftime("%H:%M:%S UTC")
        try:
            print(f"[{stamp}] {message}", file=self.stream, flush=True)
        except OSError:
            self.stream = None
            print("WARNING: could not write live RPC progress", file=sys.stderr, flush=True)

    def finish(self, label: str, status: str, started: float, reason: str) -> None:
        elapsed = time.monotonic() - started
        self.rows.append((self.phase, label, status, elapsed, reason))
        self.emit(f"{self.phase}: {status} {label}; elapsed={elapsed:.1f}s; {reason}")

    def summarize(self) -> None:
        write_summary(
            "### RPC probe details\n\n"
            "RPC-ID OK means the expected response ID was observed; live E2E tests check behavior. "
            "Setup/cleanup entries report their own calls. Rebrand probes have a separate verdict.\n\n"
            "| Phase | Probe / RPC ID | Outcome | Seconds | Diagnostic |\n"
            "| --- | --- | --- | ---: | --- |"
        )
        for phase, label, status, elapsed, reason in self.rows:
            write_summary(f"| {phase} | `{label}` | {status} | {elapsed:.1f} | {reason} |")
        if not self.rows:
            write_summary(f"No RPC probe completed; last phase: {self.phase}.")


_ACTIVE: ContextVar[RPCProgress | None] = ContextVar("rpc_progress", default=None)


@contextmanager
def live_progress(fd: int | None) -> Iterator[None]:
    if fd is None:
        yield
        return
    with open_progress_stream(fd) as stream:
        progress = RPCProgress(stream)
        token = _ACTIVE.set(progress)
        try:
            yield
        finally:
            _ACTIVE.reset(token)
            progress.summarize()


def progress_phase(phase: str) -> None:
    progress = _ACTIVE.get()
    if progress is not None:
        progress.phase = phase
        progress.emit(f"RPC phase: {phase}")


def progress_note(message: str) -> None:
    progress = _ACTIVE.get()
    if progress is not None:
        progress.emit(message)


def trace_probe(
    label: str | None = None, *, proof: str = "expected RPC ID observed"
) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
    """Trace a checked result, including setup, inventory reads, and cleanup."""

    def decorate(function: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
        @wraps(function)
        async def wrapped(*args: P.args, **kwargs: P.kwargs) -> T:
            progress = _ACTIVE.get()
            if progress is None:
                return await function(*args, **kwargs)
            name = label
            if name is None:
                method = kwargs.get("method", args[2] if len(args) > 2 else None)
                name = f"RPC-ID {method.name} ({method.value})"
            started = time.monotonic()
            progress.emit(f"{progress.phase}: START {name}")
            try:
                value = await function(*args, **kwargs)
            except BaseException:
                progress.finish(name, "ERROR", started, "probe interrupted or raised; see report")
                raise
            result = value[0] if isinstance(value, tuple) else value
            status = result.value if isinstance(result, Enum) else result.status.value
            # Only enum probes return (status, diagnostic). RPC probes return
            # (CheckResult, payload), whose text is neither an error nor public.
            detail = (
                value[1]
                if isinstance(value, tuple)
                and isinstance(result, Enum)
                and isinstance(value[1], str)
                else ""
            )
            progress.finish(name, status, started, safe_reason(result, proof, detail))
            return value

        return wrapped

    return decorate
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