documente/README.md

DocuMente

Sistema di Retrieval Agentico con AI - Interroga i tuoi documenti in modo intelligente

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.

Caratteristiche

• 🧠 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

• Python 3.10+
• uv per dependency management
• Node.js 18+ (per il frontend)
• Docker (opzionale)

Installazione

# Clona il repository
git clone https://github.com/example/documente.git
cd documente

# Backend
cd backend
uv venv --python 3.10
source .venv/bin/activate
uv sync --extra dev --extra browser

# Frontend
cd ../frontend
npm install

Configurazione

Crea un file .env nella cartella backend:

# 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

# 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=...

# Vector Store
QDRANT_HOST=localhost
QDRANT_PORT=6333

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

Avvio

Con Docker (Consigliato)

docker-compose up

Manuale

# 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

# 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

# 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/
├── 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

Provider LLM Supportati

Provider	Modelli Principali	Stato
OpenAI	GPT-4o, GPT-4, GPT-3.5	✅
Z.AI	zai-large, zai-medium	✅
OpenCode Zen	zen-1, zen-lite	✅
OpenRouter	Multi-model access	✅
Anthropic	Claude 3.5, Claude 3	✅
Google	Gemini 1.5 Pro/Flash	✅
Mistral	Mistral Large/Medium	✅
Azure	GPT-4, GPT-4o	✅

Documentazione

• PRD v2 - Product Requirements Document (DocuMente)
• Frontend Plan - Piano sviluppo frontend
• Test Coverage - Report coverage test
• AGENTS.md - Linee guida per OpenCode
• CONTRIBUTING.md - Come contribuire

⚖️ Licenza e Note Legali

Questo software è proprietà 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 è il Foro di Milano, Italia.

Vedi LICENSE per i termini completi.

Contributing

Vedi CONTRIBUTING.md per le linee guida su come contribuire al progetto.

---

Autore: Luca Sacchi Ricciardi
Contatto: luca@lucasacchi.net
Copyright: © 2026 Tutti i diritti riservati