Cernion Grid Intelligence

87+ herramientas especializadas para datos energéticos alemanes y europeos. Acceso directo de IA al Marktstammdatenregister (MaStR), ENTSO-E, Redispatch 2.0 y Operaciones de Red para empresas de servicios públicos y centros de datos.

GitHub

Documentación

Cernion Energy Tools

Capa de operaciones energéticas agénticas API-first para Stadtwerke, operadores de sistemas de distribución y equipos de servicios energéticos. Cernion combina servicios deterministas del dominio energético, enrutamiento de capacidades curado, expedientes de evidencia, lógica de roles VDMI, límites HITL y superficies de integración de solo lectura para REST, Sidecar, Microsoft Copilot, n8n, OpenWebUI y OpenClaw.

Qué Es Este Repositorio

Cernion Energy Tools es el runtime backend detrás de cernion.de: una plataforma de servicios Node.js/Moleculer para automatización del dominio energético, soporte a decisiones y orquestación de procesos agénticos.

No es solo un frontend de chat para APIs energéticas. La plataforma actual contiene:

138 servicios Moleculer en services/
1007 rutas OpenAPI en openapi-export.json
304 archivos de prueba JavaScript bajo tests/
superficies de integración curadas para Copilot, Sidecar, OpenWebUI, n8n y OpenClaw que exponen solo subconjuntos gobernados del backend
componentes de runtime agénticos para enrutamiento, recibos, expedientes, HITL, evidencia, revalidación y observabilidad
archivos de proyecto durables con ingesta por inquilino, tablas estructuradas, un grafo de relaciones respaldado por evidencia y manifiestos de enrutamiento versionados con selección de fuente visible; consulte Projektakte para APIs, procedencia, límites y limpieza

Versión actual del paquete/OpenAPI: 0.99.0

Posicionamiento público

Cernion no deja que el chat decida. La plataforma estructura el objetivo, los datos disponibles, la cadena de servicios, la evidencia, las brechas, el riesgo y el siguiente punto de control seguro. El resultado no es una respuesta de caja negra, sino una vista de estado lista para expediente o de preparación para decisión para Stadtwerke, operadores de sistemas de distribución y equipos de servicios energéticos.

Cernion Energy Tools no es una decisión contractual automática, un compromiso de conexión a la red, un sistema de control de dispositivos, un sistema de ejecución MaKo, un sistema de facturación/liquidación ni una máquina de mutación tarifaria. Los alcances de integración adecuados son ask, plan, evidence, capability lookup y read-only status. Los pasos de tipo escritura o consecuentes permanecen en estados draft, prepare o pending confirmation y requieren HITL.

El sitio web público explica Cernion como una plataforma de inteligencia energética y decisiones para Stadtwerke: análisis MaStR, planificación de red, §14a, Redispatch, Energy Sharing, automatización de servicio al cliente y complementariedad con Microsoft Copilot. Este repositorio es el sistema técnico más profundo que sustenta esa narrativa de producto.

Enlaces públicos de descubrimiento

Centro de productos y temas: Cernion Themencluster
Resumen de capacidades: Cernion Capability Hub
Integración de API y agentes: MCP Tools & API y REST API
Páginas operativas de intención de búsqueda:

Por Qué Cernion Es Agéntico

Cernion es API-first, pero la API es solo la capa de integración. La parte agéntica es el comportamiento del runtime:

Comprender un objetivo del dominio energético Ejemplos: validar un escenario de conexión a la red, construir una matriz de responsabilidades VDMI, evaluar el riesgo financiero de BESS, identificar conflictos de datos en Energy Sharing.
Seleccionar una ruta de capacidad gobernada El capability-broker asigna la intención a cadenas de servicios curadas en lugar de exponer el catálogo completo de herramientas a un LLM.
Ejecutar microservicios deterministas Los cálculos del dominio energético y las verificaciones regulatorias permanecen respaldados por código y reproducibles.
Mantener el estado del proceso Las sesiones de agentes personales, recibos, expedientes, elementos HITL y evidencia en el almacén de objetos permiten que el trabajo continúe más allá de un solo turno de chat.
Producir artefactos auditables Las salidas no son solo respuestas en lenguaje natural; incluyen expedientes, paquetes de evidencia, marcos de decisión, informes de validación, recibos y trazas.
Gobernar la revalidación Los hechos nuevos pueden convertirse en señales de control para los agentes: si un activo MaStR, un punto de datos o un elemento de evidencia en el almacén de objetos cambia, las decisiones dependientes pueden identificarse y verificarse nuevamente.

Esta es la diferencia práctica entre un bot de preguntas y respuestas y una plataforma agéntica de operaciones energéticas.

Arquitectura Principal

External systems / humans / agents
        |
        v
REST API, Copilot API, OpenClaw Sidecar, MCP-like tool surfaces
        |
        v
Personal Agent / Capability Broker / Agent Receipts / Blueprints
        |
        v
Governed Moleculer services
        |
        v
Datapoints, Object Store, Knowledge RAG, Dossiers, Jobs, Observability

Capas del Runtime

Capa	Componentes	Propósito
Bus de servicios	Moleculer, puerta de enlace REST, trabajos asíncronos	Ejecución determinista de servicios y exposición de API
Capa de datos	Object Store, Datapoints, DataSources, Knowledge RAG	Datos internos, evidencia externa, memoria del inquilino y material fuente
Enrutamiento agéntico	Personal Agent, Capability Broker, Blueprints, Agent Receipts	Resolución de intención, selección de cadenas de herramientas, ejecución durable
Gobernanza	VDMI, HITL, Clarification Policy, Interface Placeholder, Evidence Revalidation	Responsabilidades, evidencia faltante, decisiones humanas, manejo de brechas
Integración	OpenAPI completo, subconjunto Copilot, OpenClaw Sidecar, Webhooks, herramientas estilo MCP	Uso seguro por humanos, copilotos, agentes y sistemas de automatización
Observabilidad	Métricas, trazas, registros de auditoría, estado de trabajos	Operación, auditabilidad y soporte

Dominios Principales

La plataforma cubre varias áreas de trabajo de la industria energética. La siguiente lista es representativa; la exportación OpenAPI es la fuente de verdad.

Dominio	Ejemplos
Conexión a la red y fNAV	Validación de conexión a la red, acceso flexible a la red, evidencia de rechazo de conexión
Gobernanza VDMI	Verantwortlich, Durchführend, Mitwirkend, Information por paso de proceso; hallazgos, expedientes y evidencia
Zielnetzplanung (ZNP)	Proyectos, supuestos, activos de Capa 0/1/2, análisis de cartera, decisiones NOVA
Calidad de activos y datos	Calidad MaStR, anulaciones de activos, alertas de activos fantasma, clasificación de fuentes de datos
Energy Sharing y liquidación	Asignación estilo §42c, verificaciones de liquidación, conciliación ex-post de Redispatch
EDM y comunicación de mercado	Importación MSCONS, validación EDM, medidores virtuales, verificaciones de messkonzept
Pronóstico y flexibilidad	Motor de pronóstico, carga residual, eventos de flexibilidad §14a, perfiles SLP
Finanzas e inversión	Agente financiero, economía fNAV, selección BESS, priorización de capex
Reportes y BI	Gobernanza de reportes, API de paneles, monitoreo VNB, monitoreo EWK
Conocimiento y evidencia	Knowledge RAG, enrutamiento de evidencia, expedientes, contexto del almacén de objetos

Componentes Agénticos

Sitemap Agéntico / Catálogo de IA

GET /.well-known/ai-catalog.json y GET /.well-known/ard.json publican un catálogo público generado en cada solicitud a partir del registro de servicios cargado y los metadatos OpenAPI en vivo. Cada servicio REST publicado tiene una entrada con tokens de acción/capacidad, consultas representativas y un contrato OpenAPI en línea. El catálogo también enlaza al documento OpenAPI completo y a llm.txt. Las respuestas raíz anuncian ambas rutas de descubrimiento a través de encabezados HTTP Link; las solicitudes condicionales admiten ETags.

No se necesita mantenimiento manual de JSON ni llamadas a LLM. Las acciones protegidas/privadas, la configuración de servicios y los datos del runtime están excluidos. La visibilidad en el catálogo no otorga permiso para invocar una acción. Consulte detalles de implementación.

Los formatos son borradores: AI Catalog y Agentic Resource Discovery. ARD ahora usa ard.json; el ai-catalog.json solicitado permanece disponible para clientes que usan la ruta predecesora. Las pruebas fuera de línea validan ambos formatos contra esquemas ascendentes fijados; npm run sync:ai-catalog-schemas actualiza esos fixtures desde la revisión fijada en el script de sincronización (Apache-2.0).

Personal Agent

services/personal-agent.service.js es la capa de orquestación orientada al usuario. Mantiene el estado de la conversación, enruta intenciones, llama servicios deterministas y sintetiza resultados sin convertir todo el backend en un solo prompt.

Conceptos clave:

gestión de contexto en capas ("Zwiebelmodus")
estado de ejecución durable y sesiones reanudables
ingesta de archivos y puntos de datos
manejo de brechas de evidencia
eventos de trabajo en voz alta
artefactos finales conscientes de la presentación

Capability Broker

services/capability-broker.service.js y src/capability-catalog.js proporcionan enrutamiento de capacidades curado. Este es el punto de control que evita que los agentes vean o elijan toda la superficie del backend directamente.

Ejemplos de capacidades curadas incluyen:

vdmi_role_boundary_governance
vdmi_asset_validation_governance
vdmi_grid_connection_decision_governance
netzfahrplan_fnav_assessment
znp_portfolio_assessment
settlement_a96_reconciliation
financier_due_diligence_assessment
reporting_governance

Agent Receipts

services/agent-receipts.service.js convierte flujos de trabajo de agentes repetibles en recetas versionadas y comprobables. Los recibos describen condiciones de coincidencia, entradas requeridas, planes de herramientas y planes de conocimiento. Son el puente desde "el agente respondió" hasta "la plataforma seleccionó un flujo de trabajo gobernado e inspeccionable".

Expedientes y Marcos de Decisión

Cernion usa expedientes y marcos de decisión para salidas auditables. Un resultado puede incluir:

hechos utilizados
hipótesis
brechas de evidencia
riesgos
supuestos prohibidos
responsabilidades VDMI
próximas acciones
requisitos de revisión humana

Gobernanza Agéntica y Revalidación

Dos pistas activas de arquitectura están capturadas en issues de GitHub:

La dirección objetivo es que un hecho cambiado pueda convertirse en una señal de control para los agentes:

MaStR / datapoint / object-store change
        |
        v
Dependency and impact analysis
        |
        v
Revalidation queue
        |
        v
Agent receipt / capability flow rerun
        |
        v
Audit note, updated dossier, HITL item or exception case

Así es como Cernion avanza desde el análisis de API de una sola vez hacia RPA+ para procesos energéticos de productos básicos: los casos estándar se automatizan, las excepciones se hacen explícitas.

Superficies de Integración

API REST Completa

La API REST completa se genera a partir de los metadatos de los servicios Moleculer.

Swagger UI: GET /api/docs
OpenAPI JSON: GET /api/openapi.json
Exportación estática: openapi-export.json
Recetas de API públicas para descubrimiento por desarrolladores y LLM: docs/public-api-recipes.md

Las recetas usan solo ejemplos sintéticos, tokens basados en variables de entorno e identificadores de demostración seguros para el inquilino. Documentan los límites de consulta/solo lectura/confirmación pendiente y no son demostraciones de aprobación, facturación, tarifas, control de dispositivos, contratos o mutaciones de producción.

Regenerar y auditar:

npm run export:openapi
npm run audit:openapi

Puente Microsoft Copilot

Cernion no expone las más de 600 rutas de API a Microsoft Copilot. El puente de Copilot usa una lista de permitidos curada mantenida en config/copilot-operations.json.

Archivos relevantes:

Generar el subconjunto de Copilot:

npm run export:openapi:copilot

La superficie orientada a Copilot distingue:

operaciones read sin efectos secundarios
operaciones draft que preparan sugerencias
operaciones prepare que requieren confirmación
operaciones consecuentes que permanecen bloqueadas hasta que se gobiernen explícitamente

OpenClaw Sidecar

Cernion Energy Tools se puede usar desde OpenClaw a través del paquete público de ClawHub @cernion/openclaw-energy-tools-sidecar. Instálelo en OpenClaw con:

openclaw plugins install clawhub:@cernion/openclaw-energy-tools-sidecar

El repositorio complementario SmartEnergySolutions/cernion-openclaw-sidecar proporciona un plugin de OpenClaw para proveedores genéricos de Energy Sidecar, con Cernion como primer proveedor.

El límite del producto está dividido intencionalmente: OpenClaw es el runtime de agente para conversación, orquestación de herramientas, memoria y síntesis de respuestas. Cernion Energy Tools es la capa de procesos de evidencia, políticas, Knowledge RAG y gobernanza CET del dominio energético detrás de las respuestas sobre activos MaStR, contexto de red, Redispatch, Zielnetzplanung, obligaciones 14a/14d EnWG, ingesta de procesos, estado de casos del Domain Router, Case Event Outbox/MWI y estado operativo.

El sidecar consume el contrato de Cernion Sidecar:

GET /api/agent-sidecar/descriptor
GET /api/agent-sidecar/mcp/tools
POST /api/agent-sidecar/mcp/tools/:name/call
POST /api/knowledge-rag/query
POST /api/evidence-router/route
POST /api/copilot-process/intents
GET /api/_agent/capabilities[?domain=]
GET /api/_agent/operations[?domain=]

El límite es deliberadamente estricto:

Los tokens sidecar identifican el contexto de tenant, actor y cliente; la autorización/gobernanza de CET es el límite de permisos.
Las herramientas de Domain Router y MWI pueden actualizar el estado interno de PouchDB de CET, como el estado de casos, el estado de entrega de eventos y los enlaces de sesiones relacionadas.
Las búsquedas de evidence/hydration y los planes de Blueprint permanecen de solo lectura cuando esa es la operación real.
La ingesta de procesos utiliza un token de proceso separado y crea únicamente recibos pending_confirmation
Las rutas de administración, token, resolución HITL y mutación de producción están bloqueadas
El enrutamiento de dominio permanece dentro de Cernion, no dentro del sidecar

Herramientas estilo MCP

Cernion también publica descripciones de herramientas compatibles con agentes de IA a través de llm.txt, endpoints de resolución de capacidades y listas de herramientas estilo MCP/OpenClaw. La página de documentación pública describe esto como un conjunto de herramientas energéticas listas para usar para Stadtwerke.

Inicio rápido

Requisito previo: Node.js 22+

git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools
npm install
cp .env.example .env
npm start

Endpoints locales predeterminados:

API: http://localhost:3000/api
Swagger UI: http://localhost:3000/api/docs
Aplicación web: http://localhost:3000/app

Guía de configuración completa: QUICKSTART.md

Configuración

Comience con .env.example. Variables comunes:

Variable	Propósito
`CERNION_TOKEN`	Token de API para acceso autenticado
`LLM_PROVIDER`	Proveedor de LLM (`gemini`, `openai-compat`, `ollama`)
`LLM_MODEL`	Nombre del modelo para el proveedor seleccionado
`LLM_API_KEY` / `GEMINI_API_KEY`	Credenciales del proveedor cuando sean necesarias
`API_URL`	URL base utilizada en los servidores OpenAPI generados y enlaces de compartir CLI
`PORT`	Puerto de la puerta de enlace API, predeterminado `3000`
`TRACING_ENABLED`	Habilitar el rastreo de OpenTelemetry
`OTEL_EXPORTER_OTLP_ENDPOINT`	Destino de rastreo HTTP OTLP
`METRICS_PUBLIC`	Exponer `/metrics` sin un token de acceso completo

Salud de LLM:

GET /api/system/llm/health

Observabilidad:

GET /metrics devuelve métricas compatibles con Prometheus
Ejemplos de Grafana: docs/observability/grafana/README.md

Guía de autenticación: BEARER_TOKEN_AUTHENTICATION.md

Desarrollo

npm test
npm run test:unit:ci
npm run test:tdd-matrix
npm run test:rest-usecases
npm run lint
npm run audit:openapi
npm run check:llm
npm run release:check
npm run release:gate

El runbook „Release-Gate ausführen“ describe la evaluación práctica con escenarios sintéticos de múltiples turnos, rúbrica y ejecuciones repetidas contra una instancia de prueba local o HTTP. release:gate complementa las comprobaciones del repositorio con esta aceptación.

Comandos de generación útiles:

npm run export:openapi
npm run export:openapi:copilot
npm run generate:llm
npm run blueprint:export

Crear un nuevo servicio de Moleculer:

npm run create

Demostración de Cernion

Las buenas demostraciones deberían mostrar una ejecución agéntica, no solo una respuesta de chat.

Patrones de demostración sólidos:

VDMI: generar una matriz de responsabilidades por paso del proceso y detectar violaciones de límites de roles
BESS: evaluar un sitio en cuanto a conexión a la red, riesgos, supuestos de ingresos y evidencia del financiador
Energy Sharing: identificar conflictos de MaLo/MeLo, EDM y liquidación que bloquean el proceso
MaStR/Revalidación: mostrar cómo una actualización de activos externa puede desencadenar la revalidación de decisiones dependientes
Copilot/Sidecar: mostrar a Cernion como el backend de dominio energético gobernado detrás de un agente de propósito general

Un rastro agéntico útil debería hacer visibles estos elementos:

User objective
  -> intent and capability
  -> selected receipt / blueprint
  -> service chain
  -> evidence used
  -> gaps and risks
  -> HITL / policy decision
  -> dossier or decision artifact
  -> audit trace

Mapa de documentación

Documento	Tema
docs/copilot-process-bridge.md	Subconjunto curado de la API de Microsoft Copilot
docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md	Arquitectura del agente personal y contrato TDD
docs/v0.52-implementation-plans/v0.52.1-capability-broker.md	Plan de implementación del Capability Broker
docs/observability/grafana/README.md	Paneles de Grafana
docs/DSFA_TEMPLATE.md	Plantilla de evaluación de impacto en la protección de datos
docs/BACKEND_CONTEXT.md	Contexto de backend para trabajo de UI/frontend
CHANGELOG.md	Historial de versiones
MCP_TOOLS.md	Referencia de MCP/herramientas
docs/SHARED_SERVICE_JOURNAL.md	Shared Service Journal de solo anexión de RC3, resúmenes deterministas y retención
docs/domain-router.md	CET Domain Router, vinculación de casos tipificada, visibilidad own/team/tenant y Case Event Outbox / MWI
docs/tenant-memory.md	Memoria de tenant: declaraciones, anclas comunes, fuentes, corrección y avisos únicos
docs/open-webui-tenant-gateway.md	Acceso al Tenant-Gateway de RC3 Open WebUI / Cernion Workbench sin AgentOS
llm.txt	Contexto de servicio y capacidades legible por máquina
SECURITY.md	Política de seguridad

Licencia y contexto del operador

Licencia: GPL-3.0. Ver LICENSE.

Cernion es desarrollado por STROMDAO GmbH en el contexto de la plataforma de inteligencia energética Cernion.

Soporte y comentarios sobre el producto:

GitHub Issues
dev@stromdao.com

Workbench: comprender, responder, caso en segundo plano

Los mensajes de contenido y los textos externos insertados se traducen a una imagen de situación a través de la fachada central de LLM. CET responde con fuentes relevantes y como máximo tres preguntas técnicas nuevas. Las tareas de trabajo concretas reciben un caso en segundo plano; „Kein Fall“ lo retira. Las preguntas de conocimiento y estado no generan un caso. Las solicitudes de envío conducen a un aviso y, si se solicita explícitamente, a un borrador interno. La asignación de fuentes y el umbral de relevancia están configurados en src/workbench-knowledge-sources.json. Los detalles y límites se encuentran en la Guía del Tenant-Gateway y en el Informe de aceptación para #739.

CET registra declaraciones relevantes para la organización a nivel de tenant y las confirma una vez con „Hab ich festgehalten: …“. Anclas comunes poco frecuentes conectan declaraciones de diferentes personas; las interacciones detectadas aparecen en la conversación y una vez en el próximo contacto de la otra persona. La separación de tenants y los niveles de confidencialidad se aplican en cada acceso. Los detalles se encuentran en la Guía de memoria de tenant.

Catálogo de datos de tenant

Las tablas de texto CSV/XLSX completas de Open WebUI se almacenan a nivel de tenant como datos de usuario y se evalúan de forma determinista mediante dataset.query. El mismo contenido no genera otra versión ni confirmación incluso si los archivos adjuntos se envían nuevamente. Configuración, límites y ejemplos: Catálogo de datos de tenant. Mensajes estructurados y EDIFACT: Formatos, comprobaciones y consultas.

Archivos originales en el chat (#790)

Instalación del filtro versionado de Open WebUI, descargas firmadas, límites de archivos y retención: Runbook. Sin el filtro instalado, se mantiene la ruta de texto de documentos anterior.

Hotfix RC3 para correo y entrada de documentos (#846)

El reconocimiento de tablas requiere un encabezado con al menos dos columnas y al menos dos filas de datos del mismo ancho. WORKBENCH_DATASET_MIN_TABLE_RATIO determina la proporción requerida dentro del bloque de tabla (estándar 0.75, válido: mayor que 0.5 hasta 1). Los errores de análisis comunes se degradan a texto; el bloqueo de plausibilidad para tablas realmente reconocidas permanece activo. Los presupuestos de archivos, líneas y columnas siguen aplicándose. Solo el patrón de descomposición inequívoco y no reconstruible sin pérdidas de Open WebUI utiliza WORKBENCH_DATASET_DAMAGED.

Regenerar los fixtures sintéticos y verificar las regresiones localmente:

node scripts/generate-conversation-fixtures.js
node scripts/generate-review-fixture.js
node scripts/generate-dataset-fixtures.js
npm test -- --runInBand tests/workbench-846.test.js tests/workbench-838.test.js

El script en vivo existente verifica adicionalmente la ingesta de correo (1), el resumen de protocolo (3), el historial de correo junto a un registro INVOIC externo (5) y el mensaje mencionado explícitamente (6). Inicia un broker local con bases de datos temporales aisladas y un tenant de validación sintético. Todas las llamadas al modelo de lenguaje se ejecutan a través de la fachada central y el presupuesto de llamadas/tokens existente. Iniciar exclusivamente con una configuración de no producción:

WORKBENCH_ENV_FILE=/path/to/nonproduction.env \
  WORKBENCH_VALIDATION_REPORT=/tmp/rc3-hotfix-846-live.json \
  LIVE_MAX_MODEL_CALLS=80 LIVE_MAX_TOKENS=1000000 \
  node scripts/validate-rc3-closeout-live.js

La extensión no se ejecutó en vivo. Un informe en vivo solo puede usarse como evidencia de aceptación después de una ejecución separada de no producción.