Cómo Funciona EOS Core

Esta guía recorre el proceso de cálculo completo, desde datos brutos del producto hasta puntuaciones finales de impacto ambiental.

El Grafo de Cálculo

EOS Core utiliza una arquitectura de grafo de cálculo donde productos e ingredientes se representan como nodos con relaciones. Los Gap Filling Modules (GFMs) operan sobre estos nodos para rellenar datos faltantes y calcular impactos.

Paso 1: Procesamiento de Entrada

Formatos de Entrada Aceptados

El motor acepta datos de productos con niveles variables de detalle:

// Entrada mínima - solo un nombre de producto
{
  "name": "Pollo al Curry con Arroz"
}

// Entrada estructurada con ingredientes
{
  "name": "Pollo al Curry con Arroz",
  "ingredients": [
    { "name": "Pechuga de pollo", "amount": 150, "unit": "g" },
    { "name": "Arroz basmati", "amount": 200, "unit": "g" },
    { "name": "Leche de coco", "amount": 100, "unit": "ml" },
    { "name": "Pasta de curry", "amount": 30, "unit": "g" }
  ],
  "servings": 1
}

Creación de Nodos del Grafo

Cada producto e ingrediente se convierte en un nodo en el grafo de cálculo:

Nodo de Producto: "Pollo al Curry con Arroz"
├── Nodo de Flujo: Pechuga de pollo (150g)
├── Nodo de Flujo: Arroz basmati (200g)
├── Nodo de Flujo: Leche de coco (100ml)
└── Nodo de Flujo: Pasta de curry (30g)

Paso 2: Programación de Gap Filling Modules

El orquestador coordina qué GFMs deben ejecutarse en qué nodos.

Lógica de Programación

Cada GFM implementa dos métodos clave:

• should_be_scheduled() - Determina si este módulo es relevante para un nodo
• can_run_now() - Comprueba si todas las dependencias están satisfechas

Bucle del Orquestador:
1. Recoger todos los GFMs que should_be_scheduled() en nuevos nodos
2. Para cada GFM programado:
   - Comprobar can_run_now()
   - Si listo: ejecutar run()
   - Si esperando: reprogramar para siguiente iteración
3. Repetir hasta que no queden más GFMs por ejecutar

Gap Filling Modules Disponibles

EOS Core incluye módulos para diferentes aspectos del cálculo:

Módulo	Propósito
match_product_name_gfm	Coincidir nombres de productos con entradas de base de datos
origin_gfm	Determinar origen geográfico
location_gfm	Manejar factores específicos de ubicación
greenhouse_gfm	Calcular emisiones de gases de efecto invernadero
water_scarcity_gfm	Calcular huella hídrica
rainforest_gfm	Evaluar impacto de deforestación
processing_gfm	Modelar impactos del procesamiento de alimentos
transportation_decision_gfm	Determinar modos de transporte
transportation_mode_distance_gfm	Calcular distancias de transporte
impact_assessment_gfm	Agregar cálculos de impacto

Paso 3: Ejecución de Módulos

Cuando un GFM se ejecuta, lee propiedades del nodo, realiza cálculos y escribe resultados de vuelta al grafo.

Ejemplo de Flujo de Ejecución

Producto: "Manzana Orgánica de Suiza"

1. match_product_name_gfm
   → Coincide con entrada de base de datos "manzana"
   → Establece categoría y términos FoodEx2

2. origin_gfm
   → Detecta "Suiza" en el nombre
   → Establece país de origen: CH

3. transportation_decision_gfm
   → Determina transporte desde origen a consumo
   → Establece modos de transporte basados en perecibilidad

4. transportation_mode_distance_gfm
   → Calcula distancias usando API EcoTransit
   → Añade emisiones de transporte al grafo

5. matrix_calculation_gfm
   → Realiza cálculos de ACV basados en matrices
   → Agrega todos los datos de inventario

6. impact_assessment_gfm
   → Calcula CO₂eq usando metodología IPCC
   → Genera puntuaciones de impacto climático

7. water_scarcity_gfm
   → Aplica factores regionales de estrés hídrico
   → Calcula huella hídrica

8. aggregation_gfm
   → Combina resultados de todos los ingredientes
   → Produce puntuaciones finales a nivel de producto

Ejecución Paralela

Los módulos independientes pueden ejecutarse en paralelo cuando sus dependencias están satisfechas:

Paso 4: Cálculo de Impacto

Los módulos de impacto agregan datos de todas las fuentes en métricas ambientales.

Cálculo Matricial

Antes de la evaluación de impacto, el matrix_calculation_gfm realiza cálculos de Análisis de Ciclo de Vida basados en matrices para sistemas de productos complejos. Este es un componente crítico de rendimiento que:

• Convierte el grafo de cálculo en representación matricial
• Resuelve la ecuación de ACV (h = B × A⁻¹ × f) eficientemente
• Agrega flujos a través de grafos de productos complejos

Componentes de Impacto Climático

El cálculo de gases de efecto invernadero considera:

• Emisiones agrícolas - Agricultura y uso del suelo
• Emisiones de procesamiento - Energía usada en procesamiento de alimentos
• Emisiones de transporte - Distancia × factor de emisión del modo
• Emisiones de embalaje - Producción y eliminación de materiales

Evaluación Multidimensional

Dimensión	Unidad	Base de Cálculo
Clima	kg CO₂eq	Protocolo GHG, factores IPCC
Agua	litros	Huella hídrica azul
Selva Tropical	m²	Evaluación de riesgo de deforestación
Bienestar Animal	calificación	Condiciones de cría

Paso 5: Generación de Salida

Los resultados finales se estructuran para respuesta de API.

Formato de Salida Estándar

La API devuelve un objeto Calculation con los resultados del cálculo:

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

Estructura de Respuesta de API

La respuesta real de la API incluye campos adicionales para opciones de configuración, registros de mutaciones y propiedades detalladas de nodos. Consulte la documentación de Referencia de API v2 para el esquema completo.

El Patrón Factory/Worker

Cada GFM sigue un patrón Factory/Worker donde:

• Factory (Singleton): Inicializado una vez por servicio de API, mantiene conexiones de base de datos y cachés
• Worker (Por Nodo): Creado para cada nodo, implementa la lógica de cálculo

Para información detallada sobre la arquitectura Factory/Worker, incluyendo ejemplos de código y estrategias de caché, consulte la Inmersión Técnica.

Siguientes Pasos

• Gap Filling Modules - Inmersión profunda en el sistema de módulos
• Catálogo de Módulos - Referencia de módulos disponibles
• GFM SDK (próximamente) - Construir módulos personalizados