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/_live_auth_scenarios/rest_recovery.py

View on GitHub
"""Drive REST through live-jar recovery and degraded-startup lazy binding.

Two halves, both against a real ASGI app over ``httpx.ASGITransport``:

1. *mid-session* — a served request recovers after the live cookie jar of the
   bound client is emptied.
2. *stale startup* — the server starts with an unusable profile (no cookies, the
   master token withheld), must enter degraded startup with no bound client,
   and must lazily bind a working client once a sibling CLI re-mints the
   profile.

Result contract: ``{"before", "after_live_reload", "after_stale_startup_rebind",
"stale_startup_rebound"}``.
"""

from __future__ import annotations

import contextlib
import json
import os
import subprocess
import sys
from collections.abc import AsyncIterator
from pathlib import Path
from typing import Any

import httpx

from notebooklm import NotebookLMClient
from notebooklm.server.app import create_app

from ._contract import ScenarioResult, require, run_scenario

#: Disposable profile that starts out healthy and loses only its live jar.
PROFILE = "rest-live"
#: Disposable profile that is made unusable before the server starts.
STALE_PROFILE = "rest-stale"
#: Must match ``NOTEBOOKLM_SERVER_TOKEN`` in the orchestrator's phase overrides.
TOKEN = "matrix-rest-token"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Host": "127.0.0.1"}


def notebook_ids(response: httpx.Response) -> tuple[str, ...]:
    """Return the sorted notebook ids of a ``/v1/notebooks`` response."""
    return tuple(sorted(item["id"] for item in response.json()["notebooks"]))


async def mid_session() -> tuple[tuple[str, ...], tuple[str, ...]]:
    """Serve one request, empty the bound client's jar, serve another."""
    holder: dict[str, NotebookLMClient] = {}

    @contextlib.asynccontextmanager
    async def factory() -> AsyncIterator[NotebookLMClient]:
        async with NotebookLMClient.from_storage(profile=PROFILE, keepalive=600.0) as client:
            holder["client"] = client
            yield client

    app = create_app(profile=PROFILE, client_factory=factory)
    async with app.router.lifespan_context(app):
        transport = httpx.ASGITransport(
            app=app, client=("127.0.0.1", 5555), raise_app_exceptions=False
        )
        async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1") as http:
            before = await http.get("/v1/notebooks", headers=HEADERS)
            require(before.status_code == 200, before.text[-1000:])
            holder["client"]._require_web_runtime().kernel.get_http_client().cookies.clear()
            after = await http.get("/v1/notebooks", headers=HEADERS)
            require(after.status_code == 200, after.text[-1000:])
            return notebook_ids(before), notebook_ids(after)


async def stale_startup() -> tuple[str, ...]:
    """Start degraded on an unusable profile, then bind after a sibling re-mint."""
    profile_dir = Path(os.environ["NOTEBOOKLM_HOME"]) / "profiles" / STALE_PROFILE
    storage = profile_dir / "storage_state.json"
    token = profile_dir / "master_token.json"
    held_token = profile_dir / "master_token.matrix-held"
    state = json.loads(storage.read_text(encoding="utf-8"))
    state["cookies"] = []
    replacement = storage.with_suffix(".matrix-tmp")
    replacement.write_text(json.dumps(state), encoding="utf-8")
    # Match ``atomic_write_json``'s 0o600 (``_atomic_io.py``): a bare
    # ``write_text`` lands at the process umask (0o644), and ``os.replace``
    # carries the temp file's mode onto the profile. The disposable home is
    # already 0o700, so this is defence in depth rather than a live hole,
    # but a credential file must never widen on any path.
    replacement.chmod(0o600)
    os.replace(replacement, storage)
    require(token.is_file(), f"{STALE_PROFILE} profile has no master_token.json")
    token.replace(held_token)

    app = create_app(profile=STALE_PROFILE)
    async with app.router.lifespan_context(app):
        require(
            app.state.notebooklm.client is None,
            "REST server did not enter degraded startup",
        )
        held_token.replace(token)
        sibling = subprocess.run(
            [
                sys.executable,
                "-m",
                "notebooklm.notebooklm_cli",
                "--profile",
                STALE_PROFILE,
                "login",
                "--master-token-refresh",
            ],
            env=os.environ.copy(),
            text=True,
            capture_output=True,
            timeout=90,
            check=False,
        )
        require(
            sibling.returncode == 0,
            f"stale-profile master-token re-mint failed with exit code {sibling.returncode}",
        )
        transport = httpx.ASGITransport(
            app=app, client=("127.0.0.1", 5555), raise_app_exceptions=False
        )
        async with httpx.AsyncClient(transport=transport, base_url="http://127.0.0.1") as http:
            response = await http.get("/v1/notebooks", headers=HEADERS)
        require(response.status_code == 200, response.text[-1000:])
        require(
            app.state.notebooklm.client is not None,
            "REST server did not bind a recovered client",
        )
        return notebook_ids(response)


async def scenario() -> ScenarioResult:
    """Run both REST recovery halves and require one stable notebook identity."""
    before_ids, after_ids = await mid_session()
    rebound_ids = await stale_startup()
    require(
        before_ids == after_ids == rebound_ids,
        "REST recovery changed notebook identity",
    )
    payload: dict[str, Any] = {
        "before": len(before_ids),
        "after_live_reload": len(after_ids),
        "after_stale_startup_rebind": len(rebound_ids),
        "stale_startup_rebound": True,
    }
    return payload


def main() -> None:
    """Entry point for ``python -m`` execution by the live-auth matrix."""
    run_scenario(scenario)


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