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_coverage_thresholds.py

View on GitHub
"""Assert nightly CI ultimately enforces pyproject.toml's coverage threshold.

Prevents the two values from drifting (e.g. CI passing at 70% while pyproject
demands 90%, or vice versa) by failing CI whenever they disagree.

When ``--coverage-json`` is provided, additionally enforces per-file floors
declared in ``[tool.notebooklm.per_file_coverage_floors]``. Coverage.py's
``[tool.coverage.report]`` only supports a global ``fail_under``, so individual
files that lag the project-wide 90% are guarded by this script.

Usage:
    python scripts/check_coverage_thresholds.py
    python scripts/check_coverage_thresholds.py --pyproject custom/pyproject.toml --workflow custom/nightly.yml
    python scripts/check_coverage_thresholds.py --coverage-json coverage.json

Exit codes:
    0  Thresholds match (and any per-file floors are met).
    1  Drift detected, OR a per-file floor breached.
    2  Argument error / missing field / coverage.json missing or malformed.
"""

from __future__ import annotations

import argparse
import json
import re
import sys

if sys.version_info >= (3, 11):
    import tomllib
else:
    try:
        import tomli as tomllib  # type: ignore[import-not-found,no-redef]
    except ImportError:
        print(
            "tomli is required on Python 3.10. Install with: uv pip install tomli",
            file=sys.stderr,
        )
        sys.exit(2)


def _check_global_drift(pyproject_path: str, workflow_path: str) -> int:
    """Compare pyproject ``fail_under`` against CI's enforcing threshold."""
    try:
        with open(pyproject_path, "rb") as f:
            pp = tomllib.load(f)
    except FileNotFoundError:
        print(f"pyproject.toml not found: {pyproject_path}", file=sys.stderr)
        return 2

    try:
        pyproject_threshold = pp["tool"]["coverage"]["report"]["fail_under"]
    except KeyError:
        print(
            f"No [tool.coverage.report] fail_under in {pyproject_path}",
            file=sys.stderr,
        )
        return 2

    try:
        with open(workflow_path) as f:
            yml = f.read()
    except FileNotFoundError:
        print(f"Workflow not found: {workflow_path}", file=sys.stderr)
        return 2

    # Scan line-by-line and ignore commented YAML lines so a stale
    # `# --cov-fail-under=90` doesn't shadow a real drift in the executed
    # command. Collect ALL occurrences so a workflow with multiple jobs
    # cannot smuggle a divergent threshold past the check. A zero threshold is
    # permitted for an intermediate ``--cov-append`` workflow step, but at
    # least one later occurrence must enforce the configured project floor.
    thresholds: list[int] = []
    pattern = re.compile(r"(?<!\S)--cov-fail-under(?:=|\s+)(\d+)(?!\S)")
    for line in yml.splitlines():
        stripped = line.lstrip()
        if stripped.startswith("#"):
            continue
        for m in pattern.finditer(stripped):
            thresholds.append(int(m.group(1)))

    if not thresholds:
        print(f"No --cov-fail-under in {workflow_path}", file=sys.stderr)
        return 2

    for ci_threshold in thresholds:
        if ci_threshold not in {0, pyproject_threshold}:
            print(
                f"DRIFT: pyproject.toml fail_under={pyproject_threshold} but "
                f"{workflow_path} --cov-fail-under={ci_threshold}",
                file=sys.stderr,
            )
            return 1

    if pyproject_threshold not in thresholds:
        print(
            f"DRIFT: {workflow_path} only defers coverage enforcement; no "
            f"--cov-fail-under={pyproject_threshold} matches pyproject.toml",
            file=sys.stderr,
        )
        return 1

    print(f"OK: {len(thresholds)} occurrence(s), final floor enforced at {pyproject_threshold}%")
    return 0


def _check_per_file_floors(pyproject_path: str, coverage_json_path: str) -> int:
    """Enforce per-file floors from ``[tool.notebooklm.per_file_coverage_floors]``.

    Floors live in pyproject.toml so they're checked into the repo and bumped
    via PR (the commit message documents the new minimum). The script reads
    ``coverage.json`` produced by ``pytest --cov ... --cov-report=json:...``
    and fails if any guarded file's ``percent_covered`` is below its floor.
    """
    try:
        with open(pyproject_path, "rb") as f:
            pp = tomllib.load(f)
    except FileNotFoundError:
        print(f"pyproject.toml not found: {pyproject_path}", file=sys.stderr)
        return 2

    floors = pp.get("tool", {}).get("notebooklm", {}).get("per_file_coverage_floors")
    if floors is None:
        # Missing table is fine — nothing to enforce.
        print(f"OK: no [tool.notebooklm.per_file_coverage_floors] in {pyproject_path}")
        return 0
    if not isinstance(floors, dict):
        # Misconfiguration (e.g. someone wrote a string or list instead of a
        # table). Fail fast rather than silently returning OK.
        print(
            f"[tool.notebooklm.per_file_coverage_floors] must be a TOML table in "
            f"{pyproject_path}, got {type(floors).__name__}",
            file=sys.stderr,
        )
        return 2
    if not floors:
        # Empty table — explicitly opted into "enforce nothing right now".
        print(f"OK: no [tool.notebooklm.per_file_coverage_floors] in {pyproject_path}")
        return 0

    try:
        with open(coverage_json_path) as f:
            cov = json.load(f)
    except FileNotFoundError:
        print(f"coverage.json not found: {coverage_json_path}", file=sys.stderr)
        return 2
    except json.JSONDecodeError as exc:
        print(f"coverage.json malformed: {exc}", file=sys.stderr)
        return 2

    files = cov.get("files")
    if not isinstance(files, dict):
        # Includes both the missing-key case (``cov.get`` returns None) and
        # the wrong-shape case (e.g. accidentally a list); both indicate a
        # malformed ``coverage.json`` and should fail before any per-file
        # comparison runs.
        print(
            f"coverage.json 'files' must be an object map in {coverage_json_path}, "
            f"got {type(files).__name__}",
            file=sys.stderr,
        )
        return 2

    failures: list[str] = []
    missing: list[str] = []
    for path, floor in sorted(floors.items()):
        entry = files.get(path)
        if entry is None:
            # A guarded file with no measurement is itself a CI failure —
            # otherwise a rename or accidental deletion would silently drop
            # the floor and any later regression would slip through.
            missing.append(path)
            continue
        try:
            actual = float(entry["summary"]["percent_covered"])
            target = float(floor)
        except (KeyError, TypeError, ValueError) as exc:
            print(
                f"coverage.json entry for {path!r} could not be compared "
                f"(actual={entry.get('summary', {}).get('percent_covered')!r}, "
                f"floor={floor!r}): {exc}",
                file=sys.stderr,
            )
            return 2
        if actual < target:
            failures.append(f"  {path}: {actual:.2f}% < floor {floor}%")

    if missing:
        print(
            "MISSING from coverage.json (renamed/deleted? update "
            "[tool.notebooklm.per_file_coverage_floors] or restore the file):\n  "
            + "\n  ".join(missing),
            file=sys.stderr,
        )
        return 1

    if failures:
        print(
            "PER-FILE COVERAGE FLOOR BREACH:\n" + "\n".join(failures),
            file=sys.stderr,
        )
        return 1

    print(f"OK: {len(floors)} per-file floor(s) all met")
    return 0


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--pyproject", default="pyproject.toml")
    ap.add_argument("--workflow", default=".github/workflows/nightly-checks.yml")
    ap.add_argument(
        "--coverage-json",
        default=None,
        help=(
            "Optional path to coverage.json (produced by `pytest --cov "
            "--cov-report=json:coverage.json`). When present, also enforces "
            "[tool.notebooklm.per_file_coverage_floors] from pyproject.toml."
        ),
    )
    args = ap.parse_args(argv)

    drift_rc = _check_global_drift(args.pyproject, args.workflow)
    if drift_rc != 0:
        return drift_rc

    if args.coverage_json:
        return _check_per_file_floors(args.pyproject, args.coverage_json)
    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