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

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