pynotebooklm 0.21.0
Production-grade Python library for NotebookLM automation with 31 tools
License: Apache-2.0
Requires Python: <4.0,>=3.10
Keywords: notebooklm, google, automation, podcast, ai, notebook

# PyNotebookLM

<!--
📄 DOCUMENTATION SCOPE: This file is the user-facing README for the project. It should contain:
- Installation instructions, quick start guides, and usage examples
- Feature highlights and CLI command references
- How-to-run development commands (tests, linting, etc.)
- Project structure overview for end users

DO NOT include here: Detailed implementation plans, architectural decisions, or internal technical details. Those belong in `docs/architecture.md` and `docs/implementation_plan.md`.
-->

[![CI](https://img.shields.io/github/actions/workflow/status/Experto-AI/pynotebooklm/ci.yml?branch=main)](https://github.com/Experto-AI/pynotebooklm/actions)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/pynotebooklm.svg)](https://pypi.org/project/pynotebooklm/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Production-grade Python library for **Google NotebookLM** automation.

Documentation: https://github.com/Experto-AI/pynotebooklm

## Features

- 🔐 **Secure Authentication** - Browser-based Google login with cookie persistence
- 📓 **Notebook Management** - Create, list, rename, and delete notebooks
- 📰 **Source Management** - Add URLs, YouTube videos, Google Drive docs, and text
- 🔍 **Research & Analysis** - Query notebooks and discover related sources (Web/Google Drive)
- 🧠 **Mind Maps** - Generate, save, list, and export mind maps (JSON/OPML/FreeMind)
- 🎙️ **Content Generation** - Create audio overviews (podcasts), videos, infographics, and slides
- 📚 **Study Tools** - Create flashcards, quizzes, and briefing documents

## Installation

```bash
pip install pynotebooklm
```

Or with Poetry:

```bash
poetry add pynotebooklm
```

### Install Playwright Browsers

After installing, you need to install the Playwright browser:

```bash
playwright install chromium
```

## Quick Start

### 1. Authenticate

First, login to NotebookLM with your Google account:

```bash
pynotebooklm auth login
```

This opens a browser window for you to login. Cookies are saved to `~/.pynotebooklm/auth.json`.

### 2. Verify Authentication

```bash
pynotebooklm auth check
```

### 3. Use the Library

```python
import asyncio
from pynotebooklm import NotebookLMClient

async def main():
    async with NotebookLMClient() as client:
        # List notebooks
        notebooks = await client.notebooks.list()
        for nb in notebooks:
            print(f"{nb.name} ({nb.id})")

asyncio.run(main())
```

## CLI Commands

### Authentication

```bash
pynotebooklm auth login              # Login with Google account (opens browser)
pynotebooklm auth check              # Check authentication status
pynotebooklm auth logout             # Clear saved authentication
```

### Notebooks

```bash
pynotebooklm notebooks list                        # List all notebooks
pynotebooklm notebooks list --detailed             # With source count and dates
pynotebooklm notebooks create "My Notebook"        # Create a new notebook
pynotebooklm notebooks get <notebook_id>           # Get detailed notebook info with sources
pynotebooklm notebooks describe <notebook_id>      # Get AI-generated summary and topics
pynotebooklm notebooks rename <notebook_id> "New Name"  # Rename a notebook
pynotebooklm notebooks delete <notebook_id>        # Delete a notebook
pynotebooklm notebooks delete <notebook_id> -f     # Delete without confirmation
```

### Sources

```bash
pynotebooklm sources add <notebook_id> <url>               # Add URL source (Web or YouTube)
pynotebooklm sources add-text <notebook_id> "text"         # Add plain text source
pynotebooklm sources add-drive <notebook_id> <drive_id>    # Add Google Drive source
pynotebooklm sources list <notebook_id>                    # List sources in notebook
pynotebooklm sources list <notebook_id> --check-freshness  # Check if Drive sources are up-to-date
pynotebooklm sources describe <source_id>                  # AI-generated summary and keywords
pynotebooklm sources get-text <source_id>                  # Extract raw indexed text
pynotebooklm sources sync <source_id>                      # Sync stale Drive source
pynotebooklm sources delete <notebook_id> <source_id>      # Delete a source
pynotebooklm sources delete <notebook_id> <source_id> -f   # Delete without confirmation
```

### Research Discovery

```bash
pynotebooklm research start <notebook_id> "topic"              # Fast web research
pynotebooklm research start <notebook_id> "topic" --deep       # Deep research (more comprehensive)
pynotebooklm research start <notebook_id> "topic" --source drive   # Search Google Drive
pynotebooklm research poll <notebook_id>                       # Check status and get results
pynotebooklm research poll <notebook_id> --auto-import         # Poll & auto-import when done
pynotebooklm research import <notebook_id>                     # Import all discovered sources
pynotebooklm research import <notebook_id> --indices 0,1,2     # Import specific sources
```

### Mind Maps

```bash
pynotebooklm mindmap create <notebook_id>                      # Create from all sources
pynotebooklm mindmap create <notebook_id> --title "My Map"     # With custom title
pynotebooklm mindmap list <notebook_id>                        # List existing maps
pynotebooklm mindmap export <notebook_id> <map_id> -f json     # Export to JSON
pynotebooklm mindmap export <notebook_id> <map_id> -f opml     # Export to OPML
pynotebooklm mindmap export <notebook_id> <map_id> -f freemind # Export to FreeMind (.mm)
```

### Chat & Query

```bash
pynotebooklm query ask <notebook_id> "question"                # Ask a question
pynotebooklm query ask <notebook_id> "question" --sources <ids> # Scope to specific sources
pynotebooklm query ask <notebook_id> "question" -c <id>        # Follow-up in conversation
pynotebooklm query summary <notebook_id>                       # Get AI summary
pynotebooklm query briefing <notebook_id>                      # Create briefing document
pynotebooklm query configure <notebook_id> --goal learning     # Set conversation goal
pynotebooklm query configure <notebook_id> --length longer     # Set response length
```

### Content Generation

```bash
# Audio Overview (Podcast)
pynotebooklm generate audio <notebook_id>                      # Generate with defaults
pynotebooklm generate audio <notebook_id> --format deep_dive   # Format: deep_dive, brief, critique, debate
pynotebooklm generate audio <notebook_id> --length short       # Length: short, default, long
pynotebooklm generate audio <notebook_id> --language es        # Language: en, es, fr, de, ja, etc.
pynotebooklm generate audio <notebook_id> --focus "key topics" # Focus prompt for AI

# Video Overview
pynotebooklm generate video <notebook_id>                      # Generate with defaults
pynotebooklm generate video <notebook_id> --format explainer   # Format: explainer, brief
pynotebooklm generate video <notebook_id> --style anime        # Style: auto_select, classic, whiteboard, kawaii, anime, watercolor, retro_print, heritage, paper_craft

# Infographic
pynotebooklm generate infographic <notebook_id>                    # Generate with defaults
pynotebooklm generate infographic <notebook_id> --orientation portrait  # Orientation: landscape, portrait, square
pynotebooklm generate infographic <notebook_id> --detail detailed  # Detail: concise, standard, detailed

# Slide Deck
pynotebooklm generate slides <notebook_id>                         # Generate with defaults
pynotebooklm generate slides <notebook_id> --format presenter_slides  # Format: detailed_deck, presenter_slides
pynotebooklm generate slides <notebook_id> --length short          # Length: short, default
```

```

### Study Tools

```bash
# Flashcards
pynotebooklm study flashcards <notebook_id>                    # Generate flashcards
pynotebooklm study flashcards <notebook_id> --difficulty hard  # Difficulty: easy, medium, hard

# Quiz
pynotebooklm study quiz <notebook_id>                          # Generate quiz (default 2 questions)
pynotebooklm study quiz <notebook_id> --questions 10           # Number of questions
pynotebooklm study quiz <notebook_id> --difficulty 3           # Difficulty: 1 (easy) to 3 (hard)

# Data Table
pynotebooklm study table <notebook_id> --description "Extract dates"     # Extract structured data
pynotebooklm study table <notebook_id> --description "..." --language es # Output language

pynotebooklm studio status <notebook_id> # shows study artifacts
```

### Studio (Artifact Management)

```bash
pynotebooklm studio list <notebook_id>             # List all artifacts (Briefings, Audio, Video, etc.)
pynotebooklm studio status <notebook_id>           # Detailed status with download URLs
pynotebooklm studio delete <artifact_id>           # Delete an artifact (with confirmation)
pynotebooklm studio delete <artifact_id> --force   # Delete without confirmation
```

## Troubleshooting

### Authentication Errors

- Run `pynotebooklm auth login` to refresh cookies.
- Delete `~/.pynotebooklm/auth.json` if cookies are corrupted, then login again.

### Playwright Issues

- Ensure the browser is installed: `playwright install chromium`
- On Linux, install required system deps (see `Dockerfile` for a reference list).

### Debugging Requests

- Enable verbose logging with `PYNOTEBOOKLM_DEBUG=1`.
- Enable structured telemetry with `PYNOTEBOOKLM_TELEMETRY=1`.


## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/Experto-AI/pynotebooklm.git
cd pynotebooklm

# Install dependencies
poetry install

# Install Playwright browsers
poetry run playwright install chromium
```

### Running Tests

```bash
# Run all unit tests
poetry run pytest tests/unit/ -v

# Run with coverage
poetry run pytest tests/unit/ -v --cov=src/pynotebooklm

# Run specific test file
poetry run pytest tests/unit/test_auth.py -v
```

### Linting and Formatting

```bash
# Lint with ruff
poetry run ruff check src tests

# Format with black
poetry run black src tests

# Type check with mypy
poetry run mypy src
```

## Project Structure

```
pynotebooklm/
├── src/pynotebooklm/
│   ├── __init__.py        # Public API exports
│   ├── auth.py            # Authentication manager
│   ├── session.py         # Browser session management
│   ├── api.py             # Low-level RPC wrapper
│   ├── notebooks.py       # Notebook management
│   ├── sources.py         # Source management
│   ├── research.py        # Research discovery
│   ├── mindmaps.py        # Mind map generation
│   ├── study.py           # Study tools (flashcards, quiz, tables)
│   ├── content.py         # Content generation (audio, video, etc.)
│   ├── chat.py            # Chat and query functionality
│   ├── models.py          # Pydantic data models
│   ├── exceptions.py      # Custom exceptions
│   └── cli.py             # CLI interface
├── tests/
│   ├── unit/              # Unit tests (457)
│   ├── integration/       # Integration tests (192)
│   └── fixtures/          # Mock responses
└── docs/                  # Documentation
```

## How It Works

PyNotebookLM uses browser automation (Playwright) to interact with NotebookLM's internal APIs:

1. **Authentication**: Opens a browser for Google login, extracts cookies
2. **Session**: Creates a headless browser session with injected cookies
3. **API Calls**: Executes `fetch()` requests via `page.evaluate()` in browser context
4. **RPC Protocol**: Communicates using NotebookLM's internal RPC format

This approach provides:
- ✅ Full feature access (all 31 tools)
- ✅ No API keys needed
- ✅ Works with consumer Google accounts
- ⚠️ Requires browser automation
- ⚠️ Cookie refresh needed every 2-4 weeks

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## Disclaimer

This is an unofficial library. It uses NotebookLM's internal APIs which may change without notice. Use at your own risk.