detectkit 0.15.0__tar.gz → 0.16.0__tar.gz

{detectkit-0.15.0/detectkit.egg-info → detectkit-0.16.0}/PKG-INFO

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

{detectkit-0.15.0 → detectkit-0.16.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.15.0"
+__version__ = "0.16.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/channels/base.py

@@ -9,6 +9,8 @@ from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from typing import Any
 
+from detectkit.alerting.channels.branding import ALERT_GUIDE_LABEL
+
 
 @dataclass
 class AlertData:
@@ -79,6 +81,12 @@ class AlertData:
     # callers and templates render unchanged.
     dashboard_url: str | None = None
     links: dict[str, str] = field(default_factory=dict)
+    # "How to read this alert" link surfaced on every default-rendered message so
+    # non-operator stakeholders can click through to a plain-language guide. The
+    # orchestrator resolves it from ``ProjectConfig.alert_help_url`` (defaulting to
+    # the official docs); direct-API callers leave it ``None`` and render unchanged.
+    # Exposed to templates as ``{help_url}`` / ``{help_line}``.
+    help_url: str | None = None
     # Alert rule (the parameters the alert fired with) — see class docstring.
     min_detectors: int | None = None
     direction_policy: str | None = None
@@ -300,6 +308,11 @@ class BaseAlertChannel(ABC):
         dashboard_url = alert_data.dashboard_url or ""
         dashboard_line = f"Dashboard: {dashboard_url}\n" if dashboard_url else ""
 
+        # "How to read this alert" link (same shape as dashboard): a raw
+        # placeholder plus a ready-to-drop line, both empty when unset.
+        help_url = alert_data.help_url or ""
+        help_line = f"{ALERT_GUIDE_LABEL}: {help_url}\n" if help_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.
@@ -344,6 +357,9 @@ class BaseAlertChannel(ABC):
             "description_line": description_line,
             "dashboard_url": dashboard_url,
             "dashboard_line": dashboard_line,
+            "help_url": help_url,
+            "help_line": help_line,
+            "help_label": ALERT_GUIDE_LABEL,
             "mentions": mentions_str,
             "mentions_line": mentions_line,
         }
@@ -469,6 +485,7 @@ class BaseAlertChannel(ABC):
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -492,6 +509,7 @@ class BaseAlertChannel(ABC):
             "· Value: {value_display} | Expected: {expected_range}\n"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -528,6 +546,7 @@ class BaseAlertChannel(ABC):
             "Time: {timestamp}\n"
             "Status: query returned no datapoint for the latest interval\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -543,6 +562,7 @@ class BaseAlertChannel(ABC):
             "Time: {timestamp}\n"
             "Error: {error_type}: {error_message}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/channels/branding.py

@@ -18,3 +18,13 @@ BRAND_USERNAME = "detectkit"
 # 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"
+
+# Default "how to read this alert" link surfaced on every default-rendered alert,
+# so non-operator stakeholders (PMs, analysts, on-call) seeing a notification can
+# click through to a plain-language guide explaining what they're looking at. It
+# points at the official docs page by default; a project can redirect it to its
+# own runbook (or hide it) via ``ProjectConfig.alert_help_url`` — the resolved URL
+# is stamped onto ``AlertData.help_url`` by the orchestrator. ``ALERT_GUIDE_LABEL``
+# is the shared link text so every channel reads the same.
+BRAND_ALERT_GUIDE_URL = "https://dtk.pipelab.dev/guides/reading-alerts/"
+ALERT_GUIDE_LABEL = "How to read this alert"

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/channels/email.py

@@ -12,7 +12,11 @@ from email.utils import formataddr
 from typing import Any
 
 from detectkit.alerting.channels.base import AlertData, BaseAlertChannel
-from detectkit.alerting.channels.branding import BRAND_ICON_URL, BRAND_USERNAME
+from detectkit.alerting.channels.branding import (
+    ALERT_GUIDE_LABEL,
+    BRAND_ICON_URL,
+    BRAND_USERNAME,
+)
 
 # Brand palette as hex literals. Email clients (Outlook/Word engine) ignore CSS
 # custom properties, so the values from website/src/styles/brand.css are copied
@@ -458,11 +462,20 @@ class EmailChannel(BaseAlertChannel):
         project_html = (
             f" · {html.escape(alert_data.project_name)}" if alert_data.project_name else ""
         )
+        # "How to read this alert" — a clay footer link to the interpretation
+        # guide (empty when opted out via alert_help_url: false).
+        help_html = ""
+        if alert_data.help_url:
+            href = html.escape(alert_data.help_url, quote=True)
+            help_html = (
+                f' &middot; <a href="{href}" style="color:{_CLAY};text-decoration:none;">'
+                f"{html.escape(ALERT_GUIDE_LABEL)} &rarr;</a>"
+            )
         return (
             f'<tr><td bgcolor="{_SURFACE}" style="background-color:{_SURFACE};'
             f"border-top:1px solid {_BORDER};padding:14px 24px;font-family:{_SANS};"
             f'font-size:12px;color:{_FAINT};mso-line-height-rule:exactly;line-height:16px;">'
-            f"Sent by detectkit{project_html}{cc_html}</td></tr>"
+            f"Sent by detectkit{project_html}{cc_html}{help_html}</td></tr>"
         )
 
     def format_mentions(self, mentions: list[str]) -> str:

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/channels/telegram.py

@@ -219,6 +219,11 @@ class TelegramChannel(BaseAlertChannel):
         for label, url in alert_data.links.items():
             href = html.escape(url, quote=True)
             link_parts.append(f'<a href="{href}">{esc(label)}</a>')
+        # "How to read this alert" — always present (unless opted out), so a
+        # stakeholder can click through to the interpretation guide.
+        if ctx["help_url"]:
+            href = html.escape(ctx["help_url"], quote=True)
+            link_parts.append(f'<a href="{href}">{esc(ctx["help_label"])}</a>')
         if link_parts:
             lines.append("")
             lines.append(" · ".join(link_parts))

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/channels/webhook.py

@@ -303,6 +303,11 @@ class WebhookChannel(BaseAlertChannel):
         if link_lines:
             full("Links", "\n".join(link_lines))
 
+        # "How to read this alert" — the last field, a bare URL (auto-linkified on
+        # both Slack and Mattermost) pointing readers at the interpretation guide.
+        if ctx["help_url"]:
+            full(ctx["help_label"], ctx["help_url"])
+
         # A plain-text one-liner for notification previews / unsupported clients.
         if kind == "no_data":
             fallback = f"{title} at {ctx['timestamp']}"
@@ -357,6 +362,7 @@ class WebhookChannel(BaseAlertChannel):
             "Detectors: {detector_name}\n"
             "Parameters: {detector_params}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -376,6 +382,7 @@ class WebhookChannel(BaseAlertChannel):
             "· Value: {value_display} | Expected: {expected_range}\n"
             "Detectors: {detector_name}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -386,6 +393,7 @@ class WebhookChannel(BaseAlertChannel):
             "Time: {timestamp}\n"
             "Status: query returned no datapoint for the latest interval\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 
@@ -396,6 +404,7 @@ class WebhookChannel(BaseAlertChannel):
             "Time: {timestamp}\n"
             "Error: {error_type}: {error_message}\n"
             "{dashboard_line}"
+            "{help_line}"
             "{mentions_line}"
         )
 

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_base.py

@@ -26,6 +26,7 @@ class _OrchestratorBase:
         dashboard_url: str | None = None,
         links: dict[str, str] | None = None,
         project_name: str | None = None,
+        help_url: str | None = None,
     ):
         self.metric_name = metric_name
         self.interval = interval
@@ -43,6 +44,10 @@ class _OrchestratorBase:
         # came from — keeps multiple projects sharing one channel distinct
         # while the bot keeps the default brand name + avatar.
         self.project_name = project_name
+        # Resolved "how to read this alert" link (from ProjectConfig.alert_help_url,
+        # defaulting to the official docs; None when opted out). Stamped onto every
+        # AlertData so channels render a guide link for non-operator stakeholders.
+        self.help_url = help_url
 
     @staticmethod
     def _group_by_timestamp(

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_decision.py

@@ -242,6 +242,7 @@ class _DecisionMixin(_OrchestratorBase):
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,
+            help_url=self.help_url,
             # Alert rule the message foregrounds: configured thresholds plus
             # the observed quorum size that satisfied them.
             min_detectors=self.conditions.min_detectors,
@@ -302,6 +303,7 @@ class _DecisionMixin(_OrchestratorBase):
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,
+            help_url=self.help_url,
         )
 
     def get_last_complete_point(self, now: datetime | None = None) -> datetime:

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -179,6 +179,7 @@ class _RecoveryMixin(_OrchestratorBase):
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,
+            help_url=self.help_url,
             # Echo the rule that had fired so the recovery message names the
             # same alert condition that just cleared.
             min_detectors=self.conditions.min_detectors,

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -151,6 +151,34 @@ gets an inline "Open dashboard" link, and email gets an "Open dashboard" button.
 `links` adds extra `label: url` entries alongside it. Both are also exposed to
 custom templates — see `{dashboard_url}` / `{dashboard_line}` below.
 
+## "How to read this alert" link
+
+Every **default-rendered** alert (anomaly / recovery / no-data / error) on
+**every** channel carries a `How to read this alert` link pointing non-operator
+stakeholders to a plain-language interpretation guide. It defaults to the
+official detectkit guide (`https://dtk.pipelab.dev/guides/reading-alerts/`) — no
+config needed. Control it project-wide with `alert_help_url` in
+`detectkit_project.yml` (tri-state, see `project.md`):
+
+- **unset / null** → the official detectkit guide (default URL above)
+- **a URL string** → your own runbook/wiki page instead
+- **`false`** → hide the link entirely
+
+Per-channel rendering (defaults only; resolved by
+`ProjectConfig.resolve_alert_help_url`):
+
+- **Slack / Mattermost / generic webhook** — a bottom full-width attachment field
+  titled `How to read this alert` whose value is the bare URL (auto-linkified on
+  both platforms).
+- **Telegram** — appended to the links line (after the optional "Open dashboard"
+  link) as an `<a>` link reading `How to read this alert`.
+- **Email** — in the footer, after `Sent by detectkit · <project>` (and any CC),
+  a clay-colored `How to read this alert ->` link.
+
+Exposed to custom templates as `{help_url}` (raw URL, empty when unset/hidden)
+and `{help_line}` (`How to read this alert: <url>\n`, empty when unset/hidden) —
+mirrors `{dashboard_url}` / `{dashboard_line}`. See the template table below.
+
 ## How default messages render
 
 With no custom `template`, each channel renders a structured, branded message
@@ -243,6 +271,8 @@ referenced by path). Key variables:
 | `{mentions}` / `{mentions_line}` | formatted mentions |
 | `{dashboard_url}` | raw `dashboard_url` (empty string when unset) |
 | `{dashboard_line}` | `Dashboard: <url>\n` when set, else empty (appended to default plain-text templates) |
+| `{help_url}` | raw "How to read this alert" URL (empty when unset/hidden via `alert_help_url`) |
+| `{help_line}` | `How to read this alert: <url>\n` when set, else empty (mirrors `{dashboard_line}`) |
 
 > For no-data/error alerts there is no numeric value — avoid `{value:.2f}` in
 > those templates (detectkit falls back to the default template rather than

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/cli/assets/claude/rules/project.md

@@ -30,10 +30,31 @@ timeouts:                      # per-step, seconds
   detect: 7200                 # detect step (default 7200)
   alert: 300                   # alert step (default 300)
 
+alert_help_url: null           # optional, see below — "How to read this alert" link
+
 error_alerting:                # optional, see below
   enabled: false
 ```
 
+### `alert_help_url` — "How to read this alert" link
+
+Every default-rendered alert on every channel carries a `How to read this alert`
+link for non-operator stakeholders. Tri-state, resolved by
+`ProjectConfig.resolve_alert_help_url`:
+
+- **unset / null** (default) → the official detectkit guide
+  (`https://dtk.pipelab.dev/guides/reading-alerts/`).
+- **a URL string** → your own runbook/wiki page instead.
+- **`false`** → hide the link entirely.
+
+```yaml
+alert_help_url: https://wiki.ops/how-to-read-alerts   # custom page
+# alert_help_url: false                               # hide the link
+```
+
+Per-channel rendering and the `{help_url}` / `{help_line}` template variables are
+covered in `alerting.md` → "How to read this alert" link.
+
 ### `error_alerting` — project-scoped failure alerts
 
 Catches any exception from a metric's pipeline (DB down, query timeout, lock

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/cli/commands/test_alert.py

@@ -22,6 +22,7 @@ def create_mock_alert_data(
     metric_config: MetricConfig,
     alerting_config,
     timezone_display: str = "UTC",
+    help_url: str | None = None,
 ) -> AlertData:
     """
     Create realistic mock AlertData for testing.
@@ -33,6 +34,8 @@ def create_mock_alert_data(
             ``metric_config.alerting`` is a list — the test command
             iterates it and passes one entry at a time.
         timezone_display: Timezone for display
+        help_url: Resolved "how to read this alert" link to preview (the
+            project's ``alert_help_url``); ``None`` renders no help link.
 
     Returns:
         AlertData with mock anomaly data
@@ -89,6 +92,7 @@ def create_mock_alert_data(
         mentions=mentions,
         dashboard_url=getattr(alerting_config, "dashboard_url", None),
         links=dict(getattr(alerting_config, "links", {}) or {}),
+        help_url=help_url,
         min_detectors=min_detectors,
         direction_policy=direction_policy,
         consecutive_required=consecutive_required,
@@ -121,6 +125,12 @@ def run_test_alert(metric_name: str, profile: str | None = None):
 
     metrics_dir_name = project_data.get("metrics_path", "metrics")
 
+    # Resolve the "how to read this alert" link so the preview matches what real
+    # alerts would carry (brand default, a custom URL, or hidden via false).
+    from detectkit.config.project_config import resolve_alert_help_url
+
+    help_url = resolve_alert_help_url(project_data.get("alert_help_url"))
+
     # Find metric config
     metrics_dir = project_root / metrics_dir_name
     metric_files = list(metrics_dir.glob("**/*.yml")) + list(metrics_dir.glob("**/*.yaml"))
@@ -176,7 +186,9 @@ def run_test_alert(metric_name: str, profile: str | None = None):
         print(f"   Timezone: {timezone_display}")
         print(f"   Channels: {', '.join(alerting_config.channels)}\n")
 
-        alert_data = create_mock_alert_data(metric_config, alerting_config, timezone_display)
+        alert_data = create_mock_alert_data(
+            metric_config, alerting_config, timezone_display, help_url=help_url
+        )
 
         success_count = 0
         for channel_name in alerting_config.channels:

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/config/project_config.py

@@ -9,6 +9,26 @@ from pathlib import Path
 from pydantic import BaseModel, Field, field_validator
 
 
+def resolve_alert_help_url(value: "str | bool | None") -> "str | None":
+    """Resolve a raw ``alert_help_url`` config value to a concrete URL or None.
+
+    Shared by :meth:`ProjectConfig.resolve_alert_help_url` and the ``dtk
+    test-alert`` preview (which reads the project YAML as a raw dict), so the
+    tri-state rule lives in one place:
+
+    - ``False`` → ``None`` (the link is hidden).
+    - a non-empty string → that URL (a custom runbook/wiki page).
+    - ``None`` / ``True`` / empty → the official detectkit guide.
+    """
+    from detectkit.alerting.channels.branding import BRAND_ALERT_GUIDE_URL
+
+    if value is False:
+        return None
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return BRAND_ALERT_GUIDE_URL
+
+
 class ProjectPathsConfig(BaseModel):
     """
     Project directory paths configuration.
@@ -161,6 +181,44 @@ class ProjectConfig(BaseModel):
         default=None,
         description="Project-level error alerting (DB outages, query failures, etc.)",
     )
+    # "How to read this alert" link surfaced on every default-rendered alert so
+    # stakeholders (PMs, analysts, on-call) can click through to a plain-language
+    # explanation of what they're seeing. Tri-state:
+    #   - unset / None  → the official detectkit guide (brand default)
+    #   - a URL string  → your own runbook/wiki page instead
+    #   - false         → hide the link entirely
+    # Resolved via ``resolve_alert_help_url()`` and stamped onto ``AlertData``.
+    alert_help_url: str | bool | None = Field(
+        default=None,
+        description=(
+            "Link to a guide explaining how to read an alert, shown on every "
+            "alert. Defaults to the official docs; set a URL for your own page, "
+            "or false to hide it."
+        ),
+    )
+
+    @field_validator("alert_help_url")
+    @classmethod
+    def validate_alert_help_url(cls, v: "str | bool | None") -> "str | bool | None":
+        """A string override must look like an http(s) URL; ``True`` means default."""
+        if isinstance(v, str):
+            v = v.strip()
+            if not v:
+                return None  # empty string behaves like "use the default"
+            if not (v.startswith("http://") or v.startswith("https://")):
+                raise ValueError(
+                    "alert_help_url must be an http(s) URL, false (to hide), "
+                    "or unset (to use the default)"
+                )
+        return v
+
+    def resolve_alert_help_url(self) -> str | None:
+        """Resolve the configured ``alert_help_url`` to a concrete URL or None.
+
+        Defaults to the official detectkit guide; a string redirects to your own
+        page; ``false`` hides the link. See :func:`resolve_alert_help_url`.
+        """
+        return resolve_alert_help_url(self.alert_help_url)
 
     @field_validator("name")
     @classmethod

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/orchestration/error_dispatch.py

@@ -74,6 +74,11 @@ def dispatch_project_error_alert(
             )
             return False
 
+        # Resolve the project-level "how to read this alert" link (brand default
+        # unless overridden / disabled); duck-typed for stub configs in tests.
+        help_resolver = getattr(project_config, "resolve_alert_help_url", None)
+        help_url = help_resolver() if callable(help_resolver) else None
+
         alert_data = AlertData(
             metric_name=metric_name,
             timestamp=np.datetime64(now_utc_naive(), "ms"),
@@ -93,6 +98,7 @@ def dispatch_project_error_alert(
             description=None,
             mentions=cfg.mentions,
             project_name=getattr(project_config, "name", None),
+            help_url=help_url,
         )
 
         click.echo(

{detectkit-0.15.0 → detectkit-0.16.0}/detectkit/orchestration/task_manager/_alert_step.py

@@ -48,6 +48,12 @@ class _AlertStepMixin(_TaskManagerBase):
             click.echo("  │ Checking alert conditions...")
             alert_config_id = make_alert_config_id(alerting_config)
 
+            # Resolve the project-level "how to read this alert" link once per
+            # alert config (brand default unless overridden / disabled). Duck-typed
+            # so a stub project_config in tests without the resolver stays safe.
+            help_resolver = getattr(self.project_config, "resolve_alert_help_url", None)
+            help_url = help_resolver() if callable(help_resolver) else None
+
             orchestrator = AlertOrchestrator(
                 metric_name=config.name,
                 interval=interval,
@@ -65,6 +71,7 @@ class _AlertStepMixin(_TaskManagerBase):
                 dashboard_url=alerting_config.dashboard_url,
                 links=alerting_config.links,
                 project_name=getattr(self.project_config, "name", None),
+                help_url=help_url,
             )
 
             last_point = orchestrator.get_last_complete_point()

{detectkit-0.15.0 → detectkit-0.16.0/detectkit.egg-info}/PKG-INFO

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