detectkit 0.28.0__tar.gz → 0.29.0__tar.gz

{detectkit-0.28.0 → detectkit-0.29.0}/MANIFEST.in

@@ -3,6 +3,7 @@ include LICENSE
 include requirements.txt
 recursive-include detectkit *.py
 recursive-include detectkit/cli/assets *.md
+recursive-include detectkit/reporting/assets *.js
 recursive-exclude tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.pyc

{detectkit-0.28.0/detectkit.egg-info → detectkit-0.29.0}/PKG-INFO

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

{detectkit-0.28.0 → detectkit-0.29.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.28.0"
+__version__ = "0.29.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/alerting/orchestrator/__init__.py

@@ -1,5 +1,6 @@
 """Public surface of the alert-orchestrator package."""
 
+from detectkit.alerting.orchestrator._replay import ReplayedEvent
 from detectkit.alerting.orchestrator._types import (
     AlertConditions,
     DetectionRecord,
@@ -13,6 +14,7 @@ __all__ = [
     "AlertOrchestrator",
     "AlertConditions",
     "DetectionRecord",
+    "ReplayedEvent",
     # Shared hydration of DetectionRecord rows from get_recent_detections
     # output (used by TaskManager and the recovery mixin).
     "hydrate_detection_records",

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/alerting/orchestrator/_recovery.py

@@ -139,6 +139,7 @@ class _RecoveryMixin(_OrchestratorBase):
     def _build_recovery_data(
         self,
         detections: list[DetectionRecord],
+        incident_records: list[DetectionRecord] | None = None,
     ) -> AlertData | None:
         """Construct the AlertData payload sent as a recovery notification."""
         if not detections:
@@ -165,7 +166,9 @@ class _RecoveryMixin(_OrchestratorBase):
 
         # Reconstruct the just-ended incident so the recovery message can say how
         # long it lasted (symmetric with the anomaly alert's onset/duration).
-        incident_count, onset_ts, capped = self._resolve_incident(latest.timestamp)
+        incident_count, onset_ts, capped = self._resolve_incident(
+            latest.timestamp, records=incident_records
+        )
 
         return AlertData(
             metric_name=self.metric_name,
@@ -200,7 +203,9 @@ class _RecoveryMixin(_OrchestratorBase):
             streak_capped=capped,
         )
 
-    def _resolve_incident(self, cleared_ts: Any) -> tuple[int, Any, bool]:
+    def _resolve_incident(
+        self, cleared_ts: Any, records: list[DetectionRecord] | None = None
+    ) -> tuple[int, Any, bool]:
         """Find the anomalous run that just ended before the recovery point.
 
         Walks back from *cleared_ts* (the latest, now-clean point): skips the
@@ -209,20 +214,23 @@ class _RecoveryMixin(_OrchestratorBase):
         capped)`` — ``(0, None, False)`` when no run can be reconstructed, so the
         recovery message just omits the incident duration.
         """
-        if not self.internal:
-            return 0, None, False
-
         step = np.timedelta64(self.interval.seconds, "s")
-        if isinstance(cleared_ts, np.datetime64):
-            last_point = cleared_ts.astype("datetime64[ms]").astype(datetime)
-        else:
-            last_point = cleared_ts
-        rows = self.internal.get_recent_detections(
-            metric_name=self.metric_name,
-            last_point=last_point,
-            num_points=STREAK_LOOKBACK_POINTS,
-        )
-        records = hydrate_detection_records(rows)
+        # ``records`` lets a pure caller (alert replay) supply the in-memory
+        # detection slice instead of a DB read; production passes None and the
+        # incident is resolved from ``_dtk_detections`` as before.
+        if records is None:
+            if not self.internal:
+                return 0, None, False
+            if isinstance(cleared_ts, np.datetime64):
+                last_point = cleared_ts.astype("datetime64[ms]").astype(datetime)
+            else:
+                last_point = cleared_ts
+            rows = self.internal.get_recent_detections(
+                metric_name=self.metric_name,
+                last_point=last_point,
+                num_points=STREAK_LOOKBACK_POINTS,
+            )
+            records = hydrate_detection_records(rows)
         if not records:
             return 0, None, False
 

detectkit-0.29.0/detectkit/alerting/orchestrator/_replay.py

@@ -0,0 +1,258 @@
+"""Pure historical replay of alert/recovery/no-data events.
+
+Reconstructs the alert events the orchestrator *would have* produced over a
+historical period from already-persisted detections — **without** any channel
+dispatch, DB state writes or wall-clock. It is the offline counterpart of the
+live ``should_alert`` / ``should_send_recovery`` / ``should_alert_no_data`` path:
+state (last alert / last recovery) is simulated in memory and the decision at
+every grid point is evaluated *causally* (only records with ``timestamp <= t``,
+since the windowed detector is causal), reusing the exact same quorum,
+consecutive-walk, cooldown and recovery arithmetic as the live path.
+
+Used to answer "what would these detections have alerted on over this window"
+for backtesting / autotune alert-window sweeps, where firing real channels and
+mutating ``_dtk_alert_states`` would be wrong.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+import numpy as np
+
+from detectkit.alerting.channels.base import AlertData
+from detectkit.alerting.orchestrator._base import STREAK_LOOKBACK_POINTS, _OrchestratorBase
+from detectkit.alerting.orchestrator._types import DetectionRecord
+from detectkit.core.interval import Interval
+
+
+@dataclass(frozen=True)
+class ReplayedEvent:
+    """One alert event reconstructed by :meth:`_ReplayMixin.replay`.
+
+    ``kind`` is ``"anomaly"``, ``"recovery"`` or ``"no_data"``; ``timestamp`` is
+    the grid point at which the event fired (the simulated "now"); ``alert_data``
+    is identical in shape to a live :class:`AlertData` (built via the same
+    ``_build_*`` helpers as the live path).
+    """
+
+    kind: str
+    timestamp: np.datetime64
+    alert_data: AlertData
+
+
+class _ReplayMixin(_OrchestratorBase):
+    def replay(
+        self,
+        detections: list[DetectionRecord],
+        value_at: dict[np.datetime64, float | None],
+        start: datetime,
+        end: datetime,
+    ) -> list[ReplayedEvent]:
+        """Reconstruct alert/recovery/no-data events over ``[start, end]``.
+
+        Forward pass over every interval boundary in the closed range
+        ``[start, end]``. At each grid point ``t`` the decision is evaluated
+        causally — only ``detections`` with ``timestamp <= t`` are considered —
+        reusing the live quorum / consecutive-walk / cooldown / recovery logic.
+        Simulated state (last alert / last recovery) lives in memory, so nothing
+        is dispatched and no DB row is written.
+
+        Args:
+            detections: every persisted detection over the period (any order;
+                the same per-detector-per-timestamp shape the live path uses).
+            value_at: grid ``np.datetime64`` → value, with ``None`` for a
+                missing / NaN datapoint (drives the no-data check).
+            start: first grid boundary to evaluate (inclusive).
+            end: last grid boundary to evaluate (inclusive).
+
+        Returns:
+            The fired events in chronological order.
+        """
+        by_time = self._group_by_timestamp(detections)
+
+        sim_last_alert: np.datetime64 | None = None
+        sim_last_recovery: np.datetime64 | None = None
+        events: list[ReplayedEvent] = []
+
+        for t in self._replay_grid(start, end):
+            # No-data fires independently of the quorum (a single binary
+            # metric-level signal), only when configured and not in cooldown.
+            if (
+                self.alert_config
+                and getattr(self.alert_config, "no_data_alert", False)
+                and value_at.get(t) is None
+                and not self._replay_in_cooldown(t, sim_last_alert, sim_last_recovery)
+            ):
+                last_point = t.astype("datetime64[ms]").astype(datetime)
+                events.append(
+                    ReplayedEvent("no_data", t, self._build_no_data_alert_data(last_point))
+                )
+                sim_last_alert = t
+                continue
+
+            causal = {ts: recs for ts, recs in by_time.items() if ts <= t}
+            ts_desc = sorted(causal, reverse=True)
+
+            consecutive, latest_quorum, direction = self._count_consecutive_anomalies(
+                causal, ts_desc
+            )
+            fired = (
+                latest_quorum is not None
+                and consecutive >= self.conditions.consecutive_anomalies
+                and not self._replay_in_cooldown(t, sim_last_alert, sim_last_recovery)
+            )
+
+            if fired:
+                assert latest_quorum is not None  # narrowed by ``fired``
+                streak, onset, capped = self._replay_streak(causal, ts_desc)
+                ad = self._build_alert_data(latest_quorum, streak, direction, onset, capped)
+                events.append(ReplayedEvent("anomaly", t, ad))
+                sim_last_alert = t
+            elif (
+                self.alert_config
+                and getattr(self.alert_config, "notify_on_recovery", False)
+                and sim_last_alert is not None
+                and (sim_last_recovery is None or sim_last_recovery < sim_last_alert)
+                and self._replay_recovered(causal, ts_desc, sim_last_alert)
+            ):
+                slice_ = [d for d in detections if d.timestamp <= t]
+                # Pure replay: resolve the just-ended incident from the in-memory
+                # slice, never from the DB (keeps replay standalone).
+                rd = self._build_recovery_data(slice_, incident_records=slice_)
+                if rd is not None:
+                    events.append(ReplayedEvent("recovery", t, rd))
+                    sim_last_recovery = t
+
+        return events
+
+    def _replay_grid(self, start: datetime, end: datetime) -> list[np.datetime64]:
+        """Every interval boundary in the closed range ``[start, end]``.
+
+        Boundaries are produced in ``datetime64[ms]`` so they compare exactly
+        with hydrated detection timestamps and ``value_at`` keys.
+        """
+        step = timedelta(seconds=self.interval.seconds)
+        grid: list[np.datetime64] = []
+        cur = start
+        while cur <= end:
+            grid.append(np.datetime64(cur, "ms"))
+            cur = cur + step
+        return grid
+
+    def _replay_in_cooldown(
+        self,
+        t: np.datetime64,
+        sim_last_alert: np.datetime64 | None,
+        sim_last_recovery: np.datetime64 | None,
+    ) -> bool:
+        """In-memory analog of :meth:`_CooldownMixin._is_in_cooldown`.
+
+        Elapsed time is measured on the grid (``t - sim_last_alert``) rather than
+        from the wall clock. ``cooldown_reset_on_recovery`` clears the cooldown
+        when a recovery has been simulated since the last alert.
+        """
+        if not self.alert_config or not getattr(self.alert_config, "alert_cooldown", None):
+            return False
+        if sim_last_alert is None:
+            return False
+
+        cooldown = np.timedelta64(Interval(self.alert_config.alert_cooldown).seconds, "s")
+        elapsed = (t - sim_last_alert).astype("timedelta64[s]")
+
+        if getattr(self.alert_config, "cooldown_reset_on_recovery", True):
+            if sim_last_recovery is not None and sim_last_recovery > sim_last_alert:
+                return False
+
+        return bool(elapsed < cooldown)
+
+    def _replay_recovered(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        ts_desc: list[np.datetime64],
+        sim_last_alert: np.datetime64,
+    ) -> bool:
+        """Pure half of :meth:`_RecoveryMixin._check_recovery_since_last_alert`.
+
+        Returns ``True`` when the metric has recovered as of the latest causal
+        point: no blocking anomalies under the trigger direction, OR no causal
+        detections strictly after the last simulated alert.
+        """
+        if not ts_desc:
+            # No detections at all → nothing blocking → recovered.
+            return True
+
+        # No fresh detections after the alert → assume recovery (mirrors the
+        # live "no fresh detections" branch).
+        if not any(ts > sim_last_alert for ts in ts_desc):
+            return True
+
+        latest_ts = ts_desc[0]
+        latest_anomalies = [d for d in causal[latest_ts] if d.is_anomaly]
+
+        policy = self.conditions.direction
+        if policy == "down":
+            blocking = [d for d in latest_anomalies if d.direction == "down"]
+        elif policy == "up":
+            blocking = [d for d in latest_anomalies if d.direction == "up"]
+        elif policy == "same":
+            trigger_direction = self._replay_trigger_direction(causal, sim_last_alert)
+            if trigger_direction is None:
+                blocking = latest_anomalies  # conservative fallback
+            else:
+                blocking = [d for d in latest_anomalies if d.direction == trigger_direction]
+        else:  # "any" / unknown — preserve historical behaviour
+            blocking = latest_anomalies
+
+        return len(blocking) == 0
+
+    def _replay_trigger_direction(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        sim_last_alert: np.datetime64,
+    ) -> str | None:
+        """Direction of the anomaly that triggered the simulated last alert.
+
+        Pure analog of :meth:`_RecoveryMixin._get_alert_trigger_direction`: the
+        live code reads the single detection row at the alert timestamp; here the
+        alert fired at the grid point ``sim_last_alert``, so the triggering
+        quorum is the latest causal point at or before it.
+        """
+        candidates = [ts for ts in causal if ts <= sim_last_alert]
+        if not candidates:
+            return None
+        latest_ts = max(candidates)
+        anomalies = [d for d in causal[latest_ts] if d.is_anomaly]
+        if not anomalies:
+            return None
+
+        _, direction = self._quorum_at(anomalies, None)
+        if direction in ("up", "down"):
+            return direction
+
+        ups = sum(1 for d in anomalies if d.direction == "up")
+        downs = sum(1 for d in anomalies if d.direction == "down")
+        if ups > downs:
+            return "up"
+        if downs > ups:
+            return "down"
+        return None
+
+    def _replay_streak(
+        self,
+        causal: dict[np.datetime64, list[DetectionRecord]],
+        ts_desc: list[np.datetime64],
+    ) -> tuple[int, np.datetime64, bool]:
+        """In-memory analog of :meth:`_DecisionMixin._resolve_streak`.
+
+        Re-walks the same direction-aware quorum logic over the causal records to
+        get the *true* streak length, then derives the onset and the cap flag the
+        same way the live path does.
+        """
+        latest_ts = ts_desc[0]
+        step = np.timedelta64(self.interval.seconds, "s")
+        count, _, _ = self._count_consecutive_anomalies(causal, ts_desc)
+        count = max(count, 1)
+        capped = count >= STREAK_LOOKBACK_POINTS
+        return count, latest_ts - step * (count - 1), capped

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/alerting/orchestrator/orchestrator.py

@@ -6,12 +6,14 @@ from detectkit.alerting.orchestrator._cooldown import _CooldownMixin
 from detectkit.alerting.orchestrator._decision import _DecisionMixin
 from detectkit.alerting.orchestrator._dispatch import _DispatchMixin
 from detectkit.alerting.orchestrator._recovery import _RecoveryMixin
+from detectkit.alerting.orchestrator._replay import _ReplayMixin
 
 
 class AlertOrchestrator(
     _DecisionMixin,
     _CooldownMixin,
     _RecoveryMixin,
+    _ReplayMixin,
     _DispatchMixin,
 ):
     """Coordinates alert decisions, cooldown, recovery and dispatch.
@@ -21,6 +23,8 @@ class AlertOrchestrator(
     * ``_DecisionMixin`` — should we alert? builds AlertData.
     * ``_CooldownMixin`` — suppress within the configured window.
     * ``_RecoveryMixin`` — direction-aware "all-clear" detection.
+    * ``_ReplayMixin``   — pure historical replay of alert/recovery/no-data
+      events (no dispatch, no DB state, no wall-clock).
     * ``_DispatchMixin``  — ship to channels and stamp state.
     """
 

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -37,7 +37,7 @@ across the project; duplicates raise an error listing the conflicting files.
 
 ```bash
 dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
-        [--full-refresh] [--force] [--profile NAME]
+        [--full-refresh] [--force] [--profile NAME] [--report [PATH]]
 ```
 
 - `--steps` — which of `load`, `detect`, `alert` to run (default all); they always
@@ -52,6 +52,13 @@ dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
 - `--force` — ignore a held lock and run anyway (also releases it on exit).
   Risky with concurrent runs; usually `dtk unlock` is the better recovery.
 - `--profile` — override the project's default profile (e.g. run against staging).
+- `--report [PATH]` — after the run, write a **self-contained HTML report** per
+  metric (values + per-detector confidence bands + flagged anomalies + the alerts
+  that fired + a summary, with client-side period selection). It is offline — open
+  it in a browser, nothing leaves the page. The report reads the persisted `_dtk_*`
+  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.
 
 ## `dtk autotune --select <sel>`
 
@@ -60,7 +67,10 @@ history window, then writes an annotated `metrics/<name>__tuned_<id>.yml`. Reads
 the metric's loaded datapoints (run `dtk run --steps load` first if empty), never
 edits the original, never alerts. `--incidents FILE` enables supervised tuning
 against labeled incidents; without it, an unsupervised objective is used.
-`--dry-run` searches without writing. Full reference: `autotune.md`.
+`--dry-run` searches without writing. `--report [PATH]` writes the same
+self-contained HTML report as `dtk run` for the tuned winner (default
+`reports/<metric>__tuned_<id>.html`; `<dir>` or a `.html` file also accepted).
+Full reference: `autotune.md`.
 
 ## `dtk test-alert <metric>`
 

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/cli/commands/autotune.py

@@ -333,6 +333,7 @@ def run_autotune(
     profile: str | None,
     force: bool,
     dry_run: bool,
+    report_path: str | None = None,
 ) -> None:
     """Auto-tune each selected metric's detector configuration."""
     from_dt = parse_date(from_date) if from_date else None
@@ -342,6 +343,7 @@ def run_autotune(
     if loaded is None:
         return
     project_root, _project_config, internal_manager, _db_manager = loaded
+    project_name = getattr(_project_config, "name", None)
 
     try:
         metrics = select_metrics(select, project_root)
@@ -369,6 +371,8 @@ def run_autotune(
             to_dt=to_dt,
             force=force,
             dry_run=dry_run,
+            report_path=report_path,
+            project_name=project_name,
         )
         if ok:
             succeeded += 1
@@ -391,6 +395,8 @@ def _tune_one(
     to_dt: datetime | None,
     force: bool,
     dry_run: bool,
+    report_path: str | None = None,
+    project_name: str | None = None,
 ) -> bool:
     """Tune one metric end to end; return True on success."""
     name = config.name
@@ -526,6 +532,9 @@ def _tune_one(
             ground_truth=ground_truth,
             dry_run=dry_run,
             project_root=project_root,
+            config=config,
+            report_path=report_path,
+            project_name=project_name,
         )
         internal_manager.release_lock(name, "pipeline", "pipeline", status="completed")
         return True
@@ -559,6 +568,9 @@ def _finalize(
     ground_truth: GroundTruth,
     dry_run: bool,
     project_root: Path,
+    config: MetricConfig | None = None,
+    report_path: str | None = None,
+    project_name: str | None = None,
 ) -> None:
     """Persist run + winner detections + tuned config, prune prior winners, render RESULT."""
     folds = " ".join(f"{f:.2f}" for f in result.cv_per_fold) or "—"
@@ -623,6 +635,33 @@ def _finalize(
     # Write the annotated tuned config.
     out_path.write_text(config_text, encoding="utf-8")
 
+    # Optional: emit an HTML report for the tuned window (winner's bands +
+    # anomalies + replayed alerts under the metric's alerting rules).
+    if report_path is not None and config is not None:
+        try:
+            from detectkit.cli.commands.run import _resolve_report_path
+            from detectkit.reporting import build_report_payload, render_report_html
+            from detectkit.utils.datetime_utils import now_utc_naive
+
+            ts = data["timestamp"]
+            start = ts[0].astype("datetime64[ms]").astype(datetime) if len(ts) else None
+            end = ts[-1].astype("datetime64[ms]").astype(datetime) if len(ts) else None
+            payload = build_report_payload(
+                metric_config=config,
+                internal=internal_manager,
+                start=start,
+                end=end,
+                project_name=project_name,
+                generated_at=now_utc_naive().strftime("%Y-%m-%d %H:%M UTC"),
+            )
+            if payload["points"]:
+                report_out = _resolve_report_path(report_path, project_root, out_path.stem)
+                report_out.parent.mkdir(parents=True, exist_ok=True)
+                report_out.write_text(render_report_html(payload), encoding="utf-8")
+                children.append(f"Report → {report_out.relative_to(project_root)}")
+        except Exception as report_error:  # never fail tuning on a report
+            children.append(f"Report skipped: {report_error}")
+
     children.append(f"Wrote {out_path.relative_to(project_root)}  (run_id={run_id})")
     children.append(
         f"Evaluated {len(result.candidate_detector_ids)} candidate(s); "

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/cli/commands/run.py

@@ -27,6 +27,7 @@ def run_command(
     full_refresh: bool,
     force: bool,
     profile: str | None,
+    report_path: str | None = None,
 ):
     """
     Execute metric processing pipeline.
@@ -40,6 +41,9 @@ def run_command(
         full_refresh: Delete and reload all data
         force: Ignore task locks
         profile: Profile name to use
+        report_path: When not None, emit an HTML report per metric after its
+            run. "" → default location (reports/<metric>.html); a directory →
+            <dir>/<metric>.html; a .html path → that file.
     """
     # Parse steps
     step_list = parse_steps(steps)
@@ -227,6 +231,79 @@ def run_command(
             )
             break
 
+        # Optional: emit a self-contained HTML report from the freshly-persisted
+        # internal tables (values + bands + anomalies + replayed alerts).
+        if report_path is not None:
+            try:
+                emit_metric_report(
+                    config=config,
+                    project_root=project_root,
+                    internal_manager=internal_manager,
+                    report_path=report_path,
+                    project_name=getattr(project_config, "name", None),
+                    from_dt=from_dt,
+                    to_dt=to_dt,
+                )
+            except Exception as report_error:  # never fail the run on a report
+                click.echo(click.style(f"  │ Report skipped: {report_error}", fg="yellow"))
+
+
+def _resolve_report_path(report_path: str, project_root: Path, metric_name: str) -> Path:
+    """Map the ``--report`` value to a concrete output file for a metric.
+
+    "" → ``<project>/reports/<metric>.html``; a ``.html`` path → that file;
+    anything else → ``<dir>/<metric>.html``.
+    """
+    if report_path == "":
+        return project_root / "reports" / f"{metric_name}.html"
+    candidate = Path(report_path)
+    if candidate.suffix.lower() == ".html":
+        return candidate
+    return candidate / f"{metric_name}.html"
+
+
+def emit_metric_report(
+    *,
+    config: MetricConfig,
+    project_root: Path,
+    internal_manager: InternalTablesManager,
+    report_path: str,
+    project_name: str | None,
+    from_dt: datetime | None,
+    to_dt: datetime | None,
+) -> None:
+    """Build and write the HTML report for one metric (best-effort)."""
+    from detectkit.reporting import build_report_payload, render_report_html
+    from detectkit.utils.datetime_utils import now_utc_naive
+
+    payload = build_report_payload(
+        metric_config=config,
+        internal=internal_manager,
+        start=from_dt,
+        end=to_dt,
+        project_name=project_name,
+        generated_at=now_utc_naive().strftime("%Y-%m-%d %H:%M UTC"),
+    )
+    if not payload["points"]:
+        click.echo("  │ Report: no datapoints in window, skipped")
+        return
+
+    out = _resolve_report_path(report_path, project_root, config.name)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(render_report_html(payload), encoding="utf-8")
+    try:
+        shown = out.relative_to(project_root)
+    except ValueError:
+        shown = out
+    click.echo(
+        click.style(
+            f"  │ Report → {shown}  "
+            f"({payload['summary']['anomalies']} anomalies, "
+            f"{payload['summary']['alerts']} alerts)",
+            fg="cyan",
+        )
+    )
+
 
 def parse_steps(steps_str: str) -> list[PipelineStep]:
     """

{detectkit-0.28.0 → detectkit-0.29.0}/detectkit/cli/main.py

@@ -136,6 +136,18 @@ def init_claude(target_dir: str):
     "--profile",
     help="Profile to use (default: from project config)",
 )
+@click.option(
+    "--report",
+    "report_path",
+    is_flag=False,
+    flag_value="",
+    default=None,
+    help=(
+        "After the run, emit a self-contained HTML report per metric "
+        "(values, confidence bands, anomalies, and alerts). Optional value: "
+        "an output file or directory; defaults to reports/<metric>.html."
+    ),
+)
 def run(
     select: str,
     exclude: str,
@@ -145,6 +157,7 @@ def run(
     full_refresh: bool,
     force: bool,
     profile: str,
+    report_path: str,
 ):
     """
     Run metric processing pipeline.
@@ -186,6 +199,7 @@ def run(
         full_refresh=full_refresh,
         force=force,
         profile=profile,
+        report_path=report_path,
     )
 
 
@@ -246,6 +260,18 @@ def run(
     is_flag=True,
     help="Run the search but persist nothing and write no config",
 )
+@click.option(
+    "--report",
+    "report_path",
+    is_flag=False,
+    flag_value="",
+    default=None,
+    help=(
+        "After tuning, emit a self-contained HTML report for the winning "
+        "config (values, confidence bands, anomalies, alerts). Optional value: "
+        "an output file or directory; defaults to reports/<metric>__tuned_<id>.html."
+    ),
+)
 def autotune(
     select: str,
     incidents_path: str,
@@ -258,6 +284,7 @@ def autotune(
     profile: str,
     force: bool,
     dry_run: bool,
+    report_path: str,
 ):
     """
     Automatically configure a metric's anomaly detector.
@@ -298,6 +325,7 @@ def autotune(
         profile=profile,
         force=force,
         dry_run=dry_run,
+        report_path=report_path,
     )