RAGGER/README.md

RAGGER

Sistema RAG (Retrieval-Augmented Generation) per un'associazione di volontariato.

Caratteristiche

• Chat con documenti: Interroga i documenti caricati in linguaggio naturale
• Generazione lettere: Crea lettere formali basate sui documenti dell'associazione
• Generazione progetti: Proponi nuovi progetti con supporto AI
• Agent intelligente: Multi-pass retrieval e query rewriting automatico

Architettura

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Streamlit  │───▶│   Agent     │───▶│   RAG       │
│     UI      │    │  (agent.py) │    │  (core.py)  │
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │
                    ┌────────────────────────┼────────────┐
                    │                        │            │
               ┌────▼────┐            ┌─────▼────┐  ┌────▼────┐
               │ Ollama  │            │  Qdrant  │  │   OCR   │
               │ (LLM)   │            │ (Vector) │  │(Tesseract)
               └─────────┘            └──────────┘  └─────────┘

Tech Stack

Componente	Tecnologia
UI	Streamlit
LLM	Ollama (gemma2:9b, llama3.2)
Embedding	nomic-embed-text
Vector DB	Qdrant
OCR	Tesseract
Documenti	python-docx, openpyxl, python-pptx

Installazione

# Clona il repository
cd RAGGER

# Crea ambiente virtuale
python -m venv venv
source venv/bin/activate

# Installa dipendenze
pip install -r requirements.txt

# Installa dipendenze di sistema (Ubuntu/Debian)
sudo apt-get install -y tesseresseract-ocr-ita tesseract-ocract-ocr t-eng poppler-utils

# Copia .env
cp .env.example .env
# Modifica .env con le tue impostazioni

Configurazione

Modifica il file .env:

# Provider LLM
LLM_PROVIDER=ollama

# Ollama Server
OLLAMA_HOST=https://ollama.solarpi.net
OLLAMA_MODEL=llama3.2:latest
OLLAMA_EMBED_MODEL=pedrovillalobos/nomic-embed-text-no-gpu

# Qdrant
QDRANT_PATH=./data/qdrant

# OCR
TESSERACT_LANG=ita+eng

Esecuzione

# Attiva l'ambiente virtuale
source venv/bin/宣传活动

# Avvia l'app
streamlit run app.py

Apri nel browser: http://localhost:8501

Utilizzo

1. Carica documenti

• Trascina o seleziona file nella sidebar
• Formati supportati: PDF, DOCX, XLSX, PPTX, TXT, CSV, immagini

2. Scegli la modalità

• Chat: Fai domande sui documenti
• Lettera: Genera lettere formali
• Progetto: Crea proposte di progetto
• Impostazioni: Configura provider e modelli

3. Monitora i log

• Sidebar → "📜 Log Applicazione" per vedere l'attività in tempo reale

Debug

# Health check
python debug.py health

# Test embedding
python debug.py test-embed

# Test generazione
python debug.py test-gen

# Reset database
python debug.py reset-db

# Ingest documenti di test
python debug.py ingest-testdoc

Struttura Progetto

ragger/
├── app.py              # UI Streamlit
├── agent.py            # Agent intelligente
├── core.py             # Logica RAG
├── document_processor.py # Estrazione documenti
├── chunker.py          # Text chunking
├── ollama_client.py    # Client Ollama
├── vectorstore.py      # Qdrant operations
├── config.py           # Configurazione
├── logger.py           # Logging
├── debug.py            # Utility debug
├── requirements.txt    # Dipendenze Python
├── .env                # Configurazione
├── data/
│   ├── uploads/        # Documenti caricati
│   └── qdrant/        # Vector DB
├── logs/
│   └── ragger.log     # Log file
└── testdoc/           # Documenti di test

Problemi Comuni

Timeout generazione

Se le risposte impiegano troppo tempo:

• Il server Ollama carica il modello ad ogni richiesta
• Prova un modello più leggero (llama3.2:latest invece di gemma2:9b)
• Usa un provider esterno (OpenCode, Groq) per risposte più veloci

OCR non funziona

# Verifica installazione Tesseract
tesseract --version

# Installa lingue
sudo apt-get install tesseract-ocr-ita tesseract-ocr-eng

License

MIT