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

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

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

.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

.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

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

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

.venv/bin/python ollama/check_env.py

Poi genera gli embedding e salva in ChromaDB:

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

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

.venv/bin/python -m pytest tests/

---

Riferimenti

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