Cernion Energy Tools

Sistema de agentes de microservicios para mercados energéticos

Una plataforma de microservicios modular y escalable construida con Moleculer para desarrollar aplicaciones de mercado energético con integración de IA (Google Gemini) y soporte para MCP (Model Context Protocol).

Características

• 🚀 Framework de microservicios Moleculer — Framework de microservicios rápido, moderno y potente

• 🌐 API Gateway — API HTTP REST con generación automática de rutas

• 🤖 Agente de IA — Planificador de consultas en lenguaje natural impulsado por Google Gemini: describa su necesidad de datos energéticos en texto plano y el agente genera, ejecuta e interpreta automáticamente un plan de microservicios de varios pasos

• 🏢 Fuentes de datos internas — Registre, infiera, almacene en caché y descubra conjuntos de datos internos de servicios públicos (CSV, REST, GeoJSON, XLSX, DOCX, Scraper) junto con herramientas energéticas públicas

• 🧩 Aplicación web de investigación — Aplicación de página única integrada en /app para pruebas interactivas basadas en navegador del agente de IA; no se requieren herramientas adicionales

• 📥 Exportación CSV en vivo — Cada resultado del agente expone un endpoint GET parametrizado (/api/agent/session/:id/csv?param=value) para una integración sin configuración con herramientas de automatización como Microsoft Power Automate, Excel Power Query o trabajos cron

• Puntos de datos — Fuentes de datos nombradas, versionadas y con monitoreo de salud respaldadas por PouchDB integrado. Promocione cualquier sesión de agente a un punto de datos gestionado, realice un seguimiento del historial de actualización y la estabilidad del esquema, y recupere datos en vivo como JSON o CSV a través de /api/datapoints. Consulte la descripción general de salud para ver un panel de todos los puntos de datos registrados.- 📸 Instantáneas — Selle un grupo de puntos de datos como una unidad consistente con hash de procedencia SHA-256. Cree, valide (detección de deriva), enumere y elimine instantáneas a través de /api/datapoints/snapshot* (v0.13)

• 🌍 Capa geográfica OSM — Análisis de infraestructura de red a través de OpenStreetMap/Overpass: validación de asignación de VNB, infraestructura cercana, inventario de subestaciones y topología de red (v0.10)

• 🌐 Conector OEP — Acceso de solo lectura a la Open Energy Platform (datos de escenarios, referencias NEP, conjuntos de datos de investigación) a través de /api/oep/* (v0.12)

• 🔌 Validación de conexión a la red — Pipeline determinista de 6 pasos Netzanschluss (POST /api/grid-connection/validate): inventario → delta → capacidad → benchmark EWK → decisión Go/No-Go → pista de auditoría. Sin LLM: entradas idénticas, hallazgos idénticos. Informes sellados con instantáneas de PouchDB para el cumplimiento del Art. 12 de la Ley de IA de la UE (v0.14)

• 🤝 Validación de intercambio de energía — Pipeline determinista de 6 pasos § 42c EnWG (POST /api/energy-sharing/validate): elegibilidad de generador/consumidor, validación MaLo, verificación de suma de acciones, validación DV. Fecha límite regulatoria: 01.06.2026 (v0.15)

• 📊 Auditoría de calidad de datos MaStR — Auditoría de calidad de cartera de 8 pasos (POST /api/mastr-quality/audit): integridad del registro, plausibilidad de capacidad, conectividad NAP/MeLo, detección de duplicados, verificación puntual geográfica. Puntuación ponderada de 0 a 100 en 5 dimensiones (v0.17)

• ⚡ Auditoría ex-post de Redispatch — Auditoría de preparación para la liquidación de Redispatch 2.0 de 7 pasos (POST /api/redispatch/audit): ensamblaje de cartera (Weg A/B), verificaciones NAP/MeLo/DV, datos de reducción, puntuación de riesgo financiero (v0.18)

• 🗂️ API de panel — Agregador de interfaz de usuario de solo lectura con 4 endpoints compuestos (GET /api/dashboard/*): descripción general de VNB, instantánea del mercado, resumen de calidad, referencia de códigos de hallazgo. Todas las llamadas ascendentes en paralelo mediante Promise.allSettled, degradación elegante, caché de 5–15 min (v0.19)

• 🧠 OEO / OEMetadata — Anotaciones de Open Energy Ontology en los más de 45 endpoints REST, exportación OEMetadata v2.0 con validación opcional de JSON Schema (v0.11.4–v0.12)

• 🔐 Procedencia de datos — Hash de procedencia SHA-256 en cada actualización de punto de datos para el cumplimiento del Art. 12 de la Ley de IA de la UE, además de registro de explicabilidad para correcciones del agente (v0.11.5)

• 🧹 Limpiador de prompts — Enmascaramiento de PII a nivel de campo con lista de permitidos del dominio energético antes de enviar datos a LLMs externos (v0.11.5)- 🔌 Soporte MCP — Integración del SDK del Model Context Protocol

• 📝 Documentación OpenAPI — Documentación automática de API en /api/docs

• 🧭 Búsqueda de DSO/VNB — Búsqueda/consulta de VNBdigital y resolución BDEW → MaStR

• 🛠️ Herramienta CLI — Interfaz de línea de comandos para llamar a microservicios

• 📦 Plantillas de servicio — Plantilla de servicio esqueleto lista para usar

• 🔄 Recarga en caliente — Recarga automática de servicios durante el desarrollo

• 🎯 Mejores prácticas — ESLint, Prettier y diseño de proyecto estructurado

Related MCP server: EnergyAtIt MCP Server

Documentación

• CHANGELOG.md - Notas de la versión y cambios notables

• MCP_TOOLS.md - Referencia de herramientas MCP

• MCP_SERVICES.md - Mapeo de microservicio a herramienta

• BEARER_TOKEN_AUTHENTICATION.md - Guía de autenticación

• docs/BACKEND_CONTEXT.md - Referencia de arquitectura de backend (servicios, PouchDB, códigos de hallazgo, autenticación)

• llm.txt - Artefacto de contexto LLM generado (arquitectura + conocimiento del dominio + libro de cocina + OpenAPI)

• docs/ui-contracts/ - Contratos de API frontend ↔ backend (v0.20, 14 documentos)

• docs/MAINTENANCE_MILESTONE_CHECKLIST.md - Lista de verificación de puerta de calidad/seguridad previa al hito

• SECURITY.md - Política de seguridad y divulgación

• CODE_OF_CONDUCT.md - Pautas de la comunidad

CI/CD y transparencia

• Las solicitudes de extracción y los pushes a main ejecutan verificaciones de calidad automatizadas (lint, compilación, puertas de cobertura unitaria, verificación de descubrimiento de integración, auditoría OpenAPI, auditorías de seguridad).

• El análisis de seguridad se aplica continuamente con CodeQL.

• Las etiquetas de versión (v*) activan un pipeline de lanzamiento (release:check + compilación + GitHub Release).

• llm.txt se valida en las verificaciones de lanzamiento y se regenera a partir de archivos de fuente de verdad mediante npm run generate:llm.

• En la CI de mantenimiento, la sincronización de llm.txt se verifica estrictamente cuando cambia CHANGELOG.md.

• Los informes de cobertura se cargan y son visibles públicamente a través de Codecov.

• Configuración de repositorio recomendada: habilite la protección de rama en main y requiera verificaciones de Maintenance CI + CodeQL antes de fusionar.

Inicio rápido

Requisitos previos

• Node.js 18+

• npm o yarn

Instalación

# Clone the repository
git clone https://github.com/energychain/cernion-energy-tools.git
cd cernion-energy-tools

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env and add your API keys (see Configuration section)
nano .env

Ejecución de los servicios

# Start all services
npm start

# Or use development mode with hot reload
npm run dev

El API Gateway se iniciará en http://localhost:3000 de forma predeterminada.

Uso de la CLI

# Call a microservice action
npm run cli -- skeleton.hello --name=John

# Health check
npm run cli -- skeleton.health

# Get help
npm run cli -- --help

Aplicación web de investigación

La aplicación web integrada en /app le permite explorar todos los microservicios utilizando lenguaje natural en texto plano: sin curl, sin formulario Swagger, sin necesidad de codificación.

Flujo de trabajo

1. Describa su pregunta — escriba en inglés o alemán sencillo, p. ej. "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. Revise el plan — la IA descompone la pregunta en una secuencia numerada de llamadas a microservicios y le muestra exactamente qué servicios se llamarán y con qué parámetros.

3. Ajuste los parámetros — los valores concretos extraídos de su consulta (fechas, códigos postales, IDs de MeLo, nombres de operadores, …) aparecen como campos de formulario prellenados y editables. Cambie cualquier valor sin regenerar el plan.

4. Ejecute y explore — los resultados aparecen en una tabla ordenable y filtrable. El JSON sin procesar de cada paso está disponible para depuración.

5. Comparta o automatice — se generan automáticamente una URL compartible y un enlace CSV en vivo (ver más abajo).

CSV en vivo para automatización

Cada análisis completado expone un endpoint CSV parametrizado:

GET /api/agent/session/<id>/csv?param1=value1&param2=value2

• La consulta se vuelve a ejecutar en vivo contra las fuentes de datos reales cada vez que se llama: los datos nunca están obsoletos.

• Los parámetros GET anulan los valores guardados, por lo que la misma URL de sesión se puede reutilizar con diferentes fechas, regiones o identificadores.

• La URL CSV se actualiza en tiempo real en la interfaz de usuario a medida que cambia cualquier campo del formulario.

Ejemplo de Power Automate / Excel Power Query:

http://10.0.0.8:3900/api/agent/session/2a70e478-90ce-4fa5-b996-6f98efdba7cf/csv?startDate=2026-03-01

Apunte una acción HTTP → Obtener archivo o una fuente de datos Web de Power Query a esta URL. Cambie el parámetro startDate para obtener