detectkit 0.26.1__tar.gz → 0.28.0__tar.gz

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

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

{detectkit-0.26.1 → detectkit-0.28.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.26.1"
+__version__ = "0.28.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.26.1 → detectkit-0.28.0}/detectkit/autotune/config_emitter.py

@@ -23,6 +23,7 @@ _RULE = "# " + "─" * 61
 _STAGE_LABELS = {
     "seasonality": "SEASONALITY",
     "detector_select": "DETECTOR",
+    "regime": "REGIME",
     "grid_search": "GRID SEARCH",
     "window": "WINDOW",
 }

{detectkit-0.26.1 → detectkit-0.28.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.26.1 → detectkit-0.28.0}/detectkit/autotune/grid_search.py

@@ -13,9 +13,17 @@ 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 min_samples_for, select_window, trend_present
+from detectkit.autotune.window_select import (
+    detect_level_shift,
+    half_life_grid,
+    min_samples_for,
+    select_window,
+    trend_present,
+)
 from detectkit.detectors.factory import DetectorFactory
 
 
@@ -39,6 +47,30 @@ def grid_search(
         base["seasonality_components"] = seasonality
 
     has_trend = trend_present(tuner)
+    if not has_trend:
+        # The trend gate is a single midpoint-median test, so it silently misses a
+        # level shift that sits off-center (both halves straddle it) or one big
+        # 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 (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 ~{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_at=from_date,
+            )
     eps = tuner.settings.min_improvement
     best_overall: CandidateEval | None = None
 
@@ -80,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.26.1 → detectkit-0.28.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.26.1 → detectkit-0.28.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.26.1 → detectkit-0.28.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)

{detectkit-0.26.1 → detectkit-0.28.0}/detectkit/autotune/settings.py

@@ -24,7 +24,9 @@ class TuneSettings:
 
     # Cross-validation
     fold_count: int = 5
-    stability_lambda: float = 0.5  # aggregate = mean - lambda * std(folds)
+    # aggregate = mean(folds) - lambda * downside_semideviation(folds); downside-only
+    # so a regime-adaptive config isn't penalized for scoring *better* on recent folds.
+    stability_lambda: float = 0.5
 
     # Detector selection: by default the grid search evaluates ALL windowed
     # statistical detectors and lets cross-validation pick the winner; the

{detectkit-0.26.1 → detectkit-0.28.0}/detectkit/autotune/window_select.py

@@ -55,6 +55,69 @@ def trend_present(tuner: _AutoTuneBase) -> bool:
     return abs(med_second - med_first) > 2.0 * 1.4826 * mad
 
 
+# A level shift is "large" when the two regimes' centers differ by at least this
+# many within-regime robust sigmas. Measured against the *within-segment* scale
+# (not the global MAD) so a big step can't self-mask by inflating the yardstick.
+_SHIFT_SIGMA_BAR = 3.0
+_SHIFT_MIN_POINTS = 32  # too few points to meaningfully talk about two regimes
+_SHIFT_MIN_SIDE_FRAC = 0.1  # each candidate segment must hold ≥10% of the points
+_SHIFT_SCAN_SPLITS = 24  # coarse grid of candidate split points to scan
+
+
+def detect_level_shift(tuner: _AutoTuneBase) -> tuple[bool, float, int]:
+    """Scan for the strongest single level shift anywhere in the series.
+
+    Complements :func:`trend_present`, which only compares the two *halves'*
+    medians against the *global* MAD and so misses a shift that (a) sits
+    off-center — both halves then straddle it — or (b) self-masks by inflating the
+    global MAD it is measured against. This scans candidate split points across
+    the series and scores each step against the **within-segment** robust scale,
+    which a true step does not inflate (a smooth ramp, by contrast, keeps a large
+    within-segment spread and so does not register). Returns ``(found,
+    magnitude_sigmas, boundary_index)`` where ``boundary_index`` is the index of
+    the **first point of the new regime** in ``tuner.data`` (so the caller can map
+    it to a timestamp for a concrete ``--from`` suggestion). The scan runs on the
+    raw grid (NaN-aware medians) so the index aligns with ``timestamp``. ``found``
+    is ``True`` only when the strongest step clears :data:`_SHIFT_SIGMA_BAR`
+    within-regime sigmas.
+    """
+    v = np.asarray(tuner.data["value"], dtype=float)
+    n = int(v.size)
+    min_side = max(4, int(n * _SHIFT_MIN_SIDE_FRAC))
+    if n < _SHIFT_MIN_POINTS or n - 2 * min_side < 1:
+        return (False, 0.0, 0)
+    step = max(1, (n - 2 * min_side) // _SHIFT_SCAN_SPLITS)
+    best_sigmas = 0.0
+    best_idx = 0
+    for s in range(min_side, n - min_side + 1, step):
+        left, right = v[:s], v[s:]
+        if np.isnan(left).all() or np.isnan(right).all():
+            continue
+        med_l = float(np.nanmedian(left))
+        med_r = float(np.nanmedian(right))
+        delta = abs(med_r - med_l)
+        if delta <= 0:
+            continue
+        within = float(np.nanmedian(np.abs(np.concatenate([left - med_l, right - med_r]))))
+        sigmas = delta / (1.4826 * within) if within > 0 else 99.0
+        if sigmas > best_sigmas:
+            best_sigmas, best_idx = sigmas, s
+    return (best_sigmas >= _SHIFT_SIGMA_BAR, min(best_sigmas, 99.0), best_idx)
+
+
+def half_life_grid(window_size: int, min_samples: int) -> list[int]:
+    """Candidate half-lives (in points) for the recency-weighting sweep.
+
+    Spaced as fractions of the window so the search can trade a fast-forgetting
+    baseline (small half-life → tracks the current regime, good after a shift)
+    against a steady one. Floored at ``min_samples / 2`` to keep the weighted
+    effective sample size from collapsing into a noisy band.
+    """
+    floor = max(2, min_samples // 2)
+    cands = {round(window_size * f) for f in (0.05, 0.1, 0.25, 0.5)}
+    return sorted({max(floor, c) for c in cands if c >= 2})
+
+
 def select_window(
     tuner: _AutoTuneBase,
     detector_type: str,

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

@@ -27,13 +27,26 @@ same windowed detectors and `detector_id` identity). The fastest path is the
    detectors (`mad`/`zscore`/`iqr`) and cross-validation picks the winner — no
    type is excluded by heuristic.
 3. **Hyperparameters** — a bounded coordinate grid search over `threshold`,
-   recency weighting, detrending and `window_size`, maximizing a
-   cross-validated score, with a final `threshold` re-sweep at the chosen window.
+   recency weighting (and its **half-life** when adopted), detrending and
+   `window_size`, maximizing a cross-validated score, with a final `threshold`
+   re-sweep at the chosen window. Fold scores aggregate as
+   `mean − stability_lambda · downside_deviation` (downside-only, so a config that
+   scores *better* on recent folds isn't penalized; lower `stability_lambda` for a
+   regime-shift metric).
 4. **History window** — on near-ties uses a trend-gated tie-break: a stationary
    series prefers the **larger** `window_size` ("more history is better"), a
    trending / regime-shifting one the **smaller**; sets `loading_start_time` to
    cover the lead-in (and pins the detector's `start_time` to it, so the first
-   `dtk run` detects across all loaded history).
+   `dtk run` detects across all loaded history). The trend gate is a midpoint
+   test, so it can miss a level shift that sits off-center or self-masks by
+   inflating the global MAD; a backstop scan then logs a **`REGIME`** advisory in
+   the decision log (and streams it) when the series reads stationary yet a large
+   (≥3σ within-regime) level shift is present — it names a **concrete `--from
+   <date>`** (the shift's timestamp); surface it to the user and suggest re-tuning
+   with that date (or `autotune.max_history`) if the earlier regime is stale.
+   Advisory only; it changes no chosen parameters,
+   and it detects level shifts, not variance/shape changes (label incidents for
+   those).
 5. **Alert window** (supervised only) — sweeps `consecutive_anomalies` on the
    labeled incidents.
 
@@ -101,7 +114,9 @@ user to recall timestamps** — it is the easiest, most reliable path:
    clear outliers, **Threshold capture** grabs every span past a horizontal line
    at once (above/below, with an optional gap-bridge); it captures within the
    current view by default, and dragging across the chart limits it to a time
-   window (different boundary per period). Each band's ✕ (or select + Delete)
+   window (different boundary per period) — the painted window is **saved with the
+   set and restored on reopen** (a `capture_windows:` block; metadata only). Each
+   band's ✕ (or select + Delete)
    removes one, and **focus** on a list row jumps the chart to it.
 3. That writes `incidents/<metric>/<metric>[-<set>]-<UTC>.yml` automatically
    (named after the metric, optional set name as a suffix; versioned —
@@ -148,6 +163,7 @@ autotune:
   force_seasonality: [hour]       # pin the grouping, skip the search (see below)
   fixed_params: {window_size: 4320}  # pin hyperparameters (excluded from search)
   folds: 5
+  stability_lambda: 0.5           # downside-dispersion penalty weight (0 disables)
   max_history: 50000              # cap training points
 ```
 

{detectkit-0.26.1 → detectkit-0.28.0}/detectkit/cli/commands/autotune.py

@@ -32,6 +32,7 @@ from detectkit.autotune.labels import (
     GroundTruth,
     IncidentLabels,
     incidents_to_display,
+    load_capture_windows,
     load_incidents_for_display,
     parse_incident_labels,
 )
@@ -264,6 +265,7 @@ def _build_settings(*, scoring: ScoringMetric, autotune_cfg: AutoTuneConfig) ->
         metric=scoring,
         beta=autotune_cfg.beta,
         fold_count=autotune_cfg.folds,
+        stability_lambda=autotune_cfg.stability_lambda,
         allowed_detector_types=autotune_cfg.detector_types,
         allowed_seasonality=autotune_cfg.seasonality_candidates,
         force_seasonality=autotune_cfg.force_seasonality,
@@ -427,9 +429,23 @@ def _tune_one(
                 except ValueError:  # an absolute path outside the project tree
                     where = preload_src
             click.echo(f"  Editing {len(preload)} existing incident(s) from {where}")
+        # Restore the painted threshold-capture window from the same seed file
+        # (best-effort — a missing/old file just yields no window).
+        capture_windows: list[dict[str, str]] = []
+        if preload_src is not None:
+            try:
+                capture_windows = load_capture_windows(
+                    preload_src, interval_seconds=interval_seconds, metric_name=name
+                )
+            except Exception:  # noqa: BLE001 — restoring the scope is a convenience
+                capture_windows = []
         if no_serve:
             html = render_labeler_html(
-                name, data, interval_seconds=interval_seconds, incidents=preload
+                name,
+                data,
+                interval_seconds=interval_seconds,
+                incidents=preload,
+                capture_windows=capture_windows,
             )
             out = project_root / "metrics" / f"{metric_path.stem}__labeler.html"
             out.write_text(html, encoding="utf-8")
@@ -447,6 +463,7 @@ def _tune_one(
             open_browser=not no_open,
             echo=click.echo,
             preload=preload,
+            capture_windows=capture_windows,
         )
         if saved is None:
             echo_noop(name, "labeling cancelled — no labels saved")

{detectkit-0.26.1 → detectkit-0.28.0}/detectkit/config/metric_config.py

@@ -371,6 +371,13 @@ class AutoTuneConfig(BaseModel):
         default_factory=dict, description="Hyperparameters pinned across the whole search"
     )
     folds: int = Field(default=5, description="Cross-validation folds")
+    stability_lambda: float = Field(
+        default=0.5,
+        description="Weight on the cross-fold downside-dispersion penalty "
+        "(aggregate = mean - lambda * downside_semideviation). Lower it (e.g. 0.0) for a "
+        "metric whose behavior differs across a regime shift, so a config that adapts to "
+        "the recent regime isn't penalized for fold-to-fold variance.",
+    )
     max_history: int | None = Field(
         default=None, description="Cap on training points used during the search"
     )
@@ -463,6 +470,14 @@ class AutoTuneConfig(BaseModel):
             raise ValueError("max_history must be at least 1")
         return v
 
+    @field_validator("stability_lambda")
+    @classmethod
+    def validate_stability_lambda(cls, v: float) -> float:
+        """The dispersion-penalty weight must be non-negative."""
+        if v < 0:
+            raise ValueError("stability_lambda must be >= 0")
+        return v
+
     @model_validator(mode="after")
     def validate_inline_incidents(self) -> "AutoTuneConfig":
         """Validate inline incidents: not alongside labels_file, and well-formed.

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

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