detectkit 0.6.0__tar.gz → 0.8.0__tar.gz

{detectkit-0.6.0/detectkit.egg-info → detectkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.6.0
+Version: 0.8.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -77,13 +77,14 @@ Dynamic: license-file
 
 - **Pure numpy arrays** — no pandas dependency in core logic
 - **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds
+- **Trend & seasonality handling** — seasonality grouping, recency weighting (`half_life`), robust linear detrending for slowly drifting metrics
 - **Multi-channel alerting** — Mattermost, Slack, Telegram, Email, Webhook
 - **@mentions** — tag users/groups in alerts, each channel formats natively
 - **Alert lifecycle** — consecutive anomalies, cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing
-- **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, tag-based selectors
+- **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 
 ## Installation
 
@@ -115,6 +116,9 @@ dtk run --select cpu_usage --from 2024-01-01
 
 # Clear a stuck lock left by a crashed run (e.g. DB restarted mid-run)
 dtk unlock --select cpu_usage
+
+# Prune data orphaned by config edits (dry-run; add --execute to apply)
+dtk clean --select cpu_usage
 ```
 
 ### Metric Configuration
@@ -129,14 +133,16 @@ query: |
     toStartOfInterval(timestamp, INTERVAL 5 MINUTE) AS timestamp,
     countIf(status_code >= 500) / count() * 100 AS value
   FROM http_requests
-  WHERE timestamp >= %(from_date)s AND timestamp < %(to_date)s
+  WHERE timestamp >= '{{ dtk_start_time }}' AND timestamp < '{{ dtk_end_time }}'
   GROUP BY timestamp ORDER BY timestamp
 
 detectors:
   - type: mad
     params:
-      threshold: 3.0
-      window_size: 2016    # 7 days
+      threshold: 3.0                 # in sigma-equivalents
+      window_size: 2016              # 7 days of 5-min points
+      window_weights: exponential    # optional: favor recent data
+      half_life: "1d"                # weight halves every day of age
 
 alerting:
   enabled: true

{detectkit-0.6.0 → detectkit-0.8.0}/README.md

@@ -11,13 +11,14 @@
 
 - **Pure numpy arrays** — no pandas dependency in core logic
 - **Statistical detectors** — Z-Score, MAD, IQR, Manual Bounds
+- **Trend & seasonality handling** — seasonality grouping, recency weighting (`half_life`), robust linear detrending for slowly drifting metrics
 - **Multi-channel alerting** — Mattermost, Slack, Telegram, Email, Webhook
 - **@mentions** — tag users/groups in alerts, each channel formats natively
 - **Alert lifecycle** — consecutive anomalies, cooldown, recovery notifications, no-data alerts
 - **Project-level error alerts** — catch DB outages and pipeline crashes once per run
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing
-- **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, tag-based selectors
+- **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
 
 ## Installation
 
@@ -49,6 +50,9 @@ dtk run --select cpu_usage --from 2024-01-01
 
 # Clear a stuck lock left by a crashed run (e.g. DB restarted mid-run)
 dtk unlock --select cpu_usage
+
+# Prune data orphaned by config edits (dry-run; add --execute to apply)
+dtk clean --select cpu_usage
 ```
 
 ### Metric Configuration
@@ -63,14 +67,16 @@ query: |
     toStartOfInterval(timestamp, INTERVAL 5 MINUTE) AS timestamp,
     countIf(status_code >= 500) / count() * 100 AS value
   FROM http_requests
-  WHERE timestamp >= %(from_date)s AND timestamp < %(to_date)s
+  WHERE timestamp >= '{{ dtk_start_time }}' AND timestamp < '{{ dtk_end_time }}'
   GROUP BY timestamp ORDER BY timestamp
 
 detectors:
   - type: mad
     params:
-      threshold: 3.0
-      window_size: 2016    # 7 days
+      threshold: 3.0                 # in sigma-equivalents
+      window_size: 2016              # 7 days of 5-min points
+      window_weights: exponential    # optional: favor recent data
+      half_life: "1d"                # weight halves every day of age
 
 alerting:
   enabled: true

{detectkit-0.6.0 → detectkit-0.8.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.5.3"
+__version__ = "0.8.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/channels/email.py

@@ -95,12 +95,17 @@ class EmailChannel(BaseAlertChannel):
         self.subject_template = subject_template
         self.template = template
 
-    def send(self, alert_data: AlertData) -> None:
+    def send(self, alert_data: AlertData, template: str | None = None) -> bool:
         """
         Send alert via email.
 
         Args:
             alert_data: Alert information to send
+            template: Per-call template override (falls back to the
+                channel-level template, then the built-in default)
+
+        Returns:
+            True when the email was handed to the SMTP server
 
         Raises:
             smtplib.SMTPException: If email sending fails
@@ -108,7 +113,7 @@ class EmailChannel(BaseAlertChannel):
         Example:
             >>> channel.send(alert_data)
         """
-        message_body = self.format_message(alert_data, self.template)
+        message_body = self.format_message(alert_data, template or self.template)
 
         # Create email message
         msg = MIMEMultipart("alternative")
@@ -138,6 +143,8 @@ class EmailChannel(BaseAlertChannel):
         except smtplib.SMTPException as e:
             raise smtplib.SMTPException(f"Failed to send email alert: {e}") from e
 
+        return True
+
     def format_mentions(self, mentions: list[str]) -> str:
         """
         Format mentions for email.

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/channels/telegram.py

@@ -69,12 +69,17 @@ class TelegramChannel(BaseAlertChannel):
         self.disable_notification = disable_notification
         self.template = template
 
-    def send(self, alert_data: AlertData) -> None:
+    def send(self, alert_data: AlertData, template: str | None = None) -> bool:
         """
         Send alert to Telegram.
 
         Args:
             alert_data: Alert information to send
+            template: Per-call template override (falls back to the
+                channel-level template, then the built-in default)
+
+        Returns:
+            True when the message was accepted by the Telegram API
 
         Raises:
             requests.RequestException: If request fails
@@ -83,7 +88,7 @@ class TelegramChannel(BaseAlertChannel):
         Example:
             >>> channel.send(alert_data)
         """
-        message = self.format_message(alert_data, self.template)
+        message = self.format_message(alert_data, template or self.template)
 
         # Telegram Bot API URL
         url = f"https://api.telegram.org/bot{self.bot_token}/sendMessage"
@@ -103,6 +108,8 @@ class TelegramChannel(BaseAlertChannel):
         except requests.RequestException as e:
             raise requests.RequestException(f"Failed to send Telegram alert: {e}") from e
 
+        return True
+
     def format_mentions(self, mentions: list[str]) -> str:
         """
         Format mentions for Telegram.

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/orchestrator/__init__.py

@@ -5,6 +5,7 @@ from detectkit.alerting.orchestrator._types import (
     DetectionRecord,
     _direction_from_metadata,
     _parse_detection_metadata,
+    hydrate_detection_records,
 )
 from detectkit.alerting.orchestrator.orchestrator import AlertOrchestrator
 
@@ -12,8 +13,9 @@ __all__ = [
     "AlertOrchestrator",
     "AlertConditions",
     "DetectionRecord",
-    # Re-exported for callers (notably TaskManager) that build
-    # DetectionRecord rows manually before handing them to the orchestrator.
+    # Shared hydration of DetectionRecord rows from get_recent_detections
+    # output (used by TaskManager and the recovery mixin).
+    "hydrate_detection_records",
     "_direction_from_metadata",
     "_parse_detection_metadata",
 ]

detectkit-0.8.0/detectkit/alerting/orchestrator/_decision.py

@@ -0,0 +1,287 @@
+"""Decision logic: ``should_alert`` and the consecutive-anomaly helpers.
+
+The multi-detector alert contract (documented in docs/guides/alerting.md):
+
+    For every timestamp, an alert *quorum* is the set of anomalous
+    detections that match the configured direction policy:
+
+    - ``"up"`` / ``"down"``: only anomalies in that direction count.
+      Detectors firing the other way are ignored (they neither help nor
+      block the quorum).
+    - ``"any"``: every anomaly counts, regardless of direction (an
+      up-anomaly and a down-anomaly together can satisfy
+      ``min_detectors=2``).
+    - ``"same"``: at the latest point at least ``min_detectors`` detectors
+      must agree on ONE direction (up- and down-anomalies are counted
+      separately; disagreement does not form a quorum). The winning
+      direction is then locked for the consecutive walk.
+
+    An alert fires when the latest ``consecutive_anomalies`` timestamps
+    each satisfy the quorum AND are exactly one metric interval apart —
+    a gap in the detection grid breaks the chain.
+
+    The alert payload (value/CI shown in the message) is built from the
+    highest-severity record of the latest quorum; ties are broken by
+    detector name, then detector id, so the outcome never depends on SQL
+    row ordering.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+
+import numpy as np
+
+from detectkit.alerting.channels.base import AlertData
+from detectkit.alerting.orchestrator._base import _OrchestratorBase
+from detectkit.alerting.orchestrator._types import DetectionRecord
+from detectkit.utils.datetime_utils import now_utc, to_aware_utc
+
+
+class _DecisionMixin(_OrchestratorBase):
+    def should_alert(
+        self,
+        recent_detections: list[DetectionRecord],
+    ) -> tuple[bool, AlertData | None]:
+        """Decide whether to fire an alert from recent detections.
+
+        Steps (cheap → expensive):
+            1. Bail out on empty input.
+            2. Honour the alert cooldown so we don't spam channels.
+            3. Walk timestamps newest→oldest counting points where the
+               direction-aware quorum holds (see module docstring).
+            4. Require ``consecutive_anomalies`` such points on a
+               contiguous interval grid.
+        """
+        if not recent_detections:
+            return False, None
+
+        # Cooldown is checked first so a noisy run doesn't waste effort.
+        if self._is_in_cooldown():
+            return False, None
+
+        detections_by_time = self._group_by_timestamp(recent_detections)
+        timestamps_sorted = sorted(detections_by_time.keys(), reverse=True)
+
+        consecutive, latest_quorum, direction = self._count_consecutive_anomalies(
+            detections_by_time, timestamps_sorted
+        )
+        if not latest_quorum or consecutive < self.conditions.consecutive_anomalies:
+            return False, None
+
+        return True, self._build_alert_data(latest_quorum, consecutive, direction)
+
+    def _quorum_at(
+        self,
+        anomalies: list[DetectionRecord],
+        locked_direction: str | None,
+    ) -> tuple[list[DetectionRecord] | None, str | None]:
+        """Anomalies satisfying the direction policy at one timestamp.
+
+        Returns ``(quorum, direction)`` or ``(None, None)`` when the quorum
+        is not met. ``locked_direction`` carries the winning direction of
+        the latest point through the consecutive walk for ``"same"``.
+        """
+        policy = self.conditions.direction
+        required = self.conditions.min_detectors
+
+        if policy in ("up", "down"):
+            qualifying = [d for d in anomalies if d.direction == policy]
+            if len(qualifying) >= required:
+                return qualifying, policy
+            return None, None
+
+        if policy == "same":
+            if locked_direction is not None:
+                qualifying = [d for d in anomalies if d.direction == locked_direction]
+                if len(qualifying) >= required:
+                    return qualifying, locked_direction
+                return None, None
+
+            ups = [d for d in anomalies if d.direction == "up"]
+            downs = [d for d in anomalies if d.direction == "down"]
+            candidates = [c for c in (ups, downs) if len(c) >= required]
+            if not candidates:
+                return None, None
+            if len(candidates) == 2:
+                if len(ups) != len(downs):
+                    winner = ups if len(ups) > len(downs) else downs
+                else:
+                    # Same detector count in both directions: prefer the
+                    # more severe side (deterministic tie-break).
+                    winner = max(
+                        candidates,
+                        key=lambda c: max((d.severity, d.detector_name) for d in c),
+                    )
+            else:
+                winner = candidates[0]
+            return winner, winner[0].direction
+
+        # "any" (unknown policies are rejected at config validation; if one
+        # sneaks in through the direct API, fail open like "any")
+        if len(anomalies) >= required:
+            return anomalies, None
+        return None, None
+
+    def _count_consecutive_anomalies(
+        self,
+        detections_by_time: dict[np.datetime64, list[DetectionRecord]],
+        timestamps_sorted: list[np.datetime64],
+    ) -> tuple[int, list[DetectionRecord] | None, str | None]:
+        """Walk timestamps newest→oldest counting quorum-satisfying points.
+
+        The chain requires grid adjacency: each older timestamp must be
+        exactly one metric interval before the previous one, so detection
+        gaps (days without runs, detector start_time boundaries) are not
+        miscounted as "consecutive".
+
+        Returns ``(count, latest_quorum, direction)`` where direction is
+        the locked/policy direction (None for "any").
+        """
+        expected_step = np.timedelta64(self.interval.seconds, "s")
+        consecutive = 0
+        locked_direction: str | None = None
+        latest_quorum: list[DetectionRecord] | None = None
+        latest_direction: str | None = None
+        prev_ts: np.datetime64 | None = None
+
+        for ts in timestamps_sorted:
+            if prev_ts is not None and (prev_ts - ts) != expected_step:
+                break
+
+            anomalies = [d for d in detections_by_time[ts] if d.is_anomaly]
+            quorum, direction = self._quorum_at(anomalies, locked_direction)
+            if quorum is None:
+                break
+
+            if self.conditions.direction == "same":
+                locked_direction = direction
+            if latest_quorum is None:
+                latest_quorum = quorum
+                latest_direction = direction
+
+            consecutive += 1
+            prev_ts = ts
+
+        return consecutive, latest_quorum, latest_direction
+
+    @staticmethod
+    def _primary_record(anomalies: list[DetectionRecord]) -> DetectionRecord:
+        """Highest-severity record; ties broken by name/id for determinism."""
+
+        def sort_key(d: DetectionRecord):
+            severity = d.severity
+            if math.isnan(severity):
+                severity = 0.0
+            elif math.isinf(severity):
+                severity = 1e308 if severity > 0 else -1e308
+            return (-severity, d.detector_name, d.detector_id)
+
+        return min(anomalies, key=sort_key)
+
+    def _build_alert_data(
+        self,
+        anomalies: list[DetectionRecord],
+        consecutive_count: int,
+        direction: str | None,
+    ) -> AlertData:
+        primary = self._primary_record(anomalies)
+
+        if len(anomalies) > 1:
+            max_severity = max(d.severity for d in anomalies)
+            detector_names = [d.detector_name for d in anomalies]
+            detector_name = f"{len(anomalies)} detectors"
+            detector_params = "; ".join(
+                f"{d.detector_name}: {d.detector_params}" for d in anomalies
+            )
+            combined_metadata = {
+                "detectors": detector_names,
+                "count": len(anomalies),
+            }
+            for i, d in enumerate(anomalies):
+                combined_metadata[f"detector_{i}_metadata"] = d.detection_metadata
+        else:
+            max_severity = primary.severity
+            detector_name = primary.detector_name
+            detector_params = primary.detector_params
+            combined_metadata = primary.detection_metadata
+
+        return AlertData(
+            metric_name=self.metric_name,
+            timestamp=primary.timestamp,
+            timezone=self.timezone_display,
+            value=primary.value,
+            confidence_lower=primary.confidence_lower,
+            confidence_upper=primary.confidence_upper,
+            detector_name=detector_name,
+            detector_params=detector_params,
+            direction=direction or primary.direction,
+            severity=max_severity,
+            detection_metadata=combined_metadata,
+            consecutive_count=consecutive_count,
+            description=self.description,
+            mentions=self.mentions,
+        )
+
+    def should_alert_no_data(
+        self,
+        last_point: datetime,
+    ) -> tuple[bool, AlertData | None]:
+        """Decide whether to fire a no-data alert for *last_point*.
+
+        Conditions (all must hold):
+            1. ``alert_config.no_data_alert`` is true.
+            2. Not currently in alert cooldown for this alert config.
+            3. The latest expected datapoint is missing — there is no row
+               in ``_dtk_datapoints`` for *last_point* OR the row's value
+               is NULL/NaN. ``get_value_at`` returns ``None`` for both.
+
+        ``min_detectors`` and ``consecutive_anomalies`` deliberately do
+        not apply here: missing data is a single binary metric-level
+        signal, not a per-detector vote.
+        """
+        if not self.alert_config or not getattr(self.alert_config, "no_data_alert", False):
+            return False, None
+        if not self.internal:
+            return False, None
+
+        if self._is_in_cooldown():
+            return False, None
+
+        value = self.internal.get_value_at(self.metric_name, last_point)
+        if value is not None and not (isinstance(value, float) and math.isnan(value)):
+            return False, None
+
+        return True, self._build_no_data_alert_data(last_point)
+
+    def _build_no_data_alert_data(self, last_point: datetime) -> AlertData:
+        """Construct the AlertData payload for a no-data alert."""
+        return AlertData(
+            metric_name=self.metric_name,
+            timestamp=np.datetime64(last_point, "ms"),
+            timezone=self.timezone_display,
+            value=None,
+            confidence_lower=None,
+            confidence_upper=None,
+            detector_name="no_data",
+            detector_params="",
+            direction="none",
+            severity=0.0,
+            detection_metadata={"reason": "no_data"},
+            consecutive_count=0,
+            is_no_data=True,
+            description=self.description,
+            mentions=self.mentions,
+        )
+
+    def get_last_complete_point(self, now: datetime | None = None) -> datetime:
+        """Floor ``now`` to the previous fully completed interval boundary."""
+        if now is None:
+            now = now_utc()
+        now = to_aware_utc(now)
+
+        interval_seconds = self.interval.seconds
+        floored = (int(now.timestamp()) // interval_seconds) * interval_seconds
+        last_complete = floored - interval_seconds
+        return datetime.fromtimestamp(last_complete, tz=timezone.utc)

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/orchestrator/_dispatch.py

@@ -58,6 +58,13 @@ class _DispatchMixin(_OrchestratorBase):
         results: dict[str, bool] = {}
         for channel in channels:
             channel_name = channel.__class__.__name__
+            # Two channels of the same type must not collapse into one
+            # result entry (that would undercount sends).
+            if channel_name in results:
+                suffix = 2
+                while f"{channel_name}#{suffix}" in results:
+                    suffix += 1
+                channel_name = f"{channel_name}#{suffix}"
             try:
                 results[channel_name] = bool(channel.send(alert_data, template))
             except Exception as exc:

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -4,14 +4,11 @@ from __future__ import annotations
 
 from datetime import datetime
 
-import numpy as np
-
 from detectkit.alerting.channels.base import AlertData
 from detectkit.alerting.orchestrator._base import _OrchestratorBase
 from detectkit.alerting.orchestrator._types import (
     DetectionRecord,
-    _direction_from_metadata,
-    _parse_detection_metadata,
+    hydrate_detection_records,
 )
 
 
@@ -71,27 +68,7 @@ class _RecoveryMixin(_OrchestratorBase):
             # No fresh detections at all → assume recovery.
             return True
 
-        records: list[DetectionRecord] = []
-        for det in recent_detections:
-            metadata_list = det.get("detection_metadata_list") or [None] * len(det["detector_ids"])
-            for i in range(len(det["detector_ids"])):
-                is_anomaly = det["is_anomaly_flags"][i]
-                metadata = _parse_detection_metadata(metadata_list[i])
-                records.append(
-                    DetectionRecord(
-                        timestamp=np.datetime64(det["timestamp"]),
-                        detector_name=det["detector_names"][i],
-                        detector_id=det["detector_ids"][i],
-                        detector_params=det["detector_params_list"][i],
-                        value=det["value"],
-                        is_anomaly=is_anomaly,
-                        confidence_lower=det["confidence_lowers"][i],
-                        confidence_upper=det["confidence_uppers"][i],
-                        direction=_direction_from_metadata(metadata, is_anomaly),
-                        severity=0.0,  # not used for the recovery check
-                        detection_metadata=metadata,
-                    )
-                )
+        records = hydrate_detection_records(recent_detections)
 
         detections_by_time = self._group_by_timestamp(records)
         timestamps_sorted = sorted(detections_by_time.keys(), reverse=True)
@@ -114,7 +91,14 @@ class _RecoveryMixin(_OrchestratorBase):
         return len(blocking) == 0
 
     def _get_alert_trigger_direction(self, last_alert_timestamp: datetime) -> str | None:
-        """Return the direction of the anomaly that triggered the last alert."""
+        """Return the direction of the anomaly that triggered the last alert.
+
+        Mirrors the quorum logic that fired the alert (``_quorum_at`` with
+        no locked direction) so recovery checks the SAME direction the
+        alert was raised for — not whichever anomalous detector happens to
+        sort first. Falls back to a simple majority when the quorum can no
+        longer be reconstructed.
+        """
         if not self.internal:
             return None
 
@@ -126,14 +110,27 @@ class _RecoveryMixin(_OrchestratorBase):
         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
+        records = hydrate_detection_records(trigger_detections)
+        by_time = self._group_by_timestamp(records)
+        if not by_time:
+            return None
+        latest_ts = max(by_time.keys())
+        anomalies = [d for d in by_time[latest_ts] if d.is_anomaly]
+        if not anomalies:
+            return None
+
+        # _quorum_at lives in _DecisionMixin; both mixins are combined in
+        # AlertOrchestrator, so the call resolves at runtime.
+        _, direction = self._quorum_at(anomalies, None)
+        if direction in ("up", "down"):
+            return direction
+
+        ups = sum(1 for d in anomalies if d.direction == "up")
+        downs = sum(1 for d in anomalies if d.direction == "down")
+        if ups > downs:
+            return "up"
+        if downs > ups:
+            return "down"
         return None
 
     def _build_recovery_data(

{detectkit-0.6.0 → detectkit-0.8.0}/detectkit/alerting/orchestrator/_types.py

@@ -3,10 +3,12 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import datetime
 from typing import Any
 
 import numpy as np
 
+from detectkit.utils.datetime_utils import to_naive_utc
 from detectkit.utils.json_utils import json_loads
 
 
@@ -58,11 +60,15 @@ def _direction_from_metadata(metadata: Any, is_anomaly: bool) -> str:
 
 @dataclass
 class AlertConditions:
-    """Conditions that turn a sequence of detections into an alert."""
+    """Conditions that turn a sequence of detections into an alert.
+
+    Defaults mirror :class:`detectkit.config.metric_config.AlertConfig`
+    so direct API users get the same behavior as YAML users.
+    """
 
     min_detectors: int = 1
-    direction: str = "any"  # "any", "same", "up", "down"
-    consecutive_anomalies: int = 1
+    direction: str = "same"  # "any", "same", "up", "down"
+    consecutive_anomalies: int = 3
 
 
 @dataclass
@@ -80,3 +86,45 @@ class DetectionRecord:
     direction: str  # "up", "down", "none"
     severity: float
     detection_metadata: dict
+
+
+def hydrate_detection_records(rows: list[dict]) -> list[DetectionRecord]:
+    """Build :class:`DetectionRecord` rows from ``get_recent_detections`` output.
+
+    Emits one record *per detector per timestamp* (the orchestrator counts
+    records to evaluate ``min_detectors``). Input rows are timestamp-DESC as
+    returned by SQL; output is oldest→newest. Timestamps are normalized to
+    ``datetime64[ms]`` so grid-adjacency arithmetic is well-defined.
+    """
+    records: list[DetectionRecord] = []
+    for row in reversed(rows):
+        raw_ts = row["timestamp"]
+        if isinstance(raw_ts, datetime):
+            raw_ts = to_naive_utc(raw_ts)
+        timestamp = np.datetime64(raw_ts, "ms")
+        metadata_list = row.get("detection_metadata_list") or [None] * len(row["detector_ids"])
+        for i in range(len(row["detector_ids"])):
+            is_anomaly = bool(row["is_anomaly_flags"][i])
+            metadata = _parse_detection_metadata(metadata_list[i])
+            try:
+                severity = float(metadata.get("severity", 0.0) or 0.0)
+            except (TypeError, ValueError):
+                severity = 0.0
+
+            records.append(
+                DetectionRecord(
+                    timestamp=timestamp,
+                    detector_name=row["detector_names"][i],
+                    detector_id=row["detector_ids"][i],
+                    detector_params=row["detector_params_list"][i],
+                    value=row["value"],
+                    is_anomaly=is_anomaly,
+                    confidence_lower=row["confidence_lowers"][i],
+                    confidence_upper=row["confidence_uppers"][i],
+                    direction=_direction_from_metadata(metadata, is_anomaly),
+                    severity=severity,
+                    detection_metadata=metadata,
+                )
+            )
+
+    return records