diff --git a/.claude/commands/step6-fix.md b/.claude/commands/post-chunk.md similarity index 59% rename from .claude/commands/step6-fix.md rename to .claude/commands/post-chunk.md index 66a88a4..9a6ce50 100644 --- a/.claude/commands/step6-fix.md +++ b/.claude/commands/post-chunk.md @@ -1,25 +1,23 @@ --- -description: Verifica i chunk di step 5, mostra i problemi, propone e applica le fix tramite fix_chunks.py con ri-verifica automatica finale. +description: Perfeziona i chunk di un documento (verifica, dry-run, fix, ri-verifica) e li prepara per la vettorizzazione. allowed-tools: Read Bash Grep argument-hint: --- -## Passo 0 β€” Verifica fresca (sempre) +## Passo 0 β€” Verifica fresca -Esegui sempre `verify_chunks.py` per avere un report aggiornato (non fidarti di un report.json preesistente): +Esegui sempre `verify_chunks.py` per un report aggiornato: ```bash -source .venv/bin/activate && python step-6/verify_chunks.py --stem $ARGUMENTS +source .venv/bin/activate && python chunks/verify_chunks.py --stem $ARGUMENTS ``` ---- - Leggi il report appena generato: !`python3 -c " import json, sys try: - r = json.load(open('step-6/$ARGUMENTS/report.json')) + r = json.load(open('chunks/$ARGUMENTS/report.json')) v = r.get('verdict','?') s = r.get('stats', {}) t = r.get('thresholds', {}) @@ -35,7 +33,7 @@ try: print(f' πŸ”΄ {label}: {len(items)}') for c in items[:3]: print(f' [{c[\"chunk_id\"]}] {c[\"n_chars\"]} char β†’ {c[\"last_text\"][-60:]!r}') - for cat, label in [('too_short','Troppo corti'), ('too_long','Troppo lunghi')]: + for cat, label in [('too_short','Troppo corti'), ('too_long','Troppo lunghi'), ('incomplete_math','Math incompleto')]: items = wa.get(cat, []) if items: print(f' 🟑 {label}: {len(items)}') @@ -48,14 +46,14 @@ except Exception as e: print(f'ERRORE lettura report: {e}') ## Se verdict == "ok" -βœ… Nessun problema. Comunica: +βœ… Nessun problema bloccante. Comunica: ``` -βœ… Chunk puliti β€” procedi con la vettorizzazione: +βœ… Chunk pronti β€” procedi con la vettorizzazione: python step-8/ingest.py --stem $ARGUMENTS ``` -Fermati qui. Non eseguire nessun altro passo. +Se ci sono solo 🟑, spiega brevemente i warning e chiedi se l'utente vuole risolverli prima o procedere. --- @@ -64,15 +62,16 @@ Fermati qui. Non eseguire nessun altro passo. ### Passo 1 β€” Dry-run ```bash -source .venv/bin/activate && python step-6/fix_chunks.py --stem $ARGUMENTS --dry-run +source .venv/bin/activate && python chunks/fix_chunks.py --stem $ARGUMENTS --dry-run ``` Spiega in italiano ogni operazione pianificata: -- **rimuovi chunk vuoti** β€” chunk privi di testo, non contribuiscono al retrieval -- **aggiungi prefisso** β€” il prefisso `[sezione > titolo]` fornisce contesto all'embedding; senza, il chunk Γ¨ semanticamente decontestualizzato + +- **rimuovi chunk vuoti** β€” privi di testo, non contribuiscono al retrieval +- **aggiungi prefisso** β€” `[sezione > titolo]` fornisce contesto all'embedding; senza, il chunk Γ¨ decontestualizzato - **fondi incompleti** β€” frase spezzata a metΓ : il chunk corrente e il successivo formano una frase unica -- **fondi troppo corti** β€” chunk sotto MIN_CHARS: troppo brevi per portare informazione semantica utile -- **spezza troppo lunghi** β€” chunk sopra MAX_CHARSΓ—1.5: troppo densi, degradano la precision del retrieval +- **fondi troppo corti** β€” sotto MIN_CHARS: troppo brevi per portare informazione semantica utile +- **spezza troppo lunghi** β€” sopra MAX_CHARSΓ—1.5: troppo densi, degradano la precision del retrieval Se ci sono solo 🟑 (nessun πŸ”΄), informa che si puΓ² procedere anche senza fix e chiedi la preferenza. @@ -85,16 +84,16 @@ Applica solo su risposta affermativa esplicita. ### Passo 3 β€” Applica ```bash -source .venv/bin/activate && python step-6/fix_chunks.py --stem $ARGUMENTS +source .venv/bin/activate && python chunks/fix_chunks.py --stem $ARGUMENTS ``` ### Passo 4 β€” Ri-verifica automatica ```bash -source .venv/bin/activate && python step-6/verify_chunks.py --stem $ARGUMENTS +source .venv/bin/activate && python chunks/verify_chunks.py --stem $ARGUMENTS ``` -Leggi il nuovo `step-6/$ARGUMENTS/report.json` e riporta: +Leggi il nuovo `chunks/$ARGUMENTS/report.json` e riporta: - Nuovo verdict - Delta chunk (N prima β†’ N dopo) - Problemi residui se presenti @@ -104,17 +103,17 @@ Leggi il nuovo `step-6/$ARGUMENTS/report.json` e riporta: Se verdict finale Γ¨ `ok` o `warnings_only` senza πŸ”΄: ``` -βœ… Chunk pronti in step-6/$ARGUMENTS/chunks.json +βœ… Chunk pronti in chunks/$ARGUMENTS/chunks.json Procedi con la vettorizzazione: python step-8/ingest.py --stem $ARGUMENTS ``` -Se rimangono πŸ”΄ dopo il fix (raro β€” testo non spezzabile o struttura anomala): +Se rimangono πŸ”΄ dopo il fix (testo non spezzabile o struttura anomala nel sorgente): ``` πŸ”΄ X problemi residui non risolvibili automaticamente. - Torna a step-4/$ARGUMENTS/clean.md e correggi manualmente le sezioni indicate, + Torna a conversione/$ARGUMENTS/clean.md e correggi manualmente le sezioni indicate, poi riesegui nell'ordine: - python step-5/chunker.py --stem $ARGUMENTS --force - python step-6/verify_chunks.py --stem $ARGUMENTS + python chunks/chunker.py --stem $ARGUMENTS --force + python chunks/verify_chunks.py --stem $ARGUMENTS ``` diff --git a/CLAUDE.md b/CLAUDE.md index fc0e27b..109fafd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,4 +43,4 @@ Per i path degli script e degli output usa `git ls-files` o esplora la root: la ## Skills custom - `/prepare-md ` β€” corregge `clean.md`: sillabazione, artefatti, header, paragrafi spezzati, gerarchia. -- `/step6-fix ` β€” verifica chunk, dry-run e applicazione fix via `fix_chunks.py`. +- `/post-chunk ` β€” verifica chunk, dry-run, fix via `fix_chunks.py` e prepara per la vettorizzazione.