docs: reorganize README to reflect dual-system architecture
Some checks failed
CI / test (3.10) (push) Has been cancelled
CI / test (3.11) (push) Has been cancelled
CI / test (3.12) (push) Has been cancelled
CI / lint (push) Has been cancelled

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
2026-04-06 17:08:40 +02:00
parent cfb6d9052a
commit 67ba5bc2dd

478
README.md
View File

@@ -1,166 +1,117 @@
# DocuMente # DocuMente & NotebookLM Agent
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff) [![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/) [![Tests](https://img.shields.io/badge/tests-pytest-blue.svg)](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+ - [Panoramica](#panoramica)
- [uv](https://github.com/astral-sh/uv) per dependency management - [Componenti](#componenti)
- Node.js 18+ (per il frontend) - [Requisiti](#requisiti)
- Docker (opzionale) - [Installazione](#installazione)
- [Configurazione](#configurazione)
- [Avvio](#avvio)
- [Testing](#testing)
- [Struttura Progetto](#struttura-progetto)
- [Documentazione](#documentazione)
- [Licenza](#licenza)
## Installazione ---
```bash ## Panoramica
# Clona il repository
git clone https://github.com/example/documente.git
cd documente
# Backend ### NotebookLM Agent
cd backend
uv venv --python 3.10
source .venv/bin/activate
uv sync --extra dev --extra browser
# Frontend Interfaccia API e webhook per **Google NotebookLM** che permette:
cd ../frontend - Gestione programmatica di notebook, fonti e chat
npm install - 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 Sistema **Retrieval-Augmented Generation** standalone con:
# API Configuration - Supporto per 8 provider LLM diversi
NOTEBOOKLM_AGENT_API_KEY=your-api-key - Upload e indicizzazione documenti (PDF, DOCX, TXT, MD)
NOTEBOOKLM_AGENT_WEBHOOK_SECRET=your-webhook-secret - Chat conversazionale con i tuoi documenti
NOTEBOOKLM_AGENT_PORT=8000 - Interfaccia web moderna (React + TypeScript)
NOTEBOOKLM_AGENT_HOST=0.0.0.0
# LLM Provider API Keys (configura almeno uno) **Ideale per:** Knowledge management, Document analysis, Research assistant
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=...
# Vector Store ---
QDRANT_HOST=localhost
QDRANT_PORT=6333
# Logging ## Componenti
LOG_LEVEL=INFO
LOG_FORMAT=json
```
## Avvio ### NotebookLM Agent
### 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
``` ```
documente/ src/notebooklm_agent/
├── backend/ ├── api/ # FastAPI REST API
│ ├── src/agentic_rag/ # Codice sorgente backend │ ├── main.py # Application entry
│ ├── api/ # FastAPI routes │ ├── routes/ # API endpoints
│ │ ├── core/ # Config, auth, LLM factory │ │ ├── notebooks.py # CRUD notebook
│ │ ── services/ # RAG, documents, vector store │ │ ── sources.py # Gestione fonti
│ ├── tests/ # Test suite │ ├── chat.py # Chat interattiva
└── requirements.txt │ ├── generation.py # Generazione contenuti
├── frontend/ │ │ └── webhooks.py # Webhook management
── src/ # React + TypeScript ── models/ # Pydantic models
│ ├── public/ ├── services/ # Business logic
│ └── package.json └── webhooks/ # Webhook system
├── docker-compose.yml
├── Dockerfile
└── README.md
``` ```
## 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 | | Provider | Modelli Principali | Stato |
|----------|-------------------|-------| |----------|-------------------|-------|
@@ -173,22 +124,259 @@ documente/
| **Mistral** | Mistral Large/Medium | ✅ | | **Mistral** | Mistral Large/Medium | ✅ |
| **Azure** | GPT-4, GPT-4o | ✅ | | **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 ## Documentazione
- [PRD v2](./prd-v2.md) - Product Requirements Document (DocuMente) ### NotebookLM Agent
- [Frontend Plan](./frontend-plan.md) - Piano sviluppo frontend - [SKILL.md](./SKILL.md) - Skill definition per agenti AI
- [Test Coverage](./TEST_COVERAGE_REPORT.md) - Report coverage test - [prd.md](./prd.md) - Product Requirements Document
- [AGENTS.md](./AGENTS.md) - Linee guida per OpenCode - [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 - [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. Vedi [LICENSE](./LICENSE) per i termini completi.
---
## Contributing ## Contributing
Vedi [CONTRIBUTING.md](./CONTRIBUTING.md) per le linee guida su come contribuire al progetto. 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 **Autore**: Luca Sacchi Ricciardi
**Contatto**: luca@lucasacchi.net **Contatto**: luca@lucasacchi.net
**Copyright**: © 2026 Tutti i diritti riservati **Copyright**: (C) 2026 Tutti i diritti riservati