notebooklm-py 0.1.2__tar.gz

notebooklm_py-0.1.2/.env.example

@@ -0,0 +1,35 @@
+# NotebookLM Configuration
+# Copy this file to .env and fill in your values
+
+# =============================================================================
+# Configuration Environment Variables
+# =============================================================================
+
+# Custom home directory for all config files (optional)
+# Default: ~/.notebooklm
+# NOTEBOOKLM_HOME=/custom/path
+
+# Inline authentication JSON for CI/CD (optional)
+# When set, authentication is read from this variable instead of a file
+# Get the value from: cat $NOTEBOOKLM_HOME/storage_state.json (default: ~/.notebooklm)
+# NOTEBOOKLM_AUTH_JSON='{"cookies":[...]}'
+
+# Enable RPC debug logging (optional)
+# NOTEBOOKLM_DEBUG_RPC=1
+
+# =============================================================================
+# E2E Testing Configuration
+# =============================================================================
+
+# Required for E2E tests: Your READ-ONLY test notebook ID
+# Create a notebook at https://notebooklm.google.com with:
+#   - Multiple sources (text, URL, PDF, etc.)
+#   - Some pre-generated artifacts (audio, quiz, etc.)
+# Copy the notebook ID from the URL: notebooklm.google.com/notebook/YOUR_ID
+# This notebook is used for READ-ONLY tests (list, get, download operations)
+NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID=your-notebook-id-here
+
+# Optional: Generation test notebook ID
+# If not set, a notebook will be auto-created and its ID stored in
+# NOTEBOOKLM_HOME/generation_notebook_id for reuse across test runs.
+# NOTEBOOKLM_GENERATION_NOTEBOOK_ID=your-generation-notebook-id

notebooklm_py-0.1.2/.github/workflows/nightly.yml

@@ -0,0 +1,65 @@
+name: Nightly E2E Tests
+
+on:
+  schedule:
+    # Run at 6 AM UTC daily (10 PM PST / 1 AM EST)
+    - cron: '0 6 * * *'
+  workflow_dispatch:  # Allow manual trigger
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    # Only run on main repo (not forks) due to secrets requirement
+    if: github.repository == 'teng-lin/notebooklm-py'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[all]"
+
+    - name: Get Playwright version
+      id: playwright-version
+      run: |
+        echo "version=$(pip show playwright | grep '^Version:' | cut -d' ' -f2)" >> $GITHUB_OUTPUT
+
+    - name: Cache Playwright browsers
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-ubuntu-latest-${{ steps.playwright-version.outputs.version }}
+
+    - name: Install Playwright browsers and dependencies
+      run: |
+        playwright install chromium
+        playwright install-deps
+
+    - name: Debug - Print notebook IDs
+      env:
+        NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID }}
+        NOTEBOOKLM_GENERATION_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_GENERATION_NOTEBOOK_ID }}
+      run: |
+        echo "READ_ONLY_NOTEBOOK_ID: $NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID"
+        echo "GENERATION_NOTEBOOK_ID: $NOTEBOOKLM_GENERATION_NOTEBOOK_ID"
+        echo "READ_ONLY length: ${#NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID}"
+        echo "GENERATION length: ${#NOTEBOOKLM_GENERATION_NOTEBOOK_ID}"
+
+    - name: Run E2E tests
+      env:
+        NOTEBOOKLM_AUTH_JSON: ${{ secrets.NOTEBOOKLM_AUTH_JSON }}
+        NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID }}
+        NOTEBOOKLM_GENERATION_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_GENERATION_NOTEBOOK_ID }}
+      run: pytest tests/e2e -m "not variants" -s -v --tb=short

notebooklm_py-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

notebooklm_py-0.1.2/.github/workflows/test.yml

@@ -0,0 +1,83 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[all]"
+
+    - name: Run linting
+      run: ruff check src/ tests/
+
+    - name: Check formatting
+      run: ruff format --check src/ tests/
+
+    - name: Run type checking
+      run: mypy src/notebooklm --ignore-missing-imports
+
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    needs: quality
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[all]"
+
+    - name: Get Playwright version
+      id: playwright-version
+      run: |
+        echo "version=$(pip show playwright | grep '^Version:' | cut -d' ' -f2)" >> $GITHUB_OUTPUT
+
+    - name: Cache Playwright browsers
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-${{ matrix.os }}-${{ steps.playwright-version.outputs.version }}
+
+    - name: Install Playwright browsers
+      run: playwright install chromium
+
+    - name: Install Playwright system dependencies (Linux)
+      if: runner.os == 'Linux'
+      run: playwright install-deps
+
+    - name: Run tests with coverage
+      run: pytest --cov=src/notebooklm --cov-report=term-missing --cov-fail-under=70

notebooklm_py-0.1.2/.github/workflows/verify-artifacts.yml

@@ -0,0 +1,123 @@
+name: Verify Generated Artifacts
+
+on:
+  schedule:
+    # Run at 8 AM UTC daily (2 hours after nightly e2e tests)
+    - cron: '0 8 * * *'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  verify:
+    name: Verify Artifacts
+    runs-on: ubuntu-latest
+    if: github.repository == 'teng-lin/notebooklm-py'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e "."
+
+    - name: Verify artifacts exist
+      env:
+        NOTEBOOKLM_AUTH_JSON: ${{ secrets.NOTEBOOKLM_AUTH_JSON }}
+        NOTEBOOKLM_GENERATION_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_GENERATION_NOTEBOOK_ID }}
+      run: |
+        python -c "
+        import asyncio
+        import os
+        import sys
+        from notebooklm import NotebookLMClient
+
+        # Type ID to display name mapping
+        TYPE_NAMES = {
+            1: 'Audio',
+            2: 'Report',  # Study Guide, Briefing Doc, Blog Post
+            3: 'Video',
+            4: 'Quiz/Flashcards',
+            5: 'Mind Map',
+            7: 'Infographic',
+            8: 'Slide Deck',
+            9: 'Data Table',
+        }
+
+        # Expected type IDs from generation tests
+        # Note: Type 2 is Reports (study guide), Type 4 is Quiz+Flashcards
+        EXPECTED_TYPES = {1, 2, 3, 4, 5, 7, 8, 9}
+
+        async def verify():
+            async with await NotebookLMClient.from_storage() as client:
+                nb_id = os.environ['NOTEBOOKLM_GENERATION_NOTEBOOK_ID']
+                print(f'Checking notebook: {nb_id}')
+
+                # List artifacts
+                artifacts = await client.artifacts.list(nb_id)
+                print(f'\nTotal artifacts: {len(artifacts)}')
+
+                # Group by type and status
+                by_type = {}
+                for a in artifacts:
+                    key = a.artifact_type
+                    if key not in by_type:
+                        by_type[key] = []
+                    by_type[key].append(a)
+
+                print('\nArtifacts by type:')
+                for t in sorted(by_type.keys()):
+                    items = by_type[t]
+                    type_name = TYPE_NAMES.get(t, f'Unknown({t})')
+                    print(f'  {type_name} (type {t}): {len(items)}')
+                    for a in items:
+                        status = a.status or 'unknown'
+                        variant_info = f', variant={a.variant}' if a.variant else ''
+                        print(f'    - {a.title} ({status}{variant_info})')
+
+                # Check expected types
+                found = set(by_type.keys())
+                missing = EXPECTED_TYPES - found
+
+                print(f'\nExpected types: {len(EXPECTED_TYPES)}')
+                print(f'Found types: {len(found)}')
+
+                if missing:
+                    missing_names = [TYPE_NAMES.get(t, str(t)) for t in missing]
+                    print(f'\nWARNING: Missing artifact types: {missing_names}')
+
+                # Check for completed artifacts
+                completed = sum(1 for a in artifacts if a.status == 'completed')
+                processing = sum(1 for a in artifacts if a.status == 'processing')
+                failed = sum(1 for a in artifacts if a.status == 'failed')
+
+                print(f'\nStatus summary:')
+                print(f'  Completed: {completed}')
+                print(f'  Processing: {processing}')
+                print(f'  Failed: {failed}')
+
+                # List notes
+                notes = await client.notes.list(nb_id)
+                print(f'\nTotal notes: {len(notes)}')
+                for n in notes[:10]:
+                    print(f'  - {n.title or \"(untitled)\"}')
+                if len(notes) > 10:
+                    print(f'  ... and {len(notes) - 10} more')
+
+                # Fail if too many failures or no artifacts at all
+                if len(artifacts) == 0:
+                    print('\nERROR: No artifacts found!')
+                    sys.exit(1)
+                if failed > len(artifacts) // 2:
+                    print(f'\nERROR: Too many failed artifacts ({failed}/{len(artifacts)})')
+                    sys.exit(1)
+
+                print('\nVerification complete!')
+
+        asyncio.run(verify())
+        "

notebooklm_py-0.1.2/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.class
+.venv/
+env/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.env
+.notebooklm/
+captured_rpcs/
+.worktrees/
+.worktree/
+.sisyphus/
+.claude/

notebooklm_py-0.1.2/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

notebooklm_py-0.1.2/AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md
+
+Guidelines for AI agents working on `notebooklm-py`.
+
+**IMPORTANT:** Follow documentation rules in [CONTRIBUTING.md](CONTRIBUTING.md) - especially the file creation and naming conventions.
+
+## Quick Reference
+
+See [CLAUDE.md](CLAUDE.md) for full project context. Essential commands:
+
+```bash
+source .venv/bin/activate    # Always activate venv first
+pytest                       # Run tests
+pip install -e ".[all]"      # Install in dev mode
+```
+
+## Code Style Guidelines
+
+### Type Annotations (Python 3.10+)
+```python
+def process(items: list[str]) -> dict[str, Any]: ...
+async def query(notebook_id: str, source_ids: Optional[list[str]] = None): ...
+
+# Use TYPE_CHECKING for circular imports
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from ..api_client import NotebookLMClient
+```
+
+### Async Patterns
+```python
+# All client methods are async - use namespaced APIs
+async with await NotebookLMClient.from_storage() as client:
+    notebooks = await client.notebooks.list()
+    await client.sources.add_url(nb_id, url)
+    result = await client.chat.ask(nb_id, question)
+```
+
+### Data Structures
+```python
+@dataclass
+class Notebook:
+    id: str
+    title: str
+    created_at: Optional[datetime] = None
+
+    @classmethod
+    def from_api_response(cls, data: list[Any]) -> "Notebook": ...
+```
+
+### Enums for Constants
+```python
+class RPCMethod(str, Enum):
+    LIST_NOTEBOOKS = "wXbhsf"
+
+class AudioFormat(int, Enum):
+    DEEP_DIVE = 1
+```
+
+### Error Handling
+```python
+class RPCError(Exception):
+    def __init__(self, message: str, rpc_id: Optional[str] = None, code: Optional[Any] = None):
+        self.rpc_id, self.code = rpc_id, code
+        super().__init__(message)
+
+raise RPCError(f"No result found for RPC ID: {rpc_id}", rpc_id=rpc_id)
+raise ValueError(f"Invalid YouTube URL: {url}")  # For validation
+```
+
+### Docstrings
+```python
+def decode_response(raw_response: str, rpc_id: str, allow_null: bool = False) -> Any:
+    """Complete decode pipeline: strip prefix -> parse chunks -> extract result.
+
+    Args:
+        raw_response: Raw response text from batchexecute
+        rpc_id: RPC method ID to extract result for
+        allow_null: If True, return None instead of raising when null
+
+    Returns:
+        Decoded result data
+
+    Raises:
+        RPCError: If RPC returned an error or result not found
+    """
+```
+
+## Testing Patterns
+
+```python
+# Class-based for related tests
+class TestDecodeResponse:
+    def test_full_decode_pipeline(self): ...
+
+# Markers
+@pytest.mark.e2e      # End-to-end (requires auth)
+@pytest.mark.slow     # Long-running (audio/video)
+@pytest.mark.asyncio  # Async tests
+
+# Async tests
+@pytest.mark.asyncio
+async def test_list_notebooks(self, client):
+    notebooks = await client.notebooks.list()
+    assert isinstance(notebooks, list)
+```
+
+## Do NOT
+
+- Suppress type errors with `# type: ignore`
+- Commit `.env` files or credentials
+- Add dependencies without updating `pyproject.toml`
+- Change RPC method IDs without verifying via network capture
+- Delete or modify e2e tests without running them
+- Create documentation files without following CONTRIBUTING.md rules

notebooklm_py-0.1.2/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [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](docs/troubleshooting.md) 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 Capture](docs/reference/internals/rpc-capture.md) 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.
+
+[Unreleased]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/teng-lin/notebooklm-py/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/teng-lin/notebooklm-py/releases/tag/v0.1.0