docs: reorganize README to reflect dual-system architecture
Restructure README to clearly present both systems: - NotebookLM Agent: API for Google NotebookLM automation - DocuMente: Multi-provider RAG system with web UI Changes: - Add detailed architecture diagrams for both systems - Separate configuration and usage instructions - Update project structure to show both src/notebooklm_agent and src/agentic_rag - Add API examples for both systems - Reorganize documentation section by system
This commit is contained in:
Luca Sacchi Ricciardi
478
README.md
478
README.md
@@ -1,166 +1,117 @@
|
||||
# DocuMente
|
||||
# DocuMente & NotebookLM Agent
|
||||
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://fastapi.tiangolo.com/)
|
||||
[](https://github.com/astral-sh/ruff)
|
||||
[](https://docs.pytest.org/)
|
||||
|
||||
> **Sistema di Retrieval Agentico con AI - Interroga i tuoi documenti in modo intelligente**
|
||||
> **Piattaforma AI Completa - RAG Multi-Provider + Automazione NotebookLM**
|
||||
|
||||
DocuMente è un sistema RAG (Retrieval-Augmented Generation) avanzato che permette di caricare documenti e interagirci tramite chat conversazionale. Supporta multipli provider LLM (OpenAI, Z.AI, OpenCode Zen, OpenRouter, Anthropic, Google, Mistral, Azure) e offre una moderna interfaccia web React.
|
||||
Questo repository contiene **due sistemi AI complementari**:
|
||||
|
||||
## Caratteristiche
|
||||
1. **NotebookLM Agent** - API REST per l'automazione programmatica di Google NotebookLM
|
||||
2. **DocuMente (Agentic RAG)** - Sistema RAG avanzato con supporto multi-provider LLM
|
||||
|
||||
- **🧠 Multi-Provider LLM**: Supporta 8 provider diversi, scegli il tuo preferito
|
||||
- **📄 Gestione Documenti**: Upload tramite drag & drop, supporta PDF, DOCX, TXT, MD
|
||||
- **💬 Chat Intelligente**: Interroga i tuoi documenti con risposte contestuali
|
||||
- **🔗 API REST Completa**: Integra DocuMente nelle tue applicazioni
|
||||
- **🎨 Interfaccia Web Moderna**: React 18 + TypeScript + Tailwind CSS
|
||||
- **🔒 Autenticazione Sicura**: API Key + JWT support
|
||||
- **🐳 Containerizzato**: Docker e docker-compose pronti all'uso
|
||||
---
|
||||
|
||||
## Requisiti
|
||||
## Indice
|
||||
|
||||
- Python 3.10+
|
||||
- [uv](https://github.com/astral-sh/uv) per dependency management
|
||||
- Node.js 18+ (per il frontend)
|
||||
- Docker (opzionale)
|
||||
- [Panoramica](#panoramica)
|
||||
- [Componenti](#componenti)
|
||||
- [Requisiti](#requisiti)
|
||||
- [Installazione](#installazione)
|
||||
- [Configurazione](#configurazione)
|
||||
- [Avvio](#avvio)
|
||||
- [Testing](#testing)
|
||||
- [Struttura Progetto](#struttura-progetto)
|
||||
- [Documentazione](#documentazione)
|
||||
- [Licenza](#licenza)
|
||||
|
||||
## Installazione
|
||||
---
|
||||
|
||||
```bash
|
||||
# Clona il repository
|
||||
git clone https://github.com/example/documente.git
|
||||
cd documente
|
||||
## Panoramica
|
||||
|
||||
# Backend
|
||||
cd backend
|
||||
uv venv --python 3.10
|
||||
source .venv/bin/activate
|
||||
uv sync --extra dev --extra browser
|
||||
### NotebookLM Agent
|
||||
|
||||
# Frontend
|
||||
cd ../frontend
|
||||
npm install
|
||||
```
|
||||
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
|
||||
|
||||
## Configurazione
|
||||
**Ideale per:** Automation engineer, Content creator, AI Agent developers
|
||||
|
||||
Crea un file `.env` nella cartella backend:
|
||||
### DocuMente (Agentic RAG)
|
||||
|
||||
```env
|
||||
# API 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
|
||||
Sistema **Retrieval-Augmented Generation** standalone con:
|
||||
- Supporto per 8 provider LLM diversi
|
||||
- Upload e indicizzazione documenti (PDF, DOCX, TXT, MD)
|
||||
- Chat conversazionale con i tuoi documenti
|
||||
- Interfaccia web moderna (React + TypeScript)
|
||||
|
||||
# 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=...
|
||||
**Ideale per:** Knowledge management, Document analysis, Research assistant
|
||||
|
||||
# Vector Store
|
||||
QDRANT_HOST=localhost
|
||||
QDRANT_PORT=6333
|
||||
---
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=INFO
|
||||
LOG_FORMAT=json
|
||||
```
|
||||
## Componenti
|
||||
|
||||
## Avvio
|
||||
|
||||
### Con Docker (Consigliato)
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
### Manuale
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend
|
||||
uv run fastapi dev src/agentic_rag/api/main.py
|
||||
|
||||
# Frontend (in un altro terminale)
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
L'applicazione sarà disponibile:
|
||||
- **Web UI**: http://localhost:3000
|
||||
- **API docs**: http://localhost:8000/api/docs
|
||||
- **OpenAPI schema**: http://localhost:8000/openapi.json
|
||||
|
||||
## Uso Rapido
|
||||
|
||||
### Via Web UI
|
||||
|
||||
1. Accedi a http://localhost:3000
|
||||
2. Inserisci la tua API Key
|
||||
3. Carica documenti nella sezione "Documents"
|
||||
4. Inizia a chattare nella sezione "Chat"
|
||||
|
||||
### Via API
|
||||
|
||||
```bash
|
||||
# Upload documento
|
||||
curl -X POST http://localhost:8000/api/v1/documents \
|
||||
-H "X-API-Key: your-key" \
|
||||
-F "file=@documento.pdf"
|
||||
|
||||
# Query RAG
|
||||
curl -X POST http://localhost:8000/api/v1/query \
|
||||
-H "X-API-Key: your-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"question": "Qual è il contenuto principale?",
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-mini"
|
||||
}'
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Esegui tutti i test
|
||||
uv run pytest
|
||||
|
||||
# Con coverage
|
||||
uv run pytest --cov=src/agentic_rag --cov-report=term-missing
|
||||
|
||||
# Solo unit test
|
||||
uv run pytest tests/unit/ -m unit
|
||||
```
|
||||
|
||||
## Struttura Progetto
|
||||
### NotebookLM Agent
|
||||
|
||||
```
|
||||
documente/
|
||||
├── backend/
|
||||
│ ├── src/agentic_rag/ # Codice sorgente backend
|
||||
│ │ ├── api/ # FastAPI routes
|
||||
│ │ ├── core/ # Config, auth, LLM factory
|
||||
│ │ └── services/ # RAG, documents, vector store
|
||||
│ ├── tests/ # Test suite
|
||||
│ └── requirements.txt
|
||||
├── frontend/
|
||||
│ ├── src/ # React + TypeScript
|
||||
│ ├── public/
|
||||
│ └── package.json
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
└── README.md
|
||||
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
|
||||
```
|
||||
|
||||
## Provider LLM Supportati
|
||||
**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
|
||||
├── services/ # Business logic
|
||||
│ ├── rag_service.py # Core RAG logic
|
||||
│ ├── vector_store.py # Qdrant integration
|
||||
│ └── document_service.py
|
||||
└── core/ # Configurazioni
|
||||
├── config.py # Multi-provider config
|
||||
└── llm_factory.py # LLM factory pattern
|
||||
```
|
||||
|
||||
**Provider LLM Supportati:**
|
||||
|
||||
| Provider | Modelli Principali | Stato |
|
||||
|----------|-------------------|-------|
|
||||
@@ -173,22 +124,259 @@ documente/
|
||||
| **Mistral** | Mistral Large/Medium | ✅ |
|
||||
| **Azure** | GPT-4, GPT-4o | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 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>
|
||||
cd documente
|
||||
|
||||
# Crea ambiente virtuale
|
||||
uv venv --python 3.10
|
||||
source .venv/bin/activate
|
||||
|
||||
# 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
|
||||
|
||||
# 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
|
||||
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# Creare un notebook
|
||||
curl -X POST http://localhost:8000/api/v1/notebooks \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "Ricerca AI", "description": "Studio AI"}'
|
||||
|
||||
# Aggiungere una fonte URL
|
||||
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"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### DocuMente (Agentic RAG)
|
||||
|
||||
#### Con Docker (Consigliato)
|
||||
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
#### Manuale
|
||||
|
||||
```bash
|
||||
# 1. Avvia Qdrant (in un terminale separato)
|
||||
docker run -p 6333:6333 qdrant/qdrant
|
||||
|
||||
# 2. Avvia backend
|
||||
uv run fastapi dev src/agentic_rag/api/main.py
|
||||
|
||||
# 3. Avvia frontend (in un altro terminale)
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**Servizi disponibili:**
|
||||
- **Web UI**: http://localhost:3000
|
||||
- **API docs**: http://localhost:8000/api/docs
|
||||
|
||||
**Esempio di utilizzo API:**
|
||||
|
||||
```bash
|
||||
# Upload 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"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Esegui tutti i test
|
||||
uv run pytest
|
||||
|
||||
# Con coverage
|
||||
uv run pytest --cov=src --cov-report=term-missing
|
||||
|
||||
# Solo unit test
|
||||
uv run pytest tests/unit/ -m unit
|
||||
|
||||
# Test NotebookLM Agent
|
||||
uv run pytest tests/unit/test_notebooklm_agent/ -v
|
||||
|
||||
# Test DocuMente
|
||||
uv run pytest tests/unit/test_agentic_rag/ -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Struttura Progetto
|
||||
|
||||
```
|
||||
documente/
|
||||
├── src/
|
||||
│ ├── notebooklm_agent/ # API NotebookLM Agent
|
||||
│ │ ├── api/
|
||||
│ │ ├── services/
|
||||
│ │ ├── core/
|
||||
│ │ └── webhooks/
|
||||
│ └── agentic_rag/ # DocuMente RAG System
|
||||
│ ├── 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentazione
|
||||
|
||||
- [PRD v2](./prd-v2.md) - Product Requirements Document (DocuMente)
|
||||
- [Frontend Plan](./frontend-plan.md) - Piano sviluppo frontend
|
||||
- [Test Coverage](./TEST_COVERAGE_REPORT.md) - Report coverage test
|
||||
- [AGENTS.md](./AGENTS.md) - Linee guida per OpenCode
|
||||
### NotebookLM Agent
|
||||
- [SKILL.md](./SKILL.md) - Skill definition per agenti AI
|
||||
- [prd.md](./prd.md) - Product Requirements Document
|
||||
- [AGENTS.md](./AGENTS.md) - Linee guida per sviluppo
|
||||
|
||||
### DocuMente
|
||||
- [prd-v2.md](./prd-v2.md) - Product Requirements Document
|
||||
- [frontend-plan.md](./frontend-plan.md) - Piano sviluppo frontend
|
||||
- [TEST_COVERAGE_REPORT.md](./TEST_COVERAGE_REPORT.md) - Report coverage
|
||||
|
||||
### Generale
|
||||
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Come contribuire
|
||||
- [CHANGELOG.md](./CHANGELOG.md) - Cronologia modifiche
|
||||
|
||||
## ⚖️ Licenza e Note Legali
|
||||
---
|
||||
|
||||
Questo software è proprietà riservata di Luca Sacchi Ricciardi.
|
||||
## Licenza
|
||||
|
||||
Tutti i diritti sono riservati. Per ogni controversia derivante dall'uso o dallo sviluppo di questo software, il foro competente in via esclusiva è il Foro di Milano, Italia.
|
||||
Questo software e proprieta riservata di Luca Sacchi Ricciardi.
|
||||
|
||||
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.
|
||||
@@ -197,4 +385,4 @@ Vedi [CONTRIBUTING.md](./CONTRIBUTING.md) per le linee guida su come contribuire
|
||||
|
||||
**Autore**: Luca Sacchi Ricciardi
|
||||
**Contatto**: luca@lucasacchi.net
|
||||
**Copyright**: © 2026 Tutti i diritti riservati
|
||||
**Copyright**: (C) 2026 Tutti i diritti riservati
|
||||
|
||||
Reference in New Issue
Block a user