Anomaly explanation and root-cause reasoning with LLMs

"The detector told me channel 7 crossed three sigma at 02:14. Thrilling. Nobody at 2am wants a z-score; they want to know whether to call the on-call engineer or go back to sleep."

A Diagnostic AI Agent

From a flag to an explanation

Detection and explanation are different problems, and conflating them is the most common design error in this space. Detection is a hypothesis test: is this window anomalous, yes or no, with what confidence. Explanation is abductive inference: given that it is anomalous, what is the most plausible generating cause. The first is well served by the statistics and neural scorers of earlier parts precisely because it needs no world knowledge; a residual is large or it is not. The second is exactly where large models help, because naming a cause requires connecting a numeric pattern to a mechanism (a clogged filter, a drifting reference voltage, a loosening mount) and that mapping lives in text, manuals, and prior incidents rather than in the signal itself.

Concretely, the LLM's job is to take a detection event and produce an explanation object: a short causal narrative, a ranked list of candidate root causes each with a confidence and its supporting evidence, and a recommended next action or diagnostic test. The narrative must be grounded, meaning every claim traces back to a value in the evidence you supplied, not to the model's imagination. Ungrounded fluency is the failure mode that makes operators stop trusting the system, so the whole design is organized around forcing grounding.

The evidence packet: what you put in front of the model

An LLM cannot reason over a megabyte of raw samples, and it should not try. The engineering that determines explanation quality is the construction of a compact, structured evidence packet that puts the diagnostically relevant facts in front of the model in a form it can read. A good packet has five ingredients. First, the detection metadata: which channel, which timestamp, which detector, and the anomaly score expressed as an interpretable quantity such as \(z = (x - \mu)/\sigma\) rather than a raw model output. Second, the local shape: a short, decimated snippet of the offending signal and its recent baseline, so the model can see whether this was a spike, a step, a ramp, or a variance change. Third, contemporaneous context: what the other correlated channels did in the same window, because root causes usually leave a fingerprint across several sensors. Fourth, static context: the asset's identity, its recent maintenance history, and any active work orders. Fifth, precedent: the closest past incidents retrieved from an incident store, which anchor the model in what has actually caused this signature before.

The listing below assembles such a packet from a detection event and serializes it as compact JSON, the format models parse most reliably. Note that it summarizes the waveform into a handful of descriptive statistics and a coarse trend token rather than dumping samples; this is the single highest-leverage choice in the whole pipeline.

import json
import numpy as np

def trend_token(x):
    """Collapse a window into a human-readable shape label."""
    slope = np.polyfit(np.arange(len(x)), x, 1)[0]
    jump = abs(x[-1] - x[0]) / (x.std() + 1e-9)
    if jump > 3 and slope > 0:   return "step_up"
    if jump > 3 and slope < 0:   return "step_down"
    if slope > 0:                return "ramp_up"
    if slope < 0:                return "ramp_down"
    return "flat_variance_change"

def build_evidence_packet(event, window, baseline, siblings, meta, precedents):
    z = (window[-1] - baseline.mean()) / (baseline.std() + 1e-9)
    packet = {
        "detection": {"channel": event["channel"], "ts": event["ts"],
                      "detector": event["detector"], "z_score": round(float(z), 2)},
        "signal_shape": {"trend": trend_token(window),
                         "peak": round(float(window.max()), 3),
                         "baseline_mean": round(float(baseline.mean()), 3)},
        "correlated_channels": {name: trend_token(sig)      # what else moved
                                for name, sig in siblings.items()},
        "asset_context": meta,                              # id, last service, open work orders
        "similar_past_events": precedents,                  # retrieved root causes + fixes
    }
    return json.dumps(packet, indent=2)

Listing 22.2.1 embodies the grounding discipline: every field the model will later cite already exists in the packet, so a claim like "this looks like the bearing-wear signature from work order 4471" can be checked against the similar_past_events field rather than taken on faith. Retrieval of those precedents is a sensor-language grounding problem in its own right, developed in Chapter 21.

Reasoning patterns that produce correct causes

Handing a model an evidence packet and asking "why?" gives a fluent answer, not a reliable one. Three structured reasoning patterns raise accuracy sharply. The first is differential diagnosis: instruct the model to enumerate several candidate causes first, then argue for and against each against the evidence, then rank. Borrowed from clinical reasoning, this forces breadth before commitment and suppresses the anchoring failure where the model latches onto its first guess. The second is hypothesize-and-test: the model proposes a cause, states what the evidence should show if the cause were true, and checks the packet for that signature. If a bearing fault is hypothesized, the model should predict elevated high-frequency vibration on the co-located accelerometer and then look for it in correlated_channels; absence is disconfirming. The third is causal-graph traversal, where a known dependency graph of the plant (pump feeds heat exchanger feeds outlet sensor) lets the model walk upstream from the symptomatic channel to its plausible sources rather than reasoning over an unstructured soup of signals.

These patterns matter because they convert the model's fluency from a liability into an asset. Chain-of-thought over a well-ordered evidence packet lets the model do the tedious cross-referencing a human diagnostician does, while the explicit disconfirmation step is what separates root-cause reasoning from confident storytelling. The multi-agent elaboration of these patterns, where separate agents propose and critique hypotheses, is the subject of Section 22.5.

Grounding the causal claim and evaluating it

The deepest hazard is that an LLM will narrate a cause from a correlation. Two channels moving together in one window is not a mechanism, and a model trained to be helpful will happily supply the missing "because." Three guardrails keep it honest. Insist on evidence citation: every ranked cause must point at specific packet fields, and a cause with no cited evidence is dropped, not shown. Force uncertainty expression in calibrated terms rather than false precision, connecting to the calibration discipline of Chapter 18; "moderate confidence, consistent with two of three expected signatures" beats an invented 92 percent. And keep a human in the loop for any action whose cost exceeds the model's demonstrated reliability, the guardrail architecture of Section 22.6.

Evaluation is subtle because a fluent explanation and a correct one look identical to a casual reader. You cannot score these systems on language quality alone. The workable protocol scores explanations against a labeled incident registry: for each historical anomaly with a known, confirmed root cause, does the system's top-ranked cause match, and how far down the ranked list is the truth when it misses (a top-3 recall metric). This requires the leakage-safe splitting of Chapter 5, since an incident the model saw in a retrieval store is not a fair test of its reasoning. The uncomfortable truth is that many impressive-looking anomaly copilots have never been scored this way, and a copilot that cannot beat "return the most common past cause for this asset" is not reasoning, it is guessing with good grammar.

What's Next

In Section 22.3, we scale this reasoning from a single anomaly to the flood of logs and telemetry a real operation emits, and study the industrial copilots built for exactly that: Argos, AgentFM, and CALM. You will see how the evidence-packet idea generalizes to log reasoning, how retrieval over massive telemetry histories replaces the hand-picked precedents used here, and where these production systems draw the line between what the agent decides and what it escalates to a human.