Fonctionnement du EOS Core

Ce guide parcourt le processus de calcul complet, des données 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 ingrédients sont representes comme des noeuds avec des relations. Les Gap Filling Modules (GFM) operent sur ces noeuds pour combler les données manquantes et calculer les incidences.

Étape 1 : Traitement des entrées

Formats d'entrée acceptés

Le moteur accepte des données produit avec différents niveaux de détail :

// 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
}

Création des noeuds du graphe

Chaque produit et ingrédient 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)

Étape 2 : Planification des Gap Filling Modules

L'orchestrateur coordonne quels GFM doivent s'exécuter sur quels noeuds.

Logique de planification

Chaque GFM implémente deux méthodes clés :

• should_be_scheduled() - Determine si ce module est pertinent pour un noeud
• can_run_now() - Vérifie si toutes les dépendances 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 différents aspects du calcul :

Module	Objectif
match_product_name_gfm	Faire correspondre les noms de produits aux entrées de la base de données
origin_gfm	Déterminer l'origine géographique
location_gfm	Gérer les facteurs spécifiques à la localisation
greenhouse_gfm	Calculer les émissions de gaz à effet de serre
water_scarcity_gfm	Calculer l'empreinte hydrique
rainforest_gfm	Évaluer l'incidence sur la déforestation
processing_gfm	Modeliser les incidences de la transformation alimentaire
transportation_decision_gfm	Déterminer les modes de transport
transportation_mode_distance_gfm	Calculer les distances de transport
impact_assessment_gfm	Agreger les calculs d'incidence

Étape 3 : Exécution des modules

Lorsqu'un GFM s'exécute, il lit les propriétés du noeud, effectué des calculs et ecrit les résultats dans le graphe.

Exemple de flux d'exécution

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

Exécution parallele

Les modules indépendants peuvent s'exécuter en parallele lorsque leurs dépendances sont satisfaites :

Étape 4 : Calcul de l'incidence

Les modules d'incidence agrègent les données de toutes les sources en métriques environnementales.

Calcul matriciel

Avant l'évaluation de l'incidence, le matrix_calculation_gfm effectué des calculs d'Analyse du Cycle de Vie bases sur des matrices pour les systèmes de produits complexes. C'est un composant de performance critique qui :

• Convertit le graphe de calcul en représentation matricielle
• Résout l'équation ACV (h = B × A⁻¹ × f) efficacement
• Agrege les flux à travers les graphes de produits complexes

Composants de l'incidence climatique

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

• Émissions agricoles - Agriculture et utilisation des sols
• Émissions de transformation - Énergie utilisée dans la transformation alimentaire
• Émissions de transport - Distance × facteur d'émission du mode
• Émissions d'emballage - Production et élimination des matériaux

Évaluation multidimensionnelle

Dimension	Unité	Base de calcul
Climat	kg CO₂éq	Protocole GES, facteurs du GIEC
Eau	litres	Empreinte hydrique bleue
Forêt tropicale	m²	Évaluation du risque de déforestation
Bien-être animal	notation	Conditions d'élevage

Étape 5 : Génération de la sortie

Les résultats finaux sont structures pour la réponse de l'API.

Format de sortie standard

L'API retourne un objet Calculation avec les résultats 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 réponse API

La réponse API réelle inclut des champs supplémentaires pour les options de configuration, les journaux de mutations et les propriétés détaillées des noeuds. Consultez la documentation de référence de l'API v2 pour le schéma 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 données et les caches
• Worker (Par noeud) : Crée pour chaque noeud, implémente la logique de calcul

Pour des informations détaillées sur l'architecture Factory/Worker, y compris des exemples de code et des stratégies de mise en cache, consultez l'Approfondissement technique.

Prochaines étapes

• Gap Filling Modules - Approfondissement du système de modules
• Catalogue des modules - Référence des modules disponibles
• SDK GFM (bientot disponible) - Construire des modules personnalisés