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.
This commit is contained in:
@@ -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/<nome>.pdf`, poi:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user