downtime_root_cause
Read-only
Correlates downtime incident evidence (alarms, tags, state, dataflow) to rank candidate root causes, cite supporting signals, and propose a human-approved advisory action.
Instructions
[READ][risk=low] AI downtime root-cause copilot — cited verdict, ADVISORY only.
Correlates whatever evidence you supply around a downtime/incident window —
alarm events, tag samples, a diagnose_dataflow verdict, a machine-state series —
ranks candidate root causes, and cites the REAL signals behind each. Read-first:
it proposes a human-approved, undoable (MOC-gated) action but executes nothing.
Anti-hallucination: only signals present in the input are cited; thin evidence
downgrades to 'insufficient_evidence' with a 'recommended_next_data' list rather
than a confident guess. Confidence combines independent, time-correlated evidence
(signals BEFORE onset outweigh signals during it).
Args:
window: {start (ISO-8601), end? (ISO-8601), asset?, category?}. If 'end' is
omitted but state_series is given, the first running→stopped span bounds it.
alarms: Alarm/condition events — {source, timestamp, message?, priority?, state?}.
tags: Per-tag samples — {ref, samples:[scalars or {value, good|quality}],
warn_high?, alarm_high?, ...} (scored via tag_health).
dataflow: A diagnose_dataflow result dict (its 'verdict' localizes comms vs field).
state_series: {timestamp, state} samples to bound the window if 'end' is absent.
lead_window_s: How far before onset a signal may sit and still count as a cause
(default 300s); signals after onset are treated as consequences.
cause_weights: Optional per-site {cause: multiplier} override (e.g. from
learn_cause_weights) — scales each cause's evidence (1.0 = neutral
default) before the noisy-OR. Unknown causes / non-numeric weights are
rejected; values are clamped. Omit for the shipped default weighting.
include_graph: When true, also return a 'graph' block — the SAME verdict
re-projected as a causal graph {nodes, edges, mermaid, meta} (signal →
cause → downtime) for a frontend/Grafana. Pure re-shape: signal→cause
edge weights are the evidence contribution scores, cause→symptom edge
weights are the hypothesis confidences — no new reasoning. Omit for the
flat verdict only (default).
When a per-site 'historian:' block is configured (~/.iaiops/config.yaml, A7),
the 2h pre-incident window is additionally pulled from that reader and scored
as historian trend evidence — cited with its source ('historian:<name>'),
window, and sample count. Without the config, behaviour is unchanged.
Returns dict: {window, verdict ('root_cause_identified'|'multiple_candidates'|
'insufficient_evidence'), primary_cause, hypotheses:[{cause, confidence (0..1),
confidence_band, evidence:[{signal, ref, at?, lead_time_s?, detail, weight}],
recommended_action}], evidence_summary, recommended_next_data?,
anti_hallucination, graph? (when include_graph): {nodes:[{id, kind
(signal|cause|symptom), label, score, ...}], edges:[{from, to, weight,
relation (supports|attributed_to)}], mermaid, meta}}.
Example: downtime_root_cause(window={"start":"2026-06-28T10:00:00Z","asset":"line1"},
alarms=[{"source":"M1_DRIVE","timestamp":"2026-06-28T09:59:50Z",
"message":"motor overload trip"}], dataflow={"verdict":"healthy"}).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| alarms | No | ||
| window | Yes | ||
| dataflow | No | ||
| state_series | No | ||
| cause_weights | No | ||
| include_graph | No | ||
| lead_window_s | No |