Cernion Grid Intelligence

87+ ferramentas especializadas para dados energéticos alemães e europeus. Acesso direto por IA ao Marktstammdatenregister (MaStR), ENTSO-E, Redispatch 2.0 e Operações da Rede para concessionárias e datacenters.

GitHub

Documentação

Cernion Energy Tools

Camada de Operações Energéticas Agenticas com API-first para Stadtwerke, DSOs e equipes de serviços de energia. A Cernion combina serviços determinísticos de domínio energético, roteamento de capacidades curado, dossiês de evidências, lógica de papéis VDMI, limites de HITL e superfícies de integração somente leitura para REST, Sidecar, Microsoft Copilot, n8n, OpenWebUI e OpenClaw.

O Que É Este Repositório

Cernion Energy Tools é o runtime de backend por trás de cernion.de: uma plataforma de serviços Node.js/Moleculer para automação de domínio energético, suporte a decisões e orquestração de processos agenticos.

Não é apenas um frontend de chat para APIs de energia. A plataforma atual contém:

138 serviços Moleculer em services/
1007 caminhos OpenAPI em openapi-export.json
304 arquivos de teste JavaScript sob tests/
superfícies de integração curadas para Copilot, Sidecar, OpenWebUI, n8n e OpenClaw que expõem apenas subconjuntos governados do backend
componentes de runtime agenticos para roteamento, recibos, dossiês, HITL, evidências, revalidação e observabilidade
arquivos de projeto duráveis com ingestão com escopo por locatário, tabelas estruturadas, um grafo de relações com respaldo de evidências e manifestos de roteamento versionados com seleção de fonte visível; consulte Projektakte para APIs, proveniência, limites e limpeza

Versão atual do pacote/OpenAPI: 0.99.0

Posicionamento público

A Cernion não deixa o chat decidir. A plataforma estrutura o objetivo, os dados disponíveis, a cadeia de serviços, as evidências, as lacunas, o risco e o próximo portão seguro. O resultado não é uma resposta de caixa-preta, mas uma visão de status pronta para dossiê ou de prontidão para decisão para Stadtwerke, operadores de sistemas de distribuição e equipes de serviços de energia.

Cernion Energy Tools não é uma decisão contratual automática, compromisso de conexão à rede, sistema de controle de dispositivos, sistema de execução MaKo, sistema de faturamento/liquidação ou máquina de mutação tarifária. Escopos de integração adequados são ask, plan, evidence, capability lookup e read-only status. Etapas do tipo escrita ou consequentes permanecem nos estados draft, prepare ou pending confirmation e exigem HITL.

O site público explica a Cernion como uma plataforma de inteligência energética e decisão para Stadtwerke: análise MaStR, planejamento de rede, §14a, Redispatch, Energy Sharing, automação de atendimento ao cliente e complementaridade com Microsoft Copilot. Este repositório é o sistema técnico mais profundo por trás dessa narrativa de produto.

Links públicos de descoberta

Hub de produtos e tópicos: Cernion Themencluster
Visão geral de capacidades: Cernion Capability Hub
Integração de API e agentes: MCP Tools & API e REST API
Páginas operacionais de intenção de busca:

Por Que a Cernion É Agentica

A Cernion é API-first, mas a API é apenas a camada de integração. A parte agentica é o comportamento do runtime:

Entender um objetivo de domínio energético Exemplos: validar um cenário de conexão à rede, construir uma matriz de responsabilidades VDMI, avaliar risco financeiro de BESS, identificar conflitos de dados em Energy Sharing.
Selecionar um caminho de capacidade governado O capability-broker mapeia intenção para cadeias de serviços curadas em vez de expor o catálogo completo de ferramentas a um LLM.
Executar microsserviços determinísticos Cálculos de domínio energético e verificações regulatórias permanecem respaldados por código e reproduzíveis.
Manter o estado do processo Sessões de agentes pessoais, recibos, dossiês, itens de HITL e evidências no object store permitem que o trabalho continue além de uma única interação de chat.
Produzir artefatos auditáveis As saídas não são apenas respostas em linguagem natural; incluem dossiês, pacotes de evidências, quadros de decisão, relatórios de validação, recibos e rastros.
Governar a revalidação Novos fatos podem se tornar sinais de controle para agentes: se um ativo MaStR, ponto de dados ou item de evidência no object store mudar, decisões dependentes podem ser identificadas e revalidadas.

Esta é a diferença prática entre um bot de perguntas e respostas e uma plataforma agêntica de operações energéticas.

Arquitetura 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

Camadas de Runtime

Camada	Componentes	Propósito
Barramento de serviços	Moleculer, gateway REST, jobs assíncronos	Execução determinística de serviços e exposição de API
Camada de dados	Object Store, Datapoints, DataSources, Knowledge RAG	Dados internos, evidências externas, memória do locatário e material de origem
Roteamento agentico	Personal Agent, Capability Broker, Blueprints, Agent Receipts	Resolução de intenção, seleção de cadeia de ferramentas, execução durável
Governança	VDMI, HITL, Clarification Policy, Interface Placeholder, Evidence Revalidation	Responsabilidades, evidências ausentes, decisões humanas, tratamento de lacunas
Integração	OpenAPI completo, subconjunto Copilot, OpenClaw Sidecar, Webhooks, ferramentas estilo MCP	Uso seguro por humanos, copilotos, agentes e sistemas de automação
Observabilidade	Métricas, rastros, registros de auditoria, status de jobs	Operação, auditabilidade e suporte

Principais Domínios

A plataforma cobre várias áreas de trabalho da indústria de energia. A lista a seguir é representativa; a exportação OpenAPI é a fonte da verdade.

Domínio	Exemplos
Conexão à rede e fNAV	Validação de conexão à rede, acesso flexível à rede, evidências de rejeição de conexão
Governança VDMI	Verantwortlich, Durchführend, Mitwirkend, Information por etapa do processo; achados, dossiês e evidências
Zielnetzplanung (ZNP)	Projetos, premissas, ativos Layer 0/1/2, análise de portfólio, decisões NOVA
Qualidade de ativos e dados	Qualidade MaStR, sobreposições de ativos, alertas de ativos fantasma, classificação de fontes de dados
Energy Sharing e liquidação	Alocação estilo §42c, verificações de liquidação, reconciliação ex-post de Redispatch
EDM e comunicação de mercado	Importação MSCONS, validação EDM, medidores virtuais, verificações de messkonzept
Previsão e flexibilidade	Motor de previsão, carga residual, eventos de flexibilidade §14a, perfis SLP
Finanças e investimento	Agente de finanças, economia de fNAV, triagem de BESS, priorização de capex
Relatórios e BI	Governança de relatórios, API de dashboards, monitoramento VNB, monitoramento EWK
Conhecimento e evidências	Knowledge RAG, roteamento de evidências, dossiês, contexto do object store

Componentes Agenticos

Sitemap Agentico / Catálogo de IA

GET /.well-known/ai-catalog.json e GET /.well-known/ard.json publicam um catálogo público gerado a cada solicitação a partir do registro de serviços carregado e dos metadados OpenAPI em tempo real. Cada serviço REST publicado tem uma entrada com tokens de ação/capacidade, consultas representativas e um contrato OpenAPI embutido. O catálogo também vincula ao documento OpenAPI completo e a llm.txt. Respostas raiz anunciam ambos os caminhos de descoberta por meio de cabeçalhos HTTP Link; solicitações condicionais suportam ETags.

Nenhuma manutenção manual de JSON ou chamada de LLM é necessária. Ações protegidas/privadas, configurações de serviço e dados de runtime são excluídos. A visibilidade no catálogo não concede permissão para invocar uma ação. Consulte detalhes de implantação.

Os formatos são rascunhos: AI Catalog e Agentic Resource Discovery. O ARD agora usa ard.json; o ai-catalog.json solicitado permanece disponível para clientes que usam o caminho predecessor. Testes offline validam ambos os formatos contra esquemas upstream fixados; npm run sync:ai-catalog-schemas atualiza esses fixtures a partir da revisão fixada no script de sincronização (Apache-2.0).

Personal Agent

services/personal-agent.service.js é a camada de orquestração voltada ao usuário. Ela mantém estado de conversa, roteia intenções, chama serviços determinísticos e sintetiza resultados sem transformar todo o backend em um único prompt.

Conceitos-chave:

gerenciamento de contexto em camadas ("Zwiebelmodus")
estado de execução durável e sessões retomáveis
ingestão de arquivos e pontos de dados
tratamento de lacunas de evidências
eventos de trabalho visível (work-out-loud)
artefatos finais conscientes da apresentação

Capability Broker

services/capability-broker.service.js e src/capability-catalog.js fornecem roteamento de capacidades curado. Este é o ponto de controle que impede que agentes vejam ou escolham toda a superfície do backend diretamente.

Exemplos de capacidades curadas incluem:

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 transforma fluxos de trabalho agenticos repetíveis em receitas versionadas e testáveis. As receitas descrevem condições de correspondência, entradas necessárias, planos de ferramentas e planos de conhecimento. Elas são a ponte entre "o agente respondeu" e "a plataforma selecionou um fluxo de trabalho governado e inspecionável".

Dossiês e Quadros de Decisão

A Cernion usa dossiês e quadros de decisão para saídas auditáveis. Um resultado pode incluir:

fatos utilizados
hipóteses
lacunas de evidências
riscos
premissas proibidas
responsabilidades VDMI
próximas ações
requisitos de revisão humana

Governança Agentica e Revalidação

Duas trilhas de arquitetura ativas estão capturadas em issues do GitHub:

A direção alvo é que um fato alterado possa se tornar um sinal de controle para 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

É assim que a Cernion avança da análise única de API para RPA+ para processos energéticos de commodity: casos padrão são automatizados, exceções são tornadas explícitas.

Superfícies de Integração

API REST Completa

A API REST completa é gerada a partir dos metadados dos serviços Moleculer.

Swagger UI: GET /api/docs
OpenAPI JSON: GET /api/openapi.json
Exportação estática: openapi-export.json
Receitas de API públicas para descoberta por desenvolvedores e LLMs: docs/public-api-recipes.md

As receitas usam apenas exemplos sintéticos, tokens baseados em variáveis de ambiente e identificadores de demonstração seguros para o locatário. Elas documentam limites de consulta/somente leitura/confirmação pendente e não são demos de aprovação, faturamento, tarifa, controle de dispositivos, contrato ou mutação de produção.

Regenerar e auditar:

npm run export:openapi
npm run audit:openapi

Ponte Microsoft Copilot

A Cernion não expõe todos os 600+ caminhos de API ao Microsoft Copilot. A ponte Copilot usa uma allowlist curada mantida em config/copilot-operations.json.

Arquivos relevantes:

Gerar o subconjunto do Copilot:

npm run export:openapi:copilot

A superfície voltada ao Copilot distingue:

operações read sem efeitos colaterais
operações draft que preparam sugestões
operações prepare que exigem confirmação
operações consequentes que permanecem bloqueadas até serem explicitamente governadas

OpenClaw Sidecar

Cernion Energy Tools pode ser usado a partir do OpenClaw por meio do pacote público ClawHub @cernion/openclaw-energy-tools-sidecar. Instale-o no OpenClaw com:

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

O repositório complementar SmartEnergySolutions/cernion-openclaw-sidecar fornece um plugin OpenClaw para provedores genéricos de Energy Sidecar, com a Cernion como primeiro provedor.

O limite do produto é intencionalmente dividido: o OpenClaw é o runtime de agente para conversa, orquestração de ferramentas, memória e síntese de respostas. Cernion Energy Tools é a camada de evidências, políticas, Knowledge RAG e processos governados por CET do domínio energético por trás de respostas sobre ativos MaStR, contexto de rede, Redispatch, Zielnetzplanung, obrigações 14a/14d EnWG, ingestão de processos, estado de caso do Domain Router, Case Event Outbox/MWI e status operacional.

O sidecar consome o contrato 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=]

O limite é deliberadamente estrito:

Os tokens sidecar identificam o contexto de tenant, ator e cliente; a autorização/governança CET é o limite de permissão.
As ferramentas Domain Router e MWI podem atualizar o estado interno do PouchDB do CET, como estado de caso, estado de entrega de eventos e links de sessões relacionadas.
As consultas de evidence/hydration e os planos Blueprint permanecem somente leitura quando essa é a operação real.
A entrada de processos usa um token de processo separado e cria apenas recibos pending_confirmation
Os caminhos de mutação de admin, token, resolução HITL e produção são bloqueados
O roteamento de domínio permanece dentro do Cernion, não dentro do sidecar

Ferramentas no Estilo MCP

O Cernion também publica descrições de ferramentas amigáveis para agentes de IA por meio de llm.txt, endpoints de resolução de capacidade e listas de ferramentas no estilo MCP/OpenClaw. A página de documentação pública descreve isso como um conjunto de ferramentas de energia prontas para uso para Stadtwerke.

Início Rápido

Pré-requisito: 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 locais padrão:

API: http://localhost:3000/api
Swagger UI: http://localhost:3000/api/docs
Aplicativo web: http://localhost:3000/app

Guia de configuração completo: QUICKSTART.md

Configuração

Comece com .env.example. Variáveis comuns:

Variável	Finalidade
`CERNION_TOKEN`	Token de API para acesso autenticado
`LLM_PROVIDER`	Provedor de LLM (`gemini`, `openai-compat`, `ollama`)
`LLM_MODEL`	Nome do modelo para o provedor selecionado
`LLM_API_KEY` / `GEMINI_API_KEY`	Credenciais do provedor quando necessário
`API_URL`	URL base usada nos servidores OpenAPI gerados e links de compartilhamento da CLI
`PORT`	Porta do gateway de API, padrão `3000`
`TRACING_ENABLED`	Ativar rastreamento OpenTelemetry
`OTEL_EXPORTER_OTLP_ENDPOINT`	Destino de rastreamento HTTP OTLP
`METRICS_PUBLIC`	Expor `/metrics` sem um token de acesso completo

Saúde do LLM:

GET /api/system/llm/health

Observabilidade:

GET /metrics retorna métricas compatíveis com Prometheus
Exemplos de Grafana: docs/observability/grafana/README.md

Guia de autenticação: BEARER_TOKEN_AUTHENTICATION.md

Desenvolvimento

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

O runbook „Release-Gate ausführen“ descreve a avaliação prática com cenários sintéticos de múltiplas etapas, rubrica e execuções repetidas contra uma instância de teste local ou HTTP. release:gate complementa as verificações do repositório com essa aceitação.

Comandos úteis de geração:

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

Criar um novo serviço Moleculer:

npm run create

Demonstração do Cernion

Boas demonstrações devem mostrar uma execução agêntica, não apenas uma resposta de chat.

Padrões fortes de demonstração:

VDMI: gerar uma matriz de responsabilidades por etapa do processo e detectar violações de limites de função
BESS: avaliar um local considerando conexão à rede, riscos, premissas de receita e evidências do financiador
Energy Sharing: identificar conflitos de MaLo/MeLo, EDM e liquidação que bloqueiam o processo
MaStR/Revalidação: mostrar como uma atualização de ativo externo pode acionar a reavaliação de decisões dependentes
Copilot/Sidecar: mostrar o Cernion como o backend governado do domínio de energia por trás de um agente de propósito geral

Um rastreamento agêntico útil deve tornar visível:

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 Documentação

Documento	Tópico
docs/copilot-process-bridge.md	Subconjunto curado da API do Microsoft Copilot
docs/v0.52-implementation-plans/personal-agent-v052-architecture-tdd.md	Arquitetura do Personal Agent e contrato TDD
docs/v0.52-implementation-plans/v0.52.1-capability-broker.md	Plano de implementação do Capability Broker
docs/observability/grafana/README.md	Painéis do Grafana
docs/DSFA_TEMPLATE.md	Modelo de avaliação de impacto na proteção de dados
docs/BACKEND_CONTEXT.md	Contexto de backend para trabalho de UI/frontend
CHANGELOG.md	Histórico de versões
MCP_TOOLS.md	Referência de MCP/ferramentas
docs/SHARED_SERVICE_JOURNAL.md	Shared Service Journal RC3 somente anexação, digests determinísticos e retenção
docs/domain-router.md	CET Domain Router, vinculação de casos tipada, visibilidade own/team/tenant e Case Event Outbox / MWI
docs/tenant-memory.md	Memória do tenant: declarações, âncoras comuns, fontes, correção e avisos únicos
docs/open-webui-tenant-gateway.md	Acesso ao Tenant-Gateway do RC3 Open WebUI / Cernion Workbench sem AgentOS
llm.txt	Contexto legível por máquina de serviços e capacidades
SECURITY.md	Política de segurança

Licença e Contexto do Operador

Licença: GPL-3.0. Consulte LICENSE.

O Cernion é desenvolvido pela STROMDAO GmbH no contexto da plataforma de inteligência energética Cernion.

Suporte e feedback de produto:

GitHub Issues
dev@stromdao.com

Workbench: entender, responder, caso em segundo plano

Mensagens de conteúdo e textos externos inseridos são traduzidos em um quadro situacional por meio da fachada central de LLM. O CET responde com fontes relevantes e no máximo três novas perguntas de esclarecimento técnico. Tarefas de trabalho concretas recebem um caso em segundo plano; „Kein Fall“ o remove. Perguntas de conhecimento e status não geram caso. Solicitações de envio resultam em um aviso e, a pedido explícito, em um rascunho interno. A atribuição de fontes e o limite de relevância estão configurados em src/workbench-knowledge-sources.json. Detalhes e limites estão no Guia do Tenant-Gateway e no Relatório de aceitação do #739.

Declarações relevantes para a organização são registradas pelo CET em todo o tenant e confirmadas uma vez com „Hab ich festgehalten: …“. Âncoras comuns raras conectam declarações de pessoas diferentes; interações reconhecidas aparecem na conversa e uma vez no próximo contato da outra pessoa. A separação de tenants e os níveis de confidencialidade se aplicam a cada acesso. Detalhes estão no Guia de Memória do Tenant.

Catálogo de Dados do Tenant

Tabelas de texto completas em CSV/XLSX do Open WebUI são armazenadas em todo o tenant como dados de usuário e avaliadas deterministicamente por meio de dataset.query. O mesmo conteúdo não gera outra versão ou confirmação, mesmo com anexos reenviados. Configuração, limites e exemplos: Catálogo de Dados do Tenant. Mensagens estruturadas e EDIFACT: Formatos, verificações e consultas.

Arquivos Originais no Chat (#790)

Instalação do filtro versionado do Open WebUI, downloads assinados, limites de arquivo e retenção: Runbook. Sem o filtro instalado, o caminho de texto de documentos existente permanece.

Hotfix RC3 para Entrada de E-mail e Documentos (#846)

O reconhecimento de tabelas requer um cabeçalho com pelo menos duas colunas e pelo menos duas linhas de dados com largura igual. WORKBENCH_DATASET_MIN_TABLE_RATIO determina a proporção necessária no bloco de tabela (padrão 0.75, válido: maior que 0.5 até 1). Erros de parser comuns caem para texto; o bloqueio de plausibilidade para tabelas realmente reconhecidas permanece ativo. Os orçamentos de arquivo, linha e coluna continuam válidos. Apenas o padrão de decomposição exclusivo e não reproduzível sem perdas do Open WebUI usa WORKBENCH_DATASET_DAMAGED.

Regenerar fixtures sintéticos e verificar as regressões 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

O script ao vivo existente verifica adicionalmente a entrada de e-mail (1), o resumo de protocolo (3), o histórico de e-mail ao lado de um registro INVOIC estrangeiro (5) e a mensagem explicitamente mencionada (6). Ele inicia um broker local com bancos de dados temporários isolados e um tenant de validação sintético. Todas as chamadas de modelo de linguagem passam pela fachada central e pelo orçamento de chamadas/tokens existente. Iniciar exclusivamente com uma configuração de não produção:

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

A extensão não foi executada ao vivo. Um relatório ao vivo só pode ser usado como evidência de aceitação após uma execução separada de não produção.