industrial-aiops

<!-- mcp-name: io.github.industrial-aiops/iaiops -->

# Industrial-AIOps

**English** · [中文](README.zh-CN.md)

**Ask an AI agent why the line stopped — and get an answer that cites its evidence.**

A vendor-neutral, **read-first** data tap for the factory floor. It speaks **14 field protocols**,
correlates what it reads *across* them, and hands your agent an evidence-cited verdict instead of a
guess. Every call is audited, and no reading ever phones home.

```bash
pip install "iaiops[opcua]"      # pick your protocol — or [all]
iaiops init                      # write ~/.iaiops/config.yaml
iaiops doctor                    # check the setup before you trust it
```

Prefer a container? The published image is **cosign-signed** and runs **non-root**. It speaks MCP
over stdio, so keep stdin open and mount a volume for the audit store:

```bash
cosign verify --key deploy/margo/cosign.pub ghcr.io/industrial-aiops/iaiops:0.30.0-factory
docker run -i --rm -v iaiops-state:/home/iaiops/.iaiops \
  ghcr.io/industrial-aiops/iaiops:0.30.0-factory
```

For a hardened or air-gapped deployment (read-only rootfs, `cap_drop: ALL`, no-new-privileges,
optional on-box LLM) use [`deploy/margo/compose.yaml`](deploy/margo/compose.yaml) and
[`deploy/airgap/`](deploy/airgap/). The analysis engine needs **no GPU and no model API** — it is
deterministic; an LLM is optional and only *phrases* the verdict.

## What you get

|  |  |
|---|---|
| **Reads** | OPC-UA (+ Historical Access, tag auto-discovery) · Modbus TCP/RTU · S7comm · Mitsubishi MC · Omron FINS · MTConnect · MQTT/Sparkplug B · EtherNet/IP · EtherCAT · PROFINET · SECS/GEM · HART-IP · BACnet/IP · IO-Link — plus read-only REST layers for BAS supervisors (Metasys / Niagara) and Ignition Gateway |
| **Figures out** | downtime root cause (the flagship copilot), alarm floods (ISA-18.2), broken dataflows, data trustworthiness, OEE, asset inventory, legacy PLC program explainer (ST/AWL/L5X) |
| **Governs** | audit · budget · risk-tier · undo — on *every* call, through one engine, from both MCP and CLI |
| **Stays yours** | no telemetry, no phone-home. Six tools *can* send data off-box by design (`stream_publish`, `stream_publish_event`, `uns_publish`, `historian_push`, `mqtt_publish`, `rca_narrate`) — `IAIOPS_NO_EGRESS=1` withholds all six for an air-gapped posture |

Eleven editions ship in this package — ten per industry (fab · factory · process · building · water ·
warehouse · clinical · pharma · renewables · plcnext), each adding its own read-only advisory checks,
and one cross-protocol: sensor (connect, decode and read a sensor; `IAIOPS_MCP=sensor`).
Substation / utility telecontrol (IEC-104 · DNP3 · IEC-61850) ships separately as
[`iaiops-energy`](https://github.com/industrial-aiops/industrial-aiops-energy).

## Your first five minutes

Four commands. Only one of them touches a device, and it prints what it will send
before it sends anything.

```bash
pip install "iaiops[modbus]"     # pick the protocol you actually have, or [all]
iaiops onboard status            # ← run this first. Contacts NOTHING.
iaiops doctor                    # config, secrets, reachability — and the version
iaiops readiness                 # every scenario, and what each gap needs
```

`onboard status` answers the smaller questions you have first: **which journey is
this site on — reading its devices directly, or subscribing to a UNS broker its
data already flows through — which step of it are you on, and what is the one
command that advances it?** It is derived from your store and `config.yaml` every
time. The one thing it keeps is a namespace audit verdict, and that counts only for
the broker and topic filter it was taken on and always shows its age — so edit
`config.yaml` by hand and the answer stays true.

`readiness` reads your config and local store and answers one question: **which
scenarios can this site run today, and what does each gap need?** Every gap comes
with the command that closes it, ranked by how much it unlocks. No agent, no
cloud, no account, and nothing on the wire.

Then the path, in the order that matters — survey what is there, take a bounded
sample, and only then explain it:

| | | contacts a device? |
|---|---|---|
| **Survey** | `iaiops scan plan` → `iaiops scan run` | preview sends nothing; the run itemises every packet class it sent |
| **Configure** | `iaiops onboard draft` → you merge it into `config.yaml` | **no** — it reads the stored scan, and writes nothing |
| **Tap** | `iaiops collect run line1 --duration 7d` | yes — and it reports what it saw **and what it missed** |
| **Declare** | `iaiops tags export` → a person fills in `role` → `iaiops tags apply --by <you>` | **no** — the `role` column comes out empty on purpose |
| **Explain** | `iaiops oee measure --since … --until …` · `iaiops investigate open` · `iaiops diag rca` | **no** — all over collected history |

**See the whole thing run against a real device in about two minutes**, including
a genuine mid-run outage, with `./demo/oee-line/run_demo.sh` — no hardware, no
configuration, nothing written outside a temporary directory.
[demo/oee-line/](demo/oee-line/) explains what each step is for and what the
numbers do and do not claim.

## Why read-first

OT is exactly where you want an agent on a tight leash. The read paths are the product; the few
write paths are OT-dangerous, off by default, and gated by MOC discipline — dry-run, one-shot
approval, undo capture, hash-chained audit.

## Proving the analysis needs no model

The analysis layers cannot reach a language model. That is a guard, not a slogan:
`tests/test_brain_is_llm_free.py` scans eight packages — `brain`, `discovery`, `runtime`,
`readiness`, `collect`, `knowledge`, `retain`, `connectors` — for any import that could reach one,
and an empty result is the guarantee. A model is used in exactly two places, and neither is
load-bearing: `rca_narrate` rephrases a verdict that was already computed and already cited, and an
agent front-end decides *which* tool to call. Remove both and the numbers are the same numbers.

That guard is static — it proves nothing *can* call a model. For a validation team the sentence
they are asked to accept is the executed one, so it is executed:

```bash
iaiops verify determinism --out determinism-record.json
```

A pinned in-repo dataset goes through availability, production counts, the Six Big Losses,
ISA-18.2 alarm load, control charts, the conservative baseline and the RCA copilot. Each result is
canonically encoded and digested; the suite runs **twice in this process and once in each of two
fresh interpreters started at different `PYTHONHASHSEED` values** — the arm that catches a set or
dict iteration order reaching a result, which a single run never can. The socket API raises
throughout, so a computation that reached for a device or a hostname fails here instead of quietly
working on a machine that happened to be online. Afterwards the run is asked what it pulled in:
a model library that was *already* loaded (an MCP server holds `iaiops.core.llm` for the opt-in
narration tool) is recorded, not judged — only what the suite itself imported can condemn it.

The record separates `result` (identical every run — the part to sign) from `context` (when and
where this run happened). **Two good runs are not byte-identical records**, and someone will diff
them, so the halves are named rather than mixed.

This is the form the claim has to take to be usable: not "our model is accurate", which is not
evidence in a GxP context, but a test case someone can write into an IQ/OQ protocol — *remove the
model, block the network, re-run the standard dataset, compare the hash* — execute, and sign.
`verify_determinism` is the same check from the MCP side; `iaiops verify suite` lists what it
covers without running it.

## How far it's actually been verified

Short version: **verified against real protocol libraries, containers and in-process servers —
not yet against real plant gear.** We grade evidence rather than saying "tested", because a real
container round-trip and a synthetic fixture are not the same claim.

| Rung | Who judges our frames | Protocols at this rung today |
|---|---|---|
| **2a** — real wire to a **third-party** server | somebody else's implementation of the spec | OPC-UA (Microsoft `opc-plc`; certificate trust enforced both ways) · Modbus TCP (`pymodbus`) · Modbus RTU (`pymodbus` over a `socat` PTY) · MQTT / Sparkplug B (a real `mosquitto` broker) · BACnet/IP (`bacpypes3`, two IPs on one subnet) · MTConnect (the Institute's own `cppagent`) · SECS/GEM (`secsgem` equipment side) · EtherNet/IP (identification) |
| **2b** — real wire to a server **we wrote** from the spec | the third-party *client* parses our frames | S7comm (`pyS7`) · Mitsubishi MC (`pymcprotocol`) · EtherNet/IP (tag layer — `pycomm3`, all three driver routes) · PROFINET-DCP |
| **2c** — real wire, but **both ends are ours** | nobody independent | Omron FINS · IO-Link · HART-IP (codec itself at rung 1, against `hart-protocol`) |
| **mock only** — protocol logic exercised, nothing on the wire | — | EtherCAT · BAS (Metasys / Niagara) · Ignition gateway |
| **3** — real physical / vendor device | the device | **zero, for every protocol** |

Each row's detail — and, per protocol, *what is still not covered* — is in
[`docs/VERIFICATION-RECORD.md`](docs/VERIFICATION-RECORD.md). That file is the
record; this table is its summary, and a test fails if the two disagree.

**Per-protocol evidence — including what each test does *not* cover — is in
[docs/VERIFICATION-RECORD.md](docs/VERIFICATION-RECORD.md)**, one row per protocol, naming the test
behind each claim. Every `待核实` is hardware-gated, not forgotten — each one names the equipment that would settle it.

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

**我们在找现场测试伙伴。** 软件里能验证的我们都验证了（真实 in-process 服务器、真实协议库、Docker 容器 loopback）——剩下的 `待核实` 清单只有真设备能回答：物理 Modbus-RTU（RS-485）、EtherCAT 从站、HART 网关、在线 BACnet 楼宇设备、在线 Metasys/Niagara BAS 控