detectkit 0.43.0__tar.gz → 0.44.1__tar.gz

{detectkit-0.43.0/detectkit.egg-info → detectkit-0.44.1}/PKG-INFO

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

{detectkit-0.43.0 → detectkit-0.44.1}/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.43.0"
+__version__ = "0.44.1"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/autotune/autotuner.py

@@ -6,7 +6,9 @@ command handles loading, persistence, config emission and candidate cleanup.
 
 from __future__ import annotations
 
-from collections.abc import Callable
+import contextlib
+import logging
+from collections.abc import Callable, Iterator
 from datetime import datetime, timedelta
 from typing import Any
 
@@ -27,6 +29,31 @@ from detectkit.detectors.factory import DetectorFactory
 
 _ALERT_WINDOW_GRID = (1, 2, 3, 4, 5)
 
+# The windowed detectors emit a one-time "seasonality group can't fill this
+# window → falls back to global" warning per *instance*. A tune builds dozens of
+# throwaway candidate detectors, so that warning would flood the terminal and
+# bury the structured decision log. The engine already surfaces an under-fill of
+# the *chosen* seasonality as a `window` advisory in its own log, so the raw
+# per-candidate warnings are pure noise here.
+_WINDOWED_LOGGER = "detectkit.detectors.statistical._windowed"
+
+
+@contextlib.contextmanager
+def _quiet_per_candidate_warnings() -> Iterator[None]:
+    """Silence the windowed detectors' per-instance under-fill warning for a tune.
+
+    Scoped + restored, so a real ``dtk run`` (which builds one detector and *does*
+    want the warning) is unaffected — only the candidate sweep inside the engine
+    is quieted.
+    """
+    logger = logging.getLogger(_WINDOWED_LOGGER)
+    prev_level = logger.level
+    logger.setLevel(logging.ERROR)
+    try:
+        yield
+    finally:
+        logger.setLevel(prev_level)
+
 
 def _ts_to_dt(ts64: np.datetime64) -> datetime:
     ms = int(ts64.astype("datetime64[ms]").astype(np.int64))
@@ -196,4 +223,5 @@ def run_autotune_engine(
         settings=settings,
         on_stage=on_stage,
     )
-    return tuner.tune()
+    with _quiet_per_candidate_warnings():
+        return tuner.tune()

detectkit-0.44.1/detectkit/cli/_output.py

@@ -0,0 +1,112 @@
+"""Shared CLI output helpers so every command renders in one house style.
+
+Mirrors the load → detect → alert pipeline's tree look (``┌─ / │ / └─``) used by
+``dtk run`` so the maintenance commands (``dtk clean``, ``dtk unlock``) match it
+instead of each inventing its own formatting.
+
+House conventions:
+- A metric *with* something to report is a tree: a cyan-bold ``┌─ <name>``
+  header followed by one child line per item (``│   `` for all but the last,
+  ``└─ `` for the last).
+- A metric with *nothing* to do is a single ``•`` line.
+- A per-metric error is a red ``✗`` line (to stderr).
+- The final summary is a cyan-bold ``Done. …`` line.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import click
+
+# Autotune-engine stage name → display title for the streamed run-log tree.
+# Most stages render as ``stage.upper()``; only the two underscored names need a
+# space so the header reads cleanly (``DETECTOR SELECT`` / ``GRID SEARCH``).
+AUTOTUNE_STAGE_TITLES = {
+    "labels": "LABELS",
+    "seasonality": "SEASONALITY",
+    "detector_select": "DETECTOR SELECT",
+    "grid_search": "GRID SEARCH",
+    "window": "WINDOW",
+}
+
+
+def echo_block(
+    title: str,
+    children: list[str],
+    *,
+    warnings: list[str] | None = None,
+    echo: Callable[[str], None] = click.echo,
+) -> None:
+    """Print a cyan-bold ``┌─ title`` header with ``│``/``└─`` child lines.
+
+    The injectable core of the house tree style (``dtk run``'s load/detect/alert
+    blocks): ``warnings`` render as yellow ``│`` continuation lines above the
+    children, the last child gets the ``└─`` elbow. ``echo`` defaults to
+    ``click.echo`` but can be any line sink, so the tune server can stream the
+    same blocks through its own output callback. ``children`` must be non-empty.
+    """
+    echo(click.style(f"  ┌─ {title}", fg="cyan", bold=True))
+    for warning in warnings or []:
+        echo(click.style(f"  │   ⚠ {warning}", fg="yellow", bold=True))
+    last = len(children) - 1
+    for i, child in enumerate(children):
+        prefix = "  └─ " if i == last else "  │   "
+        echo(f"{prefix}{child}")
+
+
+def echo_tree(name: str, children: list[str], *, warnings: list[str] | None = None) -> None:
+    """Print a ``┌─ name`` header with ``│``/``└─`` child lines.
+
+    ``warnings`` (if any) are rendered as yellow ``│`` continuation lines above
+    the children. ``children`` must be non-empty (a metric with no items should
+    use :func:`echo_noop` instead). Thin wrapper over :func:`echo_block` (the
+    CLI-default ``click.echo`` sink).
+    """
+    echo_block(name, children, warnings=warnings)
+
+
+class StageLogRenderer:
+    """Stream ``(stage, line)`` engine progress as the run-log tree.
+
+    Opens a cyan-bold ``┌─ TITLE`` header the first time each stage appears and
+    prints every subsequent line for that stage as a ``│   `` child — the same
+    look as ``dtk run``'s load/detect/alert blocks. ``titles`` maps an engine
+    stage name to its display title (unmapped names fall back to ``upper()``);
+    ``echo`` is injectable so one renderer drives both the CLI (``click.echo``)
+    and the ``dtk tune`` server (its own output callback). Build a fresh renderer
+    per run so the first stage re-opens its header.
+    """
+
+    def __init__(
+        self,
+        *,
+        titles: dict[str, str] | None = None,
+        echo: Callable[[str], None] = click.echo,
+    ) -> None:
+        self._open: str | None = None
+        self._titles = titles or {}
+        self._echo = echo
+
+    def __call__(self, stage: str, line: str) -> None:
+        if self._open != stage:
+            title = self._titles.get(stage, stage.upper())
+            self._echo(click.style(f"  ┌─ {title}", fg="cyan", bold=True))
+            self._open = stage
+        self._echo(f"  │   {line}")
+
+
+def echo_noop(name: str, reason: str) -> None:
+    """A metric with nothing to do — a single ``•`` line."""
+    click.echo(f"  • {name}: {reason}")
+
+
+def echo_error(name: str, message: str) -> None:
+    """A per-metric failure — a red ``✗`` line on stderr."""
+    click.echo(click.style(f"  ✗ {name}: {message}", fg="red"), err=True)
+
+
+def echo_done(summary: str) -> None:
+    """The closing ``Done. …`` summary (cyan, bold), preceded by a blank line."""
+    click.echo()
+    click.echo(click.style(f"Done. {summary}", fg="cyan", bold=True))

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/assets/claude/rules/alerting.md

@@ -164,8 +164,7 @@ config needed. Control it project-wide with `alert_help_url` in
 - **a URL string** → your own runbook/wiki page instead
 - **`false`** → hide the link entirely
 
-Per-channel rendering (defaults only; resolved by
-`ProjectConfig.resolve_alert_help_url`):
+Per-channel rendering (defaults only; the resolved help URL is rendered per channel as follows):
 
 - **Slack / Mattermost / generic webhook** — a clickable `How to read this alert`
   label in the compact `Links` field (alongside `Dashboard` + any extra links),
@@ -185,7 +184,7 @@ mirrors `{dashboard_url}` / `{dashboard_line}`. See the template table below.
 
 With no custom `template`, each channel renders a structured, branded message
 (alert-centric: the rule that fired leads, the anomaly value is evidence). The
-shared value computation lives in one place (`BaseAlertChannel.build_context`),
+shared value computation lives in one place,
 so templates and native rendering stay consistent. Every alert title/headline
 leads with a colored **status circle** — 🔴 anomaly, 🟢 recovery, 🟡 no-data,
 🔵 pipeline error — so the status reads from color alone. It also leads with the
@@ -241,8 +240,7 @@ Latest reading** fields bound the span. Labels are self-describing so the onset
 isn't misread as the alert-fire moment: **Anomaly began** is the resolved onset,
 **not** when the alert fired. Recovery shows the fuller **began → fired →
 recovered** timeline (`Incident lasted …`), where **Alert fired** =
-`onset + (consecutive_required − 1) × interval` (computed in `build_context`,
-exposed as `{fired_display}`, omitted when the run is capped). The true
+`onset + (consecutive_required − 1) × interval` (exposed as `{fired_display}`, omitted when the run is capped). The true
 streak/onset is resolved only when an alert fires/clears (a bounded lookback over
 the detection history; a run older than the window shows `over …`), so the hot
 no-alert path stays cheap. Exposed to templates as `{anomaly_lead}` /

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/assets/claude/rules/autotune.md

@@ -21,10 +21,12 @@ same windowed detectors and `detector_id` identity). The fastest path is the
 > **You can also run this engine *inside* `dtk tune`** — its **Autotune** mode runs
 > the same search **server-side** (using the incidents you've marked as ground
 > truth), re-seeds the knobs with the winner, and lets you **Apply** in place. That's
-> the same computation as this command; the difference is it edits the metric YAML in
-> place (advisory — no run record / `__tuned_<id>.yml` / persisted detections) rather
-> than emitting a new tuned file. Reach for `dtk autotune` when you want the audited
-> run + tuned file + persisted winner detections.
+> the same computation as this command, with two differences: it tunes on the
+> **window currently shown** in the cockpit (the **Points shown** trim — the series
+> you see and score) rather than the full capped history, and it edits the metric YAML
+> in place (advisory — no run record / `__tuned_<id>.yml` / persisted detections)
+> rather than emitting a new tuned file. Reach for `dtk autotune` when you want the
+> audited run + tuned file + persisted winner detections.
 
 ## What it searches
 

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/assets/claude/rules/cli.md

@@ -109,10 +109,12 @@ anomalies** — loop a cloud of anomaly dots, each consecutive run, gaps bridged
 `consecutive_anomalies`, becomes one span — or **Threshold capture** every span past
 a horizontal line, each widened to a full interval so the alert lands inside; the
 painted window saves as `capture_windows`), and **Autotune** (**Run autotune**
-launches the **real** `dtk autotune` engine **server-side** over the metric's full
-history, using your marked incidents as ground truth, then **re-seeds every knob**
-with the winner and shows the score + decision log; the band leads like Tune). The
-Autotune mode is **advisory** — it computes + re-seeds only and persists nothing (no
+launches the **real** `dtk autotune` engine **server-side** over the **window
+currently shown** (the **Points shown** trim — the same series you see and score, not
+the full history), using your marked incidents as ground truth, then **re-seeds every
+knob** with the winner and shows the score + decision log; the band leads like Tune;
+each run also streams a structured `LABELS → … → RESULT` log to the terminal, like
+`dtk run`). The Autotune mode is **advisory** — it computes + re-seeds only and persists nothing (no
 run record / `__tuned_<id>.yml` / detections, so `dtk tune` stays lock-free); review
 the band and **Apply** to write it back. It honours the metric's `autotune:` block,
 is supervised when incidents are marked (also picks `consecutive_anomalies`) else

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/assets/claude/rules/overview.md

@@ -114,6 +114,5 @@ series, watch the band recompute live, then write the config back into the metri
 
 ## Authoritative sources
 
-The shipped detectkit docs (`docs/` in the repo, or
-<https://dtk.pipelab.dev>) and the `CHANGELOG.md` are authoritative for
+The detectkit docs at <https://dtk.pipelab.dev> and the project changelog are authoritative for
 behavior. These rule files summarize them for the installed version.

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/assets/claude/rules/project.md

@@ -45,8 +45,7 @@ overrides it; unset → a built-in `0.5`. Tuning-only — it never touches the p
 ### `alert_help_url` — "How to read this alert" link
 
 Every default-rendered alert on every channel carries a `How to read this alert`
-link for non-operator stakeholders. Tri-state, resolved by
-`ProjectConfig.resolve_alert_help_url`:
+link for non-operator stakeholders. Tri-state:
 
 - **unset / null** (default) → the official detectkit guide
   (`https://dtk.pipelab.dev/guides/reading-alerts/`).

{detectkit-0.43.0 → detectkit-0.44.1}/detectkit/cli/commands/autotune.py

@@ -31,7 +31,14 @@ from detectkit.autotune.labels import (
     parse_incident_labels,
 )
 from detectkit.autotune.runner import build_settings, cap_history, resolve_scoring
-from detectkit.cli._output import echo_done, echo_error, echo_noop
+from detectkit.cli._output import (
+    AUTOTUNE_STAGE_TITLES,
+    StageLogRenderer,
+    echo_block,
+    echo_done,
+    echo_error,
+    echo_noop,
+)
 from detectkit.cli.commands.run import find_project_root, parse_date, select_metrics
 from detectkit.config.metric_config import AutoTuneConfig, MetricConfig
 from detectkit.config.profile import ProfilesConfig
@@ -41,28 +48,6 @@ from detectkit.detectors.base import DetectionResult
 from detectkit.detectors.factory import DetectorFactory
 from detectkit.utils.json_utils import json_dumps_sorted
 
-_STAGE_TITLES = {
-    "labels": "LABELS",
-    "seasonality": "SEASONALITY",
-    "detector_select": "DETECTOR SELECT",
-    "grid_search": "GRID SEARCH",
-    "window": "WINDOW",
-}
-
-
-class _StageRenderer:
-    """Streams engine progress as the run-log tree (header per stage + │ lines)."""
-
-    def __init__(self) -> None:
-        self._open: str | None = None
-
-    def __call__(self, stage: str, line: str) -> None:
-        if self._open != stage:
-            title = _STAGE_TITLES.get(stage, stage.upper())
-            click.echo(click.style(f"  ┌─ {title}", fg="cyan", bold=True))
-            self._open = stage
-        click.echo(f"  │   {line}")
-
 
 def _results_to_batch(results: list[DetectionResult]) -> dict[str, np.ndarray]:
     """Convert detect() output into the ``save_detections`` batch shape."""
@@ -358,7 +343,7 @@ def _tune_one(
             ground_truth=ground_truth,
             interval_seconds=interval_seconds,
             settings=settings,
-            on_stage=_StageRenderer(),
+            on_stage=StageLogRenderer(titles=AUTOTUNE_STAGE_TITLES),
         )
 
         run_id = compute_run_id(result)
@@ -434,9 +419,7 @@ def _finalize(
 
     if dry_run:
         children.append("dry-run: no config written, no detections persisted")
-        click.echo(click.style("  ┌─ RESULT", fg="cyan", bold=True))
-        for i, child in enumerate(children):
-            click.echo(f"  {'└─' if i == len(children) - 1 else '│  '} {child}")
+        echo_block("RESULT", children)
         return
 
     # Persist the run record (the audit trail).
@@ -518,9 +501,7 @@ def _finalize(
         f"persisted winner, pruned {pruned} superseded run(s)"
     )
     children.append(f"Re-run with: dtk run --select {name}__tuned_{run_id}")
-    click.echo(click.style("  ┌─ RESULT", fg="cyan", bold=True))
-    for i, child in enumerate(children):
-        click.echo(f"  {'└─' if i == len(children) - 1 else '│  '} {child}")
+    echo_block("RESULT", children)
 
 
 def _prune_prior_winners(