lucasacchi/documente
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: comprehensive documentation for NotebookLM-RAG integration
Some checks failed
CI / test (3.10) (push) Has been cancelled
Details
CI / test (3.11) (push) Has been cancelled
Details
CI / test (3.12) (push) Has been cancelled
Details
CI / lint (push) Has been cancelled
Details

Browse Source 
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.
This commit is contained in:
Luca Sacchi Ricciardi
2026-04-06 18:01:50 +02:00
parent a5029aef20
commit 568489cae4
3 changed files with 628 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@@ -31,6 +31,9 @@ Questo repository contiene **due sistemi AI complementari**:
## Panoramica ## Panoramica
### Integrazione
- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
### NotebookLM Agent ### NotebookLM Agent
Interfaccia API e webhook per **Google NotebookLM** che permette: 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 **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 ## Componenti
### Integrazione
- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
### NotebookLM Agent ### NotebookLM Agent
``` ```
@@ -101,16 +139,46 @@ src/agentic_rag/
│ ├── documents.py # Upload documenti │ ├── documents.py # Upload documenti
│ ├── query.py # Query RAG │ ├── query.py # Query RAG
│ ├── chat.py # Chat conversazionale │ ├── chat.py # Chat conversazionale
│ └── providers.py # Gestione provider LLM │ ├── providers.py # Gestione provider LLM
│ └── notebooklm_sync.py # [NUOVO] Sync NotebookLM
├── services/ # Business logic ├── services/ # Business logic
│ ├── rag_service.py # Core RAG logic │ ├── rag_service.py # Core RAG logic
│ ├── vector_store.py # Qdrant integration │ ├── vector_store.py # Qdrant integration
│ └── document_service.py │ ├── document_service.py
│ └── notebooklm_indexer.py # [NUOVO] Indexing service
└── core/ # Configurazioni └── core/ # Configurazioni
├── config.py # Multi-provider config ├── config.py # Multi-provider config
└── llm_factory.py # LLM factory pattern └── 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 LLM Supportati:**
| Provider | Modelli Principali | Stato | | Provider | Modelli Principali | Stato |
@@ -217,6 +285,9 @@ DEBUG=false
## Avvio ## Avvio
### Integrazione
- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
### NotebookLM Agent ### NotebookLM Agent
```bash ```bash
@@ -292,6 +363,39 @@ curl -X POST http://localhost:8000/api/v1/query \
"provider": "openai", "provider": "openai",
"model": "gpt-4o-mini" "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 ## Documentazione
### Integrazione
- [docs/integration.md](./docs/integration.md) - Guida integrazione NotebookLM + RAG
### NotebookLM Agent ### NotebookLM Agent
- [SKILL.md](./SKILL.md) - Skill definition per agenti AI - [SKILL.md](./SKILL.md) - Skill definition per agenti AI
- [prd.md](./prd.md) - Product Requirements Document - [prd.md](./prd.md) - Product Requirements Document

84
SKILL.md
View File

@@ -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 | | **Generazione** | Audio (podcast), Video, Slide, Infografiche, Quiz, Flashcard, Report, Mappe mentali, Tabelle |
| **Artifacts** | Monitorare stato, scaricare in vari formati | | **Artifacts** | Monitorare stato, scaricare in vari formati |
| **Webhook** | Registrare endpoint, ricevere notifiche eventi | | **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}/chat/history` | Read-only |
| `GET /api/v1/notebooks/{id}/artifacts` | Read-only | | `GET /api/v1/notebooks/{id}/artifacts` | Read-only |
| `GET /api/v1/notebooks/{id}/artifacts/{id}/status` | 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 | | `GET /health` | Health check |
| `POST /api/v1/webhooks/{id}/test` | Test non distruttivo | | `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 | | `POST /api/v1/notebooks/{id}/generate/*` | Lungo, può fallire |
| `GET /api/v1/notebooks/{id}/artifacts/{id}/download` | Scrive filesystem | | `GET /api/v1/notebooks/{id}/artifacts/{id}/download` | Scrive filesystem |
| `POST /api/v1/webhooks` | Configura endpoint | | `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 -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 ### Webhook Management
```bash ```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 **API Version:** v1
**Last Updated:** 2026-04-06 **Last Updated:** 2026-04-06
@@ -585,3 +632,38 @@ curl http://localhost:8000/api/v1/notebooks -H "X-API-Key: your-key"
- Chat functionality - Chat functionality
- Content generation (audio, video, etc.) - Content generation (audio, video, etc.)
- Webhook system - 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

436
docs/integration.md Normal file
View File

@@ -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