From 6ec54c8616497aa09b4a104769d3c5a77f319f33 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Thu, 16 Apr 2026 15:35:42 +0200 Subject: [PATCH] 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. --- conversione/README.md | 175 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 conversione/README.md diff --git a/conversione/README.md b/conversione/README.md new file mode 100644 index 0000000..bb8e983 --- /dev/null +++ b/conversione/README.md @@ -0,0 +1,175 @@ +# 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/.pdf`, poi: + +```bash +# Singolo documento +python conversione/pipeline.py --stem + +# Tutti i PDF in sources/ +python conversione/pipeline.py + +# Forza la riesecuzione (sovrascrive output esistente) +python conversione/pipeline.py --stem --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//`: + +| 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 + +```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.