From 67ba5bc2dde6e659780bf3fe16d6821cfba155fc Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Mon, 6 Apr 2026 17:08:40 +0200 Subject: [PATCH] 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 --- README.md | 478 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 333 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index d5289ba..cbac9e2 100644 --- a/README.md +++ b/README.md @@ -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/) [![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) [![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+ -- [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 +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