detectkit 0.45.1__tar.gz → 0.47.0__tar.gz

{detectkit-0.45.1/detectkit.egg-info → detectkit-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.45.1
+Version: 0.47.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -47,12 +47,15 @@ Requires-Dist: timesfm>=0.1.0; extra == "timesfm"
 Provides-Extra: advanced-detectors
 Requires-Dist: prophet>=1.1.0; extra == "advanced-detectors"
 Requires-Dist: timesfm>=0.1.0; extra == "advanced-detectors"
+Provides-Extra: osi
+Requires-Dist: sqlglot>=20.0; extra == "osi"
 Provides-Extra: all
 Requires-Dist: clickhouse-driver>=0.2.0; extra == "all"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
 Requires-Dist: prophet>=1.1.0; extra == "all"
 Requires-Dist: timesfm>=0.1.0; extra == "all"
+Requires-Dist: sqlglot>=20.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -61,6 +64,7 @@ Requires-Dist: requests-mock>=1.12; extra == "dev"
 Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: sqlglot>=20.0; extra == "dev"
 Provides-Extra: integration
 Requires-Dist: testcontainers[clickhouse,mysql,postgres]>=4.0; extra == "integration"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "integration"

{detectkit-0.45.1 → detectkit-0.47.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.45.1"
+__version__ = "0.47.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/alerting/channels/base.py

@@ -72,6 +72,13 @@ class AlertData:
     error_message: str | None = None
     description: str | None = None
     mentions: list[str] = field(default_factory=list)
+    # OSI-compatible AI grounding: the metric's alternative names. Exposed to
+    # message templates as the OPT-IN ``{synonyms}`` / ``{synonyms_line}``
+    # variables (via :meth:`build_context`) so a custom template can surface an
+    # "Also known as: …" line — but the DEFAULT rendering deliberately does NOT
+    # show it, so existing alerts are byte-identical. Stamped by the orchestrator
+    # from ``MetricConfig.ai_context.synonyms``; defaults to empty.
+    ai_synonyms: 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
@@ -416,6 +423,14 @@ class BaseAlertChannel(ABC):
         # Format description line (empty string if no description)
         description_line = f"{alert_data.description}\n" if alert_data.description else ""
 
+        # OSI ai_context synonyms — the metric's alternative names. Provided as
+        # OPT-IN template variables only (``{synonyms}`` / ``{synonyms_line}``);
+        # the default templates do NOT reference them, so a metric without
+        # ai_context — and every existing alert — renders unchanged. A custom
+        # template can drop ``{synonyms_line}`` in to show "Also known as: …".
+        synonyms = ", ".join(alert_data.ai_synonyms) if alert_data.ai_synonyms else ""
+        synonyms_line = f"Also known as: {synonyms}\n" if synonyms else ""
+
         # Format mentions
         mentions_str = self.format_mentions(alert_data.mentions)
         mentions_line = f"\n{mentions_str}" if mentions_str else ""
@@ -482,6 +497,8 @@ class BaseAlertChannel(ABC):
             "error_message": alert_data.error_message or "",
             "description": alert_data.description or "",
             "description_line": description_line,
+            "synonyms": synonyms,
+            "synonyms_line": synonyms_line,
             "dashboard_url": dashboard_url,
             "dashboard_line": dashboard_line,
             "help_url": help_url,

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/alerting/channels/webhook.py

@@ -25,22 +25,23 @@ class WebhookChannel(BaseAlertChannel):
     - Slack incoming webhooks
     - Custom webhook endpoints
 
-    Rendering: the default (no custom ``template``) anomaly/recovery payload is
-    **two stacked Slack/Mattermost attachments** — a colored **base card** that
-    is always visible (the title, a short markdown lead with the **Rule** chip,
-    the Value / Expected fields and an always-visible compact **Links** field)
-    and a neutral **detail card** carrying the verbose tail (Quorum / Severity /
-    the anomalous span / Detectors / Parameters) as one markdown ``text`` block.
-    Slack and Mattermost natively collapse only an attachment's ``text`` (Slack
-    above 700 characters / 5 line breaks, Mattermost above ~200px of rendered
-    height) and **never** collapse the ``fields`` grid — so routing the bulk
-    into the detail card's ``text`` lets the platform fold it behind a
-    "Show more" toggle while the base (value, expected and links) stays in view.
-    Short kinds (no-data / error) render as a single base card. A custom
-    ``template`` degrades to a plain text-only attachment (one opaque string
-    that can't be sliced into fields), keeping the color, title and branding.
-    Branding (``footer`` + ``footer_icon``) rides on the **last** attachment so
-    it sits at the bottom of the whole message, below the folded detail card.
+    Rendering: the default (no custom ``template``) payload is a **single
+    status-colored Slack/Mattermost attachment** whose whole body rides in one
+    markdown ``text`` block, ordered most-important-first — the lead + **Rule**
+    chip, then Value / Expected, the action **Links**, and finally the verbose
+    evidence tail (Quorum / Severity / the anomalous span / Detectors /
+    Parameters). Both platforms natively collapse a long attachment ``text``
+    behind a **"Show more"** toggle (Slack above 700 characters / 5 line breaks;
+    Mattermost wraps only the ``text`` in its ``maxHeight`` 200px fold — the
+    ``title``, the color bar and the ``footer`` render *outside* that fold), so a
+    long anomaly folds its tail exactly like a reference AlertManager alert while
+    the one colored bar, the clickable title and the **branded footer (with the
+    logo)** stay in view even when the body is collapsed. No-data / error alerts
+    stay short, single un-folded cards; a long anomaly — or a full recovery
+    timeline (onset → fired → recovered) — folds its tail. A custom ``template``
+    renders the same shape — one colored, branded, text-only attachment.
+    Branding (``footer`` + ``footer_icon``, the brand logo) rides on that single
+    attachment and, being outside the text fold, is always visible.
 
     Mentions ride in the **top-level** ``text`` (mentions inside attachments do
     not reliably notify on Slack). A ``dashboard_url`` makes the attachment
@@ -55,10 +56,16 @@ class WebhookChannel(BaseAlertChannel):
             "text": "<!here> ...",                      # mentions (top level)
             "channel": "#channel",                      # optional (Slack)
             "attachments": [
-                # base card — always visible (never folds; fields don't collapse)
-                {"color": ..., "title": ..., "fields": [Value, Expected, Links], ...},
-                # detail card — neutral, foldable text (anomaly/recovery only)
-                {"text": "<verbose tail>", "mrkdwn_in": ["text"]},
+                # one colored card; the long body folds behind "Show more",
+                # the footer (brand + logo) stays visible below the fold.
+                {
+                    "color": ...,
+                    "title": ...,
+                    "text": "<lead + Rule + value/expected + links + tail>",
+                    "footer": "detectkit · <project>",
+                    "footer_icon": "https://.../bot-icon.png",
+                    "mrkdwn_in": ["text"],
+                },
             ]
         }
 
@@ -134,8 +141,9 @@ class WebhookChannel(BaseAlertChannel):
         Args:
             alert_data: Alert data to send
             template: Optional custom message template. When given, the
-                attachment carries the formatted template as a single text
-                blob (no fields grid); otherwise the rich default is built.
+                attachment carries the formatted template verbatim as the body
+                text (in place of the structured lead/Value/tail sections);
+                otherwise the rich default is built.
 
         Returns:
             True if sent successfully, False otherwise
@@ -199,16 +207,18 @@ class WebhookChannel(BaseAlertChannel):
         else:
             attachments = self._build_rich_attachments(alert_data, ctx, color, title)
 
-        # Dashboard link → clickable title on the base (first) attachment.
+        # Dashboard link → clickable title on the attachment.
         if alert_data.dashboard_url:
             attachments[0]["title_link"] = alert_data.dashboard_url
 
-        # Brand the LAST attachment's footer (reliable on Slack even when
-        # top-level username/icon are locked to the app install) so the brand
-        # line sits at the bottom of the whole message — below the folded detail
-        # card when one is present. 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.
+        # Brand the (single) attachment's footer (reliable on Slack even when
+        # top-level username/icon are locked to the app install). Mattermost and
+        # Slack render an attachment's footer *outside* the "Show more" text
+        # fold, so the brand line — and its logo (``footer_icon``) — stays
+        # visible at the bottom of the message even when the body is collapsed.
+        # 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}"
@@ -252,114 +262,131 @@ class WebhookChannel(BaseAlertChannel):
         color: str,
         title: str,
     ) -> list[dict[str, Any]]:
-        """Build the default attachment(s) for *alert_data*.
-
-        Returns a **base card** (always visible) and, for anomaly/recovery, a
-        neutral **detail card** whose long ``text`` block the chat client folds
-        behind "Show more". Slack and Mattermost collapse only an attachment's
-        ``text`` (never the ``fields`` grid), so the base keeps the value, the
-        expected band and the links permanently in view while the verbose tail
-        (quorum, severity, the anomalous span, detectors, parameters) rides in
-        the foldable detail card. No-data / error are short, so they render as a
-        single base card. Both cards render from one payload on Slack and
-        Mattermost.
+        """Build the default **single** attachment for *alert_data*.
+
+        Everything rides in one status-colored attachment whose body is a single
+        markdown ``text`` block, ordered most-important-first: the lead + Rule
+        chip, then value / expected, the action links, and finally the verbose
+        evidence tail (quorum, severity, the anomalous span, detectors,
+        parameters). Mattermost wraps only an attachment's ``text`` in its
+        "Show more" fold (``maxHeight`` 200px) and renders the ``title``, color
+        bar and ``footer`` outside it; Slack folds a long ``text`` too. So a long
+        anomaly collapses its tail behind "Show more" — exactly the one-block,
+        one-color, foldable layout of a reference AlertManager alert — while the
+        colored bar, the clickable title and the branded footer/logo (attached in
+        :meth:`build_payload`) stay in view even when collapsed. No-data / error
+        stay short, single un-folded cards; a long anomaly (or a full recovery
+        timeline) folds its tail.
         """
         kind = self.status_kind(alert_data)
-        base_fields: list[dict[str, Any]] = []
-        detail_lines: list[str] = []
-
-        def short(name: str, value: str) -> None:
-            """Add a 2-col field to the always-visible base card."""
-            if value:
-                base_fields.append({"title": name, "value": value, "short": True})
-
-        def full(name: str, value: str) -> None:
-            """Add a full-width field to the always-visible base card."""
-            if value:
-                base_fields.append({"title": name, "value": value, "short": False})
-
-        def detail(name: str, value: str) -> None:
-            """Add one line to the foldable detail card: bold label + value."""
-            if value:
-                detail_lines.append(f"{self._bold(name)} {value}")
 
         def code(s: str) -> str:
             return f"`{s}`" if s else ""
 
+        def line(name: str, value: str) -> str:
+            """One ``bold label + value`` body line (empty value → dropped)."""
+            return f"{self._bold(name)} {value}" if value else ""
+
         # The configured firing rule, set apart as a bold "Rule" label + an
         # inline-code chip so it reads as "this is the config that fired" at a
         # glance. Backticks render identically on Slack and Mattermost; the bold
-        # label is platform-aware (see ``_bold``). Stays in the always-visible
-        # base lead.
+        # label is platform-aware (see ``_bold``). Leads the body, above the fold.
         rule_chip = f"{self._bold('Rule')} " + code(
             f"min_detectors={ctx['min_detectors']} · "
             f"direction={ctx['direction_policy']} · "
             f"consecutive={ctx['consecutive_required']}"
         )
 
+        # Links — compact clickable labels (never raw URL strings: a Grafana URL
+        # can be a paragraph long once it carries variables), rendered in the
+        # platform's link syntax and joined by " · ". Kept high in the body so
+        # they stay above the fold and actionable at a glance. (The title is also
+        # a clickable dashboard link.)
+        link_parts: list[str] = []
+        if alert_data.dashboard_url:
+            link_parts.append(self._link_markup(alert_data.dashboard_url, "Dashboard"))
+        for label, url in alert_data.links.items():
+            link_parts.append(self._link_markup(url, label))
+        if ctx["help_url"]:
+            link_parts.append(self._link_markup(ctx["help_url"], ctx["help_label"]))
+        links_line = line("Links", " · ".join(link_parts)) if link_parts else ""
+
+        # The body is built as sections joined by a blank line; the verbose tail
+        # is last so the platform fold hides it first.
+        sections: list[list[str]] = []
         if kind == "anomaly":
-            # Base (always visible): the lead (how long it's been going on), the
-            # Rule chip, and the value vs the expected band.
-            lead = f"{ctx['anomaly_lead']}\n{rule_chip}"
-            short("Value", code(ctx["value_display"]))
-            short("Expected", code(ctx["expected_range"]))
-            # Detail (folds): quorum, severity, the span, detectors + params.
-            detail(
-                "Quorum",
-                f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}",
+            sections.append([ctx["anomaly_lead"], rule_chip])
+            sections.append(
+                [
+                    line("Value", code(ctx["value_display"])),
+                    line("Expected", code(ctx["expected_range"])),
+                    links_line,
+                ]
             )
-            detail("Severity", f"{alert_data.severity:.2f}")
+            tail = [
+                line(
+                    "Quorum",
+                    f"{ctx['detector_count']}/{ctx['min_detectors']} · {ctx['direction']}",
+                ),
+                line("Severity", f"{alert_data.severity:.2f}"),
+            ]
             if ctx["started_display"]:
-                detail("Anomaly began", ctx["started_display"])
-                detail("Latest reading", ctx["timestamp"])
+                tail.append(line("Anomaly began", ctx["started_display"]))
+                tail.append(line("Latest reading", ctx["timestamp"]))
             else:
-                detail("Detected at", ctx["timestamp"])
-            detail("Detectors", code(ctx["detector_name"]))
+                tail.append(line("Detected at", ctx["timestamp"]))
+            tail.append(line("Detectors", code(ctx["detector_name"])))
             if ctx["detector_params"]:
                 # Fenced block on its own lines so it renders as a code block (and
                 # adds line breaks that help trip the platform's fold).
-                detail_lines.append(
-                    f"{self._bold('Parameters')}\n```\n{ctx['detector_params']}\n```"
-                )
+                tail.append(f"{self._bold('Parameters')}\n```\n{ctx['detector_params']}\n```")
+            sections.append(tail)
         elif kind == "recovery":
-            lead = f"{ctx['recovery_lead']}\n{rule_chip}"
-            short("Value", code(ctx["value_display"]))
-            short("Expected", code(ctx["expected_range"]))
-            # Detail (folds): the incident timeline (onset → fired → recovered)
-            # and the detectors. ``detail`` skips the fired line when unknown.
+            sections.append([ctx["recovery_lead"], rule_chip])
+            sections.append(
+                [
+                    line("Value", code(ctx["value_display"])),
+                    line("Expected", code(ctx["expected_range"])),
+                    links_line,
+                ]
+            )
+            # The incident timeline (onset → fired → recovered) + detectors;
+            # ``line`` drops the fired entry when unknown.
             if ctx["started_display"]:
-                detail("Anomaly began", ctx["started_display"])
-                detail("Alert fired", ctx["fired_display"])
-                detail("Recovered", ctx["timestamp"])
+                tail = [
+                    line("Anomaly began", ctx["started_display"]),
+                    line("Alert fired", ctx["fired_display"]),
+                    line("Recovered", ctx["timestamp"]),
+                ]
             else:
-                detail("Cleared at", ctx["timestamp"])
-            detail("Detectors", code(ctx["detector_name"]))
+                tail = [line("Cleared at", ctx["timestamp"])]
+            tail.append(line("Detectors", code(ctx["detector_name"])))
+            sections.append(tail)
         elif kind == "no_data":
-            lead = "Query returned no datapoint for the latest expected interval."
-            full("Expected at", ctx["timestamp"])
-            short("Expected", code(ctx["expected_range"]))
+            sections.append(["Query returned no datapoint for the latest expected interval."])
+            sections.append(
+                [
+                    line("Expected at", ctx["timestamp"]),
+                    line("Expected", code(ctx["expected_range"])),
+                    links_line,
+                ]
+            )
         else:  # error
-            lead = "The detectkit pipeline failed for this metric."
-            full("Detected at", ctx["timestamp"])
             err = f"{ctx['error_type']}: {ctx['error_message']}".strip(": ")
-            full("Error", code(err))
-
-        # Links — always visible in the base card. The dashboard / "how to read
-        # this alert" links are actionable, so they never fold. Every entry is a
-        # compact clickable label, never a raw URL string (a Grafana URL can be a
-        # paragraph long once it carries variables; nobody should read that in an
-        # alert), rendered in the platform's link syntax and joined by " · " on a
-        # single line to stay compact. (The title is also a clickable dashboard
-        # link.)
-        link_parts = []
-        if alert_data.dashboard_url:
-            link_parts.append(self._link_markup(alert_data.dashboard_url, "Dashboard"))
-        for label, url in alert_data.links.items():
-            link_parts.append(self._link_markup(url, label))
-        if ctx["help_url"]:
-            link_parts.append(self._link_markup(ctx["help_url"], ctx["help_label"]))
-        if link_parts:
-            full("Links", " · ".join(link_parts))
+            sections.append(["The detectkit pipeline failed for this metric."])
+            sections.append(
+                [
+                    line("Detected at", ctx["timestamp"]),
+                    line("Error", code(err)),
+                    links_line,
+                ]
+            )
+
+        text = "\n\n".join(
+            "\n".join(entry for entry in section if entry)
+            for section in sections
+            if any(entry for entry in section)
+        )
 
         # A plain-text one-liner for notification previews / unsupported clients.
         if kind == "no_data":
@@ -372,26 +399,15 @@ class WebhookChannel(BaseAlertChannel):
                 f"(expected {ctx['expected_range']}) at {ctx['timestamp']}"
             )
 
-        base: dict[str, Any] = {
-            "fallback": fallback,
-            "color": color,
-            "title": title,
-            "text": lead,
-            "fields": base_fields,
-            "mrkdwn_in": ["text", "fields"],
-        }
-        attachments: list[dict[str, Any]] = [base]
-        # Detail card: neutral (no color bar) so it reads as a continuation of
-        # the base rather than a second alert, with the verbose tail in one
-        # foldable ``text`` block.
-        if detail_lines:
-            attachments.append(
-                {
-                    "text": "\n".join(detail_lines),
-                    "mrkdwn_in": ["text"],
-                }
-            )
-        return attachments
+        return [
+            {
+                "fallback": fallback,
+                "color": color,
+                "title": title,
+                "text": text,
+                "mrkdwn_in": ["text"],
+            }
+        ]
 
     def _bold(self, text: str) -> str:
         """Render *text* bold in the target platform's markdown.

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/alerting/orchestrator/_base.py

@@ -36,6 +36,7 @@ class _OrchestratorBase:
         links: dict[str, str] | None = None,
         project_name: str | None = None,
         help_url: str | None = None,
+        ai_synonyms: list[str] | None = None,
     ):
         self.metric_name = metric_name
         self.interval = interval
@@ -57,6 +58,10 @@ class _OrchestratorBase:
         # 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
+        # OSI ai_context synonyms (the metric's alternative names). Stamped onto
+        # every AlertData so channels can render an "Also known as" identity line.
+        # Empty list when the metric has no ai_context — renders unchanged.
+        self.ai_synonyms = ai_synonyms or []
 
     @staticmethod
     def _group_by_timestamp(

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/alerting/orchestrator/_decision.py

@@ -280,6 +280,7 @@ class _DecisionMixin(_OrchestratorBase):
             consecutive_count=consecutive_count,
             description=self.description,
             mentions=self.mentions,
+            ai_synonyms=self.ai_synonyms,
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,
@@ -345,6 +346,7 @@ class _DecisionMixin(_OrchestratorBase):
             is_no_data=True,
             description=self.description,
             mentions=self.mentions,
+            ai_synonyms=self.ai_synonyms,
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -188,6 +188,7 @@ class _RecoveryMixin(_OrchestratorBase):
             is_recovery=True,
             description=self.description,
             mentions=self.mentions,
+            ai_synonyms=self.ai_synonyms,
             dashboard_url=self.dashboard_url,
             links=self.links,
             project_name=self.project_name,

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -40,6 +40,7 @@ version — **read the relevant one on demand** instead of guessing:
 | Alert rules (quorum/direction/consecutive), cooldown, recovery, templates | `.claude/rules/detectkit/alerting.md` |
 | Auto-tuning a detector (`dtk autotune`), labels file, the `autotune:` block, `_dtk_autotune_runs` | `.claude/rules/detectkit/autotune.md` |
 | Manually/interactively tuning a detector in the browser and writing it back in place (`dtk tune`) | `.claude/rules/detectkit/cli.md` |
+| OSI (Open Semantic Interchange) interop: import an OSI metric into a native metric / export back (`dtk osi`) | `.claude/rules/detectkit/cli.md` |
 
 ### Skills
 

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -167,7 +167,7 @@ config needed. Control it project-wide with `alert_help_url` in
 Per-channel rendering (defaults only; the resolved help URL is rendered per channel as follows):
 
 - **Slack / Mattermost / generic webhook** — a clickable `How to read this alert`
-  label in the compact `Links` field (alongside `Dashboard` + any extra links),
+  label in the compact `Links` line (alongside `Dashboard` + any extra links),
   never a raw URL. Rendered in the platform's link syntax (Slack `<url|label>`,
   Mattermost/generic markdown links) so a long dashboard URL stays hidden behind
   its label.
@@ -191,25 +191,25 @@ leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-
 **project name** as a `[name] ` prefix (from `detectkit_project.yml`) — see
 [Project label](#project-label-multi-project-channels) below.
 
-- **Slack / Mattermost / generic webhook** — an anomaly/recovery renders as
-  **two stacked attachments** so long alerts fold in the channel. Both platforms
-  collapse only an attachment's `text` block behind a "Show more" toggle (Slack
-  above 700 chars / 5 line breaks; Mattermost above ~200px) and never collapse
-  the `fields` grid, so the message splits into:
-  - an always-visible **base card** — status-colored accent bar, a clickable
-    title (the metric; links to `dashboard_url` when set), a short markdown lead
-    (the duration sentence — see "Incident timing" below) with the **Rule** chip
-    beneath it, and a compact fields grid kept to **Value / Expected** plus an
-    always-visible compact **Links** field (dashboard + extra links + the "how to
-    read this alert" guide as clickable labels);
-  - a neutral, foldable **detail card** — the verbose tail as one markdown
-    `text` block: Quorum / Severity / the anomalous span (Anomaly began → Latest
-    reading; began → fired → recovered on recovery) / Detectors / Parameters.
-
-  No-data / error stay a single base card. The branded footer + footer icon ride
-  on the **last** attachment. @mentions ride in the **top-level** message text so
-  they notify. A custom `template` instead renders as a single plain text-only
-  attachment (color/title/branding kept, no fields grid, no fold split).
+- **Slack / Mattermost / generic webhook** — an alert renders as **one
+  status-colored attachment** whose whole body is a single markdown `text` block,
+  ordered **most-important-first** so a long alert folds its tail behind a
+  **"Show more"** toggle — one block, one color, just like a reference
+  AlertManager alert. The body order: the clickable title (the metric; links to
+  `dashboard_url` when set), then the markdown lead (the duration sentence — see
+  "Incident timing" below) with the **Rule** chip beneath it, **Value /
+  Expected**, the compact **Links** line (dashboard + extra links + the "how to
+  read this alert" guide as clickable labels, never raw URLs), and finally the
+  verbose tail (Quorum / Severity / the anomalous span — Anomaly began → Latest
+  reading; began → fired → recovered on recovery — / Detectors / Parameters).
+  Both clients fold **only** the `text` (Slack above 700 chars / 5 line breaks;
+  Mattermost above ~200px) and render the title, the color bar and the **footer**
+  *outside* the fold — so the branded **footer + footer icon (the logo)** stays
+  visible even when the body is collapsed. No-data / error stay short, single
+  un-folded cards; a long anomaly (or a full recovery timeline) folds its tail.
+  @mentions ride in the **top-level** message text so they notify. A custom
+  `template` renders as a single plain text-only attachment (the raw template
+  replaces the structured lead/Value/tail sections; color/title/branding kept).
 - **Telegram** — default `parse_mode` is now **HTML**. The default message is
   structured and HTML-escaped: a colored status dot (red anomaly / green
   recovery / yellow no-data / blue error), a bold headline, the lead + rule, then
@@ -297,6 +297,7 @@ referenced by path). Key variables:
 | Variable | Meaning |
 |---|---|
 | `{metric_name}`, `{description}` / `{description_line}` | identity |
+| `{synonyms}` / `{synonyms_line}` | alt names from `ai_context.synonyms` (opt-in; not in default templates — add `{synonyms_line}` for an "Also known as: …" line) |
 | `{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) |

{detectkit-0.45.1 → detectkit-0.47.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -15,6 +15,8 @@ Run all commands from a project directory (the one containing
 | `dtk test-alert <metric>` | Send a mock alert to the metric's channels |
 | `dtk unlock --select <sel>` | Clear a stuck pipeline lock |
 | `dtk clean --select <sel>` | Prune internal data that no longer matches the config |
+| `dtk osi import <model>` | Scaffold a native metric from an OSI semantic-model metric (see "OSI interop") |
+| `dtk osi export` | Publish metrics into an OSI fragment (config in `custom_extensions[detectkit]`) |
 | `dtk --version` | Show installed detectkit version |
 
 ## Selectors (`--select` / `-s`)
@@ -193,6 +195,44 @@ actually delete.
   unless `-y/--yes`; refuses to run if the project defines no metrics or configs
   fail to parse (so a wrong directory can't wipe valid data).
 
+## OSI interop (`dtk osi`)
+
+`dtk osi` converts between [Open Semantic Interchange](https://github.com/open-semantic-interchange/OSI)
+(OSI) semantic models and native detectkit metrics. It's a **separate, additive**
+layer: it never runs the pipeline, takes no lock, and the converter package
+(`detectkit/semantic/`) is not imported by load/detect/alert — so it can't affect
+a running project. OSI is treated as an *interchange* format (define the KPI once,
+consume in BI + AI), not an execution engine. OSI adoption is still early, so the
+broadly-useful piece today is `ai_context` (see the metrics rule) — the converters
+are a forward bridge for teams that already run a governed semantic layer.
+
+- `dtk osi import <model.osi.yml> --metric <name> --interval <grain>` — the
+  "enhanced init": resolve one OSI metric and **scaffold a normal native metric**
+  (SQL `query`, interval, a starter detector, the metric's `ai_context`). Review
+  it, then commit like any hand-written metric. Targets:
+  - `--target clickhouse` (default) — a direct `toStartOfInterval(...) GROUP BY`
+    query from the dataset's physical `source` (ANSI→ClickHouse via **sqlglot**,
+    the optional `[osi]` extra: `pip install 'detectkit[osi]'`).
+  - `--target cube --cube <name> --time-field <dim>` — a Cube **SQL-API**
+    `MEASURE(...)` query, so the metric runs through Cube and the alert matches a
+    Cube dashboard's number by construction. Point its `profile` at a Postgres
+    connection on Cube's SQL port.
+- Only provably per-bucket-additive measures compile (`SUM`/`COUNT`/`COUNT(DISTINCT)`/
+  `AVG`/`MIN`/`MAX` + ratios like `SUM(x)/NULLIF(COUNT(DISTINCT y),0)`). Window
+  functions / non-aggregates / unknown aggregates are **refused** with a message
+  to use `query_file:` — never a plausible-but-wrong series.
+- `dtk osi compile <model> --metric <name> --interval <g>` prints just the SQL
+  (for review). `dtk osi export [--select <sel>]` writes an OSI fragment carrying
+  a lossless snapshot of the config in `custom_extensions[detectkit]` + the
+  `ai_context` — a **one-way carrier** (`import` does not reconstruct from it; the
+  metric YAML stays the source of truth).
+
+```bash
+dtk osi compile model.osi.yml -m total_sales -i 1h          # preview the SQL
+dtk osi import model.osi.yml -m total_sales -i 1h -o metrics/  # scaffold a metric
+dtk osi export -o semantic/detectkit.osi.yml                  # publish back to OSI
+```
+
 ## Common workflows
 
 ```bash