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`:** Il file `raw.md` di ogni stem è immutabile. La copia di lavoro è sempre `clean.md`.

---

## Pipeline (operazioni in ordine)

```
PDF (sources/)
  → conversione    (PDF → clean.md + structure_profile.json)
  → chunking       (clean.md → chunks.json)
  → verifica       (chunks.json → report + fix automatici)
  → vettorizzazione (chunks.json → ChromaDB)
  → retrieval      (query → risposta via Ollama)
```

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

---

## File critici

| File | Ruolo |
|---|---|
| `config.py` | Fonte di verità: `EMBED_MODEL`, `OLLAMA_MODEL`, `TOP_K`, `TEMPERATURE`, `SYSTEM_PROMPT` |
| `chunker.py` | Chunking adattivo — `MIN_CHARS=200`, `MAX_CHARS=800`, `OVERLAP_S=2` |
| `verify_chunks.py` | Verifica chunk — stesse soglie di `chunker.py` |
| `fix_chunks.py` | Fix automatici su chunk anomali |
| `ingest.py` | Vettorizzazione ChromaDB — legge `EMBED_MODEL` da `config.py` |
| `rag.py` | Pipeline RAG interattiva |
| `conversione/pipeline.py` | Conversione PDF → clean Markdown strutturato |

---

## Regole di assistenza

**Modifica `EMBED_MODEL` in `config.py`:**
Avvisa sempre che serve rieseguire la vettorizzazione:
```bash
python 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 più file che vanno sincronizzati manualmente:
- `chunker.py`
- `verify_chunks.py`
- `fix_chunks.py`

**Conversione PDF → Markdown:**
`conversione/pipeline.py` produce `raw.md` e `clean.md`. Il `clean.md` va sempre revisionato dopo la conversione automatica — la qualità del RAG dipende da esso più di qualsiasi parametro tecnico. Suggerisci sempre `/prepare-md conversione/<stem>/clean.md` dopo la conversione.

**Verifica chunk:**
Dopo `verify_chunks.py`, usa `/step6-fix <stem>` prima di procedere con la vettorizzazione.

---

## Skills custom

- `/prepare-md <path>` — Revisione e correzione automatica di qualsiasi `clean.md`: sillabazione, artefatti, header malformati, paragrafi spezzati, gerarchia, sezioni vuote. Accetta path completo (`conversione/bitcoin/clean.md`) o stem (`bitcoin`).
- `/step6-fix <stem>` — Dry-run e applicazione fix chunk tramite `fix_chunks.py`.

---

## Output per stem

```
conversione/<stem>/raw.md              ← immutabile
conversione/<stem>/clean.md            ← copia di lavoro
conversione/<stem>/structure_profile.json
<stem>/chunks.json
<stem>/report.json
chroma_db/<stem>/                      ← collection ChromaDB
```