{
  "markdown": "# Cernion Energy Tools\n\n> API-first Agentic Energy Operations Layer for Stadtwerke, DSOs and energy-service teams.\n> Cernion combines deterministic energy-domain services, curated capability routing,\n> evidence dossiers, VDMI role logic, HITL boundaries and read-only integration surfaces\n> for REST, Sidecar, Microsoft Copilot, n8n, OpenWebUI and OpenClaw.\n\n[![Maintenance CI](https://github.com/energychain/cernion-energy-tools/actions/workflows/maintenance-ci.yml/badge.svg?branch=main)](https://github.com/energychain/cernion-energy-tools/actions/workflows/maintenance-ci.yml)\n[![CodeQL](https://github.com/energychain/cernion-energy-tools/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/energychain/cernion-energy-tools/actions/workflows/codeql.yml)\n[![Release](https://github.com/energychain/cernion-energy-tools/actions/workflows/release.yml/badge.svg)](https://github.com/energychain/cernion-energy-tools/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/energychain/cernion-energy-tools/branch/main/graph/badge.svg)](https://codecov.io/gh/energychain/cernion-energy-tools)\n\n## What This Repository Is\n\nCernion Energy Tools is the backend runtime behind [cernion.de](https://cernion.de/):\na Node.js/Moleculer service platform for energy-domain automation, decision support and\nagentic process orchestration.\n\nIt is not just a chat frontend for energy APIs. The current platform contains:\n\n- **138 Moleculer services** in `services/`\n- **1007 OpenAPI paths** in `openapi-export.json`\n- **304 JavaScript test files** under `tests/`\n- **curated Copilot, Sidecar, OpenWebUI, n8n and OpenClaw integration surfaces** that expose only governed subsets of the backend\n- **agentic runtime components** for routing, receipts, dossiers, HITL, evidence, revalidation and observability\n\nCurrent package/OpenAPI version: **`0.99.0`**\n\n### Public positioning\n\nCernion does not let the chat decide. The platform structures the objective, available\ndata, service chain, evidence, gaps, risk and the next safe gate. The result is not a\nblack-box answer, but a dossier-ready status or decision-readiness view for Stadtwerke,\ndistribution-system operators and energy-service teams.\n\nCernion Energy Tools is not an automatic contract decision, grid-connection commitment,\ndevice-control system, MaKo execution system, billing/settlement system or tariff-mutation\nmachine. Suitable integration scopes are `ask`, `plan`, `evidence`, `capability lookup`\nand `read-only status`. Write-like or consequential steps stay in `draft`, `prepare` or\n`pending confirmation` states and require HITL.\n\nThe public website explains Cernion as an energy-intelligence and decision platform for\nStadtwerke: MaStR analysis, grid planning, §14a, Redispatch, Energy Sharing, customer-service\nautomation and Microsoft Copilot complementarity. This repository is the deeper technical\nsystem underneath that product narrative.\n\n### Public discovery links\n\n- Product and topic hub: [Cernion Themencluster](https://cernion.de/themen)\n- Capability overview: [Cernion Capability Hub](https://cernion.de/capabilities)\n- API and agent integration: [MCP Tools & API](https://cernion.de/mcp-tools-api) and [REST API](https://cernion.de/rest-api)\n- Operational search-intent pages:\n  - [Verteilnetzbetreiber Software](https://cernion.de/verteilnetzbetreiber-software)\n  - [Stadtwerke Prozessautomatisierung](https://cernion.de/stadtwerke-prozessautomatisierung)\n  - [§14a EnWG Nachweisakte](https://cernion.de/14a-enwg-nachweisakte)\n  - [Redispatch 2.0 Bewegungsdaten](https://cernion.de/redispatch-20-bewegungsdaten)\n  - [KI für Stadtwerke und Netzbetreiber](https://cernion.de/ki-fuer-stadtwerke-netzbetreiber)\n\n## Why Cernion Is Agentic\n\nCernion is API-first, but the API is only the integration layer. The agentic part is the\nruntime behavior:\n\n1. **Understand an energy-domain objective**\n   Examples: validate a grid-connection scenario, build a VDMI responsibility matrix,\n   assess BESS finance risk, identify Energy Sharing data conflicts.\n2. **Select a governed capability path**\n   The `capability-broker` maps intent to curated service chains instead of exposing the\n   full tool catalogue to an LLM.\n3. **Execute deterministic microservices**\n   Energy-domain calculations and regulatory checks remain code-backed and reproducible.\n4. **Maintain process state**\n   Personal-agent sessions, receipts, dossiers, HITL items and object-store evidence allow\n   work to continue beyond a single chat turn.\n5. **Produce auditable artifacts**\n   Outputs are not only natural-language answers; they include dossiers, evidence packages,\n   decision frames, validation reports, receipts and traces.\n6. **Govern revalidation**\n   New facts can become control signals for agents: if a MaStR asset, datapoint or object-store\n   evidence item changes, dependent decisions can be identified and rechecked.\n\nThis is the practical difference between a question-and-answer bot and an agentic\nenergy-operations platform.\n\n## Core Architecture\n\n```text\nExternal systems / humans / agents\n        |\n        v\nREST API, Copilot API, OpenClaw Sidecar, MCP-like tool surfaces\n        |\n        v\nPersonal Agent / Capability Broker / Agent Receipts / Blueprints\n        |\n        v\nGoverned Moleculer services\n        |\n        v\nDatapoints, Object Store, Knowledge RAG, Dossiers, Jobs, Observability\n```\n\n### Runtime Layers\n\n| Layer | Components | Purpose |\n| --- | --- | --- |\n| Service bus | Moleculer, REST gateway, async jobs | Deterministic service execution and API exposure |\n| Data layer | Object Store, Datapoints, DataSources, Knowledge RAG | Internal data, external evidence, tenant memory and source material |\n| Agentic routing | Personal Agent, Capability Broker, Blueprints, Agent Receipts | Intent resolution, tool-chain selection, durable execution |\n| Governance | VDMI, HITL, Clarification Policy, Interface Placeholder, Evidence Revalidation | Responsibilities, missing evidence, human decisions, gap handling |\n| Integration | Full OpenAPI, Copilot subset, OpenClaw Sidecar, Webhooks, MCP-style tools | Safe use by humans, copilots, agents and automation systems |\n| Observability | Metrics, traces, audit records, job status | Operation, auditability and support |\n\n## Main Domains\n\nThe platform covers several energy-industry work areas. The following list is representative;\nthe OpenAPI export is the source of truth.\n\n| Domain | Examples |\n| --- | --- |\n| Grid connection and fNAV | Grid-connection validation, flexible network access, connection-rejection evidence |\n| VDMI governance | Verantwortlich, Durchführend, Mitwirkend, Information per process step; findings, dossiers and evidence |\n| Zielnetzplanung (ZNP) | Projects, assumptions, Layer 0/1/2 assets, portfolio analysis, NOVA decisions |\n| Asset and data quality | MaStR quality, asset overrides, ghost-asset alerts, datasource classification |\n| Energy Sharing and settlement | §42c-style allocation, settlement checks, Redispatch ex-post reconciliation |\n| EDM and market communication | MSCONS import, EDM validation, virtual meters, messkonzept checks |\n| Forecasting and flexibility | Forecast engine, residual load, §14a flex events, SLP profiles |\n| Finance and investment | Finance agent, fNAV economics, BESS screening, capex prioritization |\n| Reporting and BI | Reporting governance, dashboard API, VNB monitoring, EWK monitoring |\n| Knowledge and evidence | Knowledge RAG, evidence routing, dossiers, object-store context |\n\n## Agentic Components\n\n### Personal Agent\n\n`services/personal-agent.service.js` is the user-facing orchestration layer. It keeps\nconversation state, routes intents, calls deterministic services and synthesizes results\nwithout turning the whole backend into one prompt.\n\nKey concepts:\n\n- layered context management (\"Zwiebelmodus\")\n- durable execution state and resumable sessions\n- file and datapoint intake\n- evidence-gap handling\n- work-out-loud events\n- presentation-aware final artifacts\n\n### Capability Broker\n\n`services/capability-broker.service.js` and `src/capability-catalog.js` provide curated\ncapability routing. This is the control point that prevents agents from seeing or choosing\nthe entire backend surface directly.\n\nExamples of curated capabilities include:\n\n- `vdmi_role_boundary_governance`\n- `vdmi_asset_validation_governance`\n- `vdmi_grid_connection_decision_governance`\n- `netzfahrplan_fnav_assessment`\n- `znp_portfolio_assessment`\n- `settlement_a96_reconciliation`\n- `financier_due_diligence_assessment`\n- `reporting_governance`\n\n### Agent Receipts\n\n`services/agent-receipts.service.js` turns repeatable agent workflows into versioned,\ntestable recipes. Receipts describe matching conditions, required inputs, tool plans and\nknowledge plans. They are the bridge from \"the agent answered\" to \"the platform selected a\ngoverned, inspectable workflow\".\n\n### Dossiers and Decision Frames\n\nCernion uses dossiers and decision frames for auditable outputs. A result can include:\n\n- facts used\n- hypotheses\n- evidence gaps\n- risks\n- forbidden assumptions\n- VDMI responsibilities\n- next actions\n- human-review requirements\n\n### Agentic Governance and Revalidation\n\nTwo active architecture tracks are captured in GitHub issues:\n\n- [#275 Agent Governance Runtime: Bestandsanalyse vor Umsetzungsplan](https://github.com/energychain/cernion-energy-tools/issues/275)\n- [#276 Agentic Governance Layer: Faktenänderungen als Steuerungssignal für Agenten](https://github.com/energychain/cernion-energy-tools/issues/276)\n\nThe target direction is that a changed fact can become a control signal for agents:\n\n```text\nMaStR / datapoint / object-store change\n        |\n        v\nDependency and impact analysis\n        |\n        v\nRevalidation queue\n        |\n        v\nAgent receipt / capability flow rerun\n        |\n        v\nAudit note, updated dossier, HITL item or exception case\n```\n\nThis is how Cernion moves from one-time API analysis toward RPA+ for commodity energy\nprocesses: standard cases are automated, exceptions are made explicit.\n\n## Integration Surfaces\n\n### Full REST API\n\nThe complete REST API is generated from Moleculer service metadata.\n\n- Swagger UI: `GET /api/docs`\n- OpenAPI JSON: `GET /api/openapi.json`\n- Static export: `openapi-export.json`\n- Public API recipes for developer and LLM discovery: [docs/public-api-recipes.md](docs/public-api-recipes.md)\n\nThe recipes use only synthetic examples, environment-variable based tokens and tenant-safe demo identifiers. They document consultation/read-only/pending-confirmation boundaries and are not approval, billing, tariff, device-control, contract or production-mutation demos.\n\nRegenerate and audit:\n\n```bash\nnpm run export:openapi\nnpm run audit:openapi\n```\n\n### Microsoft Copilot Bridge\n\nCernion does not expose all 600+ API paths to Microsoft Copilot. The Copilot bridge uses a\ncurated allowlist maintained in `config/copilot-operations.json`.\n\nRelevant files:\n\n- [docs/copilot-process-bridge.md](docs/copilot-process-bridge.md)\n- [docs/copilot-agent.json](docs/copilot-agent.json)\n- [docs/copilot-plugin.json](docs/copilot-plugin.json)\n- `openapi-copilot.json`\n\nGenerate the Copilot subset:\n\n```bash\nnpm run export:openapi:copilot\n```\n\nThe Copilot-facing surface distinguishes:\n\n- `read` operations with no side effects\n- `draft` operations that prepare suggestions\n- `prepare` operations requiring confirmation\n- consequential operations that remain blocked until explicitly governed\n\n### OpenClaw Sidecar\n\nCernion Energy Tools can be used from OpenClaw through the public\n[ClawHub package @cernion/openclaw-energy-tools-sidecar](https://clawhub.ai/cernion/plugins/openclaw-energy-tools-sidecar).\nInstall it in OpenClaw with:\n\n```bash\nopenclaw plugins install clawhub:@cernion/openclaw-energy-tools-sidecar\n```\n\nThe companion repository\n[SmartEnergySolutions/cernion-openclaw-sidecar](https://github.com/SmartEnergySolutions/cernion-openclaw-sidecar)\nprovides an OpenClaw plugin for generic Energy Sidecar providers, with Cernion as the first\nprovider.\n\nThe product boundary is intentionally split: OpenClaw is the agent runtime for conversation,\ntool orchestration, memory and answer synthesis. Cernion Energy Tools is the energy-domain\nevidence, policy, Knowledge RAG and read-only API layer behind answers about MaStR assets,\ngrid context, Redispatch, Zielnetzplanung, 14a/14d EnWG duties, process intake and operational\nstatus.\n\nThe sidecar consumes the Cernion Sidecar contract:\n\n- `GET /api/agent-sidecar/descriptor`\n- `GET /api/agent-sidecar/mcp/tools`\n- `POST /api/agent-sidecar/mcp/tools/:name/call`\n- `POST /api/knowledge-rag/query`\n- `POST /api/evidence-router/route`\n- `POST /api/copilot-process/intents`\n- `GET /api/_agent/capabilities[?domain=]`\n- `GET /api/_agent/operations[?domain=]`\n\nThe boundary is deliberately strict:\n\n- read-only Cernion evidence lookup uses a read-only token\n- process intake uses a separate process token and creates only `pending_confirmation` receipts\n- admin, token, HITL-resolve and production mutation paths are blocked\n- domain routing remains inside Cernion, not inside the sidecar\n\n### MCP-Style Tooling\n\nCernion also publishes AI-agent-friendly tool descriptions through `llm.txt`, capability\nresolution endpoints and MCP/OpenClaw-style tool lists. The public documentation page\ndescribes this as a set of ready-to-use energy tools for Stadtwerke.\n\n## Quickstart\n\nPrerequisite: **Node.js 22+**\n\n```bash\ngit clone https://github.com/energychain/cernion-energy-tools.git\ncd cernion-energy-tools\nnpm install\ncp .env.example .env\nnpm start\n```\n\nDefault local endpoints:\n\n- API: `http://localhost:3000/api`\n- Swagger UI: `http://localhost:3000/api/docs`\n- Web app: `http://localhost:3000/app`\n\nFull setup guide: [QUICKSTART.md](QUICKSTART.md)\n\n## Configuration\n\nStart with [.env.example](.env.example). Common variables:\n\n| Variable | Purpose |\n| --- | --- |\n| `CERNION_TOKEN` | API token for authenticated access |\n| `LLM_PROVIDER` | LLM provider (`gemini`, `openai-compat`, `ollama`) |\n| `LLM_MODEL` | Model name for the selected provider |\n| `LLM_API_KEY` / `GEMINI_API_KEY` | Provider credentials when needed |\n| `API_URL` | Base URL used in generated OpenAPI servers and CLI share links |\n| `PORT` | API gateway port, default `3000` |\n| `TRACING_ENABLED` | Enable OpenTelemetry tracing |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP HTTP trace destination |\n| `METRICS_PUBLIC` | Expose `/metrics` without a full-access token |\n\nLLM health:\n\n```text\nGET /api/system/llm/health\n```\n\nObservability:\n\n- `GET /metrics` returns Prometheus-compatible metrics\n- Grafana examples: [docs/observability/grafana/README.md](docs/observability/grafana/README.md)\n\nAuth guide: [BEARER_TOKEN_AUTHENTICATION.md](BEARER_TOKEN_AUTHENTICATION.md)\n\n## Development\n\n```bash\nnpm test\nnpm run test:unit:ci\nnpm run test:tdd-matrix\nnpm run test:rest-usecases\nnpm run lint\nnpm run audit:openapi\nnpm run check:llm\nnpm run release:check\n```\n\nUseful generation commands:\n\n```bash\nnpm run export:openapi\nnpm run export:openapi:copilot\nnpm run generate:llm\nnpm run blueprint:export\n```\n\nCreate a new Moleculer service:\n\n```bash\nnpm run create\n```\n\n## Demonstrating Cernion\n\nGood demos should show an **agentic run**, not only a chat answer.\n\nStrong demo patterns:\n\n- VDMI: generate a responsibility matrix per process step and detect role-boundary violations\n- BESS: assess a site across grid connection, risks, revenue assumptions and financier evidence\n- Energy Sharing: identify MaLo/MeLo, EDM and settlement conflicts that block the process\n- MaStR/Revalidation: show how an external asset update can trigger rechecking of dependent decisions\n- Copilot/Sidecar: show Cernion as the governed energy-domain backend behind a general-purpose agent\n\nA useful agentic trace should make these visible:\n\n```text\nUser objective\n  -> intent and capability\n  -> selected receipt / blueprint\n  -> service chain\n  -> evidence used\n  -> gaps and risks\n  -> HITL / policy decision\n  -> dossier or decision artifact\n  -> audit trace\n```\n\n## Documentation Map\n\n| Document | Topic |\n| --- | --- |\n| [docs/copilot-process-bridge.md](docs/copilot-process-bridge.md) | Curated Microsoft Copilot API subset |\n| [docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md](docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md) | Personal Agent architecture and TDD contract |\n| [docs/v0.52-implementation-plans/v0.52.1-capability-broker.md](docs/v0.52-implementation-plans/v0.52.1-capability-broker.md) | Capability Broker implementation plan |\n| [docs/observability/grafana/README.md](docs/observability/grafana/README.md) | Grafana dashboards |\n| [docs/DSFA_TEMPLATE.md](docs/DSFA_TEMPLATE.md) | Data protection impact-assessment template |\n| [docs/BACKEND_CONTEXT.md](docs/BACKEND_CONTEXT.md) | Backend context for UI/frontend work |\n| [CHANGELOG.md](CHANGELOG.md) | Release history |\n| [MCP_TOOLS.md](MCP_TOOLS.md) | MCP/tool reference |\n| [llm.txt](llm.txt) | Machine-readable service and capability context |\n| [SECURITY.md](SECURITY.md) | Security policy |\n\n## License and Operator Context\n\nLicense: GPL-3.0. See [LICENSE](LICENSE).\n\nCernion is developed by [STROMDAO GmbH](https://stromdao.de/) in the context of the\n[Cernion](https://cernion.de/) energy-intelligence platform.\n\nSupport and product feedback:\n\n- [GitHub Issues](https://github.com/energychain/cernion-energy-tools/issues)\n- `dev@stromdao.com`\n",
  "bytes": 17425,
  "sha": "e5c8aa36d7cd7195c83e00138361bd22d8cbe1860ff829bb026687d462d860ff",
  "repo_slug": "energychain/cernion-energy-tools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_de_cernion_cernion_energy_tools_239e697a/readme"
}