Funktionsweise von EOS Core

Diese Anleitung führt durch den vollständigen Berechnungsprozess, von rohen Produktdaten bis zu den endgültigen Umweltauswirkungsbewertungen.

Der Berechnungsgraph

EOS Core verwendet eine Berechnungsgraph-Architektur, bei der Produkte und Zutaten als Knoten mit Beziehungen dargestellt werden. Gap Filling Modules (GFMs) operieren auf diesen Knoten, um fehlende Daten zu ergänzen und Auswirkungen zu berechnen.

Schritt 1: Eingabeverarbeitung

Akzeptierte Eingabeformate

Die Engine akzeptiert Produktdaten mit unterschiedlichem Detaillierungsgrad:

// Minimale Eingabe - nur ein Produktname
{
  "name": "Hähnchen-Curry mit Reis"
}

// Strukturierte Eingabe mit Zutaten
{
  "name": "Hähnchen-Curry mit Reis",
  "ingredients": [
    { "name": "Hähnchenbrust", "amount": 150, "unit": "g" },
    { "name": "Basmatireis", "amount": 200, "unit": "g" },
    { "name": "Kokosmilch", "amount": 100, "unit": "ml" },
    { "name": "Currypaste", "amount": 30, "unit": "g" }
  ],
  "servings": 1
}

Graph-Knoten-Erstellung

Jedes Produkt und jede Zutat wird zu einem Knoten im Berechnungsgraph:

Produktknoten: "Hähnchen-Curry mit Reis"
├── Flussknoten: Hähnchenbrust (150g)
├── Flussknoten: Basmatireis (200g)
├── Flussknoten: Kokosmilch (100ml)
└── Flussknoten: Currypaste (30g)

Schritt 2: Gap Filling Module-Planung

Der Orchestrator koordiniert, welche GFMs auf welchen Knoten ausgeführt werden sollen.

Planungslogik

Jedes GFM implementiert zwei Schlüsselmethoden:

• should_be_scheduled() - Bestimmt, ob dieses Modul für einen Knoten relevant ist
• can_run_now() - Prüft, ob alle Abhängigkeiten erfüllt sind

Orchestrator-Schleife:
1. Alle GFMs sammeln, die should_be_scheduled() auf neuen Knoten erfüllen
2. Für jedes geplante GFM:
   - can_run_now() prüfen
   - Wenn bereit: run() ausführen
   - Wenn wartend: Für nächste Iteration neu planen
3. Wiederholen, bis keine GFMs mehr ausgeführt werden müssen

Verfügbare Gap Filling Modules

EOS Core enthält Module für verschiedene Berechnungsaspekte:

Modul	Zweck
match_product_name_gfm	Produktnamen mit Datenbankeinträgen abgleichen
origin_gfm	Geografische Herkunft bestimmen
location_gfm	Standortspezifische Faktoren verarbeiten
greenhouse_gfm	Treibhausgasemissionen berechnen
water_scarcity_gfm	Wasserfußabdruck berechnen
rainforest_gfm	Entwaldungsauswirkungen bewerten
processing_gfm	Auswirkungen der Lebensmittelverarbeitung modellieren
transportation_decision_gfm	Transportmodi bestimmen
transportation_mode_distance_gfm	Transportentfernungen berechnen
impact_assessment_gfm	Auswirkungsberechnungen aggregieren

Schritt 3: Modul-Ausführung

Wenn ein GFM ausgeführt wird, liest es Knoteneigenschaften, führt Berechnungen durch und schreibt Ergebnisse zurück in den Graphen.

Beispiel eines Ausführungsablaufs

Produkt: "Bio-Apfel aus der Schweiz"

1. match_product_name_gfm
   → Abgleich mit Datenbankeintrag "Apfel"
   → Setzt Kategorie und FoodEx2-Begriffe

2. origin_gfm
   → Erkennt "Schweiz" im Namen
   → Setzt Herkunftsland: CH

3. transportation_decision_gfm
   → Bestimmt Transport von Herkunft zum Verbrauchsort
   → Setzt Transportmodi basierend auf Verderblichkeit

4. transportation_mode_distance_gfm
   → Berechnet Entfernungen über EcoTransit API
   → Fügt Transportemissionen zum Graphen hinzu

5. matrix_calculation_gfm
   → Führt matrixbasierte LCA-Berechnungen durch
   → Aggregiert alle Inventardaten

6. impact_assessment_gfm
   → Berechnet CO₂eq nach IPCC-Methodik
   → Generiert Klimaauswirkungsbewertungen

7. water_scarcity_gfm
   → Wendet regionale Wasserstressfaktoren an
   → Berechnet Wasserfußabdruck

8. aggregation_gfm
   → Kombiniert Ergebnisse aller Zutaten
   → Erzeugt endgültige Produktbewertungen

Parallele Ausführung

Unabhängige Module können parallel ausgeführt werden, wenn ihre Abhängigkeiten erfüllt sind:

Schritt 4: Auswirkungsberechnung

Auswirkungsmodule aggregieren Daten aus allen Quellen zu Umweltmetriken.

Matrixberechnung

Vor der Auswirkungsbewertung führt das matrix_calculation_gfm matrixbasierte Life Cycle Assessment-Berechnungen für komplexe Produktsysteme durch. Dies ist eine leistungskritische Komponente, die:

• Den Berechnungsgraph in eine Matrixdarstellung konvertiert
• Die LCA-Gleichung (h = B × A⁻¹ × f) effizient löst
• Flüsse über komplexe Produktgraphen aggregiert

Klimaauswirkungskomponenten

Die Treibhausgasberechnung berücksichtigt:

• Landwirtschaftliche Emissionen - Anbau und Landnutzung
• Verarbeitungsemissionen - Energieverbrauch bei der Lebensmittelverarbeitung
• Transportemissionen - Entfernung × Transportmodus-Emissionsfaktor
• Verpackungsemissionen - Materialproduktion und -entsorgung

Mehrdimensionale Bewertung

Dimension	Einheit	Berechnungsgrundlage
Klima	kg CO₂eq	GHG-Protokoll, IPCC-Faktoren
Wasser	Liter	Blauwasser-Fußabdruck
Regenwald	m²	Entwaldungsrisikobewertung
Tierwohl	Bewertung	Haltungsbedingungen

Schritt 5: Ausgabegenerierung

Endergebnisse werden für die API-Antwort strukturiert.

Standard-Ausgabeformat

Die API gibt ein Calculation-Objekt mit den Berechnungsergebnissen zurück:

{
  "uid": "calc-123e4567-e89b-12d3-a456-426614174000",
  "success": true,
  "statuscode": 200,
  "message": null,
  "final_root": {
    "activity": {
      "name": "Hähnchen-Curry mit Reis",
      "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": "Hähnchenbrust", "amount": 150, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 1521 } } }
      },
      {
        "flow": { "name": "Basmatireis", "amount": 200, "unit": "g" },
        "activity": { "props": { "climate_impact": { "value": 468 } } }
      }
    ]
  },
  "data_errors": [],
  "created_at": 1705934400.0
}

API-Antwortstruktur

Die tatsächliche API-Antwort enthält zusätzliche Felder für Konfigurationsoptionen, Mutationsprotokolle und detaillierte Knoteneigenschaften. Siehe die API v2 Referenzdokumentation für das vollständige Schema.

Das Factory/Worker-Muster

Jedes GFM folgt einem Factory/Worker-Muster, bei dem:

• Factory (Singleton): Einmal pro API-Service initialisiert, hält Datenbankverbindungen und Caches
• Worker (Pro Knoten): Für jeden Knoten erstellt, implementiert die Berechnungslogik

Für detaillierte Informationen zur Factory/Worker-Architektur, einschließlich Codebeispielen und Caching-Strategien, siehe die Technische Vertiefung.

Nächste Schritte

• Gap Filling Modules - Vertiefung in das Modulsystem
• Modulkatalog - Referenz verfügbarer Module
• GFM SDK (in Kürze) - Eigene Module erstellen