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

View on GitHub
#!/usr/bin/env python3
"""Materialize one selected CI token and mint a fresh auth profile."""

from __future__ import annotations

import argparse
import os
import random
import re
import stat
import subprocess
import sys
import tempfile
import time
from collections.abc import Callable, Mapping
from pathlib import Path

from notebooklm._logging import scrub_secrets

CONFIGURATION_ERROR = 2
AUTH_ERROR = 3
INFRASTRUCTURE_ERROR = 4
_SLOTS = ("A", "B", "C")
_LANES = (
    "nightly-web-ubuntu",
    "nightly-android-macos",
    "nightly-readonly-windows",
    "rpc-health-web",
    "rpc-health-android",
    "verify-package",
)
_PROFILE_RE = re.compile(
    rf"ci-(?P<slot>[A-C])-(?P<lane>{'|'.join(re.escape(lane) for lane in _LANES)})\Z"
)
MINT_TIMEOUT_SECONDS = 600


class ConfigurationError(ValueError):
    pass


class AuthenticationError(RuntimeError):
    pass


class InfrastructureError(RuntimeError):
    pass


def validate_binding(account_slot: str, profile: str) -> None:
    if account_slot not in _SLOTS:
        raise ConfigurationError("account slot must be A, B, or C")
    match = _PROFILE_RE.fullmatch(profile)
    if match is None or match.group("slot") != account_slot:
        raise ConfigurationError("profile must be ci-<selected-slot>-<allowlisted-lane>")


def profile_dir(profile: str, env: Mapping[str, str]) -> Path:
    root = Path(env.get("NOTEBOOKLM_HOME", str(Path.home() / ".notebooklm"))).expanduser()
    return root / "profiles" / profile


def _ensure_private_directory(path: Path) -> None:
    path.mkdir(parents=True, exist_ok=True, mode=0o700)
    if path.is_symlink() or not path.is_dir():
        raise InfrastructureError("profile path is not a regular directory")
    if os.name == "nt" and path.lstat().st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT:
        raise InfrastructureError("profile path is a reparse point")
    if os.name != "nt":
        path.chmod(0o700)
        if stat.S_IMODE(path.stat().st_mode) != 0o700:
            raise InfrastructureError("profile directory permissions are not private")


def atomic_private_write(path: Path, value: str) -> None:
    """Atomically write an opaque credential with private POSIX permissions."""
    _ensure_private_directory(path.parent)
    fd, raw_tmp = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
    tmp = Path(raw_tmp)
    try:
        if os.name != "nt":
            os.fchmod(fd, 0o600)
        with os.fdopen(fd, "w", encoding="utf-8", newline="") as stream:
            stream.write(value)
            stream.flush()
            os.fsync(stream.fileno())
        os.replace(tmp, path)
        if path.is_symlink() or not path.is_file():
            raise InfrastructureError("credential path is not a regular file")
        if os.name == "nt" and path.lstat().st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT:
            raise InfrastructureError("credential path is a reparse point")
        if os.name != "nt" and stat.S_IMODE(path.stat().st_mode) != 0o600:
            raise InfrastructureError("credential file permissions are not private")
        if os.name != "nt":
            # Persist the directory entry as well as the temporary file contents.
            # Without this fsync, a power loss can lose an otherwise successful
            # replace even though the file itself was flushed.
            directory_fd = os.open(path.parent, os.O_RDONLY)
            try:
                os.fsync(directory_fd)
            finally:
                os.close(directory_fd)
    finally:
        try:
            tmp.unlink()
        except FileNotFoundError:
            pass


def materialize(
    *,
    account_slot: str,
    profile: str,
    env: Mapping[str, str] | None = None,
    run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
    sleep: Callable[[float], None] = time.sleep,
    randint: Callable[[int, int], int] = random.SystemRandom().randint,
) -> int:
    source_env = dict(os.environ if env is None else env)
    validate_binding(account_slot, profile)
    token = source_env.get("NOTEBOOKLM_MASTER_TOKEN_JSON", "")
    if not token:
        raise ConfigurationError(
            f"NOTEBOOKLM_MASTER_TOKEN_JSON resolved empty for slot {account_slot}"
        )

    target_dir = profile_dir(profile, source_env)
    token_path = target_dir / "master_token.json"
    storage_path = target_dir / "storage_state.json"
    atomic_private_write(token_path, token)
    try:
        storage_path.unlink()
    except FileNotFoundError:
        pass

    child_env = source_env.copy()
    child_env.pop("NOTEBOOKLM_MASTER_TOKEN_JSON", None)
    for name in tuple(child_env):
        if name == "NOTEBOOKLM_AUTH_JSON" or name.startswith("NOTEBOOKLM_MASTER_TOKEN_JSON_"):
            child_env.pop(name, None)
    child_env["NOTEBOOKLM_PROFILE"] = profile
    command = [sys.executable, "-m", "notebooklm", "login", "--master-token-refresh"]

    last_result: subprocess.CompletedProcess[str] | None = None
    for attempt in range(1, 4):
        try:
            last_result = run(
                command,
                env=child_env,
                capture_output=True,
                text=True,
                check=False,
                timeout=MINT_TIMEOUT_SECONDS,
            )
        except subprocess.TimeoutExpired:
            last_result = subprocess.CompletedProcess(
                command,
                124,
                "",
                f"auth mint timed out after {MINT_TIMEOUT_SECONDS} seconds",
            )
        except Exception as exc:
            raise InfrastructureError("could not launch the auth mint subprocess") from exc

        for output in (last_result.stdout, last_result.stderr):
            # The shared scrubber catches credential-shaped fields, while the
            # selected master-token file is intentionally opaque and may have
            # no recognizable shape. Redact its exact bytes as well.
            sanitized = scrub_secrets((output or "").replace(token, "***")).strip()
            if sanitized:
                print(sanitized, file=sys.stderr)
        if last_result.returncode == 0:
            if not storage_path.is_file() or storage_path.is_symlink():
                raise InfrastructureError("auth mint returned success without fresh storage")
            if (
                os.name == "nt"
                and storage_path.lstat().st_file_attributes & stat.FILE_ATTRIBUTE_REPARSE_POINT
            ):
                raise InfrastructureError("auth storage path is a reparse point")
            if os.name != "nt":
                storage_path.chmod(0o600)
                if stat.S_IMODE(storage_path.stat().st_mode) != 0o600:
                    raise InfrastructureError("auth storage permissions are not private")
            print(
                f"Auth profile {profile} materialized for slot {account_slot} "
                f"after {attempt} attempt(s)"
            )
            return attempt
        if attempt < 3:
            sleep(attempt * 15 + randint(0, 19))

    code = last_result.returncode if last_result is not None else "unknown"
    raise AuthenticationError(f"master-token mint failed after 3 attempts (exit {code})")


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--account-slot", required=True, choices=_SLOTS)
    parser.add_argument("--profile", required=True)
    return parser


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        materialize(account_slot=args.account_slot, profile=args.profile)
    except ConfigurationError as exc:
        print(f"configuration error: {scrub_secrets(exc)}", file=sys.stderr)
        return CONFIGURATION_ERROR
    except AuthenticationError as exc:
        print(f"authentication error: {scrub_secrets(exc)}", file=sys.stderr)
        return AUTH_ERROR
    except (InfrastructureError, OSError) as exc:
        print(f"infrastructure error: {scrub_secrets(exc)}", file=sys.stderr)
        return INFRASTRUCTURE_ERROR
    return 0


if __name__ == "__main__":
    raise SystemExit(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