detectkit 0.50.0__tar.gz → 0.51.0__tar.gz

{detectkit-0.50.0/detectkit.egg-info → detectkit-0.51.0}/PKG-INFO

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

{detectkit-0.50.0 → detectkit-0.51.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.50.0"
+__version__ = "0.51.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/autotune/grid_search.py

@@ -1,12 +1,13 @@
 """Stage 3: bounded coordinate search over detector hyperparameters.
 
 Not a Cartesian product — a greedy coordinate sweep per candidate type:
-threshold → recency weighting → detrend (gated by a trend test) → window size
-(with the trend-gated window tie-bias from window_select) → a final threshold
-re-sweep at the chosen window (the threshold↔window coupling fix). The objective
-is the cross-validated score (settings.metric, or the unsupervised objective when
-there are no labels). Total evaluations stay in the low tens per type and are
-capped by settings.max_candidates.
+threshold → recency weighting → detrend (gated by a trend test) → stabilization
+(anomaly-robust baseline) → window size (with the trend-gated window tie-bias
+from window_select) → a final threshold re-sweep at the chosen window (the
+threshold↔window coupling fix). The objective is the cross-validated score
+(settings.metric, or the unsupervised objective when there are no labels).
+Total evaluations stay in the low tens per type and are capped by
+settings.max_candidates.
 """
 
 from __future__ import annotations
@@ -149,6 +150,19 @@ def grid_search(
                 if ev is not None and ev.score > best.score + eps:
                     best, accepted["detrend"] = ev, detrend
 
+        # Axis 3b: stabilization (anomaly-robust baseline; adopt only when it
+        # clears the margin). Flagged points enter subsequent windows clamped
+        # to the bound they violated, so a sustained incident cannot inflate
+        # 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
+
         # Axis 4: window size (large-window tie-bias, trend-gated in select_window).
         window_best = select_window(tuner, detector_type, accepted, best, grid)
         if window_best.score >= best.score - tuner.settings.window_tie_margin:

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/cli/assets/claude/rules/autotune.md

@@ -45,9 +45,10 @@ 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 (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
+   recency weighting (and its **half-life** when adopted), detrending,
+   **stabilization** (`clamp`, adopted only when it clears the score margin)
+   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).

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -84,7 +84,7 @@ Full reference: `autotune.md`.
 The **manual, interactive** sibling of `dtk autotune`. Opens a localhost browser
 view of the metric's **real** persisted series and lets you turn the detector's
 knobs (type — including **Manual bounds** with lower/upper sliders — threshold,
-window, recency weighting + half-life, detrend, smoothing, **seasonality groups**,
+window, recency weighting + half-life, detrend, stabilization, smoothing, **seasonality groups**,
 **direction** (both/up/down), alert `consecutive_anomalies`) while the confidence
 band and flagged anomalies **recompute live**. The whole screen is a **chart-first
 cockpit**: ONE chart (the windshield) fills the view, the live metrics ride

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/cli/assets/claude/rules/detectors.md

@@ -66,6 +66,7 @@ expected interval for the current point.
     window_weights: null     # null (uniform) | exponential | linear
     half_life: null          # exponential half-life: int points or "3d"/"12h"
     detrend: null            # null | linear
+    stabilization: null      # null (off) | clamp
     # --- execution (NOT hashed) ---
     start_time: "2024-01-01 00:00:00"   # optional; when detection begins (default: loading_start_time)
     batch_size: 500
@@ -161,6 +162,24 @@ Trade-off: a shorter `half_life` adapts faster but also "accepts" a real
 sustained degradation as the new normal sooner. (`weight_decay` is a deprecated
 alias for `half_life`; prefer `half_life`.)
 
+## Stabilization — sustained incidents poisoning their own baseline
+
+A sustained incident's anomalous points enter the trailing window and inflate
+the spread / drag the center toward it, so the band widens mid-incident and the
+detector stops flagging the tail ("the incident becomes the new normal") —
+z-score (mean/std) is the most vulnerable; median/quartile-based mad/iqr resist
+short incidents but still bend under a long one. `stabilization: clamp` fixes
+this: once a point is flagged anomalous, subsequent trailing windows see it
+**clamped to the confidence bound it violated** (winsorized) instead of the
+raw value — only the statistics windows read the substituted history; scored
+and persisted values are unchanged, and anomalies still render as anomalies.
+Reach for it when alerting on metrics with occasional sustained incidents; it
+composes with `window_weights`/`half_life` (where it matters most, since
+recency weighting gives an ongoing incident's points more weight), `detrend`,
+`smoothing`, `input_type` and seasonality groups, and is near-neutral on clean
+series. Enabling it is a hashed change — it produces a new `detector_id` and
+recomputes on the next run; existing configs that don't set it keep their ids.
+
 ## Feature compatibility
 
 | Feature | mad | zscore | iqr | manual_bounds |
@@ -169,6 +188,7 @@ alias for `half_life`; prefer `half_life`.)
 | `smoothing` | Yes | Yes | Yes | No |
 | `window_weights` / `half_life` | Yes | Yes | Yes | No |
 | `detrend` | Yes | Yes | Yes | No |
+| `stabilization` | Yes | Yes | Yes | No |
 | `seasonality_components` | Yes | Yes | Yes | No |
 
 `manual_bounds` has no window, so window-based features don't apply.
@@ -177,9 +197,9 @@ alias for `half_life`; prefer `half_life`.)
 
 Every parameter that affects results (threshold, window_size, min_samples,
 seasonality_components, min_samples_per_group, input_type, smoothing*,
-window_weights, half_life, detrend) is hashed into the `detector_id` — only
-non-default values participate. Execution params (`start_time`, `batch_size`)
-are **not** hashed.
+window_weights, half_life, detrend, stabilization) is hashed into the
+`detector_id` — only non-default values participate. Execution params
+(`start_time`, `batch_size`) are **not** hashed.
 
 Changing any hashed parameter creates a new `detector_id` and recomputes that
 detector's detections from scratch on the next run; old rows stay under the

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/cli/assets/claude/skills/dtk-tune/SKILL.md

@@ -101,7 +101,10 @@ Walk the user to the mode that fits what they want to do:
   **window size**, **recency weighting + half-life**, **detrend**, **smoothing**,
   and **seasonality groups**; the band + anomalies + would-fire alerts recompute
   on every change. The window-size / half-life readouts show the equivalent
-  wall-clock span. This is the core "turn the knobs yourself" loop.
+  wall-clock span. **Stabilization** (none / clamp) clamps a flagged point to
+  the bound it violated in later windows' statistics — try it when a sustained
+  incident visibly balloons the band mid-incident and the detector stops
+  flagging its tail. This is the core "turn the knobs yourself" loop.
 
 - **Autotune** — *let the engine search, then refine.* Click **Run autotune** and
   the **same engine `dtk autotune` uses** (seasonality → detector → grid → window,

{detectkit-0.50.0 → detectkit-0.51.0}/detectkit/detectors/statistical/_windowed.py

@@ -48,6 +48,7 @@ _CHANGE_INPUT_TYPES = {"changes", "absolute_changes", "log_changes"}
 _SMOOTHING_METHODS = {None, "ema", "sma"}
 _WEIGHT_METHODS = {None, "exponential", "linear"}
 _DETREND_METHODS = {None, "linear"}
+_STABILIZATION_METHODS = {None, "clamp"}
 
 
 class WindowedStatDetector(BaseDetector):
@@ -88,6 +89,18 @@ class WindowedStatDetector(BaseDetector):
             compute statistics on values projected to the current point.
             Recommended for metrics with a gradual trend so the slow
             drift itself is not flagged as anomalous.
+        stabilization (str | None): None (default) or "clamp" — when a
+            point is flagged anomalous, subsequent trailing windows see
+            the confidence bound it violated (winsorized value) instead
+            of the observed value. Keeps a long incident from poisoning
+            the baseline (inflating spread / dragging the center toward
+            the incident), so the detector keeps flagging it instead of
+            adapting to it. Clamping to the bound (not the center) is
+            deliberate: substituting the band center feeds zero-deviation
+            points back into the spread statistics, which collapses the
+            band and cascades into false flags after a long incident.
+            The scored/persisted values are unchanged — only the
+            statistics windows read the substituted history.
 
     All parameters that change detection output participate in the
     detector ID hash (only non-default values are hashed).
@@ -124,6 +137,7 @@ class WindowedStatDetector(BaseDetector):
         half_life: int | str | None = None,
         weight_decay: float | None = None,
         detrend: str | None = None,
+        stabilization: str | None = None,
     ):
         super().__init__(
             threshold=self.THRESHOLD_DEFAULT if threshold is None else threshold,
@@ -143,6 +157,7 @@ class WindowedStatDetector(BaseDetector):
             half_life=half_life,
             weight_decay=weight_decay,
             detrend=detrend,
+            stabilization=stabilization,
         )
         # Whether the one-time "seasonality groups can't fill this window" check
         # has run for this instance (so the warning fires at most once per run,
@@ -235,6 +250,10 @@ class WindowedStatDetector(BaseDetector):
         if detrend not in _DETREND_METHODS:
             raise ValueError(f"Unknown detrend method: {detrend}. Supported: linear")
 
+        stabilization = p.get("stabilization")
+        if stabilization not in _STABILIZATION_METHODS:
+            raise ValueError(f"Unknown stabilization method: {stabilization}. Supported: clamp")
+
     # ------------------------------------------------------------------
     # Identity
     # ------------------------------------------------------------------
@@ -254,6 +273,7 @@ class WindowedStatDetector(BaseDetector):
             "half_life": None,
             "weight_decay": None,
             "detrend": None,
+            "stabilization": None,
         }
 
     def _get_non_default_params(self) -> dict[str, Any]:
@@ -291,6 +311,15 @@ class WindowedStatDetector(BaseDetector):
         if self.params.get("input_type", "values") in _CHANGE_INPUT_TYPES:
             context += 1
 
+        if self.params.get("stabilization"):
+            # A point's substituted-history state depends on whether its own
+            # window points were flagged, which depends on THEIR windows. One
+            # extra window of warm-up lets every context point be scored on a
+            # full window, so incremental batches reproduce the same
+            # substitution history as a continuous run (residual differences
+            # decay geometrically past that).
+            context += int(self.params.get("window_size", 0) or 0)
+
         return context
 
     def _resolve_half_life_points(self, timestamps: np.ndarray) -> float:
@@ -463,12 +492,22 @@ class WindowedStatDetector(BaseDetector):
             "min_samples_per_group", self.MIN_SAMPLES_PER_GROUP_DEFAULT
         )
         detrend = self.params.get("detrend")
+        stabilization = self.params.get("stabilization")
         weighted = self.params.get("window_weights") is not None
 
         # STEP 0: Preprocessing (smoothing first, then input_type)
         smoothed_values = self._apply_smoothing(values)
         processed_values = self._preprocess_input(smoothed_values)
 
+        # Stabilization (opt-in): statistics windows read from a working copy
+        # where every previously-flagged point is clamped to the confidence
+        # bound it violated, so an ongoing incident cannot inflate the spread
+        # or drag the center toward itself. The scored value and the persisted
+        # processed_value stay the raw observations; genuinely missing (NaN)
+        # points are never substituted.
+        work_values = processed_values.copy() if stabilization else processed_values
+        replaced = np.zeros(len(processed_values), dtype=bool) if stabilization else None
+
         seasonality_dict = {}
         if seasonality_components and len(seasonality_data) > 0 and seasonality_columns:
             seasonality_dict = parse_seasonality_data(seasonality_data, seasonality_columns)
@@ -498,9 +537,11 @@ class WindowedStatDetector(BaseDetector):
                 )
                 continue
 
-            # Trailing window, current point excluded
+            # Trailing window, current point excluded. Both the global slice
+            # and the seasonality-group slices below read window_processed, so
+            # sourcing it from work_values covers every statistics consumer.
             window_start = max(0, i - window_size)
-            window_processed = processed_values[window_start:i]
+            window_processed = work_values[window_start:i]
             valid_mask = ~np.isnan(window_processed)
             window_valid = window_processed[valid_mask]
 
@@ -586,6 +627,14 @@ class WindowedStatDetector(BaseDetector):
                 current_processed > confidence_upper
             )
 
+            # Stabilization write-back: later windows see this point clamped
+            # to the bound it violated, not the anomalous observation.
+            if stabilization == "clamp" and is_anomaly:
+                work_values[i] = (
+                    confidence_lower if current_processed < confidence_lower else confidence_upper
+                )
+                replaced[i] = True  # type: ignore[index]
+
             # STEP 5: Metadata
             metadata: dict[str, Any] = {}
             for name, _ in self.STATS:
@@ -598,6 +647,10 @@ class WindowedStatDetector(BaseDetector):
                 metadata["ess"] = round(effective_sample_size(weights), 1)
             if detrend == "linear":
                 metadata["trend_slope_per_point"] = float(slope)
+            if replaced is not None:
+                n_replaced = int(np.count_nonzero(replaced[window_start:i]))
+                if n_replaced:
+                    metadata["stabilized_in_window"] = n_replaced
 
             if self.params.get("smoothing") or self.params.get("input_type") != "values":
                 metadata["preprocessing"] = {