Estrazione

Il dominio di estrazione trasforma i documenti office in una rappresentazione intermedia congelata e consapevole dello stile (la IR StyledGrid) — non "semplice suddivisione del testo." Ogni estrattore è deterministico per impostazione predefinita, consapevole di colore e stile, e produce fatti direttamente oppure emette una StyledGrid per l'ingestione a valle. I parser pesanti (Docling, PaddleOCR) stanno dietro giunzioni Protocol e vengono importati in modo lazy, quindi il core funziona offline.

Struttura

La IR StyledGrid

ir.py definisce due dataclass. Una StyledGrid è un foglio di lavoro o una pagina di tabella; le sue cells sono una mappa sparsa da cell_ref a StyledCell.

StyledCell

Una singola cella consapevole dello stile.

StyledCell.rgb_tag_key() restituisce la chiave di clustering dei colori: None quando cf_affected, altrimenti resolved_rgb. Le celle all'interno di regioni con formattazione condizionale sono deliberatamente escluse dalla semantica dei colori perché il loro riempimento non è affidabile.

StyledGrid

Metodi chiave: get(cell_ref), iter_cells(), add_warning(message) e cells_by_rgb() — che raggruppa le celle con colore affidabile per resolved_rgb, saltando le celle None e cf_affected. Vedi La IR StyledGrid.

Estrattori

Esistono per progettazione due obiettivi di estrazione:

• Gli estrattori di fatti (xlsx_extractor, pptx_extractor) producono direttamente oggetti Fact per schemi noti (ad es. una tabella riepilogativa quinquennale) — zero allucinazioni, zero LLM.
• Gli estrattori con stile (*_styled_extractor, pdf_*) producono la IR StyledGrid per il percorso di ingestione generale, preservando colore e stile.

from ragspine.extraction.extractors.xlsx_styled_extractor import extract_grids

grids = extract_grids("report.xlsx")        # list[StyledGrid], one per sheet
for cell in grids[0].iter_cells():
    print(cell.cell_ref, cell.value, cell.resolved_rgb)

Instradamento PDF — triage per pagina

Prima dell'estrazione, un PDF viene sottoposto a triage pagina per pagina. routing/pdf_router.route(path) restituisce una RoutingDecision che trasporta lo verdict del file, un PageInfo per pagina e — per i file misti — una channel_plan che mappa ogni numero di pagina a un nome di pipeline.

classify_page(page, page_no) ricava un kind per pagina da due segnali — il conteggio dei caratteri di testo estraibile e la copertura delle immagini — confrontati con TEXT_MIN_CHARS = 50 e IMG_COVER_SCAN = 0.55:

route() aggrega le pagine in un verdetto sul file (digital / scanned / ocr_scan / mixed / unreadable) con una soglia del 90%, legge i metadati producer/creator in origin_meta e imposta ask_for_pptx=True quando il producer sembra un export di PowerPoint / Keynote / Impress (così un chiamante può richiedere invece il sorgente nativo). I file cifrati o corrotti restituiscono verdict="unreadable" con error impostato — mai un'eccezione.

Semantica dei colori — clustering, legenda, registro versionato

color/color_semantics.py è il livello di inferenza controllata L2: mappa i colori di riempimento delle celle al loro significato di business, ma solo dopo che un umano ha confermato la mappatura. La pipeline:

MappingRegistry è uno store sqlite indipendente (tabella color_mapping, PK (scope, version)). La sua API: register_draft(mapping) (incrementa automaticamente la versione per scope), confirm(scope, version, actor, note=None), reject(...) e get_active(scope). I fatti fanno riferimento a una mappatura confermata tramite il suo mapping_version, così la tracciabilità sopravvive alle revisioni. Vedi Semantica dei colori.

Verifica a doppio canale

verification/dual_channel_verifier.verify(facts_a, facts_b, queue=None, tolerance=0.0) esegue la verifica incrociata di due estrazioni indipendenti della stessa tabella (l'esempio nel docstring: parsing di tabelle con Docling vs. ricostruzione dal layer di testo). Ciascun lato è una lista di ChannelFact, allineate per dim_key = (metric_code, entity, period_type, period, channel):

• Accordo (stessa chiave, valori entro tolerance) → approvazione automatica.
• Conflitto (stessa chiave, valori diversi) → accodato con motivo "dual_channel_conflict", priority=10.
• Solo canale singolo (chiave presente su un solo lato) → accodato con motivo "single_channel_only", priority=50.

Restituisce un VerificationResult (agreed, conflicts, only_in_a, only_in_b, n_auto_passed, n_enqueued). Con queue=None si limita a classificare e non accoda nulla. I conflitti vengono revisionati prima dei casi a canale singolo perché il numero di priorità è più basso. Questa logica pura non ha alcuna dipendenza da Docling.

Giunzioni Protocol

Le dipendenze pesanti vengono iniettate tramite Protocol @runtime_checkable in modo che un parser possa essere sostituito senza toccare il punto di chiamata dell'ingestione, e il percorso sia testabile offline con un fake.

Invarianti garantite da questo dominio

• Deterministico per impostazione predefinita, zero allucinazioni — tabelle native e dati di grafico vengono letti strutturalmente; OCR/LLM è un fallback dietro una giunzione, mai il default.
• Affidabilità dei colori — le celle cf_affected e le mappature non confermate non producono mai etichette silenziose.
• Tracciabilità di versione — source_file_hash + extractor_version (+ mapping_version) viaggiano con ogni valore estratto.
• Componibilità — i parser pesanti sono giunzioni Protocol importate in modo lazy; il core funziona offline.

Correlati