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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](../SKILL.md)