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 accademici. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa solo di: chunking, vettorizzazione e retrieval/generazione.

```
MinerU (esterno) → sources/<stem>_output/auto/<stem>.md
                        ↓
                   chunker.py   (chunks.json)
                        ↓
                   ingest.py    (embedding → ChromaDB)
                        ↓
                   rag.py / retrieve.py
```

---

## 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.py` scrive solo in `chunks/<stem>/`.

---

## Input — struttura MinerU

MinerU produce una cartella per ogni documento. Posizionarla in `sources/`:

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

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

---

## 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

# Verifica qualità chunk
.venv/bin/python chunks/verify_chunks.py --stem <stem>

# Vettorizzazione (richiede Ollama attivo)
.venv/bin/python ingestion/ingest.py --stem <stem>
.venv/bin/python ingestion/ingest.py --stem <stem> --force

# RAG interattivo
.venv/bin/python rag.py --stem <stem>
.venv/bin/python retrieve.py --stem <stem>                 # retrieval puro, senza LLM
```

---

## Architettura

### Chunking — `chunks/`

| File | Responsabilità |
|------|---------------|
| `chunker.py` | Legge `<stem>.md`, produce `chunks.json` con regole deterministiche |
| `config.py` | Parametri: `MAX_CHARS`, `MIN_CHARS`, `CONTEXT_DEPTH`, `SKIP_HEADINGS`, `ATOMIC_TYPES` |
| `verify_chunks.py` | Verifica qualità chunk (lunghezze, frasi spezzate, prefissi) |

Regole applicate dal chunker:
- 1 paragrafo = 1 chunk; paragrafi di sezioni diverse non si mescolano
- Split a confine di frase se il paragrafo supera `MAX_CHARS`
- Frasi spezzate tra paragrafi consecutivi vengono ri-fuse automaticamente
- Paragrafi brevi (< `MIN_CHARS`) vengono accorpati al successivo (stesso contesto)
- Sezioni in `SKIP_HEADINGS` saltate completamente; contenuto pre-heading saltato se `SKIP_PRE_HEADING=True`
- Tabelle, liste e code block sono blocchi atomici

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

### Vettorizzazione — `ingestion/ingest.py`

Legge `chunks/<stem>/chunks.json`, genera embedding via Ollama (`EMBED_MODEL`), indicizza in ChromaDB persistente (`chroma_db/`). Supporta collection multi-documento (`--collection <nome> --stems doc1 doc2`).

### RAG — file radice

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

### Output per stem

```
chunks/<stem>/chunks.json
chunks/<stem>/meta.json
chroma_db/<stem>/             ← collection ChromaDB
```

---

## Skills custom

- `/prepare-md <path|stem>` — corregge il Markdown MinerU: sillabazione, artefatti, header malformati, gerarchia incoerente. Opera su una copia, non sull'originale.