Skip to main content

Explain an anomaly with AI

Goal​

You'll get a natural-language summary of why an anomaly fired — what changed, by how much, against what baseline — without reading the JSON payload.

Status: partial (PARITY-9) — the explain panel UI is in flight. The POST /api/v1/ai/explain backend endpoint is already in place.

Prereqs​

  • An AnomalyEvent exists for an asset in your workspace. If you don't have one and want to test, the easiest way is to manually UPDATE the row counts in your sample table between two profile runs.
  • The org has an LLMConfig configured.
  • Workspace viewer role or higher (read access is sufficient).

Steps​

  1. Navigate to Anomalies. You see the list of open events.

  2. Click an anomaly row. A side drawer opens with the Explain panel.

  3. If an explanation already exists, you see it rendered as Markdown. Skip to step 5.

  4. Otherwise, click "Generate explanation". PLACEHOLDER Cloud enqueues a worker job; the UI shows a typing-cursor placeholder while the LLM responds. The first explanation typically returns in 5 – 20 seconds.

  5. Read the explanation. A good one tells you:

    • What metric deviated and by how much.
    • Whether the deviation is a sustained drift or a one-off spike.
    • Plausible upstream causes ("this pattern is consistent with a stalled ETL job").

  6. Optional: click "Regenerate" to force a fresh call. Use this if the first explanation referenced wrong context (a sign the prompt-built or the model picked up stale stats).

  7. Optional: click "Show me the numbers" to jump to the linked MetricRun rows that fed the deviation, so you can verify the LLM didn't hallucinate.

Verify​

The explanation renders inside the drawer. The model name + generation timestamp are shown at the bottom (claude-3-5-sonnet • 2026-05-11T14:22Z).

When to trust it​

  • High confidence: the LLM is summarising the baseline numbers PLACEHOLDER Cloud computed. The numbers are real.
  • Medium confidence: plausible cause attribution. The LLM doesn't have access to your pipelines; it's guessing based on the shape of the anomaly.
  • Low confidence: any specific dollar-amount or row-count claim not present in the underlying MetricRun payload. Use Show me the numbers to verify.

Cost​

Each explanation is one LLM call (a few thousand input tokens, a few hundred output tokens). Multiply by your provider's rate. Per-org budgets land with HARDEN-25.