80 lines
2.9 KiB
Markdown
80 lines
2.9 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`:** 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
|
|
```
|