From 568489cae46889a0d8c6a72b144b5baa6705a0f9 Mon Sep 17 00:00:00 2001
From: Luca Sacchi Ricciardi <luca@lucasacchi.net>
Date: Mon, 6 Apr 2026 18:01:50 +0200
Subject: [PATCH] docs: comprehensive documentation for NotebookLM-RAG
 integration

Update documentation to reflect new integration features:

README.md:
- Add 'Integrazione NotebookLM + RAG' section after Overview
- Update DocuMente component section with new endpoints
- Add notebooklm_sync.py and notebooklm_indexer.py to architecture
- Add integration API examples
- Add link to docs/integration.md

SKILL.md:
- Add RAG Integration to Capabilities table
- Update Autonomy Rules with new endpoints
- Add RAG Integration section to Quick Reference
- Add Sprint 2 changelog with integration features
- Update Skill Version to 1.2.0

docs/integration.md (NEW):
- Complete integration guide with architecture diagram
- API reference for all sync and query endpoints
- Usage examples and workflows
- Best practices and troubleshooting
- Performance considerations and limitations
- Roadmap for future features

All documentation now accurately reflects the unified
NotebookLM + RAG agent capabilities.
---
 README.md           | 111 ++++++++++-
 SKILL.md            |  84 ++++++++-
 docs/integration.md | 436 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 628 insertions(+), 3 deletions(-)
 create mode 100644 docs/integration.md

diff --git a/README.md b/README.md
index cbac9e2..16e44e9 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,9 @@ Questo repository contiene **due sistemi AI complementari**:
 
 ## Panoramica
 
+### Integrazione
+- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
+
 ### NotebookLM Agent
 
 Interfaccia API e webhook per **Google NotebookLM** che permette:
@@ -51,10 +54,45 @@ Sistema **Retrieval-Augmented Generation** standalone con:
 
 **Ideale per:** Knowledge management, Document analysis, Research assistant
 
+---
+
+## Integrazione NotebookLM + RAG
+
+Ora puoi sincronizzare i tuoi notebook di NotebookLM nel sistema RAG di DocuMente, permettendo di:
+
+- **Effettuare ricerche semantiche** sui contenuti dei tuoi notebook
+- **Combinare documenti locali e notebook** nelle stesse query
+- **Usare tutti i provider LLM** disponibili per interrogare i notebook
+- **Filtrare per notebook specifici** durante le ricerche
+
+### Architettura
+
+```
+NotebookLM → NotebookLMIndexerService → Qdrant Vector Store
+                                               ↓
+                                    RAGService (query con filtri)
+                                               ↓
+                                    Multi-Provider LLM Response
+```
+
+### Come funziona
+
+1. **Sincronizzazione**: I contenuti dei notebook vengono estratti, divisi in chunks e indicizzati in Qdrant
+2. **Metadati**: Ogni chunk mantiene informazioni sul notebook e la fonte di origine
+3. **Ricerca**: Le query RAG possono filtrare per notebook_id specifici
+4. **Risposta**: Il LLM riceve contesto dai notebook selezionati
+
+---
+
+
+
 ---
 
 ## Componenti
 
+### Integrazione
+- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
+
 ### NotebookLM Agent
 
 ```
@@ -101,16 +139,46 @@ src/agentic_rag/
 │       ├── documents.py  # Upload documenti
 │       ├── query.py      # Query RAG
 │       ├── chat.py       # Chat conversazionale
-│       └── providers.py  # Gestione provider LLM
+│       ├── providers.py  # Gestione provider LLM
+│       └── notebooklm_sync.py  # [NUOVO] Sync NotebookLM
 ├── services/             # Business logic
 │   ├── rag_service.py    # Core RAG logic
 │   ├── vector_store.py   # Qdrant integration
-│   └── document_service.py
+│   ├── document_service.py
+│   └── notebooklm_indexer.py  # [NUOVO] Indexing service
 └── core/                 # Configurazioni
     ├── config.py        # Multi-provider config
     └── llm_factory.py   # LLM factory pattern
 ```
 
+**Endpoint API NotebookLM Integration:**
+- `POST /api/v1/notebooklm/sync/{notebook_id}` - Sincronizza un notebook da NotebookLM
+- `GET /api/v1/notebooklm/indexed` - Lista notebook sincronizzati
+- `DELETE /api/v1/notebooklm/sync/{notebook_id}` - Rimuovi sincronizzazione
+- `GET /api/v1/notebooklm/sync/{notebook_id}/status` - Verifica stato sincronizzazione
+- `POST /api/v1/query/notebooks` - Query solo sui notebook
+
+**Query con filtri notebook:**
+```bash
+# Ricerca in notebook specifici
+POST /api/v1/query
+{
+  "question": "Quali sono i punti chiave?",
+  "notebook_ids": ["uuid-1", "uuid-2"],
+  "include_documents": true  # Include anche documenti locali
+}
+
+# Ricerca solo nei notebook
+POST /api/v1/query/notebooks
+{
+  "question": "Trova informazioni su...",
+  "notebook_ids": ["uuid-1"],
+  "k": 10
+}
+```
+
+---
+
 **Provider LLM Supportati:**
 
 | Provider | Modelli Principali | Stato |
@@ -217,6 +285,9 @@ DEBUG=false
 
 ## Avvio
 
+### Integrazione
+- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
+
 ### NotebookLM Agent
 
 ```bash
@@ -292,6 +363,39 @@ curl -X POST http://localhost:8000/api/v1/query \
     "provider": "openai",
     "model": "gpt-4o-mini"
   }'
+
+
+### Integrazione NotebookLM + RAG
+
+**Sincronizzare un notebook:**
+```bash
+# Sincronizza un notebook da NotebookLM al vector store
+curl -X POST http://localhost:8000/api/v1/notebooklm/sync/{notebook_id}
+
+# Lista notebook sincronizzati
+curl http://localhost:8000/api/v1/notebooklm/indexed
+
+# Rimuovi sincronizzazione
+curl -X DELETE http://localhost:8000/api/v1/notebooklm/sync/{notebook_id}
+```
+
+**Query sui notebook:**
+```bash
+# Query solo sui notebook (senza documenti locali)
+curl -X POST http://localhost:8000/api/v1/query/notebooks   -H "Content-Type: application/json"   -d '{
+    "question": "Quali sono le conclusioni principali?",
+    "notebook_ids": ["uuid-del-notebook"],
+    "k": 10,
+    "provider": "openai"
+  }'
+
+# Query mista (documenti + notebook)
+curl -X POST http://localhost:8000/api/v1/query   -H "Content-Type: application/json"   -d '{
+    "question": "Confronta le informazioni tra i documenti e i notebook",
+    "notebook_ids": ["uuid-1", "uuid-2"],
+    "include_documents": true,
+    "provider": "anthropic"
+  }'
 ```
 
 ---
@@ -351,6 +455,9 @@ documente/
 
 ## Documentazione
 
+### Integrazione
+- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
+
 ### NotebookLM Agent
 - [SKILL.md](./SKILL.md) - Skill definition per agenti AI
 - [prd.md](./prd.md) - Product Requirements Document
diff --git a/SKILL.md b/SKILL.md
index a92eaef..03dbb66 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -31,6 +31,7 @@ Interfaccia agentica per Google NotebookLM tramite API REST e webhook. Automatiz
 | **Generazione** | Audio (podcast), Video, Slide, Infografiche, Quiz, Flashcard, Report, Mappe mentali, Tabelle |
 | **Artifacts** | Monitorare stato, scaricare in vari formati |
 | **Webhook** | Registrare endpoint, ricevere notifiche eventi |
+| **RAG Integration** | Sincronizzare notebook, ricerche semantiche, query multi-notebook |
 
 ---
 
@@ -73,6 +74,10 @@ http://localhost:8000/health
 | `GET /api/v1/notebooks/{id}/chat/history` | Read-only |
 | `GET /api/v1/notebooks/{id}/artifacts` | Read-only |
 | `GET /api/v1/notebooks/{id}/artifacts/{id}/status` | Read-only |
+| `GET /api/v1/notebooklm/indexed` | Read-only |
+| `GET /api/v1/notebooklm/sync/{id}/status` | Read-only |
+| `POST /api/v1/query` | Read-only (ricerca) |
+| `POST /api/v1/query/notebooks` | Read-only (ricerca) |
 | `GET /health` | Health check |
 | `POST /api/v1/webhooks/{id}/test` | Test non distruttivo |
 
@@ -86,6 +91,8 @@ http://localhost:8000/health
 | `POST /api/v1/notebooks/{id}/generate/*` | Lungo, può fallire |
 | `GET /api/v1/notebooks/{id}/artifacts/{id}/download` | Scrive filesystem |
 | `POST /api/v1/webhooks` | Configura endpoint |
+| `POST /api/v1/notebooklm/sync/{id}` | Indicizza dati (tempo/risorse) |
+| `DELETE /api/v1/notebooklm/sync/{id}` | Rimuove dati indicizzati |
 
 ---
 
@@ -242,6 +249,46 @@ curl http://localhost:8000/api/v1/notebooks/{id}/artifacts/{artifact_id}/downloa
   -o artifact.mp3
 ```
 
+### RAG Integration
+
+```bash
+# Sincronizzare notebook nel vector store
+curl -X POST http://localhost:8000/api/v1/notebooklm/sync/{notebook_id} \
+  -H "X-API-Key: your-key"
+
+# Lista notebook sincronizzati
+curl http://localhost:8000/api/v1/notebooklm/indexed \
+  -H "X-API-Key: your-key"
+
+# Query sui notebook (solo contenuto notebook)
+curl -X POST http://localhost:8000/api/v1/query/notebooks \
+  -H "X-API-Key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "Quali sono i punti chiave?",
+    "notebook_ids": ["uuid-1", "uuid-2"],
+    "k": 10,
+    "provider": "openai"
+  }'
+
+# Query mista (documenti + notebook)
+curl -X POST http://localhost:8000/api/v1/query \
+  -H "X-API-Key: your-key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "Confronta le informazioni tra documenti e notebook",
+    "notebook_ids": ["uuid-1"],
+    "include_documents": true,
+    "provider": "anthropic"
+  }'
+
+# Rimuovere sincronizzazione
+curl -X DELETE http://localhost:8000/api/v1/notebooklm/sync/{notebook_id} \
+  -H "X-API-Key: your-key"
+```
+
+---
+
 ### Webhook Management
 
 ```bash
@@ -555,7 +602,7 @@ curl http://localhost:8000/api/v1/notebooks -H "X-API-Key: your-key"
 
 ---
 
-**Skill Version:** 1.1.0  
+**Skill Version:** 1.2.0  
 **API Version:** v1  
 **Last Updated:** 2026-04-06
 
@@ -585,3 +632,38 @@ curl http://localhost:8000/api/v1/notebooks -H "X-API-Key: your-key"
 - Chat functionality
 - Content generation (audio, video, etc.)
 - Webhook system
+
+---
+
+## Changelog Sprint 2
+
+### 2026-04-06 - NotebookLM + RAG Integration
+
+**Implemented:**
+- ✅ `POST /api/v1/notebooklm/sync/{id}` - Sync notebook to RAG vector store
+- ✅ `GET /api/v1/notebooklm/indexed` - List synced notebooks
+- ✅ `DELETE /api/v1/notebooklm/sync/{id}` - Remove notebook from RAG
+- ✅ `GET /api/v1/notebooklm/sync/{id}/status` - Check sync status
+- ✅ `POST /api/v1/query/notebooks` - Query only notebook content
+- ✅ Enhanced `POST /api/v1/query` - Filter by notebook_ids
+
+**Features:**
+- NotebookLMIndexerService for content extraction and indexing
+- Vector store integration with Qdrant
+- Metadata preservation (notebook_id, source_id, source_title)
+- Multi-notebook queries
+- Hybrid search (documents + notebooks)
+- Support for all LLM providers in notebook queries
+- Comprehensive test coverage (428 lines of tests)
+
+**Architecture:**
+- Service layer: NotebookLMIndexerService
+- API routes: notebooklm_sync.py
+- Enhanced RAGService with notebook filtering
+- Extended VectorStoreService with filter support
+
+**Documentation:**
+- ✅ Updated README.md with integration overview
+- ✅ Created docs/integration.md with full guide
+- ✅ Updated SKILL.md with new capabilities
+- ✅ API examples and best practices
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..fd6841d
--- /dev/null
+++ b/docs/integration.md
@@ -0,0 +1,436 @@
+# Guida Integrazione NotebookLM + RAG
+
+Questo documento descrive l'integrazione tra **NotebookLM Agent** e **DocuMente RAG**, che permette di eseguire ricerche semantiche (RAG) sui contenuti dei notebook di Google NotebookLM.
+
+---
+
+## Indice
+
+- [Overview](#overview)
+- [Architettura](#architettura)
+- [Come Funziona](#come-funziona)
+- [API Reference](#api-reference)
+- [Esempi di Utilizzo](#esempi-di-utilizzo)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+L'integrazione colma il divario tra **gestione notebook** (NotebookLM Agent) e **ricerca semantica** (DocuMente RAG), permettendo di:
+
+- 🔍 **Ricercare** nei contenuti dei notebook con semantic search
+- 🧠 **Usare LLM multi-provider** per interrogare i notebook
+- 📊 **Combinare** notebook e documenti locali nelle stesse query
+- 🎯 **Filtrare** per notebook specifici
+- ⚡ **Indicizzare** automaticamente i contenuti
+
+### Use Cases
+
+1. **Research Assistant**: "Cosa dicono tutti i miei notebook sull'intelligenza artificiale?"
+2. **Knowledge Mining**: "Trova tutte le fonti che parlano di Python nei miei notebook di programmazione"
+3. **Cross-Notebook Analysis**: "Confronta le conclusioni tra il notebook A e il notebook B"
+4. **Document + Notebook Search**: "Quali informazioni ho sia nei documenti PDF che nei notebook?"
+
+---
+
+## Architettura
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        NotebookLM Agent                         │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
+│  │  Notebooks  │───▶│   Sources   │───▶│   Full Text Get     │ │
+│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              │ Extract Content
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   NotebookLMIndexerService                      │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
+│  │   Chunking  │───▶│  Embedding  │───▶│   Metadata Store    │ │
+│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              │ Index to Vector Store
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         Qdrant Vector Store                     │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │  Collection: "documents"                                  │  │
+│  │  Points with metadata:                                    │  │
+│  │    - notebook_id, source_id, source_title                 │  │
+│  │    - notebook_title, source_type                          │  │
+│  │    - source: "notebooklm"                                 │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              │ Query with Filters
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                          RAGService                             │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐ │
+│  │    Query    │───▶│   Search    │───▶│   LLM Generation    │ │
+│  └─────────────┘    └─────────────┘    └─────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Come Funziona
+
+### 1. Sincronizzazione
+
+Quando sincronizzi un notebook:
+
+1. **Estrazione**: Ottiene tutte le fonti dal notebook via `notebooklm-py`
+2. **Full Text**: Recupera il testo completo di ogni fonte (se disponibile)
+3. **Chunking**: Divide i contenuti in chunks di ~1024 caratteri
+4. **Embedding**: Genera embeddings vettoriali usando OpenAI
+5. **Storage**: Salva in Qdrant con metadata completi
+
+### 2. Metadata Structure
+
+Ogni chunk memorizzato contiene:
+
+```json
+{
+  "text": "contenuto del chunk...",
+  "notebook_id": "uuid-del-notebook",
+  "source_id": "uuid-della-fonte",
+  "source_title": "Titolo della Fonte",
+  "source_type": "url|file|youtube|drive",
+  "notebook_title": "Titolo del Notebook",
+  "source": "notebooklm"
+}
+```
+
+### 3. Query
+
+Quando esegui una query:
+
+1. **Embedding**: La domanda viene convertita in embedding
+2. **Search**: Qdrant cerca i chunk più simili
+3. **Filter**: Se specificati, filtra per `notebook_id`
+4. **Context**: I chunk vengono formattati come contesto
+5. **Generation**: Il LLM genera la risposta basata sul contesto
+
+---
+
+## API Reference
+
+### Sync Endpoints
+
+#### POST `/api/v1/notebooklm/sync/{notebook_id}`
+Sincronizza un notebook da NotebookLM al vector store.
+
+**Response:**
+```json
+{
+  "sync_id": "uuid-della-sync",
+  "notebook_id": "uuid-del-notebook",
+  "notebook_title": "Titolo Notebook",
+  "status": "success",
+  "sources_indexed": 5,
+  "total_chunks": 42,
+  "message": "Successfully synced 5 sources with 42 chunks"
+}
+```
+
+#### GET `/api/v1/notebooklm/indexed`
+Lista tutti i notebook sincronizzati.
+
+**Response:**
+```json
+{
+  "notebooks": [
+    {
+      "notebook_id": "uuid-1",
+      "notebook_title": "AI Research",
+      "sources_count": 10,
+      "chunks_count": 150,
+      "last_sync": "2026-01-15T10:30:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+#### DELETE `/api/v1/notebooklm/sync/{notebook_id}`
+Rimuove un notebook dal vector store.
+
+**Response:**
+```json
+{
+  "notebook_id": "uuid-del-notebook",
+  "deleted": true,
+  "message": "Successfully removed index..."
+}
+```
+
+#### GET `/api/v1/notebooklm/sync/{notebook_id}/status`
+Verifica lo stato di sincronizzazione di un notebook.
+
+**Response:**
+```json
+{
+  "notebook_id": "uuid-del-notebook",
+  "status": "indexed",
+  "sources_count": 5,
+  "chunks_count": 42,
+  "last_sync": "2026-01-15T10:30:00Z"
+}
+```
+
+### Query Endpoints
+
+#### POST `/api/v1/query` (with notebook filter)
+Esegue una RAG query con possibilità di filtrare per notebook.
+
+**Request:**
+```json
+{
+  "question": "Quali sono i punti chiave?",
+  "notebook_ids": ["uuid-1", "uuid-2"],
+  "include_documents": true,
+  "k": 10,
+  "provider": "openai",
+  "model": "gpt-4o"
+}
+```
+
+**Response:**
+```json
+{
+  "question": "Quali sono i punti chiave?",
+  "answer": "Secondo i documenti e i notebook analizzati...",
+  "provider": "openai",
+  "model": "gpt-4o",
+  "sources": [
+    {
+      "text": "Contenuto del chunk...",
+      "source_type": "notebooklm",
+      "notebook_id": "uuid-1",
+      "notebook_title": "AI Research",
+      "source_title": "Introduction to AI"
+    }
+  ],
+  "user": "anonymous",
+  "filters_applied": {
+    "notebook_ids": ["uuid-1", "uuid-2"],
+    "include_documents": true
+  }
+}
+```
+
+#### POST `/api/v1/query/notebooks`
+Esegue una query **solo** sui notebook (esclude documenti locali).
+
+**Request:**
+```json
+{
+  "question": "Trova informazioni su...",
+  "notebook_ids": ["uuid-1"],
+  "k": 10,
+  "provider": "anthropic"
+}
+```
+
+---
+
+## Esempi di Utilizzo
+
+### Esempio 1: Sincronizzazione e Query Base
+
+```bash
+# 1. Sincronizza un notebook
+curl -X POST http://localhost:8000/api/v1/notebooklm/sync/abc-123
+
+# 2. Query sul notebook sincronizzato
+curl -X POST http://localhost:8000/api/v1/query/notebooks \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "Quali sono le tecnologie AI menzionate?",
+    "notebook_ids": ["abc-123"]
+  }'
+```
+
+### Esempio 2: Ricerca Multi-Notebook
+
+```bash
+# Query su più notebook contemporaneamente
+curl -X POST http://localhost:8000/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{
+    "question": "Confronta gli approcci di machine learning descritti",
+    "notebook_ids": ["notebook-1", "notebook-2", "notebook-3"],
+    "k": 15,
+    "provider": "anthropic"
+  }'
+```
+
+### Esempio 3: Workflow Completo
+
+```bash
+#!/bin/bash
+
+# 1. Ottieni lista notebook da NotebookLM
+NOTEBOOKS=$(curl -s http://localhost:8000/api/v1/notebooks)
+
+# 2. Sincronizza il primo notebook
+NOTEBOOK_ID=$(echo $NOTEBOOKS | jq -r '.data.items[0].id')
+echo "Sincronizzazione notebook: $NOTEBOOK_ID"
+
+SYNC_RESULT=$(curl -s -X POST "http://localhost:8000/api/v1/notebooklm/sync/$NOTEBOOK_ID")
+echo "Risultato: $SYNC_RESULT"
+
+# 3. Attendi che la sincronizzazione sia completata (se asincrona)
+sleep 2
+
+# 4. Esegui query sul notebook
+curl -X POST http://localhost:8000/api/v1/query/notebooks \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"question\": \"Riassumi i punti principali\",
+    \"notebook_ids\": [\"$NOTEBOOK_ID\"],
+    \"provider\": \"openai\"
+  }"
+```
+
+---
+
+## Best Practices
+
+### 1. **Sincronizzazione Selettiva**
+Non sincronizzare tutti i notebook, solo quelli rilevanti per le ricerche.
+
+```bash
+# Sincronizza solo i notebook attivi
+for notebook_id in "notebook-1" "notebook-2"; do
+  curl -X POST "http://localhost:8000/api/v1/notebooklm/sync/$notebook_id"
+done
+```
+
+### 2. **Gestione Chunks**
+Ogni fonte viene divisa in chunks di ~1024 caratteri. Se un notebook ha molte fonti grandi, considera:
+- Aumentare `k` nelle query (default: 5, max: 50)
+- Filtrare per notebook specifici per ridurre il contesto
+
+### 3. **Provider Selection**
+Usa provider diversi per tipologie di query diverse:
+- **OpenAI GPT-4o**: Query complesse, analisi dettagliate
+- **Anthropic Claude**: Sintesi lunghe, analisi testuali
+- **Mistral**: Query veloci, risposte concise
+
+### 4. **Refresh Periodico**
+I notebook cambiano nel tempo. Considera di:
+- Rimuovere e risincronizzare periodicamente
+- Aggiungere un job schedulato per il refresh
+
+```bash
+# Cron job per refresh settimanale
+0 2 * * 0 /path/to/sync-notebooks.sh
+```
+
+### 5. **Monitoraggio**
+Traccia quali notebook sono sincronizzati:
+
+```bash
+# Lista e verifica stato
+curl http://localhost:8000/api/v1/notebooklm/indexed | jq '.'
+```
+
+---
+
+## Troubleshooting
+
+### Problema: Sincronizzazione fallita
+
+**Sintomi**: Errore 500 durante la sincronizzazione
+
+**Causa**: NotebookLM potrebbe non avere il testo completo disponibile per alcune fonti
+
+**Soluzione**:
+1. Verifica che il notebook esista: `GET /api/v1/notebooks/{id}`
+2. Controlla che le fonti siano indicizzate: NotebookLM mostra "Ready"
+3. Alcune fonti (YouTube, Drive) potrebbero non avere testo estratto
+
+### Problema: Query non trova risultati
+
+**Sintomi**: Risposta "I don't have enough information..."
+
+**Verifica**:
+```bash
+# 1. Il notebook è sincronizzato?
+curl http://localhost:8000/api/v1/notebooklm/sync/{notebook_id}/status
+
+# 2. Quanti chunks ci sono?
+curl http://localhost:8000/api/v1/notebooklm/indexed
+```
+
+**Soluzione**:
+- Aumenta `k` nella query
+- Verifica che il contenuto sia stato effettivamente estratto
+- Controlla che l'embedding model sia configurato correttamente
+
+### Problema: Rate Limiting
+
+**Sintomi**: Errori 429 durante sincronizzazione
+
+**Soluzione**:
+- NotebookLM ha rate limits aggressivi
+- Aggiungi delay tra le sincronizzazioni
+- Sincronizza durante ore di basso traffico
+
+```python
+# Aggiungi delay
+import asyncio
+
+for notebook_id in notebook_ids:
+    await sync_notebook(notebook_id)
+    await asyncio.sleep(5)  # Attendi 5 secondi
+```
+
+---
+
+## Performance Considerations
+
+### Dimensione dei Chunks
+- **Default**: 1024 caratteri
+- **Trade-off**: 
+  - Chunks più grandi = più contesto ma meno precisione
+  - Chunks più piccoli = più precisione ma meno contesto
+
+### Numero di Notebook
+- **Consigliato**: < 50 notebook sincronizzati contemporaneamente
+- **Ottimale**: Filtra per notebook specifici nelle query
+
+### Refresh Strategy
+- **Full Refresh**: Rimuovi tutto e risincronizza (lento ma pulito)
+- **Incremental**: Aggiungi solo nuove fonti (più veloce ma può avere duplicati)
+
+---
+
+## Limitazioni Conosciute
+
+1. **Testo Completo**: Non tutte le fonti di NotebookLM hanno testo completo disponibile (es. alcuni PDF, YouTube)
+2. **Sync Non Automatica**: La sincronizzazione è manuale via API, non automatica
+3. **Storage**: I chunks duplicano lo storage (contenuto sia in NotebookLM che in Qdrant)
+4. **Embedding Model**: Attualmente usa OpenAI per embeddings (configurabile in futuro)
+
+---
+
+## Roadmap
+
+- [ ] **Auto-Sync**: Sincronizzazione automatica quando i notebook cambiano
+- [ ] **Incremental Sync**: Aggiornamento solo delle fonti modificate
+- [ ] **Multi-Embedder**: Supporto per altri modelli di embedding
+- [ ] **Semantic Chunking**: Chunking basato su significato anziché lunghezza
+- [ ] **Cross-Reference**: Link tra fonti simili in notebook diversi
+
+---
+
+**Versione**: 1.0.0  
+**Ultimo Aggiornamento**: 2026-04-06