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

View on GitHub
"""Assert the repo-structure file map is fresh in both directions.

The hand-maintained module map (the ``### Repository Structure`` tree) lives in
``docs/architecture.md`` — it was moved there from CLAUDE.md to keep CLAUDE.md
slim; the ``--claude-md`` flag is kept (name unchanged for back-compat) but now
defaults to the architecture doc. This gate prevents silent drift:

* documented paths must still exist; and
* every ``src/notebooklm`` module/package (including subpackage members) must
  be documented or explicitly omitted with a reason.

Usage:
    python scripts/check_claude_md_freshness.py
    python scripts/check_claude_md_freshness.py --claude-md path/to/doc.md

Exit codes:
    0  The structure doc (docs/architecture.md) is fresh.
    1  One or more paths are stale or missing from the map.
    2  Argument error or the structure doc not found.
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

_DOCUMENTED_ROOTS = ("src/notebooklm", "tests")
_OMISSIONS_HEADING = "### Repository Structure Intentional Omissions"
_OMISSION_BULLET_RE = re.compile(r"^\s*[-*]\s+")
_OMISSION_PATH_RE = re.compile(r"^\s*[-*]\s+`(?P<path>src/notebooklm/[^`]+)`")
_IGNORED_PATH_RE = re.compile(
    r"^\s*[-*]\s+`(?P<path>src/notebooklm/[^`]+)`\s+(?:--|-|:)\s+(?P<reason>.+?)\s*$"
)


def _extract_paths(text: str) -> list[str]:
    paths: list[str] = []
    stack: list[tuple[int, str]] = []

    for line in text.splitlines():
        # Do not strip yet, we need leading spaces for indent calculation
        trimmed = line.strip()
        if not trimmed or any(trimmed.startswith(p) for p in ("|", "#", "```")):
            continue

        # Determine indentation level and clean the line
        indent = 0
        clean_line = trimmed
        found_marker = False
        for marker in ("├── ", "└── ", "│   "):
            if marker in line:
                # Calculate depth based on the position of the marker
                # We expect 4 spaces per level (or equivalent tree chars)
                pos = line.find(marker)
                indent = (pos // 4) + 1
                clean_line = line.split(marker, 1)[1]
                found_marker = True
                break

        if not found_marker:
            if trimmed.startswith(("src/notebooklm", "tests")):
                indent = 0
                clean_line = trimmed
            else:
                continue

        # Remove comments
        if " # " in clean_line:
            clean_line = clean_line.split(" # ", 1)[0]
        clean_line = clean_line.strip().rstrip("/")

        if not clean_line:
            continue

        # Manage the stack for tree traversal
        while stack and stack[-1][0] >= indent:
            stack.pop()

        stack.append((indent, clean_line))

        full_path = "/".join(segment for _, segment in stack)
        if full_path.startswith(_DOCUMENTED_ROOTS):
            paths.append(full_path)

    return sorted(set(paths))


def _repository_structure_section(text: str) -> str:
    section = _section_after_heading(text, "### Repository Structure")
    next_heading = re.search(r"^\s*##\s+", section, flags=re.MULTILINE)
    if next_heading is not None:
        section = section[: next_heading.start()]
    return section


def _extract_intentional_omissions(text: str) -> dict[str, str]:
    """Return intentionally omitted ``src/notebooklm`` paths and their reasons."""
    omissions: dict[str, str] = {}
    for line in _intentional_omissions_section(text).splitlines():
        if "`src/notebooklm/" not in line:
            continue
        match = _IGNORED_PATH_RE.match(line)
        if match is None:
            continue
        path = match.group("path").rstrip("/")
        reason = match.group("reason").strip()
        if reason:
            omissions[path] = reason
    return omissions


def _extract_unreasoned_omissions(text: str) -> list[str]:
    """Return omission bullets that mention a path but do not provide a reason."""
    unreasoned: list[str] = []
    for line in _intentional_omissions_section(text).splitlines():
        if _OMISSION_PATH_RE.match(line) and _IGNORED_PATH_RE.match(line) is None:
            unreasoned.append(line.strip())
    return unreasoned


def _extract_omission_bullet_path(line: str) -> str | None:
    match = _OMISSION_PATH_RE.match(line)
    if match is None:
        return None
    return match.group("path").rstrip("/")


def _intentional_omissions_section(text: str) -> str:
    section = _section_after_heading(text, _OMISSIONS_HEADING)
    next_heading = re.search(r"^\s*###\s+", section, flags=re.MULTILINE)
    if next_heading is not None:
        section = section[: next_heading.start()]
    return section


def _section_after_heading(text: str, heading: str) -> str:
    match = re.search(rf"^\s*{re.escape(heading)}\s*$", text, flags=re.MULTILINE)
    if match is None:
        return ""
    return text[match.end() :]


def _top_level_notebooklm_modules(repo_root: Path) -> list[str]:
    """Return every ``src/notebooklm`` Python module and subpackage.

    Recurses through subpackages so that subpackage members (e.g.
    ``_auth/tokens.py``, ``_web/wire/overrides.py``) must be documented too — not
    just direct top-level modules. ``__init__.py`` package markers are
    excluded from the required set; the enclosing package directory stands in
    for them.
    """
    package_root = repo_root / "src" / "notebooklm"
    if not package_root.is_dir():
        return []

    paths: list[str] = []
    for child in package_root.rglob("*"):
        if "__pycache__" in child.parts:
            continue
        is_package = child.is_dir() and (child / "__init__.py").is_file()
        is_module = child.is_file() and child.suffix == ".py" and child.name != "__init__.py"
        if is_package or is_module:
            paths.append(child.relative_to(repo_root).as_posix())
    return sorted(paths)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--claude-md", default="docs/architecture.md")
    ap.add_argument("--repo-root", default=".")
    args = ap.parse_args(argv)

    claude = Path(args.claude_md)
    if not claude.is_file():
        print(f"Structure doc not found: {claude}", file=sys.stderr)
        return 2

    repo_root = Path(args.repo_root).resolve()
    text = _repository_structure_section(claude.read_text(encoding="utf-8"))

    paths = _extract_paths(text)
    omissions = _extract_intentional_omissions(text)
    unreasoned_omissions = _extract_unreasoned_omissions(text)
    unreasoned_paths = {
        path for line in unreasoned_omissions if (path := _extract_omission_bullet_path(line))
    }
    missing = [p for p in paths if not (repo_root / p).exists()]
    top_level_modules = _top_level_notebooklm_modules(repo_root)
    undocumented = [
        p
        for p in top_level_modules
        if p not in paths and p not in omissions and p not in unreasoned_paths
    ]
    stale_omissions = [p for p in omissions if not (repo_root / p).exists()]

    if missing or undocumented or stale_omissions or unreasoned_omissions:
        if missing:
            print("Stale structure-doc path references:", file=sys.stderr)
            for p in missing:
                print(f"  {p}", file=sys.stderr)
        if undocumented:
            print("Undocumented src/notebooklm modules/packages:", file=sys.stderr)
            for p in undocumented:
                print(f"  {p}", file=sys.stderr)
        if stale_omissions:
            print("Stale structure-doc intentional omissions:", file=sys.stderr)
            for p in stale_omissions:
                print(f"  {p}", file=sys.stderr)
        if unreasoned_omissions:
            print("Intentional omissions without parseable reasons:", file=sys.stderr)
            for line in unreasoned_omissions:
                print(f"  {line}", file=sys.stderr)
        return 1
    print(
        f"OK: {len(paths)} documented paths resolve; "
        f"{len(top_level_modules)} modules/packages "
        f"are documented or intentionally omitted"
    )
    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