rag-from-scratch/CLAUDE.md

# CLAUDE.md — RAG from Scratch

## Regole invarianti

- **Lingua:** Rispondi sempre in italiano.
- **Venv:** Usa `.venv/bin/python` o `source .venv/bin/activate`. Mai `pip`/`python` di sistema.
- **`raw.md` immutabile:** La copia di lavoro è sempre `clean.md`.

---

## Pipeline

```
PDF → conversione → chunking → verifica → vettorizzazione → retrieval
```

`--stem` = nome PDF senza estensione = nome collection ChromaDB.

Per i path degli script e degli output usa `git ls-files` o esplora la root: la struttura è in evoluzione verso un programma unico.

---

## Configurazione

`config.py` è la fonte di verità: `EMBED_MODEL`, `OLLAMA_MODEL`, `TOP_K`, `TEMPERATURE`, `SYSTEM_PROMPT`.

**Se cambi `EMBED_MODEL`:** riesegui ingest con `--force` — embedding incoerenti non producono errori ma risposte insensate.

**Se cambi `MIN_CHARS` / `MAX_CHARS`:** cerca tutte le occorrenze nel repo e sincronizza.

---

## Workflow consigliato

1. Converti il PDF con lo script di conversione
2. `/prepare-md conversione/<stem>/clean.md`
3. Chunking
4. Vettorizza con `--stem <stem>`
6. `python rag.py --stem <stem>`

---

## Skills custom

- `/prepare-md <path|stem>` — corregge `clean.md`: sillabazione, artefatti, header, paragrafi spezzati, gerarchia.
- `/post-chunk <stem>` — verifica chunk, dry-run, fix via `fix_chunks.py` e prepara per la vettorizzazione.