RAGGER/CHANGELOG.md

RAGGER - Changelog Sessione 22/02/2026

Obiettivo Iniziale

Implementare un sistema di debug e test efficace per il progetto RAGGER, un sistema RAG (Retrieval-Augmented Generation) per un'associazione di volontariato.

---

1. Sistema di Debug

1.1 Creazione logger.py

Sistema di logging verboso con:

• Output colorato su console
• Log su file con rotazione (5MB, 3 files)
• File: logs/ragger.log
• Livello: DEBUG

1.2 Riscrittura debug.py

Utility completa con menu interattivo:

MENU
------------------------------
  1. Health Check
  2. Show Status
  3. Show Logs
------------------------------
  4. Test Embedding
  5. Test Generation
  6. Test Qdrant
  7. Ingest testdoc/
------------------------------
  8. Reset Database
  9. Reset Uploads
  0. Full Reset (DESTROY ALL)
------------------------------

Comandi CLI disponibili:

python debug.py health          # Health check 7 componenti
python debug.py reset-db        # Reset database (conferma)
python debug.py reset-all       # Reset completo (DESTROY)
python debug.py ingest-testdoc  # Ingest documenti da testdoc/
python debug.py test-embed      # Test embedding
python debug.py test-gen        # Test generazione
python debug.py test-qdrant     # Test Qdrant

1.3 Health Check

Verifica 7 componenti:

1. Tesseract OCR + Lingue (ita, eng)
2. Poppler (pdf2image)
3. Connessione Ollama
4. Modello Embedding (nomic-embed-text)
5. Qdrant Vector DB
6. Uploads Directory
7. Logs Directory

---

2. Logging Integrato

2.1 Moduli aggiornati con logging

File	Modifica
ollama_client.py	Logging richieste HTTP, embedding, generazione
vectorstore.py	Logging operazioni CRUD, search
core.py	Logging ingest, query, generazione
ocr.py	Logging estrazione OCR
chunker.py	Logging chunking
app.py	Health check all'avvio

2.2 Configurazione

Aggiunto in config.py:

LOG_LEVEL: str = "DEBUG"

---

3. Supporto Multi-Formato Documenti

3.1 Nuovo document_processor.py

Sostituisce ocr.py con supporto per:

Estensione	Tipo	Metodo
.pdf	PDF	OCR (Tesseract)
.png, .jpg, .jpeg, .tiff, .bmp	Immagini	OCR
.xlsx, .xls	Excel	openpyxl
.docx, .doc	Word	python-docx
.pptx, .ppt	PowerPoint	python-pptx
.txt, .md	Testo	Lettura diretta
.csv	CSV	Lettura diretta

3.2 Dipendenze aggiunte

openpyxl       # Excel
python-docx    # Word
python-pptx    # PowerPoint

3.3 Aggiornamenti correlati

• chunker.py: Aggiunto campo sheet per Excel
• vectorstore.py: Aggiunto sheet nel payload
• app.py: Aggiornato file_uploader per tutti i formati
• core.py: Import aggiornato a document_processor

---

4. Configurazione

4.1 File .env aggiornato

LLM_PROVIDER=ollama
OLLAMA_HOST=https://ollama.solarpi.net
OLLAMA_MODEL=gemma2:9b
OLLAMA_EMBED_MODEL=pedrovillalobos/nomic-embed-text-no-gpu
LOG_LEVEL=DEBUG

4.2 Timeout aumentato

ollama_client.py: Timeout da 120s a 300s per generazione lenta su CPU.

---

5. Test Effettuati

5.1 Health Check

[1/7] Tesseract OCR.............. ✅ v5.5.0
[2/7] Tesseract Languages........ ✅ ita, eng
[3/7] Poppler (pdf2image)........ ✅
[4/7] Ollama Connection.......... ✅ 0.3s
[5/7] Embedding Model............ ✅ 768 dims, 2.2s
[6/7] Qdrant..................... ✅ 11 chunks
[7/7] Uploads Directory.......... ✅ 1 file

STATUS: 7/7 OK

5.2 Ingest Documenti

Documenti nella cartella testdoc/:

• Nuova Modalità di Iscrizione UILDM Gorizia.pdf → 2 chunks
• Soci UILDM.xlsx → 4 chunks
• UILDM GORIZIA 2026 Brochure_2.pdf → 2 chunks
• progetto_insieme_senza_confini.pdf → 3 chunks

Totale: 11 chunks

5.3 Search Test

Query: "come iscriversi alla UILDM"

• Risultato #1: score 0.70 (documento corretto)

---

6. Struttura Progetto Finale

ragger/
├── app.py                    # UI Streamlit
├── core.py                   # Logica RAG
├── document_processor.py     # Estrazione testo multi-formato
├── ocr.py                    # Tesseract wrapper (deprecato)
├── chunker.py                # Text chunking
├── ollama_client.py          # Client Ollama
├── vectorstore.py            # Qdrant
├── config.py                 # Settings
├── logger.py                 # Logging system
├── debug.py                  # Debug utility
├── requirements.txt          # Dipendenze
├── .env                      # Configurazione attiva
├── .env.example              # Template
├── data/
│   ├── uploads/              # Documenti caricati
│   └── qdrant/               # Vector DB
├── logs/
│   └── ragger.log            # Log file
├── testdoc/                  # Documenti di test
└── docs/
    └── DESIGN.md             # Documento di design

---

7. Comandi Rapidi

# Attiva ambiente
source venv/bin/activate

# Health check
python debug.py health

# Ingest documenti test
python debug.py ingest-testdoc

# Reset database
python debug.py reset-db

# Avvia app
streamlit run app.py

---

8. Note Tecniche

8.1 Problemi noti

• Generazione lenta: gemma2:9b su CPU remoto richiede ~2+ minuti per risposta
• Qdrant cleanup warning: Warning innocuo alla chiusura di Python

8.2 Architettura

• Monolitica: Single app per singolo utente
• Ollama remoto: Server esistente a ollama.solarpi.net
• Qdrant locale: Database vettoriale in data/qdrant/
• Tesseract locale: OCR on-premise

---

9. Prossimi Passi

1. Testare l'app Streamlit con streamlit run app.py
2. Valutare modello più veloce per generazione (es. llama3.2)
3. Implementare agentic layer (query planning, multi-pass retrieval)
4. Aggiungere UI per visualizzare documenti indicizzati

---

Sessione completata: 22/02/2026