@techwavedev/agi-agent-kit 1.1.7 → 1.2.7

package/templates/skills/knowledge/notebooklm-rag/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: notebooklm-rag
+description: "Deep RAG layer powered by Google NotebookLM + Gemini. The agent autonomously manages notebooks via MCP tools — authentication, library management, querying, follow-ups, and caching. Opt-in for users with a Google account. Default RAG is qdrant-memory. Triggers on: '@notebooklm', 'research my docs', 'deep search', 'query my notebook', 'check my notebooks'."
+---
+
+# NotebookLM Deep RAG
+
+> **This is a Deep RAG tool.** The agent uses NotebookLM as an autonomous knowledge backend via MCP tools. It handles auth, notebooks, queries, follow-ups, and caching — fully hands-free.
+>
+> **Opt-in:** Requires a Google account with NotebookLM. Default RAG uses `qdrant-memory` (local, offline, no account needed).
+
+## Architecture
+
+```
+User question
+    ↓
+Agent checks Qdrant cache → hit? → return cached answer (0 cost)
+    ↓ miss
+Agent checks NotebookLM auth → not authenticated? → setup_auth (opens browser)
+    ↓ authenticated
+Agent resolves notebook → list_notebooks / search_notebooks / select_notebook
+    ↓
+Agent asks question → ask_question (browser automation, Gemini-grounded answer)
+    ↓
+Agent evaluates answer → gaps? → ask follow-up automatically
+    ↓ complete
+Agent stores in Qdrant → cache for future use
+    ↓
+Agent responds to user with synthesized answer
+```
+
+## MCP Tools Reference
+
+The agent has direct access to these tools. Use them autonomously.
+
+### Authentication
+
+| Tool         | When                                          |
+| ------------ | --------------------------------------------- |
+| `get_health` | First — always check auth status              |
+| `setup_auth` | One-time Google login (opens visible browser) |
+| `re_auth`    | Switch account or fix expired session         |
+
+### Library Management
+
+| Tool                | When                                                              |
+| ------------------- | ----------------------------------------------------------------- |
+| `list_notebooks`    | See all registered notebooks                                      |
+| `add_notebook`      | Register a new notebook (url, name, description, topics required) |
+| `remove_notebook`   | Remove a notebook from library                                    |
+| `update_notebook`   | Update notebook metadata                                          |
+| `search_notebooks`  | Find notebooks by topic/keyword                                   |
+| `select_notebook`   | Set active notebook (used as default for queries)                 |
+| `get_notebook`      | Get details of a specific notebook                                |
+| `get_library_stats` | Library overview                                                  |
+
+### Querying
+
+| Tool            | When                                  |
+| --------------- | ------------------------------------- |
+| `ask_question`  | Query a notebook — core research tool |
+| `list_sessions` | Check active browser sessions         |
+| `close_session` | Close a session when done             |
+| `reset_session` | Clear session history                 |
+
+### Maintenance
+
+| Tool           | When                           |
+| -------------- | ------------------------------ |
+| `cleanup_data` | Clean browser data, fix issues |
+
+## Autonomous Workflow
+
+### On Any Research Request:
+
+1. **Check Qdrant first** — `memory_manager.py auto --query "..."`. If cache hit, return immediately.
+
+2. **Check auth** — `get_health`. If not authenticated, run `setup_auth` and tell user a browser will open.
+
+3. **Resolve notebook** — `list_notebooks`. If user mentions a topic, `search_notebooks`. If no notebooks exist, ask user for a NotebookLM URL and `add_notebook`.
+
+4. **Ask the question** — `ask_question` with the resolved notebook. Can pass `notebook_id` (from library) or `notebook_url` (direct URL).
+
+5. **Follow up** — Every answer ends with "Is that ALL you need to know?" The agent MUST:
+   - Compare answer to original request
+   - Identify gaps
+   - Ask follow-up questions automatically (include full context — each question is a new browser session)
+   - Repeat until information is complete
+
+6. **Cache in Qdrant** — Store result with `memory_manager.py store` and `cache-store`.
+
+7. **Respond** — Synthesize all answers into a cohesive response.
+
+### On "Add a notebook":
+
+**Smart Add** — If user provides a URL but no details:
+
+1. `ask_question` with `notebook_url` and question: "What is the content of this notebook? What topics are covered? Provide a brief overview."
+2. Use the answer to fill in `name`, `description`, `topics`
+3. `add_notebook` with discovered metadata
+
+**Manual Add** — If user provides all details directly, just `add_notebook`.
+
+### On Notebook Management:
+
+- "List my notebooks" → `list_notebooks`
+- "Remove X" → Confirm with user → `remove_notebook`
+- "Switch to X" → `select_notebook`
+- "Update X description" → `update_notebook`
+- "Search for X" → `search_notebooks`
+
+## Qdrant Integration (Context Keeping)
+
+NotebookLM answers are cached in Qdrant. Prior research is recalled automatically.
+
+### Before Query
+
+```bash
+python3 execution/memory_manager.py auto --query "<research question>"
+```
+
+- `cache_hit: true` → Skip browser, return cached answer
+- `source: memory` → Inject prior context into the question
+- `source: none` → Proceed with NotebookLM query
+
+### After Query
+
+```bash
+python3 execution/memory_manager.py store \
+  --content "Q: [question] A: [answer]" \
+  --type technical \
+  --project notebooklm-research \
+  --tags notebooklm [notebook-name] [topic]
+
+python3 execution/memory_manager.py cache-store \
+  --query "[question]" \
+  --response "[synthesized answer]"
+```
+
+### Context Keeping
+
+- Prior research on same topic is auto-recalled
+- Previous findings enrich follow-up questions
+- Each session builds compound knowledge
+
+## MCP Server Setup
+
+The NotebookLM MCP server must be configured in the AI host:
+
+### Claude Desktop / Claude Code
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/notebooklm-mcp"]
+    }
+  }
+}
+```
+
+### Opencode
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/notebooklm-mcp"]
+    }
+  }
+}
+```
+
+If MCP is not configured, fall back to the Python scripts in `scripts/` (see Fallback section below).
+
+## Fallback: Python Scripts
+
+When MCP is not available, use the bundled scripts via `run.py`:
+
+```bash
+python scripts/run.py auth_manager.py status          # Check auth
+python scripts/run.py auth_manager.py setup            # Authenticate
+python scripts/run.py notebook_manager.py list         # List notebooks
+python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS
+python scripts/run.py ask_question.py --question "..." # Query
+python scripts/run.py ask_question.py --question "..." --notebook-url "https://..."
+python scripts/run.py cleanup_manager.py --confirm     # Cleanup
+```
+
+The `run.py` wrapper auto-creates `.venv`, installs dependencies (patchright, python-dotenv), and installs Chrome.
+
+## Troubleshooting
+
+| Problem                  | Solution                                                |
+| ------------------------ | ------------------------------------------------------- |
+| Not authenticated        | `setup_auth` (browser opens for Google login)           |
+| Rate limit (50/day free) | Wait 24h or `re_auth` with different Google account     |
+| Browser crashes          | `cleanup_data(preserve_library=true)` then `setup_auth` |
+| Stale cached answer      | Re-query or clear Qdrant cache                          |
+| Notebook not found       | `list_notebooks`, then `add_notebook` if missing        |
+| MCP not available        | Use fallback Python scripts via `run.py`                |
+
+## Limitations
+
+- Rate limits: 50 queries/day (free), 250/day (Google AI Pro)
+- Manual upload: User must add documents to NotebookLM first
+- Browser overhead: Few seconds per query
+- No live notebook discovery: User must provide URLs to register notebooks
+
+## Credits
+
+MCP server: [PleasePrompto/notebooklm-mcp](https://github.com/PleasePrompto/notebooklm-mcp)
+Browser automation: [PleasePrompto/notebooklm-skill](https://github.com/PleasePrompto/notebooklm-skill) (MIT License)
+Adapted for the Agi Agent Framework with Qdrant memory integration.

package/templates/skills/knowledge/notebooklm-rag/requirements.txt

@@ -0,0 +1,9 @@
+# NotebookLM RAG Skill Dependencies
+# These will be installed in the skill's local .venv
+
+# Core browser automation with anti-detection
+# Note: After installation, run: patchright install chrome
+patchright==1.55.2
+
+# Environment management
+python-dotenv==1.0.0

package/templates/skills/knowledge/notebooklm-rag/scripts/ask_question.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+Simple NotebookLM Question Interface
+Adapted from PleasePrompto/notebooklm-skill (MIT License)
+
+Implements hybrid auth approach:
+- Persistent browser profile (user_data_dir) for fingerprint consistency
+- Manual cookie injection from state.json for session cookies (Playwright bug workaround)
+See: https://github.com/microsoft/playwright/issues/36139
+"""
+
+import argparse
+import sys
+import time
+import re
+from pathlib import Path
+
+from patchright.sync_api import sync_playwright
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+from auth_manager import AuthManager
+from notebook_manager import NotebookLibrary
+from config import QUERY_INPUT_SELECTORS, RESPONSE_SELECTORS
+from browser_utils import BrowserFactory, StealthUtils
+
+
+# Since we don't have persistent sessions, we encourage comprehensive questions
+FOLLOW_UP_REMINDER = (
+    "\n\nEXTREMELY IMPORTANT: Is that ALL you need to know? "
+    "You can always ask another question! Think about it carefully: "
+    "before you reply to the user, review their original request and this answer. "
+    "If anything is still unclear or missing, ask me another comprehensive question "
+    "that includes all necessary context (since each question opens a new browser session)."
+)
+
+
+def ask_notebooklm(question: str, notebook_url: str, headless: bool = True) -> str:
+    """
+    Ask a question to NotebookLM
+
+    Args:
+        question: Question to ask
+        notebook_url: NotebookLM notebook URL
+        headless: Run browser in headless mode
+
+    Returns:
+        Answer text from NotebookLM
+    """
+    auth = AuthManager()
+
+    if not auth.is_authenticated():
+        print("⚠️ Not authenticated. Run: python scripts/run.py auth_manager.py setup")
+        return None
+
+    print(f"💬 Asking: {question}")
+    print(f"📚 Notebook: {notebook_url}")
+
+    playwright = None
+    context = None
+
+    try:
+        playwright = sync_playwright().start()
+
+        context = BrowserFactory.launch_persistent_context(
+            playwright,
+            headless=headless
+        )
+
+        page = context.new_page()
+        print("  🌐 Opening notebook...")
+        page.goto(notebook_url, wait_until="domcontentloaded")
+
+        page.wait_for_url(re.compile(r"^https://notebooklm\.google\.com/"), timeout=10000)
+
+        print("  ⏳ Waiting for query input...")
+        query_element = None
+
+        for selector in QUERY_INPUT_SELECTORS:
+            try:
+                query_element = page.wait_for_selector(
+                    selector,
+                    timeout=10000,
+                    state="visible"
+                )
+                if query_element:
+                    print(f"  ✓ Found input: {selector}")
+                    break
+            except:
+                continue
+
+        if not query_element:
+            print("  ❌ Could not find query input")
+            return None
+
+        print("  ⏳ Typing question...")
+
+        input_selector = QUERY_INPUT_SELECTORS[0]
+        StealthUtils.human_type(page, input_selector, question)
+
+        print("  📤 Submitting...")
+        page.keyboard.press("Enter")
+
+        StealthUtils.random_delay(500, 1500)
+
+        print("  ⏳ Waiting for answer...")
+
+        answer = None
+        stable_count = 0
+        last_text = None
+        deadline = time.time() + 120  # 2 minutes timeout
+
+        while time.time() < deadline:
+            try:
+                thinking_element = page.query_selector('div.thinking-message')
+                if thinking_element and thinking_element.is_visible():
+                    time.sleep(1)
+                    continue
+            except:
+                pass
+
+            for selector in RESPONSE_SELECTORS:
+                try:
+                    elements = page.query_selector_all(selector)
+                    if elements:
+                        latest = elements[-1]
+                        text = latest.inner_text().strip()
+
+                        if text:
+                            if text == last_text:
+                                stable_count += 1
+                                if stable_count >= 3:
+                                    answer = text
+                                    break
+                            else:
+                                stable_count = 0
+                                last_text = text
+                except:
+                    continue
+
+            if answer:
+                break
+
+            time.sleep(1)
+
+        if not answer:
+            print("  ❌ Timeout waiting for answer")
+            return None
+
+        print("  ✅ Got answer!")
+        return answer + FOLLOW_UP_REMINDER
+
+    except Exception as e:
+        print(f"  ❌ Error: {e}")
+        import traceback
+        traceback.print_exc()
+        return None
+
+    finally:
+        if context:
+            try:
+                context.close()
+            except:
+                pass
+
+        if playwright:
+            try:
+                playwright.stop()
+            except:
+                pass
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Ask NotebookLM a question')
+
+    parser.add_argument('--question', required=True, help='Question to ask')
+    parser.add_argument('--notebook-url', help='NotebookLM notebook URL')
+    parser.add_argument('--notebook-id', help='Notebook ID from library')
+    parser.add_argument('--show-browser', action='store_true', help='Show browser')
+
+    args = parser.parse_args()
+
+    # Resolve notebook URL
+    notebook_url = args.notebook_url
+
+    if not notebook_url and args.notebook_id:
+        library = NotebookLibrary()
+        notebook = library.get_notebook(args.notebook_id)
+        if notebook:
+            notebook_url = notebook['url']
+        else:
+            print(f"❌ Notebook '{args.notebook_id}' not found")
+            return 1
+
+    if not notebook_url:
+        library = NotebookLibrary()
+        active = library.get_active_notebook()
+        if active:
+            notebook_url = active['url']
+            print(f"📚 Using active notebook: {active['name']}")
+        else:
+            notebooks = library.list_notebooks()
+            if notebooks:
+                print("\n📚 Available notebooks:")
+                for nb in notebooks:
+                    mark = " [ACTIVE]" if nb.get('id') == library.active_notebook_id else ""
+                    print(f"  {nb['id']}: {nb['name']}{mark}")
+                print("\nSpecify with --notebook-id or set active:")
+                print("python scripts/run.py notebook_manager.py activate --id ID")
+            else:
+                print("❌ No notebooks in library. Add one first:")
+                print("python scripts/run.py notebook_manager.py add --url URL --name NAME --description DESC --topics TOPICS")
+            return 1
+
+    answer = ask_notebooklm(
+        question=args.question,
+        notebook_url=notebook_url,
+        headless=not args.show_browser
+    )
+
+    if answer:
+        print("\n" + "=" * 60)
+        print(f"Question: {args.question}")
+        print("=" * 60)
+        print()
+        print(answer)
+        print()
+        print("=" * 60)
+        return 0
+    else:
+        print("\n❌ Failed to get answer")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())