Status: Active Last Updated: 2026-01-21

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
NotebookLMClient.settings
NotebookLMClient.sharing

# Types
Notebook, Source, Artifact, Note
GenerationStatus, AskResult
NotebookDescription, ConversationTurn
ShareStatus, SharedUser, SourceFulltext

# Exceptions (all inherit from NotebookLMError)
NotebookLMError                    # Base exception
RPCError, AuthError, RateLimitError, RPCTimeoutError, ServerError
NetworkError, DecodingError, UnknownRPCMethodError
ClientError, ConfigurationError, ValidationError
# Domain-specific
SourceError, SourceAddError, SourceProcessingError, SourceTimeoutError, SourceNotFoundError
NotebookError, NotebookNotFoundError
ArtifactError, ArtifactDownloadError, ArtifactNotFoundError, ArtifactNotReadyError, ArtifactParseError
ChatError

# Enums
AudioFormat, VideoFormat, ExportType
SourceType, ArtifactType, SourceStatus
ShareAccess, SharePermission, ShareViewLevel
ChatGoal, ChatResponseLength, ChatMode

# 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

The following are deprecated and will be removed in v0.4.0:

Version 0.3.0 introduces deprecated attributes that emit DeprecationWarning when accessed. These will be removed in v0.4.0. Update your code now to avoid breakage.

Before (deprecated):

source = await client.sources.list(notebook_id)[0]
if source.source_type == "pdf":  # ⚠️ Emits DeprecationWarning
    print("This is a PDF")

After (recommended):

from notebooklm import SourceType

source = await client.sources.list(notebook_id)[0]

# Option 1: Use enum comparison (recommended)
if source.kind == SourceType.PDF:
    print("This is a PDF")

# Option 2: Use string comparison (str enum supports this)
if source.kind == "pdf":
    print("This is a PDF")

Available SourceType values: GOOGLE_DOCS, GOOGLE_SLIDES, GOOGLE_SPREADSHEET, PDF, PASTED_TEXT, WEB_PAGE, YOUTUBE, MARKDOWN, DOCX, CSV, IMAGE, MEDIA, UNKNOWN

Before (deprecated):

from notebooklm import StudioContentType  # ⚠️ Emits DeprecationWarning

artifact = await client.artifacts.list(notebook_id)[0]
if artifact.artifact_type == StudioContentType.AUDIO:  # ⚠️ Emits DeprecationWarning
    print("This is an audio artifact")

After (recommended):

from notebooklm import ArtifactType

artifact = await client.artifacts.list(notebook_id)[0]

# Option 1: Use enum comparison (recommended)
if artifact.kind == ArtifactType.AUDIO:
    print("This is an audio artifact")

# Option 2: Use string comparison (str enum supports this)
if artifact.kind == "audio":
    print("This is an audio artifact")

Available ArtifactType values: AUDIO, VIDEO, REPORT, QUIZ, FLASHCARDS, MIND_MAP, INFOGRAPHIC, SLIDE_DECK, DATA_TABLE, UNKNOWN

Before (deprecated):

if artifact.artifact_type == 4 and artifact.variant == 2:  # ⚠️ Deprecated
    print("This is a quiz")

After (recommended):

# Option 1: Use .kind
if artifact.kind == ArtifactType.QUIZ:
    print("This is a quiz")

# Option 2: Use helper properties
if artifact.is_quiz:
    print("This is a quiz")
if artifact.is_flashcards:
    print("These are flashcards")

1. Stability: The .kind property abstracts internal integer codes that Google may change
2. Usability: String enums work in comparisons, logging, and serialization
3. Future-proofing: Unknown types return UNKNOWN with a warning instead of crashing

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