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