davide
94766d67cc
Espande CLAUDE.md da 6 a ~80 righe per orientare Claude Code sulle convenzioni critiche del progetto: pipeline visiva, sincronizzazione soglie chunking su 3 file, coerenza EMBED_MODEL, skills custom.
87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
# 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
|
|
```
|