refactor(docs): skill prepare-md sostituisce step4-review, CLAUDE.md senza step-X
This commit is contained in:
@@ -4,83 +4,76 @@
|
||||
|
||||
- **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`.
|
||||
- **Non modificare `raw.md`:** Il file `raw.md` di ogni stem è immutabile. La copia di lavoro è sempre `clean.md`.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline (ordine obbligatorio)
|
||||
## Pipeline (operazioni in ordine)
|
||||
|
||||
```
|
||||
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
|
||||
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.
|
||||
|
||||
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 |
|
||||
| `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 `step-9/config.py`:**
|
||||
**Modifica `EMBED_MODEL` in `config.py`:**
|
||||
Avvisa sempre che serve rieseguire la vettorizzazione:
|
||||
```bash
|
||||
python step-8/ingest.py --stem <stem> --force
|
||||
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 tre file che vanno sincronizzati manualmente:
|
||||
1. `step-5/chunker.py`
|
||||
2. `step-6/verify_chunks.py`
|
||||
3. `step-6/fix_chunks.py`
|
||||
I valori compaiono in più file che vanno sincronizzati manualmente:
|
||||
- `chunker.py`
|
||||
- `verify_chunks.py`
|
||||
- `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`.
|
||||
**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.
|
||||
|
||||
**Step 6 — verifica chunk:**
|
||||
Dopo `verify_chunks.py`, usa `/step6-fix <stem>` prima di passare a step-8.
|
||||
**Verifica chunk:**
|
||||
Dopo `verify_chunks.py`, usa `/step6-fix <stem>` prima di procedere con la vettorizzazione.
|
||||
|
||||
---
|
||||
|
||||
## Skills custom
|
||||
|
||||
- `/step4-review <stem>` — Revisione qualitativa `clean.md`: artefatti, paragrafi spezzati, header errati.
|
||||
- `/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`.
|
||||
|
||||
---
|
||||
|
||||
## Struttura directory per stem
|
||||
## Output 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
|
||||
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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user