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
2026-04-06 18:48:16 +02:00
parent e239829938
commit 2aa96e9efa
3 changed files with 287 additions and 849 deletions
--- a/README.md
+++ b/README.md
@@ -5,508 +5,198 @@
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![Tests](https://img.shields.io/badge/tests-pytest-blue.svg)](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