detectkit 0.42.0__tar.gz → 0.44.0__tar.gz

{detectkit-0.42.0/detectkit.egg-info → detectkit-0.44.0}/PKG-INFO

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

{detectkit-0.42.0 → detectkit-0.44.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.42.0"
+__version__ = "0.44.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.42.0 → detectkit-0.44.0}/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.0/detectkit/autotune/runner.py

@@ -0,0 +1,102 @@
+"""Shared autotune entry point reused by ``dtk autotune`` and ``dtk tune``.
+
+The pure ``run_autotune_engine`` operates on an in-memory ``data`` dict, a
+``GroundTruth`` and a ``TuneSettings``. Both callers need the same plumbing to
+get there from a metric's ``AutoTuneConfig`` + labels: resolve the scoring
+metric, cap the training history, build the settings, project the labels onto
+the grid, and run the engine. That plumbing used to live privately in
+``cli/commands/autotune.py``; it lives here so the ``dtk tune`` server can reuse
+it verbatim for its server-side **Autotune** mode (no browser port of the
+scoring/CV/seasonality search). Neither this module nor the engine touches the
+database or the filesystem — the caller loads the datapoints and decides what to
+persist.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import numpy as np
+
+from detectkit.autotune._types import ScoringMetric
+from detectkit.autotune.autotuner import run_autotune_engine
+from detectkit.autotune.labels import IncidentLabels
+from detectkit.autotune.result import AutoTuneResult
+from detectkit.autotune.settings import TuneSettings
+from detectkit.config.metric_config import AutoTuneConfig
+
+# Cap the scored training span when the user doesn't pin max_history, so tuning
+# stays responsive on very long histories (recent data is the most relevant).
+DEFAULT_TRAIN_CAP = 50_000
+
+
+def resolve_scoring(scoring_override: str | None, autotune_cfg: AutoTuneConfig) -> ScoringMetric:
+    """Resolve the scoring metric: CLI override > config > MCC default.
+
+    Raises ``ValueError`` on an unknown name (callers translate as they see fit).
+    """
+    value = scoring_override or autotune_cfg.scoring_metric or ScoringMetric.MCC.value
+    try:
+        return ScoringMetric(value)
+    except ValueError as exc:
+        allowed = ", ".join(m.value for m in ScoringMetric)
+        raise ValueError(f"Invalid scoring metric '{value}'. Allowed: {allowed}") from exc
+
+
+def build_settings(*, scoring: ScoringMetric, autotune_cfg: AutoTuneConfig) -> TuneSettings:
+    """Map an ``AutoTuneConfig`` block (+ resolved scoring) to ``TuneSettings``."""
+    return TuneSettings(
+        metric=scoring,
+        beta=autotune_cfg.beta,
+        fold_count=autotune_cfg.folds,
+        stability_lambda=autotune_cfg.stability_lambda,
+        allowed_detector_types=autotune_cfg.detector_types,
+        allowed_seasonality=autotune_cfg.seasonality_candidates,
+        force_seasonality=autotune_cfg.force_seasonality,
+        fixed_params=dict(autotune_cfg.fixed_params),
+        max_history=autotune_cfg.max_history,
+    )
+
+
+def cap_history(data: dict[str, np.ndarray], max_history: int | None) -> dict[str, np.ndarray]:
+    """Keep the most recent ``max_history`` (or the default cap) points."""
+    n = len(data["timestamp"])
+    cap = max_history if max_history is not None else DEFAULT_TRAIN_CAP
+    if n <= cap:
+        return data
+    return {
+        "timestamp": data["timestamp"][-cap:],
+        "value": data["value"][-cap:],
+        "seasonality_data": data["seasonality_data"][-cap:],
+        "seasonality_columns": data["seasonality_columns"],
+    }
+
+
+def autotune_from_data(
+    *,
+    metric_name: str,
+    data: dict[str, np.ndarray],
+    labels: IncidentLabels,
+    interval_seconds: int,
+    autotune_cfg: AutoTuneConfig,
+    scoring_override: str | None = None,
+    on_stage: Callable[[str, str], None] | None = None,
+) -> AutoTuneResult:
+    """Run the full autotune engine on an in-memory series + labels.
+
+    Caps the history, resolves the scoring metric, projects ``labels`` onto the
+    (capped) grid as ground truth, builds the settings and runs the engine.
+    Pure: no DB, no filesystem, no lock — the caller decides what to persist.
+    """
+    data = cap_history(data, autotune_cfg.max_history)
+    scoring = resolve_scoring(scoring_override, autotune_cfg)
+    ground_truth = labels.to_ground_truth(data["timestamp"], interval_seconds)
+    settings = build_settings(scoring=scoring, autotune_cfg=autotune_cfg)
+    return run_autotune_engine(
+        metric_name=metric_name,
+        data=data,
+        ground_truth=ground_truth,
+        interval_seconds=interval_seconds,
+        settings=settings,
+        on_stage=on_stage,
+    )

detectkit-0.44.0/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.42.0 → detectkit-0.44.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -54,7 +54,9 @@ version — **read the relevant one on demand** instead of guessing:
   `dtk autotune`, and explains the chosen, annotated config (an automatic,
   cross-validated search). For **hands-on** tuning instead, `dtk tune` opens a
   browser view where you drag the detector's knobs against the real series and
-  write the result back in place (see `cli.md`).
+  write the result back in place — and its **Autotune** mode can run that same
+  search server-side and re-seed the knobs without leaving the cockpit (see
+  `cli.md`).
 - **Hit a detectkit bug, or have feedback** — once you've ruled out a local
   config fix (see the gotchas below), use the **`dtk-feedback`** skill to file a
   redacted bug report, feature request, or comment as a GitHub issue on the

{detectkit-0.42.0 → detectkit-0.44.0}/detectkit/cli/assets/claude/rules/autotune.md

@@ -17,6 +17,16 @@ same windowed detectors and `detector_id` identity). The fastest path is the
 > `metrics/.history/<metric>/` first). Use `autotune` to search automatically and
 > emit a new file; use `tune` to dial a detector in by eye and commit it. See
 > `cli.md`.
+>
+> **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, 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.42.0 → detectkit-0.44.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -88,7 +88,8 @@ cockpit**: ONE chart (the windshield) fills the view, the live metrics ride
 **pinned in a HUD over the chart** (the speedometer), and every control lives in an
 **always-visible, mode-aware side rail** beside the chart (Tune shows the detector
 knobs + effective config + Apply, Review the verdict actions, Label the capture
-tools + incident list + Save), while the controls that aren't detector-specific —
+tools + incident list + Save, Autotune the search button + winning config), while
+the controls that aren't detector-specific —
 the **Points shown** data window, the alert rule (**direction** + **consecutive
 anomalies**) and the **y = 0** toggle — stay visible in every mode. The chart is
 **zoomable** (scroll/drag + navigator strip) with a **"Points shown"** trim slider.
@@ -103,11 +104,22 @@ and which interactions are armed on the one chart: **Tune** (band leads; inciden
 recede to read-only context; hover a point for its window), **Review** (the fired
 alerts lead, band ghosts — click an alert marker to cycle its verdict un-reviewed →
 **valid** (green) → **false alarm** (slate); **Confirm all unreviewed valid** does
-the lot), and **Label** (band hides; **mark the real incidents** by drag, **Lasso
+the lot), **Label** (band hides; **mark the real incidents** by drag, **Lasso
 anomalies** — loop a cloud of anomaly dots, each consecutive run, gaps bridged up to
 `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`). **Confirming an alert valid IS marking an
+painted window saves as `capture_windows`), and **Autotune** (**Run autotune**
+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
+unsupervised, and needs the live server (unavailable under `--no-serve`).
+**Confirming an alert valid IS marking an
 incident**: the confirmed streak becomes a first-class **ground-truth incident** that
 shows in the Marked-incidents list (a read-only "✓ confirmed alert" row; its ✕
 un-confirms the alert), counts toward recall + correct, and is written on Save — so a

{detectkit-0.42.0 → detectkit-0.44.0}/detectkit/cli/commands/autotune.py

@@ -20,7 +20,6 @@ import numpy as np
 from detectkit.autotune import (
     AutoTuneError,
     ScoringMetric,
-    TuneSettings,
     compute_run_id,
     emit_tuned_config,
     parse_labels_file,
@@ -31,7 +30,15 @@ from detectkit.autotune.labels import (
     IncidentLabels,
     parse_incident_labels,
 )
-from detectkit.cli._output import echo_done, echo_error, echo_noop
+from detectkit.autotune.runner import build_settings, cap_history, resolve_scoring
+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,32 +48,6 @@ from detectkit.detectors.base import DetectionResult
 from detectkit.detectors.factory import DetectorFactory
 from detectkit.utils.json_utils import json_dumps_sorted
 
-# Cap the scored training span when the user doesn't pin max_history, so tuning
-# stays responsive on very long histories (recent data is the most relevant).
-_DEFAULT_TRAIN_CAP = 50_000
-
-_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."""
@@ -88,12 +69,11 @@ def _results_to_batch(results: list[DetectionResult]) -> dict[str, np.ndarray]:
 
 
 def _resolve_scoring(scoring_override: str | None, autotune_cfg: AutoTuneConfig) -> ScoringMetric:
-    value = scoring_override or autotune_cfg.scoring_metric or ScoringMetric.MCC.value
+    """CLI wrapper over the shared resolver: bad name → a click usage error."""
     try:
-        return ScoringMetric(value)
+        return resolve_scoring(scoring_override, autotune_cfg)
     except ValueError as exc:
-        allowed = ", ".join(m.value for m in ScoringMetric)
-        raise click.BadParameter(f"Invalid scoring metric '{value}'. Allowed: {allowed}") from exc
+        raise click.BadParameter(str(exc)) from exc
 
 
 _LABELS_GLOBS = ("*.yml", "*.yaml", "*.json")
@@ -216,34 +196,6 @@ def _prompt_labels(*, interval_seconds: int) -> IncidentLabels:
     return parse_incident_labels({"incidents": incidents}, interval_seconds=interval_seconds)
 
 
-def _build_settings(*, scoring: ScoringMetric, autotune_cfg: AutoTuneConfig) -> TuneSettings:
-    return TuneSettings(
-        metric=scoring,
-        beta=autotune_cfg.beta,
-        fold_count=autotune_cfg.folds,
-        stability_lambda=autotune_cfg.stability_lambda,
-        allowed_detector_types=autotune_cfg.detector_types,
-        allowed_seasonality=autotune_cfg.seasonality_candidates,
-        force_seasonality=autotune_cfg.force_seasonality,
-        fixed_params=dict(autotune_cfg.fixed_params),
-        max_history=autotune_cfg.max_history,
-    )
-
-
-def _cap_history(data: dict[str, np.ndarray], max_history: int | None) -> dict[str, np.ndarray]:
-    """Keep the most recent ``max_history`` (or default-cap) points."""
-    n = len(data["timestamp"])
-    cap = max_history if max_history is not None else _DEFAULT_TRAIN_CAP
-    if n <= cap:
-        return data
-    return {
-        "timestamp": data["timestamp"][-cap:],
-        "value": data["value"][-cap:],
-        "seasonality_data": data["seasonality_data"][-cap:],
-        "seasonality_columns": data["seasonality_columns"],
-    }
-
-
 def _load_project(
     profile: str | None,
 ) -> tuple[Path, ProjectConfig, InternalTablesManager, Any] | None:
@@ -368,7 +320,7 @@ def _tune_one(
         return False
 
     try:
-        data = _cap_history(data, autotune_cfg.max_history)
+        data = cap_history(data, autotune_cfg.max_history)
         click.echo(
             f"  Training span: {len(data['timestamp']):,} points " f"(interval {interval_seconds}s)"
         )
@@ -384,14 +336,14 @@ def _tune_one(
         ground_truth = labels.to_ground_truth(data["timestamp"], interval_seconds)
         click.echo(f"  Labels: {label_source}")
 
-        settings = _build_settings(scoring=scoring, autotune_cfg=autotune_cfg)
+        settings = build_settings(scoring=scoring, autotune_cfg=autotune_cfg)
         result = run_autotune_engine(
             metric_name=name,
             data=data,
             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)
@@ -467,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).
@@ -551,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(

{detectkit-0.42.0 → detectkit-0.44.0}/detectkit/cli/commands/tune.py

@@ -143,6 +143,10 @@ def run_tune(
         metric_name=name,
         incidents_dir=incidents_dir,
         interval_seconds=interval_seconds,
+        # Enable the server-side Autotune mode: the config (autotune block, interval)
+        # + a DB handle to reload the metric's history for the engine.
+        metric_config=config,
+        internal_manager=internal_manager,
     )
     if applied is None:
         echo_noop(name, "tuning cancelled — metric unchanged")