detectkit 0.14.0__tar.gz → 0.15.0__tar.gz

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

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

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

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

@@ -32,10 +32,14 @@ class AlertData:
         consecutive_count: Number of consecutive anomalies
         is_recovery: True for recovery notifications
         is_no_data: True for missing-data alerts (no_data_alert)
-        project_name: Optional ``detectkit_project.yml`` name. Surfaces
-            as ``{project_name}`` in templates and as a ``[name] `` prefix
-            in the default error title. Lets multiple projects share the
-            same alert channel without ambiguity.
+        project_name: Optional ``detectkit_project.yml`` name. Surfaces as
+            ``{project_name}`` / ``{project_name_prefix}`` in templates and, by
+            default, as a ``[name] `` prefix on every alert title/headline
+            (anomaly, recovery, no-data, error) plus a brand-paired footer
+            ("detectkit · name" on webhook/email). The detectkit pipeline stamps
+            it from the project config; direct-API callers leave it ``None`` and
+            render unchanged. Lets multiple projects share one alert channel —
+            keeping the default brand bot name + avatar — without ambiguity.
 
     Alert-rule fields (``min_detectors``, ``direction_policy``,
     ``consecutive_required``, ``detector_count``) describe *why the alert
@@ -450,7 +454,7 @@ class BaseAlertChannel(ABC):
             Default template string
         """
         return (
-            "🔴 Alert: {metric_name}\n"
+            "🔴 {project_name_prefix}Alert: {metric_name}\n"
             "{description_line}"
             "Quorum {detector_count}/{min_detectors} · "
             "direction {direction} (policy {direction_policy}) · "
@@ -476,7 +480,7 @@ class BaseAlertChannel(ABC):
             Default recovery template string
         """
         return (
-            "🟢 Alert cleared: {metric_name}\n"
+            "🟢 {project_name_prefix}Alert cleared: {metric_name}\n"
             "{description_line}"
             "The alert condition no longer holds — "
             "the metric is back within expected bounds.\n"
@@ -500,7 +504,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default title template string
         """
-        return "🔴 Alert: {metric_name}"
+        return "🔴 {project_name_prefix}Alert: {metric_name}"
 
     def get_default_recovery_title_template(self) -> str:
         """
@@ -509,7 +513,7 @@ class BaseAlertChannel(ABC):
         Returns:
             Default recovery title template string
         """
-        return "🟢 Alert cleared: {metric_name}"
+        return "🟢 {project_name_prefix}Alert cleared: {metric_name}"
 
     def get_default_no_data_template(self) -> str:
         """
@@ -519,7 +523,7 @@ class BaseAlertChannel(ABC):
         has no datapoint (no row OR row with NULL/NaN value).
         """
         return (
-            "🟡 No data for metric: {metric_name}\n"
+            "🟡 {project_name_prefix}No data for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
             "Status: query returned no datapoint for the latest interval\n"
@@ -529,12 +533,12 @@ class BaseAlertChannel(ABC):
 
     def get_default_no_data_title_template(self) -> str:
         """Get default title template for no-data alerts."""
-        return "🟡 No data: {metric_name}"
+        return "🟡 {project_name_prefix}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"
+            "🔵 {project_name_prefix}Pipeline failed for metric: {metric_name}\n"
             "{description_line}"
             "Time: {timestamp}\n"
             "Error: {error_type}: {error_message}\n"

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

@@ -74,7 +74,7 @@ class EmailChannel(BaseAlertChannel):
         smtp_username: str | None = None,
         smtp_password: str | None = None,
         use_tls: bool = True,
-        subject_template: str = "🔴 Alert: {metric_name}",
+        subject_template: str = "🔴 {project_name_prefix}Alert: {metric_name}",
         from_name: str = BRAND_USERNAME,
         template: str | None = None,
         **kwargs,
@@ -144,10 +144,18 @@ class EmailChannel(BaseAlertChannel):
         # 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)
-        # Strip CR/LF from the metric name before it reaches the Subject header
-        # so a metric name can never inject extra email headers.
+        # Strip CR/LF from the metric *and* project name before they reach the
+        # Subject header so neither can inject extra email headers. The project
+        # prefix ("[my_project] ") makes the inbox row distinguishable when
+        # several projects email the same address.
         subject_metric = alert_data.metric_name.replace("\r", " ").replace("\n", " ")
-        msg["Subject"] = self.subject_template.format(metric_name=subject_metric)
+        project_clean = (alert_data.project_name or "").replace("\r", " ").replace("\n", " ")
+        project_prefix = f"[{project_clean}] " if project_clean else ""
+        msg["Subject"] = self.subject_template.format(
+            metric_name=subject_metric,
+            project_name_prefix=project_prefix,
+            project_name=project_clean,
+        )
 
         # Attach both parts. In multipart/alternative the LAST part is the
         # preferred one, so HTML (the branded card) is shown when supported and
@@ -247,6 +255,8 @@ class EmailChannel(BaseAlertChannel):
             f'font-size:4px;background-color:{accent};">&nbsp;</td></tr>'
             # header: logo + wordmark + status pill
             f"{self._header_html(accent, pill)}"
+            # project eyebrow (small label above the metric, only when set)
+            f"{self._eyebrow_html(ctx['project_name'])}"
             # title
             f'<tr><td style="padding:6px 24px 2px 24px;font-family:{_SANS};font-size:22px;'
             f'font-weight:bold;color:{_INK};mso-line-height-rule:exactly;line-height:28px;">'
@@ -258,6 +268,17 @@ class EmailChannel(BaseAlertChannel):
             "</table></td></tr></table></body></html>"
         )
 
+    def _eyebrow_html(self, project_name: str) -> str:
+        """Small uppercase project label above the metric title (empty if unset)."""
+        if not project_name:
+            return ""
+        return (
+            f'<tr><td style="padding:10px 24px 0 24px;font-family:{_SANS};font-size:11px;'
+            f"font-weight:bold;letter-spacing:0.5px;color:{_FAINT};text-transform:uppercase;"
+            f'mso-line-height-rule:exactly;line-height:14px;">'
+            f"{html.escape(project_name)}</td></tr>"
+        )
+
     def _header_html(self, accent: str, pill: str) -> str:
         """Logo + wordmark (real text) + colored status pill row."""
         return (
@@ -432,11 +453,16 @@ class EmailChannel(BaseAlertChannel):
     def _footer_html(self, alert_data: AlertData) -> str:
         cc = self.format_mentions(alert_data.mentions)
         cc_html = f" &middot; {html.escape(cc)}" if cc else ""
+        # Pair the brand with the project name ("Sent by detectkit · my_project")
+        # so the source project is clear even past the subject/eyebrow.
+        project_html = (
+            f" &middot; {html.escape(alert_data.project_name)}" if alert_data.project_name else ""
+        )
         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{cc_html}</td></tr>"
+            f"Sent by detectkit{project_html}{cc_html}</td></tr>"
         )
 
     def format_mentions(self, mentions: list[str]) -> str:

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

@@ -148,7 +148,12 @@ class TelegramChannel(BaseAlertChannel):
             return html.escape(str(value))
 
         metric = esc(ctx["metric_name"])
-        lines: list[str] = [f"{dot} <b>{word} · {metric}</b>"]
+        # Lead the headline with the project name (when set) so multiple
+        # projects sharing one chat stay distinguishable — Telegram has no
+        # footer/avatar override, so this prefix is the only project cue.
+        proj = ctx["project_name"]
+        head_prefix = f"[{esc(proj)}] " if proj else ""
+        lines: list[str] = [f"{dot} <b>{head_prefix}{word} · {metric}</b>"]
 
         if ctx["description"]:
             lines.append(f"<i>{esc(self._cap(ctx['description'], _DESC_CAP))}</i>")

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

@@ -189,8 +189,13 @@ class WebhookChannel(BaseAlertChannel):
             attachment["title_link"] = alert_data.dashboard_url
 
         # Brand the attachment footer (reliable on Slack even when top-level
-        # username/icon are locked to the app install).
-        attachment["footer"] = self.username or BRAND_USERNAME
+        # username/icon are locked to the app install). Pair the brand name with
+        # the project name when set ("detectkit · my_project") so two projects
+        # posting to the same channel stay distinguishable even past the title.
+        footer = self.username or BRAND_USERNAME
+        if alert_data.project_name:
+            footer = f"{footer} · {alert_data.project_name}"
+        attachment["footer"] = footer
         if self.icon_url:
             attachment["footer_icon"] = self.icon_url
         # Slack-only sugar: a real timestamp under the footer. Mattermost

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

@@ -25,6 +25,7 @@ class _OrchestratorBase:
         mentions: list[str] | None = None,
         dashboard_url: str | None = None,
         links: dict[str, str] | None = None,
+        project_name: str | None = None,
     ):
         self.metric_name = metric_name
         self.interval = interval
@@ -37,6 +38,11 @@ class _OrchestratorBase:
         self.mentions = mentions or []
         self.dashboard_url = dashboard_url
         self.links = links or {}
+        # Optional project name (``detectkit_project.yml`` ``name``). Stamped
+        # onto every AlertData so channels can label which project an alert
+        # came from — keeps multiple projects sharing one channel distinct
+        # while the bot keeps the default brand name + avatar.
+        self.project_name = project_name
 
     @staticmethod
     def _group_by_timestamp(

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

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

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

@@ -178,6 +178,7 @@ class _RecoveryMixin(_OrchestratorBase):
             mentions=self.mentions,
             dashboard_url=self.dashboard_url,
             links=self.links,
+            project_name=self.project_name,
             # 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.14.0 → detectkit-0.15.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -158,7 +158,9 @@ With no custom `template`, each channel renders a structured, branded message
 shared value computation lives in one place (`BaseAlertChannel.build_context`),
 so templates and native rendering stay consistent. Every alert title/headline
 leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-data,
-🔵 pipeline error — so the status reads from color alone.
+🔵 pipeline error — so the status reads from color alone. It also leads with the
+**project name** as a `[name] ` prefix (from `detectkit_project.yml`) — see
+[Project label](#project-label-multi-project-channels) below.
 
 - **Slack / Mattermost / generic webhook** — one message *attachment* with a
   status-colored accent bar, a clickable title (the metric; links to
@@ -181,6 +183,25 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
   table, a monospace params box, an optional "Open dashboard" button, and a
   footer. The plain-text body remains the multipart fallback.
 
+## Project label (multi-project channels)
+
+The bot keeps the **detectkit brand** name + avatar by default (so users rarely
+override them). To still tell apart two projects posting to the **same** channel,
+detectkit stamps the project name (`detectkit_project.yml` → `name`) onto every
+alert and shows it by default — no config needed:
+
+- **Title / headline / subject** lead with a `[name] ` prefix on every kind
+  (anomaly, recovery, no-data, error): `🔴 [payments] Alert: api_error_rate`.
+- **Webhook (Slack/Mattermost)** also pairs it in the footer: `detectkit · payments`.
+- **Telegram** carries it in the bold headline (no footer/avatar to override).
+- **Email** prefixes the subject, shows a small project eyebrow above the metric,
+  and pairs it in the footer (`Sent by detectkit · payments`).
+
+It is exposed to custom templates as `{project_name}` and `{project_name_prefix}`
+(`"[name] "` when set, else `""`). Direct library/API callers that don't set it
+render unchanged. The `name` is informational only (it does not key any `_dtk_*`
+table), so renaming it is safe — spaces are allowed for a prettier label.
+
 ## Multiple alert configs per metric
 
 `alerting:` may be a **list** of independent blocks, each with its own channels,
@@ -210,6 +231,7 @@ referenced by path). Key variables:
 | Variable | Meaning |
 |---|---|
 | `{metric_name}`, `{description}` / `{description_line}` | identity |
+| `{project_name}` / `{project_name_prefix}` | project label (`"[name] "` prefix, or `""`) |
 | `{timestamp}`, `{timezone}` | when (display tz via `alerting.timezone`, default UTC) |
 | `{value}` / `{value_display}` | metric value (`value_display` is NaN-safe) |
 | `{confidence_lower}` / `{confidence_upper}` / `{confidence_interval}` | bounds |

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

@@ -9,7 +9,9 @@ errors (not empty strings).
 ## `detectkit_project.yml`
 
 ```yaml
-name: my_monitoring            # required — project identifier (logs, error-alert titles)
+name: my_monitoring            # required — project identifier; also labels every
+                               # alert ("[my_monitoring] Alert: …") so multiple
+                               # projects on one channel stay distinct (alerting.md)
 version: "1.0"                 # optional (default "1.0")
 default_profile: prod          # profile name from profiles.yml
 
@@ -57,8 +59,10 @@ error_alerting:
   via cron cadence). Channel send failures are swallowed so a flaky webhook
   can't crash the run.
 - Extra template variables: `{error_type}`, `{error_message}`, `{status}`
-  (always `"ERROR"`), `{project_name}`, `{project_name_prefix}` (=
-  `"[<name>] "` when `name` set — keeps multi-project channels distinguishable).
+  (always `"ERROR"`). `{project_name}` / `{project_name_prefix}` (=
+  `"[<name>] "` when `name` set) are available here **and in every other alert
+  template** — and by default lead the title/headline on all channels, keeping
+  multi-project channels distinguishable (see `alerting.md` → Project label).
 
 ## `profiles.yml`
 

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

@@ -64,6 +64,7 @@ class _AlertStepMixin(_TaskManagerBase):
                 mentions=alerting_config.mentions,
                 dashboard_url=alerting_config.dashboard_url,
                 links=alerting_config.links,
+                project_name=getattr(self.project_config, "name", None),
             )
 
             last_point = orchestrator.get_last_complete_point()

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

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