# PDF → Chunk RAG-ready

Converte PDF digitali in chunk semantici pronti per la vettorizzazione RAG,
senza LLM né OCR.

**Pipeline:** PDF → Markdown strutturato → chunk semantici → embedding ChromaDB  
**Stack:** Python · PyMuPDF · pdfplumber  
**Non supportati:** PDF scansionati (solo immagini), PDF protetti da password.

---

## Setup

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## Flusso completo

### 1. Posiziona il PDF

```
sources/<nome>.pdf
```

### 2. Converti il PDF in Markdown

```bash
# Singolo documento
.venv/bin/python conversione/ --stem <nome>

# Tutti i PDF in sources/
.venv/bin/python conversione/

# Forza riesecuzione (sovrascrive output esistente)
.venv/bin/python conversione/ --stem <nome> --force
```

Output in `conversione/<nome>/`:

| File | Descrizione |
|------|-------------|
| `raw.md` | Markdown grezzo — **non modificare** |
| `clean.md` | Markdown pulito — input per il chunker |
| `structure_profile.json` | Struttura rilevata e strategia di chunking |
| `report.json` | Metriche di qualità della conversione |

### 3. Verifica la qualità del Markdown (opzionale)

```bash
.venv/bin/python conversione/ validate <nome> --detail
```

Se lo score è ≥ 80 e `valid=true`, procedi. Altrimenti usa `/prepare-md` per
correzioni manuali (sillabazione residua, header malformati, ecc.).

### 4. Genera i chunk

```bash
.venv/bin/python chunks/chunker.py --stem <nome>

# Forza riesecuzione
.venv/bin/python chunks/chunker.py --stem <nome> --force
```

La strategia di chunking (`h3_aware`, `h2_paragraph_split`, `paragraph`,
`sliding_window`) viene scelta automaticamente da `structure_profile.json`.

Output in `chunks/<nome>/`:

| File | Descrizione |
|------|-------------|
| `chunks.json` | Lista di chunk con testo, sezione, titolo e metadati |
| `report.json` | Statistiche e anomalie del chunking |

### 5. Verifica i chunk

```bash
.venv/bin/python chunks/verify_chunks.py --stem <nome>
```

Verdict possibili:

| Verdict | Significato | Cosa fare |
|---------|-------------|-----------|
| `ok` | Nessun problema | Procedi alla vettorizzazione |
| `warnings_only` | Solo avvisi minori | Puoi procedere o eseguire il fix |
| `blocked` | Problemi bloccanti (chunk incompleti) | Esegui il fix |

### 6. Correggi i problemi (se necessario)

```bash
# Anteprima delle correzioni senza applicarle
.venv/bin/python chunks/fix_chunks.py --stem <nome> --dry-run

# Applica le correzioni (ricorsivo, fino a 3 iterazioni)
.venv/bin/python chunks/fix_chunks.py --stem <nome>
```

Il fix gestisce automaticamente: chunk incompleti (frase spezzata), chunk
troppo corti (accorpa al successivo), chunk eccessivamente lunghi (spezza
su punteggiatura). Ogni chunk termina sempre su un confine di frase.

### 7. Esegui l'ingestion

Prima verifica che Ollama e i modelli siano pronti:

```bash
.venv/bin/python ollama/check_env.py
```

Poi genera gli embedding e salva in ChromaDB:

```bash
# Singolo documento
.venv/bin/python ingestion/ingest.py --stem <nome>

# Tutti i documenti in chunks/
.venv/bin/python ingestion/ingest.py

# Rigenera dopo aver cambiato modello o aggiornato i chunk
.venv/bin/python ingestion/ingest.py --stem <nome> --force
```

Output in `chroma_db/<nome>/` (ignorata da git).

---

## Configurazione del chunking

Tutti i parametri sono in [`chunks/config.py`](chunks/config.py):

```python
TARGET_CHARS    = 600   # dimensione target dei chunk
CHUNK_TOLERANCE = 0.25  # ±25% → range accettabile [450, 750]
OVERLAP_SENTENCES = 1   # frasi di overlap tra chunk consecutivi
PROTECT_TABLES  = True  # tabelle emesse come chunk atomici
FIX_MAX_ITERATIONS = 3  # iterazioni massime del fix ricorsivo
```

Per ogni strategia è possibile definire valori diversi tramite `STRATEGY_OVERRIDES`.
Modificare solo questo file — chunker, verify e fix si aggiornano automaticamente.

---

## Test

```bash
.venv/bin/python -m pytest tests/
```

---

## Riferimenti

- [`conversione/README.md`](conversione/README.md) — dettagli sulla pipeline PDF→Markdown e sui tipi di documento supportati
- [`ingestion/README.md`](ingestion/README.md) — configurazione embedding, scelta modello, regole --force