industrial-aiops-energy — 能源 edition (变电 / 电力)

The energy edition of Industrial-AIOps, split out into its own repo: read-only OT connectors for substation / utility telecontrol protocols, built on top of iaiops.core.

• IEC 60870-5-104 (c104) — RTU / substation telemetry
• DNP3 / IEEE 1815 (pydnp3) — outstation monitoring
• IEC 61850 MMS (pyiec61850, linux-only wheel) — substation IED reads

It reuses the base package's shared governance (audit / budget / risk-tier / undo), cross-protocol brain (data-flow / alarm / OEE / downtime RCA on the normalized ISA-95/18.2 model), and MCP server infrastructure — this repo only adds the three energy connectors + their session builders + MCP tools. Read-first: no control-direction writes are exposed.

Current release: 0.1.9 (requires iaiops>=0.20.1,<1.0). New in 0.1.9 — every tool now ships the MCP ToolAnnotations hints (readOnlyHint / destructiveHint / openWorldHint), derived from the @governed_tool harness rather than hand-written, so a client can tell a monitor read from a tool that acts without parsing the [READ]/[WRITE] docstring tag. On the wire that is 59 tools, 55 read-only and 0 destructive — this edition exposes no control direction, and that is now enforced by a test rather than only documented. They are hints, not a gate: the MCP spec forbids relying on annotations for security decisions, and enforcement stays in @governed_tool. The base pin moved to iaiops>=0.20.1 so the hint derivation is imported from mcp_server.hints instead of duplicated here.

Previously in 0.1.8 — the base IAIOPS_READ_ONLY gate was removed in iaiops 0.19.0 (read/write authorisation is the caller's decision — agent judgement / account management — not the tap's; every tool is governed and audited via the base @governed_tool harness), so this edition drops it too. It keeps the IAIOPS_NO_EGRESS=1 gate — a data-exfiltration / airgap axis that withholds data-shipping tools from list_tools() at registration time. This edition runs its own FastMCP instance, so the gate is wired into its own main(); without it IAIOPS_NO_EGRESS=1 would still expose historian_push, rca_narrate and the stream_publish* pair mirrored in from the base brain. The energy connectors themselves are monitor-only and survive the gate intact. See CHANGELOG.md.

Previously in 0.1.6 — an audit-hardening pass over the three read-only connectors: DNP3 no longer reports an offline outstation as online or returns a partial integrity-poll database; IEC-61850 gained a bounded connect/request timeout and stopped fabricating 0.0/empty-success on failure; the substation analyzer no longer calls a lone breaker-open a "selective trip"; tests isolate IAIOPS_HOME; and the base pin was raised to iaiops>=0.14 so the governance endpoint-scoping fix applies. See CHANGELOG.md §0.1.6. (0.1.5 verified the IEC-104 monitor path — a real c104 client↔server round-trip in a Linux container, tests/test_iec104_live.py.) Physical RTU/IED still 待核实. Since 0.1.3 the server has its own MCP identity — iaiops-energy-mcp runs a dedicated FastMCP("iaiops-energy") instance with energy-specific instructions (IEC-104 / DNP3 / IEC-61850, read-first, no control/operate), with the base cross-protocol brain tools mirrored onto it — plus an edition skill (skills/iaiops-energy/SKILL.md, anti-drift-tested against the registered tool surface) and protocol-consistency contract tests (every tool must carry the governance marker, a [READ]-style risk tag, an Args: section, and the canonical {error, hint} error shape; the server refuses to start if any registered tool lacks the governance marker).

🧪 测试与共创 / Beta testing & co-creation

变电站现场的测试反馈是这个包最缺的东西。 IEC-104 / DNP3 / IEC-61850 三条监视路径均已 对真实库(c104 / opendnp3 / libiec61850 的进程内 server)在 Linux 容器里 loopback 往返验证,但 真实 RTU / IED 物理设备一律 待核实 —— 如果你能在授权的测试环境里对真实变电设备跑一遍 iaiops doctor,我们非常想听结果。经你验证的设备会署名写进支持矩阵。

Live substation RTU / IED / IEC-104 field testing is what this package needs most. The IEC-104, DNP3 and IEC-61850 monitor paths are library-loopback-verified, but real gear stays 待核实. Report results (protocol + device model + iaiops doctor output) via the base repo's pinned issue: 👉 industrial-aiops#28 — Call for field-testing partners (v0.10.0)

Why a separate repo

Energy targets a distinct buyer (utilities / substations), has heavier platform-specific deps (pyiec61850 is a linux-only SWIG wheel; pydnp3 builds a native ext), and its own compliance surface (电力监控系统安全防护). Splitting keeps the base install light. See the base repo's docs/ENERGY-SPINOUT.md for the plan.

Install

pip install iaiops-energy[energy]      # all three energy protocols
pip install iaiops-energy[iec104]      # just IEC-104

iaiops-energy pulls in iaiops (the shared core) automatically.

Use (MCP)

iaiops-energy-mcp                       # brain + energy tools over stdio

Point a target at your substation gear in ~/.iaiops/config.yaml (protocol: iec104|dnp3|iec61850, host, port, common_address / unit_id).

Edge deployment & ecosystem (edge-native / Margo)

Like the base package, the energy edition rides on a hardened, centrally-managed edge host as a portable, governed edge application — mapping onto the Margo edge-interoperability roles (immutable host · compliant orchestrator · iaiops-energy = the OT-domain app), deployable as an OCI Managed Container (outbound-only to substation RTUs/IEDs, no inbound). A container + margo.org/v1-alpha1 application-description skeleton is in deploy/margo/; the full alignment + honest gap analysis lives in the base repo's docs/MARGO-ALIGNMENT.md. The descriptor is validated against Margo's published margo.org/v1-alpha1 LinkML schema on every PR (CI job margo-descriptor) and passes clean — structural validity only, see deploy/margo/schema/PROVENANCE.md.

Honest status: a natural Margo edge application, but NOT Margo-compliant yet — image build, hosted+signed package, and a published conformance result are roadmap ⏳. No claim of compliance until that result exists, and the schema pass above is not a step toward it: the compliance test suite cannot be run today because it does not exist yet (no conformance repo in the margo org; a first PR1 vertical slice was still being scoped as of 2026-01-15).

Validation status (honest)

The same honesty ladder as the base repo. Driver codec / API surface is verified against the real libraries; the mock/monkeypatched unit tests run in CI without hardware. See the base repo's docs/PREVIEW-VERIFICATION.md runbook for how a protocol is promoted.

¹ CI-coverage caveat (honest). Only IEC-104's monitor path is CI-gated: the CI job hard-installs the iec104 extra, so test_iec104_live.py runs its full loopback round-trip on every push. DNP3 and IEC-61850 are loopback-verified only via manual / Docker runs — their native libraries (opendnp3 via pydnp3, libiec61850 via pyiec61850) do not build on hosted GitHub runners, so CI installs them best-effort and test_dnp3_live.py / test_iec61850_live.py SKIP there. A regression in the DNP3 or IEC-61850 monitor path is therefore not caught by CI and must be re-checked with a manual/Docker run — the "verified (monitor path)" claim for those two rests on those out-of-CI runs, not on the green CI badge.

DNP3 notes: read-only / monitor direction only (no control). pydnp3 0.1.0 ships no wheel and needs a native opendnp3 build, so the live test runs in a Linux container; its DNP3Manager.Shutdown() can block in a long-lived interpreter, so the connector bounds teardown (_Pydnp3MasterAdapter.shutdown) and the test drives the round-trip in a short-lived child process.

License

MIT — © wei. Part of the vendor-neutral, governed Industrial-AIOps line.