rag-from-scratch/CLAUDE.md

# CLAUDE.md — RAG from Scratch

## Regole invarianti

- **Lingua:** Rispondi sempre in italiano.
- **Venv obbligatorio:** Usa `.venv/bin/python` o attiva con `source .venv/bin/activate`. Mai `pip`/`python` di sistema.
- **Non modificare `raw.md`:** `step-2/<stem>/raw.md` è immutabile. La copia di lavoro è `step-4/<stem>/clean.md`.

---

## Pipeline (ordine obbligatorio)

```
PDF (sources/) → step-0 → step-1 → step-2 → step-3
              → step-4 (CRITICO: revisione manuale clean.md)
              → step-5 → step-6 → step-7 (Ollama) → step-8 → step-9
```

Il parametro `--stem` identifica il documento (nome PDF senza `.pdf`). Lo stem è anche il nome della collection ChromaDB.

Comandi tipici:
```bash
source .venv/bin/activate
python step-4/revise.py --stem <stem>
python step-5/chunker.py --stem <stem>
python step-6/verify_chunks.py --stem <stem>
python step-8/ingest.py --stem <stem>
python step-9/rag.py --stem <stem>
```

---

## File critici

| File | Ruolo |
|---|---|
| `step-9/config.py` | Fonte di verità: `EMBED_MODEL`, `OLLAMA_MODEL`, `TOP_K`, `TEMPERATURE`, `SYSTEM_PROMPT` |
| `step-5/chunker.py` | Chunking adattivo — `MIN_CHARS=200`, `MAX_CHARS=800`, `OVERLAP_S=2` |
| `step-6/verify_chunks.py` | Verifica chunk — stesse soglie di `chunker.py` |
| `step-6/fix_chunks.py` | Fix automatici su chunk anomali |
| `step-4/revise.py` | Pre-processing MD automatico (8 trasformazioni euristiche) |
| `step-8/ingest.py` | Vettorizzazione ChromaDB — legge `EMBED_MODEL` da `config.py` |
| `step-9/rag.py` | Pipeline RAG interattiva |

---

## Regole di assistenza

**Modifica `EMBED_MODEL` in `step-9/config.py`:**
Avvisa sempre che serve rieseguire la vettorizzazione:
```bash
python step-8/ingest.py --stem <stem> --force
```
`ingest.py` importa `EMBED_MODEL` direttamente da `config.py` — la coerenza è critica: se violata non produce errori ma restituisce risultati insensati.

**Modifica soglie chunking (`MIN_CHARS`, `MAX_CHARS`, `OVERLAP_S`):**
I valori compaiono in tre file che vanno sincronizzati manualmente:
1. `step-5/chunker.py`
2. `step-6/verify_chunks.py`
3. `step-6/fix_chunks.py`

**Step 4 — revisione clean.md:**
`revise.py` applica trasformazioni automatiche, ma il risultato va sempre revisionato a mano. La qualità del RAG dipende da `clean.md` più di qualsiasi parametro tecnico. Suggerisci sempre `/step4-review <stem>` dopo `revise.py`.

**Step 6 — verifica chunk:**
Dopo `verify_chunks.py`, usa `/step6-fix <stem>` prima di passare a step-8.

---

## Skills custom

- `/step4-review <stem>` — Revisione qualitativa `clean.md`: artefatti, paragrafi spezzati, header errati.
- `/step6-fix <stem>` — Dry-run e applicazione fix chunk tramite `fix_chunks.py`.

---

## Struttura directory per stem

```
step-2/<stem>/raw.md                ← immutabile
step-4/<stem>/clean.md              ← copia di lavoro
step-4/<stem>/structure_profile.json
step-5/<stem>/chunks.json
step-6/<stem>/report.json
chroma_db/<stem>/                   ← collection ChromaDB
```