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:**
```bash
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`:
```python
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

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

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