detectkit 0.8.2__tar.gz → 0.9.0__tar.gz

{detectkit-0.8.2/detectkit.egg-info → detectkit-0.9.0}/PKG-INFO

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

{detectkit-0.8.2 → detectkit-0.9.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.8.2"
+__version__ = "0.9.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/alerting/channels/base.py

@@ -36,6 +36,15 @@ class AlertData:
             as ``{project_name}`` in templates and as a ``[name] `` prefix
             in the default error title. Lets multiple projects share the
             same alert channel without ambiguity.
+
+    Alert-rule fields (``min_detectors``, ``direction_policy``,
+    ``consecutive_required``, ``detector_count``) describe *why the alert
+    fired* — the configured quorum/direction/consecutive thresholds plus
+    the observed number of agreeing detectors. They are filled by the
+    orchestrator from :class:`AlertConditions` and are deliberately kept
+    distinct from the observed ``direction``/``consecutive_count`` above so
+    templates can contrast "required vs actual". They default to ``None``
+    so direct-API callers (and non-anomaly alerts) still render cleanly.
     """
 
     metric_name: str
@@ -58,6 +67,11 @@ class AlertData:
     description: str | None = None
     mentions: list[str] = field(default_factory=list)
     project_name: str | None = None
+    # Alert rule (the parameters the alert fired with) — see class docstring.
+    min_detectors: int | None = None
+    direction_policy: str | None = None
+    consecutive_required: int | None = None
+    detector_count: int = 1
 
 
 class BaseAlertChannel(ABC):
@@ -123,10 +137,17 @@ class BaseAlertChannel(ABC):
         - {value} / {value_display}
         - {confidence_lower}
         - {confidence_upper}
+        - {confidence_interval} — "[lower, upper]" or "N/A"
+        - {expected_range} — one-sided aware: ">= lo", "<= hi",
+          "[lo, hi]" or "N/A" (renders one-sided detector bounds cleanly)
         - {detector_name}
-        - {direction}
+        - {detector_count} — observed detectors that agreed (the quorum)
+        - {direction} — observed/locked direction of the anomaly
+        - {direction_policy} — configured direction rule ("same"/"any"/...)
+        - {min_detectors} — configured quorum threshold (the rule)
+        - {consecutive_count} — observed consecutive points
+        - {consecutive_required} — configured consecutive threshold (rule)
         - {severity}
-        - {consecutive_count}
         - {status}
 
         Args:
@@ -177,6 +198,40 @@ class BaseAlertChannel(ABC):
         else:
             confidence_str = "N/A"
 
+        # One-sided-aware expected range. A NaN/inf bound means "no bound on
+        # that side" (e.g. ManualBounds with only ``lower_bound`` set), so we
+        # render ">= lo" / "<= hi" instead of the confusing "[7.00, nan]".
+        def _bounded(b: Any) -> bool:
+            return b is not None and not (isinstance(b, float) and (math.isnan(b) or math.isinf(b)))
+
+        lo_ok = _bounded(alert_data.confidence_lower)
+        hi_ok = _bounded(alert_data.confidence_upper)
+        if lo_ok and hi_ok:
+            expected_range = (
+                f"[{alert_data.confidence_lower:.2f}, {alert_data.confidence_upper:.2f}]"
+            )
+        elif lo_ok:
+            expected_range = f">= {alert_data.confidence_lower:.2f}"
+        elif hi_ok:
+            expected_range = f"<= {alert_data.confidence_upper:.2f}"
+        else:
+            expected_range = "N/A"
+
+        # Alert-rule display values. The orchestrator fills these from the
+        # configured AlertConditions; for direct-API/non-anomaly callers that
+        # leave them unset we fall back to the observed counts so the default
+        # templates never render a bare "None".
+        detector_count = alert_data.detector_count
+        min_detectors = (
+            alert_data.min_detectors if alert_data.min_detectors is not None else detector_count
+        )
+        consecutive_required = (
+            alert_data.consecutive_required
+            if alert_data.consecutive_required is not None
+            else alert_data.consecutive_count
+        )
+        direction_policy = alert_data.direction_policy or alert_data.direction
+
         # Display-safe value: stays usable even when value is None/NaN (no-data).
         raw_value = alert_data.value
         if raw_value is None or (isinstance(raw_value, float) and math.isnan(raw_value)):
@@ -221,11 +276,16 @@ class BaseAlertChannel(ABC):
                 confidence_lower=alert_data.confidence_lower,
                 confidence_upper=alert_data.confidence_upper,
                 confidence_interval=confidence_str,
+                expected_range=expected_range,
                 detector_name=alert_data.detector_name,
+                detector_count=detector_count,
                 detector_params=alert_data.detector_params,
                 direction=alert_data.direction,
+                direction_policy=direction_policy,
+                min_detectors=min_detectors,
                 severity=alert_data.severity,
                 consecutive_count=alert_data.consecutive_count,
+                consecutive_required=consecutive_required,
                 status=status,
                 error_type=alert_data.error_type or "",
                 error_message=alert_data.error_message or "",
@@ -312,12 +372,19 @@ class BaseAlertChannel(ABC):
             Default template string
         """
         return (
-            "Anomaly detected in metric: {metric_name}\n"
+            "⚠ Alert: {metric_name}\n"
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Direction: {direction} | Severity: {severity:.2f} | Consecutive: {consecutive_count}\n"
-            "Detector: {detector_name}\n"
+            "Quorum {detector_count}/{min_detectors} · "
+            "direction {direction} (policy {direction_policy}) · "
+            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point (evidence):\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "· Severity: {severity:.2f}\n"
+            "Detectors: {detector_name}\n"
             "Parameters: {detector_params}"
             "{mentions_line}"
         )
@@ -330,12 +397,17 @@ class BaseAlertChannel(ABC):
             Default recovery template string
         """
         return (
-            "Metric recovered: {metric_name}\n"
+            "✅ Alert cleared: {metric_name}\n"
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Detector: {detector_name}\n"
-            "Status: metric returned to normal"
+            "The alert condition no longer holds — "
+            "the metric is back within expected bounds.\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point:\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Detectors: {detector_name}"
             "{mentions_line}"
         )
 
@@ -348,7 +420,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default title template string
         """
-        return "Anomaly detected: {metric_name}"
+        return "⚠ Alert: {metric_name}"
 
     def get_default_recovery_title_template(self) -> str:
         """
@@ -357,7 +429,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default recovery title template string
         """
-        return "Metric recovered: {metric_name}"
+        return "✅ Alert cleared: {metric_name}"
 
     def get_default_no_data_template(self) -> str:
         """

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/alerting/channels/email.py

@@ -54,7 +54,7 @@ class EmailChannel(BaseAlertChannel):
         smtp_username: str | None = None,
         smtp_password: str | None = None,
         use_tls: bool = True,
-        subject_template: str = "Anomaly Alert: {metric_name}",
+        subject_template: str = "⚠ Alert: {metric_name}",
         template: str | None = None,
         **kwargs,
     ):

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/alerting/channels/webhook.py

@@ -155,10 +155,17 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Direction: {direction} | Severity: {severity:.2f} | Consecutive: {consecutive_count}\n"
-            "Detector: {detector_name}\n"
+            "Quorum {detector_count}/{min_detectors} · "
+            "direction {direction} (policy {direction_policy}) · "
+            "consecutive {consecutive_count}/{consecutive_required}\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point (evidence):\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "· Severity: {severity:.2f}\n"
+            "Detectors: {detector_name}\n"
             "Parameters: {detector_params}"
             "{mentions_line}"
         )
@@ -171,10 +178,15 @@ class WebhookChannel(BaseAlertChannel):
         """
         return (
             "{description_line}"
-            "Time: {timestamp}\n"
-            "Value: {value} | CI: {confidence_interval}\n"
-            "Detector: {detector_name}\n"
-            "Status: metric returned to normal"
+            "The alert condition no longer holds — "
+            "the metric is back within expected bounds.\n"
+            "Rule: min_detectors={min_detectors} · "
+            "direction={direction_policy} · consecutive={consecutive_required}\n"
+            "\n"
+            "Latest point:\n"
+            "· Time: {timestamp}\n"
+            "· Value: {value_display} | Expected: {expected_range}\n"
+            "Detectors: {detector_name}"
             "{mentions_line}"
         )
 

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/alerting/orchestrator/_decision.py

@@ -207,6 +207,23 @@ class _DecisionMixin(_OrchestratorBase):
             detector_params = primary.detector_params
             combined_metadata = primary.detection_metadata
 
+        # Observed direction shown in the message. For "same"/"up"/"down" the
+        # caller passes the locked/policy direction. For "any" it passes None
+        # because the quorum may combine directions — collapse to the shared
+        # side only when every quorum member agrees, otherwise label it
+        # "mixed" so the message never claims an agreement that did not happen
+        # (e.g. one up + one down satisfying min_detectors=2).
+        if direction:
+            observed_direction = direction
+        else:
+            quorum_dirs = {d.direction for d in anomalies if d.direction in ("up", "down")}
+            if len(quorum_dirs) == 1:
+                observed_direction = next(iter(quorum_dirs))
+            elif len(quorum_dirs) >= 2:
+                observed_direction = "mixed"
+            else:
+                observed_direction = primary.direction
+
         return AlertData(
             metric_name=self.metric_name,
             timestamp=primary.timestamp,
@@ -216,12 +233,18 @@ class _DecisionMixin(_OrchestratorBase):
             confidence_upper=primary.confidence_upper,
             detector_name=detector_name,
             detector_params=detector_params,
-            direction=direction or primary.direction,
+            direction=observed_direction,
             severity=max_severity,
             detection_metadata=combined_metadata,
             consecutive_count=consecutive_count,
             description=self.description,
             mentions=self.mentions,
+            # Alert rule the message foregrounds: configured thresholds plus
+            # the observed quorum size that satisfied them.
+            min_detectors=self.conditions.min_detectors,
+            direction_policy=self.conditions.direction,
+            consecutive_required=self.conditions.consecutive_anomalies,
+            detector_count=len(anomalies),
         )
 
     def should_alert_no_data(

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -176,4 +176,9 @@ class _RecoveryMixin(_OrchestratorBase):
             is_recovery=True,
             description=self.description,
             mentions=self.mentions,
+            # Echo the rule that had fired so the recovery message names the
+            # same alert condition that just cleared.
+            min_detectors=self.conditions.min_detectors,
+            direction_policy=self.conditions.direction,
+            consecutive_required=self.conditions.consecutive_anomalies,
         )

{detectkit-0.8.2 → detectkit-0.9.0}/detectkit/cli/commands/test_alert.py

@@ -44,6 +44,23 @@ def create_mock_alert_data(
     # different teams). Pull them from the specific config we're testing.
     mentions = list(alerting_config.mentions) if alerting_config else []
 
+    # Preview the alert with the rule it would actually fire on (min_detectors
+    # / direction / consecutive) so the test message matches the alert-centric
+    # default layout. Observed counts are set to satisfy the rule, as a real
+    # firing would.
+    min_detectors = getattr(alerting_config, "min_detectors", 1) or 1
+    direction_policy = getattr(alerting_config, "direction", "same") or "same"
+    consecutive_required = getattr(alerting_config, "consecutive_anomalies", 1) or 1
+    # Observed direction for the preview: a concrete side for up/down/same; for
+    # an "any" quorum of 2+ detectors show "mixed" (its whole point is that
+    # cross-direction anomalies combine), mirroring the real engine output.
+    if direction_policy in ("up", "down"):
+        observed_direction = direction_policy
+    elif direction_policy == "any" and min_detectors >= 2:
+        observed_direction = "mixed"
+    else:
+        observed_direction = "up"
+
     # Create realistic mock data
     return AlertData(
         metric_name=metric_config.name,
@@ -54,7 +71,7 @@ def create_mock_alert_data(
         confidence_upper=0.6234,
         detector_name="MADDetector:threshold=3.0",
         detector_params='{"threshold": 3.0, "window_size": 8640}',
-        direction="above",
+        direction=observed_direction,
         severity=4.52,
         detection_metadata={
             "global_median": 0.5123,
@@ -68,8 +85,12 @@ def create_mock_alert_data(
                 }
             ],
         },
-        consecutive_count=3,
+        consecutive_count=consecutive_required,
         mentions=mentions,
+        min_detectors=min_detectors,
+        direction_policy=direction_policy,
+        consecutive_required=consecutive_required,
+        detector_count=min_detectors,
     )
 
 

{detectkit-0.8.2 → detectkit-0.9.0/detectkit.egg-info}/PKG-INFO

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