detectkit 0.52.1__tar.gz → 0.53.0__tar.gz

{detectkit-0.52.1/detectkit.egg-info → detectkit-0.53.0}/PKG-INFO

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

{detectkit-0.52.1 → detectkit-0.53.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.52.1"
+__version__ = "0.53.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/autotuner.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import contextlib
 import logging
 from collections.abc import Callable, Iterator
+from dataclasses import dataclass
 from datetime import datetime, timedelta
 from typing import Any
 
@@ -16,6 +17,7 @@ import numpy as np
 
 from detectkit.autotune._base import AutoTuneError, _AutoTuneBase
 from detectkit.autotune._types import CandidateEval, TuneMode
+from detectkit.autotune.axis_spec import max_context_size
 from detectkit.autotune.crossval import build_cv_plan, predictions_from_results
 from detectkit.autotune.detector_select import select_detector_types
 from detectkit.autotune.grid_search import grid_search
@@ -71,6 +73,33 @@ def _consecutive(flags: np.ndarray, k: int) -> np.ndarray:
     return out
 
 
+def _fraction_fire(flags: np.ndarray, window_points: int, share: float) -> np.ndarray:
+    """Mark index i where the fraction alert rule fires — the pure-numpy sibling
+    of ``_decision._share_fire``: the latest point itself is anomalous (a stale
+    window never fires) AND the anomalous share over the trailing
+    ``window_points`` slots (current point inclusive) reaches *share*. Slots
+    before the series start, gaps and invalid points all count in the
+    denominator only, exactly like the pipeline's missing-slot handling."""
+    n = len(flags)
+    if n == 0 or window_points <= 0:
+        return flags.copy()
+    counts = np.convolve(flags.astype(np.int64), np.ones(window_points, dtype=np.int64))[:n]
+    return flags & (counts >= share * window_points)
+
+
+@dataclass(frozen=True)
+class _AlertRuleChoice:
+    """Outcome of the supervised alert-rule sweep.
+
+    ``window_points``/``min_anomaly_share`` are set only when the OR-ed
+    fraction rule strictly beat the consecutive-only optimum; the deployed
+    behavior (consecutive OR fraction) is exactly what was scored."""
+
+    consecutive_anomalies: int | None
+    window_points: int | None = None
+    min_anomaly_share: float | None = None
+
+
 class AutoTuner(_AutoTuneBase):
     """Runs the load-free tuning pipeline and returns an :class:`AutoTuneResult`."""
 
@@ -83,12 +112,17 @@ class AutoTuner(_AutoTuneBase):
             )
 
         grid = window_grid(self)
-        max_window = max([*grid, 100])
-        self.cv_plan = build_cv_plan(n, max_window, self.settings.fold_count)
+        # Reserve the largest context any candidate the search can build might
+        # need (window + stabilization warm-up + AR lags), not just the raw
+        # window size — otherwise folds silently score points where detect()
+        # returns insufficient_data / missing_lags (valid=False), degrading
+        # the CV signal without erroring.
+        max_context = max_context_size(self, grid)
+        self.cv_plan = build_cv_plan(n, max_context, self.settings.fold_count)
         if not self.cv_plan.fold_bounds:
             raise AutoTuneError(
                 f"not enough datapoints ({n}) for {self.settings.fold_count}-fold "
-                f"cross-validation with a {max_window}-point context window"
+                f"cross-validation with a {max_context}-point context window"
             )
 
         gt = self.ground_truth
@@ -111,36 +145,80 @@ class AutoTuner(_AutoTuneBase):
         if best is None:
             raise AutoTuneError("no viable detector candidate found for this data")
 
-        consecutive = self._select_alert_window(best.detector_type, best.params)
+        alert_rule = self._select_alert_window(best.detector_type, best.params)
 
-        return self._build_result(seasonality, best, consecutive)
+        return self._build_result(seasonality, best, alert_rule)
 
     # ------------------------------------------------------------------
 
-    def _select_alert_window(self, detector_type: str, params: dict[str, Any]) -> int | None:
-        """Sweep consecutive_anomalies on labeled incidents (supervised only)."""
+    def _select_alert_window(
+        self, detector_type: str, params: dict[str, Any]
+    ) -> _AlertRuleChoice | None:
+        """Sweep the alert rule on labeled incidents (supervised only).
+
+        Two passes over one ``detect()`` run: the legacy 1-D
+        ``consecutive_anomalies`` sweep first, then a 2-D (window × share)
+        sweep of the fraction rule **OR-ed with the chosen consecutive rule**
+        — scoring exactly the composite the pipeline would deploy. The pair is
+        adopted only on a strictly greater score, so the legacy rule wins ties
+        and existing behavior is byte-stable when the fraction rule doesn't
+        help.
+        """
         if self.ground_truth.mode != TuneMode.SUPERVISED:
             return None
         detector = DetectorFactory.create(detector_type, params)
         y_pred, y_score, valid = predictions_from_results(detector.detect(self.data))
         y_true = self.ground_truth.y_true
+        metric, beta = self.settings.metric, self.settings.beta
+
+        def _score(alert: np.ndarray) -> float:
+            # Same invalid-point handling seam as the CV folds (pointwise
+            # metrics mask; the segment-aware one keeps unmasked arrays).
+            yt, yp, ys = arrays_for_metric(y_true, alert, y_score, valid, metric)
+            return score_predictions(yt, yp, ys, metric, beta)
+
         best_k = 1
         best_score = float("-inf")
         for k in _ALERT_WINDOW_GRID:
-            alert = _consecutive(y_pred, k)
-            # Same invalid-point handling seam as the CV folds (pointwise
-            # metrics mask; the segment-aware one keeps unmasked arrays).
-            yt, yp, ys = arrays_for_metric(y_true, alert, y_score, valid, self.settings.metric)
-            score = score_predictions(yt, yp, ys, self.settings.metric, self.settings.beta)
+            score = _score(_consecutive(y_pred, k))
             if score > best_score:
                 best_score, best_k = score, k
+
+        consecutive_fire = _consecutive(y_pred, best_k)
+        n = len(y_pred)
+        best_pair: tuple[int, float] | None = None
+        for window_points in self.settings.alert_window_points_grid:
+            # < 2 would degenerate to consecutive_anomalies=1 (MetricConfig
+            # rejects it); a window longer than the series can never be
+            # observed at its own width.
+            if window_points < 2 or window_points > n:
+                continue
+            for share in self.settings.alert_share_grid:
+                alert = consecutive_fire | _fraction_fire(y_pred, window_points, share)
+                score = _score(alert)
+                if score > best_score:
+                    best_score, best_pair = score, (window_points, share)
+
+        if best_pair is not None:
+            window_points, share = best_pair
+            self.log(
+                "window",
+                f"consecutive_anomalies={best_k} OR anomaly_window={window_points}p × "
+                f"min_anomaly_share={share} "
+                f"(max {metric.value}={best_score:.3f} on labeled incidents)",
+                consecutive_anomalies=best_k,
+                anomaly_window_points=window_points,
+                min_anomaly_share=share,
+            )
+            return _AlertRuleChoice(best_k, window_points, share)
+
         self.log(
             "window",
             f"consecutive_anomalies={best_k} "
-            f"(max {self.settings.metric.value}={best_score:.3f} on labeled incidents)",
+            f"(max {metric.value}={best_score:.3f} on labeled incidents)",
             consecutive_anomalies=best_k,
         )
-        return best_k
+        return _AlertRuleChoice(best_k)
 
     def _clean_params(self, params: dict[str, Any]) -> dict[str, Any]:
         """Drop None/empty values so the emitted config is tidy."""
@@ -154,7 +232,7 @@ class AutoTuner(_AutoTuneBase):
         return out
 
     def _build_result(
-        self, seasonality: list | None, best: CandidateEval, consecutive: int | None
+        self, seasonality: list | None, best: CandidateEval, alert_rule: _AlertRuleChoice | None
     ) -> AutoTuneResult:
         timestamps = self.data["timestamp"]
         training_start = _ts_to_dt(timestamps[0]) if len(timestamps) else None
@@ -194,7 +272,13 @@ class AutoTuner(_AutoTuneBase):
             score=best.score,
             cv_per_fold=best.fold_scores.per_fold,
             cv_stability_penalty=best.fold_scores.stability_penalty,
-            consecutive_anomalies=consecutive,
+            consecutive_anomalies=alert_rule.consecutive_anomalies if alert_rule else None,
+            anomaly_window=(
+                f"{alert_rule.window_points * self.interval_seconds}s"
+                if alert_rule and alert_rule.window_points is not None
+                else None
+            ),
+            min_anomaly_share=alert_rule.min_anomaly_share if alert_rule else None,
             candidate_detector_ids=self.evaluated_ids(),
             candidates=candidates,
             group_votes=group_votes,

detectkit-0.53.0/detectkit/autotune/axis_spec.py

@@ -0,0 +1,118 @@
+"""Per-detector-type axis specification for the grid search (issue #97 Phase 2).
+
+``grid_search`` used to be one hardcoded coordinate sweep whose every axis name
+(``window_weights``, ``half_life``, ``detrend``, ``seasonality_components``) is
+a ``WindowedStatDetector`` constructor kwarg. The prediction-based ``autoreg``
+detector accepts none of those (and *raises* on truthy
+``seasonality_components``), so the sweep dispatches on a small spec keyed by
+detector type — kept here, NOT on the detector classes, the same
+easy-to-remove externalized-knowledge choice as ``detector_select``'s
+suitability spec. Unlisted (future) types get the windowed default, which is
+behavior-identical to the pre-seam sweep.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from detectkit.detectors.factory import DetectorFactory
+
+if TYPE_CHECKING:
+    from detectkit.autotune._base import _AutoTuneBase
+
+
+@dataclass(frozen=True)
+class AxisSpec:
+    """Which grid-search axes apply to a detector type, plus per-type floors.
+
+    ``min_samples_floor`` / ``threshold_default`` override the class-attribute
+    lookup (``MIN_SAMPLES_FLOOR`` / ``THRESHOLD_DEFAULT``) for types that don't
+    carry the windowed template's attributes; ``None`` keeps the lookup.
+    ``initial`` seeds the accepted-params dict so type-specific defaults (e.g.
+    autoreg's default-on stabilization) are explicit from the first candidate.
+    """
+
+    seasonality: bool = True  # inject the chosen seasonality_components
+    weighting: bool = True  # window_weights + half_life axes
+    detrend: bool = True  # detrend axis (still trend-gated)
+    stabilization: bool = True  # stabilization axis
+    lags: bool = False  # AR-order axis (settings.lags_grid)
+    min_samples_floor: int | None = None
+    threshold_default: float | None = None
+    initial: dict[str, Any] = field(default_factory=dict)
+
+
+_WINDOWED = AxisSpec()
+
+_AXIS_SPECS: dict[str, AxisSpec] = {
+    # v1 autoreg has no seasonality/smoothing/weighting/detrend by design (the
+    # AR residual model adapts to level and short-range dynamics on its own);
+    # it *rejects* seasonality_components, so the seam must never inject them.
+    # min_samples additionally floors at lags + 2 — see ``min_samples_for``.
+    "autoreg": AxisSpec(
+        seasonality=False,
+        weighting=False,
+        detrend=False,
+        lags=True,
+        min_samples_floor=10,
+        threshold_default=3.0,
+        initial={"lags": 5, "stabilization": "clamp"},
+    ),
+}
+
+
+def axis_spec_for(detector_type: str) -> AxisSpec:
+    """The axis spec for *detector_type* (windowed default when unlisted)."""
+    return _AXIS_SPECS.get(detector_type, _WINDOWED)
+
+
+def resolve_floor(detector_type: str) -> int:
+    """Min-samples floor: spec override first, then the class attribute."""
+    spec = axis_spec_for(detector_type)
+    if spec.min_samples_floor is not None:
+        return spec.min_samples_floor
+    detector_cls = DetectorFactory.DETECTOR_TYPES[detector_type]
+    return int(getattr(detector_cls, "MIN_SAMPLES_FLOOR", 1))
+
+
+def resolve_threshold_default(detector_type: str) -> float:
+    """Default threshold: spec override first, then the class attribute."""
+    spec = axis_spec_for(detector_type)
+    if spec.threshold_default is not None:
+        return spec.threshold_default
+    detector_cls = DetectorFactory.DETECTOR_TYPES[detector_type]
+    return float(getattr(detector_cls, "THRESHOLD_DEFAULT", 3.0))
+
+
+def max_context_size(tuner: _AutoTuneBase, grid: list[int]) -> int:
+    """Largest ``get_context_size()`` any candidate the search can build needs.
+
+    The CV plan must reserve this much lead-in — deriving it from the raw
+    window grid alone (the pre-fix behavior) under-reserves for stabilization
+    (an extra window of warm-up) and for autoreg (``+ lags``), silently
+    scoring points where ``detect()`` returns ``insufficient_data`` /
+    ``missing_lags`` (they become ``valid=False``, degrading the CV signal
+    without erroring).
+    """
+    from detectkit.autotune.detector_select import _candidate_types
+
+    max_window = max([*grid, 100])
+    context = max_window
+    for detector_type in _candidate_types(tuner):
+        spec = axis_spec_for(detector_type)
+        params: dict[str, Any] = {**tuner.settings.fixed_params}
+        params["window_size"] = max_window
+        # Worst-case axes the sweep can adopt: stabilization adds a window of
+        # warm-up; the largest lags in the grid adds `lags` context points.
+        params["stabilization"] = "clamp"
+        if spec.lags and tuner.settings.lags_grid:
+            max_lags = max(tuner.settings.lags_grid)
+            params["lags"] = max_lags
+            params["min_samples"] = max(max_lags + 2, min(30, max_window))
+        try:
+            detector = DetectorFactory.create(detector_type, params)
+        except ValueError:
+            continue
+        context = max(context, detector.get_context_size())
+    return context

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/config_emitter.py

@@ -61,6 +61,11 @@ def _build_alerting(original: MetricConfig, result: AutoTuneResult) -> list[dict
     first = original.alerting[0].model_dump(exclude_none=True, exclude_defaults=True)
     if result.consecutive_anomalies is not None:
         first["consecutive_anomalies"] = result.consecutive_anomalies
+    if result.anomaly_window is not None and result.min_anomaly_share is not None:
+        # Exact-seconds duration: round-trips losslessly through
+        # `AlertConditions.from_alert_config` back to the swept point count.
+        first["anomaly_window"] = result.anomaly_window
+        first["min_anomaly_share"] = result.min_anomaly_share
     first["min_detectors"] = 1  # single tuned detector now
     return [first]
 

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/detector_select.py

@@ -20,12 +20,10 @@ from detectkit.autotune.distribution import compute_distribution_features
 from detectkit.detectors.factory import DetectorFactory
 from detectkit.detectors.seasonality import parse_seasonality_data
 
-# Detector types the engine can auto-tune (windowed statistical detectors).
-# Derived from the factory minus the manual/stateless ones.
-# "autoreg" is prediction-based (fits AR coefficients, not the windowed
-# center/spread stats this module's grid axes assume) — Phase 2 will add a
-# per-type grid seam before it can be tuned here.
-_EXCLUDED_TYPES = {"manual", "manual_bounds", "autoreg"}
+# Detector types the engine can auto-tune. Derived from the factory minus the
+# manual/stateless ones; the prediction-based "autoreg" participates via its
+# AxisSpec (see autotune/axis_spec.py), which gates the windowed-only axes.
+_EXCLUDED_TYPES = {"manual", "manual_bounds"}
 # A seasonal sub-group needs at least this many points to vote.
 _MIN_GROUP_FOR_VOTE = 10
 # Cap on voting sub-groups so a high-cardinality component can't explode cost.
@@ -56,6 +54,13 @@ def detector_suitability(detector_type: str, features: dict[str, float]) -> floa
     if detector_type == "iqr":
         # Best on skewed / asymmetric distributions.
         return _clip01(0.3 + 0.5 * min(1.0, skewness / 3.0) + 0.4 * outlier_fraction)
+    if detector_type == "autoreg":
+        # Prediction-based: models short-range dynamics, not level, and the
+        # distribution shape says little about dynamics — so the vote is
+        # mildly conservative (clean data, where a per-window AR fit is
+        # stable, nudges it up; it never outranks a clearly-matched level
+        # detector). Ordering only; the grid search still evaluates it.
+        return _clip01(0.3 + 0.3 * normality * (1.0 - outlier_fraction))
     return 0.5
 
 

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/grid_search.py

@@ -18,6 +18,7 @@ import numpy as np
 
 from detectkit.autotune._base import _AutoTuneBase
 from detectkit.autotune._types import CandidateEval
+from detectkit.autotune.axis_spec import axis_spec_for, resolve_floor, resolve_threshold_default
 from detectkit.autotune.window_select import (
     detect_level_shift,
     half_life_grid,
@@ -26,7 +27,6 @@ from detectkit.autotune.window_select import (
     select_window,
     trend_present,
 )
-from detectkit.detectors.factory import DetectorFactory
 
 
 def _initial_window(grid: list[int], floor: int) -> int | None:
@@ -92,9 +92,9 @@ def grid_search(
     best_overall: CandidateEval | None = None
 
     for detector_type in detector_types:
-        detector_cls = DetectorFactory.DETECTOR_TYPES[detector_type]
-        floor = int(getattr(detector_cls, "MIN_SAMPLES_FLOOR", 1))
-        threshold_default = float(getattr(detector_cls, "THRESHOLD_DEFAULT", 3.0))
+        spec = axis_spec_for(detector_type)
+        floor = resolve_floor(detector_type)
+        threshold_default = resolve_threshold_default(detector_type)
         window = _initial_window(grid, floor)
         if window is None:
             tuner.log(
@@ -104,11 +104,12 @@ def grid_search(
             continue
 
         accepted: dict[str, Any] = {
-            **base,
+            **(base if spec.seasonality else {}),
+            **spec.initial,
             "threshold": threshold_default,
             "window_size": window,
-            "min_samples": min_samples_for(window, floor),
         }
+        accepted["min_samples"] = min_samples_for(window, floor, accepted.get("lags"))
         best = tuner.safe_evaluate(detector_type, accepted)
         if best is None:
             continue
@@ -121,28 +122,47 @@ def grid_search(
             if ev is not None and ev.score > best.score:
                 best, accepted["threshold"] = ev, threshold
 
+        # Axis 1b: AR order (autoreg only) — swept like threshold, with the
+        # min-samples floor tracking lags + 2 (the detector validates that).
+        if spec.lags:
+            for lags in tuner.settings.lags_grid:
+                if lags == accepted.get("lags"):
+                    continue
+                candidate = {
+                    **accepted,
+                    "lags": lags,
+                    "min_samples": min_samples_for(accepted["window_size"], floor, lags),
+                }
+                ev = tuner.safe_evaluate(detector_type, candidate)
+                if ev is not None and ev.score > best.score:
+                    best = ev
+                    accepted["lags"] = lags
+                    accepted["min_samples"] = candidate["min_samples"]
+
         # Axis 2: recency weighting (only adopt if it clears the margin).
-        for weights in (None, "exponential"):
-            if weights == accepted.get("window_weights"):
-                continue
-            ev = tuner.safe_evaluate(detector_type, {**accepted, "window_weights": weights})
-            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"):
+        if spec.weighting:
+            for weights in (None, "exponential"):
+                if weights == accepted.get("window_weights"):
                     continue
-                ev = tuner.safe_evaluate(detector_type, {**accepted, "half_life": half_life})
+                ev = tuner.safe_evaluate(detector_type, {**accepted, "window_weights": weights})
                 if ev is not None and ev.score > best.score + eps:
-                    best, accepted["half_life"] = ev, half_life
+                    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:
+        if spec.detrend and has_trend:
             for detrend in (None, "linear"):
                 if detrend == accepted.get("detrend"):
                     continue
@@ -156,12 +176,15 @@ def grid_search(
         # the band and mask its own tail — usually decisive on labeled data
         # with long incidents, near-neutral on clean series. Swept before the
         # window axis so select_window evaluates with the adopted baseline.
-        for stabilization in (None, "clamp"):
-            if stabilization == accepted.get("stabilization"):
-                continue
-            ev = tuner.safe_evaluate(detector_type, {**accepted, "stabilization": stabilization})
-            if ev is not None and ev.score > best.score + eps:
-                best, accepted["stabilization"] = ev, stabilization
+        if spec.stabilization:
+            for stabilization in (None, "clamp"):
+                if stabilization == accepted.get("stabilization"):
+                    continue
+                ev = tuner.safe_evaluate(
+                    detector_type, {**accepted, "stabilization": stabilization}
+                )
+                if ev is not None and ev.score > best.score + eps:
+                    best, accepted["stabilization"] = ev, stabilization
 
         # Axis 4: window size (large-window tie-bias, trend-gated in select_window).
         window_best = select_window(tuner, detector_type, accepted, best, grid)

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/result.py

@@ -35,6 +35,13 @@ class AutoTuneResult:
 
     consecutive_anomalies: int | None
     candidate_detector_ids: list[str]
+    # Fraction alert rule (issue #101): an exact-seconds duration string (e.g.
+    # "7200s", lossless through `Interval(...).seconds // interval_seconds`) +
+    # share, set only when the supervised sweep adopts the OR-ed fraction rule.
+    # Like consecutive_anomalies they are non-identity metadata — deliberately
+    # excluded from `compute_run_id`.
+    anomaly_window: str | None = None
+    min_anomaly_share: float | None = None
     candidates: list[dict[str, Any]] = field(default_factory=list)
     group_votes: list[dict[str, Any]] = field(default_factory=list)
     decision_log: list[dict[str, Any]] = field(default_factory=list)

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/settings.py

@@ -43,10 +43,20 @@ class TuneSettings:
     # being trapped flagging its legitimate tail.
     threshold_grid_sigma: tuple[float, ...] = (2.5, 3.0, 3.5, 4.0, 5.0, 6.0)  # mad / zscore
     threshold_grid_iqr: tuple[float, ...] = (1.5, 2.0, 3.0, 4.0, 6.0)  # iqr (Tukey)
+    # AR-order sweep for the prediction-based autoreg detector (axis gated by
+    # its AxisSpec; the residual z is in σ-units so it reuses the sigma grid).
+    lags_grid: tuple[int, ...] = (2, 3, 5, 8)
 
     # History / window selection
     window_tie_margin: float = 0.01  # prefer a larger window within this score gap
 
+    # Fraction alert window (supervised 2-D sweep, OR-ed with the consecutive
+    # rule exactly as the pipeline deploys it). Window grid is in grid points
+    # of the metric interval; entries < 2 are dropped (MetricConfig rejects an
+    # anomaly_window spanning < 2 intervals). Shares are fractions in (0, 1].
+    alert_window_points_grid: tuple[int, ...] = (4, 6, 12, 24)
+    alert_share_grid: tuple[float, ...] = (0.2, 0.3, 0.5)
+
     # Stage-1 seasonality search probe
     probe_detector_type: str = "mad"
 
@@ -58,5 +68,9 @@ class TuneSettings:
     max_history: int | None = None
 
     def threshold_grid(self, detector_type: str) -> tuple[float, ...]:
-        """Threshold sweep for a detector type (Tukey multipliers for IQR)."""
+        """Threshold sweep for a detector type (Tukey multipliers for IQR).
+
+        ``autoreg`` deliberately falls through to the sigma grid: its residual
+        z-score is in σ-units, directly comparable with mad/zscore thresholds.
+        """
         return self.threshold_grid_iqr if detector_type == "iqr" else self.threshold_grid_sigma

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/autotune/window_select.py

@@ -15,7 +15,7 @@ import numpy as np
 
 from detectkit.autotune._base import _AutoTuneBase
 from detectkit.autotune._types import CandidateEval
-from detectkit.detectors.factory import DetectorFactory
+from detectkit.autotune.axis_spec import resolve_floor
 from detectkit.detectors.seasonality import parse_seasonality_data
 from detectkit.detectors.statistical._windowed import WindowedStatDetector
 
@@ -27,9 +27,17 @@ from detectkit.detectors.statistical._windowed import WindowedStatDetector
 _MSPG_REF = int(WindowedStatDetector.MIN_SAMPLES_PER_GROUP_DEFAULT)
 
 
-def min_samples_for(window_size: int, floor: int) -> int:
-    """Derived min_samples: a quarter of the window, clamped to ``[floor, window]``."""
-    return min(window_size, max(floor, round(window_size / 4)))
+def min_samples_for(window_size: int, floor: int, lags: int | None = None) -> int:
+    """Derived min_samples: a quarter of the window, clamped to ``[floor, window]``.
+
+    For the autoreg detector the floor additionally tracks the AR order: the
+    AR(p) + intercept model has ``lags + 1`` unknowns, so at least ``lags + 2``
+    fit rows are required (the detector validates exactly that).
+    """
+    ms = min(window_size, max(floor, round(window_size / 4)))
+    if lags is not None:
+        ms = min(window_size, max(ms, lags + 2))
+    return ms
 
 
 def max_seasonal_cardinality(tuner: _AutoTuneBase) -> int:
@@ -184,12 +192,13 @@ def select_window(
     grid: list[int],
 ) -> CandidateEval:
     """Sweep the window grid (final axis); return the tie-biased-largest winner."""
-    floor = int(getattr(DetectorFactory.DETECTOR_TYPES[detector_type], "MIN_SAMPLES_FLOOR", 1))
+    floor = resolve_floor(detector_type)
+    lags = accepted.get("lags")
     evals: list[tuple[int, CandidateEval]] = []
     for w in grid:
         if w < floor:
             continue
-        candidate = {**accepted, "window_size": w, "min_samples": min_samples_for(w, floor)}
+        candidate = {**accepted, "window_size": w, "min_samples": min_samples_for(w, floor, lags)}
         ev = tuner.safe_evaluate(detector_type, candidate)
         if ev is not None:
             evals.append((w, ev))

{detectkit-0.52.1 → detectkit-0.53.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -118,9 +118,12 @@ fire and recovery always name one rule; a scattered share-fired incident's
 Reports and `dtk ui`'s overview pick up share-fired
 alerts automatically via the shared replay seam.
 
-Not yet tunable: `dtk tune`'s cockpit and `dtk autotune`'s alert-window sweep
-still only search `consecutive_anomalies` (fraction-rule support is a
-follow-up) — set `anomaly_window` / `min_anomaly_share` by hand in the YAML.
+Both paths tune this pair now: supervised `dtk autotune` runs a 2-D sweep of
+`anomaly_window` × `min_anomaly_share` OR-ed with the chosen
+`consecutive_anomalies` rule, adopted only on a strictly greater score (a tie
+keeps the consecutive-only rule); `dtk tune`'s cockpit has always-visible
+anomaly-window / min-share rail controls with live replay of the same OR-ed
+rule, and Apply writes the pair back (or removes both when off).
 
 ## Cooldown (spam control) — **set it in production**