@biggora/claude-plugins 1.0.0 → 1.1.0

package/src/skills/notebook-lm/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: notebooklm
+description: |
+  Automate Google NotebookLM via the notebooklm-py Python library. Use this skill whenever the user wants to:
+  - Create, manage, or delete NotebookLM notebooks
+  - Add sources (URLs, YouTube, PDFs, files, text, Google Drive) to a notebook
+  - Ask questions / chat with notebook content
+  - Generate content: Audio Overview (podcast), Video Overview, Quiz, Flashcards, Slide Deck, Infographic, Report, Data Table, Mind Map
+  - Download generated artifacts (MP3, MP4, PDF, PNG, CSV, JSON, Markdown)
+  - Run web/Drive research and auto-import results
+  - Manage sharing, notes, and source full-text extraction
+  - Automate any NotebookLM workflow programmatically
+
+  Trigger this skill for ANY request involving NotebookLM, notebooklm-py, Google NotebookLM automation, podcast/audio overview generation from notes, or bulk research pipelines.
+---
+
+# NotebookLM Skill
+
+Provides full programmatic access to Google NotebookLM via the unofficial `notebooklm-py` library. Supports Python API and CLI — use the Python API for complex or multi-step workflows, CLI for quick one-off tasks.
+
+## Prerequisites
+
+```bash
+pip install "notebooklm-py[browser]"
+playwright install chromium
+
+# First-time auth (opens browser)
+notebooklm login
+```
+
+**Auth via env variable (CI/CD, no browser):**
+```bash
+export NOTEBOOKLM_AUTH_JSON='{"cookies": [...]}'
+```
+
+Read `references/auth.md` for detailed authentication setup.
+
+## Quick Start Pattern
+
+```python
+import asyncio
+from notebooklm import NotebookLMClient
+
+async def main():
+    async with await NotebookLMClient.from_storage() as client:
+        nb = await client.notebooks.create("My Research")
+        await client.sources.add_url(nb.id, "https://example.com/article", wait=True)
+        result = await client.chat.ask(nb.id, "Summarize the main points")
+        print(result.answer)
+
+asyncio.run(main())
+```
+
+## API Reference Summary
+
+### Client Structure
+```
+NotebookLMClient
+├── .notebooks   → NotebooksAPI
+├── .sources     → SourcesAPI
+├── .artifacts   → ArtifactsAPI
+├── .chat        → ChatAPI
+├── .research    → ResearchAPI
+├── .notes       → NotesAPI
+└── .sharing     → SharingAPI
+```
+
+### Notebooks (`client.notebooks`)
+| Method | Description |
+|--------|-------------|
+| `list()` | List all notebooks |
+| `create(title)` | Create new notebook → `Notebook` |
+| `get(notebook_id)` | Get notebook details |
+| `delete(notebook_id)` | Delete notebook |
+| `rename(notebook_id, new_title)` | Rename notebook |
+| `get_description(notebook_id)` | Get AI summary + suggested topics |
+
+### Sources (`client.sources`)
+| Method | Description |
+|--------|-------------|
+| `add_url(nb_id, url, wait=True)` | Add URL/YouTube source |
+| `add_file(nb_id, path, wait=True)` | Add local file (PDF, txt, md, docx, etc.) |
+| `add_text(nb_id, text, title, wait=True)` | Add pasted text |
+| `add_drive(nb_id, drive_id, title)` | Add Google Drive document |
+| `list(nb_id)` | List all sources |
+| `get(nb_id, source_id)` | Get source details |
+| `fulltext(nb_id, source_id)` | Get indexed text content |
+| `refresh(nb_id, source_id)` | Refresh URL source |
+| `delete(nb_id, source_id)` | Delete source |
+
+### Chat (`client.chat`)
+| Method | Description |
+|--------|-------------|
+| `ask(nb_id, question, source_ids=None)` | Ask a question → `ChatResult` |
+| `history(nb_id)` | Get conversation history |
+| `configure(nb_id, mode=None, persona=None)` | Set chat mode/persona |
+
+### Artifacts — Generate (`client.artifacts`)
+
+All generate methods return a `GenerationStatus` with `task_id`. Use `wait_for_completion()` to poll until done.
+
+| Method | Key Options | Download Method |
+|--------|-------------|-----------------|
+| `generate_audio(nb_id, instructions, format, length, language)` | format: `deep-dive/brief/critique/debate`, length: `short/default/long` | `download_audio(nb_id, path)` |
+| `generate_video(nb_id, instructions, format, style)` | style: `classic/whiteboard/kawaii/anime/watercolor/...` | `download_video(nb_id, path)` |
+| `generate_quiz(nb_id, difficulty, quantity)` | difficulty: `easy/medium/hard` | `download_quiz(nb_id, path, output_format)` |
+| `generate_flashcards(nb_id, difficulty, quantity)` | — | `download_flashcards(nb_id, path, output_format)` |
+| `generate_slide_deck(nb_id, instructions, format)` | format: `detailed/presenter` | `download_slide_deck(nb_id, path)` — PDF or PPTX |
+| `generate_infographic(nb_id, orientation, detail)` | orientation: `landscape/portrait/square` | `download_infographic(nb_id, path)` |
+| `generate_report(nb_id, format, instructions)` | format: `briefing-doc/study-guide/blog-post/custom` | `download_report(nb_id, path)` |
+| `generate_data_table(nb_id, instructions)` | — | `download_data_table(nb_id, path)` |
+| `generate_mind_map(nb_id)` | Sync, no wait needed | `download_mind_map(nb_id, path)` |
+
+**Wait pattern:**
+```python
+status = await client.artifacts.generate_audio(nb_id, instructions="Focus on key facts")
+final = await client.artifacts.wait_for_completion(nb_id, status.task_id, timeout=300)
+if final.is_complete:
+    await client.artifacts.download_audio(nb_id, "./podcast.mp3")
+```
+
+### Research (`client.research`)
+```python
+# Start web research
+research = await client.research.start(nb_id, "quantum computing trends", source="web", mode="deep")
+# Poll until complete
+status = await client.research.poll(nb_id)
+# Import discovered sources
+await client.research.import_sources(nb_id, task_id, sources[:10])
+```
+
+## CLI Quick Reference
+
+```bash
+# Session
+notebooklm login
+notebooklm use <notebook_id>
+notebooklm status
+
+# Notebooks
+notebooklm list
+notebooklm create "My Notebook"
+notebooklm delete <id>
+notebooklm rename "New Title"
+
+# Sources
+notebooklm source add "https://example.com"
+notebooklm source add ./paper.pdf
+notebooklm source add-research "AI trends 2025" --mode deep --import-all
+notebooklm source list
+
+# Chat
+notebooklm ask "What are the key themes?"
+
+# Generate (--wait blocks until done)
+notebooklm generate audio "make it engaging" --wait
+notebooklm generate video --style whiteboard --wait
+notebooklm generate quiz --difficulty hard --wait
+notebooklm generate flashcards --quantity more --wait
+notebooklm generate slide-deck --wait
+notebooklm generate infographic --orientation portrait --wait
+notebooklm generate report --format study-guide --wait
+notebooklm generate mind-map
+
+# Download
+notebooklm download audio ./podcast.mp3
+notebooklm download video ./overview.mp4
+notebooklm download quiz --format json ./quiz.json
+notebooklm download flashcards --format markdown ./cards.md
+notebooklm download slide-deck ./slides.pdf
+notebooklm download mind-map ./mindmap.json
+notebooklm download data-table ./data.csv
+```
+
+## Common Workflows
+
+### Research → Podcast
+See `references/workflows.md` for the full pattern.
+
+### Bulk Source Import
+```python
+urls = ["https://...", "https://...", ...]
+for url in urls:
+    await client.sources.add_url(nb_id, url, wait=False)
+    await asyncio.sleep(1)  # Rate limiting
+```
+
+### Quiz Generation + JSON Export
+```python
+status = await client.artifacts.generate_quiz(nb_id, difficulty="hard")
+final = await client.artifacts.wait_for_completion(nb_id, status.task_id)
+await client.artifacts.download_quiz(nb_id, "quiz.json", output_format="json")
+```
+
+## Error Handling
+
+```python
+from notebooklm import RPCError
+
+try:
+    result = await client.notebooks.create("Test")
+except RPCError as e:
+    # Session expired → re-run `notebooklm login`
+    # Rate limited → wait and retry
+    print(f"Error: {e}")
+```
+
+**Common issues:**
+- `RPCError` auth failure → re-run `notebooklm login` or call `await client.refresh_auth()`
+- Rate limits → add `await asyncio.sleep(2)` between bulk operations
+- Source not ready → use `wait=True` in `add_url()` / `add_file()`
+
+## Reference Files
+
+- `references/auth.md` — Detailed auth setup, CI/CD, environment variables
+- `references/workflows.md` — Complete workflow examples (research→podcast, bulk import, etc.)
+- `references/artifact-options.md` — All generation options, formats, and styles

package/src/skills/notebook-lm/references/artifact-options.md

@@ -0,0 +1,168 @@
+# Artifact Generation Options
+
+## Audio Overview (Podcast)
+
+```python
+await client.artifacts.generate_audio(
+    nb_id,
+    instructions="Focus on practical applications",  # optional
+    format="deep-dive",    # deep-dive | brief | critique | debate
+    length="default",      # short | default | long
+    language="en",         # ISO language code
+    source_ids=None,       # list of source IDs to limit scope
+)
+```
+
+CLI: `notebooklm generate audio "instructions" --format deep-dive --length long --wait`
+
+Download: MP3 or MP4
+
+## Video Overview
+
+```python
+await client.artifacts.generate_video(
+    nb_id,
+    instructions="Explainer for beginners",
+    format="explainer",    # explainer | brief
+    style="whiteboard",    # auto | classic | whiteboard | kawaii | anime | watercolor | retro-print | heritage | paper-craft
+    language="en",
+)
+```
+
+CLI: `notebooklm generate video --style kawaii --format brief --wait`
+
+Download: MP4
+
+## Slide Deck
+
+```python
+await client.artifacts.generate_slide_deck(
+    nb_id,
+    instructions="Focus on key metrics",
+    format="detailed",     # detailed | presenter
+    length="default",      # default | short
+)
+```
+
+CLI: `notebooklm generate slide-deck --format presenter --wait`
+
+Download: PDF or PPTX (PPTX not available in web UI!)
+
+## Quiz
+
+```python
+await client.artifacts.generate_quiz(
+    nb_id,
+    difficulty="medium",   # easy | medium | hard
+    quantity="standard",   # fewer | standard | more
+)
+```
+
+CLI: `notebooklm generate quiz --difficulty hard --quantity more --wait`
+
+Download: `output_format` → `json` | `markdown` | `html`
+
+## Flashcards
+
+```python
+await client.artifacts.generate_flashcards(
+    nb_id,
+    difficulty="medium",
+    quantity="standard",
+)
+```
+
+CLI: `notebooklm generate flashcards --quantity more --wait`
+
+Download: `output_format` → `json` | `markdown` | `html`
+
+## Infographic
+
+```python
+await client.artifacts.generate_infographic(
+    nb_id,
+    instructions="Highlight statistics",
+    orientation="portrait",  # landscape | portrait | square
+    detail="standard",       # concise | standard | detailed
+)
+```
+
+CLI: `notebooklm generate infographic --orientation portrait --detail detailed --wait`
+
+Download: PNG
+
+## Report
+
+```python
+await client.artifacts.generate_report(
+    nb_id,
+    format="study-guide",   # briefing-doc | study-guide | blog-post | custom
+    instructions="Include key examples",  # extra instructions appended to template
+)
+```
+
+CLI: `notebooklm generate report --format blog-post --append "target audience: beginners" --wait`
+
+Download: Markdown
+
+## Data Table
+
+```python
+await client.artifacts.generate_data_table(
+    nb_id,
+    instructions="Compare pricing, features, and limitations of each tool",
+)
+```
+
+CLI: `notebooklm generate data-table "compare main concepts" --wait`
+
+Download: CSV
+
+## Mind Map
+
+```python
+# Synchronous — returns immediately, no wait needed
+result = await client.artifacts.generate_mind_map(nb_id)
+await client.artifacts.download_mind_map(nb_id, "mindmap.json")
+```
+
+CLI: `notebooklm generate mind-map`
+
+Download: JSON (hierarchical structure)
+
+## Revise Individual Slide
+
+```python
+# Requires existing slide deck artifact ID
+await client.artifacts.revise_slide(
+    nb_id,
+    artifact_id="art_xxx",
+    slide_index=0,           # 0-based
+    instructions="Move title to top, add bullet points",
+)
+```
+
+CLI: `notebooklm generate revise-slide "revise instructions" --artifact <id> --slide 0 --wait`
+
+## Artifact Management
+
+```python
+# List all artifacts
+artifacts = await client.artifacts.list(nb_id)
+artifacts = await client.artifacts.list(nb_id, artifact_type="audio")
+
+# Get specific artifact
+artifact = await client.artifacts.get(nb_id, artifact_id)
+
+# Rename
+await client.artifacts.rename(nb_id, artifact_id, "New Name")
+
+# Delete
+await client.artifacts.delete(nb_id, artifact_id)
+
+# Export to Google Docs/Sheets
+await client.artifacts.export(nb_id, artifact_id, export_type="docs", title="My Export")
+
+# Get AI suggestions
+suggestions = await client.artifacts.suggestions(nb_id)
+```

package/src/skills/notebook-lm/references/auth.md

@@ -0,0 +1,58 @@
+# NotebookLM Authentication
+
+## First-Time Setup (Browser)
+
+```bash
+pip install "notebooklm-py[browser]"
+playwright install chromium
+notebooklm login
+```
+
+This opens a browser, you log into Google, and cookies are saved to `~/.notebooklm/storage_state.json`.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NOTEBOOKLM_HOME` | Base directory for config (default: `~/.notebooklm`) |
+| `NOTEBOOKLM_AUTH_JSON` | Inline auth JSON — no file needed (for CI/CD) |
+| `NOTEBOOKLM_DEBUG_RPC` | Set to `1` for debug logging |
+
+## CI/CD (No Browser)
+
+Export cookies from a logged-in session, then:
+
+```bash
+export NOTEBOOKLM_AUTH_JSON='{"cookies": [{"name": "SID", "value": "...", ...}], "csrf_token": "...", "session_id": "..."}'
+```
+
+Or in Python:
+```python
+import os
+os.environ["NOTEBOOKLM_AUTH_JSON"] = '{"cookies": [...]}'
+async with await NotebookLMClient.from_storage() as client:
+    ...
+```
+
+## Auth Precedence (highest → lowest)
+1. Explicit `path` arg to `from_storage()`
+2. `NOTEBOOKLM_AUTH_JSON` env var
+3. `$NOTEBOOKLM_HOME/storage_state.json`
+4. `~/.notebooklm/storage_state.json`
+
+## Token Refresh
+
+CSRF tokens auto-refresh on 401/403. For proactive refresh:
+```python
+await client.refresh_auth()
+```
+
+If session cookies expire entirely → re-run `notebooklm login`.
+
+## Diagnose Auth Issues
+
+```bash
+notebooklm auth check
+notebooklm auth check --test   # Also validates network
+notebooklm auth check --json   # Machine-readable
+```

package/src/skills/notebook-lm/references/workflows.md

@@ -0,0 +1,144 @@
+# NotebookLM Workflow Examples
+
+## 1. Complete Quickstart
+
+```python
+import asyncio
+from notebooklm import NotebookLMClient
+
+async def main():
+    async with await NotebookLMClient.from_storage() as client:
+        # Create notebook
+        nb = await client.notebooks.create("Research")
+        
+        # Add sources
+        await client.sources.add_url(nb.id, "https://example.com/article", wait=True)
+        await client.sources.add_file(nb.id, "./paper.pdf", wait=True)
+        
+        # Chat
+        result = await client.chat.ask(nb.id, "What are the key findings?")
+        print(result.answer)
+        
+        # Generate podcast
+        status = await client.artifacts.generate_audio(
+            nb.id, instructions="Make it engaging and accessible"
+        )
+        final = await client.artifacts.wait_for_completion(nb.id, status.task_id, timeout=300)
+        if final.is_complete:
+            await client.artifacts.download_audio(nb.id, "./podcast.mp3")
+
+asyncio.run(main())
+```
+
+## 2. Research → Podcast Pipeline
+
+```python
+import asyncio
+from notebooklm import NotebookLMClient
+
+async def research_to_podcast(topic: str, output_path: str = "./podcast.mp3"):
+    async with await NotebookLMClient.from_storage() as client:
+        # Create notebook
+        nb = await client.notebooks.create(f"Research: {topic}")
+        
+        # Start deep research
+        research = await client.research.start(nb.id, topic, source="web", mode="deep")
+        task_id = research.get("task_id")
+        
+        # Wait for research
+        for _ in range(30):
+            status = await client.research.poll(nb.id)
+            if status.get("status") == "completed":
+                sources = status.get("sources", [])
+                await client.research.import_sources(nb.id, task_id, sources[:10])
+                break
+            await asyncio.sleep(10)
+        
+        # Generate podcast
+        gen = await client.artifacts.generate_audio(
+            nb.id, instructions=f"Engaging overview of {topic}"
+        )
+        final = await client.artifacts.wait_for_completion(nb.id, gen.task_id, timeout=600)
+        
+        if final.is_complete:
+            await client.artifacts.download_audio(nb.id, output_path)
+            print(f"Saved to {output_path}")
+        
+        return nb.id  # Keep for reference
+
+asyncio.run(research_to_podcast("AI trends 2025"))
+```
+
+## 3. Bulk URL Import
+
+```python
+async def bulk_import(nb_id: str, urls: list[str]):
+    async with await NotebookLMClient.from_storage() as client:
+        for i, url in enumerate(urls):
+            print(f"Adding {i+1}/{len(urls)}: {url}")
+            await client.sources.add_url(nb_id, url, wait=False)
+            await asyncio.sleep(1)  # Avoid rate limits
+        print("All sources submitted. Processing in background.")
+```
+
+## 4. Generate All Content Types
+
+```python
+async def generate_all(nb_id: str):
+    async with await NotebookLMClient.from_storage() as client:
+        tasks = [
+            client.artifacts.generate_audio(nb_id, format="deep-dive"),
+            client.artifacts.generate_quiz(nb_id, difficulty="medium"),
+            client.artifacts.generate_flashcards(nb_id),
+            client.artifacts.generate_slide_deck(nb_id, format="detailed"),
+            client.artifacts.generate_mind_map(nb_id),  # Sync, returns immediately
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        return results
+```
+
+## 5. Quiz Export in Multiple Formats
+
+```python
+async def export_quiz(nb_id: str):
+    async with await NotebookLMClient.from_storage() as client:
+        status = await client.artifacts.generate_quiz(nb_id, difficulty="hard", quantity="more")
+        final = await client.artifacts.wait_for_completion(nb_id, status.task_id)
+        
+        if final.is_complete:
+            await client.artifacts.download_quiz(nb_id, "quiz.json", output_format="json")
+            await client.artifacts.download_quiz(nb_id, "quiz.md", output_format="markdown")
+            await client.artifacts.download_quiz(nb_id, "quiz.html", output_format="html")
+```
+
+## 6. Save Chat History as Notes
+
+```python
+async def save_session(nb_id: str, questions: list[str]):
+    async with await NotebookLMClient.from_storage() as client:
+        for q in questions:
+            await client.chat.ask(nb_id, q)
+        # Save entire session as a notebook note
+        history = await client.chat.history(nb_id)
+        await client.notes.create(nb_id, content=str(history), title="Research Session")
+```
+
+## 7. CLI One-Liner Workflows
+
+```bash
+# Quick research notebook + podcast
+notebooklm create "AI Research" && \
+notebooklm source add-research "artificial intelligence 2025" --mode deep --import-all && \
+notebooklm generate audio "engaging overview" --wait && \
+notebooklm download audio ./ai-research.mp3
+
+# Generate study materials from PDF
+notebooklm create "Study" && \
+notebooklm source add ./textbook.pdf && \
+notebooklm generate quiz --difficulty hard --wait && \
+notebooklm generate flashcards --quantity more --wait && \
+notebooklm generate slide-deck --wait && \
+notebooklm download quiz --format json ./quiz.json && \
+notebooklm download flashcards --format markdown ./cards.md && \
+notebooklm download slide-deck ./slides.pdf
+```