From 70b304e1d42c44fc0d643df1a2e183ae1821d7d0 Mon Sep 17 00:00:00 2001
From: Davide Grilli <davide.grilli@outlook.com>
Date: Mon, 11 May 2026 15:46:52 +0200
Subject: [PATCH] =?UTF-8?q?docs(readme):=20flusso=20completo=20conversione?=
 =?UTF-8?q?=20=E2=86=92=20chunking?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 137 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 103 insertions(+), 34 deletions(-)

diff --git a/README.md b/README.md
index a3ca353..cea5b99 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,11 @@
-# PDF → Markdown
+# PDF → Chunk RAG-ready
 
-Converte PDF digitali in Markdown strutturato e pulito.
+Converte PDF digitali in chunk semantici pronti per la vettorizzazione RAG,
+senza LLM né OCR.
 
-**Stack:** Python · opendataloader-pdf (XY-Cut++) · Java 11+  
-**Compatibile con:** Linux · macOS · Windows (WSL2)
+**Pipeline:** PDF → Markdown strutturato → chunk semantici  
+**Stack:** Python · PyMuPDF · pdfplumber  
+**Non supportati:** PDF scansionati (solo immagini), PDF protetti da password.
 
 ---
 
@@ -15,54 +17,121 @@ source .venv/bin/activate
 pip install -r requirements.txt
 ```
 
-**Java 11+** richiesto:
-
-```bash
-sudo apt install default-jdk   # Ubuntu/Debian/WSL
-java -version
-```
-
 ---
 
-## Utilizzo
+## Flusso completo
+
+### 1. Posiziona il PDF
+
+```
+sources/<nome>.pdf
+```
+
+### 2. Converti il PDF in Markdown
 
 ```bash
-# Singolo PDF
-python conversione/pipeline.py --stem <nome>
+# Singolo documento
+.venv/bin/python conversione/ --stem <nome>
 
 # Tutti i PDF in sources/
-python conversione/pipeline.py
+.venv/bin/python conversione/
 
-# Forza riesecuzione
-python conversione/pipeline.py --stem <nome> --force
+# Forza riesecuzione (sovrascrive output esistente)
+.venv/bin/python conversione/ --stem <nome> --force
 ```
 
-`--stem` = nome file PDF senza estensione.  
-Esempio: `sources/analisi1.pdf` → `--stem analisi1`
-
----
-
-## Output
-
-Per ogni stem in `conversione/<stem>/`:
+Output in `conversione/<nome>/`:
 
 | File | Descrizione |
 |------|-------------|
 | `raw.md` | Markdown grezzo — **non modificare** |
-| `clean.md` | Markdown pulito — copia di lavoro |
-| `structure_profile.json` | Struttura rilevata e metriche |
-| `report.json` | Statistiche complete della conversione |
+| `clean.md` | Markdown pulito — input per il chunker |
+| `structure_profile.json` | Struttura rilevata e strategia di chunking |
+| `report.json` | Metriche di qualità della conversione |
 
----
-
-## Validazione batch
+### 3. Verifica la qualità del Markdown (opzionale)
 
 ```bash
-python conversione/validate.py
+.venv/bin/python conversione/ validate <nome> --detail
 ```
 
-Stampa una tabella di stato su tutti gli stem convertiti.
+Se lo score è ≥ 80 e `valid=true`, procedi. Altrimenti usa `/prepare-md` per
+correzioni manuali (sillabazione residua, header malformati, ecc.).
+
+### 4. Genera i chunk
+
+```bash
+.venv/bin/python chunks/chunker.py --stem <nome>
+
+# Forza riesecuzione
+.venv/bin/python chunks/chunker.py --stem <nome> --force
+```
+
+La strategia di chunking (`h3_aware`, `h2_paragraph_split`, `paragraph`,
+`sliding_window`) viene scelta automaticamente da `structure_profile.json`.
+
+Output in `chunks/<nome>/`:
+
+| File | Descrizione |
+|------|-------------|
+| `chunks.json` | Lista di chunk con testo, sezione, titolo e metadati |
+| `report.json` | Statistiche e anomalie del chunking |
+
+### 5. Verifica i chunk
+
+```bash
+.venv/bin/python chunks/verify_chunks.py --stem <nome>
+```
+
+Verdict possibili:
+
+| Verdict | Significato | Cosa fare |
+|---------|-------------|-----------|
+| `ok` | Nessun problema | Procedi alla vettorizzazione |
+| `warnings_only` | Solo avvisi minori | Puoi procedere o eseguire il fix |
+| `blocked` | Problemi bloccanti (chunk incompleti) | Esegui il fix |
+
+### 6. Correggi i problemi (se necessario)
+
+```bash
+# Anteprima delle correzioni senza applicarle
+.venv/bin/python chunks/fix_chunks.py --stem <nome> --dry-run
+
+# Applica le correzioni (ricorsivo, fino a 3 iterazioni)
+.venv/bin/python chunks/fix_chunks.py --stem <nome>
+```
+
+Il fix gestisce automaticamente: chunk incompleti (frase spezzata), chunk
+troppo corti (accorpa al successivo), chunk eccessivamente lunghi (spezza
+su punteggiatura). Ogni chunk termina sempre su un confine di frase.
 
 ---
 
-Vedi [`conversione/README.md`](conversione/README.md) per dettagli sulla pipeline e i tipi di documento supportati.
+## Configurazione del chunking
+
+Tutti i parametri sono in [`chunks/config.py`](chunks/config.py):
+
+```python
+TARGET_CHARS    = 600   # dimensione target dei chunk
+CHUNK_TOLERANCE = 0.25  # ±25% → range accettabile [450, 750]
+OVERLAP_SENTENCES = 1   # frasi di overlap tra chunk consecutivi
+PROTECT_TABLES  = True  # tabelle emesse come chunk atomici
+FIX_MAX_ITERATIONS = 3  # iterazioni massime del fix ricorsivo
+```
+
+Per ogni strategia è possibile definire valori diversi tramite `STRATEGY_OVERRIDES`.
+Modificare solo questo file — chunker, verify e fix si aggiornano automaticamente.
+
+---
+
+## Test
+
+```bash
+.venv/bin/python -m pytest tests/
+```
+
+---
+
+## Riferimenti
+
+- [`conversione/README.md`](conversione/README.md) — dettagli sulla pipeline PDF→Markdown e sui tipi di documento supportati