detectkit 0.10.0__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.10.0
+Version: 0.12.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -61,7 +61,9 @@ Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Provides-Extra: integration
-Requires-Dist: testcontainers[clickhouse]>=4.0; extra == "integration"
+Requires-Dist: testcontainers[clickhouse,mysql,postgres]>=4.0; extra == "integration"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "integration"
+Requires-Dist: pymysql>=1.0.0; extra == "integration"
 Dynamic: license-file
 
 # detectkit

{detectkit-0.10.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.10.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.10.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.10.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.10.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.10.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.10.0 → detectkit-0.12.0}/detectkit/cli/assets/claude/rules/overview.md

@@ -3,9 +3,9 @@
 detectkit is a Python library and CLI (`dtk`) for monitoring time-series
 metrics with automatic anomaly detection and multi-channel alerting. It is
 **dbt-like**: metrics live as YAML + SQL in a project directory, and you run
-them with one command. Core logic is pure numpy (no pandas). **ClickHouse is
-the only implemented backend today**; PostgreSQL and MySQL are planned (their
-profiles validate but creating a manager raises `NotImplementedError`).
+them with one command. Core logic is pure numpy (no pandas). **ClickHouse,
+PostgreSQL and MySQL are all fully supported** — only the connection and the SQL
+dialect of your metric queries differ between them.
 
 ## The pipeline: load → detect → alert
 

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

@@ -78,11 +78,11 @@ alert_channels:
 
 ### Database profiles
 
-> ClickHouse is the only implemented backend today. PostgreSQL and MySQL are
-> planned — their profiles validate, but creating a manager raises
-> `NotImplementedError("... coming soon")`.
+> ClickHouse, PostgreSQL and MySQL are all fully supported. ClickHouse/MySQL use
+> two *databases*; PostgreSQL connects to one `database` and uses two *schemas*.
+> `dtk init --db-type {clickhouse,postgres,mysql}` scaffolds the right shape.
 
-**ClickHouse** (priority backend):
+**ClickHouse**:
 ```yaml
 profiles:
   prod:
@@ -98,36 +98,34 @@ profiles:
       max_memory_usage: 10000000000
 ```
 
-**PostgreSQL** (planned, not yet implemented):
+**PostgreSQL** (connect to `database`, tables in schemas):
 ```yaml
 profiles:
   prod:
     type: postgres
     host: localhost
     port: 5432
-    database: analytics            # required
+    database: detectkit            # required — must already exist
     user: postgres
     password: "..."
-    internal_schema: detectkit     # required — _dtk_* tables
+    internal_schema: detectkit     # required — _dtk_* tables (auto-created)
     data_schema: public            # required — data queries
-    pool_size: 5                   # optional
-    max_overflow: 10               # optional
+    settings: {}                   # optional — extra psycopg2.connect kwargs
 ```
 
-**MySQL** (planned, not yet implemented):
+**MySQL** (8.0+; two databases):
 ```yaml
 profiles:
   prod:
     type: mysql
     host: localhost
     port: 3306
-    database: analytics            # required
     user: root
     password: "..."
-    internal_database: detectkit   # required
+    internal_database: detectkit   # required — _dtk_* tables (auto-created)
     data_database: analytics       # required
-    charset: utf8mb4               # optional
-    autocommit: true               # optional
+    database: analytics            # optional — default db for the connection
+    settings: {}                   # optional — extra pymysql.connect kwargs
 ```
 
 ### Alert channels
@@ -135,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.
 
@@ -157,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
@@ -167,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
@@ -185,12 +197,12 @@ alert_channels:
 ## Notes
 
 - **First-run setup:** the `profiles.yml` that `dtk init` writes is a
-  placeholder — its `dev` profile points `internal_database` / `data_database`
-  at example values (`detectkit` / `default`) on `localhost`. Edit the host,
-  credentials and both database names to match your environment before running
-  (the **`dtk-setup-project`** skill walks this). There is no `database:` field —
-  ClickHouse needs both `internal_database` and `data_database`, or the run
-  raises `internal_database must be set for ClickHouse`.
+  placeholder scaffolded for `--db-type` (default ClickHouse) — its `dev`
+  profile points the location fields at example values on `localhost`. Edit the
+  host, credentials and location names to match your environment before running
+  (the **`dtk-setup-project`** skill walks this). ClickHouse/MySQL use
+  `internal_database` / `data_database` (no `database:` field on ClickHouse);
+  PostgreSQL connects to a `database` and uses `internal_schema` / `data_schema`.
 - `dtk run` (without `--profile`) uses the `default_profile` declared in
   **`profiles.yml`**; the `default_profile` in `detectkit_project.yml` is not
   read at runtime — keep them in sync to avoid confusion.

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

@@ -40,12 +40,17 @@ side by side, ask which one to set up.
 
 ## Step 1 — Pick the database backend
 
-**ClickHouse is the only implemented backend today.** PostgreSQL and MySQL
-profiles validate, but `dtk run` raises `NotImplementedError("PostgreSQL
-support coming soon")` / `"MySQL support coming soon"` when it builds the
-manager. If the user wants Postgres/MySQL, say plainly that runs won't work
-yet; you can still write the profile shape for later, but set expectations.
-Assume ClickHouse unless told otherwise.
+**ClickHouse, PostgreSQL and MySQL are all fully supported.** Ask which one the
+project uses (default to ClickHouse if unsure). `dtk init --db-type
+{clickhouse,postgres,mysql}` scaffolds `profiles.yml` for the chosen backend.
+The location fields differ:
+- **ClickHouse** / **MySQL** — two *databases*: `internal_database` / `data_database`.
+- **PostgreSQL** — connect to a `database` (must already exist), then two
+  *schemas*: `internal_schema` / `data_schema`.
+
+The metric query SQL dialect also differs (e.g. `toStartOfInterval` on
+ClickHouse vs `date_trunc`/`to_timestamp` on Postgres vs `FROM_UNIXTIME` on
+MySQL). Everything else — detectors, alerting, the CLI — is identical.
 
 ## Step 2 — Connection details (gather, don't guess)
 
@@ -74,8 +79,8 @@ values):
   data, e.g. `detectkit` or `monitoring`.
 - `data_database` — where the source tables your metric queries read from live.
 
-For Postgres these are `internal_schema` / `data_schema`; for MySQL they are
-`internal_database` / `data_database` (relevant only once those backends land).
+For Postgres these are `internal_schema` / `data_schema` (inside the connected
+`database`); for MySQL they are `internal_database` / `data_database`.
 
 ## Step 4 — Profile name & `default_profile`
 
@@ -111,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