detectkit 0.11.0__tar.gz → 0.13.0__tar.gz

{detectkit-0.11.0/detectkit.egg-info → detectkit-0.13.0}/PKG-INFO

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

{detectkit-0.11.0 → detectkit-0.13.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.11.0"
+__version__ = "0.13.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.11.0 → detectkit-0.13.0}/detectkit/alerting/channels/base.py

@@ -67,6 +67,14 @@ class AlertData:
     description: str | None = None
     mentions: list[str] = field(default_factory=list)
     project_name: str | None = None
+    # Optional actionable links surfaced in the message. ``dashboard_url`` is the
+    # headline link (rendered natively as a clickable title/link on
+    # Slack/Mattermost, an ``<a>`` on Telegram, a button in email, and exposed as
+    # the ``{dashboard_url}`` template variable). ``links`` adds further
+    # ``label -> url`` pairs for advanced use. Both default to empty so existing
+    # callers and templates render unchanged.
+    dashboard_url: str | None = None
+    links: dict[str, str] = field(default_factory=dict)
     # Alert rule (the parameters the alert fired with) — see class docstring.
     min_detectors: int | None = None
     direction_policy: str | None = None
@@ -171,12 +179,47 @@ class BaseAlertChannel(ABC):
             else:
                 template = self.get_default_template()
 
-        # Format timestamp to string
+        ctx = self.build_context(alert_data)
+
+        try:
+            message = template.format(**ctx)
+        except (KeyError, ValueError, TypeError):
+            # Template has an unknown variable or a format spec that doesn't fit
+            # the actual value (e.g. ``{value:.2f}`` in a no-data template where
+            # value is a string). Fall back to the kind-appropriate default.
+            if alert_data.is_error:
+                fallback = self.get_default_error_template()
+            elif alert_data.is_no_data:
+                fallback = self.get_default_no_data_template()
+            elif alert_data.is_recovery:
+                fallback = self.get_default_recovery_template()
+            else:
+                fallback = self.get_default_template()
+            if template == fallback:
+                # Already on the default — re-raise instead of recursing.
+                raise
+            message = self.format_message(alert_data, fallback)
+
+        return message
+
+    def build_context(self, alert_data: AlertData) -> dict[str, Any]:
+        """Compute the display-ready variables for *alert_data*.
+
+        This is the **single source** of the values injected into message
+        templates *and* consumed by channels that render natively (the webhook
+        attachment fields, the Telegram HTML message, the email HTML card), so
+        every surface stays consistent. It does no escaping — each channel
+        applies its own (HTML for Telegram/email, markdown for webhook).
+
+        Returns a dict whose keys are exactly the ``{placeholders}`` the default
+        templates use, plus a few extras (``dashboard_url``, ``dashboard_line``).
+        """
         import math
         from datetime import datetime
 
         import numpy as np
 
+        # Format timestamp to string
         ts = alert_data.timestamp
         if isinstance(ts, np.datetime64):
             ts = ts.astype(datetime)
@@ -248,13 +291,18 @@ class BaseAlertChannel(ABC):
         mentions_str = self.format_mentions(alert_data.mentions)
         mentions_line = f"\n{mentions_str}" if mentions_str else ""
 
+        # Optional dashboard link surfaced both as a raw placeholder and a ready
+        # "Dashboard: <url>" line (empty when unset so templates stay clean).
+        dashboard_url = alert_data.dashboard_url or ""
+        dashboard_line = f"Dashboard: {dashboard_url}\n" if dashboard_url else ""
+
         # Project name + synth prefix for templates. Prefix is empty when
         # project_name is None so default templates render cleanly for
         # callers that don't set it.
         project_name = alert_data.project_name or ""
         project_name_prefix = f"[{alert_data.project_name}] " if alert_data.project_name else ""
 
-        # Format message
+        # Status keyword
         if alert_data.is_error:
             status = "ERROR"
         elif alert_data.is_no_data:
@@ -264,54 +312,84 @@ class BaseAlertChannel(ABC):
         else:
             status = "ANOMALY"
 
-        try:
-            message = template.format(
-                metric_name=alert_data.metric_name,
-                project_name=project_name,
-                project_name_prefix=project_name_prefix,
-                timestamp=ts_str,
-                timezone=alert_data.timezone,
-                value=value_for_template,
-                value_display=value_display,
-                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 "",
-                description=alert_data.description or "",
-                description_line=description_line,
-                mentions=mentions_str,
-                mentions_line=mentions_line,
-            )
-        except (KeyError, ValueError, TypeError):
-            # Template has an unknown variable or a format spec that doesn't fit
-            # the actual value (e.g. ``{value:.2f}`` in a no-data template where
-            # value is a string). Fall back to the kind-appropriate default.
-            if alert_data.is_error:
-                fallback = self.get_default_error_template()
-            elif alert_data.is_no_data:
-                fallback = self.get_default_no_data_template()
-            elif alert_data.is_recovery:
-                fallback = self.get_default_recovery_template()
-            else:
-                fallback = self.get_default_template()
-            if template == fallback:
-                # Already on the default — re-raise instead of recursing.
-                raise
-            message = self.format_message(alert_data, fallback)
+        return {
+            "metric_name": alert_data.metric_name,
+            "project_name": project_name,
+            "project_name_prefix": project_name_prefix,
+            "timestamp": ts_str,
+            "timezone": alert_data.timezone,
+            "value": value_for_template,
+            "value_display": value_display,
+            "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 "",
+            "description": alert_data.description or "",
+            "description_line": description_line,
+            "dashboard_url": dashboard_url,
+            "dashboard_line": dashboard_line,
+            "mentions": mentions_str,
+            "mentions_line": mentions_line,
+        }
+
+    # ---- Status presentation (shared accents across all channels) ----
+    # Kept in sync with the brand status tokens (.claude/rules/design.md) and the
+    # website status colors so chat, email and dashboards read the same way.
+    _STATUS_COLORS = {
+        "anomaly": "#D63232",
+        "recovery": "#36A64F",
+        "no_data": "#F0AD4E",
+        "error": "#5A7A8C",
+    }
+    _STATUS_WORDS = {
+        "anomaly": "Anomaly",
+        "recovery": "Recovered",
+        "no_data": "No data",
+        "error": "Pipeline error",
+    }
+    # Colored status dots — the at-a-glance status cue that leads every alert
+    # title/headline (and the only color cue on Telegram, which has no bar).
+    _STATUS_EMOJI = {
+        "anomaly": "\U0001f534",  # red circle
+        "recovery": "\U0001f7e2",  # green circle
+        "no_data": "\U0001f7e1",  # yellow circle
+        "error": "\U0001f535",  # blue circle
+    }
+
+    @staticmethod
+    def status_kind(alert_data: AlertData) -> str:
+        """Return the alert kind: ``anomaly`` / ``recovery`` / ``no_data`` / ``error``."""
+        if alert_data.is_error:
+            return "error"
+        if alert_data.is_no_data:
+            return "no_data"
+        if alert_data.is_recovery:
+            return "recovery"
+        return "anomaly"
 
-        return message
+    def status_color(self, alert_data: AlertData) -> str:
+        """Accent color for this alert kind (hex)."""
+        return self._STATUS_COLORS[self.status_kind(alert_data)]
+
+    def status_word(self, alert_data: AlertData) -> str:
+        """Human-readable status word for this alert kind."""
+        return self._STATUS_WORDS[self.status_kind(alert_data)]
+
+    def status_emoji(self, alert_data: AlertData) -> str:
+        """Colored status dot for channels without a native color bar."""
+        return self._STATUS_EMOJI[self.status_kind(alert_data)]
 
     def format_mentions(self, mentions: list[str]) -> str:
         """
@@ -372,7 +450,7 @@ class BaseAlertChannel(ABC):
             Default template string
         """
         return (
-            "⚠ Alert: {metric_name}\n"
+            "🔴 Alert: {metric_name}\n"
             "{description_line}"
             "Quorum {detector_count}/{min_detectors} · "
             "direction {direction} (policy {direction_policy}) · "
@@ -385,7 +463,8 @@ class BaseAlertChannel(ABC):
             "· Value: {value_display} | Expected: {expected_range}\n"
             "· Severity: {severity:.2f}\n"
             "Detectors: {detector_name}\n"
-            "Parameters: {detector_params}"
+            "Parameters: {detector_params}\n"
+            "{dashboard_line}"
             "{mentions_line}"
         )
 
@@ -397,7 +476,7 @@ class BaseAlertChannel(ABC):
             Default recovery template string
         """
         return (
-            "✅ Alert cleared: {metric_name}\n"
+            "🟢 Alert cleared: {metric_name}\n"
             "{description_line}"
             "The alert condition no longer holds — "
             "the metric is back within expected bounds.\n"
@@ -407,7 +486,8 @@ class BaseAlertChannel(ABC):
             "Latest point:\n"
             "· Time: {timestamp}\n"
             "· Value: {value_display} | Expected: {expected_range}\n"
-            "Detectors: {detector_name}"
+            "Detectors: {detector_name}\n"
+            "{dashboard_line}"
             "{mentions_line}"
         )
 
@@ -420,7 +500,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default title template string
         """
-        return "⚠ Alert: {metric_name}"
+        return "🔴 Alert: {metric_name}"
 
     def get_default_recovery_title_template(self) -> str:
         """
@@ -429,7 +509,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default recovery title template string
         """
-        return "✅ Alert cleared: {metric_name}"
+        return "🟢 Alert cleared: {metric_name}"
 
     def get_default_no_data_template(self) -> str:
         """
@@ -439,24 +519,26 @@ class BaseAlertChannel(ABC):
         has no datapoint (no row OR row with NULL/NaN value).
         """
         return (
-            "No data for metric: {metric_name}\n"
+            "🟡 No data for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
-            "Status: query returned no datapoint for the latest interval"
+            "Status: query returned no datapoint for the latest interval\n"
+            "{dashboard_line}"
             "{mentions_line}"
         )
 
     def get_default_no_data_title_template(self) -> str:
         """Get default title template for no-data alerts."""
-        return "No data: {metric_name}"
+        return "🟡 No data: {metric_name}"
 
     def get_default_error_template(self) -> str:
         """Default body template for project-level error alerts."""
         return (
-            "Pipeline failed for metric: {metric_name}\n"
+            "🔵 Pipeline failed for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
-            "Error: {error_type}: {error_message}"
+            "Error: {error_type}: {error_message}\n"
+            "{dashboard_line}"
             "{mentions_line}"
         )
 
@@ -468,7 +550,7 @@ class BaseAlertChannel(ABC):
         stay distinguishable. The prefix collapses to an empty string
         when ``AlertData.project_name`` is None.
         """
-        return "{project_name_prefix}Pipeline error: {metric_name}"
+        return "🔵 {project_name_prefix}Pipeline error: {metric_name}"
 
     def __repr__(self) -> str:
         """String representation of channel."""

detectkit-0.13.0/detectkit/alerting/channels/branding.py

@@ -0,0 +1,20 @@
+"""
+Default detectkit branding for alert channels.
+
+Centralizes the bot identity — display name and avatar — so every channel
+defaults to the **detectkit brand**. These are only the fallbacks: each channel
+still accepts per-channel overrides (``username`` / ``from_name`` for the name,
+``icon_url`` / ``icon_emoji`` for the avatar). Keeping them in one place means
+the brand avatar URL and name have a single source of truth.
+"""
+
+# Bot display name shown as the message sender across channels (webhook-family
+# ``username`` and the email ``From`` display name).
+BRAND_USERNAME = "detectkit"
+
+# Brand avatar served from the docs site. Slack/Mattermost render the webhook
+# bot icon from a **raster** URL (an SVG is not rendered as a bot avatar), so
+# this points at a PNG. Override per channel with ``icon_url`` (a custom image)
+# or opt out of the avatar entirely with ``icon_emoji``. The PNG is generated by
+# ``website/scripts/make-bot-icon.mjs`` and served from ``website/public/``.
+BRAND_ICON_URL = "https://dtk.pipelab.dev/bot-icon.png"