detectkit 0.11.0__tar.gz → 0.12.0__tar.gz

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

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

{detectkit-0.11.0 → detectkit-0.12.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.12.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

detectkit-0.12.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"

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/alerting/channels/email.py

@@ -4,11 +4,14 @@ Email alert channel implementation.
 Sends anomaly alerts via SMTP email.
 """
 
+import html
 import smtplib
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
+from email.utils import formataddr
 
 from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
+from detectkit.alerting.channels.branding import BRAND_ICON_URL, BRAND_USERNAME
 
 
 class EmailChannel(BaseAlertChannel):
@@ -55,6 +58,7 @@ class EmailChannel(BaseAlertChannel):
         smtp_password: str | None = None,
         use_tls: bool = True,
         subject_template: str = "⚠ Alert: {metric_name}",
+        from_name: str = BRAND_USERNAME,
         template: str | None = None,
         **kwargs,
     ):
@@ -70,6 +74,9 @@ class EmailChannel(BaseAlertChannel):
             smtp_password: SMTP authentication password (optional)
             use_tls: Whether to use STARTTLS (default: True)
             subject_template: Email subject template with {metric_name} placeholder
+            from_name: Sender display name shown in the ``From`` header — the
+                email equivalent of the bot name (default: "detectkit"). The
+                brand logo is also rendered in the HTML body.
             template: Custom message template (optional)
             **kwargs: Additional parameters (ignored)
 
@@ -93,6 +100,7 @@ class EmailChannel(BaseAlertChannel):
         self.to_emails = to_emails
         self.use_tls = use_tls
         self.subject_template = subject_template
+        self.from_name = from_name
         self.template = template
 
     def send(self, alert_data: AlertData, template: str | None = None) -> bool:
@@ -117,12 +125,17 @@ class EmailChannel(BaseAlertChannel):
 
         # Create email message
         msg = MIMEMultipart("alternative")
-        msg["From"] = self.from_email
+        # Branded From: "detectkit <alerts@example.com>" — the email equivalent
+        # of a bot display name. formataddr quotes the name when required.
+        msg["From"] = formataddr((self.from_name, self.from_email))
         msg["To"] = ", ".join(self.to_emails)
         msg["Subject"] = self.subject_template.format(metric_name=alert_data.metric_name)
 
-        # Attach plain text body
+        # Attach both parts. In multipart/alternative the LAST part is the
+        # preferred one, so HTML (with the brand logo) is shown when supported
+        # and the plain-text body remains the fallback.
         msg.attach(MIMEText(message_body, "plain"))
+        msg.attach(MIMEText(self._build_html_body(message_body), "html"))
 
         try:
             # Connect to SMTP server
@@ -145,6 +158,37 @@ class EmailChannel(BaseAlertChannel):
 
         return True
 
+    def _build_html_body(self, message_body: str) -> str:
+        """Wrap the plain-text body in a branded HTML layout.
+
+        Renders a small header with the detectkit brand logo and name above the
+        message (kept in a ``<pre>`` so the alert-centric text layout carries
+        over verbatim). The logo is referenced by URL; clients that block remote
+        images simply fall back to the alt text and the plain-text part.
+
+        Args:
+            message_body: The formatted plain-text alert body.
+
+        Returns:
+            An HTML document string.
+        """
+        safe_body = html.escape(message_body)
+        return (
+            '<div style="font-family:-apple-system,Segoe UI,Roboto,Helvetica,'
+            'Arial,sans-serif;color:#1b1916;max-width:640px">'
+            '<div style="margin-bottom:12px">'
+            f'<img src="{BRAND_ICON_URL}" width="28" height="28" '
+            f'alt="{html.escape(BRAND_USERNAME)}" '
+            'style="border-radius:6px;vertical-align:middle">'
+            '<span style="font-weight:600;font-size:16px;color:#d15b36;'
+            f'vertical-align:middle;margin-left:8px">{html.escape(BRAND_USERNAME)}</span>'
+            "</div>"
+            '<pre style="white-space:pre-wrap;font-family:JetBrains Mono,'
+            "ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px;"
+            f'line-height:1.5;margin:0">{safe_body}</pre>'
+            "</div>"
+        )
+
     def format_mentions(self, mentions: list[str]) -> str:
         """
         Format mentions for email.

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/alerting/channels/mattermost.py

@@ -4,6 +4,7 @@ Mattermost alert channel.
 Convenience wrapper around WebhookChannel for Mattermost.
 """
 
+from detectkit.alerting.channels.branding import BRAND_USERNAME
 from detectkit.alerting.channels.webhook import WebhookChannel
 
 
@@ -15,10 +16,15 @@ class MattermostChannel(WebhookChannel):
     for Mattermost. Mattermost webhooks are compatible with Slack API,
     so WebhookChannel can be used directly.
 
+    The bot defaults to the **detectkit brand avatar** and name; override the
+    avatar with ``icon_url`` (a custom image) or opt out of the avatar with
+    ``icon_emoji``. See :class:`WebhookChannel` for the icon precedence rules.
+
     Parameters:
         webhook_url (str): Mattermost incoming webhook URL
-        username (str): Bot username to display (default: "detectk")
-        icon_emoji (str): Bot emoji icon (default: ":warning:")
+        username (str): Bot username to display (default: "detectkit")
+        icon_url (str): Bot avatar image URL (default: detectkit brand avatar)
+        icon_emoji (str): Bot emoji icon — use instead of an avatar image
         timeout (int): Request timeout in seconds (default: 10)
 
     Example:
@@ -31,8 +37,9 @@ class MattermostChannel(WebhookChannel):
     def __init__(
         self,
         webhook_url: str,
-        username: str = "detectk",
-        icon_emoji: str = ":warning:",
+        username: str = BRAND_USERNAME,
+        icon_url: str | None = None,
+        icon_emoji: str | None = None,
         channel: str | None = None,
         timeout: int = 10,
     ):
@@ -40,6 +47,7 @@ class MattermostChannel(WebhookChannel):
         super().__init__(
             webhook_url=webhook_url,
             username=username,
+            icon_url=icon_url,
             icon_emoji=icon_emoji,
             channel=channel,  # Optional: override webhook's default channel
             timeout=timeout,

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/alerting/channels/slack.py

@@ -4,6 +4,7 @@ Slack alert channel.
 Convenience wrapper around WebhookChannel for Slack.
 """
 
+from detectkit.alerting.channels.branding import BRAND_USERNAME
 from detectkit.alerting.channels.webhook import WebhookChannel
 
 
@@ -14,10 +15,15 @@ class SlackChannel(WebhookChannel):
     This is a convenience wrapper around WebhookChannel specifically
     for Slack. Slack and Mattermost use compatible webhook formats.
 
+    The bot defaults to the **detectkit brand avatar** and name; override the
+    avatar with ``icon_url`` (a custom image) or opt out of the avatar with
+    ``icon_emoji``. See :class:`WebhookChannel` for the icon precedence rules.
+
     Parameters:
         webhook_url (str): Slack incoming webhook URL
-        username (str): Bot username to display (default: "detectk")
-        icon_emoji (str): Bot emoji icon (default: ":warning:")
+        username (str): Bot username to display (default: "detectkit")
+        icon_url (str): Bot avatar image URL (default: detectkit brand avatar)
+        icon_emoji (str): Bot emoji icon — use instead of an avatar image
         channel (str): Target Slack channel (optional, e.g., "#alerts")
         timeout (int): Request timeout in seconds (default: 10)
 
@@ -32,8 +38,9 @@ class SlackChannel(WebhookChannel):
     def __init__(
         self,
         webhook_url: str,
-        username: str = "detectk",
-        icon_emoji: str = ":warning:",
+        username: str = BRAND_USERNAME,
+        icon_url: str | None = None,
+        icon_emoji: str | None = None,
         channel: str | None = None,
         timeout: int = 10,
     ):
@@ -41,6 +48,7 @@ class SlackChannel(WebhookChannel):
         super().__init__(
             webhook_url=webhook_url,
             username=username,
+            icon_url=icon_url,
             icon_emoji=icon_emoji,
             channel=channel,
             timeout=timeout,

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/alerting/channels/webhook.py

@@ -8,6 +8,7 @@ Compatible with Mattermost, Slack, and other webhook-based systems.
 import requests
 
 from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
+from detectkit.alerting.channels.branding import BRAND_ICON_URL, BRAND_USERNAME
 
 
 class WebhookChannel(BaseAlertChannel):
@@ -24,14 +25,21 @@ class WebhookChannel(BaseAlertChannel):
     {
         "text": "message",
         "username": "bot_name",
-        "icon_emoji": ":emoji:",
+        "icon_url": "https://.../bot-icon.png",   # or "icon_emoji": ":emoji:"
         "channel": "#channel" (optional)
     }
 
+    Branding: the bot defaults to the **detectkit brand avatar** (``icon_url``)
+    and name (``username``). An explicit ``icon_url`` overrides it with a custom
+    image; an explicit ``icon_emoji`` opts out of the avatar in favor of an
+    emoji. Only one icon field is sent (``icon_url`` wins when both are set).
+
     Parameters:
         webhook_url (str): Webhook URL to send alerts to
-        username (str): Bot username to display (default: "detectk")
-        icon_emoji (str): Bot emoji icon (default: ":warning:")
+        username (str): Bot username to display (default: "detectkit")
+        icon_url (str): Bot avatar image URL (default: detectkit brand avatar)
+        icon_emoji (str): Bot emoji icon — use instead of an avatar image
+            (default: None; falls back to the brand avatar)
         channel (str): Target channel (optional, for Slack/Mattermost)
         timeout (int): Request timeout in seconds (default: 10)
         extra_headers (dict): Additional HTTP headers (optional)
@@ -58,8 +66,9 @@ class WebhookChannel(BaseAlertChannel):
     def __init__(
         self,
         webhook_url: str,
-        username: str = "detectk",
-        icon_emoji: str = ":warning:",
+        username: str = BRAND_USERNAME,
+        icon_url: str | None = None,
+        icon_emoji: str | None = None,
         channel: str | None = None,
         timeout: int = 10,
         extra_headers: dict[str, str] | None = None,
@@ -70,6 +79,12 @@ class WebhookChannel(BaseAlertChannel):
 
         self.webhook_url = webhook_url
         self.username = username
+        # Default to the detectkit brand avatar. An explicit icon_url or
+        # icon_emoji opts out of the default; we only fill in the brand avatar
+        # when the user configured neither.
+        if icon_url is None and icon_emoji is None:
+            icon_url = BRAND_ICON_URL
+        self.icon_url = icon_url
         self.icon_emoji = icon_emoji
         self.channel = channel
         self.timeout = timeout
@@ -118,12 +133,18 @@ class WebhookChannel(BaseAlertChannel):
             "text": body,
         }
 
-        payload = {
+        payload: dict[str, object] = {
             "username": self.username,
-            "icon_emoji": self.icon_emoji,
             "attachments": [attachment],
         }
 
+        # Send exactly one icon field: the avatar image (brand default or a
+        # custom override) takes precedence over an emoji.
+        if self.icon_url:
+            payload["icon_url"] = self.icon_url
+        elif self.icon_emoji:
+            payload["icon_emoji"] = self.icon_emoji
+
         # Add channel if specified (for Slack)
         if self.channel:
             payload["channel"] = self.channel

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/cli/assets/claude/rules/project.md

@@ -133,17 +133,24 @@ profiles:
 Defined once in `profiles.yml`, referenced by name in each metric's
 `alerting.channels` (and in `error_alerting.channels`).
 
+The bot defaults to the **detectkit brand** name + avatar on every channel.
+Override per channel; Telegram and email brand differently (see their notes).
+
 **Mattermost** / **Slack** (Slack-compatible webhook API, same fields):
 ```yaml
 alert_channels:
   mattermost_ops:
     type: mattermost            # or: slack
     webhook_url: "{{ env_var('MATTERMOST_WEBHOOK_URL') }}"   # required
-    username: "detectkit"       # optional (default: "detectkit")
-    icon_emoji: ":warning:"     # optional
     channel: "alerts"           # optional — override webhook default ("#alerts" for Slack)
     timeout: 10                 # optional HTTP timeout (s)
+    # Bot identity defaults to the detectkit brand; override any of:
+    # username: "detectkit"            # display name
+    # icon_url: "https://.../bot.png"  # avatar image (default: brand avatar)
+    # icon_emoji: ":warning:"          # emoji instead of an avatar image
 ```
+> Icon precedence: `icon_url` (default: brand avatar) wins over `icon_emoji`;
+> set either to opt out of the brand avatar.
 > Slack note: `@username` in a Slack webhook is **display-only** (no real ping).
 > Use Slack user IDs (`U…`) for real pings.
 
@@ -155,6 +162,9 @@ alert_channels:
     bot_token: "{{ env_var('TG_BOT_TOKEN') }}"   # required
     chat_id: "-1001234567890"                    # required
 ```
+> Telegram shows the bot account's own avatar (set in @BotFather, not
+> per-message), so detectkit can't override it. Brand it via `/setuserpic` —
+> the detectkit avatar is at `https://dtk.pipelab.dev/bot-icon.png`.
 
 **Email** (SMTP):
 ```yaml
@@ -165,10 +175,14 @@ alert_channels:
     smtp_port: 587                # required (587 TLS, 465 SSL)
     from_email: "alerts@example.com"   # required
     to_emails: ["ops@example.com"]     # required (list)
+    from_name: "detectkit"        # optional — From display name (default: "detectkit")
     smtp_username: "..."          # optional
     smtp_password: "..."          # optional (use env_var)
     use_tls: true                 # optional (default: true)
 ```
+> Sends as `detectkit <from_email>` with the brand logo in an HTML body (plain
+> text stays the fallback). The avatar mail clients show is set by the sending
+> domain (BIMI), not the message — brand it via `from_name` + your domain.
 
 **Webhook** (generic):
 ```yaml

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/cli/assets/claude/skills/dtk-setup-project/SKILL.md

@@ -116,14 +116,19 @@ If the user wants alerts now, add one channel under `alert_channels:` (it is
 referenced by name from each metric's `alerting.channels`). Pick the type and
 gather its required fields (see `project.md` for the full set per type):
 
+The bot defaults to the **detectkit brand** name + avatar everywhere; the
+identity fields below are optional overrides.
+
 - **mattermost** / **slack** — `webhook_url` (use `env_var`); optional
-  `channel`, `username`, `icon_emoji`.
-- **telegram** — `bot_token` (env_var) + `chat_id`.
+  `channel`, `username`, `icon_url` (avatar; default brand), `icon_emoji`.
+- **telegram** — `bot_token` (env_var) + `chat_id`. (Bot avatar is set in
+  @BotFather, not by detectkit.)
 - **email** — `smtp_host`, `smtp_port`, `from_email`, `to_emails` (list);
+  optional `from_name` (From display name, default `detectkit`);
   `smtp_username` / `smtp_password` via env_var.
 - **webhook** — generic `webhook_url` (required) + optional `extra_headers`
-  (also accepts `username` / `icon_emoji` / `channel`). There is no `url`,
-  `method` or `headers` field.
+  (also accepts `username` / `icon_url` / `icon_emoji` / `channel`). There is
+  no `url`, `method` or `headers` field.
 
 ```yaml
 # at the end of profiles.yml

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit/cli/commands/init.py

@@ -134,20 +134,21 @@ _BUCKET_SQL = {
 _ALERT_CHANNELS = """
 # Alert channels (referenced by name from a metric's alerting.channels)
 alert_channels:
-  # Mattermost. Supported keys: webhook_url, username, icon_emoji, channel,
-  # timeout. NOTE: there is no `icon_url` param — use `icon_emoji`.
+  # Mattermost. Supported keys: webhook_url, username, icon_url, icon_emoji,
+  # channel, timeout. The bot name + avatar default to the detectkit brand;
+  # override the avatar with icon_url (an image URL) or icon_emoji (an emoji).
   mattermost_alerts:
     type: mattermost
     webhook_url: "{{ env_var('MATTERMOST_WEBHOOK_URL') }}"
-    username: detectkit
-    icon_emoji: ":warning:"
+    # username: detectkit              # optional — override the display name
+    # icon_url: "https://.../bot.png"  # optional — override the brand avatar
+    # icon_emoji: ":warning:"          # optional — emoji instead of an avatar
 
   # Slack example (same fields as mattermost)
   # slack_alerts:
   #   type: slack
   #   webhook_url: "{{ env_var('SLACK_WEBHOOK_URL') }}"
   #   channel: "#alerts"
-  #   username: detectkit
 
   # Telegram example (required: bot_token, chat_id)
   # telegram_alerts:
@@ -161,6 +162,7 @@ alert_channels:
   #   smtp_host: smtp.gmail.com
   #   smtp_port: 587
   #   from_email: alerts@example.com
+  #   from_name: detectkit          # optional — From display name (default: detectkit)
   #   to_emails:
   #     - team@example.com
   #   smtp_username: "{{ env_var('SMTP_USERNAME') }}"

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

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

{detectkit-0.11.0 → detectkit-0.12.0}/detectkit.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ detectkit.egg-info/top_level.txt
 detectkit/alerting/__init__.py
 detectkit/alerting/channels/__init__.py
 detectkit/alerting/channels/base.py
+detectkit/alerting/channels/branding.py
 detectkit/alerting/channels/email.py
 detectkit/alerting/channels/factory.py
 detectkit/alerting/channels/mattermost.py