detectkit 0.57.0__tar.gz → 0.58.0__tar.gz

{detectkit-0.57.0/detectkit.egg-info → detectkit-0.58.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.57.0
+Version: 0.58.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -36,6 +36,8 @@ Provides-Extra: postgres
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "postgres"
 Provides-Extra: mysql
 Requires-Dist: pymysql>=1.0.0; extra == "mysql"
+Provides-Extra: mariadb
+Requires-Dist: pymysql>=1.0.0; extra == "mariadb"
 Provides-Extra: all-db
 Requires-Dist: clickhouse-driver>=0.2.0; extra == "all-db"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "all-db"

{detectkit-0.57.0 → detectkit-0.58.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.57.0"
+__version__ = "0.58.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/alerting/channels/webhook.py

@@ -5,6 +5,10 @@ Sends alerts to any webhook endpoint that accepts JSON payload.
 Compatible with Mattermost, Slack, and other webhook-based systems.
 """
 
+import hashlib
+import hmac
+import json
+import math
 from datetime import datetime, timezone
 from typing import Any
 
@@ -83,6 +87,17 @@ class WebhookChannel(BaseAlertChannel):
         channel (str): Target channel (optional, for Slack/Mattermost)
         timeout (int): Request timeout in seconds (default: 10)
         extra_headers (dict): Additional HTTP headers (optional)
+        format (str): Payload shape — "attachments" (default; today's
+            byte-identical Slack/Mattermost card), "json" (a structured event
+            payload, ``schema_version`` 1) or "alertmanager" (a Prometheus
+            Alertmanager webhook-receiver payload, version "4"). Any other
+            value raises ``ValueError`` at construction. A custom ``template``
+            passed to :meth:`send` is ignored for "json"/"alertmanager" —
+            those are structured formats with no free-text body.
+        secret (str): When set, every outgoing request (any format) is
+            HMAC-SHA256 signed GitHub-webhook style: header
+            ``X-Detectkit-Signature-256: sha256=<hexdigest>`` computed over
+            the exact request body bytes with *secret* as the key.
 
     Example:
         >>> # Mattermost
@@ -103,6 +118,8 @@ class WebhookChannel(BaseAlertChannel):
         ... )
     """
 
+    _FORMATS = ("attachments", "json", "alertmanager")
+
     def __init__(
         self,
         webhook_url: str,
@@ -112,10 +129,15 @@ class WebhookChannel(BaseAlertChannel):
         channel: str | None = None,
         timeout: int = 10,
         extra_headers: dict[str, str] | None = None,
+        format: str = "attachments",
+        secret: str | None = None,
     ):
         """Initialize webhook channel."""
         if not webhook_url:
             raise ValueError("webhook_url is required")
+        if format not in self._FORMATS:
+            allowed = ", ".join(self._FORMATS)
+            raise ValueError(f"Unknown webhook format: '{format}'. Allowed: {allowed}")
 
         self.webhook_url = webhook_url
         self.username = username
@@ -129,6 +151,8 @@ class WebhookChannel(BaseAlertChannel):
         self.channel = channel
         self.timeout = timeout
         self.extra_headers = extra_headers or {}
+        self.format = format
+        self.secret = secret
 
     def send(
         self,
@@ -140,10 +164,12 @@ class WebhookChannel(BaseAlertChannel):
 
         Args:
             alert_data: Alert data to send
-            template: Optional custom message template. When given, the
-                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.
+            template: Optional custom message template. Applies only to the
+                default "attachments" format, where the 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. Ignored for "json"/"alertmanager" — those
+                are structured formats with no free-text body.
 
         Returns:
             True if sent successfully, False otherwise
@@ -155,17 +181,31 @@ class WebhookChannel(BaseAlertChannel):
             >>> channel = WebhookChannel(webhook_url="https://...")
             >>> success = channel.send(alert_data)
         """
-        payload = self.build_payload(alert_data, template)
+        if self.format == "json":
+            payload = self.build_event_payload(alert_data)
+        elif self.format == "alertmanager":
+            payload = self.build_alertmanager_payload(alert_data)
+        else:
+            payload = self.build_payload(alert_data, template)
 
-        # Prepare headers
+        # Serialize ourselves (rather than letting ``requests`` do it via
+        # ``json=``) so the HMAC signature covers the exact bytes sent.
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
         headers = {"Content-Type": "application/json"}
         headers.update(self.extra_headers)
+        if self.format in ("json", "alertmanager"):
+            headers["X-Detectkit-Event"] = self.status_kind(alert_data)
+        if self.secret:
+            # GitHub-webhook style signature, computed AFTER extra_headers so
+            # a misconfigured extra header can't clobber it.
+            signature = hmac.new(self.secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
+            headers["X-Detectkit-Signature-256"] = f"sha256={signature}"
 
         # Send to webhook
         try:
             response = requests.post(
                 self.webhook_url,
-                json=payload,
+                data=body,
                 headers=headers,
                 timeout=self.timeout,
             )
@@ -405,6 +445,232 @@ class WebhookChannel(BaseAlertChannel):
             }
         ]
 
+    def _display_lead(self, alert_data: AlertData, ctx: dict[str, Any], kind: str) -> str:
+        """The plain-language lead sentence shared by both structured formats.
+
+        Anomaly/recovery reuse the same ready-made sentence the attachment
+        body leads with; no-data/error get a fixed one-liner (they have no
+        streak/duration story).
+        """
+        if kind == "anomaly":
+            return str(ctx["anomaly_lead"])
+        if kind == "recovery":
+            return str(ctx["recovery_lead"])
+        if kind == "no_data":
+            return "Query returned no datapoint for the latest expected interval."
+        return "The detectkit pipeline failed for this metric."
+
+    def build_event_payload(self, alert_data: AlertData) -> dict[str, Any]:
+        """Structured JSON event payload (``format="json"``).
+
+        ``schema_version`` 1 — **frozen**: this shape is a public contract for
+        downstream consumers (custom receivers, log pipelines), so existing
+        keys must not change meaning or disappear; only additive changes are
+        safe without bumping the version. Built from ``alert_data`` plus
+        :meth:`build_context` (the same resolved values every other rendering
+        surface — the attachment, Telegram, email — uses), so this event and
+        the human-readable message never disagree.
+        """
+        ctx = self.build_context(alert_data)
+        kind = self.status_kind(alert_data)
+        streak = alert_data.consecutive_count
+        interval_seconds = alert_data.interval_seconds
+        duration_seconds = streak * interval_seconds if interval_seconds is not None else None
+
+        return {
+            "schema_version": 1,
+            "source": "detectkit",
+            "kind": kind,
+            "status": "resolved" if alert_data.is_recovery else "firing",
+            "project": alert_data.project_name,
+            "metric": alert_data.metric_name,
+            "description": alert_data.description,
+            "timestamp": self._iso_utc(alert_data.timestamp),
+            "value": self._clean_float(alert_data.value),
+            "expected": {
+                "lower": self._bounded_value(alert_data.confidence_lower),
+                "upper": self._bounded_value(alert_data.confidence_upper),
+            },
+            "severity": self._clean_float(alert_data.severity),
+            "direction": alert_data.direction,
+            "detector": {
+                "name": alert_data.detector_name,
+                "params": self._parse_detector_params(alert_data.detector_params),
+            },
+            "rule": {
+                "min_detectors": ctx["min_detectors"],
+                "direction": ctx["direction_policy"],
+                "consecutive": ctx["consecutive_required"],
+                "window_points": alert_data.window_points,
+                "min_anomaly_share": alert_data.min_anomaly_share,
+                "fired_by_share": alert_data.fired_by_share,
+                "display": ctx["rule_display"],
+            },
+            "quorum": {
+                "detector_count": alert_data.detector_count,
+                "min_detectors": ctx["min_detectors"],
+            },
+            "incident": {
+                "onset": self._iso_utc(alert_data.onset_timestamp),
+                "streak": streak,
+                "capped": alert_data.streak_capped,
+                "interval_seconds": interval_seconds,
+                "duration_seconds": duration_seconds,
+            },
+            "links": {
+                "dashboard": alert_data.dashboard_url,
+                "help": ctx["help_url"] or None,
+                "extra": alert_data.links,
+            },
+            "mentions": alert_data.mentions,
+            "synonyms": alert_data.ai_synonyms,
+            "error": (
+                {"type": alert_data.error_type, "message": alert_data.error_message}
+                if kind == "error"
+                else None
+            ),
+            "display": {
+                "title": self.format_title(alert_data),
+                "lead": self._display_lead(alert_data, ctx, kind),
+                "value": ctx["value_display"],
+                "expected_range": ctx["expected_range"],
+                "timestamp": ctx["timestamp"],
+            },
+        }
+
+    def build_alertmanager_payload(self, alert_data: AlertData) -> dict[str, Any]:
+        """Prometheus Alertmanager webhook-receiver payload (``format="alertmanager"``).
+
+        Version "4" — **frozen** shape, same contract rationale as
+        :meth:`build_event_payload`. A recovery deliberately carries the
+        **same labels** as the anomaly it resolves (``kind`` maps back to
+        ``"anomaly"``) so Alertmanager-style consumers pair the two via
+        ``fingerprint`` — only ``status``/``endsAt`` differ.
+        """
+        ctx = self.build_context(alert_data)
+        kind = self.status_kind(alert_data)
+        is_recovery = alert_data.is_recovery
+
+        labels_kind = "anomaly" if is_recovery else kind
+        labels: dict[str, str] = {
+            "alertname": alert_data.metric_name,
+            "metric": alert_data.metric_name,
+            "kind": labels_kind,
+            "source": "detectkit",
+            "severity": "warning" if labels_kind == "no_data" else "critical",
+        }
+        if alert_data.project_name:
+            labels["project"] = alert_data.project_name
+
+        lead = self._display_lead(alert_data, ctx, kind)
+        annotations: dict[str, str] = {
+            "summary": self.format_title(alert_data),
+            "description": lead,
+        }
+        if kind in ("anomaly", "recovery"):
+            annotations["value"] = ctx["value_display"]
+            annotations["expected"] = ctx["expected_range"]
+        # Direction rides as an ANNOTATION, never a label: the orchestrator
+        # stamps recovery AlertData with direction="none", so a direction label
+        # would change the label set — and the fingerprint — between a firing
+        # alert and its recovery, breaking trigger/resolve pairing.
+        if kind == "anomaly" and alert_data.direction and alert_data.direction != "none":
+            annotations["direction"] = alert_data.direction
+
+        fingerprint = self._label_fingerprint(labels)
+        onset = (
+            alert_data.onset_timestamp
+            if alert_data.onset_timestamp is not None
+            else alert_data.timestamp
+        )
+        status = "resolved" if is_recovery else "firing"
+
+        alert = {
+            "status": status,
+            "labels": labels,
+            "annotations": annotations,
+            "startsAt": self._iso_utc(onset),
+            "endsAt": (
+                self._iso_utc(alert_data.timestamp) if is_recovery else "0001-01-01T00:00:00Z"
+            ),
+            "generatorURL": alert_data.dashboard_url or "",
+            "fingerprint": fingerprint,
+        }
+
+        return {
+            "version": "4",
+            "groupKey": f"detectkit/{alert_data.project_name or 'default'}/{alert_data.metric_name}",
+            "truncatedAlerts": 0,
+            "status": status,
+            "receiver": "detectkit",
+            "groupLabels": {"alertname": alert_data.metric_name},
+            "commonLabels": labels,
+            "commonAnnotations": annotations,
+            "externalURL": "",
+            "alerts": [alert],
+        }
+
+    @staticmethod
+    def _label_fingerprint(labels: dict[str, str]) -> str:
+        """Stable short hash of *labels*, sorted so key order never matters."""
+        label_str = "\n".join(f"{k}={v}" for k, v in sorted(labels.items()))
+        return hashlib.sha256(label_str.encode("utf-8")).hexdigest()[:16]
+
+    @staticmethod
+    def _clean_float(value: Any) -> float | None:
+        """``float(value)``, or ``None`` for a missing/NaN value."""
+        if value is None:
+            return None
+        if isinstance(value, float) and math.isnan(value):
+            return None
+        return float(value)
+
+    @staticmethod
+    def _bounded_value(bound: Any) -> float | None:
+        """A confidence bound as JSON, or ``None`` when unset/NaN/inf.
+
+        Mirrors ``BaseAlertChannel.build_context``'s ``_bounded`` check (a
+        NaN/inf bound means "no bound on that side", e.g. a one-sided
+        ManualBounds detector).
+        """
+        if bound is None or (isinstance(bound, float) and (math.isnan(bound) or math.isinf(bound))):
+            return None
+        return float(bound)
+
+    @staticmethod
+    def _parse_detector_params(raw: str) -> Any:
+        """Detector params as parsed JSON when possible, else the raw string.
+
+        ``detector_params`` is stored as a JSON string; consumers of the
+        structured formats want it as real JSON, not a string-within-a-string
+        — but a non-JSON/non-container value (or an empty string) is passed
+        through rather than dropped.
+        """
+        if not raw:
+            return None
+        try:
+            parsed = json.loads(raw)
+        except (ValueError, TypeError):
+            return raw
+        return parsed if isinstance(parsed, dict | list) else raw
+
+    @staticmethod
+    def _iso_utc(ts: Any) -> str | None:
+        """ISO-8601 UTC string (``2026-07-11T10:30:00Z``) for a naive-UTC
+        timestamp, or ``None`` when unset/unparseable."""
+        if ts is None:
+            return None
+        try:
+            if isinstance(ts, np.datetime64):
+                ts = ts.astype("datetime64[s]").astype(datetime)
+            if isinstance(ts, datetime):
+                if ts.tzinfo is not None:
+                    ts = ts.astimezone(timezone.utc).replace(tzinfo=None)
+                return str(ts.strftime("%Y-%m-%dT%H:%M:%SZ"))
+        except (ValueError, TypeError, OverflowError):
+            return None
+        return None
+
     def _bold(self, text: str) -> str:
         """Render *text* bold in the target platform's markdown.
 

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -14,7 +14,7 @@ conventions.
 **Database access for _you_ (recommended, not required).** detectkit itself
 connects to the database directly via its drivers — it **never** needs an MCP to
 run. But you assist far better with **read access to the same database** (e.g. a
-database MCP for the project's ClickHouse / PostgreSQL / MySQL): you can inspect
+database MCP for the project's ClickHouse / PostgreSQL / MySQL / MariaDB): you can inspect
 a metric's series, find real incidents to label for `dtk autotune`, sanity-check
 a metric query before running it, and confirm detections — instead of asking the
 user to run every query by hand. Without it, fall back to marking incidents

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -37,11 +37,26 @@ Used by `run`, `unlock`, and `clean` (drift mode). Three forms:
 (`--select "*" --exclude "metrics/staging/*"`). Metric names must be unique
 across the project; duplicates raise an error listing the conflicting files.
 
+## Exit codes
+
+`dtk run`, `dtk autotune`, and `dtk clean` return a process exit code meant for
+schedulers and CI to gate on:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success — every metric completed the requested steps. |
+| `1` | Failure — any metric failed, the run aborted early, a startup/config/DB error occurred, or the selector matched no metrics. |
+| `2` | Usage error — bad CLI arguments. |
+
+On `dtk autotune`, a metric that's disabled in its config counts as **skipped**,
+not failed, and doesn't turn the exit code non-zero by itself. Other commands
+keep Click's default behavior (0 on success, non-zero on any exception).
+
 ## `dtk run`
 
 ```bash
 dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
-        [--full-refresh] [--force] [--profile NAME] [--report [PATH]]
+        [--full-refresh] [--force] [--profile NAME] [--report [PATH]] [--json]
 ```
 
 - `--steps` — which of `load`, `detect`, `alert` to run (default all); they always
@@ -66,6 +81,12 @@ dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
   tables, so even a `--steps load` run can produce one. Dual-mode: bare `--report`
   → `reports/<metric>.html`; `--report <dir>` → `<dir>/<metric>.html`;
   `--report file.html` → that file.
+- `--json` — human-readable progress still goes to **stderr**; **stdout** gets
+  exactly one JSON summary line for scripting/CI:
+  `{schema_version: 1, command, project, selector, steps, started_at,
+  finished_at, status: success|failed|error, metrics: [{name, status,
+  steps_completed, datapoints_loaded, anomalies_detected, alerts_sent, error}],
+  totals: {metrics, succeeded, failed, skipped, ...}, exit_code}`.
 
 ## `dtk autotune --select <sel>`
 
@@ -396,6 +417,12 @@ timers / Windows Task Scheduler. Always `cd` into the project first:
 Pair scheduling with `error_alerting` (in `detectkit_project.yml`) so in-process
 failures page someone; cron monitoring covers `dtk run` not running at all.
 
+Beyond cron, orchestrators can gate directly on the process instead of parsing
+logs: an Airflow `BashOperator`, a Dagster op, a Prefect task, or a CI job all
+fail their step when `dtk run` / `dtk autotune` / `dtk clean` exits non-zero
+(see "Exit codes" above), and can additionally parse `dtk run --json`'s stdout
+summary for per-metric detail.
+
 ## Troubleshooting
 
 - **"Metric not found"** — selector doesn't match. Use the bare name

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/cli/assets/claude/rules/project.md

@@ -116,9 +116,10 @@ alert_channels:
 
 ### Database profiles
 
-> ClickHouse, PostgreSQL and MySQL are all fully supported. ClickHouse/MySQL use
-> two *databases*; PostgreSQL connects to one `database` and uses two *schemas*.
-> `dtk init --db-type {clickhouse,postgres,mysql}` scaffolds the right shape.
+> ClickHouse, PostgreSQL, MySQL and MariaDB are all fully supported.
+> ClickHouse/MySQL/MariaDB use two *databases*; PostgreSQL connects to one
+> `database` and uses two *schemas*.
+> `dtk init --db-type {clickhouse,postgres,mysql,mariadb}` scaffolds the right shape.
 
 **ClickHouse**:
 ```yaml
@@ -166,6 +167,12 @@ profiles:
     settings: {}                   # optional — extra pymysql.connect kwargs
 ```
 
+**MariaDB**: identical fields to the MySQL block above — just spell `type:
+mariadb` instead of `type: mysql`. The vendor (MySQL vs MariaDB) is
+auto-detected at connect (`SELECT VERSION()`), so MariaDB gets its own
+`VALUES()`-form upsert instead of MySQL 8.0.19's row-alias form.
+`pip install 'detectkit[mariadb]'`.
+
 ### Alert channels
 
 Defined once in `profiles.yml`, referenced by name in each metric's
@@ -228,9 +235,22 @@ alert_channels:
   webhook_alerts:
     type: webhook
     webhook_url: "{{ env_var('WEBHOOK_URL') }}"   # required
+    format: attachments                           # optional: attachments (default) | json | alertmanager
+    secret: "{{ env_var('WEBHOOK_SECRET') }}"      # optional — HMAC-SHA256-signs the request body
     extra_headers:                                # optional
       Authorization: "Bearer {{ env_var('WEBHOOK_TOKEN') }}"
 ```
+> `format` — `attachments` (default) renders the same platform-style card as
+> Mattermost/Slack; `json` sends a versioned structured event
+> (`schema_version: 1`; fields like `kind`/`status`/`project`/`metric`/
+> `timestamp`/`value`/`expected`/`severity`/`direction`/`detector`/`rule`/
+> `quorum`/`incident`/`links`/`display`); `alertmanager` sends a Prometheus
+> Alertmanager webhook-receiver payload (v4) — a trigger/resolve pair sharing
+> identical labels/fingerprint, `severity: critical` for anomaly/error and
+> `warning` for no-data (no-data never auto-resolves). `json`/`alertmanager`
+> ignore a custom `template` and add an `X-Detectkit-Event` header.
+> `secret` — signs the raw request body as HMAC-SHA256 into
+> `X-Detectkit-Signature-256: sha256=<hex>`, for any `format`.
 
 ## Notes
 

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/cli/assets/claude/skills/dtk-setup-project/SKILL.md

@@ -50,17 +50,19 @@ side by side, ask which one to set up.
 
 ## Step 1 — Pick the database backend
 
-**ClickHouse, PostgreSQL and MySQL are all fully supported.** Ask which one the
-project uses (default to ClickHouse if unsure). `dtk init --db-type
-{clickhouse,postgres,mysql}` scaffolds `profiles.yml` for the chosen backend.
-The location fields differ:
-- **ClickHouse** / **MySQL** — two *databases*: `internal_database` / `data_database`.
+**ClickHouse, PostgreSQL, MySQL and MariaDB are all fully supported.** Ask
+which one the project uses (default to ClickHouse if unsure). `dtk init
+--db-type {clickhouse,postgres,mysql,mariadb}` scaffolds `profiles.yml` for the
+chosen backend. The location fields differ:
+- **ClickHouse** / **MySQL** / **MariaDB** — two *databases*: `internal_database` / `data_database`.
 - **PostgreSQL** — connect to a `database` (must already exist), then two
   *schemas*: `internal_schema` / `data_schema`.
 
-The metric query SQL dialect also differs (e.g. `toStartOfInterval` on
-ClickHouse vs `date_trunc`/`to_timestamp` on Postgres vs `FROM_UNIXTIME` on
-MySQL). Everything else — detectors, alerting, the CLI — is identical.
+`type: mariadb` is an identical profile alias to `type: mysql` (same location
+fields; the vendor is auto-detected at connect). The metric query SQL dialect
+also differs (e.g. `toStartOfInterval` on ClickHouse vs `date_trunc`/
+`to_timestamp` on Postgres vs `FROM_UNIXTIME` on MySQL/MariaDB). Everything
+else — detectors, alerting, the CLI — is identical.
 
 ## Step 2 — Connection details (gather, don't guess)
 
@@ -136,9 +138,11 @@ identity fields below are optional overrides.
 - **email** — `smtp_host`, `smtp_port`, `from_email`, `to_emails` (list);
   optional `from_name` (From display name, default `detectkit`);
   `smtp_username` / `smtp_password` via env_var.
-- **webhook** — generic `webhook_url` (required) + optional `extra_headers`
-  (also accepts `username` / `icon_url` / `icon_emoji` / `channel`). There is
-  no `url`, `method` or `headers` field.
+- **webhook** — generic `webhook_url` (required) + optional `format`
+  (`attachments` default / `json` / `alertmanager`), `secret` (HMAC-SHA256-signs
+  the request body into `X-Detectkit-Signature-256`), and `extra_headers` (also
+  accepts `username` / `icon_url` / `icon_emoji` / `channel`). There is no
+  `url`, `method` or `headers` field.
 
 ```yaml
 # at the end of profiles.yml

{detectkit-0.57.0 → detectkit-0.58.0}/detectkit/cli/commands/autotune.py

@@ -239,14 +239,19 @@ def run_autotune(
     force: bool,
     dry_run: bool,
     report_path: str | None = None,
-) -> None:
-    """Auto-tune each selected metric's detector configuration."""
+) -> int:
+    """Auto-tune each selected metric's detector configuration.
+
+    Returns:
+        0 if every metric tuned or was explicitly skipped, 1 if any startup
+        step failed or any metric's tuning attempt failed.
+    """
     from_dt = parse_date(from_date) if from_date else None
     to_dt = parse_date(to_date) if to_date else None
 
     loaded = _load_project(profile)
     if loaded is None:
-        return
+        return 1
     project_root, _project_config, internal_manager, _db_manager = loaded
     project_name = getattr(_project_config, "name", None)
 
@@ -254,15 +259,17 @@ def run_autotune(
         metrics = select_metrics(select, project_root)
     except ValueError as exc:
         click.echo(click.style(f"Error: {exc}", fg="red", bold=True))
-        return
+        return 1
     if not metrics:
         click.echo(click.style(f"No metrics found matching selector: {select}", fg="yellow"))
-        return
+        return 1
 
     click.echo(f"Found {len(metrics)} metric(s) to tune")
-    succeeded = 0
+    ok_count = 0
+    skipped_count = 0
+    failed_count = 0
     for metric_path, config in metrics:
-        ok = _tune_one(
+        status = _tune_one(
             metric_path=metric_path,
             config=config,
             project_root=project_root,
@@ -277,10 +284,20 @@ def run_autotune(
             project_name=project_name,
             project_loading_delay=getattr(_project_config, "loading_delay", None),
         )
-        if ok:
-            succeeded += 1
-
-    echo_done(f"Tuned {len(metrics)} metric(s), {succeeded} succeeded.")
+        if status == "ok":
+            ok_count += 1
+        elif status == "skipped":
+            skipped_count += 1
+        else:
+            failed_count += 1
+
+    parts = [f"{ok_count} succeeded"]
+    if skipped_count:
+        parts.append(f"{skipped_count} skipped")
+    if failed_count:
+        parts.append(f"{failed_count} failed")
+    echo_done(f"Tuned {len(metrics)} metric(s), {', '.join(parts)}.")
+    return 1 if failed_count else 0
 
 
 def _tune_one(
@@ -298,13 +315,19 @@ def _tune_one(
     report_path: str | None = None,
     project_name: str | None = None,
     project_loading_delay: str | int | None = None,
-) -> bool:
-    """Tune one metric end to end; return True on success."""
+) -> str:
+    """Tune one metric end to end.
+
+    Returns:
+        ``"ok"`` on success, ``"skipped"`` when autotune is disabled for this
+        metric (an explicit config choice, not a failure), or ``"failed"``
+        (no datapoints, a validation/engine error, or an unexpected exception).
+    """
     name = config.name
     autotune_cfg = config.autotune or AutoTuneConfig()
     if not autotune_cfg.enabled:
         echo_noop(name, "autotune disabled in config")
-        return False
+        return "skipped"
 
     interval_seconds = config.get_interval().seconds
 
@@ -312,14 +335,14 @@ def _tune_one(
     data = internal_manager.load_datapoints(name, from_timestamp=from_dt, to_timestamp=to_dt)
     if len(data["timestamp"]) == 0:
         echo_noop(name, "no datapoints — run `dtk run --select " + name + " --steps load` first")
-        return False
+        return "failed"
 
     click.echo(click.style(f"Tuning metric: {name}", fg="cyan", bold=True))
     click.echo(f"  Config file: {metric_path.relative_to(project_root)}")
 
     if not force and not internal_manager.acquire_lock(name, "pipeline", "pipeline"):
         echo_error(name, "locked by another run (use --force or `dtk unlock`)")
-        return False
+        return "failed"
 
     try:
         data = cap_history(data, autotune_cfg.max_history)
@@ -375,7 +398,7 @@ def _tune_one(
             project_loading_delay=project_loading_delay,
         )
         internal_manager.release_lock(name, "pipeline", "pipeline", status="completed")
-        return True
+        return "ok"
 
     except (AutoTuneError, ValueError, FileNotFoundError) as exc:
         internal_manager.release_lock(
@@ -384,13 +407,13 @@ def _tune_one(
         if not dry_run:
             _save_failed_run(internal_manager, name, interval_seconds, scoring_override, str(exc))
         echo_error(name, str(exc))
-        return False
+        return "failed"
     except Exception as exc:  # noqa: BLE001 — never leave a held lock behind
         internal_manager.release_lock(
             name, "pipeline", "pipeline", status="failed", error_message=str(exc)
         )
         echo_error(name, f"unexpected error: {exc}")
-        return False
+        return "failed"
 
 
 def _finalize(