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:

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

2.9 KiB Raw Blame History