detectkit 0.46.0__tar.gz → 0.47.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.46.0
+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.46.0 → 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.46.0"
+__version__ = "0.47.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.46.0 → 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.46.0 → 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.46.0 → 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.46.0 → 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.46.0 → 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.46.0 → detectkit-0.47.0}/detectkit/cli/assets/claude/rules/alerting.md

@@ -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.46.0 → 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

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

@@ -13,6 +13,9 @@ description: API p95 latency   # optional, shown in alerts
 profile: prod                  # optional, overrides project default_profile
 enabled: true                  # optional, false → skipped by `dtk run`
 tags: [critical, api]          # optional, used by `--select tag:<t>`
+ai_context:                    # optional — OSI-compatible grounding (descriptive only)
+  instructions: "p95 API latency, ms; user-facing"
+  synonyms: ["api latency", "response time"]
 
 interval: 5min                 # required — point spacing on the time grid
 
@@ -63,6 +66,19 @@ false_alert_budget: 0.3        # optional — `dtk tune` target false-alert rate
 project-wide default; unset → project, then a built-in `0.5`. Tuning-only — it never
 affects the load/detect/alert pipeline.
 
+`ai_context` is **OSI-compatible grounding** you can add to any metric with **no
+OSI model needed** — the metric's business meaning (`instructions`), alternative
+names (`synonyms`) and example values (`examples`), mirroring the
+[Open Semantic Interchange](https://github.com/open-semantic-interchange/OSI)
+`ai_context` shape so a metric's meaning is portable to/from an OSI semantic model.
+Accepts a bare string (→ `instructions`) or the full mapping. It is **purely
+descriptive**: it never affects load/detect/alert or the detector id, and it does
+**not** change any default-rendered alert. The `synonyms` are exposed to alert
+templates as the **opt-in** `{synonyms}` / `{synonyms_line}` variables (a custom
+`template` can add an "Also known as: …" line), and the whole block is carried in
+the `dtk tune` cockpit payload as read-only grounding. Omit it and everything
+renders as before.
+
 ## `interval` (required)
 
 Point spacing. String (`"30s"`, `"1min"`, `"5min"`, `"10min"`, `"1hour"`,

detectkit-0.47.0/detectkit/cli/commands/osi.py

@@ -0,0 +1,245 @@
+"""``dtk osi`` — Open Semantic Interchange interop (import / export / compile).
+
+A self-contained, additive command group. It never runs the pipeline, takes no
+lock, and touches no internal table:
+
+- ``dtk osi import`` scaffolds a native detectkit metric from an OSI model metric
+  (review the output, then commit it like any hand-written metric).
+- ``dtk osi export`` publishes detectkit metrics into an OSI fragment (a one-way
+  carrier: the full config rides in ``custom_extensions[detectkit]``; ``import``
+  does not reconstruct from it).
+- ``dtk osi compile`` prints just the SQL an import would generate (for review).
+
+Needs the optional ``[osi]`` extra (sqlglot) only for the ClickHouse target.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+
+
+@click.group()
+def osi() -> None:
+    """Open Semantic Interchange (OSI) interop: import / export / compile metrics."""
+
+
+def _split_csv(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    items = [v.strip() for v in value.split(",") if v.strip()]
+    return items or None
+
+
+def _dump_metric_yaml(body: dict[str, Any], header: str) -> str:
+    """Render a metric body as YAML with a ``#`` provenance header (mirrors config_emitter)."""
+    text = yaml.safe_dump(body, sort_keys=False, allow_unicode=True, width=100)
+    return header + text
+
+
+def _import_header(result: Any, model_file: Path) -> str:
+    lines = [
+        "# Generated by `dtk osi import` — review before committing.",
+        f"# Source OSI model: {model_file}",
+        f"# Metric: {result.metric_name}  ·  target: {result.target}  ·  "
+        f"sql-fingerprint: {result.fingerprint}",
+        "# detectkit resumes from the last datapoint, so if you re-import and this",
+        "# fingerprint changes, backfill/clean to avoid mixing definitions.",
+    ]
+    for w in result.warnings:
+        lines.append(f"# NOTE: {w}")
+    return "\n".join(lines) + "\n"
+
+
+@osi.command(name="import")
+@click.argument("model_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--metric", "-m", required=True, help="OSI metric name to import")
+@click.option("--interval", "-i", required=True, help="Series grain (e.g. 1h, 10min, 3600)")
+@click.option(
+    "--target",
+    type=click.Choice(["clickhouse", "cube"]),
+    default="clickhouse",
+    show_default=True,
+    help="clickhouse = direct SQL from dataset.source; cube = Cube SQL-API (MEASURE)",
+)
+@click.option("--dataset", help="OSI dataset to build FROM (default: the model's only dataset)")
+@click.option("--time-field", help="Time grain column / dimension (default: a field with is_time)")
+@click.option("--where", help="Extra SQL predicate (ANSI) added to the WHERE clause")
+@click.option("--cube", help="Cube name (cube target)")
+@click.option("--cube-measure", help="Cube measure name (cube target; default: the metric name)")
+@click.option("--time-dimension", help="Cube time dimension (cube target)")
+@click.option("--seasonality", help="Comma-separated time-derived seasonality columns")
+@click.option("--detector", default="mad", show_default=True, help="Starter detector type")
+@click.option(
+    "--out",
+    "-o",
+    type=click.Path(path_type=Path),
+    help="Write the metric YAML here (a dir → <name>.yml). Default: print to stdout.",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing --out file")
+def import_(
+    model_file: Path,
+    metric: str,
+    interval: str,
+    target: str,
+    dataset: str | None,
+    time_field: str | None,
+    where: str | None,
+    cube: str | None,
+    cube_measure: str | None,
+    time_dimension: str | None,
+    seasonality: str | None,
+    detector: str,
+    out: Path | None,
+    force: bool,
+) -> None:
+    """Scaffold a native detectkit metric from an OSI MODEL_FILE metric."""
+    from detectkit.semantic import OsiError, import_osi_metric, load_osi_models
+
+    try:
+        models = load_osi_models(model_file)
+        result = import_osi_metric(
+            models=models,
+            metric_name=metric,
+            interval=interval,
+            target=target,
+            dataset=dataset,
+            time_field=time_field,
+            where=where,
+            cube=cube,
+            cube_measure=cube_measure,
+            time_dimension=time_dimension,
+            seasonality=_split_csv(seasonality),
+            detector_type=detector,
+        )
+    except OsiError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    rendered = _dump_metric_yaml(result.metric, _import_header(result, model_file))
+
+    if out is None:
+        click.echo(rendered)
+        click.echo("# (printed only — pass --out to write a metric file)", err=True)
+        return
+
+    dest = out / f"{result.metric_name}.yml" if out.is_dir() else out
+    if dest.exists() and not force:
+        raise click.ClickException(f"{dest} exists — pass --force to overwrite")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(rendered)
+    click.echo(f"Wrote {dest}")
+    for w in result.warnings:
+        click.echo(f"  note: {w}")
+
+
+@osi.command()
+@click.argument("model_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--metric", "-m", required=True, help="OSI metric name")
+@click.option("--interval", "-i", required=True, help="Series grain (e.g. 1h, 10min, 3600)")
+@click.option("--target", type=click.Choice(["clickhouse", "cube"]), default="clickhouse")
+@click.option("--dataset", help="OSI dataset to build FROM")
+@click.option("--time-field", help="Time grain column / dimension")
+@click.option("--where", help="Extra SQL predicate (ANSI)")
+@click.option("--cube", help="Cube name (cube target)")
+@click.option("--cube-measure", help="Cube measure name (cube target)")
+@click.option("--time-dimension", help="Cube time dimension (cube target)")
+def compile(  # noqa: A001 - mirrors the `dtk osi compile` verb
+    model_file: Path,
+    metric: str,
+    interval: str,
+    target: str,
+    dataset: str | None,
+    time_field: str | None,
+    where: str | None,
+    cube: str | None,
+    cube_measure: str | None,
+    time_dimension: str | None,
+) -> None:
+    """Print ONLY the SQL an import would generate (no file written)."""
+    from detectkit.semantic import OsiError, import_osi_metric, load_osi_models
+
+    try:
+        models = load_osi_models(model_file)
+        result = import_osi_metric(
+            models=models,
+            metric_name=metric,
+            interval=interval,
+            target=target,
+            dataset=dataset,
+            time_field=time_field,
+            where=where,
+            cube=cube,
+            cube_measure=cube_measure,
+            time_dimension=time_dimension,
+        )
+    except OsiError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(result.sql)
+
+
+@osi.command()
+@click.option(
+    "--select", "-s", "selector", help="Metric selector (name / path / tag:<t>); default: all"
+)
+@click.option("--model-name", default="detectkit_export", show_default=True, help="OSI model name")
+@click.option(
+    "--out",
+    "-o",
+    type=click.Path(path_type=Path),
+    help="Write the OSI YAML here. Default: print to stdout.",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing --out file")
+def export(selector: str | None, model_name: str, out: Path | None, force: bool) -> None:
+    """Export native detectkit metrics into an OSI fragment (config in custom_extensions)."""
+    from detectkit.cli.commands.run import find_project_root, select_metrics
+    from detectkit.config.validator import validate_project_metrics
+    from detectkit.semantic import export_models
+
+    root = find_project_root()
+    if root is None:
+        raise click.ClickException(
+            "not inside a detectkit project (no detectkit_project.yml found)"
+        )
+
+    try:
+        pairs = select_metrics(selector, root) if selector else validate_project_metrics(root)
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+    configs = [cfg for _, cfg in pairs]
+    if not configs:
+        raise click.ClickException("no metrics selected")
+
+    doc = export_models(configs, model_name=model_name)
+    rendered = yaml.safe_dump(doc, sort_keys=False, allow_unicode=True, width=100)
+    header = (
+        f"# Generated by `dtk osi export` — {len(configs)} metric(s).\n"
+        "# The portable measure is a placeholder; the exact detectkit definition\n"
+        "# (detectors, alerting, query) rides in custom_extensions[detectkit].\n"
+        "# One-way carrier: `dtk osi import` does not reconstruct from this block —\n"
+        "# keep your metric YAML as the source of truth.\n"
+    )
+    rendered = header + rendered
+
+    if out is None:
+        click.echo(rendered)
+        return
+    if out.exists() and not force:
+        raise click.ClickException(f"{out} exists — pass --force to overwrite")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(rendered)
+    click.echo(f"Wrote {out} ({len(configs)} metric(s))", err=False)
+    click.echo(
+        "  note: one-way carrier — `dtk osi import` does not reconstruct from "
+        "custom_extensions[detectkit]; keep your metric YAML as the source of truth.",
+        err=True,
+    )
+
+
+def run_osi() -> None:
+    """Entry shim (kept symmetric with other commands; the group is wired in main)."""
+    osi(standalone_mode=True)  # pragma: no cover
+    sys.exit(0)  # pragma: no cover

{detectkit-0.46.0 → detectkit-0.47.0}/detectkit/cli/main.py

@@ -515,5 +515,13 @@ def clean(select: str, orphaned_metrics: bool, execute: bool, yes: bool, profile
     )
 
 
+# OSI (Open Semantic Interchange) interop — a self-contained command group
+# (`dtk osi import` / `export` / `compile`). Isolated from the load/detect/alert
+# pipeline; its module only imports click/yaml at load time (sqlglot stays lazy).
+from detectkit.cli.commands.osi import osi as _osi_group  # noqa: E402
+
+cli.add_command(_osi_group)
+
+
 if __name__ == "__main__":
     cli()

{detectkit-0.46.0 → detectkit-0.47.0}/detectkit/config/metric_config.py

@@ -507,6 +507,59 @@ class AutoTuneConfig(BaseModel):
         return self
 
 
+class AiContextConfig(BaseModel):
+    """OSI-compatible AI grounding for a metric (purely descriptive).
+
+    Mirrors the OSI ``ai_context`` shape (``instructions`` / ``synonyms`` /
+    ``examples``) verbatim, so a metric's business meaning, alternative names and
+    example values are portable to and from an OSI semantic model (Open Semantic
+    Interchange). It is surfaced to humans and agents — synonyms ride into alerts
+    as an "Also known as" line, the whole block is baked into the ``dtk tune``
+    cockpit payload, and it is shipped to the assistant via ``dtk init-claude`` —
+    but it **never** affects the load/detect/alert pipeline or the detector id. A
+    metric with no ``ai_context`` behaves exactly as before.
+
+    Accepts either the full mapping or a bare string (lifted to ``instructions``):
+
+        ```yaml
+        ai_context: "Revenue recognized at order completion, net of refunds."
+        # or
+        ai_context:
+          instructions: "Revenue recognized at order completion, net of refunds."
+          synonyms: ["total revenue", "gross sales"]
+          examples: ["12030.50", "9821.00"]
+        ```
+    """
+
+    instructions: str | None = Field(
+        default=None,
+        description="Business meaning / how to interpret the metric (grounds humans + LLMs)",
+    )
+    synonyms: list[str] = Field(
+        default_factory=list,
+        description="Alternative names for the metric (grounding + the alert 'Also known as' line)",
+    )
+    examples: list[str] = Field(
+        default_factory=list,
+        description="Illustrative example values or phrasings (grounding only)",
+    )
+
+    @field_validator("synonyms", "examples")
+    @classmethod
+    def _clean_str_list(cls, v: list[str]) -> list[str]:
+        """Drop blank/whitespace-only entries (trimming each), preserving order and
+        de-duplicating, so a stray empty YAML entry can't leak a bare comma into the
+        rendered "Also known as" line."""
+        seen: set[str] = set()
+        cleaned: list[str] = []
+        for item in v:
+            s = str(item).strip()
+            if s and s not in seen:
+                seen.add(s)
+                cleaned.append(s)
+        return cleaned
+
+
 class MetricConfig(BaseModel):
     """
     Configuration for a single metric.
@@ -602,7 +655,7 @@ class MetricConfig(BaseModel):
         """Normalize alerting to list. Accepts single dict/AlertConfig (backward compat) or list."""
         if v is None:
             return None
-        if isinstance(v, (dict, AlertConfig)):
+        if isinstance(v, dict | AlertConfig):
             return [v]
         return v
 
@@ -612,6 +665,19 @@ class MetricConfig(BaseModel):
     autotune: AutoTuneConfig | None = Field(
         default=None, description="Optional auto-tuning constraints (for `dtk autotune`)"
     )
+    # OSI-compatible AI grounding (instructions/synonyms/examples). Descriptive
+    # only: surfaced in alerts (synonyms → "Also known as"), the `dtk tune`
+    # cockpit and assistant grounding, but never touches load/detect/alert or the
+    # detector id. Mirrors OSI's `ai_context` so a metric's meaning is portable to
+    # and from an OSI semantic model. Accepts a bare string (→ instructions).
+    ai_context: AiContextConfig | None = Field(
+        default=None,
+        description=(
+            "Optional OSI-compatible AI grounding (instructions/synonyms/examples). "
+            "Descriptive only — surfaced in alerts, the tune cockpit and assistant "
+            "grounding; never affects load/detect/alert or the detector id."
+        ),
+    )
     # Per-metric false-alert-rate (FDR) budget for manual tuning, overriding the
     # project-wide `false_alert_budget`. The `dtk tune` cockpit flags — non
     # intrusively — when the share of fired alerts that don't overlap a real
@@ -637,6 +703,15 @@ class MetricConfig(BaseModel):
             raise ValueError("false_alert_budget must be a fraction in (0, 1] (e.g. 0.3 = 30%)")
         return v
 
+    @field_validator("ai_context", mode="before")
+    @classmethod
+    def _accept_ai_context_string(cls, v: Any) -> Any:
+        """Allow ``ai_context: "free text"`` as shorthand for ``{instructions: ...}``,
+        mirroring OSI's ``ai_context`` which is itself either a string or a struct."""
+        if isinstance(v, str):
+            return {"instructions": v}
+        return v
+
     # Parsed interval (computed from string/int)
     _interval: Interval | None = None
 

{detectkit-0.46.0 → detectkit-0.47.0}/detectkit/orchestration/task_manager/_alert_step.py

@@ -68,6 +68,7 @@ class _AlertStepMixin(_TaskManagerBase):
                 alert_config=alerting_config,
                 description=config.description,
                 mentions=alerting_config.mentions,
+                ai_synonyms=(config.ai_context.synonyms if config.ai_context else None),
                 dashboard_url=alerting_config.dashboard_url,
                 links=alerting_config.links,
                 project_name=getattr(self.project_config, "name", None),

detectkit-0.47.0/detectkit/semantic/__init__.py

@@ -0,0 +1,41 @@
+"""OSI (Open Semantic Interchange) interop for detectkit.
+
+An **isolated, additive** layer: nothing in the load/detect/alert pipeline imports
+it, so it can never affect a running project. It powers the ``dtk osi`` command
+group only (import an OSI metric into a native detectkit metric; export detectkit
+metrics into an OSI fragment). sqlglot is an optional dependency (the ``[osi]``
+extra), imported lazily inside :mod:`detectkit.semantic.query_gen`.
+
+See ``.claude/rules/architecture.md`` ("Manual semantic interop") and
+``project_osi_detectkit_integration`` for the design.
+"""
+
+from __future__ import annotations
+
+from detectkit.semantic.errors import (
+    OsiDependencyMissing,
+    OsiError,
+    OsiParseError,
+    OsiUnsupportedMetric,
+)
+from detectkit.semantic.exporter import export_metric_to_osi, export_models
+from detectkit.semantic.importer import ImportResult, import_osi_metric
+from detectkit.semantic.osi_model import (
+    DETECTKIT_VENDOR,
+    OsiSemanticModel,
+    load_osi_models,
+)
+
+__all__ = [
+    "DETECTKIT_VENDOR",
+    "ImportResult",
+    "OsiDependencyMissing",
+    "OsiError",
+    "OsiParseError",
+    "OsiSemanticModel",
+    "OsiUnsupportedMetric",
+    "export_metric_to_osi",
+    "export_models",
+    "import_osi_metric",
+    "load_osi_models",
+]