Come Funziona EOS Core

Questa guida illustra il processo di calcolo completo, dai dati grezzi del prodotto ai punteggi finali di impatto ambientale.

Il Grafo di Calcolo

EOS Core utilizza un'architettura basata su grafo di calcolo dove prodotti e ingredienti sono rappresentati come nodi con relazioni. I Gap Filling Module (GFM) operano su questi nodi per colmare i dati mancanti e calcolare gli impatti.

Passo 1: Elaborazione Input

Formati di Input Accettati

Il motore accetta dati di prodotto con vari livelli di dettaglio:

// Input minimo - solo nome prodotto
{
  "name": "Pollo al Curry con Riso"
}

// Input strutturato con ingredienti
{
  "name": "Pollo al Curry con Riso",
  "ingredients": [
    { "name": "Petto di pollo", "amount": 150, "unit": "g" },
    { "name": "Riso basmati", "amount": 200, "unit": "g" },
    { "name": "Latte di cocco", "amount": 100, "unit": "ml" },
    { "name": "Pasta di curry", "amount": 30, "unit": "g" }
  ],
  "servings": 1
}

Creazione Nodi del Grafo

Ogni prodotto e ingrediente diventa un nodo nel grafo di calcolo:

Nodo Prodotto: "Pollo al Curry con Riso"
├── Nodo Flusso: Petto di pollo (150g)
├── Nodo Flusso: Riso basmati (200g)
├── Nodo Flusso: Latte di cocco (100ml)
└── Nodo Flusso: Pasta di curry (30g)

Passo 2: Pianificazione dei Gap Filling Module

L'orchestratore coordina quali GFM devono essere eseguiti su quali nodi.

Logica di Pianificazione

Ogni GFM implementa due metodi chiave:

• should_be_scheduled() - Determina se questo modulo e rilevante per un nodo
• can_run_now() - Verifica se tutte le dipendenze sono soddisfatte

Ciclo Orchestratore:
1. Raccogli tutti i GFM che should_be_scheduled() sui nuovi nodi
2. Per ogni GFM pianificato:
   - Verifica can_run_now()
   - Se pronto: esegui run()
   - Se in attesa: ripianifica per la prossima iterazione
3. Ripeti finche non ci sono piu GFM da eseguire

Gap Filling Module Disponibili

EOS Core include moduli per diversi aspetti del calcolo:

Modulo	Scopo
match_product_name_gfm	Abbina nomi prodotto alle voci del database
origin_gfm	Determina l'origine geografica
location_gfm	Gestisce fattori specifici della localita
greenhouse_gfm	Calcola le emissioni di gas serra
water_scarcity_gfm	Calcola l'impronta idrica
rainforest_gfm	Valuta l'impatto sulla deforestazione
processing_gfm	Modella gli impatti della trasformazione alimentare
transportation_decision_gfm	Determina le modalita di trasporto
transportation_mode_distance_gfm	Calcola le distanze di trasporto
impact_assessment_gfm	Aggrega i calcoli di impatto

Passo 3: Esecuzione dei Moduli

Quando un GFM viene eseguito, legge le proprieta del nodo, esegue i calcoli e riscrive i risultati nel grafo.

Esempio di Flusso di Esecuzione

Prodotto: "Mela Biologica dalla Svizzera"

1. match_product_name_gfm
   → Abbina alla voce del database "mela"
   → Imposta categoria e termini FoodEx2

2. origin_gfm
   → Rileva "Svizzera" nel nome
   → Imposta paese di origine: CH

3. transportation_decision_gfm
   → Determina il trasporto dall'origine al consumo
   → Imposta le modalita di trasporto in base alla deperibilita

4. transportation_mode_distance_gfm
   → Calcola le distanze usando l'API EcoTransit
   → Aggiunge le emissioni di trasporto al grafo

5. matrix_calculation_gfm
   → Esegue calcoli LCA basati su matrici
   → Aggrega tutti i dati dell'inventario

6. impact_assessment_gfm
   → Calcola CO₂eq usando la metodologia IPCC
   → Genera i punteggi di impatto climatico

7. water_scarcity_gfm
   → Applica fattori regionali di stress idrico
   → Calcola l'impronta idrica

8. aggregation_gfm
   → Combina i risultati di tutti gli ingredienti
   → Produce i punteggi finali a livello prodotto

Esecuzione Parallela

I moduli indipendenti possono essere eseguiti in parallelo quando le loro dipendenze sono soddisfatte:

Passo 4: Calcolo dell'Impatto

I moduli di impatto aggregano i dati da tutte le fonti in metriche ambientali.

Calcolo Matriciale

Prima della valutazione dell'impatto, il matrix_calculation_gfm esegue calcoli Life Cycle Assessment basati su matrici per sistemi di prodotto complessi. Questo e un componente critico per le prestazioni che:

• Converte il grafo di calcolo in rappresentazione matriciale
• Risolve l'equazione LCA (h = B × A⁻¹ × f) in modo efficiente
• Aggrega i flussi attraverso grafi di prodotto complessi

Componenti dell'Impatto Climatico

Il calcolo dei gas serra considera:

• Emissioni agricole - Agricoltura e uso del suolo
• Emissioni di trasformazione - Energia usata nella lavorazione alimentare
• Emissioni di trasporto - Distanza × fattore di emissione della modalita
• Emissioni dell'imballaggio - Produzione del materiale e smaltimento

Valutazione Multi-Dimensionale

Dimensione	Unita	Base di Calcolo
Clima	kg CO₂eq	Protocollo GHG, fattori IPCC
Acqua	litri	Impronta idrica blu
Foresta Pluviale	m²	Valutazione del rischio di deforestazione
Benessere Animale	valutazione	Condizioni di allevamento

Passo 5: Generazione dell'Output

I risultati finali sono strutturati per la risposta API.

Formato di Output Standard

L'API restituisce un oggetto Calculation con i risultati del calcolo:

{
  "uid": "calc-123e4567-e89b-12d3-a456-426614174000",
  "success": true,
  "statuscode": 200,
  "message": null,
  "final_root": {
    "activity": {
      "name": "Pollo al Curry con Riso",
      "props": {
        "climate_impact": {
          "value": 2340,
          "unit": "g CO₂eq"
        },
        "water_footprint": {
          "value": 450,
          "unit": "L"
        },
        "daily_food_unit": {
          "value": 0.85
        }
      }
    },
    "sub_flows": [
      {
        "flow": { "name": "Petto di pollo", "amount": 150, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 1521 } } }
      },
      {
        "flow": { "name": "Riso basmati", "amount": 200, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 468 } } }
      }
    ]
  },
  "data_errors": [],
  "created_at": 1705934400.0
}

Struttura della Risposta API

La risposta API effettiva include campi aggiuntivi per opzioni di configurazione, log delle mutazioni e proprieta dettagliate dei nodi. Consulta la documentazione di riferimento dell'API v2 per lo schema completo.

Il Pattern Factory/Worker

Ogni GFM segue un pattern Factory/Worker dove:

• Factory (Singleton): Inizializzato una volta per servizio API, mantiene connessioni al database e cache
• Worker (Per Nodo): Creato per ogni nodo, implementa la logica di calcolo

Per informazioni dettagliate sull'architettura Factory/Worker, inclusi esempi di codice e strategie di caching, consulta l'Approfondimento Tecnico.

Prossimi Passi

• Gap Filling Module - Approfondimento sul sistema modulare
• Catalogo Moduli - Riferimento dei moduli disponibili
• GFM SDK (in arrivo) - Costruisci moduli personalizzati