detectkit 0.27.0__tar.gz → 0.29.0__tar.gz

{detectkit-0.27.0 → detectkit-0.29.0}/MANIFEST.in

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

{detectkit-0.27.0/detectkit.egg-info → detectkit-0.29.0}/PKG-INFO

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

{detectkit-0.27.0 → detectkit-0.29.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.27.0"
+__version__ = "0.29.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.27.0 → detectkit-0.29.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.27.0 → detectkit-0.29.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.29.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.27.0 → detectkit-0.29.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.27.0 → detectkit-0.29.0}/detectkit/autotune/crossval.py

@@ -61,6 +61,29 @@ def predictions_from_results(
     return y_pred, y_score, valid
 
 
+def _aggregate(per_fold: list[float], stability_lambda: float) -> tuple[float, float]:
+    """Mean across folds minus a **downside-only** dispersion penalty.
+
+    Returns ``(aggregate, penalty)``. The penalty uses the semi-deviation of the
+    folds that score *below* the mean, not the full ``std``: a config that simply
+    scores *higher* on some folds — e.g. a recency-aware baseline that fits the
+    current regime better than stale history — should not be punished for that
+    *upside* spread. Penalizing full ``std`` did exactly that, biasing the search
+    against regime-adaptive configs; downside-only keeps the guard against
+    genuinely unstable candidates while letting an adaptive one win.
+    """
+    arr = np.asarray(per_fold, dtype=float)
+    mean = float(np.mean(arr))
+    # Downside deviation: square only the shortfalls below the mean (upside → 0),
+    # averaged over ALL folds. This is always <= the full std, and reduces to 0
+    # when folds are equal — so a config that's merely *better* on recent folds is
+    # not penalized, only one that drops below par on some.
+    deficits = np.minimum(arr - mean, 0.0)
+    downside = float(np.sqrt(np.mean(deficits**2)))
+    penalty = stability_lambda * downside
+    return mean - penalty, penalty
+
+
 def run_cv(
     detector: BaseDetector,
     data: dict[str, np.ndarray],
@@ -95,7 +118,5 @@ def run_cv(
     if not per_fold:
         return FoldScores(per_fold=[], aggregate=0.0, stability_penalty=0.0)
 
-    arr = np.asarray(per_fold, dtype=float)
-    penalty = settings.stability_lambda * float(np.std(arr))
-    aggregate = float(np.mean(arr)) - penalty
+    aggregate, penalty = _aggregate(per_fold, settings.stability_lambda)
     return FoldScores(per_fold=per_fold, aggregate=aggregate, stability_penalty=penalty)

{detectkit-0.27.0 → detectkit-0.29.0}/detectkit/autotune/grid_search.py

@@ -13,10 +13,13 @@ from __future__ import annotations
 
 from typing import Any
 
+import numpy as np
+
 from detectkit.autotune._base import _AutoTuneBase
 from detectkit.autotune._types import CandidateEval
 from detectkit.autotune.window_select import (
     detect_level_shift,
+    half_life_grid,
     min_samples_for,
     select_window,
     trend_present,
@@ -50,18 +53,23 @@ def grid_search(
         # enough to inflate the global MAD it is measured against. When that
         # happens the engine treats the series as stationary — prefers the largest
         # window, skips detrend — and the baseline quietly averages two regimes.
-        # Surface it so the user can narrow the window and re-tune; advisory only.
-        found, sigmas, frac = detect_level_shift(tuner)
+        # Surface it (with a concrete --from date) so the user can narrow the
+        # window and re-tune; advisory only.
+        found, sigmas, idx = detect_level_shift(tuner)
         if found:
+            timestamps = tuner.data["timestamp"]
+            n = int(len(timestamps))
+            from_date = str(np.datetime64(timestamps[idx], "D"))
+            pct = round(idx / n * 100) if n else 0
             tuner.log(
                 "regime",
                 f"series reads stationary, but a large level shift (~{sigmas:.1f}σ "
-                f"within-regime) sits ~{round(frac * 100)}% into the training window — "
-                "the midpoint trend test misses an off-center shift, so the baseline "
-                "may average two regimes. If the earlier regime is stale, re-tune with "
-                "`--from <date after the shift>` (or set `autotune.max_history`).",
+                f"within-regime) sits ~{pct}% in, around {from_date} — the midpoint "
+                "trend test misses an off-center shift, so the baseline may average "
+                f"two regimes. If the earlier regime is stale, re-tune with "
+                f"`--from {from_date}` (or set `autotune.max_history`).",
                 shift_sigmas=round(sigmas, 2),
-                shift_fraction=round(frac, 3),
+                shift_at=from_date,
             )
     eps = tuner.settings.min_improvement
     best_overall: CandidateEval | None = None
@@ -104,6 +112,18 @@ def grid_search(
             if ev is not None and ev.score > best.score + eps:
                 best, accepted["window_weights"] = ev, weights
 
+        # Axis 2b: half-life of the recency weighting — only when exponential
+        # weighting was adopted. The detector defaults to a fixed half-life; this
+        # lets the search pick a faster-forgetting baseline that tracks the current
+        # regime (the term that matters on a metric that shifted level).
+        if accepted.get("window_weights") == "exponential":
+            for half_life in half_life_grid(accepted["window_size"], accepted["min_samples"]):
+                if half_life == accepted.get("half_life"):
+                    continue
+                ev = tuner.safe_evaluate(detector_type, {**accepted, "half_life": half_life})
+                if ev is not None and ev.score > best.score + eps:
+                    best, accepted["half_life"] = ev, half_life
+
         # Axis 3: detrend (gated by the trend pre-test).
         if has_trend:
             for detrend in (None, "linear"):

{detectkit-0.27.0 → detectkit-0.29.0}/detectkit/autotune/html_labeler.py

@@ -216,6 +216,8 @@ const INTERVAL_S = __INTERVAL__;
 // Incidents to seed the editor with (editing an existing labels file). Each is
 // {start, end, label} in "YYYY-MM-DD HH:MM:SS" UTC; a point is start === end.
 const PRELOAD = __INCIDENTS__;
+// Threshold-capture window(s) to restore (from a saved file): [{start, end}] UTC.
+const CAPWINS = __CAPTURE_WINDOWS__;
 const pts = DATA.points.map(p => ({ts: Date.parse(p.t.replace(' ','T')+'Z'), v: p.v}));
 const N = pts.length;
 const vraw = pts.filter(p => p.v !== null).map(p => p.v);
@@ -242,6 +244,12 @@ let selObj = null, hoverRow = -1, hoverDel = -1, thMode = false, thHover = null;
 // Threshold-capture window: thDown tracks a press, thDragWin a live drag, capWin
 // the committed custom window (null → capture within the current view).
 let thDown = null, thDragWin = null, capWin = null;
+// Restore a saved capture window so re-opening a labels file keeps the painted
+// regime scope (only shown once threshold capture is toggled on).
+if (CAPWINS && CAPWINS.length) { const w0 = CAPWINS[0];
+  const a = Date.parse(String(w0.start).replace(' ','T')+'Z'),
+        b = Date.parse(String(w0.end).replace(' ','T')+'Z');
+  if (!isNaN(a) && !isNaN(b)) capWin = {a: Math.min(a,b), b: Math.max(a,b)}; }
 
 const clamp = (x,a,b) => Math.max(a, Math.min(b, x));
 const vspan = () => viewMax - viewMin;
@@ -710,6 +718,9 @@ const buildYaml = () => {
   if (!sorted.length) y+='  []\\n';
   sorted.forEach(iv => { y+='  - {start: "'+fmtTs(iv.a)+'", end: "'+fmtTs(iv.b)+'"'
     + (iv.label && iv.label.trim() ? ', label: '+yamlStr(iv.label.trim()) : '') + '}\\n'; });
+  // Persist the painted threshold-capture window so the regime scope is auditable
+  // in the saved file and restored on reopen. Pure metadata — autotune ignores it.
+  if (capWin) y+='capture_windows:\\n  - {start: "'+fmtTs(capWin.a)+'", end: "'+fmtTs(capWin.b)+'"}\\n';
   return y;
 };
 
@@ -767,6 +778,7 @@ def render_labeler_html(
     save_url: str | None = None,
     interval_seconds: int | None = None,
     incidents: list[dict[str, str]] | None = None,
+    capture_windows: list[dict[str, str]] | None = None,
 ) -> str:
     """Return a self-contained HTML labeler page for *metric_name*'s series.
 
@@ -791,6 +803,7 @@ def render_labeler_html(
     return (
         _TEMPLATE.replace("__PAYLOAD__", payload)
         .replace("__INCIDENTS__", preload)
+        .replace("__CAPTURE_WINDOWS__", json_dumps_sorted(capture_windows or []))
         .replace("__FAVICON__", _favicon_data_uri())
         .replace("__SAVE_URL__", json.dumps(save_url))
         .replace("__INTERVAL__", json.dumps(interval_seconds))

{detectkit-0.27.0 → detectkit-0.29.0}/detectkit/autotune/label_server.py

@@ -122,11 +122,14 @@ def build_label_server(
     incidents_dir: Path,
     interval_seconds: int,
     preload: list[dict[str, str]] | None = None,
+    capture_windows: list[dict[str, str]] | None = None,
 ) -> tuple[_LabelServer, str]:
     """Construct (without running) the labeler server; return ``(server, page_url)``.
 
     ``preload`` seeds the labeler with already-marked incidents (editing an
     existing labels file); the caller resolves which file to load.
+    ``capture_windows`` restores the painted threshold-capture window from a saved
+    file so the regime scope survives a reopen.
     """
     server = _LabelServer(("127.0.0.1", 0), _Handler)
     token = secrets.token_urlsafe(16)
@@ -141,6 +144,7 @@ def build_label_server(
         save_url=f"http://127.0.0.1:{port}/save?token={token}",
         interval_seconds=interval_seconds,
         incidents=preload,
+        capture_windows=capture_windows,
     )
     return server, f"http://127.0.0.1:{port}/?token={token}"
 
@@ -155,10 +159,12 @@ def serve_labeler(
     echo: Callable[[str], None] = print,
     on_ready: Callable[[str], None] | None = None,
     preload: list[dict[str, str]] | None = None,
+    capture_windows: list[dict[str, str]] | None = None,
 ) -> Path | None:
     """Serve the labeler until the user saves (returns the file) or cancels (None).
 
-    ``preload`` seeds the page with existing incidents to edit in place.
+    ``preload`` seeds the page with existing incidents to edit in place;
+    ``capture_windows`` restores the painted threshold-capture scope.
     """
     server, url = build_label_server(
         metric_name=metric_name,
@@ -166,6 +172,7 @@ def serve_labeler(
         incidents_dir=incidents_dir,
         interval_seconds=interval_seconds,
         preload=preload,
+        capture_windows=capture_windows,
     )
     if on_ready is not None:
         on_ready(url)

{detectkit-0.27.0 → detectkit-0.29.0}/detectkit/autotune/labels.py

@@ -14,7 +14,7 @@ When no labels are supplied the tuner falls back to unsupervised mode.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -62,6 +62,10 @@ class IncidentLabels:
 
     intervals: list[IncidentInterval]
     points: list[IncidentPoint]
+    # Optional threshold-capture time window(s) painted in the labeler. Pure
+    # metadata: it records the regime scope the user reasoned about (auditable in
+    # the saved file, restored on reopen); it does NOT affect ground truth.
+    capture_windows: list[tuple[datetime, datetime]] = field(default_factory=list)
 
     def is_empty(self) -> bool:
         return not self.intervals and not self.points
@@ -152,6 +156,7 @@ def parse_incident_labels(
     if raw is None:
         return IncidentLabels([], [])
 
+    raw_windows: list = []
     if isinstance(raw, list):
         entries = raw
         tz: ZoneInfo | None = None
@@ -164,6 +169,9 @@ def parse_incident_labels(
         entries = raw.get("incidents", [])
         if not isinstance(entries, list):
             raise ValueError("'incidents' must be a list")
+        raw_windows = raw.get("capture_windows") or []
+        if not isinstance(raw_windows, list):
+            raise ValueError("'capture_windows' must be a list")
     else:
         raise ValueError("Labels must be a mapping with 'incidents' or a list of incidents")
 
@@ -187,7 +195,16 @@ def parse_incident_labels(
                 "Each incident needs either 'at' (a point) or 'start'+'end' (an interval)"
             )
 
-    return IncidentLabels(intervals=intervals, points=points)
+    capture_windows: list[tuple[datetime, datetime]] = []
+    for win in raw_windows:
+        if not isinstance(win, dict) or "start" not in win or "end" not in win:
+            raise ValueError("Each capture_windows entry needs 'start' and 'end'")
+        ws, we = _parse_dt(win["start"], tz), _parse_dt(win["end"], tz)
+        if ws > we:
+            raise ValueError(f"Capture window start {ws} is after end {we}")
+        capture_windows.append((ws, we))
+
+    return IncidentLabels(intervals=intervals, points=points, capture_windows=capture_windows)
 
 
 def parse_labels_file(
@@ -243,3 +260,22 @@ def load_incidents_for_display(
     """Load a canonical labels file and render it as labeler display dicts."""
     labels = parse_labels_file(path, interval_seconds=interval_seconds, metric_name=metric_name)
     return incidents_to_display(labels)
+
+
+def capture_windows_to_display(labels: IncidentLabels) -> list[dict[str, str]]:
+    """Render parsed capture windows as labeler display dicts (naive-UTC strings)."""
+    return [
+        {"start": start.strftime(_DISPLAY_FMT), "end": end.strftime(_DISPLAY_FMT)}
+        for start, end in labels.capture_windows
+    ]
+
+
+def load_capture_windows(
+    path: str | Path,
+    *,
+    interval_seconds: int,
+    metric_name: str | None = None,
+) -> list[dict[str, str]]:
+    """Load a labels file and render its capture windows as labeler display dicts."""
+    labels = parse_labels_file(path, interval_seconds=interval_seconds, metric_name=metric_name)
+    return capture_windows_to_display(labels)