detectkit 0.3.12__tar.gz → 0.3.13__tar.gz

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

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

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

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

@@ -12,6 +12,7 @@ Handles:
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Dict, List, Optional
+from detectkit.utils.datetime_utils import now_utc, now_utc_naive, to_naive_utc, to_aware_utc
 
 import numpy as np
 
@@ -60,6 +61,7 @@ class AlertOrchestrator:
         >>> orchestrator = AlertOrchestrator(
         ...     metric_name="cpu_usage",
         ...     interval=Interval.parse("10min"),
+        ...     alert_config_id="abc123",
         ...     conditions=AlertConditions(consecutive_anomalies=3, direction="same")
         ... )
         >>> should_alert, alert_data = orchestrator.should_alert(recent_detections)
@@ -71,6 +73,7 @@ class AlertOrchestrator:
         self,
         metric_name: str,
         interval: Interval,
+        alert_config_id: str,
         conditions: Optional[AlertConditions] = None,
         timezone_display: str = "UTC",
         internal=None,  # InternalTablesManager (optional, for cooldown tracking)
@@ -84,6 +87,7 @@ class AlertOrchestrator:
         Args:
             metric_name: Name of the metric
             interval: Metric interval
+            alert_config_id: MD5 hash of alerting config params (for independent state per config)
             conditions: Alert conditions (defaults to AlertConditions())
             timezone_display: Timezone for alert display (default: UTC)
             internal: InternalTablesManager instance (optional, for cooldown tracking)
@@ -93,6 +97,7 @@ class AlertOrchestrator:
         """
         self.metric_name = metric_name
         self.interval = interval
+        self.alert_config_id = alert_config_id
         self.conditions = conditions or AlertConditions()
         self.timezone_display = timezone_display
         self.internal = internal
@@ -335,13 +340,14 @@ class AlertOrchestrator:
                 print(f"Error sending alert via {channel_name}: {e}")
                 results[channel_name] = False
 
-        # NEW: Update alert timestamp after sending (for cooldown tracking)
+        # Update alert timestamp after sending (for cooldown tracking)
         if any(results.values()) and self.internal:
             # At least one channel succeeded - update timestamp
             self.internal.update_alert_timestamp(
                 metric_name=self.metric_name,
-                timestamp=datetime.now(timezone.utc).replace(tzinfo=None),
-                increment_count=True
+                alert_config_id=self.alert_config_id,
+                timestamp=now_utc_naive(),
+                increment_count=True,
             )
 
         return results
@@ -362,18 +368,17 @@ class AlertOrchestrator:
             - Example: now=13:23, interval=10min -> 13:10
 
         Example:
-            >>> orchestrator = AlertOrchestrator("metric", Interval.parse("10min"))
+            >>> orchestrator = AlertOrchestrator("metric", Interval.parse("10min"), alert_config_id="abc123")
             >>> now = datetime(2024, 1, 1, 13, 23, 0, tzinfo=timezone.utc)
             >>> last_point = orchestrator.get_last_complete_point(now)
             >>> print(last_point)
             2024-01-01 13:10:00+00:00
         """
         if now is None:
-            now = datetime.now(timezone.utc)
+            now = now_utc()
 
         # Ensure UTC
-        if now.tzinfo is None:
-            now = now.replace(tzinfo=timezone.utc)
+        now = to_aware_utc(now)
 
         # Floor to interval
         interval_seconds = self.interval.seconds
@@ -412,7 +417,7 @@ class AlertOrchestrator:
             return False
 
         # Get last alert timestamp
-        last_sent = self.internal.get_last_alert_timestamp(self.metric_name)
+        last_sent = self.internal.get_last_alert_timestamp(self.metric_name, self.alert_config_id)
 
         if not last_sent:
             return False  # Never sent alert before
@@ -423,7 +428,7 @@ class AlertOrchestrator:
         cooldown_seconds = cooldown_interval.seconds
 
         # Calculate elapsed time
-        now = datetime.now(timezone.utc).replace(tzinfo=None)
+        now = now_utc_naive()
         elapsed = (now - last_sent).total_seconds()
 
         # Check recovery reset (if enabled)
@@ -523,14 +528,15 @@ 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
-        # (prevents false recovery when there are fewer post-alert points
-        # than consecutive_anomalies threshold)
+        # 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.
         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) >= self.conditions.min_detectors:
-            # Latest point is still anomalous — no recovery
+        if len(latest_anomalies) > 0:
+            # At least one detector still considers this point anomalous — no recovery
             return False
 
         return True
@@ -558,12 +564,12 @@ class AlertOrchestrator:
             return False, None
 
         # Check if there was a previous alert
-        last_alert = self.internal.get_last_alert_timestamp(self.metric_name)
+        last_alert = self.internal.get_last_alert_timestamp(self.metric_name, self.alert_config_id)
         if not last_alert:
             return False, None  # Never alerted, nothing to recover from
 
         # Check if recovery already sent for this incident
-        last_recovery = self.internal.get_last_recovery_timestamp(self.metric_name)
+        last_recovery = self.internal.get_last_recovery_timestamp(self.metric_name, self.alert_config_id)
         if last_recovery and last_recovery >= last_alert:
             return False, None  # Already sent recovery for this alert
 
@@ -595,8 +601,9 @@ class AlertOrchestrator:
         if not detections:
             return None
 
-        # Use the latest detection point for recovery info
-        latest = detections[0]
+        # Use the latest (newest) detection point for recovery info.
+        # detections are sorted oldest→newest by _load_recent_detections.
+        latest = detections[-1]
 
         return AlertData(
             metric_name=self.metric_name,
@@ -647,10 +654,10 @@ class AlertOrchestrator:
 
         # Update recovery timestamp after sending
         if any(results.values()) and self.internal:
-            from datetime import timezone as tz
             self.internal.update_recovery_timestamp(
                 metric_name=self.metric_name,
-                timestamp=datetime.now(tz.utc).replace(tzinfo=None),
+                alert_config_id=self.alert_config_id,
+                timestamp=now_utc_naive(),
             )
 
         return results
@@ -661,6 +668,7 @@ class AlertOrchestrator:
             f"AlertOrchestrator("
             f"metric='{self.metric_name}', "
             f"interval={self.interval}, "
+            f"config_id='{self.alert_config_id[:8]}...', "
             f"min_detectors={self.conditions.min_detectors}, "
             f"direction='{self.conditions.direction}', "
             f"consecutive={self.conditions.consecutive_anomalies})"

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit/cli/commands/test_alert.py

@@ -8,11 +8,11 @@ Useful for:
 - Previewing alert templates
 """
 
-from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
 import numpy as np
+from detectkit.utils.datetime_utils import now_utc
 
 from detectkit.alerting.channels.base import AlertData
 from detectkit.alerting.channels.factory import AlertChannelFactory
@@ -34,7 +34,7 @@ def create_mock_alert_data(
         AlertData with mock anomaly data
     """
     # Use current time
-    now = datetime.now(timezone.utc)
+    now = now_utc()
 
     # Get mentions from alerting config
     mentions = metric_config.alerting.mentions if metric_config.alerting else []

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit/database/clickhouse_manager.py

@@ -8,6 +8,7 @@ from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 import numpy as np
+from detectkit.utils.datetime_utils import now_utc_naive, to_naive_utc
 
 try:
     from clickhouse_driver import Client
@@ -345,38 +346,8 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
 
         full_table = self.get_full_table_name(TABLE_TASKS, use_internal=True)
 
-        # Get current UTC time (convert to naive UTC for numpy compatibility)
-        now = datetime.now(timezone.utc).replace(tzinfo=None)
-
-        # Read existing alert tracking fields before delete (preserve across upsert)
-        existing_last_alert_sent = None
-        existing_last_recovery_sent = None
-        existing_alert_count = 0
-
-        preserve_query = f"""
-        SELECT last_alert_sent, last_recovery_sent, alert_count
-        FROM {full_table}
-        WHERE metric_name = %(metric_name)s
-          AND detector_id = %(detector_id)s
-          AND process_type = %(process_type)s
-        ORDER BY updated_at DESC
-        LIMIT 1
-        """
-        try:
-            preserve_results = self.execute_query(
-                preserve_query,
-                params={
-                    "metric_name": metric_name,
-                    "detector_id": detector_id,
-                    "process_type": process_type,
-                }
-            )
-            if preserve_results:
-                existing_last_alert_sent = preserve_results[0].get("last_alert_sent")
-                existing_last_recovery_sent = preserve_results[0].get("last_recovery_sent")
-                existing_alert_count = preserve_results[0].get("alert_count", 0) or 0
-        except Exception:
-            pass  # If read fails, proceed with defaults
+        # Get current UTC time (naive UTC for numpy compatibility)
+        now = now_utc_naive()
 
         # Delete existing record (if any), sync to ensure old row is gone before insert
         delete_query = f"""
@@ -396,15 +367,9 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
             }
         )
 
-        # Convert last_processed_timestamp to naive UTC if needed
-        last_ts_naive = None
-        if last_processed_timestamp:
-            if last_processed_timestamp.tzinfo is not None:
-                last_ts_naive = last_processed_timestamp.replace(tzinfo=None)
-            else:
-                last_ts_naive = last_processed_timestamp
+        last_ts_naive = to_naive_utc(last_processed_timestamp)
 
-        # Then insert new record (preserving alert tracking fields)
+        # Insert new record (alert state is now stored in _dtk_alert_states, not here)
         insert_data = {
             "metric_name": np.array([metric_name]),
             "detector_id": np.array([detector_id]),
@@ -415,9 +380,9 @@ class ClickHouseDatabaseManager(BaseDatabaseManager):
             "last_processed_timestamp": np.array([last_ts_naive], dtype="datetime64[ms]") if last_ts_naive else np.array([None]),
             "error_message": np.array([error_message]),
             "timeout_seconds": np.array([timeout_seconds], dtype=np.int32),
-            "last_alert_sent": np.array([existing_last_alert_sent], dtype="datetime64[ms]") if existing_last_alert_sent else np.array([None]),
-            "alert_count": np.array([existing_alert_count], dtype=np.uint32),
-            "last_recovery_sent": np.array([existing_last_recovery_sent], dtype="datetime64[ms]") if existing_last_recovery_sent else np.array([None]),
+            "last_alert_sent": np.array([None]),
+            "alert_count": np.array([0], dtype=np.uint32),
+            "last_recovery_sent": np.array([None]),
         }
 
         self.insert_batch(

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

@@ -9,14 +9,16 @@ methods underneath. It does NOT duplicate logic - just provides semantic wrapper
 """
 
 import json
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Dict, List, Optional
 
 import numpy as np
+from detectkit.utils.datetime_utils import now_utc_naive, to_naive_utc, to_aware_utc
 
 from detectkit.database.manager import BaseDatabaseManager
 from detectkit.database.tables import (
     INTERNAL_TABLES,
+    TABLE_ALERT_STATES,
     TABLE_DATAPOINTS,
     TABLE_DETECTIONS,
     TABLE_METRICS,
@@ -127,7 +129,7 @@ class InternalTablesManager:
                 num_rows, ",".join(seasonality_columns), dtype=object
             ),
             "created_at": np.full(
-                num_rows, datetime.now(timezone.utc).replace(tzinfo=None), dtype="datetime64[ms]"
+                num_rows, now_utc_naive(), dtype="datetime64[ms]"
             ),
         }
 
@@ -198,7 +200,7 @@ class InternalTablesManager:
             "detector_params": np.full(num_rows, detector_params, dtype=object),
             "detection_metadata": data["detection_metadata"],
             "created_at": np.full(
-                num_rows, datetime.now(timezone.utc).replace(tzinfo=None), dtype="datetime64[ms]"
+                num_rows, now_utc_naive(), dtype="datetime64[ms]"
             ),
         }
 
@@ -343,9 +345,7 @@ class InternalTablesManager:
 
         # Convert timezone-aware timestamps to naive to avoid numpy warning
         timestamps = [
-            row["timestamp"].replace(tzinfo=None)
-            if hasattr(row["timestamp"], 'tzinfo') and row["timestamp"].tzinfo
-            else row["timestamp"]
+            to_naive_utc(row["timestamp"])
             for row in results
         ]
         values = [row["value"] for row in results]
@@ -560,8 +560,7 @@ class InternalTablesManager:
                 ts_value = ts
             else:
                 # datetime object - normalize and convert to string
-                if hasattr(ts, 'tzinfo') and ts.tzinfo is not None:
-                    ts = ts.replace(tzinfo=None)
+                ts = to_naive_utc(ts)
                 ts_key = ts.isoformat()
                 ts_value = ts
 
@@ -791,7 +790,7 @@ class InternalTablesManager:
         )
 
         # Get current UTC time (naive for numpy compatibility)
-        now = datetime.now(timezone.utc).replace(tzinfo=None)
+        now = now_utc_naive()
 
         # Parse loading_start_time if provided
         loading_start_time_dt = None
@@ -801,7 +800,7 @@ class InternalTablesManager:
                 loading_start_time_dt = dt.strptime(
                     metric_config.loading_start_time,
                     "%Y-%m-%d %H:%M:%S"
-                ).replace(tzinfo=None)
+                )  # already naive UTC from config string
             except (ValueError, AttributeError):
                 # If parsing fails, leave as None
                 pass
@@ -858,207 +857,206 @@ class InternalTablesManager:
 
     def get_last_alert_timestamp(
         self,
-        metric_name: str
+        metric_name: str,
+        alert_config_id: str,
     ) -> Optional[datetime]:
         """
-        Get timestamp of last sent alert for a metric.
-
-        Used for alert cooldown tracking - prevents sending alerts
-        too frequently for the same metric.
+        Get timestamp of last sent alert for a specific alerting config.
 
         Args:
             metric_name: Metric identifier
+            alert_config_id: MD5 hash of alerting config params
 
         Returns:
             Timestamp of last sent alert, or None if never sent
-
-        Example:
-            >>> last_sent = internal.get_last_alert_timestamp("cpu_usage")
-            >>> if last_sent:
-            ...     elapsed = (datetime.utcnow() - last_sent).total_seconds()
-            ...     print(f"Last alert sent {elapsed}s ago")
         """
-        full_table_name = self._manager.get_full_table_name(
-            TABLE_TASKS, use_internal=True
-        )
+        state = self.get_alert_state(metric_name, alert_config_id)
+        return state["last_alert_sent"]
 
-        # Query for pipeline task (detector_id="pipeline", process_type="pipeline")
-        query = f"""
-        SELECT last_alert_sent
-        FROM {full_table_name}
-        WHERE metric_name = %(metric_name)s
-          AND detector_id = 'pipeline'
-          AND process_type = 'pipeline'
-        LIMIT 1
+    def update_alert_timestamp(
+        self,
+        metric_name: str,
+        alert_config_id: str,
+        timestamp: datetime,
+        increment_count: bool = True,
+    ) -> int:
         """
+        Update last_alert_sent timestamp for a specific alerting config.
 
-        results = self._manager.execute_query(
-            query,
-            params={"metric_name": metric_name}
-        )
+        Args:
+            metric_name: Metric identifier
+            alert_config_id: MD5 hash of alerting config params
+            timestamp: Timestamp when alert was sent
+            increment_count: Whether to increment alert_count (default: True)
 
-        if not results or not results[0]["last_alert_sent"]:
-            return None
+        Returns:
+            1 (always)
+        """
+        self.upsert_alert_state(
+            metric_name=metric_name,
+            alert_config_id=alert_config_id,
+            last_alert_sent=timestamp,
+            increment_count=increment_count,
+        )
+        return 1
 
-        last_sent = results[0]["last_alert_sent"]
+    def get_last_recovery_timestamp(
+        self,
+        metric_name: str,
+        alert_config_id: str,
+    ) -> Optional[datetime]:
+        """
+        Get timestamp of last sent recovery notification for a specific alerting config.
 
-        # Normalize to naive datetime if needed
-        if hasattr(last_sent, 'tzinfo') and last_sent.tzinfo is not None:
-            last_sent = last_sent.replace(tzinfo=None)
+        Args:
+            metric_name: Metric identifier
+            alert_config_id: MD5 hash of alerting config params
 
-        return last_sent
+        Returns:
+            Timestamp of last sent recovery, or None if never sent
+        """
+        state = self.get_alert_state(metric_name, alert_config_id)
+        return state["last_recovery_sent"]
 
-    def update_alert_timestamp(
+    def update_recovery_timestamp(
         self,
         metric_name: str,
+        alert_config_id: str,
         timestamp: datetime,
-        increment_count: bool = True
     ) -> int:
         """
-        Update last_alert_sent timestamp and optionally increment alert_count.
-
-        Called after successfully sending an alert to track cooldown state.
+        Update last_recovery_sent timestamp for a specific alerting config.
 
         Args:
             metric_name: Metric identifier
-            timestamp: Timestamp when alert was sent (typically datetime.utcnow())
-            increment_count: Whether to increment alert_count (default: True)
+            alert_config_id: MD5 hash of alerting config params
+            timestamp: Timestamp when recovery was sent
 
         Returns:
-            Number of rows updated (typically 1)
-
-        Example:
-            >>> # After sending alert
-            >>> internal.update_alert_timestamp(
-            ...     "cpu_usage",
-            ...     datetime.utcnow(),
-            ...     increment_count=True
-            ... )
+            1 (always)
         """
-        full_table_name = self._manager.get_full_table_name(
-            TABLE_TASKS, use_internal=True
-        )
-
-        # Normalize timestamp to naive if needed
-        if hasattr(timestamp, 'tzinfo') and timestamp.tzinfo is not None:
-            timestamp = timestamp.replace(tzinfo=None)
-
-        if increment_count:
-            # Update with alert_count increment
-            update_query = f"""
-            ALTER TABLE {full_table_name}
-            UPDATE
-                last_alert_sent = %(timestamp)s,
-                alert_count = alert_count + 1,
-                updated_at = %(timestamp)s
-            WHERE metric_name = %(metric_name)s
-              AND detector_id = 'pipeline'
-              AND process_type = 'pipeline'
-            SETTINGS mutations_sync = 1
-            """
-        else:
-            # Update without alert_count increment
-            update_query = f"""
-            ALTER TABLE {full_table_name}
-            UPDATE
-                last_alert_sent = %(timestamp)s,
-                updated_at = %(timestamp)s
-            WHERE metric_name = %(metric_name)s
-              AND detector_id = 'pipeline'
-              AND process_type = 'pipeline'
-            SETTINGS mutations_sync = 1
-            """
-
-        self._manager.execute_query(
-            update_query,
-            params={
-                "metric_name": metric_name,
-                "timestamp": timestamp
-            }
+        self.upsert_alert_state(
+            metric_name=metric_name,
+            alert_config_id=alert_config_id,
+            last_recovery_sent=timestamp,
         )
-
         return 1
 
-    def get_last_recovery_timestamp(
+    # ─── Alert States (_dtk_alert_states) ───────────────────────────────────
+
+    def get_alert_state(
         self,
-        metric_name: str
-    ) -> Optional[datetime]:
+        metric_name: str,
+        alert_config_id: str,
+    ) -> Dict:
         """
-        Get timestamp of last sent recovery notification for a metric.
+        Get alert state for a specific alerting config.
 
         Args:
             metric_name: Metric identifier
+            alert_config_id: MD5 hash of alerting config params
 
         Returns:
-            Timestamp of last sent recovery, or None if never sent
+            Dict with keys:
+                - last_alert_sent: datetime or None
+                - last_recovery_sent: datetime or None
+                - alert_count: int
         """
         full_table_name = self._manager.get_full_table_name(
-            TABLE_TASKS, use_internal=True
+            TABLE_ALERT_STATES, use_internal=True
         )
 
         query = f"""
-        SELECT last_recovery_sent
+        SELECT last_alert_sent, last_recovery_sent, alert_count
         FROM {full_table_name}
+        FINAL
         WHERE metric_name = %(metric_name)s
-          AND detector_id = 'pipeline'
-          AND process_type = 'pipeline'
+          AND alert_config_id = %(alert_config_id)s
         LIMIT 1
         """
 
         results = self._manager.execute_query(
             query,
-            params={"metric_name": metric_name}
+            params={
+                "metric_name": metric_name,
+                "alert_config_id": alert_config_id,
+            }
         )
 
-        if not results or not results[0].get("last_recovery_sent"):
-            return None
-
-        last_sent = results[0]["last_recovery_sent"]
-
-        if hasattr(last_sent, 'tzinfo') and last_sent.tzinfo is not None:
-            last_sent = last_sent.replace(tzinfo=None)
+        if not results:
+            return {
+                "last_alert_sent": None,
+                "last_recovery_sent": None,
+                "alert_count": 0,
+            }
 
-        return last_sent
+        row = results[0]
+        return {
+            "last_alert_sent": to_naive_utc(row.get("last_alert_sent")),
+            "last_recovery_sent": to_naive_utc(row.get("last_recovery_sent")),
+            "alert_count": row.get("alert_count", 0) or 0,
+        }
 
-    def update_recovery_timestamp(
+    def upsert_alert_state(
         self,
         metric_name: str,
-        timestamp: datetime,
-    ) -> int:
+        alert_config_id: str,
+        last_alert_sent: Optional[datetime] = None,
+        last_recovery_sent: Optional[datetime] = None,
+        increment_count: bool = False,
+    ) -> None:
         """
-        Update last_recovery_sent timestamp after sending recovery notification.
+        Upsert alert state for a specific alerting config.
+
+        Uses SELECT -> DELETE -> INSERT pattern to handle new rows and updates.
 
         Args:
             metric_name: Metric identifier
-            timestamp: Timestamp when recovery was sent
-
-        Returns:
-            Number of rows updated (typically 1)
+            alert_config_id: MD5 hash of alerting config params
+            last_alert_sent: New last_alert_sent timestamp (None = keep existing)
+            last_recovery_sent: New last_recovery_sent timestamp (None = keep existing)
+            increment_count: Whether to increment alert_count by 1
         """
         full_table_name = self._manager.get_full_table_name(
-            TABLE_TASKS, use_internal=True
+            TABLE_ALERT_STATES, use_internal=True
         )
 
-        if hasattr(timestamp, 'tzinfo') and timestamp.tzinfo is not None:
-            timestamp = timestamp.replace(tzinfo=None)
+        # Read existing state to preserve fields not being updated
+        existing = self.get_alert_state(metric_name, alert_config_id)
+
+        now = now_utc_naive()
+
+        new_last_alert = to_naive_utc(last_alert_sent) if last_alert_sent is not None else existing["last_alert_sent"]
+        new_last_recovery = to_naive_utc(last_recovery_sent) if last_recovery_sent is not None else existing["last_recovery_sent"]
+        new_alert_count = existing["alert_count"] + 1 if increment_count else existing["alert_count"]
 
-        update_query = f"""
+        # Delete existing row
+        delete_query = f"""
         ALTER TABLE {full_table_name}
-        UPDATE
-            last_recovery_sent = %(timestamp)s,
-            updated_at = %(timestamp)s
-        WHERE metric_name = %(metric_name)s
-          AND detector_id = 'pipeline'
-          AND process_type = 'pipeline'
+        DELETE WHERE metric_name = %(metric_name)s
+          AND alert_config_id = %(alert_config_id)s
         SETTINGS mutations_sync = 1
         """
-
         self._manager.execute_query(
-            update_query,
+            delete_query,
             params={
                 "metric_name": metric_name,
-                "timestamp": timestamp
+                "alert_config_id": alert_config_id,
             }
         )
 
-        return 1
+        # Insert new row
+        insert_data = {
+            "metric_name": np.array([metric_name]),
+            "alert_config_id": np.array([alert_config_id]),
+            "last_alert_sent": np.array([new_last_alert], dtype="datetime64[ms]") if new_last_alert else np.array([None]),
+            "last_recovery_sent": np.array([new_last_recovery], dtype="datetime64[ms]") if new_last_recovery else np.array([None]),
+            "alert_count": np.array([new_alert_count], dtype=np.uint32),
+            "updated_at": np.array([now], dtype="datetime64[ms]"),
+        }
+
+        self._manager.insert_batch(
+            full_table_name,
+            insert_data,
+            conflict_strategy="ignore",
+        )

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit/database/tables.py

@@ -140,6 +140,48 @@ def get_tasks_table_model() -> TableModel:
     )
 
 
+def get_alert_states_table_model() -> TableModel:
+    """
+    Get TableModel for _dtk_alert_states table.
+
+    Stores alert state independently per alerting config (not per metric).
+    Each alerting config block in metric YAML gets its own row identified
+    by a hash of the config parameters.
+
+    Schema:
+        - metric_name: Metric identifier
+        - alert_config_id: MD5 hash of alerting config params (channels, conditions, etc.)
+        - last_alert_sent: Timestamp of last sent alert (nullable)
+        - last_recovery_sent: Timestamp of last sent recovery notification (nullable)
+        - alert_count: Total alerts sent for this config
+        - updated_at: Last update timestamp
+
+    Primary Key: (metric_name, alert_config_id)
+    Engine: ReplacingMergeTree(updated_at)
+    """
+    return TableModel(
+        columns=[
+            ColumnDefinition("metric_name", "String"),
+            ColumnDefinition("alert_config_id", "String"),
+            ColumnDefinition(
+                "last_alert_sent",
+                "Nullable(DateTime64(3, 'UTC'))",
+                nullable=True,
+            ),
+            ColumnDefinition(
+                "last_recovery_sent",
+                "Nullable(DateTime64(3, 'UTC'))",
+                nullable=True,
+            ),
+            ColumnDefinition("alert_count", "UInt32", default="0"),
+            ColumnDefinition("updated_at", "DateTime64(3, 'UTC')"),
+        ],
+        primary_key=["metric_name", "alert_config_id"],
+        engine="ReplacingMergeTree(updated_at)",
+        order_by=["metric_name", "alert_config_id"],
+    )
+
+
 def get_metrics_table_model() -> TableModel:
     """
     Get TableModel for _dtk_metrics table.
@@ -203,6 +245,7 @@ TABLE_DATAPOINTS = "_dtk_datapoints"
 TABLE_DETECTIONS = "_dtk_detections"
 TABLE_TASKS = "_dtk_tasks"
 TABLE_METRICS = "_dtk_metrics"
+TABLE_ALERT_STATES = "_dtk_alert_states"
 
 # Map of table names to model factories
 INTERNAL_TABLES = {
@@ -210,4 +253,5 @@ INTERNAL_TABLES = {
     TABLE_DETECTIONS: get_detections_table_model,
     TABLE_TASKS: get_tasks_table_model,
     TABLE_METRICS: get_metrics_table_model,
+    TABLE_ALERT_STATES: get_alert_states_table_model,
 }

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit/loaders/metric_loader.py

@@ -11,6 +11,7 @@ Loads time-series data from databases with:
 
 from datetime import datetime, timedelta, timezone
 from typing import Dict, List, Optional
+from detectkit.utils.datetime_utils import now_utc_naive, to_naive_utc
 
 import numpy as np
 
@@ -118,12 +119,9 @@ class MetricLoader:
             >>> print(data["timestamp"])
             >>> print(data["value"])
         """
-        # Normalize datetimes to naive (remove timezone info)
-        # ClickHouse returns naive datetimes, so we need to compare with naive
-        if from_date.tzinfo is not None:
-            from_date = from_date.replace(tzinfo=None)
-        if to_date.tzinfo is not None:
-            to_date = to_date.replace(tzinfo=None)
+        # Normalize datetimes to naive UTC (ClickHouse returns naive UTC for DateTime64)
+        from_date = to_naive_utc(from_date)
+        to_date = to_naive_utc(to_date)
 
         # Get interval
         interval = self.config.get_interval()
@@ -344,7 +342,7 @@ class MetricLoader:
                     # Parse loading_start_time string (format: "YYYY-MM-DD HH:MM:SS" in UTC)
                     from_date = datetime.strptime(
                         self.config.loading_start_time, "%Y-%m-%d %H:%M:%S"
-                    ).replace(tzinfo=timezone.utc)
+                    )  # naive UTC from config string
                 else:
                     # No data and no loading_start_time - need to specify from_date
                     raise ValueError(
@@ -353,7 +351,7 @@ class MetricLoader:
                     )
 
         if to_date is None:
-            to_date = datetime.now(timezone.utc)
+            to_date = now_utc_naive()
 
         # Load and save
         data = self.load(from_date, to_date, fill_gaps=True)

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

@@ -8,8 +8,10 @@ Orchestrates the complete workflow:
 """
 
 from datetime import datetime, timezone, timedelta
+from detectkit.utils.datetime_utils import now_utc, now_utc_naive, to_naive_utc, to_aware_utc
 from enum import Enum
 from typing import Dict, List, Optional
+import hashlib
 import json
 
 import click
@@ -30,6 +32,33 @@ from detectkit.detectors.factory import DetectorFactory
 from detectkit.loaders.metric_loader import MetricLoader
 
 
+def _make_alert_config_id(alerting_config) -> str:
+    """
+    Generate a stable unique ID for an alerting config block.
+
+    Hashes ALL parameters that define the config's identity so that:
+    - Two configs with same channels but different conditions get different IDs
+    - The same config always gets the same ID across runs
+    - Changing any parameter produces a new ID (fresh state)
+
+    Args:
+        alerting_config: AlertConfig instance
+
+    Returns:
+        16-character hex string (MD5 truncated)
+    """
+    config_dict = {
+        "channels": sorted(alerting_config.channels),
+        "min_detectors": alerting_config.min_detectors,
+        "direction": alerting_config.direction,
+        "consecutive_anomalies": alerting_config.consecutive_anomalies,
+        "alert_cooldown": str(alerting_config.alert_cooldown) if alerting_config.alert_cooldown else None,
+        "cooldown_reset_on_recovery": alerting_config.cooldown_reset_on_recovery,
+    }
+    config_str = json.dumps(config_dict, sort_keys=True)
+    return hashlib.md5(config_str.encode()).hexdigest()[:16]
+
+
 class PipelineStep(str, Enum):
     """Pipeline execution steps."""
 
@@ -268,7 +297,7 @@ class TaskManager:
                 if config.loading_start_time:
                     actual_from = datetime.strptime(
                         config.loading_start_time, "%Y-%m-%d %H:%M:%S"
-                    ).replace(tzinfo=timezone.utc)
+                    )  # naive UTC from config string
                     click.echo(f"  │ Starting fresh from: {config.loading_start_time}")
                 else:
                     raise ValueError(
@@ -277,13 +306,12 @@ class TaskManager:
                     )
 
         if actual_to is None:
-            actual_to = datetime.now(timezone.utc)
+            actual_to = now_utc_naive()
+        else:
+            actual_to = to_naive_utc(actual_to)
 
         # Normalize to naive UTC (ClickHouse returns aware UTC for DateTime64(3, 'UTC'))
-        if actual_from.tzinfo is not None:
-            actual_from = actual_from.replace(tzinfo=None)
-        if actual_to.tzinfo is not None:
-            actual_to = actual_to.replace(tzinfo=None)
+        actual_from = to_naive_utc(actual_from)
 
         # Guard: next interval hasn't arrived yet
         if actual_from >= actual_to:
@@ -379,15 +407,8 @@ class TaskManager:
         click.echo(f"  │ Running {len(config.detectors)} detector(s)...")
 
         # Determine to_date if not specified
-        actual_to = to_date or datetime.now(timezone.utc)
-        # Normalize to naive datetime (remove timezone info)
-        if actual_to and actual_to.tzinfo is not None:
-            actual_to = actual_to.replace(tzinfo=None)
-
-        # Normalize from_date to naive
-        normalized_from_date = from_date
-        if normalized_from_date and normalized_from_date.tzinfo is not None:
-            normalized_from_date = normalized_from_date.replace(tzinfo=None)
+        actual_to = to_naive_utc(to_date) if to_date else now_utc_naive()
+        normalized_from_date = to_naive_utc(from_date)
 
         # Run each detector
         for idx, detector_config in enumerate(config.detectors, 1):
@@ -425,9 +446,7 @@ class TaskManager:
                 metric_name=config.name,
                 detector_id=detector_id
             )
-            # Normalize last_detection_ts to naive if needed
-            if last_detection_ts and last_detection_ts.tzinfo is not None:
-                last_detection_ts = last_detection_ts.replace(tzinfo=None)
+            last_detection_ts = to_naive_utc(last_detection_ts)
 
             # Determine actual from_date
             actual_from = normalized_from_date
@@ -442,17 +461,15 @@ class TaskManager:
             # Apply start_time filter if configured
             start_time_str = detector_config.get_start_time()
             if start_time_str:
-                start_time = datetime.fromisoformat(start_time_str.replace('Z', '+00:00'))
-                # Always normalize to naive datetime
-                start_time = start_time.replace(tzinfo=None)
+                start_time = to_naive_utc(
+                    datetime.fromisoformat(start_time_str.replace('Z', '+00:00'))
+                )
                 if actual_from:
                     actual_from = max(actual_from, start_time)
                 else:
                     actual_from = start_time
 
-            # Ensure actual_from is naive (for comparison with actual_to)
-            if actual_from and actual_from.tzinfo is not None:
-                actual_from = actual_from.replace(tzinfo=None)
+            actual_from = to_naive_utc(actual_from)
 
             # Skip if nothing to detect
             if not actual_from or actual_from >= actual_to:
@@ -589,9 +606,12 @@ class TaskManager:
 
             click.echo(f"  │ Checking alert conditions...")
 
+            alert_config_id = _make_alert_config_id(alerting_config)
+
             orchestrator = AlertOrchestrator(
                 metric_name=config.name,
                 interval=interval,
+                alert_config_id=alert_config_id,
                 conditions=AlertConditions(
                     min_detectors=alerting_config.min_detectors,
                     direction=alerting_config.direction,

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit/utils/__init__.py

@@ -7,6 +7,12 @@ from detectkit.utils.stats import (
     weighted_percentile,
     weighted_std,
 )
+from detectkit.utils.datetime_utils import (
+    now_utc,
+    now_utc_naive,
+    to_naive_utc,
+    to_aware_utc,
+)
 
 __all__ = [
     "weighted_percentile",
@@ -14,4 +20,8 @@ __all__ = [
     "weighted_mad",
     "weighted_mean",
     "weighted_std",
+    "now_utc",
+    "now_utc_naive",
+    "to_naive_utc",
+    "to_aware_utc",
 ]

detectkit-0.3.13/detectkit/utils/datetime_utils.py

@@ -0,0 +1,54 @@
+"""UTC datetime utilities.
+
+Contract: all internal timestamps are naive UTC (tzinfo=None).
+- ClickHouse DateTime64(3, 'UTC') stores and returns naive UTC
+- numpy datetime64 has no timezone representation
+- Comparisons between timestamps must use the same convention
+
+Functions:
+    now_utc()       -> aware UTC datetime (for calculations requiring timezone)
+    now_utc_naive() -> naive UTC datetime (for numpy / ClickHouse inserts)
+    to_naive_utc()  -> normalize any datetime to naive UTC
+    to_aware_utc()  -> normalize any datetime to aware UTC
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+
+def now_utc() -> datetime:
+    """Return current time as timezone-aware UTC datetime."""
+    return datetime.now(timezone.utc)
+
+
+def now_utc_naive() -> datetime:
+    """Return current time as naive UTC datetime (for numpy / ClickHouse)."""
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+def to_naive_utc(dt: Optional[datetime]) -> Optional[datetime]:
+    """Strip tzinfo from a UTC datetime, returning naive UTC.
+
+    Args:
+        dt: datetime object (aware or naive) or None
+
+    Returns:
+        Naive UTC datetime, or None if input is None
+    """
+    if dt is None:
+        return None
+    return dt.replace(tzinfo=None) if dt.tzinfo is not None else dt
+
+
+def to_aware_utc(dt: Optional[datetime]) -> Optional[datetime]:
+    """Attach UTC timezone to a naive datetime.
+
+    Args:
+        dt: datetime object (aware or naive) or None
+
+    Returns:
+        Timezone-aware UTC datetime, or None if input is None
+    """
+    if dt is None:
+        return None
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)

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

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

{detectkit-0.3.12 → detectkit-0.3.13}/detectkit.egg-info/SOURCES.txt

@@ -54,4 +54,5 @@ detectkit/loaders/query_template.py
 detectkit/orchestration/__init__.py
 detectkit/orchestration/task_manager.py
 detectkit/utils/__init__.py
+detectkit/utils/datetime_utils.py
 detectkit/utils/stats.py

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

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