docs: simplify documentation - clarify two separate systems
Rewrite documentation to clearly separate the two systems: README.md Changes: - Restructure as two independent systems (NotebookLM Agent vs DocuMente) - Clear separation of requirements: * NotebookLM Agent: NO Qdrant needed * DocuMente RAG: Qdrant REQUIRED - Remove confusing 'dual-system' language - Add FAQ section clarifying common questions - Simplified examples for each system - Clear statement: systems work independently docs/integration.md Changes: - Remove overly complex architecture diagrams - Focus on practical usage only - Simplified to 3 steps: start services → sync → query - Remove redundant API documentation (refer to SKILL.md) - Add clear use cases section - Shorter troubleshooting section docs/README.md Changes: - Minimal structure overview - Clear separation of endpoints by system - Quick links to relevant docs Impact: - 821 lines removed, 259 added - Much clearer for new users - No confusion about Qdrant requirements - Clear distinction between the two systems Closes documentation clarity issue
This commit is contained in:
Luca Sacchi Ricciardi
530
README.md
530
README.md
@@ -5,508 +5,198 @@
|
||||
[](https://github.com/astral-sh/ruff)
|
||||
[](https://docs.pytest.org/)
|
||||
|
||||
> **Piattaforma AI Completa - RAG Multi-Provider + Automazione NotebookLM**
|
||||
> **Due Sistemi AI - Usali Separatamente o Insieme**
|
||||
|
||||
Questo repository contiene **due sistemi AI complementari**:
|
||||
|
||||
1. **NotebookLM Agent** - API REST per l'automazione programmatica di Google NotebookLM
|
||||
2. **DocuMente (Agentic RAG)** - Sistema RAG avanzato con supporto multi-provider LLM
|
||||
Questo repository contiene **due sistemi AI indipendenti** che puoi usare separatamente o insieme:
|
||||
|
||||
---
|
||||
|
||||
## Indice
|
||||
## 🤖 NotebookLM Agent
|
||||
|
||||
- [Panoramica](#panoramica)
|
||||
- [Integrazione NotebookLM + RAG](#integrazione-notebooklm--rag)
|
||||
- [Componenti](#componenti)
|
||||
- [Requisiti](#requisiti)
|
||||
- [Installazione](#installazione)
|
||||
- [Configurazione](#configurazione)
|
||||
- [Avvio](#avvio)
|
||||
- [Testing](#testing)
|
||||
- [Struttura Progetto](#struttura-progetto)
|
||||
- [Documentazione](#documentazione)
|
||||
- [Licenza](#licenza)
|
||||
API REST per gestire **Google NotebookLM** programmaticamente.
|
||||
|
||||
---
|
||||
### Cosa fa
|
||||
- Crea e gestisci notebook NotebookLM
|
||||
- Aggiungi fonti (URL, PDF, YouTube, Drive)
|
||||
- Chat con le fonti
|
||||
- Genera contenuti (podcast, video, quiz, flashcard)
|
||||
- Ricevi notifiche via webhook
|
||||
|
||||
## Panoramica
|
||||
### Requisiti
|
||||
- Python 3.10+
|
||||
- Account Google NotebookLM
|
||||
|
||||
### NotebookLM Agent
|
||||
|
||||
Interfaccia API e webhook per **Google NotebookLM** che permette:
|
||||
- Gestione programmatica di notebook, fonti e chat
|
||||
- Generazione automatica di contenuti (podcast, video, quiz, flashcard, slide)
|
||||
- Integrazione con altri agenti AI tramite webhook
|
||||
- Automazione completa dei workflow NotebookLM
|
||||
|
||||
**Ideale per:** Automation engineer, Content creator, AI Agent developers
|
||||
|
||||
### DocuMente (Agentic RAG)
|
||||
|
||||
Sistema **Retrieval-Augmented Generation** standalone con:
|
||||
- Supporto per 8+ provider LLM (cloud e locali)
|
||||
- Upload e indicizzazione documenti (PDF, DOCX, TXT, MD)
|
||||
- Chat conversazionale con i tuoi documenti
|
||||
- Interfaccia web moderna (React + TypeScript)
|
||||
- **Integrazione con NotebookLM** - Ricerca semantica sui notebook
|
||||
|
||||
**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
|
||||
|
||||
📚 **[Guida Completa Integrazione](./docs/integration.md)** - API, esempi, best practices
|
||||
|
||||
---
|
||||
|
||||
## Componenti
|
||||
|
||||
### NotebookLM Agent
|
||||
|
||||
```
|
||||
src/notebooklm_agent/
|
||||
├── api/ # FastAPI REST API
|
||||
│ ├── main.py # Application entry
|
||||
│ ├── routes/ # API endpoints
|
||||
│ │ ├── notebooks.py # CRUD notebook
|
||||
│ │ ├── sources.py # Gestione fonti
|
||||
│ │ ├── chat.py # Chat interattiva
|
||||
│ │ ├── generation.py # Generazione contenuti
|
||||
│ │ └── webhooks.py # Webhook management
|
||||
│ └── models/ # Pydantic models
|
||||
├── services/ # Business logic
|
||||
└── webhooks/ # Webhook system
|
||||
```
|
||||
|
||||
**Funzionalita principali:**
|
||||
|
||||
| Categoria | Operazioni |
|
||||
|-----------|------------|
|
||||
| **Notebook** | Creare, listare, ottenere, aggiornare, eliminare |
|
||||
| **Fonti** | Aggiungere URL, PDF, YouTube, Drive, ricerca web |
|
||||
| **Chat** | Interrogare fonti, storico conversazioni |
|
||||
| **Generazione** | Audio (podcast), Video, Slide, Quiz, Flashcard, Report, Mappe mentali |
|
||||
| **Webhook** | Registrare endpoint, ricevere notifiche eventi |
|
||||
|
||||
**Endpoint API principali:**
|
||||
- `POST /api/v1/notebooks` - Creare notebook
|
||||
- `POST /api/v1/notebooks/{id}/sources` - Aggiungere fonti
|
||||
- `POST /api/v1/notebooks/{id}/chat` - Chat con le fonti
|
||||
- `POST /api/v1/notebooks/{id}/generate/audio` - Generare podcast
|
||||
- `POST /api/v1/webhooks` - Registrare webhook
|
||||
|
||||
---
|
||||
|
||||
### DocuMente (Agentic RAG)
|
||||
|
||||
```
|
||||
src/agentic_rag/
|
||||
├── api/ # FastAPI REST API
|
||||
│ ├── main.py # Application entry
|
||||
│ └── routes/ # API endpoints
|
||||
│ ├── documents.py # Upload documenti
|
||||
│ ├── query.py # Query RAG
|
||||
│ ├── chat.py # Chat conversazionale
|
||||
│ ├── providers.py # Gestione provider LLM
|
||||
│ └── notebooklm_sync.py # Sync NotebookLM
|
||||
├── services/ # Business logic
|
||||
│ ├── rag_service.py # Core RAG logic
|
||||
│ ├── vector_store.py # Qdrant integration
|
||||
│ ├── document_service.py
|
||||
│ └── notebooklm_indexer.py # 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:**
|
||||
### Installazione
|
||||
```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 | Tipo | Modelli Principali |
|
||||
|----------|------|-------------------|
|
||||
| **OpenAI** | Cloud | GPT-4o, GPT-4, GPT-3.5 |
|
||||
| **Anthropic** | Cloud | Claude 3.5, Claude 3 |
|
||||
| **Google** | Cloud | Gemini 1.5 Pro/Flash |
|
||||
| **Mistral** | Cloud | Mistral Large/Medium |
|
||||
| **Azure** | Cloud | GPT-4, GPT-4o |
|
||||
| **Z.AI** | Cloud | zai-large, zai-medium |
|
||||
| **OpenCode Zen** | Cloud | zen-1, zen-lite |
|
||||
| **OpenRouter** | Cloud | Multi-model access |
|
||||
| **Ollama** | 🏠 Locale | llama3.2, mistral, qwen |
|
||||
| **LM Studio** | 🏠 Locale | Any loaded model |
|
||||
|
||||
---
|
||||
|
||||
## Requisiti
|
||||
|
||||
- **Python** 3.10+
|
||||
- **[uv](https://github.com/astral-sh/uv)** - Dependency management
|
||||
- **[Node.js](https://nodejs.org/)** 18+ (solo per DocuMente frontend)
|
||||
- **Docker** (opzionale)
|
||||
- **Qdrant** (per DocuMente vector store)
|
||||
|
||||
---
|
||||
|
||||
## Installazione
|
||||
|
||||
```bash
|
||||
# Clona il repository
|
||||
# Clona e installa
|
||||
git clone <repository-url>
|
||||
cd documente
|
||||
|
||||
# Crea ambiente virtuale
|
||||
uv venv --python 3.10
|
||||
source .venv/bin/activate
|
||||
uv sync
|
||||
|
||||
# Installa tutte le dipendenze
|
||||
uv sync --extra dev --extra browser
|
||||
```
|
||||
|
||||
**Per DocuMente (frontend):**
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configurazione
|
||||
|
||||
Crea un file `.env` nella root del progetto:
|
||||
|
||||
```env
|
||||
# ========================================
|
||||
# NotebookLM Agent Configuration
|
||||
# ========================================
|
||||
NOTEBOOKLM_AGENT_API_KEY=your-api-key
|
||||
NOTEBOOKLM_AGENT_WEBHOOK_SECRET=your-webhook-secret
|
||||
NOTEBOOKLM_AGENT_PORT=8000
|
||||
NOTEBOOKLM_AGENT_HOST=0.0.0.0
|
||||
|
||||
# NotebookLM Authentication (via notebooklm-py)
|
||||
# Esegui: notebooklm login (prima volta)
|
||||
NOTEBOOKLM_HOME=~/.notebooklm
|
||||
NOTEBOOKLM_PROFILE=default
|
||||
|
||||
# ========================================
|
||||
# DocuMente (Agentic RAG) Configuration
|
||||
# ========================================
|
||||
|
||||
# LLM Provider API Keys (configura almeno uno)
|
||||
OPENAI_API_KEY=sk-...
|
||||
ZAI_API_KEY=...
|
||||
OPENCODE_ZEN_API_KEY=...
|
||||
OPENROUTER_API_KEY=...
|
||||
ANTHROPIC_API_KEY=...
|
||||
GOOGLE_API_KEY=...
|
||||
MISTRAL_API_KEY=...
|
||||
AZURE_API_KEY=...
|
||||
AZURE_ENDPOINT=https://your-resource.openai.azure.com
|
||||
|
||||
# Local LLM Providers (no API key needed)
|
||||
OLLAMA_BASE_URL=http://localhost:11434
|
||||
LMSTUDIO_BASE_URL=http://localhost:1234
|
||||
|
||||
# Vector Store (Qdrant)
|
||||
QDRANT_HOST=localhost
|
||||
QDRANT_PORT=6333
|
||||
QDRANT_COLLECTION=documents
|
||||
|
||||
# Embedding Configuration
|
||||
EMBEDDING_MODEL=text-embedding-3-small
|
||||
EMBEDDING_API_KEY=sk-...
|
||||
|
||||
# Default LLM Provider
|
||||
default_llm_provider=openai
|
||||
|
||||
# ========================================
|
||||
# General Configuration
|
||||
# ========================================
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Avvio
|
||||
|
||||
### NotebookLM Agent
|
||||
|
||||
```bash
|
||||
# 1. Autenticazione NotebookLM (prima volta)
|
||||
# Autenticazione NotebookLM (prima volta)
|
||||
notebooklm login
|
||||
|
||||
# 2. Avvio server API
|
||||
uv run fastapi dev src/notebooklm_agent/api/main.py
|
||||
|
||||
# Server disponibile su http://localhost:8000
|
||||
# API docs: http://localhost:8000/docs
|
||||
```
|
||||
|
||||
**Esempio di utilizzo API:**
|
||||
|
||||
### Avvio
|
||||
```bash
|
||||
# Creare un notebook
|
||||
uv run fastapi dev src/notebooklm_agent/api/main.py
|
||||
```
|
||||
|
||||
API disponibile su: http://localhost:8000
|
||||
|
||||
### Esempio
|
||||
```bash
|
||||
# Crea notebook
|
||||
curl -X POST http://localhost:8000/api/v1/notebooks \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "Ricerca AI", "description": "Studio AI"}'
|
||||
-d '{"title": "Ricerca AI"}'
|
||||
|
||||
# Aggiungere una fonte URL
|
||||
# Aggiungi fonte
|
||||
curl -X POST http://localhost:8000/api/v1/notebooks/{id}/sources \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"type": "url", "url": "https://example.com"}'
|
||||
|
||||
# Generare un podcast
|
||||
curl -X POST http://localhost:8000/api/v1/notebooks/{id}/generate/audio \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"format": "deep-dive", "length": "long"}'
|
||||
```
|
||||
|
||||
📚 **Documentazione**: [SKILL.md](./SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
### DocuMente (Agentic RAG)
|
||||
## 🧠 DocuMente (RAG con NotebookLM)
|
||||
|
||||
#### Con Docker (Consigliato)
|
||||
Sistema **RAG** (Retrieval-Augmented Generation) che permette di:
|
||||
- Caricare documenti (PDF, DOCX, TXT, MD)
|
||||
- Sincronizzare notebook da NotebookLM
|
||||
- Fare ricerche semantiche su entrambi
|
||||
- Chat con LLM multi-provider
|
||||
|
||||
### Cosa fa
|
||||
- **Ricerca su documenti**: Carica file e fai domande
|
||||
- **Ricerca su notebook**: Sincronizza notebook NotebookLM e interrogali
|
||||
- **Ricerca combinata**: Cerca sia nei documenti che nei notebook
|
||||
|
||||
### Requisiti
|
||||
- Python 3.10+
|
||||
- **Qdrant** (vector database)
|
||||
- Node.js 18+ (per frontend opzionale)
|
||||
|
||||
### Installazione
|
||||
```bash
|
||||
docker-compose up
|
||||
# Dipendenze già installate con uv sync sopra
|
||||
|
||||
# Avvia Qdrant (richiesto)
|
||||
docker run -p 6333:6333 qdrant/qdrant
|
||||
```
|
||||
|
||||
#### Manuale
|
||||
|
||||
### Avvio
|
||||
```bash
|
||||
# 1. Avvia Qdrant (in un terminale separato)
|
||||
docker run -p 6333:6333 qdrant/qdrant
|
||||
|
||||
# 2. Avvia backend
|
||||
# Backend
|
||||
uv run fastapi dev src/agentic_rag/api/main.py
|
||||
|
||||
# 3. Avvia frontend (in un altro terminale)
|
||||
cd frontend
|
||||
npm run dev
|
||||
# Frontend (opzionale)
|
||||
cd frontend && npm install && npm run dev
|
||||
```
|
||||
|
||||
**Servizi disponibili:**
|
||||
- **Web UI**: http://localhost:3000
|
||||
- **API docs**: http://localhost:8000/api/docs
|
||||
|
||||
**Esempio di utilizzo API:**
|
||||
Servizi:
|
||||
- API: http://localhost:8000/api
|
||||
- Web UI: http://localhost:3000
|
||||
|
||||
### Esempi
|
||||
```bash
|
||||
# Upload documento
|
||||
# Carica documento
|
||||
curl -X POST http://localhost:8000/api/v1/documents \
|
||||
-F "file=@documento.pdf"
|
||||
|
||||
# Query RAG
|
||||
curl -X POST http://localhost:8000/api/v1/query \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"question": "Qual e il contenuto principale?",
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-mini"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Integrazione NotebookLM + RAG
|
||||
|
||||
**Sincronizzare un notebook:**
|
||||
```bash
|
||||
# Sincronizza un notebook da NotebookLM al vector store
|
||||
# Sincronizza notebook da NotebookLM
|
||||
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)
|
||||
# Fai una domanda (cerca in 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"
|
||||
"question": "Trova informazioni su...",
|
||||
"notebook_ids": ["uuid-notebook"],
|
||||
"include_documents": true
|
||||
}'
|
||||
```
|
||||
|
||||
📚 **Documentazione Integrazione**: [docs/integration.md](./docs/integration.md)
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
## 🔧 Configurazione
|
||||
|
||||
```bash
|
||||
# Esegui tutti i test
|
||||
uv run pytest
|
||||
Crea un file `.env` nella root:
|
||||
|
||||
# Con coverage
|
||||
uv run pytest --cov=src --cov-report=term-missing
|
||||
```env
|
||||
# Per NotebookLM Agent
|
||||
NOTEBOOKLM_HOME=~/.notebooklm
|
||||
|
||||
# Solo unit test
|
||||
uv run pytest tests/unit/ -m unit
|
||||
# Per DocuMente (almeno un provider LLM)
|
||||
OPENAI_API_KEY=sk-... # o altro provider
|
||||
|
||||
# Test NotebookLM Agent
|
||||
uv run pytest tests/unit/test_notebooklm_agent/ -v
|
||||
# Per ricerche su notebook (opzionale)
|
||||
OLLAMA_BASE_URL=http://localhost:11434 # se usi Ollama
|
||||
LMSTUDIO_BASE_URL=http://localhost:1234 # se usi LM Studio
|
||||
|
||||
# Test DocuMente
|
||||
uv run pytest tests/unit/test_agentic_rag/ -v
|
||||
# Qdrant (solo per DocuMente)
|
||||
QDRANT_HOST=localhost
|
||||
QDRANT_PORT=6333
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Struttura Progetto
|
||||
## 📁 Struttura Progetto
|
||||
|
||||
```
|
||||
documente/
|
||||
├── src/
|
||||
│ ├── notebooklm_agent/ # API NotebookLM Agent
|
||||
│ ├── notebooklm_agent/ # 🤖 Solo NotebookLM
|
||||
│ │ ├── api/
|
||||
│ │ ├── services/
|
||||
│ │ ├── core/
|
||||
│ │ └── webhooks/
|
||||
│ └── agentic_rag/ # DocuMente RAG System
|
||||
│ │ └── services/
|
||||
│ │
|
||||
│ └── agentic_rag/ # 🧠 RAG + NotebookLM
|
||||
│ ├── api/
|
||||
│ ├── services/
|
||||
│ └── core/
|
||||
├── tests/
|
||||
│ ├── unit/
|
||||
│ │ ├── test_notebooklm_agent/
|
||||
│ │ └── test_agentic_rag/
|
||||
│ ├── integration/
|
||||
│ └── e2e/
|
||||
├── frontend/ # React + TypeScript UI
|
||||
│ ├── src/
|
||||
│ └── package.json
|
||||
├── docs/ # Documentazione
|
||||
├── prompts/ # Prompt engineering
|
||||
├── pyproject.toml # Configurazione progetto
|
||||
├── docker-compose.yml
|
||||
└── README.md
|
||||
│ └── ...
|
||||
│
|
||||
├── frontend/ # 🎨 Web UI (solo per RAG)
|
||||
├── docs/
|
||||
│ └── integration.md # Guida integrazione
|
||||
│
|
||||
└── tests/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentazione
|
||||
## 📚 Documentazione
|
||||
|
||||
### 📚 Guide Principali
|
||||
| File | Descrizione |
|
||||
|------|-------------|
|
||||
| **[SKILL.md](./SKILL.md)** | Guida completa NotebookLM Agent |
|
||||
| **[docs/integration.md](./docs/integration.md)** | Come integrare NotebookLM con RAG |
|
||||
| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Come contribuire |
|
||||
|
||||
| Documento | Descrizione |
|
||||
|-----------|-------------|
|
||||
| **[docs/integration.md](./docs/integration.md)** | Guida completa integrazione NotebookLM + RAG - API, esempi, best practices |
|
||||
| **[docs/README.md](./docs/README.md)** | Panoramica documentazione API e endpoint |
|
||||
---
|
||||
|
||||
### 🤖 NotebookLM Agent
|
||||
## ❓ FAQ
|
||||
|
||||
| Documento | Descrizione |
|
||||
|-----------|-------------|
|
||||
| **[SKILL.md](./SKILL.md)** | Skill definition per agenti AI - API reference completo |
|
||||
| **[prd.md](./prd.md)** | Product Requirements Document |
|
||||
| **[AGENTS.md](./AGENTS.md)** | Linee guida per sviluppo |
|
||||
**Q: Devo usare entrambi i sistemi?**
|
||||
A: No! Puoi usare solo NotebookLM Agent, solo DocuMente, o entrambi.
|
||||
|
||||
### 🧠 DocuMente (Agentic RAG)
|
||||
**Q: NotebookLM Agent richiede Qdrant?**
|
||||
A: No, funziona standalone senza database.
|
||||
|
||||
| Documento | Descrizione |
|
||||
|-----------|-------------|
|
||||
| **[prd-v2.md](./prd-v2.md)** | Product Requirements Document v2 |
|
||||
| **[frontend-plan.md](./frontend-plan.md)** | Piano sviluppo frontend |
|
||||
| **[TEST_COVERAGE_REPORT.md](./TEST_COVERAGE_REPORT.md)** | Report coverage test |
|
||||
**Q: Posso cercare solo nei notebook senza caricare documenti?**
|
||||
A: Sì, usa DocuMente e sincronizza solo i notebook.
|
||||
|
||||
### 📝 Generale
|
||||
|
||||
| Documento | Descrizione |
|
||||
|-----------|-------------|
|
||||
| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Come contribuire al progetto |
|
||||
| **[CHANGELOG.md](./CHANGELOG.md)** | Cronologia modifiche e release |
|
||||
| **[LICENSE](./LICENSE)** | Termini di licenza |
|
||||
**Q: Quali provider LLM supporta DocuMente?**
|
||||
A: OpenAI, Anthropic, Google, Mistral, Azure, Ollama (locale), LM Studio (locale).
|
||||
|
||||
---
|
||||
|
||||
## Licenza
|
||||
|
||||
Questo software e proprieta riservata di Luca Sacchi Ricciardi.
|
||||
Proprietà di Luca Sacchi Ricciardi. Tutti i diritti riservati.
|
||||
|
||||
Tutti i diritti sono riservati. Per ogni controversia derivante dall'uso o dallo sviluppo di questo software, il foro competente in via esclusiva e il Foro di Milano, Italia.
|
||||
|
||||
Vedi [LICENSE](./LICENSE) per i termini completi.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Vedi [CONTRIBUTING.md](./CONTRIBUTING.md) per le linee guida su come contribuire al progetto.
|
||||
|
||||
---
|
||||
|
||||
**Autore**: Luca Sacchi Ricciardi
|
||||
**Contatto**: luca@lucasacchi.net
|
||||
**Copyright**: (C) 2026 Tutti i diritti riservati
|
||||
**Contatto**: luca@lucasacchi.net
|
||||
|
||||
@@ -1,71 +1,55 @@
|
||||
# Documentation
|
||||
# Documentazione
|
||||
|
||||
Benvenuto nella documentazione di NotebookLM Agent API.
|
||||
## Struttura
|
||||
|
||||
## Indice
|
||||
```
|
||||
docs/
|
||||
├── README.md # Questo file - panoramica
|
||||
├── integration.md # Come usare NotebookLM con RAG
|
||||
└── api/ # Documentazione API dettagliata
|
||||
```
|
||||
|
||||
- [API Reference](./api/) - Documentazione completa delle API (TODO)
|
||||
- [Examples](./examples/) - Esempi di utilizzo (TODO)
|
||||
## Guide Rapide
|
||||
|
||||
## Panoramica
|
||||
### Solo NotebookLM Agent
|
||||
Non serve Qdrant. Vedi [README principale](../README.md) sezione "NotebookLM Agent".
|
||||
|
||||
NotebookLM Agent API fornisce:
|
||||
### NotebookLM + RAG
|
||||
Serve Qdrant. Vedi [integration.md](./integration.md).
|
||||
|
||||
1. **REST API** per gestire notebook, fonti, chat e generazione contenuti
|
||||
2. **Webhook System** per notifiche event-driven
|
||||
3. **AI Skill** per integrazione con agenti AI
|
||||
### API Reference
|
||||
Endpoint dettagliati in [api/endpoints.md](./api/endpoints.md).
|
||||
|
||||
---
|
||||
|
||||
## Endpoint Principali
|
||||
|
||||
### Notebook Management
|
||||
- `POST /api/v1/notebooks` - Creare notebook
|
||||
- `GET /api/v1/notebooks` - Listare notebook
|
||||
- `GET /api/v1/notebooks/{id}` - Ottenere notebook
|
||||
- `DELETE /api/v1/notebooks/{id}` - Eliminare notebook
|
||||
### NotebookLM Agent
|
||||
```
|
||||
POST /api/v1/notebooks # Crea notebook
|
||||
GET /api/v1/notebooks # Lista notebook
|
||||
POST /api/v1/notebooks/{id}/sources # Aggiungi fonte
|
||||
POST /api/v1/notebooks/{id}/chat # Chat
|
||||
POST /api/v1/webhooks # Registra webhook
|
||||
```
|
||||
|
||||
### Source Management
|
||||
- `POST /api/v1/notebooks/{id}/sources` - Aggiungere fonte
|
||||
- `GET /api/v1/notebooks/{id}/sources` - Listare fonti
|
||||
- `POST /api/v1/notebooks/{id}/sources/research` - Ricerca web
|
||||
### DocuMente RAG
|
||||
```
|
||||
POST /api/v1/documents # Upload documento
|
||||
POST /api/v1/query # Query RAG
|
||||
POST /api/v1/notebooklm/sync/{id} # Sincronizza notebook
|
||||
GET /api/v1/notebooklm/indexed # Lista sincronizzati
|
||||
```
|
||||
|
||||
### Content Generation
|
||||
- `POST /api/v1/notebooks/{id}/generate/audio` - Generare podcast
|
||||
- `POST /api/v1/notebooks/{id}/generate/video` - Generare video
|
||||
- `POST /api/v1/notebooks/{id}/generate/quiz` - Generare quiz
|
||||
- `POST /api/v1/notebooks/{id}/generate/flashcards` - Generare flashcard
|
||||
|
||||
### Webhooks
|
||||
- `POST /api/v1/webhooks` - Registrare webhook
|
||||
- `GET /api/v1/webhooks` - Listare webhook
|
||||
- `POST /api/v1/webhooks/{id}/test` - Testare webhook
|
||||
---
|
||||
|
||||
## Autenticazione
|
||||
|
||||
Tutte le richieste API richiedono header `X-API-Key`:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/api/v1/notebooks \
|
||||
-H "X-API-Key: your-api-key"
|
||||
Header richiesto:
|
||||
```
|
||||
X-API-Key: your-api-key
|
||||
```
|
||||
|
||||
## Webhook Security
|
||||
---
|
||||
|
||||
I webhook includono firma HMAC-SHA256 nell'header `X-Webhook-Signature`:
|
||||
|
||||
```python
|
||||
import hmac
|
||||
import hashlib
|
||||
|
||||
signature = hmac.new(
|
||||
secret.encode(),
|
||||
payload.encode(),
|
||||
hashlib.sha256
|
||||
).hexdigest()
|
||||
```
|
||||
|
||||
## Risorse
|
||||
|
||||
- [README](../README.md) - Panoramica progetto
|
||||
- [PRD](../prd.md) - Requisiti prodotto
|
||||
- [SKILL.md](../SKILL.md) - Skill per agenti AI
|
||||
- [CONTRIBUTING](../CONTRIBUTING.md) - Come contribuire
|
||||
Per informazioni complete vedi [SKILL.md](../SKILL.md)
|
||||
|
||||
@@ -1,436 +1,200 @@
|
||||
# Guida Integrazione NotebookLM + RAG
|
||||
# Guida Integrazione NotebookLM con 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.
|
||||
Questa guida spiega come usare **NotebookLM** con il sistema **RAG** di DocuMente.
|
||||
|
||||
---
|
||||
|
||||
## Indice
|
||||
## Casi d'Uso
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architettura](#architettura)
|
||||
- [Come Funziona](#come-funziona)
|
||||
- [API Reference](#api-reference)
|
||||
- [Esempi di Utilizzo](#esempi-di-utilizzo)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
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"
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
## Requisiti
|
||||
|
||||
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?"
|
||||
- NotebookLM Agent funzionante
|
||||
- DocuMente RAG con Qdrant avviato
|
||||
- Almeno un notebook su NotebookLM
|
||||
|
||||
---
|
||||
|
||||
## Architettura
|
||||
## Architettura Semplice
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 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 │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ NotebookLM │────▶│ DocuMente RAG │────▶│ LLM Provider │
|
||||
│ (Google) │ │ (Qdrant + API) │ │ (OpenAI/etc) │
|
||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||
│ │
|
||||
│ Sincronizza │ Query
|
||||
▼ ▼
|
||||
Contenuti dei Ricerca semantica
|
||||
notebook su documenti + notebook
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Come Funziona
|
||||
## Quick Start
|
||||
|
||||
### 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
|
||||
### 1. Avvia i Servizi
|
||||
|
||||
```bash
|
||||
# 1. Sincronizza un notebook
|
||||
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/abc-123
|
||||
# Terminale 1: Qdrant (richiesto per RAG)
|
||||
docker run -p 6333:6333 qdrant/qdrant
|
||||
|
||||
# 2. Query sul notebook sincronizzato
|
||||
# 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 le tecnologie AI menzionate?",
|
||||
"notebook_ids": ["abc-123"]
|
||||
"question": "Quali sono i punti chiave?",
|
||||
"notebook_ids": ["uuid-1"]
|
||||
}'
|
||||
```
|
||||
|
||||
### Esempio 2: Ricerca Multi-Notebook
|
||||
|
||||
```bash
|
||||
# Query su più notebook contemporaneamente
|
||||
# Cerca in documenti + notebook
|
||||
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"
|
||||
"question": "Confronta le fonti",
|
||||
"notebook_ids": ["uuid-1"],
|
||||
"include_documents": true
|
||||
}'
|
||||
```
|
||||
|
||||
### 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
|
||||
## API Endpoints
|
||||
|
||||
### 1. **Sincronizzazione Selettiva**
|
||||
Non sincronizzare tutti i notebook, solo quelli rilevanti per le ricerche.
|
||||
### 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 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
|
||||
# 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
|
||||
# }
|
||||
```
|
||||
|
||||
### 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
|
||||
### Query con Filtri
|
||||
|
||||
```bash
|
||||
# Cron job per refresh settimanale
|
||||
0 2 * * 0 /path/to/sync-notebooks.sh
|
||||
# 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"
|
||||
}'
|
||||
```
|
||||
|
||||
### 5. **Monitoraggio**
|
||||
Traccia quali notebook sono sincronizzati:
|
||||
---
|
||||
|
||||
## 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
|
||||
# Lista e verifica stato
|
||||
curl http://localhost:8000/api/v1/notebooklm/indexed | jq '.'
|
||||
# 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: Sincronizzazione fallita
|
||||
**Problema: "Notebook not found"**
|
||||
→ Verifica che il notebook esista su NotebookLM
|
||||
|
||||
**Sintomi**: Errore 500 durante la sincronizzazione
|
||||
**Problema: Qdrant non risponde**
|
||||
→ Controlla che Qdrant sia avviato: `docker ps`
|
||||
|
||||
**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
|
||||
```
|
||||
**Problema: Nessun risultato**
|
||||
→ Verifica che il notebook sia sincronizzato: `GET /api/v1/notebooklm/indexed`
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
## Limitazioni
|
||||
|
||||
### 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)
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
Per domande avanzate vedi [SKILL.md](../SKILL.md)
|
||||
|
||||
Reference in New Issue
Block a user