Cernion Energy Tools

MicroService-Agentensystem für Energiemärkte

Eine modulare, skalierbare Microservices-Plattform, entwickelt mit Moleculer, zur Erstellung von Energiemarkt-Anwendungen mit KI-Integration (Google Gemini) und MCP-Unterstützung (Model Context Protocol).

Funktionen

• 🚀 Moleculer Microservices Framework — Schnelles, modernes und leistungsstarkes Microservices-Framework

• 🌐 API Gateway — HTTP REST API mit automatischer Routengenerierung

• 🤖 KI-Agent — Natürlichsprachlicher Abfrageplaner, betrieben durch Google Gemini: Beschreiben Sie Ihren Bedarf an Energiedaten in einfachem Text, und der Agent generiert, führt aus und interpretiert automatisch einen mehrstufigen Microservice-Plan

• 🏢 Interne Datenquellen — Registrieren, ableiten, zwischenspeichern und entdecken Sie interne Versorgungsdatensätze (CSV, REST, GeoJSON, XLSX, DOCX, Scraper) neben öffentlichen Energiewerkzeugen

• 🧩 Research Web App — Integrierte Single-Page-Anwendung unter /app für interaktive, browserbasierte Tests des KI-Agenten — keine separaten Werkzeuge erforderlich

• 📥 Live CSV-Export — Jedes Agentenergebnis stellt einen parametrisierten GET-Endpunkt (/api/agent/session/:id/csv?param=value) für eine Zero-Config-Integration mit Automatisierungstools wie Microsoft Power Automate, Excel Power Query oder Cron-Jobs bereit

• Datenpunkte — Benannte, versionierte, gesundheitsüberwachte Datenquellen, die auf eingebettetem PouchDB basieren. Befördern Sie jede Agentsitzung zu einem verwalteten Datenpunkt, verfolgen Sie die Aktualisierungshistorie und Schema-Stabilität und rufen Sie Live-Daten als JSON oder CSV über /api/datapoints ab. Siehe die Gesundheitsübersicht für ein Dashboard aller registrierten Datenpunkte.

• 📸 Snapshots — Versiegeln Sie eine Gruppe von Datenpunkten als konsistente Einheit mit SHA-256 Provenance-Hashing. Erstellen, validieren (Drifterkennung), auflisten und entfernen Sie Snapshots über /api/datapoints/snapshot* (v0.13)

• 🌍 OSM Geo Layer — Netzinfrastrukturanalyse via OpenStreetMap/Overpass: VNB-Zuordnungsvalidierung, Infrastruktur in der Nähe, Umspannwerksinventar und Netztopologie (v0.10)

• 🌐 OEP Connector — Schreibgeschützter Zugriff auf die Open Energy Platform (Szenariodaten, NEP-Referenzen, Forschungsdatensätze) via /api/oep/* (v0.12)

• 🔌 Netzanschlussvalidierung — Deterministische 6-stufige Netzanschluss-Pipeline (POST /api/grid-connection/validate): Inventar → Delta → Kapazität → EWK-Benchmark → Go/No-Go-Entscheidung → Audit-Trail. Kein LLM — identische Eingaben, identische Ergebnisse. Berichte versiegelt mit PouchDB-Snapshots für EU AI Act Art. 12 Konformität (v0.14)

• 🤝 Energy Sharing Validierung — Deterministische 6-stufige § 42c EnWG-Pipeline (POST /api/energy-sharing/validate): Erzeuger/Verbraucher-Berechtigung, MaLo-Validierung, Anteils-Summenprüfung, DV-Validierung. Regulatorische Frist: 01.06.2026 (v0.15)

• 📊 MaStR Datenqualitäts-Audit — 8-stufiges Portfolio-Qualitätsaudit (POST /api/mastr-quality/audit): Registrierungsvollständigkeit, Kapazitätsplausibilität, NAP/MeLo-Konnektivität, Duplikaterkennung, Geo-Stichprobenprüfung. Gewichteter 0–100 Score über 5 Dimensionen (v0.17)

• ⚡ Redispatch Ex-Post Audit — 7-stufiges Redispatch 2.0 Abrechnungsbereitschafts-Audit (POST /api/redispatch/audit): Portfolio-Zusammenstellung (Weg A/B), NAP/MeLo/DV-Prüfungen, Abregelungsdaten, finanzielles Risikoscoring (v0.18)

• 🗂️ Dashboard API — Schreibgeschützter UI-Aggregator mit 4 zusammengesetzten Endpunkten (GET /api/dashboard/*): VNB-Übersicht, Markt-Snapshot, Qualitätszusammenfassung, Referenz für Findungscodes. Alle Upstream-Aufrufe parallel via Promise.allSettled, Graceful Degradation, 5–15 Min. Cache (v0.19)

• 🧠 OEO / OEMetadata — Open Energy Ontology-Annotationen auf allen 45+ REST-Endpunkten, OEMetadata v2.0 Export mit optionaler JSON-Schema-Validierung (v0.11.4–v0.12)

• 🔐 Datenprovenienz — SHA-256 Provenance-Hashing bei jeder Datenpunkt-Aktualisierung für EU AI Act Art. 12 Konformität, plus Erklärbarkeits-Log für Agentenkorrekturen (v0.11.5)

• 🧹 Prompt Scrubber — PII-Maskierung auf Feldebene mit Allowlist für den Energiebereich, bevor Daten an externe LLMs gesendet werden (v0.11.5)

• 🔌 MCP-Unterstützung — Model Context Protocol SDK-Integration

• 📝 OpenAPI-Dokumentation — Automatische API-Dokumentation unter /api/docs

• 🧭 DSO/VNB-Suche — VNBdigital-Suche/Lookup und BDEW → MaStR-Auflösung

• 🛠️ CLI-Tool — Befehlszeilenschnittstelle zum Aufrufen von Microservices

• 📦 Service-Vorlagen — Gebrauchsfertige Skelett-Service-Vorlage

• 🔄 Hot Reload — Automatisches Neuladen von Services während der Entwicklung

• 🎯 Best Practices — ESLint, Prettier und strukturierter Projektlayout

Related MCP server: EnergyAtIt MCP Server

Dokumentation

• CHANGELOG.md - Versionshinweise und wichtige Änderungen

• MCP_TOOLS.md - MCP-Tool-Referenz

• MCP_SERVICES.md - Microservice-zu-Tool-Mapping

• BEARER_TOKEN_AUTHENTICATION.md - Authentifizierungsleitfaden

• docs/BACKEND_CONTEXT.md - Backend-Architekturreferenz (Services, PouchDB, Findungscodes, Auth)

• llm.txt - Generiertes LLM-Kontext-Artefakt (Architektur + Domänenwissen + Kochbuch + OpenAPI)

• docs/ui-contracts/ - Frontend ↔ Backend API-Verträge (v0.20, 14 Dokumente)

• docs/MAINTENANCE_MILESTONE_CHECKLIST.md - Checkliste für Qualitäts-/Sicherheits-Gates vor Meilensteinen

• SECURITY.md - Sicherheitsrichtlinie und Offenlegung

• CODE_OF_CONDUCT.md - Community-Richtlinien

CI/CD & Transparenz

• Pull Requests und Pushes auf main führen automatisierte Qualitätsprüfungen aus (Lint, Build, Unit-Coverage-Gates, Integration-Discovery-Sanity, OpenAPI-Audit, Sicherheitsaudits).

• Sicherheitsanalysen werden kontinuierlich mit CodeQL erzwungen.

• Version-Tags (v*) lösen eine Release-Pipeline aus (release:check + Build + GitHub Release).

• llm.txt wird bei Release-Prüfungen validiert und aus den Source-of-Truth-Dateien via npm run generate:llm neu generiert.

• In der Wartungs-CI wird die Synchronität von llm.txt streng geprüft, wenn sich CHANGELOG.md ändert.

• Coverage-Berichte werden hochgeladen und sind öffentlich über Codecov sichtbar.

• Empfohlene Repository-Einstellung: Branch-Schutz auf main aktivieren und Maintenance CI + CodeQL-Prüfungen vor dem Merge verlangen.

Schnellstart

Voraussetzungen

• Node.js 18+

• npm oder yarn

Installation

# 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

Ausführen der Services

# Start all services
npm start

# Or use development mode with hot reload
npm run dev

Das API Gateway startet standardmäßig unter http://localhost:3000.

Verwendung der 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

Research Web App

Die integrierte Webanwendung unter /app ermöglicht es Ihnen, alle Microservices in natürlicher Sprache zu erkunden — kein curl, kein Swagger-Formular, kein Programmieren erforderlich.

Workflow

1. Beschreiben Sie Ihre Frage — geben Sie sie in einfachem Englisch oder Deutsch ein, z. B. "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. Überprüfen Sie den Plan — die KI zerlegt die Frage in eine nummerierte Sequenz von Microservice-Aufrufen und zeigt Ihnen genau, welche Services mit welchen Parametern aufgerufen werden.

3. Parameter anpassen — konkrete Werte, die aus Ihrer Abfrage extrahiert wurden (Daten, Postleitzahlen, MeLo-IDs, Betreibernamen, …), erscheinen als vorausgefüllte, bearbeitbare Formularfelder. Ändern Sie jeden Wert, ohne den Plan neu zu generieren.

4. Ausführen & erkunden — Ergebnisse erscheinen in einer sortierbaren, filterbaren Tabelle. Das rohe JSON jedes Schritts ist für das Debugging verfügbar.

5. Teilen oder automatisieren — eine teilbare URL und ein Live CSV-Link werden automatisch generiert (siehe unten).

Live CSV für Automatisierung

Jede abgeschlossene Analyse stellt einen parametrisierten CSV-Endpunkt bereit:

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

• Die Abfrage läuft bei jedem Aufruf live gegen die echten Datenquellen — Daten sind niemals veraltet.

• GET-Parameter überschreiben die gespeicherten Werte, sodass dieselbe Sitzungs-URL mit unterschiedlichen Daten, Regionen oder Identifikatoren wiederverwendet werden kann.

• Die CSV-URL aktualisiert sich in Echtzeit in der UI, während Sie ein Formularfeld ändern.

Beispiel für Power Automate / Excel Power Query:

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

Verweisen Sie eine HTTP → Datei abrufen-Aktion oder eine Power Query Web-Datenquelle auf diese URL. Ändern Sie den startDate-Parameter, um einen anderen Berichtszeitraum abzurufen — keine erneute Analyse erforderlich.

Andere Automatisierungsmuster:

• Planen Sie einen Cron-Job / GitHub Action, um täglich frische CSVs abzurufen

• Speisen Sie Daten direkt in pandas read_csv(url) in einem Jupyter Notebook ein

• Verwenden Sie es als Datenquelle in Grafana, Power BI oder jedem Tool, das eine CSV-URL akzeptiert

Erstellen neuer Services

Verwendung des Service Creators

# Create a new service interactively
npm run create

# Or specify a name directly
npm run create -- my-service

Dies erstellt einen neuen Service in custom-services/ aus der Skelett-Vorlage und generiert einen passenden Test in custom-tests/.

Benutzerdefinierte Services sind nur lokal vorhanden und werden von git ignoriert. Kern-Services, die mit dem Projekt geliefert werden, befinden sich in services/.

Manuelle Service-Erstellung

1. Kopieren Sie die Skelett-Vorlage:

   cp templates/skeleton.service.js custom-services/my-service.service.js

2. Bearbeiten Sie den Service — ändern Sie die name-Eigenschaft, fügen Sie Aktionen, Ereignisse und Methoden hinzu.

3. Starten Sie die Services neu:

   npm start

Benutzerdefinierte Services & Tests

• Benutzerdefinierte Services befinden sich in custom-services/ und werden beim Start geladen.

• Benutzerdefinierte Tests befinden sich in custom-tests/ und sind von der Release-Coverage ausgeschlossen.

• Führen Sie benutzerdefinierte Tests ohne globale Coverage-Schwellenwerte aus:

  npm run test:custom -- my-service.service.test.js

Projektstruktur

cernion-energy-tools/
├── services/              # Core microservices (shipped with release)
│   ├── api.service.js     # API Gateway + Swagger UI
│   ├── agent.service.js   # AI agent — plan/execute/export
│   ├── assets.service.js  # MaStR installation assets
│   ├── datapoint.service.js # Named datapoints + snapshots (v0.11–v0.13)
│   ├── osm-geo.service.js # OSM geo layer (v0.10)
│   ├── oep.service.js     # Open Energy Platform (v0.12)
│   ├── datasource-registry.service.js
│   ├── datasource-connector.service.js
│   ├── datasource-cache.service.js
│   ├── datasource-discovery.service.js
│   ├── forecast.service.js
│   ├── gas-storage.service.js
│   ├── german-grid.service.js
│   ├── grid-operations.service.js
│   └── ...                # See services/ for full list
├── src/
│   ├── app.html           # Research Web App (single-page)
│   ├── connectors/        # Built-in datasource connector plugins
│   ├── mcp-client.js      # Centralised MCP tool caller
│   ├── async-job-poller.js # Async job polling
│   ├── prompt-scrubber.js  # PII masking for LLM prompts
│   ├── oeo-mappings.js    # OEO class mappings (~150 entries)
│   ├── validation-findings.js # Grid connection finding constants (v0.14)
│   └── oemetadata-builder.js # OEMetadata v2.0 builder
├── custom-services/       # Local/custom services (git-ignored)
├── custom-connectors/     # Local/custom datasource plugins (git-ignored)
├── custom-tests/          # Local/custom tests (git-ignored)
├── templates/
│   └── skeleton.service.js
├── tests/                 # Core test suite
├── scripts/               # Build / audit scripts
├── index.js               # Main entry point
├── cli.js                 # CLI tool
├── create-service.js      # Interactive service creator
├── moleculer.config.js    # Moleculer configuration
├── .env.example           # Environment variables template
└── package.json

Konfiguration

Umgebungsvariablen

Kopieren Sie .env.example nach .env und bearbeiten Sie diese: