Skip to content

claude-world/notebooklm-skill

notebooklm-research

Verified

Automate source-grounded research with Google NotebookLM. Create notebooks from URLs, text, or local files; ask cited questions; run fast or deep web research; create articles and social drafts; and generate or download audio, video, cinematic video, slides, reports, study guides, quizzes, flashcards, mind maps, infographics, and data tables. Use when a user asks for NotebookLM, cited source analysis, research-to-content workflows, podcasts, slides, study material, artifact generation, RSS digests, or trend research.

FileKindSize
SKILL.mdskill md7.3 KB
examples/research-to-article/README.mdmarkdown1.9 KB
examples/research-to-threads/README.mdmarkdown1.4 KB
examples/trend-to-content/README.mdmarkdown2.0 KB
references/api_surface.mdmarkdown6.4 KB
references/output_formats.mdmarkdown3.2 KB
references/pipeline_recipes.mdmarkdown3.5 KB
scripts/__init__.pyscript0 B
scripts/auth_helper.pyexecutablescript6.0 KB
scripts/common.pyscript26.5 KB
scripts/make_video.shexecutablescript3.7 KB
scripts/notebooklm_client.pyexecutablescript20.2 KB
scripts/pipeline.pyexecutablescript26.1 KB
scripts/skill_installer.pyexecutablescript4.5 KB

references/api_surface.md

View on GitHub
# notebooklm-py compatibility surface

> Project contract: `notebooklm-py>=0.8.5,<0.9`

The private NotebookLM web API changes frequently. Application code should use
`scripts/common.py` instead of calling `notebooklm-py` independently from each public
surface. This document lists the upstream calls the compatibility layer relies on.
`tests/test_upstream_contract.py` checks these signatures, enums, and result types
against the installed release on every CI run.

## Client and authentication

```python
from notebooklm import NotebookLMClient

async with NotebookLMClient.from_storage() as client:
    notebooks = await client.notebooks.list()
```

`from_storage()` is itself an async context manager; do not write
`async with await NotebookLMClient.from_storage()`. Profile resolution is delegated to
`notebooklm.paths.get_storage_path()` and respects `NOTEBOOKLM_PROFILE`,
`NOTEBOOKLM_HOME`, and upstream auth configuration.

The project normalizes upstream authentication exceptions to
`AuthenticationRequired` with a safe message that never includes cookies. A missing
session file raises `FileNotFoundError` upstream and is reported the same way.

## Error contract (0.8.x)

notebooklm-py 0.8 raises instead of returning sentinel values:

- `artifacts.generate_*` raises `RateLimitError` or `RPCError` when NotebookLM refuses
  a generation, instead of returning `GenerationStatus(status="failed")`;
- `research.start` raises `DecodingError` instead of returning `None`;
- expired sessions and HTTP 401/403 artifact downloads raise `AuthError`.

The wrappers let refusals propagate as operation errors (CLI exit 1, MCP tool error,
or a failed pipeline item) and map `AuthError` to `AUTH_REQUIRED` (CLI exit 4). The
older `task_id` and `None` checks remain as defensive guards.

## Notebook and source APIs

| Operation | Upstream call |
|---|---|
| Create | `client.notebooks.create(title=...)` |
| List | `client.notebooks.list()` |
| Delete | `client.notebooks.delete(notebook_id=...)` — success returns `None` |
| Summary | `client.notebooks.get_summary(notebook_id=...)` |
| List sources | `client.sources.list(notebook_id)` |
| Add URL | `add_url(notebook_id, url, wait=True, wait_timeout=...)` |
| Add text | `add_text(notebook_id, title, content, wait=True, wait_timeout=...)` |
| Add file | `add_file(notebook_id, file_path=Path(...), wait=True, wait_timeout=...)` |

Mixed source ingestion validates URLs, checks local files, runs with bounded
concurrency, preserves input order, and returns one result per attempted source.

## Chat API

```python
answer = await client.chat.ask(notebook_id, question="...")
```

The public wrappers retain `answer.answer`, `answer.references`, and
`answer.conversation_id`. Citation objects are serialized without assuming a fixed
set of upstream fields.

## Artifact APIs

The wrappers expose 11 canonical names while mapping them to current upstream
generators and downloaders:

| Canonical type | Generator | Downloader | Default extension |
|---|---|---|---:|
| `audio` | `generate_audio` | `download_audio` | `m4a` |
| `video` | `generate_video` | `download_video` | `mp4` |
| `cinematic` | `generate_cinematic_video` | `download_video` | `mp4` |
| `slides` | `generate_slide_deck` | `download_slide_deck` | `pdf` |
| `report` | `generate_report` | `download_report` | `md` |
| `study-guide` | `generate_study_guide` | `download_report` | `md` |
| `quiz` | `generate_quiz` | `download_quiz` | `json` |
| `flashcards` | `generate_flashcards` | `download_flashcards` | `json` |
| `mind-map` | `generate_mind_map` | `download_mind_map` | `json` |
| `infographic` | `generate_infographic` | `download_infographic` | `png` |
| `data-table` | `generate_data_table` | `download_data_table` | `csv` |

All task-based generators return a `GenerationStatus`. The compatibility layer checks
for `task_id`, waits with
`client.artifacts.wait_for_completion(notebook_id, task_id, timeout=...)`, and accepts
only a `completed` terminal state. `artifacts.generate_mind_map` remains the
synchronous, note-backed mind-map path in 0.8.x and is handled separately; its
`note_id` is the artifact ID used for downloads.

Artifacts are listed with `client.artifacts.list(notebook_id, ArtifactType | None)`.
Signed download URLs are deliberately omitted from serialized output. Downloads pass
the exact selected `artifact_id` where supplied, validate output formats, reject
symlinks, and refuse accidental overwrites.

### Type-specific enum options

- audio: `AudioFormat`, `AudioLength`
- video: `VideoFormat` (including `SHORT`), `VideoStyle`, plus custom `style_prompt`
- slides: `SlideDeckFormat`, `SlideDeckLength`
- report: `ReportFormat`, plus `custom_prompt`
- quiz/flashcards: `QuizQuantity` (including `MORE`), `QuizDifficulty`
- infographic: `InfographicOrientation`, `InfographicDetail`, `InfographicStyle`

User-facing kebab-case values are validated and converted to upstream enums. The
wrappers reject upstream-invalid combinations before any network call: a custom
video style needs `style_prompt`, cinematic videos take no `style_prompt`, and short
videos have a fixed style.

## Research API

The complete lifecycle is:

```python
started = await client.research.start(notebook_id, query=query, source="web", mode="deep")
final = await client.research.wait_for_completion(notebook_id, task_id=started.task_id, timeout=1800)
imported = await client.research.import_sources(notebook_id, started.task_id, final.sources[:max_sources])
```

`mode` is `"fast"` or `"deep"`. `ResearchTask` and `ResearchSource` are attribute-only
dataclasses in 0.8.x; the wrappers never subscript them.

The wrapper validates terminal status, caps imported sources, and supports returning
immediately with the task ID. It never reports a non-terminal or failed task as
completed.

## Serialization contract

Serialization accepts mappings, sequences, dataclasses, enums, paths, dates, and
typed upstream objects. Stable public subsets are used for notebooks, sources, and
artifacts. Unknown non-private fields are retained only by the generic serializer.

## Upgrade checklist

When raising the upper dependency bound:

1. inspect every signature listed above;
2. run the contract tests against both the minimum and newest supported versions;
3. verify enum names/values and terminal states;
4. verify profile path behavior and authentication exceptions;
5. exercise one real read-only session plus an artifact list;
6. update this file, CLI help snapshots, and the version bound together.
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall