Files

T

davide 6ec54c8616 docs(pdf-to-md): aggiungi README per conversione/

Spiega requisiti (Java 11+, opendataloader-pdf), setup, utilizzo,
output prodotti, tutte le trasformazioni strutturali e i tipi di
documento supportati.

2026-04-16 15:35:58 +02:00

5.7 KiB

Raw Blame History

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:

# 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:

# Singolo documento
python conversione/pipeline.py --stem <nome>

# Tutti i PDF in sources/
python conversione/pipeline.py

# Forza la riesecuzione (sovrascrive output esistente)
python conversione/pipeline.py --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 tre 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`	Profilo strutturale del documento

structure_profile.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": []
}

strategia_chunking indica come il chunker dovrebbe suddividere il documento:

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

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...
  ✅ Immagini rimosse:      0
     Accenti corretti:      3701
     Dot-leader rimossi:    53
     Header concat fixati:  0
     TOC rimosso:           sì
     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.

5.7 KiB Raw Blame History