Skip to content

Latest commit

 

History

History
333 lines (280 loc) · 19 KB

CHANGELOG.md

File metadata and controls

333 lines (280 loc) · 19 KB

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.