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
528
README.md
528
README.md
@@ -5,508 +5,198 @@
|
|||||||
[](https://github.com/astral-sh/ruff)
|
[](https://github.com/astral-sh/ruff)
|
||||||
[](https://docs.pytest.org/)
|
[](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**:
|
Questo repository contiene **due sistemi AI indipendenti** che puoi usare separatamente o insieme:
|
||||||
|
|
||||||
1. **NotebookLM Agent** - API REST per l'automazione programmatica di Google NotebookLM
|
|
||||||
2. **DocuMente (Agentic RAG)** - Sistema RAG avanzato con supporto multi-provider LLM
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Indice
|
## 🤖 NotebookLM Agent
|
||||||
|
|
||||||
- [Panoramica](#panoramica)
|
API REST per gestire **Google NotebookLM** programmaticamente.
|
||||||
- [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)
|
|
||||||
|
|
||||||
---
|
### 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
|
### Installazione
|
||||||
|
|
||||||
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:**
|
|
||||||
```bash
|
```bash
|
||||||
# Ricerca in notebook specifici
|
# Clona e installa
|
||||||
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
|
|
||||||
git clone <repository-url>
|
git clone <repository-url>
|
||||||
cd documente
|
cd documente
|
||||||
|
|
||||||
# Crea ambiente virtuale
|
|
||||||
uv venv --python 3.10
|
uv venv --python 3.10
|
||||||
source .venv/bin/activate
|
source .venv/bin/activate
|
||||||
|
uv sync
|
||||||
|
|
||||||
# Installa tutte le dipendenze
|
# Autenticazione NotebookLM (prima volta)
|
||||||
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)
|
|
||||||
notebooklm login
|
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
|
```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 \
|
curl -X POST http://localhost:8000/api/v1/notebooks \
|
||||||
-H "Content-Type: application/json" \
|
-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 \
|
curl -X POST http://localhost:8000/api/v1/notebooks/{id}/sources \
|
||||||
-H "Content-Type: application/json" \
|
|
||||||
-d '{"type": "url", "url": "https://example.com"}'
|
-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
|
```bash
|
||||||
docker-compose up
|
# Dipendenze già installate con uv sync sopra
|
||||||
|
|
||||||
|
# Avvia Qdrant (richiesto)
|
||||||
|
docker run -p 6333:6333 qdrant/qdrant
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Manuale
|
### Avvio
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. Avvia Qdrant (in un terminale separato)
|
# Backend
|
||||||
docker run -p 6333:6333 qdrant/qdrant
|
|
||||||
|
|
||||||
# 2. Avvia backend
|
|
||||||
uv run fastapi dev src/agentic_rag/api/main.py
|
uv run fastapi dev src/agentic_rag/api/main.py
|
||||||
|
|
||||||
# 3. Avvia frontend (in un altro terminale)
|
# Frontend (opzionale)
|
||||||
cd frontend
|
cd frontend && npm install && npm run dev
|
||||||
npm run dev
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Servizi disponibili:**
|
Servizi:
|
||||||
- **Web UI**: http://localhost:3000
|
- API: http://localhost:8000/api
|
||||||
- **API docs**: http://localhost:8000/api/docs
|
- Web UI: http://localhost:3000
|
||||||
|
|
||||||
**Esempio di utilizzo API:**
|
|
||||||
|
|
||||||
|
### Esempi
|
||||||
```bash
|
```bash
|
||||||
# Upload documento
|
# Carica documento
|
||||||
curl -X POST http://localhost:8000/api/v1/documents \
|
curl -X POST http://localhost:8000/api/v1/documents \
|
||||||
-F "file=@documento.pdf"
|
-F "file=@documento.pdf"
|
||||||
|
|
||||||
# Query RAG
|
# Sincronizza notebook da NotebookLM
|
||||||
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
|
|
||||||
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/{notebook_id}
|
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/{notebook_id}
|
||||||
|
|
||||||
# Lista notebook sincronizzati
|
# Fai una domanda (cerca in documenti + notebook)
|
||||||
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 \
|
curl -X POST http://localhost:8000/api/v1/query \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{
|
-d '{
|
||||||
"question": "Confronta le informazioni tra i documenti e i notebook",
|
"question": "Trova informazioni su...",
|
||||||
"notebook_ids": ["uuid-1", "uuid-2"],
|
"notebook_ids": ["uuid-notebook"],
|
||||||
"include_documents": true,
|
"include_documents": true
|
||||||
"provider": "anthropic"
|
|
||||||
}'
|
}'
|
||||||
```
|
```
|
||||||
|
|
||||||
|
📚 **Documentazione Integrazione**: [docs/integration.md](./docs/integration.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Testing
|
## 🔧 Configurazione
|
||||||
|
|
||||||
```bash
|
Crea un file `.env` nella root:
|
||||||
# Esegui tutti i test
|
|
||||||
uv run pytest
|
|
||||||
|
|
||||||
# Con coverage
|
```env
|
||||||
uv run pytest --cov=src --cov-report=term-missing
|
# Per NotebookLM Agent
|
||||||
|
NOTEBOOKLM_HOME=~/.notebooklm
|
||||||
|
|
||||||
# Solo unit test
|
# Per DocuMente (almeno un provider LLM)
|
||||||
uv run pytest tests/unit/ -m unit
|
OPENAI_API_KEY=sk-... # o altro provider
|
||||||
|
|
||||||
# Test NotebookLM Agent
|
# Per ricerche su notebook (opzionale)
|
||||||
uv run pytest tests/unit/test_notebooklm_agent/ -v
|
OLLAMA_BASE_URL=http://localhost:11434 # se usi Ollama
|
||||||
|
LMSTUDIO_BASE_URL=http://localhost:1234 # se usi LM Studio
|
||||||
|
|
||||||
# Test DocuMente
|
# Qdrant (solo per DocuMente)
|
||||||
uv run pytest tests/unit/test_agentic_rag/ -v
|
QDRANT_HOST=localhost
|
||||||
|
QDRANT_PORT=6333
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Struttura Progetto
|
## 📁 Struttura Progetto
|
||||||
|
|
||||||
```
|
```
|
||||||
documente/
|
documente/
|
||||||
├── src/
|
├── src/
|
||||||
│ ├── notebooklm_agent/ # API NotebookLM Agent
|
│ ├── notebooklm_agent/ # 🤖 Solo NotebookLM
|
||||||
│ │ ├── api/
|
│ │ ├── api/
|
||||||
│ │ ├── services/
|
│ │ └── services/
|
||||||
│ │ ├── core/
|
│ │
|
||||||
│ │ └── webhooks/
|
│ └── agentic_rag/ # 🧠 RAG + NotebookLM
|
||||||
│ └── agentic_rag/ # DocuMente RAG System
|
|
||||||
│ ├── api/
|
│ ├── api/
|
||||||
│ ├── services/
|
│ ├── services/
|
||||||
│ └── core/
|
│ └── ...
|
||||||
├── tests/
|
│
|
||||||
│ ├── unit/
|
├── frontend/ # 🎨 Web UI (solo per RAG)
|
||||||
│ │ ├── test_notebooklm_agent/
|
├── docs/
|
||||||
│ │ └── test_agentic_rag/
|
│ └── integration.md # Guida integrazione
|
||||||
│ ├── integration/
|
│
|
||||||
│ └── e2e/
|
└── tests/
|
||||||
├── frontend/ # React + TypeScript UI
|
|
||||||
│ ├── src/
|
|
||||||
│ └── package.json
|
|
||||||
├── docs/ # Documentazione
|
|
||||||
├── prompts/ # Prompt engineering
|
|
||||||
├── pyproject.toml # Configurazione progetto
|
|
||||||
├── docker-compose.yml
|
|
||||||
└── README.md
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 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 |
|
**Q: Devo usare entrambi i sistemi?**
|
||||||
|-----------|-------------|
|
A: No! Puoi usare solo NotebookLM Agent, solo DocuMente, o entrambi.
|
||||||
| **[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 |
|
|
||||||
|
|
||||||
### 🧠 DocuMente (Agentic RAG)
|
**Q: NotebookLM Agent richiede Qdrant?**
|
||||||
|
A: No, funziona standalone senza database.
|
||||||
|
|
||||||
| Documento | Descrizione |
|
**Q: Posso cercare solo nei notebook senza caricare documenti?**
|
||||||
|-----------|-------------|
|
A: Sì, usa DocuMente e sincronizza solo i notebook.
|
||||||
| **[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 |
|
|
||||||
|
|
||||||
### 📝 Generale
|
**Q: Quali provider LLM supporta DocuMente?**
|
||||||
|
A: OpenAI, Anthropic, Google, Mistral, Azure, Ollama (locale), LM Studio (locale).
|
||||||
| Documento | Descrizione |
|
|
||||||
|-----------|-------------|
|
|
||||||
| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Come contribuire al progetto |
|
|
||||||
| **[CHANGELOG.md](./CHANGELOG.md)** | Cronologia modifiche e release |
|
|
||||||
| **[LICENSE](./LICENSE)** | Termini di licenza |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Licenza
|
## 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
|
**Contatto**: luca@lucasacchi.net
|
||||||
**Copyright**: (C) 2026 Tutti i diritti riservati
|
|
||||||
|
|||||||
@@ -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)
|
## Guide Rapide
|
||||||
- [Examples](./examples/) - Esempi di utilizzo (TODO)
|
|
||||||
|
|
||||||
## 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
|
### API Reference
|
||||||
2. **Webhook System** per notifiche event-driven
|
Endpoint dettagliati in [api/endpoints.md](./api/endpoints.md).
|
||||||
3. **AI Skill** per integrazione con agenti AI
|
|
||||||
|
---
|
||||||
|
|
||||||
## Endpoint Principali
|
## Endpoint Principali
|
||||||
|
|
||||||
### Notebook Management
|
### NotebookLM Agent
|
||||||
- `POST /api/v1/notebooks` - Creare notebook
|
```
|
||||||
- `GET /api/v1/notebooks` - Listare notebook
|
POST /api/v1/notebooks # Crea notebook
|
||||||
- `GET /api/v1/notebooks/{id}` - Ottenere notebook
|
GET /api/v1/notebooks # Lista notebook
|
||||||
- `DELETE /api/v1/notebooks/{id}` - Eliminare notebook
|
POST /api/v1/notebooks/{id}/sources # Aggiungi fonte
|
||||||
|
POST /api/v1/notebooks/{id}/chat # Chat
|
||||||
|
POST /api/v1/webhooks # Registra webhook
|
||||||
|
```
|
||||||
|
|
||||||
### Source Management
|
### DocuMente RAG
|
||||||
- `POST /api/v1/notebooks/{id}/sources` - Aggiungere fonte
|
```
|
||||||
- `GET /api/v1/notebooks/{id}/sources` - Listare fonti
|
POST /api/v1/documents # Upload documento
|
||||||
- `POST /api/v1/notebooks/{id}/sources/research` - Ricerca web
|
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
|
## Autenticazione
|
||||||
|
|
||||||
Tutte le richieste API richiedono header `X-API-Key`:
|
Header richiesto:
|
||||||
|
```
|
||||||
```bash
|
X-API-Key: your-api-key
|
||||||
curl http://localhost:8000/api/v1/notebooks \
|
|
||||||
-H "X-API-Key: your-api-key"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Webhook Security
|
---
|
||||||
|
|
||||||
I webhook includono firma HMAC-SHA256 nell'header `X-Webhook-Signature`:
|
Per informazioni complete vedi [SKILL.md](../SKILL.md)
|
||||||
|
|
||||||
```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
|
|
||||||
|
|||||||
@@ -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)
|
1. **Ricerca nei notebook**: "Cosa dicono i miei notebook sull'AI?"
|
||||||
- [Architettura](#architettura)
|
2. **Ricerca combinata**: "Cosa ho su Python nei documenti PDF e nei notebook?"
|
||||||
- [Come Funziona](#come-funziona)
|
3. **Analisi multi-notebook**: "Confronta le conclusioni tra notebook A e B"
|
||||||
- [API Reference](#api-reference)
|
|
||||||
- [Esempi di Utilizzo](#esempi-di-utilizzo)
|
|
||||||
- [Best Practices](#best-practices)
|
|
||||||
- [Troubleshooting](#troubleshooting)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Overview
|
## Requisiti
|
||||||
|
|
||||||
L'integrazione colma il divario tra **gestione notebook** (NotebookLM Agent) e **ricerca semantica** (DocuMente RAG), permettendo di:
|
- NotebookLM Agent funzionante
|
||||||
|
- DocuMente RAG con Qdrant avviato
|
||||||
- 🔍 **Ricercare** nei contenuti dei notebook con semantic search
|
- Almeno un notebook su NotebookLM
|
||||||
- 🧠 **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
|
## Architettura Semplice
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||||
│ NotebookLM Agent │
|
│ NotebookLM │────▶│ DocuMente RAG │────▶│ LLM Provider │
|
||||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
│ (Google) │ │ (Qdrant + API) │ │ (OpenAI/etc) │
|
||||||
│ │ Notebooks │───▶│ Sources │───▶│ Full Text Get │ │
|
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
||||||
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
│ │
|
||||||
└─────────────────────────────────────────────────────────────────┘
|
│ Sincronizza │ Query
|
||||||
│
|
▼ ▼
|
||||||
│ Extract Content
|
Contenuti dei Ricerca semantica
|
||||||
▼
|
notebook su documenti + notebook
|
||||||
┌─────────────────────────────────────────────────────────────────┐
|
|
||||||
│ 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
|
## Quick Start
|
||||||
|
|
||||||
### 1. Sincronizzazione
|
### 1. Avvia i Servizi
|
||||||
|
|
||||||
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
|
```bash
|
||||||
# 1. Sincronizza un notebook
|
# Terminale 1: Qdrant (richiesto per RAG)
|
||||||
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/abc-123
|
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 \
|
curl -X POST http://localhost:8000/api/v1/query/notebooks \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{
|
-d '{
|
||||||
"question": "Quali sono le tecnologie AI menzionate?",
|
"question": "Quali sono i punti chiave?",
|
||||||
"notebook_ids": ["abc-123"]
|
"notebook_ids": ["uuid-1"]
|
||||||
}'
|
}'
|
||||||
```
|
|
||||||
|
|
||||||
### Esempio 2: Ricerca Multi-Notebook
|
# Cerca in documenti + notebook
|
||||||
|
|
||||||
```bash
|
|
||||||
# Query su più notebook contemporaneamente
|
|
||||||
curl -X POST http://localhost:8000/api/v1/query \
|
curl -X POST http://localhost:8000/api/v1/query \
|
||||||
-H "Content-Type: application/json" \
|
-H "Content-Type: application/json" \
|
||||||
-d '{
|
-d '{
|
||||||
"question": "Confronta gli approcci di machine learning descritti",
|
"question": "Confronta le fonti",
|
||||||
"notebook_ids": ["notebook-1", "notebook-2", "notebook-3"],
|
"notebook_ids": ["uuid-1"],
|
||||||
"k": 15,
|
"include_documents": true
|
||||||
"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
|
## API Endpoints
|
||||||
|
|
||||||
### 1. **Sincronizzazione Selettiva**
|
### Gestione Notebook
|
||||||
Non sincronizzare tutti i notebook, solo quelli rilevanti per le ricerche.
|
|
||||||
|
| 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
|
```bash
|
||||||
# Sincronizza solo i notebook attivi
|
# Sincronizza
|
||||||
for notebook_id in "notebook-1" "notebook-2"; do
|
curl -X POST http://localhost:8000/api/v1/notebooklm/sync/abc-123
|
||||||
curl -X POST "http://localhost:8000/api/v1/notebooklm/sync/$notebook_id"
|
|
||||||
done
|
# Response:
|
||||||
|
# {
|
||||||
|
# "sync_id": "...",
|
||||||
|
# "notebook_id": "abc-123",
|
||||||
|
# "status": "success",
|
||||||
|
# "sources_indexed": 5,
|
||||||
|
# "total_chunks": 42
|
||||||
|
# }
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. **Gestione Chunks**
|
### Query con Filtri
|
||||||
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
|
```bash
|
||||||
# Cron job per refresh settimanale
|
# Multi-notebook
|
||||||
0 2 * * 0 /path/to/sync-notebooks.sh
|
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
|
```bash
|
||||||
# Lista e verifica stato
|
# Esempio con Ollama (locale)
|
||||||
curl http://localhost:8000/api/v1/notebooklm/indexed | jq '.'
|
curl -X POST http://localhost:8000/api/v1/query/notebooks \
|
||||||
|
-d '{
|
||||||
|
"question": "Spiega...",
|
||||||
|
"notebook_ids": ["id-1"],
|
||||||
|
"provider": "ollama",
|
||||||
|
"model": "llama3.2"
|
||||||
|
}'
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Troubleshooting
|
## 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
|
**Problema: Nessun risultato**
|
||||||
|
→ Verifica che il notebook sia sincronizzato: `GET /api/v1/notebooklm/indexed`
|
||||||
**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
|
## Limitazioni
|
||||||
|
|
||||||
### Dimensione dei Chunks
|
- I contenuti devono essere "scaricabili" da NotebookLM (alcuni PDF potrebbero non avere testo)
|
||||||
- **Default**: 1024 caratteri
|
- La sincronizzazione è manuale (non automatica quando il notebook cambia)
|
||||||
- **Trade-off**:
|
- Ogni fonte diventa chunk di ~1024 caratteri
|
||||||
- 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
|
Per domande avanzate vedi [SKILL.md](../SKILL.md)
|
||||||
|
|
||||||
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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user