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/_onetime_retarget_cassette_hosts.py

View on GitHub
"""One-time: retarget recorded request hosts onto the post-rebrand host (#2067).

#2067 moved the default base host from ``notebooklm.google.com`` to
``notebook.google.com``. The VCR cassettes were recorded against the old
default and match on host, so every integration test would replay-miss.

**Why rewrite rather than re-record.** Google dual-serves ``batchexecute`` on
both hosts (ADR-0028), so a re-recording would differ from these fixtures only
in the host field -- at the cost of hundreds of fresh network round-trips,
fresh scrubbing, and a diff no reviewer could check. Rewriting the one field
that actually changed keeps the diff readable and the evidence intact.

**What it does not touch.** Only the *request* side is rewritten: ``uri`` and
the ``host`` / ``origin`` / ``referer`` request headers. Response bodies keep
every ``notebooklm.google.com`` they were recorded with -- those bytes are
Google's own HTML and rewriting them would fabricate content Google never sent.
Leaving them is not sloppiness; it is what dual-serving genuinely looks like on
the wire. The script hashes every response block before and after and refuses
to write if one changed.

**Two interaction-scoped skips**, both preserving real recorded behaviour:

* **3xx interactions** -- these record the legacy host redirecting *to* the
  rebrand host. Rewriting the request would fabricate a self-redirect.
* **Upload interactions carrying ``upload_id=``** -- these endpoints are
  server-directed: the client reads ``X-Goog-Upload-URL`` out of the *response*
  and derives its follow-up URL and ``Origin`` from it
  (``_upload_decode.py``, ``upload_payloads.py``). They stay on whatever host
  the recorded response named, so the uri/host/origin/referer of such an
  interaction must move together or not at all -- here, not at all.

Idempotent and re-runnable. Parses with PyYAML to *decide*, splices raw lines to
*apply*: a ``safe_dump`` round-trip would reflow the whole corpus into an
unreviewable diff.

Usage::

    python scripts/_onetime_retarget_cassette_hosts.py [--apply]

Defaults to a dry run that reports per-category and per-skip-reason counts.
"""

from __future__ import annotations

import argparse
import hashlib
import re
import sys
from collections import Counter
from pathlib import Path
from typing import Any

import yaml

PROJECT_ROOT = Path(__file__).resolve().parents[1]

# Deliberately non-recursive. The recursive glob pulls in
# ``gzip_coverage/artifacts_revise_slide_gzipped.yaml``, whose test hardcodes
# the legacy URL and matches on host -- cassette and test are a coupled,
# self-consistent pair. Rewriting one without the other breaks it.
CASSETTE_GLOB = "tests/cassettes/web/*.yaml"

LEGACY_HOST = "notebooklm.google.com"
REBRAND_HOST = "notebook.google.com"

# Request headers whose value names the host the client chose.
HOST_HEADERS = frozenset({"host", "origin", "referer"})


def _response_digest(doc: Any) -> str:
    """Return a digest over every ``response`` block in a parsed cassette."""
    hasher = hashlib.sha256()
    for interaction in (doc or {}).get("interactions") or []:
        hasher.update(repr(interaction.get("response")).encode("utf-8"))
    return hasher.hexdigest()


def _is_redirect(interaction: dict[str, Any]) -> bool:
    status = (interaction.get("response") or {}).get("status") or {}
    code = status.get("code") if isinstance(status, dict) else None
    return isinstance(code, int) and 300 <= code < 400


def _is_server_directed_upload(interaction: dict[str, Any]) -> bool:
    """True when the endpoint was handed to the client by a prior response."""
    return "upload_id=" in str((interaction.get("request") or {}).get("uri") or "")


def _line_span(lines: list[str], start: int) -> int:
    """Return the index one past the ``- request:`` block beginning at ``start``."""
    for index in range(start + 1, len(lines)):
        if lines[index].startswith("- ") or (
            lines[index].strip() and not lines[index].startswith(" ")
        ):
            return index
    return len(lines)


def _rewrite_request_lines(lines: list[str]) -> tuple[list[str], Counter]:
    """Rewrite host-bearing request lines in one ``- request:`` block."""
    counts: Counter = Counter()
    out: list[str] = []
    header_key: str | None = None
    in_response = False

    for line in lines:
        # Track which half of the interaction we are in. ``response:`` sits at
        # the same indent as ``request:`` inside an interaction.
        if re.match(r"^\s{2}response:\s*$", line):
            in_response = True
        elif re.match(r"^\s{2}request:\s*$", line):
            in_response = False

        # Track the enclosing key *before* any early exit: header values are
        # YAML sequence items on their own lines ("host:" then
        # "- notebooklm.google.com"), so the line that names the key never
        # contains the host itself.
        key_match = re.match(r"^\s*([A-Za-z0-9_-]+):\s*(.*)$", line)
        if key_match:
            header_key = key_match.group(1).lower()

        if in_response or LEGACY_HOST not in line:
            out.append(line)
            continue

        if key_match and key_match.group(1).lower() == "uri":
            out.append(line.replace(LEGACY_HOST, REBRAND_HOST))
            counts["uri"] += 1
        elif header_key in HOST_HEADERS:
            # Header values are YAML sequence items on their own lines.
            out.append(line.replace(LEGACY_HOST, REBRAND_HOST))
            counts[header_key] += 1
        else:
            out.append(line)

    return out, counts


def process(path: Path, apply: bool) -> Counter:
    raw = path.read_text(encoding="utf-8")
    doc = yaml.safe_load(raw)
    before_digest = _response_digest(doc)

    interactions = (doc or {}).get("interactions") or []
    skip_flags = [
        "redirect"
        if _is_redirect(i)
        else ("server_directed_upload" if _is_server_directed_upload(i) else None)
        for i in interactions
    ]

    lines = raw.splitlines(keepends=True)
    starts = [n for n, line in enumerate(lines) if line.startswith("- request:")]
    if len(starts) != len(interactions):
        raise AssertionError(
            f"{path}: parsed {len(interactions)} interactions but found "
            f"{len(starts)} '- request:' anchors; refusing to splice"
        )

    counts: Counter = Counter()
    out: list[str] = lines[: starts[0]] if starts else lines
    for index, start in enumerate(starts):
        end = _line_span(lines, start)
        block = lines[start:end]
        reason = skip_flags[index]
        if reason:
            counts[f"skipped_{reason}"] += 1
            out.extend(block)
        else:
            rewritten, block_counts = _rewrite_request_lines(block)
            counts.update(block_counts)
            out.extend(rewritten)

    # Everything after the final interaction -- notably the top-level
    # ``version: 1`` key, which VCR requires and which sits outside every
    # ``- request:`` span. Dropping it silently corrupts the cassette in a way
    # the response digest cannot see, because it is not a response block.
    if starts:
        out.extend(lines[_line_span(lines, starts[-1]) :])

    new_raw = "".join(out)
    if new_raw != raw:
        counts["files_changed"] += 1
        after = yaml.safe_load(new_raw)
        if _response_digest(after) != before_digest:
            raise AssertionError(f"{path}: response bytes changed -- refusing to write")
        if set((after or {}).keys()) != set((doc or {}).keys()):
            raise AssertionError(
                f"{path}: top-level keys changed "
                f"{sorted((doc or {}).keys())} -> {sorted((after or {}).keys())}"
            )
        if len((after or {}).get("interactions") or []) != len(interactions):
            raise AssertionError(f"{path}: interaction count changed -- refusing to write")
        if apply:
            path.write_text(new_raw, encoding="utf-8")
    return counts


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--apply", action="store_true", help="write changes (default: dry run)")
    args = parser.parse_args()

    paths = sorted(PROJECT_ROOT.glob(CASSETTE_GLOB))
    totals: Counter = Counter()
    for path in paths:
        totals.update(process(path, args.apply))

    mode = "APPLIED" if args.apply else "DRY RUN"
    print(f"[{mode}] cassettes scanned: {len(paths)}")
    for key in sorted(totals):
        print(f"  {key}: {totals[key]}")
    rewritten = sum(v for k, v in totals.items() if not k.startswith(("skipped_", "files_")))
    print(f"  total lines rewritten: {rewritten}")
    return 0


if __name__ == "__main__":
    sys.exit(main())
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