Cernion 에너지 도구

에너지 시장을 위한 마이크로서비스 에이전트 시스템

AI 통합(Google Gemini) 및 MCP(Model Context Protocol) 지원을 통해 에너지 시장 애플리케이션을 개발하기 위해 Moleculer로 구축된 모듈식 확장형 마이크로서비스 플랫폼입니다.

주요 기능

• 🚀 Moleculer 마이크로서비스 프레임워크 — 빠르고 현대적이며 강력한 마이크로서비스 프레임워크

• 🌐 API 게이트웨이 — 자동 경로 생성을 지원하는 HTTP REST API

• 🤖 AI 에이전트 — Google Gemini 기반의 자연어 쿼리 플래너: 일반 텍스트로 에너지 데이터 요구 사항을 설명하면 에이전트가 다단계 마이크로서비스 계획을 자동으로 생성, 실행 및 해석합니다.

• 🏢 사내 데이터 소스 — 공공 에너지 도구와 함께 내부 유틸리티 데이터 세트(CSV, REST, GeoJSON, XLSX, DOCX, 스크레이퍼)를 등록, 추론, 캐싱 및 검색합니다.

• 🧩 연구용 웹 앱 — AI 에이전트의 대화형 브라우저 기반 테스트를 위해 /app에 내장된 단일 페이지 애플리케이션 — 별도의 도구가 필요하지 않습니다.

• 📥 실시간 CSV 내보내기 — 모든 에이전트 결과는 Microsoft Power Automate, Excel Power Query 또는 cron 작업과 같은 자동화 도구와의 제로 구성 통합을 위해 매개변수화된 GET 엔드포인트(/api/agent/session/:id/csv?param=value)를 노출합니다.

• 💾 데이터 포인트 — 내장 PouchDB로 지원되는 이름 지정, 버전 관리 및 상태 모니터링 데이터 소스입니다. 모든 에이전트 세션을 관리형 데이터 포인트로 승격하고, 새로 고침 기록 및 스키마 안정성을 추적하며, /api/datapoints를 통해 JSON 또는 CSV로 실시간 데이터를 검색할 수 있습니다. 등록된 모든 데이터 포인트의 대시보드는 상태 개요를 참조하세요.

• 📸 스냅샷 — SHA-256 출처 해싱을 사용하여 데이터 포인트 그룹을 일관된 단위로 봉인합니다. /api/datapoints/snapshot*(v0.13)을 통해 스냅샷을 생성, 검증(드리프트 감지), 나열 및 제거할 수 있습니다.

• 🌍 OSM 지리 레이어 — OpenStreetMap/Overpass를 통한 그리드 인프라 분석: VNB 할당 검증, 인근 인프라, 변전소 인벤토리 및 그리드 토폴로지(v0.10)

• 🌐 OEP 커넥터 — /api/oep/*(v0.12)를 통해 Open Energy Platform(시나리오 데이터, NEP 참조, 연구 데이터 세트)에 대한 읽기 전용 액세스를 제공합니다.

• 🔌 그리드 연결 검증 — 결정론적 6단계 Netzanschluss 파이프라인(POST /api/grid-connection/validate): 인벤토리 → 델타 → 용량 → EWK 벤치마크 → Go/No-Go 결정 → 감사 추적. LLM을 사용하지 않으며, 동일한 입력에 대해 동일한 결과를 보장합니다. EU AI Act Art. 12 준수를 위해 PouchDB 스냅샷으로 봉인된 보고서를 제공합니다(v0.14).

• 🤝 에너지 공유 검증 — 결정론적 6단계 § 42c EnWG 파이프라인(POST /api/energy-sharing/validate): 발전기/소비자 자격, MaLo 검증, 공유 합계 확인, DV 검증. 규제 마감일: 2026년 6월 1일(v0.15)

• 📊 MaStR 데이터 품질 감사 — 8단계 포트폴리오 품질 감사(POST /api/mastr-quality/audit): 등록 완전성, 용량 타당성, NAP/MeLo 연결성, 중복 감지, 지리적 현장 점검. 5개 차원에 걸쳐 0~100점의 가중치 점수 부여(v0.17)

• ⚡ Redispatch 사후 감사 — 7단계 Redispatch 2.0 정산 준비 상태 감사(POST /api/redispatch/audit): 포트폴리오 구성(Weg A/B), NAP/MeLo/DV 확인, 감축 데이터, 재무 위험 점수(v0.18)

• 🗂️ 대시보드 API — 4개의 복합 엔드포인트(GET /api/dashboard/*)를 갖춘 읽기 전용 UI 집계기: VNB 개요, 시장 스냅샷, 품질 요약, 결과 코드 참조. 모든 업스트림 호출은 Promise.allSettled를 통해 병렬로 처리되며, 정상적인 성능 저하 및 5~15분 캐시를 지원합니다(v0.19)

• 🧠 OEO / OEMetadata — 45개 이상의 모든 REST 엔드포인트에 대한 Open Energy Ontology 주석, 선택적 JSON 스키마 검증을 포함한 OEMetadata v2.0 내보내기(v0.11.4~v0.12)

• 🔐 데이터 출처 — EU AI Act Art. 12 준수를 위해 모든 데이터 포인트 새로 고침 시 SHA-256 출처 해싱을 수행하며, 에이전트 수정 사항에 대한 설명 가능성 로그를 제공합니다(v0.11.5)

• 🧹 프롬프트 스크러버 — 외부 LLM으로 데이터를 보내기 전에 에너지 도메인 허용 목록을 사용하여 필드 수준의 PII 마스킹을 수행합니다(v0.11.5)

• 🔌 MCP 지원 — Model Context Protocol SDK 통합

• 📝 OpenAPI 문서 — /api/docs에서 자동 API 문서화

• 🧭 DSO/VNB 조회 — VNBdigital 검색/조회 및 BDEW → MaStR 확인

• 🛠️ CLI 도구 — 마이크로서비스 호출을 위한 명령줄 인터페이스

• 📦 서비스 템플릿 — 즉시 사용 가능한 스켈레톤 서비스 템플릿

• 🔄 핫 리로드 — 개발 중 자동 서비스 재로드

• 🎯 모범 사례 — ESLint, Prettier 및 구조화된 프로젝트 레이아웃

Related MCP server: EnergyAtIt MCP Server

문서

• CHANGELOG.md - 릴리스 노트 및 주요 변경 사항

• MCP_TOOLS.md - MCP 도구 참조

• MCP_SERVICES.md - 마이크로서비스-도구 매핑

• BEARER_TOKEN_AUTHENTICATION.md - 인증 가이드

• docs/BACKEND_CONTEXT.md - 백엔드 아키텍처 참조(서비스, PouchDB, 결과 코드, 인증)

• llm.txt - 생성된 LLM 컨텍스트 아티팩트(아키텍처 + 도메인 지식 + 쿡북 + OpenAPI)

• docs/ui-contracts/ - 프론트엔드 ↔ 백엔드 API 계약(v0.20, 14개 문서)

• docs/MAINTENANCE_MILESTONE_CHECKLIST.md - 마일스톤 이전 품질/보안 게이트 체크리스트

• SECURITY.md - 보안 정책 및 공개

• CODE_OF_CONDUCT.md - 커뮤니티 가이드라인

CI/CD 및 투명성

• main에 대한 풀 리퀘스트 및 푸시는 자동화된 품질 검사(린트, 빌드, 단위 커버리지 게이트, 통합 검색 건전성, OpenAPI 감사, 보안 감사)를 실행합니다.

• 보안 분석은 CodeQL을 통해 지속적으로 시행됩니다.

• 버전 태그(v*)는 릴리스 파이프라인(release:check + 빌드 + GitHub 릴리스)을 트리거합니다.

• llm.txt는 릴리스 검사에서 검증되며 npm run generate:llm을 통해 소스 파일에서 재생성됩니다.

• 유지 관리 CI에서는 CHANGELOG.md가 변경될 때 llm.txt 동기화가 엄격하게 확인됩니다.

• 커버리지 보고서는 업로드되어 Codecov를 통해 공개적으로 볼 수 있습니다.

• 권장 리포지토리 설정: main에 브랜치 보호를 활성화하고 병합 전 Maintenance CI + CodeQL 검사를 요구합니다.

빠른 시작

사전 요구 사항

• Node.js 18+

• npm 또는 yarn

설치

# 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

서비스 실행

# Start all services
npm start

# Or use development mode with hot reload
npm run dev

API 게이트웨이는 기본적으로 http://localhost:3000에서 시작됩니다.

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

연구용 웹 앱

/app에 내장된 웹 애플리케이션을 사용하면 curl, Swagger 양식, 코딩 없이 일반 텍스트 자연어를 사용하여 모든 마이크로서비스를 탐색할 수 있습니다.

워크플로우

1. 질문 설명 — 일반 영어 또는 독일어로 입력하세요. 예: "Alle PV-Anlagen im Netz der Enercity in Hannover"

2. 계획 검토 — AI가 질문을 번호가 매겨진 마이크로서비스 호출 시퀀스로 분해하고, 어떤 서비스가 어떤 매개변수로 호출될지 정확히 보여줍니다.

3. 매개변수 조정 — 쿼리에서 추출된 구체적인 값(날짜, 우편번호, MeLo ID, 운영자 이름 등)이 미리 채워진 편집 가능한 양식 필드로 나타납니다. 계획을 다시 생성하지 않고도 값을 변경할 수 있습니다.

4. 실행 및 탐색 — 결과가 정렬 및 필터링 가능한 테이블에 나타납니다. 디버깅을 위해 모든 단계의 원시 JSON을 사용할 수 있습니다.

5. 공유 또는 자동화 — 공유 가능한 URL과 실시간 CSV 링크가 자동으로 생성됩니다(아래 참조).

자동화를 위한 실시간 CSV

완료된 모든 분석은 매개변수화된 CSV 엔드포인트를 노출합니다:

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

• 쿼리는 호출될 때마다 실제 데이터 소스에 대해 실시간으로 재실행되므로 데이터가 절대 오래되지 않습니다.

• GET 매개변수는 저장된 값을 재정의하므로 동일한 세션 URL을 다른 날짜, 지역 또는 식별자로 재사용할 수 있습니다.

• 양식 필드를 변경하면 UI에서 CSV URL이 실시간으로 업데이트됩니다.

Power Automate / Excel Power Query 예시:

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

HTTP → 파일 가져오기 작업 또는 Power Query 웹 데이터 소스를 이 URL로 지정하세요. startDate 매개변수를 변경하여 다른 보고 기간을 가져오세요. 재분석이 필요하지 않습니다.

기타 자동화 패턴:

• cron 작업 / GitHub Action을 예약하여 매일 최신 CSV를 가져오기

• Jupyter 노트북에서 pandas read_csv(url)로 직접 피드

• Grafana, Power BI 또는 CSV URL을 허용하는 모든 도구에서 데이터 소스로 사용

새 서비스 생성

서비스 생성기 사용

# Create a new service interactively
npm run create

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

이 명령은 스켈레톤 템플릿에서 custom-services/에 새 서비스를 생성하고 custom-tests/에 일치하는 테스트를 생성합니다.

사용자 지정 서비스는 로컬 전용이며 git에서 무시됩니다. 프로젝트와 함께 제공되는 핵심 서비스는 services/에 있습니다.

수동 서비스 생성

1. 스켈레톤 템플릿 복사:

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

2. 서비스 편집 — name 속성을 변경하고 작업, 이벤트 및 메서드를 추가합니다.

3. 서비스 재시작:

npm start

사용자 지정 서비스 및 테스트

• 사용자 지정 서비스는 custom-services/에 있으며 시작 시 로드됩니다.

• 사용자 지정 테스트는 custom-tests/에 있으며 릴리스 커버리지에서 제외됩니다.

• 전역 커버리지 임계값 없이 사용자 지정 테스트 실행:

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

프로젝트 구조

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

구성

환경 변수

.env.example을 .env로 복사하고 편집하세요: