documente/docs/integration.md

Guida Integrazione NotebookLM con RAG

Questa guida spiega come usare NotebookLM con il sistema RAG di DocuMente.

---

Casi d'Uso

1. Ricerca nei notebook: "Cosa dicono i miei notebook sull'AI?"
2. Ricerca combinata: "Cosa ho su Python nei documenti PDF e nei notebook?"
3. Analisi multi-notebook: "Confronta le conclusioni tra notebook A e B"

---

Requisiti

• NotebookLM Agent funzionante
• DocuMente RAG con Qdrant avviato
• Almeno un notebook su NotebookLM

---

Architettura Semplice

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  NotebookLM     │────▶│  DocuMente RAG   │────▶│   LLM Provider  │
│  (Google)       │     │  (Qdrant + API)  │     │   (OpenAI/etc)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                        │
         │ Sincronizza            │ Query
         ▼                        ▼
  Contenuti dei          Ricerca semantica
  notebook               su documenti + notebook

---

Quick Start

1. Avvia i Servizi

# Terminale 1: Qdrant (richiesto per RAG)
docker run -p 6333:6333 qdrant/qdrant

# Terminale 2: DocuMente API
uv run fastapi dev src/agentic_rag/api/main.py

# Terminale 3 (opzionale): Web UI
cd frontend && npm run dev

2. Sincronizza un Notebook

# Ottieni ID notebook da NotebookLM
curl http://localhost:8000/api/v1/notebooks

# Sincronizza nel RAG
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/{NOTEBOOK_ID}

3. Fai una Domanda

# Cerca solo nei notebook
curl -X POST http://localhost:8000/api/v1/query/notebooks \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Quali sono i punti chiave?",
    "notebook_ids": ["uuid-1"]
  }'

# Cerca in documenti + notebook
curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Confronta le fonti",
    "notebook_ids": ["uuid-1"],
    "include_documents": true
  }'

---

API Endpoints

Gestione Notebook

Endpoint	Metodo	Descrizione
/api/v1/notebooklm/sync/{id}	POST	Sincronizza notebook
/api/v1/notebooklm/indexed	GET	Lista notebook sincronizzati
/api/v1/notebooklm/sync/{id}/status	GET	Verifica stato
/api/v1/notebooklm/sync/{id}	DELETE	Rimuovi sincronizzazione

Query

Endpoint	Metodo	Descrizione
/api/v1/query/notebooks	POST	Cerca solo nei notebook
/api/v1/query	POST	Cerca in documenti + notebook

---

Esempi

Sincronizzazione

# Sincronizza
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/abc-123

# Response:
# {
#   "sync_id": "...",
#   "notebook_id": "abc-123",
#   "status": "success",
#   "sources_indexed": 5,
#   "total_chunks": 42
# }

Query con Filtri

# Multi-notebook
curl -X POST http://localhost:8000/api/v1/query/notebooks \
  -d '{
    "question": "AI trends",
    "notebook_ids": ["id-1", "id-2", "id-3"],
    "provider": "openai"
  }'

# Con modello locale (Ollama)
curl -X POST http://localhost:8000/api/v1/query/notebooks \
  -d '{
    "question": "Riassumi",
    "notebook_ids": ["id-1"],
    "provider": "ollama",
    "model": "llama3.2"
  }'

---

Web UI

Se hai avviato il frontend:

1. Vai su http://localhost:3000
2. Sezione Chat
3. Seleziona i notebook dalla lista
4. Fai le tue domande

---

Provider LLM

Puoi usare qualsiasi provider supportato:

Cloud: OpenAI, Anthropic, Google, Mistral, Azure
Locale: Ollama, LM Studio

# Esempio con Ollama (locale)
curl -X POST http://localhost:8000/api/v1/query/notebooks \
  -d '{
    "question": "Spiega...",
    "notebook_ids": ["id-1"],
    "provider": "ollama",
    "model": "llama3.2"
  }'

---

Troubleshooting

Problema: "Notebook not found"
→ Verifica che il notebook esista su NotebookLM

Problema: Qdrant non risponde
→ Controlla che Qdrant sia avviato: docker ps

Problema: Nessun risultato
→ Verifica che il notebook sia sincronizzato: GET /api/v1/notebooklm/indexed

---

Limitazioni

• I contenuti devono essere "scaricabili" da NotebookLM (alcuni PDF potrebbero non avere testo)
• La sincronizzazione è manuale (non automatica quando il notebook cambia)
• Ogni fonte diventa chunk di ~1024 caratteri

---

Per domande avanzate vedi SKILL.md