Cernion Energy Tools

API-first Agentic Energy Operations Layer for Stadtwerke, DSOs and energy-service teams. Cernion combines deterministic energy-domain services, curated capability routing, evidence dossiers, VDMI role logic, HITL boundaries and read-only integration surfaces for REST, Sidecar, Microsoft Copilot, n8n, OpenWebUI and OpenClaw.

What This Repository Is

Cernion Energy Tools is the backend runtime behind cernion.de: a Node.js/Moleculer service platform for energy-domain automation, decision support and agentic process orchestration.

It is not just a chat frontend for energy APIs. The current platform contains:

• 138 Moleculer services in services/
• 1007 OpenAPI paths in openapi-export.json
• 304 JavaScript test files under tests/
• curated Copilot, Sidecar, OpenWebUI, n8n and OpenClaw integration surfaces that expose only governed subsets of the backend
• agentic runtime components for routing, receipts, dossiers, HITL, evidence, revalidation and observability

Current package/OpenAPI version: 0.99.0

Public positioning

Cernion does not let the chat decide. The platform structures the objective, available data, service chain, evidence, gaps, risk and the next safe gate. The result is not a black-box answer, but a dossier-ready status or decision-readiness view for Stadtwerke, distribution-system operators and energy-service teams.

Cernion Energy Tools is not an automatic contract decision, grid-connection commitment, device-control system, MaKo execution system, billing/settlement system or tariff-mutation machine. Suitable integration scopes are ask, plan, evidence, capability lookup and read-only status. Write-like or consequential steps stay in draft, prepare or pending confirmation states and require HITL.

The public website explains Cernion as an energy-intelligence and decision platform for Stadtwerke: MaStR analysis, grid planning, §14a, Redispatch, Energy Sharing, customer-service automation and Microsoft Copilot complementarity. This repository is the deeper technical system underneath that product narrative.

Public discovery links

• Product and topic hub: Cernion Themencluster
• Capability overview: Cernion Capability Hub
• API and agent integration: MCP Tools & API and REST API
• Operational search-intent pages:
  • Verteilnetzbetreiber Software
  • Stadtwerke Prozessautomatisierung
  • §14a EnWG Nachweisakte
  • Redispatch 2.0 Bewegungsdaten
  • KI für Stadtwerke und Netzbetreiber

Why Cernion Is Agentic

Cernion is API-first, but the API is only the integration layer. The agentic part is the runtime behavior:

1. Understand an energy-domain objective Examples: validate a grid-connection scenario, build a VDMI responsibility matrix, assess BESS finance risk, identify Energy Sharing data conflicts.
2. Select a governed capability path The capability-broker maps intent to curated service chains instead of exposing the full tool catalogue to an LLM.
3. Execute deterministic microservices Energy-domain calculations and regulatory checks remain code-backed and reproducible.
4. Maintain process state Personal-agent sessions, receipts, dossiers, HITL items and object-store evidence allow work to continue beyond a single chat turn.
5. Produce auditable artifacts Outputs are not only natural-language answers; they include dossiers, evidence packages, decision frames, validation reports, receipts and traces.
6. Govern revalidation New facts can become control signals for agents: if a MaStR asset, datapoint or object-store evidence item changes, dependent decisions can be identified and rechecked.

This is the practical difference between a question-and-answer bot and an agentic energy-operations platform.

Core Architecture

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

Runtime Layers

Main Domains

The platform covers several energy-industry work areas. The following list is representative; the OpenAPI export is the source of truth.

Agentic Components

Personal Agent

services/personal-agent.service.js is the user-facing orchestration layer. It keeps conversation state, routes intents, calls deterministic services and synthesizes results without turning the whole backend into one prompt.

Key concepts:

• layered context management ("Zwiebelmodus")
• durable execution state and resumable sessions
• file and datapoint intake
• evidence-gap handling
• work-out-loud events
• presentation-aware final artifacts

Capability Broker

services/capability-broker.service.js and src/capability-catalog.js provide curated capability routing. This is the control point that prevents agents from seeing or choosing the entire backend surface directly.

Examples of curated capabilities include:

• 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 turns repeatable agent workflows into versioned, testable recipes. Receipts describe matching conditions, required inputs, tool plans and knowledge plans. They are the bridge from "the agent answered" to "the platform selected a governed, inspectable workflow".

Dossiers and Decision Frames

Cernion uses dossiers and decision frames for auditable outputs. A result can include:

• facts used
• hypotheses
• evidence gaps
• risks
• forbidden assumptions
• VDMI responsibilities
• next actions
• human-review requirements

Agentic Governance and Revalidation

Two active architecture tracks are captured in GitHub issues:

• #275 Agent Governance Runtime: Bestandsanalyse vor Umsetzungsplan
• #276 Agentic Governance Layer: Faktenänderungen als Steuerungssignal für Agenten

The target direction is that a changed fact can become a control signal for agents:

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