rag-from-scratch/chunks/config.py

#!/usr/bin/env python3
"""
Parametri della pipeline di chunking.

Input atteso: sources/<stem>/<stem>.md — Markdown già pulito e ben strutturato.
"""

# ─── Dimensione chunk ─────────────────────────────────────────────────────────

# Caratteri massimi per chunk (prefisso di contesto incluso).
# Paragrafi più lunghi vengono spezzati a confine di frase.
# Una singola frase che supera MAX_CHARS non viene mai spezzata.
MAX_CHARS: int = 1200

# Soglia minima attesa (usata da verify_chunks come warning, non blocca).
MIN_CHARS: int = 80

# ─── Spezzatura frasi ─────────────────────────────────────────────────────────

# Regex per rilevare il confine di fine frase.
# Split solo prima di lettera maiuscola o virgolette — evita split su abbreviazioni.
SENTENCE_SPLIT_RE: str = r"(?<=[.!?»])\s+(?=[A-ZÀÈÉÌÒÙ\"])"

# ─── Blocchi atomici ──────────────────────────────────────────────────────────

# Blocchi Markdown che non vengono mai spezzati, anche se superano MAX_CHARS.
ATOMIC_TYPES: set[str] = {"table", "code", "list"}

# ─── Contesto heading ─────────────────────────────────────────────────────────

# Profondità massima del percorso heading incluso nel prefisso di ogni chunk.
# 1 = solo H1, 2 = H1 > H2, 3 = H1 > H2 > H3.
CONTEXT_DEPTH: int = 3

# ─── Sezioni da escludere ────────────────────────────────────────────────────

# Heading (case-insensitive) le cui sezioni vengono saltate completamente.
# Il match è su prefisso: "indice" salta anche "Indice delle figure".
# Lasciare vuoto per non escludere nulla.
SKIP_HEADINGS: set[str] = {
    "indice",
    "sommario",
    "bibliografia",
    "ringraziamenti",
    "abbreviazioni",
}

# Se True, salta il contenuto che precede il primo heading (frontespizio, copertina).
SKIP_PRE_HEADING: bool = True

# ─── Merge paragrafi corti ────────────────────────────────────────────────────

# Paragrafi consecutivi più corti di MIN_CHARS vengono fusi fino a raggiungerlo,
# purché appartengano allo stesso contesto heading.
MERGE_SHORT_PARAGRAPHS: bool = True

# ─── verify_chunks ────────────────────────────────────────────────────────────

# Numero minimo di simboli matematici perché un chunk incompleto sia classificato
# come "matematico" (warning meno grave rispetto a frase spezzata normale).
MATH_SYMS_MIN: int = 3

PROTECT_TABLES: bool = True
PROTECT_MATH:   bool = True