detectkit 0.26.1__tar.gz → 0.27.0__tar.gz

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

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

{detectkit-0.26.1 → detectkit-0.27.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.27.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.26.1 → detectkit-0.27.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.27.0}/detectkit/autotune/grid_search.py

@@ -15,7 +15,12 @@ from typing import Any
 
 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,
+    min_samples_for,
+    select_window,
+    trend_present,
+)
 from detectkit.detectors.factory import DetectorFactory
 
 
@@ -39,6 +44,25 @@ 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 so the user can narrow the window and re-tune; advisory only.
+        found, sigmas, frac = detect_level_shift(tuner)
+        if found:
+            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`).",
+                shift_sigmas=round(sigmas, 2),
+                shift_fraction=round(frac, 3),
+            )
     eps = tuner.settings.min_improvement
     best_overall: CandidateEval | None = None
 

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

@@ -55,6 +55,50 @@ 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, float]:
+    """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, location_fraction)``; ``found`` is ``True`` only when the
+    strongest step clears :data:`_SHIFT_SIGMA_BAR` within-regime sigmas.
+    """
+    v = np.asarray(tuner.data["value"], dtype=float)
+    v = v[~np.isnan(v)]
+    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.0)
+    step = max(1, (n - 2 * min_side) // _SHIFT_SCAN_SPLITS)
+    best_sigmas = 0.0
+    best_frac = 0.0
+    for s in range(min_side, n - min_side + 1, step):
+        med_l = float(np.median(v[:s]))
+        med_r = float(np.median(v[s:]))
+        delta = abs(med_r - med_l)
+        if delta <= 0:
+            continue
+        within = float(np.median(np.abs(np.concatenate([v[:s] - med_l, v[s:] - med_r]))))
+        sigmas = delta / (1.4826 * within) if within > 0 else 99.0
+        if sigmas > best_sigmas:
+            best_sigmas, best_frac = sigmas, s / n
+    return (best_sigmas >= _SHIFT_SIGMA_BAR, min(best_sigmas, 99.0), best_frac)
+
+
 def select_window(
     tuner: _AutoTuneBase,
     detector_type: str,

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

@@ -33,7 +33,15 @@ same windowed detectors and `detector_id` identity). The fastest path is the
    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 — surface it to the user and suggest
+   re-tuning with `--from <date after the shift>` (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.
 

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

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