📬 Mail RAG Architecture (Retrieval-Augmented Generation)

Sistema completo ed in produzione per la sincronizzazione IMAP, l'indicizzazione locale ultra-veloce (SQLite FTS5) e l'interrogazione tramite RAG On-Demand di archivi mail di grandi dimensioni (300.000+ file .eml).

---

📂 Alberatura del Repository (/home/mf18626/forgejo/mail/)

.
├── .env.example                # Modello di variabili d'ambiente (Credenziali IMAP, URL Ollama, Identità)
├── .gitignore                  # Esclusione dati sensibili, maildir, database e build artifacts
├── README.md                   # Documentazione principale del repository
├── docker-compose.yml          # Orchestrazione dei container Docker mail-sync e mail-analyzer
├── ask_emails.py               # Strumento CLI per la ricerca e l'interrogazione RAG On-Demand
├── architettura_mail_rag.md    # Documentazione architetturale in formato Markdown + Diagrammi Mermaid
├── architettura_mail_rag.tex   # Articolo formale in formato LaTeX (pubblicazione / report tecnico)
├── architettura_mail_rag.pdf   # PDF compilato a partire dal sorgente LaTeX (4 pagine)
├── sync/
│   ├── Dockerfile              # Immagine Docker per la sincronizzazione IMAP con mbsync
│   ├── entrypoint.sh           # Script di avvio per interpolazione variabili ed esecuzione sync
│   └── mbsyncrc.template       # Template di configurazione parametrico per mbsync
└── analyzer/
    ├── Dockerfile              # Immagine Docker per l'indicizzatore metadati Python
    ├── process_emails.py       # Daemon residente in background per popolamento SQLite/FTS5
    └── requirements.txt        # Dipendenze Python (requests)

---

🧩 Analisi dei Componenti

1. docker-compose.yml

Orchestra i due microservizi trasversali:

• mail-sync: Esegue il download IMAP incrementale dei file .eml nella directory locale ./maildir/.
• mail-analyzer: Daemon Python residente che controlla ogni 5 minuti la presenza di nuove mail nella cartella ./maildir/ e ne popola le intestazioni in SQLite in <1 secondo.

2. sync/ (Sincronizzazione IMAP)

• sync/Dockerfile: Basato su Alpine Linux leggero, installa isync (mbsync), ca-certificates e gettext (envsubst).
• sync/mbsyncrc.template: Template parametrico che riceve le credenziali dal file .env senza mai esporre password in chiaro nei repository Git.
• sync/entrypoint.sh: Interpola le variabili d'ambiente in /etc/mbsyncrc ed esegue mbsync -a in sicurezza.

3. analyzer/ (Indicizzazione Metadati)

• analyzer/process_emails.py: Daemon Python che esegue la Fase 1 di indicizzazione rapida (500 mail in 0,5s) popolare le tabelle emails ed emails_fts (FTS5 Full-Text Search). Rimane in ascolto continuo con ciclo while True: ed un intervallo di sleep a 300s per azzerare l'uso di CPU/GPU quando inattivo.

4. ask_emails.py (Interfaccia CLI RAG)

Strumento da riga di comando per interrogare l'archivio mail:

• Ricerca FTS5: Trova in 0.01s i 20 candidati più rilevanti.
• Stemming Linguistico: Normalizza termini tecnici e plurali (es. incidente \rightarrow incident).
• UID Resolution: Risolve dinamicamente i percorsi Maildir reali cercando l'identificativo IMAP U=XXXX, tollerando i cambi di flag eseguiti da Thunderbird o mbsync.
• HTML Fallback: Decodifica le mail Outlook/Exchange prive di parte text/plain.
• Filtro Anno Automatico: Se la domanda cita un anno (es. 2025), vincola la query SQL su date_iso LIKE '2025%'.

---

🚀 Guida Rapida all'Avvio (Quickstart)

1. Configurazione Variabili d'Ambiente

Copia il file di esempio .env.example creando il file .env:

cp .env.example .env

Modifica il file .env inserendo le tue credenziali IMAP ed il tuo server Ollama:

OLLAMA_URL=http://<IP_SERVER_OLLAMA>:11434/api/generate
OLLAMA_MODEL=ornith:9b

IMAP_HOST=imap.tuodominio.it
IMAP_USER=tuo.nome@tuodominio.it
IMAP_PASS=tua_password_segreta

USER_NAME=Tuo Nome Cognome
USER_EMAIL=tuo.nome@tuodominio.it

2. Avvio dei Servizi Docker

docker compose up -d

Verifica che i container siano attivi:

docker compose ps
docker logs -f mail-analyzer

3. Esecuzione delle Interrogazioni RAG

Esegui domande in lingua naturale sull'archivio:

python3 ask_emails.py "Nel 2025, quali indicazioni sono state fornite per il monitoraggio dei sistemi?"

---

📄 Documentazione Tecnica e Pubblicazione LaTeX

Nello stesso repository sono disponibili le trattazioni approfondite dell'architettura:

• architettura_mail_rag.md: Documento Markdown con diagrammi di flusso Mermaid.
• architettura_mail_rag.tex: Sorgente LaTeX in formato articolo scientifico.
• architettura_mail_rag.pdf: Documento PDF compilato pronto per la consultazione (4 pagine).

Per ricompilare il file PDF da sorgente LaTeX:

pdflatex -interaction=nonstopmode architettura_mail_rag.tex