Gap Filling Module (GFM)

I Gap Filling Module sono i mattoni del motore di calcolo EOS. Ogni modulo e un'unita specializzata e autonoma che gestisce un aspetto specifico del calcolo dell'impatto ambientale.

Cosa sono i Gap Filling Module?

Nel mondo reale, i dati sui prodotti alimentari sono spesso incompleti. Un prodotto potrebbe avere:

• Un nome ma nessuna lista ingredienti
• Ingredienti ma nessuna informazione sull'origine
• Origine ma nessun dettaglio sul trasporto
• Dati nutrizionali parziali

I GFM risolvono questo problema colmando automaticamente le lacune nei dati del prodotto utilizzando modelli scientifici, database e valori predefiniti intelligenti.

Il Concetto GFM

Ogni GFM consiste di:

1. Logica di Pianificazione - Determina se il modulo e rilevante per un dato nodo
2. Verifica di Prontezza - Verifica che tutte le dipendenze siano soddisfatte
3. Esecuzione - La logica di calcolo che colma le lacune e aggiorna il grafo

Moduli Disponibili

EOS include 28 GFM specializzati organizzati per funzione:

Moduli di Matching

Abbinano nomi di prodotti e ingredienti alle voci del database:

Modulo	Scopo
match_product_name_gfm	Abbina i nomi dei prodotti alle voci del database
attach_food_tags_gfm	Allega tag di classificazione alimentare
link_term_to_activity_node_gfm	Collega i termini alle attivita LCA
link_food_categories_gfm	Assegna categorie alimentari

Moduli di Localizzazione

Gestiscono dati geografici e di origine:

Modulo	Scopo
origin_gfm	Determina l'origine del prodotto
location_gfm	Gestione della posizione geografica
transportation_decision_gfm	Determina le modalita di trasporto
transportation_mode_distance_gfm	Calcola le distanze di trasporto

Moduli del Ciclo di Vita

Modellano la trasformazione e la catena di fornitura:

Modulo	Scopo
processing_gfm	Impatti della trasformazione alimentare
greenhouse_gfm	Calcoli dei gas serra
conservation_gfm	Conservazione e stoccaggio
perishability_gfm	Fattori di durata e spreco

Moduli di Valutazione dell'Impatto

Calcolano le metriche ambientali:

Modulo	Scopo
impact_assessment_gfm	Aggrega i calcoli di impatto
water_scarcity_gfm	Calcolo dell'impronta idrica
rainforest_gfm	Impatto sulla deforestazione
vitascore_gfm	Punteggio nutrizionale

Moduli di Aggregazione

Combinano i risultati tra gli ingredienti:

Modulo	Scopo
aggregation_gfm	Aggrega gli impatti degli ingredienti
ingredient_splitter_gfm	Scompone ingredienti compositi
ingredient_amount_estimator_gfm	Stima le quantita degli ingredienti

Architettura dei Moduli

Ogni GFM segue il pattern Factory/Worker:

# Factory - inizializzato una volta per servizio, gestisce i worker
class ExampleGapFillingFactory(AbstractGapFillingFactory):
    def __init__(self, postgres_db, service_provider):
        super().__init__(postgres_db, service_provider)
        self.cache = {}  # Cache persistente tra i calcoli

    async def init_cache(self):
        # Carica i dati richiesti in memoria
        pass

    def spawn_worker(self, node):
        return ExampleGapFillingWorker(node)

# Worker - creato per nodo, esegue il calcolo
class ExampleGapFillingWorker(AbstractGapFillingWorker):
    def should_be_scheduled(self) -> bool:
        # Questo GFM e rilevante per questo nodo?
        return self.node.needs_processing()

    def can_run_now(self) -> GapFillingWorkerStatusEnum:
        # Le dipendenze sono soddisfatte?
        if self.node.has_required_data():
            return GapFillingWorkerStatusEnum.ready
        return GapFillingWorkerStatusEnum.reschedule

    async def run(self, calc_graph):
        # Esegui la logica di gap-filling
        result = await self.calculate()
        self.node.set_property("result", result)

Perche Factory/Worker?

Beneficio	Descrizione
Isolamento	Ogni calcolo viene eseguito nella propria istanza worker
Caching	La Factory mantiene le cache tra i calcoli
Scalabilita	I worker possono essere distribuiti
Test	I worker possono essere testati indipendentemente

Orchestrazione

L'orchestratore coordina l'esecuzione dei GFM:

Ciclo di Pianificazione

1. Aggiunta Nodo - Quando i nodi vengono aggiunti al CalcGraph, l'orchestratore crea i worker
2. Verifica Pianificazione - Viene chiamato should_be_scheduled() di ogni worker
3. Verifica Prontezza - can_run_now() verifica le dipendenze
4. Esecuzione - I worker pronti vengono eseguiti in modo asincrono
5. Aggiornamenti Grafo - I risultati vengono scritti nelle proprieta del nodo
6. Propagazione - Nuovi nodi possono attivare GFM aggiuntivi

Dipendenze tra Moduli

I moduli dipendono dagli output di altri moduli:

Le dipendenze vengono risolte automaticamente attraverso il ciclo di pianificazione dell'orchestratore.

Gestione dello Stato

I GFM tracciano il loro stato di esecuzione per ogni nodo:

# Stato per-nodo memorizzato in GfmStateProp (worker_states)
# I valori provengono da NodeGfmStateEnum: "S" (scheduled), "F" (finished), "C" (canceled)
gfm_state = {
    "MatchProductNameGapFillingWorker": "F",  # completato
    "OriginGapFillingWorker": "F",            # completato
    "GreenhouseGapFillingWorker": "S",        # pianificato (in esecuzione)
    "ImpactAssessmentGapFillingWorker": "S"   # pianificato (in attesa)
}

Valori di Stato

Lo stato GFM viene tracciato usando NodeGfmStateEnum:

Stato	Codice	Descrizione
scheduled	S	GFM pianificato per essere eseguito su questo nodo
finished	F	GFM completato con successo
canceled	C	GFM cancellato (non applicabile o fallito)

Gestione degli Errori

I GFM implementano una gestione degli errori robusta:

async def run(self, calc_graph):
    try:
        result = await self.calculate()
        self.node.set_property("result", result)
    except Exception as e:
        # Registra l'errore con contesto
        logger.error("GFM fallito",
            gfm=self.__class__.__name__,
            node_uid=self.node.uid,
            error=str(e))
        # Crea DataError per tracciamento
        error = DataError(
            node_uid=self.node.uid,
            gfm_name=self.__class__.__name__,
            message=str(e),
            classification=ErrorClassification.calculation_error
        )
        self.node.add_error(error)

Strategia di Fallback

Quando un modulo fallisce:

1. Registra l'errore - Logging strutturato con contesto
2. Crea DataError - Traccia per reportistica
3. Continua l'elaborazione - Altri moduli possono comunque essere eseguiti
4. Segnala incertezza - Marca il risultato con confidenza ridotta

Prossimi Passi

• Come Funzionano i GFM - Meccanica dettagliata
• Catalogo Moduli - Tutti i moduli disponibili
• GFM SDK (in arrivo) - Costruisci moduli personalizzati