250 lines
8.6 KiB
Markdown
250 lines
8.6 KiB
Markdown
# conversione — PDF → Markdown pulito
|
|
|
|
Pipeline automatica che trasforma un PDF grezzo in Markdown strutturato e
|
|
pronto per la suddivisione in chunk. Gestisce l'intero processo: validazione
|
|
del PDF, estrazione del testo, pulizia strutturale e analisi della struttura
|
|
del documento.
|
|
|
|
## Requisiti
|
|
|
|
### Python
|
|
```
|
|
pip install opendataloader-pdf pdfplumber
|
|
```
|
|
|
|
### Java 11+
|
|
`opendataloader-pdf` richiede Java sul PATH. Se non è installato:
|
|
|
|
```bash
|
|
# Ubuntu / Debian / WSL
|
|
sudo apt install default-jdk
|
|
|
|
# Verifica
|
|
java -version
|
|
```
|
|
|
|
Download alternativo: https://adoptium.net/
|
|
|
|
---
|
|
|
|
## Utilizzo
|
|
|
|
Posiziona il PDF in `sources/<nome>.pdf`, poi:
|
|
|
|
```bash
|
|
# Singolo documento
|
|
python conversione/ --stem <nome>
|
|
|
|
# Tutti i PDF in sources/
|
|
python conversione/
|
|
|
|
# Forza la riesecuzione (sovrascrive output esistente)
|
|
python conversione/ --stem <nome> --force
|
|
```
|
|
|
|
Il parametro `--stem` è il nome del file PDF senza estensione.
|
|
Esempio: `sources/analisi1.pdf` → `--stem analisi1`
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
Per ogni stem vengono prodotti quattro file in `conversione/<stem>/`:
|
|
|
|
| File | Descrizione |
|
|
|------|-------------|
|
|
| `raw.md` | Markdown grezzo estratto dal PDF — **non modificare** |
|
|
| `clean.md` | Markdown pulito e strutturato — input per il chunker |
|
|
| `structure_profile.json` | Struttura rilevata e strategia di chunking consigliata |
|
|
| `report.json` | Metriche complete di qualità della conversione |
|
|
|
|
### 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
|
|
{
|
|
"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 suddividere il documento in chunk:
|
|
|
|
| Valore | Significato |
|
|
|--------|-------------|
|
|
| `h3_aware` | Documento ricco di sezioni `###` — usa i `###` come boundary |
|
|
| `h2_paragraph_split` | Struttura parziale `##` — suddividi per paragrafo dentro ogni `##` |
|
|
| `paragraph` | Nessuna gerarchia chiara — suddividi per paragrafo |
|
|
| `sliding_window` | Testo piatto — usa finestra scorrevole |
|
|
|
|
---
|
|
|
|
## Validazione batch
|
|
|
|
Dopo aver convertito uno o più documenti, esegui `validate` per ottenere
|
|
una tabella di stato su tutti gli stem:
|
|
|
|
```bash
|
|
# Tutti i documenti
|
|
python conversione/ validate
|
|
|
|
# Singolo documento con dettaglio penalità
|
|
python conversione/ validate <stem> --detail
|
|
```
|
|
|
|
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.
|
|
|
|
### Fase 1 — Validazione
|
|
|
|
Verifica che il PDF esista, non sia vuoto, non sia protetto da password e
|
|
contenga testo digitale estraibile. I PDF scansionati (immagini) non sono
|
|
supportati.
|
|
|
|
### Fase 2 — Estrazione testo
|
|
|
|
Usa `opendataloader-pdf` con l'algoritmo **XY-Cut++** per ricostruire il
|
|
corretto ordine di lettura anche in documenti multi-colonna. Le immagini
|
|
vengono ignorate completamente — il `clean.md` non contiene mai riferimenti
|
|
a immagini.
|
|
|
|
### Fase 3 — Pulizia strutturale
|
|
|
|
Serie di trasformazioni applicate al Markdown grezzo:
|
|
|
|
| Trasformazione | Problema risolto |
|
|
|----------------|-----------------|
|
|
| Rimozione riferimenti immagini | Artefatti `![...]()` lasciati dal convertitore |
|
|
| Fix accenti backtick LaTeX | `` `e``→`è`, ``puo` ``→`può`, ``sar`a``→`sarà` |
|
|
| Rimozione dot-leader TOC | `- 1.1 Titolo . . . . . 42` (voci indice) |
|
|
| Rimozione numerali romani pagina | `i`, `ii`, `iii` su riga isolata (footer LaTeX) |
|
|
| Fix header + body concatenati | `### 11 TitoloCorpo testo...` → header + paragrafo separati |
|
|
| Estrazione header Capitolo inline | `Capitolo 3: IL TITOLO` nel corpo → `## Capitolo 3: ...` |
|
|
| Normalizzazione livelli header | `####`, `#####` → `###` (gerarchia uniforme a 3 livelli) |
|
|
| Rimozione bold negli header | `## **Titolo**` → `## Titolo` |
|
|
| Normalizzazione ALL-CAPS header | `## IL TITOLO` → `## Il titolo` |
|
|
| Rimozione TOC | Blocchi indice/sommario rilevati per keyword |
|
|
| ALL-CAPS standalone → header | Righe in maiuscolo isolate → `## Titolo` |
|
|
| Sezioni numerate → header | `N. Titolo sezione` → `### N.` + corpo |
|
|
| Sezioni con punto → header | `- N. Testo aphorismo...` → `### N.` + corpo |
|
|
| Sezioni lista numerate → header | `- N Titolo Corpo testo...` → `### N. Titolo` + corpo |
|
|
| Unione paragrafi spezzati | Paragrafi tagliati dal salto pagina PDF ricongiunti |
|
|
| Normalizzazione whitespace | Spazi multipli ridotti a singoli |
|
|
| Riduzione righe vuote | Tre o più righe vuote consecutive → due |
|
|
| Rimozione URL watermark | `www.piattaforma.com`, `https://...` su riga isolata |
|
|
| Rimozione header senza corpo | Sezioni vuote e header watermark scartati |
|
|
|
|
> **Rilevamento automatico tipo documento**: se il documento contiene sezioni
|
|
> "Esercizi" (libri di testo accademici), la conversione dei numeri di esercizio
|
|
> in header viene disabilitata automaticamente.
|
|
|
|
### Fase 4 — Analisi struttura
|
|
|
|
Rileva la gerarchia del documento (conteggio `#`/`##`/`###`), la lingua
|
|
(italiano / inglese / sconosciuta), la lunghezza media delle sezioni e
|
|
suggerisce la strategia di chunking ottimale. I risultati sono scritti in
|
|
`structure_profile.json`.
|
|
|
|
---
|
|
|
|
## Tipi di documento supportati
|
|
|
|
| Tipo | Esempi | Note |
|
|
|------|--------|------|
|
|
| Testo giuridico / accademico | Manuali, dispense, codici | Header numerati `N.` e `N.N` |
|
|
| Filosofia / saggistica | Aforismi numerati, capitoli | Pattern `- N. testo` |
|
|
| Matematica / LaTeX | Analisi, algebra, fisica | Fix accenti, TOC, numerali romani |
|
|
| Testo generico strutturato | Qualsiasi PDF digitale | Paragrafi e header standard |
|
|
|
|
**Non supportati**: PDF scansionati (solo immagini), PDF protetti da password.
|
|
|
|
---
|
|
|
|
## Log di esecuzione
|
|
|
|
Durante l'esecuzione la pipeline stampa le statistiche di ogni trasformazione:
|
|
|
|
```
|
|
[3/4] Pulizia strutturale...
|
|
✅ Simboli PUA corretti: 0
|
|
Immagini rimosse: 0
|
|
Note rimosse: 12
|
|
Accenti corretti: 3701
|
|
Dot-leader rimossi: 53
|
|
Header concat fixati: 0
|
|
Header num. normaliz.: 8
|
|
Articoli → ###: 0
|
|
Ambienti matematici: 0
|
|
Titoli header uniti: 4
|
|
TOC rimosso: sì
|
|
Versi poesia riprist.: 0
|
|
Header verso demotati: 0
|
|
ALL-CAPS → ##: 14
|
|
Sezioni → ###: 279
|
|
Paragrafi uniti: 12998
|
|
Riduzione testo: 3%
|
|
```
|
|
|
|
Se un documento è già stato convertito, la pipeline lo salta automaticamente.
|
|
Usa `--force` per rieseguire.
|