detectkit 0.3.13__tar.gz → 0.3.15__tar.gz

{detectkit-0.3.13/detectkit.egg-info → detectkit-0.3.15}/PKG-INFO

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

{detectkit-0.3.13 → detectkit-0.3.15}/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.3.13"
+__version__ = "0.3.14"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.3.13 → detectkit-0.3.15}/detectkit/alerting/channels/base.py

@@ -144,10 +144,13 @@ class BaseAlertChannel(ABC):
         if isinstance(ts, np.datetime64):
             ts = ts.astype(datetime)
 
-        # Format timestamp with timezone
-        ts_str = ts.strftime("%Y-%m-%d %H:%M:%S")
+        # Convert naive UTC timestamp to target timezone if specified
         if alert_data.timezone:
-            ts_str = f"{ts_str} ({alert_data.timezone})"
+            from zoneinfo import ZoneInfo
+            ts = ts.replace(tzinfo=ZoneInfo("UTC")).astimezone(ZoneInfo(alert_data.timezone))
+            ts_str = f"{ts.strftime('%Y-%m-%d %H:%M:%S')} ({alert_data.timezone})"
+        else:
+            ts_str = ts.strftime("%Y-%m-%d %H:%M:%S")
 
         # Format confidence interval
         if alert_data.confidence_lower is not None and alert_data.confidence_upper is not None:

{detectkit-0.3.13 → detectkit-0.3.15}/detectkit/alerting/orchestrator.py

@@ -9,9 +9,10 @@ Handles:
 - Coordinating alert sending
 """
 
+import json
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
 from detectkit.utils.datetime_utils import now_utc, now_utc_naive, to_naive_utc, to_aware_utc
 
 import numpy as np
@@ -20,6 +21,48 @@ from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
 from detectkit.core.interval import Interval
 
 
+def _parse_detection_metadata(metadata: Any) -> Dict:
+    """Parse detection_metadata stored as dict or JSON string into a dict."""
+    if metadata is None:
+        return {}
+    if isinstance(metadata, dict):
+        return metadata
+    if isinstance(metadata, (bytes, bytearray)):
+        try:
+            metadata = metadata.decode("utf-8")
+        except Exception:
+            return {}
+    if isinstance(metadata, str):
+        if not metadata:
+            return {}
+        try:
+            parsed = json.loads(metadata)
+            return parsed if isinstance(parsed, dict) else {}
+        except (ValueError, TypeError):
+            return {}
+    return {}
+
+
+def _direction_from_metadata(metadata: Any, is_anomaly: bool) -> str:
+    """
+    Resolve alert direction ("up"/"down"/"none") from detector metadata.
+
+    Detectors authoritatively write direction as "below"/"above" in
+    detection_metadata. This is the source of truth — confidence-bound
+    reconstruction does not work for one-sided detectors (e.g. ManualBounds
+    with only upper_bound set).
+    """
+    if not is_anomaly:
+        return "none"
+    parsed = _parse_detection_metadata(metadata)
+    raw = parsed.get("direction")
+    if raw == "below":
+        return "down"
+    if raw == "above":
+        return "up"
+    return "none"
+
+
 @dataclass
 class AlertConditions:
     """Alert conditions configuration."""
@@ -488,26 +531,19 @@ class AlertOrchestrator:
         # Convert to DetectionRecord format
         detection_records = []
         for det in recent_detections:
+            metadata_list = det.get("detection_metadata_list") or [None] * len(det["detector_ids"])
             # Group has multiple detectors per timestamp
             for i in range(len(det["detector_ids"])):
-                # Parse detection metadata
-                try:
-                    import json
-                    metadata = json.loads(det["detector_params_list"][i])
-                except:
-                    metadata = {}
-
-                # Determine direction
                 value = det["value"]
                 conf_lower = det["confidence_lowers"][i]
                 conf_upper = det["confidence_uppers"][i]
+                is_anomaly = det["is_anomaly_flags"][i]
 
-                if value < conf_lower:
-                    direction = "down"
-                elif value > conf_upper:
-                    direction = "up"
-                else:
-                    direction = "none"
+                # Use detector-authoritative direction from detection_metadata
+                # (works for one-sided detectors like ManualBounds where
+                # confidence_lower/upper may be None).
+                metadata = _parse_detection_metadata(metadata_list[i])
+                direction = _direction_from_metadata(metadata, is_anomaly)
 
                 record = DetectionRecord(
                     timestamp=np.datetime64(det["timestamp"]),
@@ -515,12 +551,12 @@ class AlertOrchestrator:
                     detector_id=det["detector_ids"][i],
                     detector_params=det["detector_params_list"][i],
                     value=value,
-                    is_anomaly=det["is_anomaly_flags"][i],
+                    is_anomaly=is_anomaly,
                     confidence_lower=conf_lower,
                     confidence_upper=conf_upper,
                     direction=direction,
                     severity=0.0,  # Not used for recovery check
-                    detection_metadata=metadata
+                    detection_metadata=metadata,
                 )
                 detection_records.append(record)
 
@@ -528,18 +564,64 @@ class AlertOrchestrator:
         detections_by_time = self._group_by_timestamp(detection_records)
         timestamps_sorted = sorted(detections_by_time.keys(), reverse=True)
 
-        # Check that latest post-alert point is NOT anomalous by ANY detector.
-        # Recovery = zero detectors flag the latest point as anomalous.
-        # Using > 0 (not >= min_detectors) prevents false recovery when
-        # some but not all detectors still flag the metric as anomalous.
+        # Direction-aware recovery: only block recovery on anomalies that
+        # match the alert's direction condition. For a "down"-only alert an
+        # "up" anomaly already means the alert condition no longer holds, so
+        # it should count as recovery.
+        direction_condition = self.conditions.direction
         latest_ts = timestamps_sorted[0]
         latest_detections = detections_by_time[latest_ts]
         latest_anomalies = [d for d in latest_detections if d.is_anomaly]
-        if len(latest_anomalies) > 0:
-            # At least one detector still considers this point anomalous — no recovery
-            return False
 
-        return True
+        if direction_condition == "down":
+            blocking = [d for d in latest_anomalies if d.direction == "down"]
+        elif direction_condition == "up":
+            blocking = [d for d in latest_anomalies if d.direction == "up"]
+        elif direction_condition == "same":
+            trigger_direction = self._get_alert_trigger_direction(last_alert_timestamp)
+            if trigger_direction is None:
+                # Unknown trigger direction → fall back to conservative behavior
+                blocking = latest_anomalies
+            else:
+                blocking = [d for d in latest_anomalies if d.direction == trigger_direction]
+        else:  # "any" and unknown — preserve historical behavior
+            blocking = latest_anomalies
+
+        return len(blocking) == 0
+
+    def _get_alert_trigger_direction(
+        self, last_alert_timestamp: datetime
+    ) -> Optional[str]:
+        """
+        Resolve the direction of the anomaly that triggered the last alert.
+
+        Used by direction="same" recovery logic. Loads the detection record
+        at last_alert_timestamp and returns the dominant anomaly direction
+        from detection_metadata.
+
+        Returns:
+            "up", "down", or None if not resolvable.
+        """
+        if not self.internal:
+            return None
+
+        trigger_detections = self.internal.get_recent_detections(
+            metric_name=self.metric_name,
+            last_point=last_alert_timestamp,
+            num_points=1,
+        )
+        if not trigger_detections:
+            return None
+
+        det = trigger_detections[0]
+        metadata_list = det.get("detection_metadata_list") or [None] * len(det["detector_ids"])
+        for i in range(len(det["detector_ids"])):
+            if not det["is_anomaly_flags"][i]:
+                continue
+            direction = _direction_from_metadata(metadata_list[i], True)
+            if direction in ("up", "down"):
+                return direction
+        return None
 
     def should_send_recovery(
         self,
@@ -601,19 +683,37 @@ class AlertOrchestrator:
         if not detections:
             return None
 
-        # Use the latest (newest) detection point for recovery info.
+        # Use the latest (newest) detection point for recovery timestamp/value.
         # detections are sorted oldest→newest by _load_recent_detections.
         latest = detections[-1]
 
+        # Use detector info and CI from the last anomalous detection
+        # (the one that triggered the alert), since normal points have
+        # detector_name="unknown" and confidence=None.
+        last_anomalous = next(
+            (d for d in reversed(detections) if d.is_anomaly),
+            None,
+        )
+        if last_anomalous:
+            recovery_detector_name = last_anomalous.detector_name
+            recovery_detector_params = last_anomalous.detector_params
+            recovery_ci_lower = last_anomalous.confidence_lower
+            recovery_ci_upper = last_anomalous.confidence_upper
+        else:
+            recovery_detector_name = latest.detector_name
+            recovery_detector_params = latest.detector_params
+            recovery_ci_lower = latest.confidence_lower
+            recovery_ci_upper = latest.confidence_upper
+
         return AlertData(
             metric_name=self.metric_name,
             timestamp=latest.timestamp,
             timezone=self.timezone_display,
             value=latest.value,
-            confidence_lower=latest.confidence_lower,
-            confidence_upper=latest.confidence_upper,
-            detector_name=latest.detector_name,
-            detector_params=latest.detector_params,
+            confidence_lower=recovery_ci_lower,
+            confidence_upper=recovery_ci_upper,
+            detector_name=recovery_detector_name,
+            detector_params=recovery_detector_params,
             direction="none",
             severity=0.0,
             detection_metadata={},

{detectkit-0.3.13 → detectkit-0.3.15}/detectkit/database/internal_tables.py

@@ -467,6 +467,7 @@ class InternalTablesManager:
                 - detector_ids: List of detector IDs for this timestamp
                 - detector_names: List of detector names
                 - detector_params_list: List of detector params (JSON strings)
+                - detection_metadata_list: List of detection metadata (JSON strings)
                 - is_anomaly_flags: List of is_anomaly bools
                 - confidence_lowers: List of lower confidence bounds
                 - confidence_uppers: List of upper confidence bounds
@@ -531,6 +532,7 @@ class InternalTablesManager:
             detector_id,
             detector_name,
             detector_params,
+            detection_metadata,
             is_anomaly,
             confidence_lower,
             confidence_upper,
@@ -570,6 +572,7 @@ class InternalTablesManager:
                     "detector_ids": [],
                     "detector_names": [],
                     "detector_params_list": [],
+                    "detection_metadata_list": [],
                     "is_anomaly_flags": [],
                     "confidence_lowers": [],
                     "confidence_uppers": [],
@@ -579,6 +582,7 @@ class InternalTablesManager:
             grouped[ts_key]["detector_ids"].append(row["detector_id"])
             grouped[ts_key]["detector_names"].append(row["detector_name"])
             grouped[ts_key]["detector_params_list"].append(row["detector_params"])
+            grouped[ts_key]["detection_metadata_list"].append(row.get("detection_metadata"))
             grouped[ts_key]["is_anomaly_flags"].append(row["is_anomaly"])
             grouped[ts_key]["confidence_lowers"].append(row["confidence_lower"])
             grouped[ts_key]["confidence_uppers"].append(row["confidence_upper"])

{detectkit-0.3.13 → detectkit-0.3.15}/detectkit/orchestration/task_manager.py

@@ -23,6 +23,8 @@ from detectkit.alerting.orchestrator import (
     AlertConditions,
     AlertOrchestrator,
     DetectionRecord,
+    _direction_from_metadata,
+    _parse_detection_metadata,
 )
 from detectkit.config.metric_config import MetricConfig
 from detectkit.core.interval import Interval
@@ -737,7 +739,9 @@ class TaskManager:
                 if flag
             ]
 
-            # Determine direction and severity for the most severe detector
+            # Determine direction and severity for the most severe detector.
+            # Direction is read from detector metadata (authoritative for all
+            # detectors including ManualBounds where confidence bounds may be None).
             direction = "none"
             severity = 0.0
             confidence_lower = None
@@ -745,6 +749,9 @@ class TaskManager:
             detector_name = "unknown"
             detector_id = "unknown"
             detector_params = "{}"
+            metadata: dict = {}
+
+            metadata_list = row.get("detection_metadata_list") or [None] * len(row["detector_ids"])
 
             if is_anomaly and anomaly_indices:
                 # Get data from first anomalous detector
@@ -755,14 +762,12 @@ class TaskManager:
                 confidence_lower = row["confidence_lowers"][first_idx]
                 confidence_upper = row["confidence_uppers"][first_idx]
 
-                # Determine direction
-                value = row["value"]
-                if value < confidence_lower:
-                    direction = "down"
-                    severity = (confidence_lower - value) / max(abs(confidence_lower), 1e-10)
-                elif value > confidence_upper:
-                    direction = "up"
-                    severity = (value - confidence_upper) / max(abs(confidence_upper), 1e-10)
+                metadata = _parse_detection_metadata(metadata_list[first_idx])
+                direction = _direction_from_metadata(metadata, True)
+                try:
+                    severity = float(metadata.get("severity", 0.0) or 0.0)
+                except (TypeError, ValueError):
+                    severity = 0.0
 
             records.append(
                 DetectionRecord(
@@ -776,7 +781,7 @@ class TaskManager:
                     confidence_upper=confidence_upper,
                     direction=direction,
                     severity=severity,
-                    detection_metadata={},
+                    detection_metadata=metadata,
                 )
             )
 

{detectkit-0.3.13 → detectkit-0.3.15/detectkit.egg-info}/PKG-INFO

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

{detectkit-0.3.13 → detectkit-0.3.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "detectkit"
-version = "0.3.13"
+version = "0.3.15"
 description = "Metric monitoring with automatic anomaly detection"
 readme = "README.md"
 requires-python = ">=3.10"