rag-from-scratch/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

## Lingua e comportamento

- **Lingua:** Rispondi sempre in italiano.
- **Prima di eseguire qualsiasi istruzione**, esponi:
  1. Come intendi procedere (approccio, file coinvolti).
  2. Se l'istruzione ha problemi concettuali — e perché — con una proposta alternativa.
  3. Aspetta conferma o correzione prima di toccare il codice, salvo che l'istruzione sia banale (rinomina, formattazione).

---

## Missione

Pipeline RAG su documenti PDF, interamente in locale. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa di: chunking, vettorizzazione, retrieval/generazione e GUI desktop.

Il PDF viene convertito da MinerU in Markdown strutturato. Il chunker lo analizza e produce chunk semantici. Il modulo di ingest genera gli embedding tramite Ollama e li indicizza in ChromaDB. Infine `rag/rag.py` (o la GUI) riceve la domanda, recupera i chunk più rilevanti e genera la risposta.

---

## Regole invarianti

- **Venv:** Usa `.venv/bin/python`. Mai `pip`/`python` di sistema.
- **Niente LLM nella pipeline:** chunking e pulizia devono essere rule-based e riproducibili.
- **Input immutabile:** Non modificare mai i file in `sources/`. Il chunker scrive solo in `chunks/<stem>/`.

---

## Input — struttura MinerU

```
sources/<stem>_output/auto/<stem>.md        ← Markdown strutturato (input della pipeline)
sources/<stem>_output/auto/images/          ← immagini estratte
```

`<stem>` = nome del documento, usato come identificatore in tutti i comandi.

---

## Comandi

```bash
# Setup
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

# Chunking
.venv/bin/python chunks/chunker.py --stem <stem>
.venv/bin/python chunks/chunker.py                          # tutti gli stem in sources/
.venv/bin/python chunks/chunker.py --stem <stem> --force    # rigenera anche se già presente

# Vettorizzazione (richiede Ollama attivo)
.venv/bin/python ingestion/ingest.py --stem <stem>
.venv/bin/python ingestion/ingest.py --collection <nome> --stems doc1 doc2 doc3
.venv/bin/python ingestion/ingest.py --stem <stem> --force

# RAG interattivo
.venv/bin/python rag/rag.py --collection <nome>
.venv/bin/python rag/rag.py --stem <stem>

# Retrieval puro (debug senza LLM)
.venv/bin/python rag/retrieve.py --stem <stem>
.venv/bin/python rag/retrieve.py --collection <nome> --top-k 10

# GUI desktop
.venv/bin/python gui/main.py
.venv/bin/python gui/main.py --collection <nome>

# Verifica ambiente Ollama
.venv/bin/python ollama/check_env.py
```

---

## Architettura

### Chunking — `chunks/`

| File | Responsabilità |
|------|---------------|
| `chunker.py` | Entry point: legge `<stem>.md`, orchestra parser → segmenter → packer → validator |
| `parser.py` | Markdown → AST di `Block` tramite markdown-it-py |
| `segmenter.py` | AST → sequenza di `Block` con header_path e contesto heading |
| `packer.py` | `Block[]` → `Chunk[]` con packing min/target/max |
| `validator.py` | Verifica integrità e coerenza dei chunk prodotti |
| `models.py` | Dataclass: `Block`, `Chunk`, `Diagnostics`, `ChunkingResult` |
| `config.py` | `ChunkerConfig`: `max_chars`, `min_chars`, `target_chars`, `context_depth`, `skip_headings`, `atomic_types` |

Output per stem: `chunks/<stem>/chunks.json`, `chunks/<stem>/meta.json`, `chunks/<stem>/report.json`

**Schema chunk** (`chunks.json`):

| Campo | Descrizione |
|-------|-------------|
| `chunk_id` | Identificatore univoco |
| `content_for_embedding` | Testo con prefisso heading, usato per generare il vettore |
| `content_original` | Testo originale senza prefisso, memorizzato in ChromaDB |
| `header_path` | Lista di dict `{level, text}` — gerarchia heading del chunk |
| `content_type` | Tipo blocco dominante (`paragraph`, `table`, `code`, ecc.) |
| `flags` | Dict: `has_code`, `has_table`, `has_math`, `is_overflow` |
| `chunk_index` | Posizione ordinale nel documento |
| `start_line` / `end_line` | Righe sorgente nel Markdown |
| `chars` | Lunghezza in caratteri di `content_original` |

### Vettorizzazione — `ingestion/`

| File | Responsabilità |
|------|---------------|
| `ingest.py` | Legge `chunks.json`, genera embedding via Ollama, indicizza in ChromaDB |
| `config.py` | `EMBED_MODEL` (default: `bge-m3`), `EMBED_MAX_CHARS`, `OLLAMA_URL` |

ChromaDB persistente in `chroma_db/`. Supporta collection multi-documento (`--collection`).

### RAG — `rag/`

| File | Responsabilità |
|------|---------------|
| `rag.py` | Loop interattivo: retrieval + generazione Ollama |
| `retrieve.py` | Retrieval puro (debug senza LLM) |
| `config.py` | `TOP_K`, `TEMPERATURE`, `NO_THINK`, `OLLAMA_MODEL`, `OLLAMA_URL`, `SYSTEM_PROMPT` |

### GUI — `gui/`

| File | Responsabilità |
|------|---------------|
| `main.py` | Entry point PySide6, argparse `--collection` |
| `chat_window.py` | `QMainWindow`: top bar (combo collection + toggle tema), `QWebEngineView`, input bar |
| `worker.py` | `QThread`: esegue retrieve + build_prompt + call_ollama in background |
| `chat.html` | Template HTML con marked.js + KaTeX (CDN); funzioni JS: `addMessage`, `addThinking`, `removeThinking`, `setTheme` |

Temi light/dark gestiti via CSS custom properties in `chat.html` e stylesheet Qt in `chat_window.py`.

### Utility — `ollama/`

| File | Responsabilità |
|------|---------------|
| `check_env.py` | Verifica che Ollama sia attivo e i modelli configurati siano disponibili |
| `test_ollama.py` | Test embedding e generazione end-to-end |