# DocuMente

[![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**

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](https://github.com/astral-sh/uv) per dependency management
- Node.js 18+ (per il frontend)
- Docker (opzionale)

## Installazione

```bash
# 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:

```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

# 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)

```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/
├── 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](./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
- [CONTRIBUTING.md](./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](./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**: © 2026 Tutti i diritti riservati