Status: Active Last Updated: 2026-01-14

This document describes the stability guarantees and versioning policy for notebooklm-py.

This library uses undocumented Google APIs. Unlike official Google APIs, there are:

• No stability guarantees from Google
• No deprecation notices before changes
• No SLAs or support

Google can change the underlying APIs at any time, which may break this library without warning.

We follow Semantic Versioning with modifications for our unique situation:

1. RPC ID Changes = Patch Release

   • When Google changes internal RPC method IDs, we release a patch
   • These are "bug fixes" from our perspective, not breaking changes
   • Users should always use the latest patch version

2. Python API Stability

   • Public API (items in __all__) is stable within a major version
   • Breaking changes require a major version bump
   • Deprecated APIs are marked with DeprecationWarning and documented

The following are considered public API and are subject to stability guarantees:

# Client
NotebookLMClient
NotebookLMClient.from_storage()
NotebookLMClient.notebooks
NotebookLMClient.sources
NotebookLMClient.artifacts
NotebookLMClient.chat
NotebookLMClient.research
NotebookLMClient.notes

# Types
Notebook, Source, Artifact, Note
GenerationStatus, AskResult
NotebookDescription, ConversationTurn

# Exceptions
SourceError, SourceProcessingError, SourceTimeoutError, SourceNotFoundError
RPCError

# Enums
AudioFormat, VideoFormat, StudioContentType, ExportType, etc.

# Auth
AuthTokens, DEFAULT_STORAGE_PATH

# These are NOT part of the public API:
notebooklm.rpc.*          # RPC protocol internals
notebooklm._core.*        # Core infrastructure
notebooklm._*.py          # All underscore-prefixed modules
notebooklm.auth.*         # Auth internals (except AuthTokens)

To use internal APIs, import them explicitly:

# Explicit import for power users (may break)
from notebooklm.rpc import RPCMethod, encode_rpc_request

1. Deprecation Notice: Deprecated features emit DeprecationWarning
2. Documentation: Deprecations are noted in docstrings and CHANGELOG
3. Removal Timeline: Deprecated features are removed in the next major version
4. Migration Guide: Breaking changes include migration instructions

None at this time.

When Google changes their internal APIs:

1. Detection: Automated RPC health check runs nightly (see below)
2. Investigation: Identify changed method IDs using browser devtools
3. Fix: Update rpc/types.py with new method IDs
4. Release: Push patch release as soon as possible

A nightly GitHub Action (rpc-health.yml) monitors all 35+ RPC methods for ID changes.

What it verifies:

• The RPC method ID we send matches the ID returned in the response envelope
• Example: LIST_NOTEBOOKS sends wXbhsf → response must contain wXbhsf

What it does NOT verify:

• Response data correctness (E2E tests cover this)
• Response schema validation (too fragile across 35+ methods)
• Business logic (out of scope for monitoring)

Why this design:

• Google's breaking change pattern is silent ID changes, not schema changes
• Error responses still contain the method ID, so we detect mismatches even on API errors
• A mismatch means rpc/types.py needs updating, triggering a patch release

On mismatch detection:

• GitHub Issue auto-created with bug, rpc-breakage, and automated labels
• Report shows expected vs actual IDs and which RPCMethod entries need updating

Configuration:

• NOTEBOOKLM_RPC_DELAY: Delay between RPC calls in seconds (default: 1.0)

Manual trigger: gh workflow run rpc-health.yml

1. Check GitHub Issues for existing reports
2. If not reported, open an issue with:
   • Error message (especially any RPC error codes)
   • Which operation failed
   • When it started failing
3. See RPC Development Guide for debugging

If the library breaks before we release a fix:

1. Open browser devtools on NotebookLM
2. Perform the failing operation manually
3. Find the new RPC method ID in Network tab
4. Temporarily patch your local copy:

   # In your code, before using the library
   from notebooklm.rpc.types import RPCMethod
   RPCMethod.SOME_METHOD._value_ = "NewMethodId"

# Always use latest patch version
pip install --upgrade notebooklm-py

# pyproject.toml - recommended
dependencies = [
    "notebooklm-py>=0.1,<1.0",  # Accept patches and minors
]

# requirements.txt - for reproducibility
notebooklm-py==0.1.0  # Exact version (but update regularly!)

# Test in development first
pip install notebooklm-py==X.Y.Z
pytest

• Bug reports: GitHub Issues
• Discussions: GitHub Discussions
• Security issues: See SECURITY.md