notebooklm-py 0.1.1__tar.gz

notebooklm_py-0.1.1/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pytest:*)",
+      "Bash(pip install:*)",
+      "Bash(python3 -m pip:*)",
+      "Bash(uv pip install:*)",
+      "Bash(grep:*)",
+      "Bash(tree:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(python3:*)",
+      "Bash(source:*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(curl:*)"
+    ]
+  }
+}

notebooklm_py-0.1.1/.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.1/.github/workflows/nightly.yml

@@ -0,0 +1,64 @@
+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: Set up authentication
+      env:
+        NOTEBOOKLM_STORAGE_STATE: ${{ secrets.NOTEBOOKLM_STORAGE_STATE }}
+      run: |
+        mkdir -p ~/.notebooklm
+        echo "$NOTEBOOKLM_STORAGE_STATE" > ~/.notebooklm/storage_state.json
+
+    - name: Run E2E tests
+      env:
+        NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID: ${{ secrets.NOTEBOOKLM_READ_ONLY_NOTEBOOK_ID }}
+      run: pytest tests/e2e -m e2e -v --tb=short
+
+    - name: Clean up authentication
+      if: always()
+      run: rm -rf ~/.notebooklm

notebooklm_py-0.1.1/.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.1/.github/workflows/test.yml

@@ -0,0 +1,80 @@
+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/
+
+    - 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.9", "3.10", "3.11", "3.12"]
+
+    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.1/.gitignore

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

notebooklm_py-0.1.1/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.9+)
+```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.1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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).
+
+## [0.1.0] - 2026-01-08
+
+### 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.
+
+[0.1.0]: https://github.com/teng-lin/notebooklm-py/releases/tag/v0.1.0

notebooklm_py-0.1.1/CLAUDE.md

@@ -0,0 +1,168 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**IMPORTANT:** Follow documentation rules in [CONTRIBUTING.md](CONTRIBUTING.md) - especially the file creation and naming conventions.
+
+## Project Overview
+
+`notebooklm-py` is an unofficial Python client for Google NotebookLM that uses undocumented RPC APIs. The library enables programmatic automation of NotebookLM features including notebook management, source integration, AI querying, and studio artifact generation (podcasts, videos, quizzes, etc.).
+
+**Critical constraint**: This uses Google's internal `batchexecute` RPC protocol with obfuscated method IDs that Google can change at any time. All RPC method IDs in `src/notebooklm/rpc/types.py` are undocumented and subject to breakage.
+
+## Development Commands
+
+```bash
+# Create/recreate venv with uv (recommended - relocatable venvs)
+uv venv .venv
+uv pip install -e ".[all]"
+playwright install chromium
+
+# Activate virtual environment
+source .venv/bin/activate
+
+# Run all tests (excluding e2e by default)
+pytest
+
+# Run with coverage
+pytest --cov
+
+# Run e2e tests (requires authentication)
+pytest tests/e2e -m e2e
+
+# CLI testing
+notebooklm --help
+```
+
+## Architecture
+
+### Layered Design
+
+```
+CLI Layer (cli/)
+    ↓
+Client Layer (client.py, _*.py APIs)
+    ↓
+Core Layer (_core.py)
+    ↓
+RPC Layer (rpc/)
+```
+
+1. **RPC Layer** (`src/notebooklm/rpc/`):
+   - `types.py`: All RPC method IDs and enums (source of truth)
+   - `encoder.py`: Request encoding
+   - `decoder.py`: Response parsing
+
+2. **Core Layer** (`src/notebooklm/_core.py`):
+   - HTTP client management
+   - RPC call abstraction
+   - Request counter handling
+
+3. **Client Layer** (`src/notebooklm/client.py`, `_*.py`):
+   - `NotebookLMClient`: Main async client with namespaced APIs
+   - `_notebooks.py`, `_sources.py`, `_artifacts.py`, etc.: Domain APIs
+
+4. **CLI Layer** (`src/notebooklm/cli/`):
+   - Modular Click commands
+   - `session.py`, `notebook.py`, `source.py`, `generate.py`, etc.
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `client.py` | Main `NotebookLMClient` class |
+| `_core.py` | HTTP and RPC infrastructure |
+| `_notebooks.py` | `client.notebooks` API |
+| `_sources.py` | `client.sources` API |
+| `_artifacts.py` | `client.artifacts` API |
+| `_chat.py` | `client.chat` API |
+| `rpc/types.py` | RPC method IDs (source of truth) |
+| `auth.py` | Authentication handling |
+| `cli/` | CLI command modules |
+
+### Repository Structure
+
+```
+src/notebooklm/
+├── __init__.py          # Public exports
+├── client.py            # NotebookLMClient
+├── auth.py              # Authentication
+├── types.py             # Dataclasses
+├── _core.py             # Core infrastructure
+├── _notebooks.py        # NotebooksAPI
+├── _sources.py          # SourcesAPI
+├── _artifacts.py        # ArtifactsAPI
+├── _chat.py             # ChatAPI
+├── _research.py         # ResearchAPI
+├── _notes.py            # NotesAPI
+├── rpc/                 # RPC protocol layer
+│   ├── types.py         # Method IDs and enums
+│   ├── encoder.py       # Request encoding
+│   └── decoder.py       # Response parsing
+└── cli/                 # CLI implementation
+    ├── __init__.py
+    ├── helpers.py       # Shared utilities
+    ├── session.py       # login, use, status, clear
+    ├── notebook.py      # list, create, delete, rename
+    ├── source.py        # source add, list, delete
+    ├── artifact.py      # artifact commands
+    ├── generate.py      # generate audio, video, etc.
+    ├── download.py      # download commands
+    ├── chat.py          # ask, configure, history
+    └── note.py          # note commands
+```
+
+## API Patterns
+
+### Client Usage
+
+```python
+# Correct pattern - uses 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)
+    status = await client.artifacts.generate_audio(nb_id)
+```
+
+### CLI Structure
+
+Commands are organized as:
+- **Top-level**: `login`, `use`, `status`, `clear`, `list`, `create`, `ask`
+- **Grouped**: `source add`, `artifact list`, `generate audio`, `download video`, `note create`
+
+## Testing Strategy
+
+- **Unit tests** (`tests/unit/`): Test encoding/decoding, no network
+- **Integration tests** (`tests/integration/`): Mock HTTP responses
+- **E2E tests** (`tests/e2e/`): Real API, require auth, marked `@pytest.mark.e2e`
+
+### E2E Test Status
+
+- ✅ Notebook operations (list, create, rename, delete)
+- ✅ Source operations (add URL/text/YouTube, rename)
+- ✅ Download operations (audio, video, infographic, slides)
+- ⚠️ Artifact generation may fail due to rate limiting
+
+## Common Pitfalls
+
+1. **RPC method IDs change**: Check network traffic and update `rpc/types.py`
+2. **Nested list structures**: Params are position-sensitive. Check existing implementations.
+3. **Source ID nesting**: Different methods need `[id]`, `[[id]]`, `[[[id]]]`, or `[[[[id]]]]`
+4. **CSRF tokens expire**: Use `client.refresh_auth()` or re-run `notebooklm login`
+5. **Rate limiting**: Add delays between bulk operations
+
+## Documentation
+
+All docs use lowercase-kebab naming in `docs/`:
+- `docs/getting-started.md` - Installation and first workflow
+- `docs/cli-reference.md` - CLI commands
+- `docs/python-api.md` - Python API reference
+- `docs/configuration.md` - Storage and settings
+- `docs/troubleshooting.md` - Known issues
+- `docs/contributing/` - Architecture, debugging, testing guides
+
+## When to Suggest CLI vs API
+
+- **CLI**: Quick tasks, shell scripts, LLM agent automation
+- **Python API**: Application integration, complex workflows, async operations