detectkit 0.46.0__tar.gz → 0.48.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.46.0
+Version: 0.48.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.48.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.48.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.46.0 → detectkit-0.48.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.48.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.48.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.48.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.48.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.48.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.48.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`)
@@ -95,7 +97,14 @@ anomalies**) and the **y = 0** toggle — stay visible in every mode. The chart
 **zoomable** (scroll/drag + navigator strip) with a **"Points shown"** trim slider.
 Clicking **Apply** writes the chosen
 config back into the metric YAML **in place** (autotune, by contrast, writes a new
-`__tuned_<id>.yml` and never edits the original). Reads the metric's loaded
+`__tuned_<id>.yml` and never edits the original). Apply **merges** — it rewrites
+only the detector(s) you tuned and keeps every **other** detector unchanged, so a
+`manual_bounds` floor alongside a `mad` detector (and a `min_detectors: 2` alert)
+survives a retune. If a metric configures **more than one detector**, a **Tuning
+detector** picker in the Tune rail lets you choose which one to tune (the cockpit
+shows one band at a time); switching re-seeds every knob from that detector, and
+non-tunable detectors (`prophet`/`timesfm`) plus the ones you didn't touch are
+listed as "preserved on Apply". Reads the metric's loaded
 datapoints (run `dtk run --steps load` first if empty); the selector must resolve
 to a single metric.
 
@@ -153,8 +162,11 @@ relative to zero.
 
 Safe write-back: the config is validated before anything is written, the previous
 YAML is archived under `metrics/.history/<metric>/`, and only then is the metric
-overwritten. Takes **no pipeline lock** (it only edits a config file); re-run
-`dtk run` afterward to recompute detections under the new config.
+overwritten (the merge keeps your other detectors verbatim; the re-emitted header
+names what was updated vs preserved). The `.history/` archive is **not** discovered
+as a live metric, so a tuned metric never collides with its own snapshots as a
+"duplicate metric name". Takes **no pipeline lock** (it only edits a config file);
+re-run `dtk run` afterward to recompute detections under the new config.
 `--no-serve` writes a static read-only preview HTML instead (no write-back —
 **Save incidents** downloads the labels file); `--from` / `--to` bound the window;
 `--no-open` prints the URL without opening a browser.
@@ -193,6 +205,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.48.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.46.0 → detectkit-0.48.0}/detectkit/cli/assets/claude/skills/dtk-tune/SKILL.md

@@ -146,9 +146,17 @@ false-alert rate exceeds it (tuning-only; labeling stays optional).
 When the user is happy, they click **Apply to metric**. detectkit then, in order:
 **validates** the config (a bad/untunable config is rejected and **nothing is
 written**), **archives** the current YAML verbatim under
-`metrics/.history/<metric>/`, and **re-emits** the metric in place with the tuned
-detector (and updates the first alerting block's `consecutive_anomalies` if it has
-one). Applying ends the session; saving incidents does not.
+`metrics/.history/<metric>/`, and **re-emits** the metric in place, **merging** the
+tuned detector(s) back in (and updating the first alerting block's
+`consecutive_anomalies` if it has one). Applying ends the session; saving incidents
+does not. **Merge, not replace:** only the detector(s) the user tuned are
+rewritten; every other detector is kept **verbatim** — so a metric with a
+`manual_bounds` floor alongside a `mad` detector (and a `min_detectors: 2` alert)
+keeps both. When a metric has more than one detector, the Tune rail shows a
+**Tuning detector** picker to choose which one to tune. If the user asks to tune a
+metric that has several detectors, reassure them the others are preserved. (The
+`.history/` archive is not discovered as a live metric, so it never causes a
+"duplicate metric name" error.)
 
 ## Step 5 — Recompute under the new config
 

detectkit-0.48.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.48.0}/detectkit/cli/commands/run.py

@@ -12,7 +12,11 @@ import click
 from detectkit.config.metric_config import MetricConfig
 from detectkit.config.profile import ProfilesConfig
 from detectkit.config.project_config import ProjectConfig
-from detectkit.config.validator import validate_metric_uniqueness
+from detectkit.config.validator import (
+    discover_metric_files,
+    is_discoverable_metric_file,
+    validate_metric_uniqueness,
+)
 from detectkit.database.internal_tables import InternalTablesManager
 from detectkit.orchestration.error_dispatch import dispatch_project_error_alert
 from detectkit.orchestration.task_manager import PipelineStep, TaskManager
@@ -433,17 +437,16 @@ def select_metrics(selector: str, project_root: Path) -> list[tuple[Path, Metric
         if selector == "*":
             # "all metrics" — search recursively so nested metrics are included
             # (mirrors validate_project_metrics); a plain glob of "metrics/*"
-            # would only see the top level.
-            metric_paths = [p for sub in ("**/*.yml", "**/*.yaml") for p in metrics_dir.glob(sub)]
+            # would only see the top level. Excludes the metrics/.history/ archive.
+            metric_paths = discover_metric_files(metrics_dir)
         else:
             pattern = selector if selector.startswith("metrics/") else f"metrics/{selector}"
             # Keep only metric files: a bare glob also matches the `.gitkeep`
-            # stub created by `dtk init`, any other non-YAML files, and
-            # directories — all of which would crash the YAML parser.
+            # stub created by `dtk init`, any other non-YAML files, directories, and
+            # the metrics/.history/ archive dtk tune writes (whose snapshots keep the
+            # original name:) — all of which would crash the parser or collide on name.
             metric_paths = [
-                p
-                for p in project_root.glob(pattern)
-                if p.is_file() and p.suffix in (".yml", ".yaml")
+                p for p in project_root.glob(pattern) if is_discoverable_metric_file(p, metrics_dir)
             ]
     # Metric name selector
     else:
@@ -485,26 +488,25 @@ def find_metrics_by_tag(metrics_dir: Path, tag: str) -> list[Path]:
 
     matching_metrics = []
 
-    # Search both .yml and .yaml extensions (consistent with find_metric_by_name)
-    for pattern in ["**/*.yml", "**/*.yaml"]:
-        for metric_file in metrics_dir.glob(pattern):
-            try:
-                with open(metric_file) as f:
-                    config = yaml.safe_load(f)
-
-                if config and "tags" in config:
-                    if tag in config["tags"]:
-                        matching_metrics.append(metric_file)
-            except Exception as e:
-                # Warn about unparseable files but continue searching
-                click.echo(
-                    click.style(
-                        f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
-                        fg="yellow",
-                    ),
-                    err=True,
-                )
-                continue
+    # Live metric files only (excludes the metrics/.history/ archive).
+    for metric_file in discover_metric_files(metrics_dir):
+        try:
+            with open(metric_file) as f:
+                config = yaml.safe_load(f)
+
+            if config and "tags" in config:
+                if tag in config["tags"]:
+                    matching_metrics.append(metric_file)
+        except Exception as e:
+            # Warn about unparseable files but continue searching
+            click.echo(
+                click.style(
+                    f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            continue
 
     return matching_metrics
 
@@ -522,25 +524,24 @@ def find_metric_by_name(metrics_dir: Path, name: str) -> Path | None:
     """
     import yaml
 
-    # Search both .yml and .yaml extensions
-    for pattern in ["**/*.yml", "**/*.yaml"]:
-        for metric_file in metrics_dir.glob(pattern):
-            try:
-                with open(metric_file) as f:
-                    config = yaml.safe_load(f)
-
-                if config and config.get("name") == name:
-                    return metric_file
-            except Exception as e:
-                # Warn about unparseable files but continue searching
-                click.echo(
-                    click.style(
-                        f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
-                        fg="yellow",
-                    ),
-                    err=True,
-                )
-                continue
+    # Live metric files only (excludes the metrics/.history/ archive).
+    for metric_file in discover_metric_files(metrics_dir):
+        try:
+            with open(metric_file) as f:
+                config = yaml.safe_load(f)
+
+            if config and config.get("name") == name:
+                return metric_file
+        except Exception as e:
+            # Warn about unparseable files but continue searching
+            click.echo(
+                click.style(
+                    f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            continue
 
     return None