detectkit 0.28.0__tar.gz → 0.30.0__tar.gz

{detectkit-0.28.0 → detectkit-0.30.0}/MANIFEST.in

@@ -3,6 +3,8 @@ include LICENSE
 include requirements.txt
 recursive-include detectkit *.py
 recursive-include detectkit/cli/assets *.md
+recursive-include detectkit/reporting/assets *.js
+recursive-include detectkit/tuning/assets *.js
 recursive-exclude tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.pyc

{detectkit-0.28.0/detectkit.egg-info → detectkit-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.28.0
+Version: 0.30.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/__init__.py

@@ -4,7 +4,7 @@ detectk - Anomaly Detection for Time-Series Metrics
 A Python library for data analysts and engineers to monitor metrics with automatic anomaly detection.
 """
 
-__version__ = "0.28.0"
+__version__ = "0.30.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/alerting/orchestrator/__init__.py

@@ -1,5 +1,6 @@
 """Public surface of the alert-orchestrator package."""
 
+from detectkit.alerting.orchestrator._replay import ReplayedEvent
 from detectkit.alerting.orchestrator._types import (
     AlertConditions,
     DetectionRecord,
@@ -13,6 +14,7 @@ __all__ = [
     "AlertOrchestrator",
     "AlertConditions",
     "DetectionRecord",
+    "ReplayedEvent",
     # Shared hydration of DetectionRecord rows from get_recent_detections
     # output (used by TaskManager and the recovery mixin).
     "hydrate_detection_records",

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -139,6 +139,7 @@ class _RecoveryMixin(_OrchestratorBase):
     def _build_recovery_data(
         self,
         detections: list[DetectionRecord],
+        incident_records: list[DetectionRecord] | None = None,
     ) -> AlertData | None:
         """Construct the AlertData payload sent as a recovery notification."""
         if not detections:
@@ -165,7 +166,9 @@ class _RecoveryMixin(_OrchestratorBase):
 
         # Reconstruct the just-ended incident so the recovery message can say how
         # long it lasted (symmetric with the anomaly alert's onset/duration).
-        incident_count, onset_ts, capped = self._resolve_incident(latest.timestamp)
+        incident_count, onset_ts, capped = self._resolve_incident(
+            latest.timestamp, records=incident_records
+        )
 
         return AlertData(
             metric_name=self.metric_name,
@@ -200,7 +203,9 @@ class _RecoveryMixin(_OrchestratorBase):
             streak_capped=capped,
         )
 
-    def _resolve_incident(self, cleared_ts: Any) -> tuple[int, Any, bool]:
+    def _resolve_incident(
+        self, cleared_ts: Any, records: list[DetectionRecord] | None = None
+    ) -> tuple[int, Any, bool]:
         """Find the anomalous run that just ended before the recovery point.
 
         Walks back from *cleared_ts* (the latest, now-clean point): skips the
@@ -209,20 +214,23 @@ class _RecoveryMixin(_OrchestratorBase):
         capped)`` — ``(0, None, False)`` when no run can be reconstructed, so the
         recovery message just omits the incident duration.
         """
-        if not self.internal:
-            return 0, None, False
-
         step = np.timedelta64(self.interval.seconds, "s")
-        if isinstance(cleared_ts, np.datetime64):
-            last_point = cleared_ts.astype("datetime64[ms]").astype(datetime)
-        else:
-            last_point = cleared_ts
-        rows = self.internal.get_recent_detections(
-            metric_name=self.metric_name,
-            last_point=last_point,
-            num_points=STREAK_LOOKBACK_POINTS,
-        )
-        records = hydrate_detection_records(rows)
+        # ``records`` lets a pure caller (alert replay) supply the in-memory
+        # detection slice instead of a DB read; production passes None and the
+        # incident is resolved from ``_dtk_detections`` as before.
+        if records is None:
+            if not self.internal:
+                return 0, None, False
+            if isinstance(cleared_ts, np.datetime64):
+                last_point = cleared_ts.astype("datetime64[ms]").astype(datetime)
+            else:
+                last_point = cleared_ts
+            rows = self.internal.get_recent_detections(
+                metric_name=self.metric_name,
+                last_point=last_point,
+                num_points=STREAK_LOOKBACK_POINTS,
+            )
+            records = hydrate_detection_records(rows)
         if not records:
             return 0, None, False
 

detectkit-0.30.0/detectkit/alerting/orchestrator/_replay.py

@@ -0,0 +1,258 @@
+"""Pure historical replay of alert/recovery/no-data events.
+
+Reconstructs the alert events the orchestrator *would have* produced over a
+historical period from already-persisted detections — **without** any channel
+dispatch, DB state writes or wall-clock. It is the offline counterpart of the
+live ``should_alert`` / ``should_send_recovery`` / ``should_alert_no_data`` path:
+state (last alert / last recovery) is simulated in memory and the decision at
+every grid point is evaluated *causally* (only records with ``timestamp <= t``,
+since the windowed detector is causal), reusing the exact same quorum,
+consecutive-walk, cooldown and recovery arithmetic as the live path.
+
+Used to answer "what would these detections have alerted on over this window"
+for backtesting / autotune alert-window sweeps, where firing real channels and
+mutating ``_dtk_alert_states`` would be wrong.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+import numpy as np
+
+from detectkit.alerting.channels.base import AlertData
+from detectkit.alerting.orchestrator._base import STREAK_LOOKBACK_POINTS, _OrchestratorBase
+from detectkit.alerting.orchestrator._types import DetectionRecord
+from detectkit.core.interval import Interval
+
+
+@dataclass(frozen=True)
+class ReplayedEvent:
+    """One alert event reconstructed by :meth:`_ReplayMixin.replay`.
+
+    ``kind`` is ``"anomaly"``, ``"recovery"`` or ``"no_data"``; ``timestamp`` is
+    the grid point at which the event fired (the simulated "now"); ``alert_data``
+    is identical in shape to a live :class:`AlertData` (built via the same
+    ``_build_*`` helpers as the live path).
+    """
+
+    kind: str
+    timestamp: np.datetime64
+    alert_data: AlertData
+
+
+class _ReplayMixin(_OrchestratorBase):
+    def replay(
+        self,
+        detections: list[DetectionRecord],
+        value_at: dict[np.datetime64, float | None],
+        start: datetime,
+        end: datetime,
+    ) -> list[ReplayedEvent]:
+        """Reconstruct alert/recovery/no-data events over ``[start, end]``.
+
+        Forward pass over every interval boundary in the closed range
+        ``[start, end]``. At each grid point ``t`` the decision is evaluated
+        causally — only ``detections`` with ``timestamp <= t`` are considered —
+        reusing the live quorum / consecutive-walk / cooldown / recovery logic.
+        Simulated state (last alert / last recovery) lives in memory, so nothing
+        is dispatched and no DB row is written.
+
+        Args:
+            detections: every persisted detection over the period (any order;
+                the same per-detector-per-timestamp shape the live path uses).
+            value_at: grid ``np.datetime64`` → value, with ``None`` for a
+                missing / NaN datapoint (drives the no-data check).
+            start: first grid boundary to evaluate (inclusive).
+            end: last grid boundary to evaluate (inclusive).
+
+        Returns:
+            The fired events in chronological order.
+        """
+        by_time = self._group_by_timestamp(detections)
+
+        sim_last_alert: np.datetime64 | None = None
+        sim_last_recovery: np.datetime64 | None = None
+        events: list[ReplayedEvent] = []
+
+        for t in self._replay_grid(start, end):
+            # No-data fires independently of the quorum (a single binary
+            # metric-level signal), only when configured and not in cooldown.
+            if (
+                self.alert_config
+                and getattr(self.alert_config, "no_data_alert", False)
+                and value_at.get(t) is None
+                and not self._replay_in_cooldown(t, sim_last_alert, sim_last_recovery)
+            ):
+                last_point = t.astype("datetime64[ms]").astype(datetime)
+                events.append(
+                    ReplayedEvent("no_data", t, self._build_no_data_alert_data(last_point))
+                )
+                sim_last_alert = t
+                continue
+
+            causal = {ts: recs for ts, recs in by_time.items() if ts <= t}
+            ts_desc = sorted(causal, reverse=True)
+
+            consecutive, latest_quorum, direction = self._count_consecutive_anomalies(
+                causal, ts_desc
+            )
+            fired = (
+                latest_quorum is not None
+                and consecutive >= self.conditions.consecutive_anomalies
+                and not self._replay_in_cooldown(t, sim_last_alert, sim_last_recovery)
+            )
+
+            if fired:
+                assert latest_quorum is not None  # narrowed by ``fired``
+                streak, onset, capped = self._replay_streak(causal, ts_desc)
+                ad = self._build_alert_data(latest_quorum, streak, direction, onset, capped)
+                events.append(ReplayedEvent("anomaly", t, ad))
+                sim_last_alert = t
+            elif (
+                self.alert_config
+                and getattr(self.alert_config, "notify_on_recovery", False)
+                and sim_last_alert is not None
+                and (sim_last_recovery is None or sim_last_recovery < sim_last_alert)
+                and self._replay_recovered(causal, ts_desc, sim_last_alert)
+            ):
+                slice_ = [d for d in detections if d.timestamp <= t]
+                # Pure replay: resolve the just-ended incident from the in-memory
+                # slice, never from the DB (keeps replay standalone).
+                rd = self._build_recovery_data(slice_, incident_records=slice_)
+                if rd is not None:
+                    events.append(ReplayedEvent("recovery", t, rd))
+                    sim_last_recovery = t
+
+        return events
+
+    def _replay_grid(self, start: datetime, end: datetime) -> list[np.datetime64]:
+        """Every interval boundary in the closed range ``[start, end]``.
+
+        Boundaries are produced in ``datetime64[ms]`` so they compare exactly
+        with hydrated detection timestamps and ``value_at`` keys.
+        """
+        step = timedelta(seconds=self.interval.seconds)
+        grid: list[np.datetime64] = []
+        cur = start
+        while cur <= end:
+            grid.append(np.datetime64(cur, "ms"))
+            cur = cur + step
+        return grid
+
+    def _replay_in_cooldown(
+        self,
+        t: np.datetime64,
+        sim_last_alert: np.datetime64 | None,
+        sim_last_recovery: np.datetime64 | None,
+    ) -> bool:
+        """In-memory analog of :meth:`_CooldownMixin._is_in_cooldown`.
+
+        Elapsed time is measured on the grid (``t - sim_last_alert``) rather than
+        from the wall clock. ``cooldown_reset_on_recovery`` clears the cooldown
+        when a recovery has been simulated since the last alert.
+        """
+        if not self.alert_config or not getattr(self.alert_config, "alert_cooldown", None):
+            return False
+        if sim_last_alert is None:
+            return False
+
+        cooldown = np.timedelta64(Interval(self.alert_config.alert_cooldown).seconds, "s")
+        elapsed = (t - sim_last_alert).astype("timedelta64[s]")
+
+        if getattr(self.alert_config, "cooldown_reset_on_recovery", True):
+            if sim_last_recovery is not None and sim_last_recovery > sim_last_alert:
+                return False
+
+        return bool(elapsed < cooldown)
+
+    def _replay_recovered(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        ts_desc: list[np.datetime64],
+        sim_last_alert: np.datetime64,
+    ) -> bool:
+        """Pure half of :meth:`_RecoveryMixin._check_recovery_since_last_alert`.
+
+        Returns ``True`` when the metric has recovered as of the latest causal
+        point: no blocking anomalies under the trigger direction, OR no causal
+        detections strictly after the last simulated alert.
+        """
+        if not ts_desc:
+            # No detections at all → nothing blocking → recovered.
+            return True
+
+        # No fresh detections after the alert → assume recovery (mirrors the
+        # live "no fresh detections" branch).
+        if not any(ts > sim_last_alert for ts in ts_desc):
+            return True
+
+        latest_ts = ts_desc[0]
+        latest_anomalies = [d for d in causal[latest_ts] if d.is_anomaly]
+
+        policy = self.conditions.direction
+        if policy == "down":
+            blocking = [d for d in latest_anomalies if d.direction == "down"]
+        elif policy == "up":
+            blocking = [d for d in latest_anomalies if d.direction == "up"]
+        elif policy == "same":
+            trigger_direction = self._replay_trigger_direction(causal, sim_last_alert)
+            if trigger_direction is None:
+                blocking = latest_anomalies  # conservative fallback
+            else:
+                blocking = [d for d in latest_anomalies if d.direction == trigger_direction]
+        else:  # "any" / unknown — preserve historical behaviour
+            blocking = latest_anomalies
+
+        return len(blocking) == 0
+
+    def _replay_trigger_direction(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        sim_last_alert: np.datetime64,
+    ) -> str | None:
+        """Direction of the anomaly that triggered the simulated last alert.
+
+        Pure analog of :meth:`_RecoveryMixin._get_alert_trigger_direction`: the
+        live code reads the single detection row at the alert timestamp; here the
+        alert fired at the grid point ``sim_last_alert``, so the triggering
+        quorum is the latest causal point at or before it.
+        """
+        candidates = [ts for ts in causal if ts <= sim_last_alert]
+        if not candidates:
+            return None
+        latest_ts = max(candidates)
+        anomalies = [d for d in causal[latest_ts] if d.is_anomaly]
+        if not anomalies:
+            return None
+
+        _, direction = self._quorum_at(anomalies, None)
+        if direction in ("up", "down"):
+            return direction
+
+        ups = sum(1 for d in anomalies if d.direction == "up")
+        downs = sum(1 for d in anomalies if d.direction == "down")
+        if ups > downs:
+            return "up"
+        if downs > ups:
+            return "down"
+        return None
+
+    def _replay_streak(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        ts_desc: list[np.datetime64],
+    ) -> tuple[int, np.datetime64, bool]:
+        """In-memory analog of :meth:`_DecisionMixin._resolve_streak`.
+
+        Re-walks the same direction-aware quorum logic over the causal records to
+        get the *true* streak length, then derives the onset and the cap flag the
+        same way the live path does.
+        """
+        latest_ts = ts_desc[0]
+        step = np.timedelta64(self.interval.seconds, "s")
+        count, _, _ = self._count_consecutive_anomalies(causal, ts_desc)
+        count = max(count, 1)
+        capped = count >= STREAK_LOOKBACK_POINTS
+        return count, latest_ts - step * (count - 1), capped

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/alerting/orchestrator/orchestrator.py

@@ -6,12 +6,14 @@ from detectkit.alerting.orchestrator._cooldown import _CooldownMixin
 from detectkit.alerting.orchestrator._decision import _DecisionMixin
 from detectkit.alerting.orchestrator._dispatch import _DispatchMixin
 from detectkit.alerting.orchestrator._recovery import _RecoveryMixin
+from detectkit.alerting.orchestrator._replay import _ReplayMixin
 
 
 class AlertOrchestrator(
     _DecisionMixin,
     _CooldownMixin,
     _RecoveryMixin,
+    _ReplayMixin,
     _DispatchMixin,
 ):
     """Coordinates alert decisions, cooldown, recovery and dispatch.
@@ -21,6 +23,8 @@ class AlertOrchestrator(
     * ``_DecisionMixin`` — should we alert? builds AlertData.
     * ``_CooldownMixin`` — suppress within the configured window.
     * ``_RecoveryMixin`` — direction-aware "all-clear" detection.
+    * ``_ReplayMixin``   — pure historical replay of alert/recovery/no-data
+      events (no dispatch, no DB state, no wall-clock).
     * ``_DispatchMixin``  — ship to channels and stamp state.
     """
 

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/autotune/html_labeler.py

@@ -67,96 +67,116 @@ _TEMPLATE = """<!doctype html>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <link rel="icon" type="image/svg+xml" href="__FAVICON__">
 <title>detectkit · label incidents · __METRIC__</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&family=Schibsted+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">
 <style>
   :root {
-    --clay:#d15b36; --clay-700:#b4471f; --paper:#f5f1e8; --muted:#6e675b; --faint:#9a9384;
+    --clay:#d15b36; --clay-700:#b4471f; --ink:#1b1916; --muted:#6e675b; --faint:#9a9384;
+    --paper:#f5f1e8; --surface:#fbf9f3; --border:#e6e0d4;
     --term-bg:#211e1a; --term-surface:#1b1916; --term-border:#332f29; --term-text:#c9c2b4;
-    --anomaly:#d63232; --nodata:#f0ad4e;
+    --accent-green:#2e9e73; --anomaly:#d63232; --nodata:#f0ad4e;
+    --panel-shadow:0 24px 60px -30px rgba(27,25,22,.45);
     --ui:'Schibsted Grotesk',ui-sans-serif,system-ui,-apple-system,'Segoe UI',Roboto,sans-serif;
     --mono:'JetBrains Mono',ui-monospace,'SFMono-Regular',Menlo,Consolas,monospace;
   }
   * { box-sizing: border-box; }
-  body { font-family: var(--ui); margin: 0; background: var(--term-bg); color: var(--term-text);
+  body { font-family: var(--ui); margin: 0; background: var(--paper); color: var(--ink);
     -webkit-font-smoothing: antialiased; }
-  .shell { max-width: 1080px; margin: 0 auto; padding: 22px 22px 44px; }
-  .brand { display:flex; align-items:center; gap:9px; margin-bottom: 14px; }
+  .shell { max-width: 1100px; margin: 0 auto; padding: 26px 26px 48px; }
+  .brand { display:flex; align-items:center; gap:9px; margin-bottom: 18px; }
   .brand svg { width: 26px; height: 26px; border-radius: 7px; display:block; }
-  .brand b { color: var(--paper); font-weight: 600; font-size: 15px; letter-spacing: .2px; }
-  .brand span { color: var(--faint); font-size: 12px; }
-  h1 { font-size: 18px; line-height: 1.3; margin: 0 0 6px; color: var(--paper); font-weight: 600; }
-  h1 code { color: var(--clay); font-family: var(--mono); font-size: .82em; }
-  .ichip { display:inline-flex; align-items:center; gap:6px; vertical-align: middle; margin-left: 8px;
-    font-family: var(--mono); font-size: 12px; font-weight: 500; color: var(--paper);
-    background: rgba(209,91,54,0.16); border: 1px solid var(--clay); border-radius: 999px; padding: 3px 10px; }
+  .brand b { color: var(--ink); font-weight: 600; font-size: 15px; letter-spacing: .2px; }
+  .brand span { color: var(--muted); font-size: 12px; }
+  .head { display:flex; align-items:flex-start; gap:12px; margin-bottom: 14px; }
+  .head .bar { flex: 0 0 auto; width: 4px; align-self: stretch; min-height: 38px;
+    border-radius: 999px; background: var(--clay); margin-top: 2px; }
+  .head .htext { min-width: 0; }
+  h1 { font-size: 22px; line-height: 1.25; margin: 0 0 5px; color: var(--ink); font-weight: 700;
+    letter-spacing: -.01em; display:flex; align-items:center; flex-wrap:wrap; gap: 9px; }
+  h1 code { color: var(--clay); font-family: var(--mono); font-size: .7em; font-weight: 600; }
+  .subline { color: var(--muted); font-family: var(--mono); font-size: 12.5px; margin: 0; }
+  .ichip { display:inline-flex; align-items:center; gap:6px; vertical-align: middle;
+    font-family: var(--mono); font-size: 11.5px; font-weight: 500; color: var(--clay-700);
+    background: var(--surface); border: 1px solid var(--border); border-radius: 999px; padding: 3px 11px; }
   .ichip .d { width:6px; height:6px; border-radius:50%; background: var(--clay); }
-  .ichip b { color: var(--clay); font-weight: 700; }
-  .hint { color: var(--faint); font-size: 13px; margin: 0 0 18px; line-height: 1.55; }
-  .hint code, code.k { color: var(--term-text); font-family: var(--mono); font-size: 12px;
-    background: var(--term-surface); border: 1px solid var(--term-border); border-radius: 5px; padding: 1px 6px; }
+  .ichip b { color: var(--clay-700); font-weight: 700; }
+  .hint { color: var(--muted); font-size: 13px; margin: 0 0 18px; line-height: 1.55; }
+  .hint code, code.k { color: var(--ink); font-family: var(--mono); font-size: 12px;
+    background: var(--surface); border: 1px solid var(--border); border-radius: 5px; padding: 1px 6px; }
   .toolbar { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin-bottom: 12px; }
   button { font-family: var(--ui); font-size: 13px; font-weight: 500; border: 0; border-radius: 7px;
     padding: 9px 15px; cursor: pointer; transition: background .12s ease, border-color .12s ease, color .12s ease; }
   button.primary { background: var(--clay); color: #fff; }
   button.primary:hover { background: var(--clay-700); }
-  button.primary:disabled { background: var(--term-border); color: var(--faint); cursor: default; }
-  button.ghost { background: transparent; color: var(--term-text); border: 1px solid var(--term-border); }
-  button.ghost:hover { border-color: var(--faint); color: var(--paper); }
-  button.ghost.active { border-color: var(--nodata); color: var(--paper); background: rgba(240,173,78,0.16); }
-  input.setname { background: var(--term-surface); color: var(--paper); border: 1px solid var(--term-border);
+  button.primary:disabled { background: var(--border); color: var(--faint); cursor: default; }
+  button.ghost { background: var(--surface); color: var(--ink); border: 1px solid var(--border); }
+  button.ghost:hover { border-color: var(--clay); color: var(--clay-700); }
+  button.ghost.active { border-color: var(--nodata); color: var(--ink); background: rgba(240,173,78,0.18); }
+  input.setname { background: var(--surface); color: var(--ink); border: 1px solid var(--border);
     border-radius: 7px; padding: 9px 11px; font-family: var(--ui); font-size: 13px; min-width: 200px; }
-  input.setname::placeholder { color: var(--muted); }
+  input.setname::placeholder { color: var(--faint); }
   input.setname:focus { outline: none; border-color: var(--clay); }
-  .summary { margin-left: auto; color: var(--faint); font-size: 12.5px; font-family: var(--mono); }
-  .summary b { color: var(--clay); font-weight: 600; }
+  .summary { margin-left: auto; color: var(--muted); font-size: 12.5px; font-family: var(--mono); }
+  .summary b { color: var(--clay-700); font-weight: 600; }
   .savemsg { margin: 4px 2px 0; font-size: 13px; display: none; }
-  .savemsg.ok { display: block; color: var(--accent-green, #2e9e73); }
+  .savemsg.ok { display: block; color: var(--accent-green); }
   .savemsg.err { display: block; color: var(--anomaly); }
-  .savemsg.info { display: block; color: var(--faint); }
+  .savemsg.info { display: block; color: var(--muted); }
   .thbar { display:none; flex-wrap:wrap; gap:12px; align-items:center; margin: 0 0 12px;
-    padding: 11px 13px; border: 1px solid var(--nodata); border-radius: 9px; background: var(--term-surface); }
-  .thbar .thlabel { color: var(--nodata); font-size: 12.5px; font-weight: 600; }
-  .thbar label { color: var(--faint); font-size: 12.5px; display:inline-flex; align-items:center; gap:6px; }
-  .thbar select, .thbar input { background: var(--term-bg); color: var(--paper); border: 1px solid var(--term-border);
+    padding: 11px 13px; border: 1px solid var(--nodata); border-radius: 9px; background: var(--surface); }
+  .thbar .thlabel { color: var(--clay-700); font-family: var(--mono); font-size: 11px; font-weight: 600;
+    letter-spacing: .06em; text-transform: uppercase; }
+  .thbar label { color: var(--muted); font-size: 12.5px; display:inline-flex; align-items:center; gap:6px; }
+  .thbar select, .thbar input { background: var(--paper); color: var(--ink); border: 1px solid var(--border);
     border-radius: 6px; padding: 6px 8px; font-family: var(--ui); font-size: 12.5px; }
   .thbar input.num { width: 84px; font-family: var(--mono); }
   .thbar input:focus, .thbar select:focus { outline: none; border-color: var(--nodata); }
   .thbar button { padding: 7px 13px; }
   .thbar .thscope { color: var(--faint); font-size: 12px; white-space: nowrap; }
   .thbar .thscope.hint { font-style: italic; }
-  .thbar .thscope b { color: var(--nodata); font-weight: 600; font-style: normal; }
+  .thbar .thscope b { color: var(--clay-700); font-weight: 600; font-style: normal; }
   canvas#c { width: 100%; height: clamp(300px, 44vh, 500px); display:block; touch-action: none;
-    background: var(--term-surface); border: 1px solid var(--term-border); border-radius: 10px; cursor: crosshair; }
-  .zoombar { display:flex; align-items:center; gap:8px; margin: 10px 0 6px; }
-  .rangelbl { margin-left: auto; color: var(--faint); font-size: 12px; font-family: var(--mono); }
+    background: var(--term-bg); border: 1px solid var(--term-border); border-radius: 12px; cursor: crosshair;
+    box-shadow: var(--panel-shadow); }
+  .zoombar { display:flex; align-items:center; gap:8px; margin: 12px 0 6px; }
+  .rangelbl { margin-left: auto; color: var(--muted); font-size: 12px; font-family: var(--mono); }
   canvas#ov { width: 100%; height: 66px; display:block; touch-action: none;
-    background: var(--term-surface); border: 1px solid var(--term-border); border-radius: 10px; cursor: grab; }
-  .navhint { color: var(--faint); font-size: 12px; margin: 7px 2px 0; line-height: 1.55; }
+    background: var(--term-bg); border: 1px solid var(--term-border); border-radius: 12px; cursor: grab;
+    box-shadow: var(--panel-shadow); }
+  .navhint { color: var(--faint); font-size: 12px; margin: 8px 2px 0; line-height: 1.55; }
   .empty { color: var(--faint); font-size: 13px; margin: 18px 2px; font-style: italic; }
   ul { list-style: none; margin: 16px 0 0; padding: 0; }
   li { display:flex; align-items:center; gap:11px; padding: 9px 12px; font-size: 13px; flex-wrap: wrap;
-    border: 1px solid var(--term-border); border-radius: 8px; margin-bottom: 7px; background: var(--term-surface); }
-  li.sel { border-color: var(--clay); background: rgba(209,91,54,0.10); }
+    border: 1px solid var(--border); border-radius: 8px; margin-bottom: 7px; background: var(--surface); }
+  li.sel { border-color: var(--clay); background: rgba(209,91,54,0.07); }
   li .dot { width:9px; height:9px; border-radius:50%; background: var(--anomaly); flex: 0 0 auto; }
-  li .span { font-family: var(--mono); color: var(--term-text); }
-  li .dur { color: var(--faint); font-size: 12px; }
-  li input.desc { flex: 1 1 220px; min-width: 160px; background: var(--term-bg); color: var(--paper);
-    border: 1px solid var(--term-border); border-radius: 6px; padding: 6px 9px; font-family: var(--ui); font-size: 12.5px; }
-  li input.desc::placeholder { color: var(--muted); }
+  li .span { font-family: var(--mono); color: var(--ink); }
+  li .dur { color: var(--muted); font-size: 12px; }
+  li input.desc { flex: 1 1 220px; min-width: 160px; background: var(--paper); color: var(--ink);
+    border: 1px solid var(--border); border-radius: 6px; padding: 6px 9px; font-family: var(--ui); font-size: 12.5px; }
+  li input.desc::placeholder { color: var(--faint); }
   li input.desc:focus { outline: none; border-color: var(--clay); }
   li button { margin-left: auto; padding: 5px 11px; font-size: 12px; }
   li button.focus { margin-left: auto; }
   li button.focus + button { margin-left: 0; }
-  footer { margin-top: 26px; padding-top: 14px; border-top: 1px solid var(--term-border);
+  footer { margin-top: 26px; padding-top: 14px; border-top: 1px solid var(--border);
     color: var(--faint); font-size: 12px; line-height: 1.6; }
-  footer code { font-family: var(--mono); color: var(--term-text); }
+  footer code { font-family: var(--mono); color: var(--muted); }
 </style>
 <div class="shell">
   <div class="brand">
     <svg viewBox="0 0 100 100" aria-hidden="true"><rect x="3" y="3" width="94" height="94" rx="26" fill="#D15B36"/><polyline points="14,62 36,62 50,22 64,62 86,62" fill="none" stroke="#FBF9F3" stroke-width="8" stroke-linecap="round" stroke-linejoin="round"/><circle cx="50" cy="22" r="6.5" fill="#FBF9F3"/></svg>
     <b>detectkit</b><span>· incident labeler</span>
   </div>
-  <h1>Label incidents — <code>__METRIC__</code><span id="intervalchip" class="ichip"
-    title="The metric's sampling interval — the spacing between points, taken straight from the metric."></span></h1>
+  <div class="head">
+    <span class="bar" aria-hidden="true"></span>
+    <div class="htext">
+      <h1>Label incidents <code>__METRIC__</code><span id="intervalchip" class="ichip"
+        title="The metric's sampling interval — the spacing between points, taken straight from the metric."></span></h1>
+      <p class="subline">incident labeler · all times UTC</p>
+    </div>
+  </div>
   <p class="hint">Click-drag across the chart to mark each real incident, add a short description, then
   <b>Export</b>. Save the file into <code class="k">incidents/__METRIC__/</code> and run
   <code class="k">dtk autotune --select __METRIC__ --incidents incidents/__METRIC__/</code></p>

{detectkit-0.28.0 → detectkit-0.30.0}/detectkit/cli/assets/claude/rules/autotune.md

@@ -10,6 +10,14 @@ A tuned config is an ordinary detectkit config (one chosen detector reusing the
 same windowed detectors and `detector_id` identity). The fastest path is the
 **`dtk-autotune`** skill, which runs the whole flow conversationally.
 
+> **Prefer to tune by hand?** `dtk tune --select <metric>` is the interactive,
+> human-in-the-loop sibling: it opens a browser view of the real series, lets you
+> turn the knobs and watch the band recompute live, and on **Apply** writes the
+> config back into the metric YAML **in place** (archiving the previous version to
+> `metrics/.history/<metric>/` first). Use `autotune` to search automatically and
+> emit a new file; use `tune` to dial a detector in by eye and commit it. See
+> `cli.md`.
+
 ## What it searches
 
 1. **Seasonality** — greedily builds the best `seasonality_components` grouping
@@ -57,7 +65,7 @@ ratios to choose.
 
 ```bash
 dtk autotune --select <sel> [--incidents FILE] [--label] [--scoring METRIC] \
-             [--from DATE] [--to DATE] [--profile NAME] [--force] [--dry-run]
+             [--from DATE] [--to DATE] [--profile NAME] [--force] [--dry-run] [--report]
 ```
 
 - `--incidents FILE|DIR` — a labels file (below) → **supervised** tuning. May be a
@@ -80,6 +88,12 @@ dtk autotune --select <sel> [--incidents FILE] [--label] [--scoring METRIC] \
 - `--scoring` — `mcc` (default), `f1`, `f_beta`, `balanced_accuracy`, `roc_auc`,
   `pr_auc`. MCC uses the whole confusion matrix and suits rare anomalies.
 - `--dry-run` — run the search but persist nothing and write no config.
+- `--report [PATH]` — after tuning, emit a self-contained **HTML report** for the
+  winning config over the training window (values, confidence band, anomalies,
+  replayed alerts; offline). Bare `--report` writes
+  `reports/<name>__tuned_<id>.html`; pass a directory or a `.html` path to
+  override. `dtk run --select <m> --report` produces the same report from the
+  live config.
 - Selectors match `dtk run`. Tuning reads loaded datapoints — if empty, run
   `dtk run --select <m> --steps load` (optionally `--from`) first.
 
@@ -215,7 +229,12 @@ LIMIT 5
 
 ## Reading the tuned detector's results
 
-To see the winning detector at work, join recent datapoints with its detections
+The quickest view is an **HTML report**: add `--report` to the tune (or run
+`dtk run --select <m> --report` later) to get a self-contained file charting the
+winning detector's values, confidence band, flagged anomalies and the alerts it
+would fire, with a period selector — no BI/SQL setup, offline.
+
+To query the raw rows instead, join recent datapoints with its detections
 (`value` vs `confidence_lower/upper` vs `is_anomaly`) for the
 `winning_detector_id` — see the per-backend query templates in the
 **`dtk-autotune`** skill and in the visualizing-results guide.