Fonctionnement du EOS Core

Ce guide parcourt le processus de calcul complet, des donnees brutes du produit aux scores d'incidence environnementale finaux.

Le graphe de calcul

Le EOS Core utilise une architecture de graphe de calcul ou les produits et ingredients sont representes comme des noeuds avec des relations. Les Gap Filling Modules (GFM) operent sur ces noeuds pour combler les donnees manquantes et calculer les incidences.

Etape 1 : Traitement des entrees

Formats d'entree acceptes

Le moteur accepte des donnees produit avec differents niveaux de detail :

// Entree minimale - juste un nom de produit
{
  "name": "Curry de poulet avec riz"
}

// Entree structuree avec ingredients
{
  "name": "Curry de poulet avec riz",
  "ingredients": [
    { "name": "Blanc de poulet", "amount": 150, "unit": "g" },
    { "name": "Riz basmati", "amount": 200, "unit": "g" },
    { "name": "Lait de coco", "amount": 100, "unit": "ml" },
    { "name": "Pate de curry", "amount": 30, "unit": "g" }
  ],
  "servings": 1
}

Creation des noeuds du graphe

Chaque produit et ingredient devient un noeud dans le graphe de calcul :

Noeud produit : "Curry de poulet avec riz"
├── Noeud de flux : Blanc de poulet (150g)
├── Noeud de flux : Riz basmati (200g)
├── Noeud de flux : Lait de coco (100ml)
└── Noeud de flux : Pate de curry (30g)

Etape 2 : Planification des Gap Filling Modules

L'orchestrateur coordonne quels GFM doivent s'executer sur quels noeuds.

Logique de planification

Chaque GFM implemente deux methodes cles :

• should_be_scheduled() - Determine si ce module est pertinent pour un noeud
• can_run_now() - Verifie si toutes les dependances sont satisfaites

Boucle de l'orchestrateur :
1. Collecter tous les GFM qui should_be_scheduled() sur les nouveaux noeuds
2. Pour chaque GFM planifie :
   - Verifier can_run_now()
   - Si pret : executer run()
   - Si en attente : replanifier pour la prochaine iteration
3. Repeter jusqu'a ce qu'aucun GFM ne doive s'executer

Gap Filling Modules disponibles

Le EOS Core inclut des modules pour differents aspects du calcul :

Module	Objectif
match_product_name_gfm	Faire correspondre les noms de produits aux entrees de la base de donnees
origin_gfm	Determiner l'origine geographique
location_gfm	Gerer les facteurs specifiques a la localisation
greenhouse_gfm	Calculer les emissions de gaz a effet de serre
water_scarcity_gfm	Calculer l'empreinte hydrique
rainforest_gfm	Evaluer l'incidence sur la deforestation
processing_gfm	Modeliser les incidences de la transformation alimentaire
transportation_decision_gfm	Determiner les modes de transport
transportation_mode_distance_gfm	Calculer les distances de transport
impact_assessment_gfm	Agreger les calculs d'incidence

Etape 3 : Execution des modules

Lorsqu'un GFM s'execute, il lit les proprietes du noeud, effectue des calculs et ecrit les resultats dans le graphe.

Exemple de flux d'execution

Produit : "Pomme bio de Suisse"

1. match_product_name_gfm
   → Correspond a l'entree de base de donnees "pomme"
   → Definit la categorie et les termes FoodEx2

2. origin_gfm
   → Detecte "Suisse" dans le nom
   → Definit le pays d'origine : CH

3. transportation_decision_gfm
   → Determine le transport de l'origine a la consommation
   → Definit les modes de transport selon la perissabilite

4. transportation_mode_distance_gfm
   → Calcule les distances via l'API EcoTransit
   → Ajoute les emissions de transport au graphe

5. matrix_calculation_gfm
   → Effectue les calculs ACV bases sur des matrices
   → Agrege toutes les donnees d'inventaire

6. impact_assessment_gfm
   → Calcule le CO₂eq selon la methodologie du GIEC
   → Genere les scores d'incidence climatique

7. water_scarcity_gfm
   → Applique les facteurs de stress hydrique regionaux
   → Calcule l'empreinte hydrique

8. aggregation_gfm
   → Combine les resultats de tous les ingredients
   → Produit les scores finaux au niveau du produit

Execution parallele

Les modules independants peuvent s'executer en parallele lorsque leurs dependances sont satisfaites :

Etape 4 : Calcul de l'incidence

Les modules d'incidence agregent les donnees de toutes les sources en metriques environnementales.

Calcul matriciel

Avant l'evaluation de l'incidence, le matrix_calculation_gfm effectue des calculs d'Analyse du Cycle de Vie bases sur des matrices pour les systemes de produits complexes. C'est un composant de performance critique qui :

• Convertit le graphe de calcul en representation matricielle
• Resout l'equation ACV (h = B × A⁻¹ × f) efficacement
• Agrege les flux a travers les graphes de produits complexes

Composants de l'incidence climatique

Le calcul des gaz a effet de serre prend en compte :

• Emissions agricoles - Agriculture et utilisation des sols
• Emissions de transformation - Energie utilisee dans la transformation alimentaire
• Emissions de transport - Distance × facteur d'emission du mode
• Emissions d'emballage - Production et elimination des materiaux

Evaluation multidimensionnelle

Dimension	Unite	Base de calcul
Climat	kg CO₂eq	Protocole GES, facteurs du GIEC
Eau	litres	Empreinte hydrique bleue
Foret tropicale	m²	Evaluation du risque de deforestation
Bien-etre animal	notation	Conditions d'elevage

Etape 5 : Generation de la sortie

Les resultats finaux sont structures pour la reponse de l'API.

Format de sortie standard

L'API retourne un objet Calculation avec les resultats du calcul :

{
  "uid": "calc-123e4567-e89b-12d3-a456-426614174000",
  "success": true,
  "statuscode": 200,
  "message": null,
  "final_root": {
    "activity": {
      "name": "Curry de poulet avec riz",
      "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": "Blanc de poulet", "amount": 150, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 1521 } } }
      },
      {
        "flow": { "name": "Riz basmati", "amount": 200, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 468 } } }
      }
    ]
  },
  "data_errors": [],
  "created_at": 1705934400.0
}

Structure de la reponse API

La reponse API reelle inclut des champs supplementaires pour les options de configuration, les journaux de mutations et les proprietes detaillees des noeuds. Consultez la documentation de reference de l'API v2 pour le schema complet.

Le patron Factory/Worker

Chaque GFM suit un patron Factory/Worker ou :

• Factory (Singleton) : Initialise une fois par service API, detient les connexions a la base de donnees et les caches
• Worker (Par noeud) : Cree pour chaque noeud, implemente la logique de calcul

Pour des informations detaillees sur l'architecture Factory/Worker, y compris des exemples de code et des strategies de mise en cache, consultez l'Approfondissement technique.

Prochaines etapes

• Gap Filling Modules - Approfondissement du systeme de modules
• Catalogue des modules - Reference des modules disponibles
• SDK GFM (bientot disponible) - Construire des modules personnalises