notebooklm-py-analysis/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.3.3 - 2026-03-03

Added

• ask --save-as-note - Save chat answers as notebook notes directly from the CLI (#135)
  • notebooklm ask "question" --save-as-note - Save response as a note
  • notebooklm ask "question" --save-as-note --note-title "Title" - Save with custom title
• history --save - Save full conversation history as a notebook note (#135)
  • notebooklm history --save - Save history with default title
  • notebooklm history --save --note-title "Title" - Save with custom title
  • notebooklm history --show-all - Show full Q&A content instead of preview
• generate report --append - Append custom instructions to built-in report format templates (#134)
  • Works with briefing-doc, study-guide, and blog-post formats (no effect on custom)
  • Example: notebooklm generate report --format study-guide --append "Target audience: beginners"
• generate revise-slide - Revise individual slides in an existing slide deck (#129)
  • notebooklm generate revise-slide "prompt" --artifact <id> --slide 0
• PPTX download for slide decks - Download slide decks as editable PowerPoint files (#129)
  • notebooklm download slide-deck --format pptx (web UI only offers PDF)

Fixed

• Partial artifact ID in download commands - Download commands now support partial artifact IDs (#130)
• Chat empty answer - Fixed ask returning empty answer when API response marker changes (#123)
• X.com/Twitter content parsing - Fixed parsing of X.com/Twitter source content (#119)
• Language sync on login - Syncs server language setting to local config after notebooklm login (#124)
• Python version check - Added runtime check with clear error message for Python < 3.10 (#125)
• RPC error diagnostics - Improved error reporting for GET_NOTEBOOK and auth health check failures (#126, #127)
• Conversation persistence - Chat conversations now persist server-side; conversation ID shown in history output (#138)
• History Q&A previews - Fixed populating Q&A previews using conversation turns API (#136)
• generate report --language - Fixed missing --language option for report generation (#109)

Changed

• Chat history API - Simplified history retrieval; removed exchange_id, improved conversation grouping with parallel fetching (#140, #141)
• Conversation ID tracking - Server-side conversation lookup via new hPTbtc RPC (GET_LAST_CONVERSATION_ID) replaces local exchange ID tracking
• History Q&A population - Now uses khqZz RPC (GET_CONVERSATION_TURNS) to fetch full Q&A turns with accurate previews (#136)

Infrastructure

• Bumped actions/upload-artifact from v6 to v7 (#131)

0.3.2 - 2026-01-26

Fixed

• CLI conversation reset - Fixed conversation ID not resetting when switching notebooks (#97)
• UTF-8 file encoding - Added explicit UTF-8 encoding to all file I/O operations (#93)
• Windows Playwright login - Restored ProactorEventLoop for Playwright login on Windows (#91)

Infrastructure

• Fixed E2E test teardown hook for pytest 8.x compatibility (#101)
• Added 15-second delay between E2E generation tests to avoid rate limits (#95)

0.3.1 - 2026-01-23

Fixed

• Windows CLI hanging - Fixed asyncio ProactorEventLoop incompatibility causing CLI to hang on Windows (#79)
• Unicode encoding errors - Fixed encoding issues on non-English Windows systems (#80)
• Streaming downloads - Downloads now use streaming with temp files to prevent corrupted partial downloads (#82)
• Partial ID resolution - All CLI commands now support partial ID matching for notebooks, sources, and artifacts (#84)
• Source operations - Fixed empty array handling and add_drive nesting (#73)
• Guide response parsing - Fixed 3-level nesting in get_guide responses (#72)
• RPC health check - Handle null response in health check scripts (#71)
• Script cleanup - Ensure temp notebook cleanup on failure or interrupt

Infrastructure

• Added develop branch to nightly E2E tests with staggered schedule
• Added custom branch support to nightly E2E workflow for release testing

0.3.0 - 2026-01-21

Added

• Language settings - Configure output language for artifact generation (audio, video, etc.)
  • New notebooklm language list - List all 80+ supported languages with native names
  • New notebooklm language get - Show current language setting
  • New notebooklm language set <code> - Set language (e.g., zh_Hans, ja, es)
  • Language is a global setting affecting all notebooks in your account
  • --local flag for offline-only operations (skip server sync)
  • --language flag on generate commands for per-command override
• Sharing API - Programmatic notebook sharing management
  • New client.sharing.get_status(notebook_id) - Get current sharing configuration
  • New client.sharing.set_public(notebook_id, True/False) - Enable/disable public link
  • New client.sharing.set_view_level(notebook_id, level) - Set viewer access (FULL_NOTEBOOK or CHAT_ONLY)
  • New client.sharing.add_user(notebook_id, email, permission) - Share with specific users
  • New client.sharing.update_user(notebook_id, email, permission) - Update user permissions
  • New client.sharing.remove_user(notebook_id, email) - Remove user access
  • New ShareStatus, SharedUser dataclasses for structured sharing data
  • New ShareAccess, SharePermission, ShareViewLevel enums
• SourceType enum - New str, Enum for type-safe source identification:
  • GOOGLE_DOCS, GOOGLE_SLIDES, GOOGLE_SPREADSHEET, PDF, PASTED_TEXT, WEB_PAGE, YOUTUBE, MARKDOWN, DOCX, CSV, IMAGE, MEDIA, UNKNOWN
• ArtifactType enum - New str, Enum for type-safe artifact identification:
  • AUDIO, VIDEO, REPORT, QUIZ, FLASHCARDS, MIND_MAP, INFOGRAPHIC, SLIDES, DATA_TABLE, UNKNOWN
• .kind property - Unified type access across Source, Artifact, and SourceFulltext:

  # Works with both enum and string comparison
  source.kind == SourceType.PDF        # True
  source.kind == "pdf"                 # Also True
  artifact.kind == ArtifactType.AUDIO  # True
  artifact.kind == "audio"             # Also True
  

• UnknownTypeWarning - Warning (deduplicated) when API returns unknown type codes
• SourceStatus.PREPARING - New status (5) for sources in upload/preparation phase
• E2E test coverage - Added file upload tests for CSV, MP3, MP4, DOCX, JPG, Markdown with type verification
• --retry flag for generation commands - Automatic retry with exponential backoff on rate limits
  • notebooklm generate audio --retry 3 - Retry up to 3 times on rate limit errors
  • Works with all generate commands (audio, video, quiz, etc.)
• ArtifactStatus.FAILED - New status (code 4) for artifact generation failures
• Centralized exception hierarchy - All errors now inherit from NotebookLMError base class
  • New SourceAddError with detailed failure messages for source operations
  • Granular exception types for better error handling in automation
• CLI share command group - Notebook sharing management from command line
  • notebooklm share - Enable public sharing
  • notebooklm share --revoke - Disable public sharing
• Partial UUID matching for note commands - note get, note delete, etc. now support partial IDs

Fixed

• Silent failures in CLI - Commands now properly report errors instead of failing silently
• Source type emoji display - Improved consistency in source list output

Changed

• Source type detection - Use API-provided type codes as source of truth instead of URL/extension heuristics
• CLI file handling - Simplified to always use add_file() for proper type detection

Removed

• detect_source_type() - Obsolete heuristic function replaced by Source.kind property
• ARTIFACT_TYPE_DISPLAY - Unused constant replaced by get_artifact_type_display()

Deprecated

The following emit DeprecationWarning when accessed and will be removed in v0.4.0. See Migration Guide for upgrade instructions.

• Source.source_type - Use .kind property instead (returns SourceType str enum)
• Artifact.artifact_type - Use .kind property instead (returns ArtifactType str enum)
• Artifact.variant - Use .kind, .is_quiz, or .is_flashcards instead
• SourceFulltext.source_type - Use .kind property instead
• StudioContentType - Use ArtifactType (str enum) for user-facing code

0.2.1 - 2026-01-15

Added

• Authentication diagnostics - New notebooklm auth check command for troubleshooting auth issues
  • Shows storage file location and validity
  • Lists cookies present and their domains
  • Detects NOTEBOOKLM_AUTH_JSON and NOTEBOOKLM_HOME usage
  • --test flag performs network validation
  • --json flag for machine-readable output (CI/CD friendly)
• Structured logging - Comprehensive DEBUG logging across library
  • NOTEBOOKLM_LOG_LEVEL environment variable (DEBUG, INFO, WARNING, ERROR)
  • RPC call timing and method tracking
  • Legacy NOTEBOOKLM_DEBUG_RPC=1 still works
• RPC health monitoring - Automated nightly check for Google API changes
  • Detects RPC method ID mismatches before they cause failures
  • Auto-creates GitHub issues with rpc-breakage label on detection

Fixed

• Cookie domain priority - Prioritize .google.com cookies over regional domains (e.g., .google.co.uk) for more reliable authentication
• YouTube URL parsing - Improved handling of edge cases in YouTube video URLs

Documentation

• Added auth check to CLI reference and troubleshooting guide
• Consolidated CI/CD troubleshooting in development guide
• Added installation instructions to SKILL.md for Claude Code
• Clarified version numbering policy (PATCH vs MINOR)

0.2.0 - 2026-01-14

Added

• Source fulltext extraction - Retrieve the complete indexed text content of any source
  • New client.sources.get_fulltext(notebook_id, source_id) Python API
  • New source fulltext <source_id> CLI command with --json and -o output options
  • Returns SourceFulltext dataclass with content, title, URL, and character count
• Chat citation references - Get detailed source references for chat answers
  • AskResult.references field contains list of ChatReference objects
  • Each reference includes source_id, cited_text, start_char, end_char, chunk_id
  • Use notebooklm ask "question" --json to see references in CLI output
• Source status helper - New source_status_to_str() function for consistent status display
• Quiz and flashcard downloads - Export interactive study materials in multiple formats
  • New download quiz and download flashcards CLI commands
  • Supports JSON, Markdown, and HTML output formats via --format flag
  • Python API: client.artifacts.download_quiz() and client.artifacts.download_flashcards()
• Extended artifact downloads - Download additional artifact types
  • New download report command (exports as Markdown)
  • New download mind-map command (exports as JSON)
  • New download data-table command (exports as CSV)
  • All download commands support --all, --latest, --name, and --artifact selection options

Fixed

• Regional Google domain authentication - SID cookie extraction now works with regional Google domains (e.g., google.co.uk, google.de, google.cn) in addition to google.com
• Artifact completion detection - Media URL availability is now verified before reporting artifact as complete, preventing premature "ready" status
• URL hostname validation - Use proper URL parsing instead of string operations for security

Changed

• Pre-commit checks - Added mypy type checking to required pre-commit workflow

0.1.4 - 2026-01-11

Added

• Source selection for chat and artifacts - Select specific sources when using ask or generate commands
  • New --sources flag accepts comma-separated source IDs or partial matches
  • Works with all generation commands (audio, video, quiz, etc.) and chat
• Research sources table - research status now displays sources in a formatted table instead of just a count

Fixed

• JSON output broken in TTY terminals - --json flag output was including ANSI color codes, breaking JSON parsing for commands like notebooklm list --json
• Warning stacklevel - warnings.warn calls now report correct source location

Infrastructure

• Windows CI testing - Windows is now part of the nightly E2E test matrix
• VCR.py integration - Added recorded HTTP cassette support for faster, deterministic integration tests
• Test coverage improvements - Improved coverage for _artifacts.py (71% → 83%), download.py, and session.py

0.1.3 - 2026-01-10

Fixed

• PyPI README links - Documentation links now work correctly on PyPI
  • Added hatch-fancy-pypi-readme plugin for build-time link transformation
  • Relative links (e.g., docs/troubleshooting.md) are converted to version-tagged GitHub URLs
  • PyPI users now see links pointing to the exact version they installed (e.g., /blob/v0.1.3/docs/...)
• Development repository link - Added prominent source link for PyPI users to find the GitHub repo

0.1.2 - 2026-01-10

Added

• Ruff linter/formatter - Added to development workflow with pre-commit hooks and CI integration
• Multi-version testing - Docker-based test runner script for Python 3.10-3.14 (/matrix skill)
• Artifact verification workflow - New CI workflow runs 2 hours after nightly tests to verify generated artifacts

Changed

• Python version support - Now supports Python 3.10-3.14 (dropped 3.9)
• CI authentication - Use NOTEBOOKLM_AUTH_JSON environment variable (inline JSON, no file writes)

Fixed

• E2E test cleanup - Generation notebook fixture now only cleans artifacts once per session (was deleting artifacts between tests)
• Nightly CI - Fixed pytest marker from -m e2e to -m "not variants" (e2e marker didn't exist)
• macOS CI fix for Playwright version extraction (grep pattern anchoring)
• Python 3.10 test compatibility with mock.patch resolution

Documentation

• Claude Code skill: parallel agent safety guidance
• Claude Code skill: timeout recommendations for all artifact types
• Claude Code skill: clarified -n vs --notebook flag availability

0.1.1 - 2026-01-08

Added

• NOTEBOOKLM_HOME environment variable for custom storage location
• NOTEBOOKLM_AUTH_JSON environment variable for inline authentication (CI/CD friendly)
• Claude Code skill installation via notebooklm skill install

Fixed

• Infographic generation parameter structure
• Mind map artifacts now persist as notes after generation
• Artifact export with proper ExportType enum handling
• Skill install path resolution for package data

Documentation

• PyPI release checklist
• Streamlined README
• E2E test fixture documentation

0.1.0 - 2026-01-06

Added

• Initial release of notebooklm-py - unofficial Python client for Google NotebookLM
• Full notebook CRUD operations (create, list, rename, delete)
• Research polling CLI commands for LLM agent workflows:
  • notebooklm research status - Check research progress (non-blocking)
  • notebooklm research wait --import-all - Wait for completion and import sources
  • notebooklm source add-research --no-wait - Start deep research without blocking
• Multi-artifact downloads with intelligent selection:
  • download audio, download video, download infographic, download slide-deck
  • Multiple artifact selection (--all flag)
  • Smart defaults and intelligent filtering (--latest, --earliest, --name, --artifact-id)
  • File/directory conflict handling (--force, --no-clobber, auto-rename)
  • Preview mode (--dry-run) and structured output (--json)
• Source management:
  • Add URL sources (with YouTube transcript support)
  • Add text sources
  • Add file sources (PDF, TXT, MD, DOCX) via native upload
  • Delete sources
  • Rename sources
• Studio artifact generation:
  • Audio overviews (podcasts) with 4 formats and 3 lengths
  • Video overviews with 9 visual styles
  • Quizzes and flashcards
  • Infographics, slide decks, and data tables
  • Study guides, briefing docs, and reports
• Query/chat interface with conversation history support
• Research agents (Fast and Deep modes)
• Artifact downloads (audio, video, infographics, slides)
• CLI with 27 commands
• Comprehensive documentation (API, RPC, examples)
• 96 unit tests (100% passing)
• E2E tests for all major features

Fixed

• Audio overview instructions parameter now properly supported at RPC position [6][1][0]
• Quiz and flashcard distinction via title-based filtering
• Package renamed from notebooklm-automation to notebooklm
• CLI module renamed from cli.py to notebooklm_cli.py
• Removed orphaned cli_query.py file

⚠️ Beta Release Notice

This is the initial public release of notebooklm-py. While core functionality is tested and working, please note:

• RPC Protocol Fragility: This library uses undocumented Google APIs. Method IDs can change without notice, potentially breaking functionality. See Troubleshooting for debugging guidance.
• Unofficial Status: This is not affiliated with or endorsed by Google.
• API Stability: The Python API may change in future releases as we refine the interface.

Known Issues

• RPC method IDs may change: Google can update their internal APIs at any time, breaking this library. Check the RPC Development Guide for how to identify and update method IDs.
• Rate limiting: Heavy usage may trigger Google's rate limits. Add delays between bulk operations.
• Authentication expiry: CSRF tokens expire after some time. Re-run notebooklm login if you encounter auth errors.
• Large file uploads: Files over 50MB may fail or timeout. Split large documents if needed.