feat(pdf-to-md): sostituisci report.md con report.json + validate.py

pipeline.py produce conversione/<stem>/report.json invece di
structure_profile.json + report.md. Il JSON contiene tutto:
trasformazioni, struttura, distribuzione lunghezze sezioni,
anomalie (bare_headers, short/long sections) e residui con esempi.

Fix: bare_headers flagga solo header senza corpo < 30 chars;
header numerati con corpo lungo (aforismi) non sono anomalie.

Nuovo validate.py legge tutti i report.json e stampa tabella
di stato per ogni stem ( / ⚠️ / ) con soglie configurabili.

README aggiornato con sezione validazione batch e struttura report.json.
This commit is contained in:
2026-04-16 15:53:46 +02:00
parent b8d3c459c8
commit e06b65272b
3 changed files with 338 additions and 17 deletions
+74 -13
View File
@@ -55,26 +55,49 @@ Per ogni stem vengono prodotti tre file in `conversione/<stem>/`:
|------|-------------|
| `raw.md` | Markdown grezzo estratto dal PDF — **non modificare** |
| `clean.md` | Markdown pulito e strutturato — input per il chunker |
| `structure_profile.json` | Profilo strutturale del documento |
| `report.json` | Metriche complete di qualità della conversione |
### structure_profile.json
### report.json
Contiene tutto ciò che serve per valutare la conversione: statistiche
trasformazioni, struttura rilevata, distribuzione lunghezze sezioni,
anomalie e problemi residui con esempi.
```json
{
"livello_struttura": 3,
"n_h1": 1,
"n_h2": 6,
"n_h3": 163,
"n_paragrafi": 213,
"boundary_primario": "h3",
"lingua_rilevata": "it",
"lunghezza_media_sezione": 520,
"strategia_chunking": "h3_aware",
"avvertenze": []
"stem": "dirittoprivato",
"timestamp": "2026-04-16 15:41",
"transforms": {
"n_accenti_corretti": 0,
"n_dotleader_rimossi": 0,
"toc_rimosso": false,
"n_sezioni_numerate": 63,
"riduzione_pct": 1
},
"structure": {
"livello_struttura": 3,
"n_h1": 0, "n_h2": 6, "n_h3": 163,
"lingua_rilevata": "it",
"strategia_chunking": "h3_aware",
"avvertenze": []
},
"distribution": { "min": 12, "p25": 312, "mediana": 681, "p75": 1197, "max": 6120 },
"anomalie": {
"bare_headers": 0,
"short_sections": 1,
"long_sections": 39,
"bare_headers_list": [],
"short_sections_list": [...],
"long_sections_list": [...]
},
"residui": {
"backtick": 0, "dotleader": 0, "url": 0, "immagini": 0,
"backtick_esempi": []
}
}
```
**`strategia_chunking`** indica come il chunker dovrebbe suddividere il documento:
**`strategia_chunking`** indica come suddividere il documento in chunk:
| Valore | Significato |
|--------|-------------|
@@ -85,6 +108,44 @@ Per ogni stem vengono prodotti tre file in `conversione/<stem>/`:
---
## Validazione batch
Dopo aver convertito uno o più documenti, esegui `validate.py` per ottenere
una tabella di stato su tutti gli stem:
```bash
python conversione/validate.py
```
Output di esempio:
```
stem h2 h3 strategia bare corte lunghe backtick dotlead url status
──────────────────────────────────────────────────────────────────────────────────────────────
analisi1 13 279 h3_aware 0 36 151 10 0 0 ⚠️
dirittoprivato 6 163 h3_aware 0 1 39 0 0 0 ✅
nietzsche 4 303 h3_aware 6 104 100 0 0 0 ⚠️
──────────────────────────────────────────────────────────────────────────────────────────────
Totale: 3 ✅ 1 ⚠️ 2 ❌ 0
```
**Legenda colonne:**
| Colonna | Significato | Soglia warning |
|---------|-------------|----------------|
| `bare` | Header solo-numero senza corpo (`### 1.` vuoto) | ≥ 1 |
| `corte` | Sezioni con corpo < 150 chars | informativo |
| `lunghe` | Sezioni con corpo > 1500 chars | ≥ 80 |
| `backtick` | Backtick `` ` `` residui nel testo | ≥ 1 |
| `dotlead` | Dot-leader residui (`. . . .`) | ≥ 1 |
**Stato:**
- ✅ nessuna anomalia critica
- ⚠️ anomalie presenti, documento processabile ma da verificare
- ❌ struttura non rilevata (`livello_struttura = 0`) o > 50 backtick residui
---
## Cosa fa la pipeline
La pipeline esegue quattro fasi in sequenza.