iaiops 0.4.0__py3-none-any.whl

iaiops/__init__.py

@@ -0,0 +1,12 @@
+"""iaiops — Industrial-AIOps: governed, read-first OT/industrial data tap.
+
+A preview AI-ops tool for *reading* (and, gated, writing) industrial control
+systems across OPC-UA, Modbus-TCP, S7comm, Mitsubishi MC, MTConnect,
+MQTT/Sparkplug B, EtherNet/IP, EtherCAT, and SECS/GEM — plus a cross-protocol
+intelligence layer (dataflow / connection / subscription / tag / alarm
+diagnostics and OEE/asset analytics). Every tool runs through the shared
+governance harness (audit / budget / risk-tier / undo). Read-first: the few
+write/command tools are off by default (dry-run) and MOC-gated at high risk_tier.
+"""
+
+__version__ = "0.4.0"

iaiops/cli/__init__.py

@@ -0,0 +1,5 @@
+"""iaiops CLI package — exposes the assembled Typer ``app``."""
+
+from iaiops.cli._root import app
+
+__all__ = ["app"]

iaiops/cli/_common.py

@@ -0,0 +1,56 @@
+"""Shared helpers for iaiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+EndpointOption = Annotated[
+    str | None, typer.Option("--endpoint", "-e", help="Endpoint name from config")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from iaiops.core.runtime.connection import OTConnectionError
+
+    return (OTConnectionError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_manager(config_path: Path | None = None):
+    """Return a ConnectionManager built from config."""
+    from iaiops.core.runtime.config import load_config
+    from iaiops.core.runtime.connection import ConnectionManager
+
+    return ConnectionManager(load_config(config_path))
+
+
+def resolve_target(endpoint: str | None):
+    """Resolve an endpoint target by name (or the default endpoint)."""
+    return get_manager().target(endpoint)

iaiops/cli/_root.py

@@ -0,0 +1,78 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from iaiops.cli.analytics import analytics_app
+from iaiops.cli.diagnostics import diag_app
+from iaiops.cli.doctor import doctor_cmd
+from iaiops.cli.eip import eip_app
+from iaiops.cli.ethercat import ethercat_app
+from iaiops.cli.init import init_cmd
+from iaiops.cli.mc import mc_app
+from iaiops.cli.modbus import modbus_app
+from iaiops.cli.mqtt import mqtt_app
+from iaiops.cli.mtconnect import mtconnect_app
+from iaiops.cli.opcua import opcua_app
+from iaiops.cli.s7 import s7_app
+from iaiops.cli.secret import secret_app
+
+app = typer.Typer(
+    name="iaiops",
+    help="Governed, vendor-neutral OT data tap + intelligent troubleshooting for "
+    "AI agents (OPC-UA / Modbus / S7comm / Mitsubishi MC / MTConnect / "
+    "MQTT-Sparkplug / EtherNet-IP / EtherCAT) + OEE/asset analytics. Read-first; "
+    "writes are MOC-gated.",
+    no_args_is_help=True,
+)
+
+app.add_typer(opcua_app, name="opcua")
+app.add_typer(modbus_app, name="modbus")
+app.add_typer(s7_app, name="s7")
+app.add_typer(mc_app, name="mc")
+app.add_typer(mtconnect_app, name="mtconnect")
+app.add_typer(mqtt_app, name="mqtt")
+app.add_typer(eip_app, name="eip")
+app.add_typer(ethercat_app, name="ethercat")
+app.add_typer(diag_app, name="diag")
+app.add_typer(analytics_app, name="analytics")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("protocols")
+def protocols_cmd() -> None:
+    """Print the protocol/capability map (what iaiops supports)."""
+    import json
+
+    from rich.console import Console
+
+    from iaiops.core.brain.overview import protocols_supported
+
+    Console().print_json(json.dumps(protocols_supported(), default=str))
+
+
+@app.command("mcp")
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport)."""
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: iaiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force iaiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

iaiops/cli/analytics.py

@@ -0,0 +1,75 @@
+"""``iaiops analytics ...`` — OEE / downtime / asset-inventory (read-only).
+
+The OEE/downtime analyzers consume a JSON list (``--input file.json``) so the CLI
+stays scriptable; ``asset`` actively fingerprints configured endpoints.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from iaiops.cli._common import cli_errors, get_manager
+from iaiops.core.brain import asset_inventory as asset
+from iaiops.core.brain import oee
+
+analytics_app = typer.Typer(help="OEE / downtime / asset-inventory analytics (read-only).",
+                            no_args_is_help=True)
+console = Console()
+
+
+def _emit(data) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+def _load_json(path: Path):
+    return json.loads(Path(path).read_text("utf-8"))
+
+
+@analytics_app.command("oee")
+@cli_errors
+def oee_cmd(
+    planned_time_s: float,
+    run_time_s: float,
+    ideal_cycle_time_s: float,
+    total_count: float,
+    good_count: float,
+) -> None:
+    """Compute OEE = Availability × Performance × Quality from inputs."""
+    _emit(oee.oee_compute(planned_time_s, run_time_s, ideal_cycle_time_s,
+                          total_count, good_count))
+
+
+@analytics_app.command("downtime")
+@cli_errors
+def downtime_cmd(
+    input: Path = typer.Option(..., "--input", help="JSON file: list of {timestamp, state}"),
+    min_duration_s: float = typer.Option(0.0, "--min-duration-s"),
+) -> None:
+    """Detect + categorize stoppages from a JSON state series."""
+    _emit(oee.downtime_events(_load_json(input), None, min_duration_s))
+
+
+@analytics_app.command("oee-multidim")
+@cli_errors
+def oee_multidim_cmd(
+    input: Path = typer.Option(..., "--input", help="JSON file: list of labelled records"),
+) -> None:
+    """Aggregate OEE across dimensions (machine × part × shift) from JSON records."""
+    _emit(oee.oee_multidim(_load_json(input)))
+
+
+@analytics_app.command("asset")
+@cli_errors
+def asset_cmd(
+    endpoint: list[str] = typer.Option(None, "--endpoint", "-e",
+                                       help="Endpoint name (repeatable; omit = all)"),
+) -> None:
+    """Actively fingerprint configured endpoints into an asset register."""
+    mgr = get_manager()
+    names = list(endpoint) if endpoint else mgr.list_targets()
+    targets = [mgr.target(n) for n in names]
+    _emit(asset.asset_inventory(targets))

iaiops/cli/diagnostics.py

@@ -0,0 +1,67 @@
+"""``iaiops diag ...`` — cross-protocol intelligent troubleshooting (read-only).
+
+The flood/tag/historian analyzers consume a JSON list of events/samples; pass a
+path to a JSON file (``--input events.json``) so the CLI stays scriptable.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from iaiops.cli._common import EndpointOption, cli_errors, resolve_target
+from iaiops.core.brain import diagnostics as diag
+
+diag_app = typer.Typer(help="Cross-protocol intelligent troubleshooting (read-only).",
+                       no_args_is_help=True)
+console = Console()
+
+
+def _emit(data) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+def _load_json(path: Path):
+    return json.loads(Path(path).read_text("utf-8"))
+
+
+@diag_app.command("dataflow")
+@cli_errors
+def dataflow_cmd(
+    endpoint: EndpointOption = None,
+    ref: str = typer.Option(None, "--ref", help="Tag/node/address to read"),
+    freshness_s: int = typer.Option(60, "--freshness-s"),
+) -> None:
+    """Localize a 'no data' break across an endpoint's reachable hops."""
+    _emit(diag.diagnose_dataflow(resolve_target(endpoint), ref, freshness_s))
+
+
+@diag_app.command("alarms")
+@cli_errors
+def alarms_cmd(
+    input: Path = typer.Option(..., "--input", help="JSON file: list of alarm events"),
+) -> None:
+    """ISA-18.2 alarm-flood analysis over a JSON list of events."""
+    _emit(diag.alarm_bad_actors(_load_json(input)))
+
+
+@diag_app.command("tags")
+@cli_errors
+def tags_cmd(
+    input: Path = typer.Option(..., "--input", help="JSON file: list of {ref, samples:[...]}"),
+) -> None:
+    """Rank tag offenders by quality/flatline/range/anomaly over JSON samples."""
+    _emit(diag.tag_health(_load_json(input)))
+
+
+@diag_app.command("historian")
+@cli_errors
+def historian_cmd(
+    input: Path = typer.Option(..., "--input", help="JSON file: list of samples"),
+    gap_s: float = typer.Option(60.0, "--gap-s"),
+) -> None:
+    """Bad-tag / flatline / gap detection over a JSON sample series."""
+    _emit(diag.historian_health(_load_json(input), gap_s))

iaiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from iaiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_probe: Annotated[
+        bool, typer.Option("--skip-probe", help="Skip connectivity probe (faster)")
+    ] = False,
+) -> None:
+    """Check config and OPC-UA / Modbus endpoint reachability."""
+    from iaiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_probe=skip_probe))

iaiops/cli/eip.py

@@ -0,0 +1,74 @@
+"""``iaiops eip ...`` sub-commands (EtherNet/IP — Rockwell/AB Logix, read-first)."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+
+from iaiops.cli._common import EndpointOption, cli_errors, resolve_target
+from iaiops.connectors.eip import ops
+
+eip_app = typer.Typer(help="EtherNet/IP read-first telemetry (Allen-Bradley Logix).",
+                      no_args_is_help=True)
+console = Console()
+
+
+def _emit(data) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+@eip_app.command("info")
+@cli_errors
+def info_cmd(endpoint: EndpointOption = None) -> None:
+    """Show Logix controller identity (name/product/revision/serial)."""
+    _emit(ops.eip_controller_info(resolve_target(endpoint)))
+
+
+@eip_app.command("tags")
+@cli_errors
+def tags_cmd(endpoint: EndpointOption = None) -> None:
+    """Discover the controller's tag list (names/types/structures)."""
+    _emit(ops.eip_list_tags(resolve_target(endpoint)))
+
+
+@eip_app.command("read")
+@cli_errors
+def read_cmd(tag: str, endpoint: EndpointOption = None) -> None:
+    """Read one Logix tag (or array element)."""
+    _emit(ops.eip_read_tag(resolve_target(endpoint), tag))
+
+
+@eip_app.command("read-many")
+@cli_errors
+def read_many_cmd(
+    tags: list[str] = typer.Argument(..., help="Logix tag names to batch-read"),
+    endpoint: EndpointOption = None,
+) -> None:
+    """Batch-read many Logix tags in one request."""
+    _emit(ops.eip_read_many(resolve_target(endpoint), tags))
+
+
+@eip_app.command("write-tag")
+@cli_errors
+def write_tag_cmd(
+    tag: str,
+    value: str,
+    endpoint: EndpointOption = None,
+    apply: bool = typer.Option(False, "--apply", help="Actually write (omit = dry-run)"),
+) -> None:
+    """[HIGH RISK] Write one value to a Logix tag (dry-run unless --apply + confirm)."""
+    target = resolve_target(endpoint)
+    if not apply:
+        _emit(ops.eip_write_tag(target, tag, value, dry_run=True))
+        return
+    console.print(
+        f"[red]OT-DANGEROUS:[/] write tag '{tag}'={value} on '{target.name}'. "
+        f"未经授权勿对生产控制系统写入."
+    )
+    if not typer.confirm("Confirm you are authorized to write to this PLC?", default=False):
+        raise typer.Abort()
+    if not typer.confirm("Final confirm — apply the write now?", default=False):
+        raise typer.Abort()
+    _emit(ops.eip_write_tag(target, tag, value, dry_run=False))

iaiops/cli/ethercat.py

@@ -0,0 +1,125 @@
+"""``iaiops ethercat ...`` sub-commands (EtherCAT fieldbus, read-first).
+
+REAL pysoem/SOEM master. Requires Linux + root/CAP_NET_RAW + a dedicated NIC +
+real slaves (optional extra: ``pip install iaiops[ethercat]``). No simulator;
+macOS unsupported. Reads are non-destructive; SDO write and AL-state change are
+OT-dangerous (dry-run unless ``--apply`` + double-confirm).
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+from rich.console import Console
+
+from iaiops.cli._common import EndpointOption, cli_errors, resolve_target
+from iaiops.connectors.ethercat import ops
+
+ethercat_app = typer.Typer(
+    help="EtherCAT read-first telemetry (pysoem/SOEM; Linux+root+NIC+slaves).",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def _emit(data) -> None:
+    console.print_json(json.dumps(data, default=str))
+
+
+@ethercat_app.command("master")
+@cli_errors
+def master_cmd(endpoint: EndpointOption = None) -> None:
+    """Show master/working-counter state and expected vs found slave count."""
+    _emit(ops.ethercat_master_state(resolve_target(endpoint)))
+
+
+@ethercat_app.command("slaves")
+@cli_errors
+def slaves_cmd(endpoint: EndpointOption = None) -> None:
+    """Bus scan: enumerate slaves (id/vendor/product/rev/addr/state)."""
+    _emit(ops.ethercat_slaves(resolve_target(endpoint)))
+
+
+@ethercat_app.command("info")
+@cli_errors
+def info_cmd(slave: int, endpoint: EndpointOption = None) -> None:
+    """Detail one slave: identity, SM/FMMU config, object-dictionary summary."""
+    _emit(ops.ethercat_slave_info(resolve_target(endpoint), slave))
+
+
+@ethercat_app.command("read-sdo")
+@cli_errors
+def read_sdo_cmd(
+    slave: int,
+    index: int,
+    subindex: int = typer.Option(0, "--subindex"),
+    size: int = typer.Option(0, "--size"),
+    endpoint: EndpointOption = None,
+) -> None:
+    """CoE SDO upload: read one object-dictionary entry (e.g. read-sdo 0 4120)."""
+    _emit(ops.ethercat_read_sdo(resolve_target(endpoint), slave, index, subindex, size))
+
+
+@ethercat_app.command("read-pdo")
+@cli_errors
+def read_pdo_cmd(slave: int, endpoint: EndpointOption = None) -> None:
+    """One cyclic snapshot of a slave's input process-data image."""
+    _emit(ops.ethercat_read_pdo(resolve_target(endpoint), slave))
+
+
+@ethercat_app.command("write-sdo")
+@cli_errors
+def write_sdo_cmd(
+    slave: int,
+    index: int,
+    value: str,
+    subindex: int = typer.Option(0, "--subindex"),
+    endpoint: EndpointOption = None,
+    apply: bool = typer.Option(False, "--apply", help="Actually write (omit = dry-run)"),
+) -> None:
+    """[HIGH RISK] CoE SDO download (dry-run unless --apply + confirm).
+
+    VALUE is a hex string of the raw little-endian bytes (e.g. 'e803' = 1000 u16).
+    """
+    target = resolve_target(endpoint)
+    if not apply:
+        _emit(ops.ethercat_write_sdo(target, slave, index, value, subindex, dry_run=True))
+        return
+    console.print(
+        f"[red]OT-DANGEROUS:[/] write SDO 0x{index:04X}:{subindex}=0x{value} on "
+        f"slave {slave} of '{target.name}'. 未经授权勿对生产控制系统写入."
+    )
+    if not typer.confirm("Confirm you are authorized to write to this bus?", default=False):
+        raise typer.Abort()
+    if not typer.confirm("Final confirm — apply the SDO write now?", default=False):
+        raise typer.Abort()
+    _emit(ops.ethercat_write_sdo(target, slave, index, value, subindex, dry_run=False))
+
+
+@ethercat_app.command("set-state")
+@cli_errors
+def set_state_cmd(
+    state: str,
+    slave: int = typer.Option(-1, "--slave", help="Slave index, or -1 for the master"),
+    endpoint: EndpointOption = None,
+    apply: bool = typer.Option(False, "--apply", help="Actually transition (omit = dry-run)"),
+) -> None:
+    """[HIGH RISK] Request an AL-state transition (dry-run unless --apply + confirm).
+
+    Changing EtherCAT state can START or STOP machine motion. STATE = INIT|PREOP|SAFEOP|OP.
+    """
+    target = resolve_target(endpoint)
+    if not apply:
+        _emit(ops.ethercat_set_state(target, state, slave, dry_run=True))
+        return
+    scope = "master" if slave < 0 else f"slave {slave}"
+    console.print(
+        f"[red]OT-DANGEROUS:[/] request state '{state}' on {scope} of '{target.name}'. "
+        f"This can START or STOP machine motion. 未经授权勿对生产控制系统写入."
+    )
+    if not typer.confirm("Confirm you are authorized to change bus state?", default=False):
+        raise typer.Abort()
+    if not typer.confirm("Final confirm — apply the state change now?", default=False):
+        raise typer.Abort()
+    _emit(ops.ethercat_set_state(target, state, slave, dry_run=False))