rag-from-scratch/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Missione

Ricostruire la struttura logica di PDF digitali e serializzarla in Markdown stabile e valido per la vettorizzazione RAG, senza LLM né OCR. Il Markdown è solo il formato di output finale — la pipeline deve operare su una rappresentazione intermedia strutturata.

Non supportato: PDF scansionati (immagini), PDF protetti da password.

---

Regole invarianti

• Lingua: Rispondi sempre in italiano.
• Venv: Usa .venv/bin/python o source .venv/bin/activate. Mai pip/python di sistema.
• raw.md immutabile: Non modificare mai raw.md. La copia di lavoro è sempre clean.md.
• Niente LLM nella pipeline: tutta la logica deve essere rule-based e riproducibile.

---

Setup

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

Dipendenze principali:

• PyMuPDF (fitz) — estrazione primaria con metadati font e coordinate
• pdfplumber — ricostruzione tabelle (opzionale, non per parsing generico)

---

Comandi

# Converti un PDF (posizionalo prima in sources/<nome>.pdf)
.venv/bin/python conversione/ --stem <nome>

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

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

# Validazione batch
.venv/bin/python conversione/ validate
.venv/bin/python conversione/ validate <stem> --detail

# Rimuove l'output di uno stem
bash conversione/clear.sh <nome>

# Test suite
.venv/bin/python -m pytest tests/

--stem = nome file PDF senza estensione.

---

Architettura

Principio fondamentale

La pipeline non converte direttamente PDF → Markdown.

PDF → Structured Document Tree → Markdown

Il Markdown è generato solo dall'albero documentale. Non dal testo grezzo.

Modello dati intermedio

class Block:
    text: str
    page: int
    bbox: tuple
    font_size: float
    font_name: str
    is_bold: bool
    block_type: str  # "header" | "paragraph" | "list" | "table" | "code"

class Section:
    title: str
    level: int          # 1, 2, 3
    content: list[Block]
    children: list[Section]

Il Markdown si genera solo da Section. Mai da Block direttamente.

---

I 9 stadi della pipeline

Stage 1 — Metadata Extraction

Usa page.get_text("dict") (o "rawdict") di PyMuPDF. Non usare estrazione plain text.

Per ogni span estrai: testo, font size, font name, flags, bbox, numero di pagina. Estrai anche: TOC del documento, bookmark, dimensioni pagina.

Stage 2 — Layout Analysis

Identifica i blocchi strutturali preservando l'ordine di lettura: headers, paragrafi, liste, tabelle, code block, interruzioni di pagina.

Stage 3 — Font Analysis

Inferisce la gerarchia visiva per documento (non hardcoded):

• calcola il font size dominante del corpo
• raggruppa i font size in cluster
• identifica i candidati header per dimensione

Stage 4 — Header Detection

Segnali combinati (tutti richiesti):

• font size > corpo testo
• boldness / semibold
• numerazione (^\d+(\.\d+)*\s+)
• spaziatura verticale sopra/sotto
• lunghezza riga corta

Stage 5 — Hierarchy Inference

Priorità delle regole (in ordine):

1. Numerazione — 1 → H1, 1.1 → H2, 1.1.1 → H3 (ha precedenza sul font size)
2. TOC del PDF — se presente, è autoritativo; allineare i header rilevati alla sua gerarchia
3. Font size clustering — fallback se né numerazione né TOC esistono

Stage 6 — Document Tree Reconstruction

Costruisce l'albero Section con relazioni parent-child, ordinamento e nesting. Ogni nodo contiene titolo, livello, contenuto e figli.

Stage 7 — Markdown Generation

Serializza l'albero in Markdown valido:

• Header: #/##/### senza salti di livello
• Liste: preserva nesting ordered/unordered
• Tabelle: GitHub-compatible; fallback testo strutturato
• Code block: fenced con language tag dove rilevabile

Stage 8 — Hierarchy Normalization

Ripara le inconsistenze strutturali:

• salti di livello invalidi (# A → #### B diventa # A → ## B)
• header vuoti (rimuovi o mergia)
• header consecutivi duplicati (collassa)
• nesting rotto

Stage 9 — Structural Validation

Valida il Markdown finale:

• nessun salto di livello heading
• nessuna sezione vuota
• liste correttamente annidate
• tabelle con colonne consistenti
• ordine uguale al PDF sorgente

---

Cosa rende un Markdown perfetto per la vettorizzazione

• Struttura semantica: ogni header è un confine naturale di chunk; ogni sezione è un'unità concettuale.
• Gerarchia corretta: h1/h2/h3 riflettono la struttura logica, non il layout tipografico.
• Testo pulito: nessun artefatto di encoding, footnote superscript, <br>, dot-leader, PUA.
• Paragrafi interi: nessuna frase troncata da salto pagina.
• Output deterministico: stessa pipeline su stesso PDF produce sempre lo stesso output.

---

Linee guida per sviluppare la pipeline

• Ogni stage deve essere indipendentemente testabile.
• Le regex per header numbering e simili vanno compilate in _constants.py, mai inline.
• PyMuPDF è il parser primario. pdfplumber si usa solo per tabelle complesse.
• Ogni stage deve ricevere l'output del precedente come struttura tipizzata, non testo grezzo.
• Prima di aggiungere un nuovo segnale di detection (Stage 4), validarlo su almeno 3 PDF diversi.

Categorie di test richieste

Categoria	Input	Validazione attesa
Header reconstruction	PDF con H1/H2/H3 numerati	gerarchia corretta, no level skip
TOC alignment	PDF con bookmark/TOC	markdown allineato al TOC
Mixed font sizes	Font inconsistenti, bold nel corpo	body non classificato come header
Broken layout	Header multi-riga, spacing irregolare	header mergiati, markdown valido
Tables	Tabelle nel PDF	markdown table con colonne preservate
Lists	Liste ordered/unordered annidate	nesting corretto
Large documents	PDF tecnico voluminoso	output deterministico, memoria stabile
Invalid hierarchy repair	# A + #### B artificiale	riparazione automatica in # A + ## B

---

Pipeline attuale

La pipeline in conversione/_pipeline/ (basata su trasformazioni testo con _apply.py) è deprecata e deve essere sostituita dall'architettura a 9 stadi descritta sopra. Durante la migrazione:

• separare estrazione da ricostruzione
• introdurre strutture intermedie esplicite (Block, Section)
• rimuovere l'architettura parser-centrica
• ogni stage deve essere indipendente e testabile

---

Skills custom

• /prepare-md <path|stem> — corregge clean.md quando la pipeline non basta: sillabazione, artefatti residui, header malformati, gerarchia incoerente.