detectkit 0.24.0__tar.gz → 0.24.2__tar.gz

{detectkit-0.24.0/detectkit.egg-info → detectkit-0.24.2}/PKG-INFO

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

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

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/autotune/config_emitter.py

@@ -103,9 +103,17 @@ def _build_body(original: MetricConfig, result: AutoTuneResult, new_name: str) -
         elif original.seasonality_columns:
             body["seasonality_columns"] = original.seasonality_columns
 
-    body["detectors"] = [
-        {"type": result.chosen_detector_type, "params": result.chosen_detector_params}
-    ]
+    # Pin the detector's detection start to the load start so the first
+    # `dtk run` on the generated config detects across all loaded history. A
+    # fresh detector that omits `start_time` has no lower bound (no prior
+    # detections, no --from); DETECT falls back to loading_start_time, but
+    # emitting it keeps the generated config explicit and self-sufficient on
+    # older detectkit. `start_time` is execution-level and excluded from the
+    # detector_id hash, so it never changes detector identity.
+    detector_params = dict(result.chosen_detector_params)
+    if "start_time" not in detector_params and body.get("loading_start_time"):
+        detector_params["start_time"] = body["loading_start_time"]
+    body["detectors"] = [{"type": result.chosen_detector_type, "params": detector_params}]
     alerting = _build_alerting(original, result)
     if alerting is not None:
         body["alerting"] = alerting

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/cli/assets/claude/rules/autotune.md

@@ -32,7 +32,8 @@ same windowed detectors and `detector_id` identity). The fastest path is the
 4. **History window** — on near-ties uses a trend-gated tie-break: a stationary
    series prefers the **larger** `window_size` ("more history is better"), a
    trending / regime-shifting one the **smaller**; sets `loading_start_time` to
-   cover the lead-in.
+   cover the lead-in (and pins the detector's `start_time` to it, so the first
+   `dtk run` detects across all loaded history).
 5. **Alert window** (supervised only) — sweeps `consecutive_anomalies` on the
    labeled incidents.
 

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/cli/assets/claude/rules/cli.md

@@ -20,15 +20,16 @@ Run all commands from a project directory (the one containing
 
 Used by `run`, `unlock`, and `clean` (drift mode). Three forms:
 
-- **Metric name** — `--select cpu_usage`. Searches the root `metrics/` dir only.
-  Do **not** add `.yml` (it is appended). This matches the metric **file**, but
-  every operation is keyed by the metric `name` inside the YAML.
+- **Metric name** — `--select cpu_usage`. Resolves to `metrics/cpu_usage.yml` at
+  the root, then falls back to a recursive search by the YAML `name:` field in any
+  subdirectory. Do **not** add `.yml` (it is appended). This matches the metric by
+  **name**, and every operation is keyed by that `name` inside the YAML.
 - **Path / glob** — `--select "metrics/critical/*.yml"`, `--select "api_*"`,
   `--select "metrics/**/*.yml"`. Searches recursively via glob; keep `.yml`.
 - **Tag** — `--select tag:critical`. Searches recursively for metrics whose
   `tags:` list contains that tag.
 
-`--select "*"` selects everything. `--exclude / -e` removes matches
+`--select "*"` selects everything. `--exclude / -e` (on `dtk run`) removes matches
 (`--select "*" --exclude "metrics/staging/*"`). Metric names must be unique
 across the project; duplicates raise an error listing the conflicting files.
 
@@ -39,9 +40,9 @@ dtk run --select <sel> [--steps load,detect,alert] [--from DATE] [--to DATE] \
         [--full-refresh] [--force] [--profile NAME]
 ```
 
-- `--steps` — subset/order of `load`, `detect`, `alert` (default all). Examples:
-  `--steps load` (verify the query), `--steps detect` (rerun detection only),
-  `--steps detect,alert` (skip load).
+- `--steps` — which of `load`, `detect`, `alert` to run (default all); they always
+  execute in `load → detect → alert` order. Examples: `--steps load` (verify the
+  query), `--steps detect` (rerun detection only), `--steps detect,alert` (skip load).
 - `--from DATE` / `--to DATE` — `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`, UTC.
   Affects only the `load` step. `--from` overrides the metric's
   `loading_start_time`; `--to` defaults to now.

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/cli/assets/claude/rules/detectors.md

@@ -67,7 +67,7 @@ expected interval for the current point.
     half_life: null          # exponential half-life: int points or "3d"/"12h"
     detrend: null            # null | linear
     # --- execution (NOT hashed) ---
-    start_time: "2024-01-01 00:00:00"   # when detection begins
+    start_time: "2024-01-01 00:00:00"   # optional; when detection begins (default: loading_start_time)
     batch_size: 500
 ```
 

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/cli/assets/claude/skills/dtk-autotune/SKILL.md

@@ -158,8 +158,10 @@ dtk autotune --select <name>
 none yet, load first: `dtk run --select <name> --steps load` (optionally
 `--from <date>` to backfill history — more history tunes better). The default
 **supervised** scoring metric is **MCC** (robust to rare anomalies). Override
-only with reason: `--scoring recall` when a miss is worse than a false page,
-`--scoring f1`, etc. Run `dtk autotune --help` to confirm the live flags. Use
+only with reason: `--scoring f_beta` (with a higher `beta:` in the `autotune:`
+block) when a miss is worse than a false page, `--scoring f1` for a balanced
+trade-off, etc. The valid values are `mcc`, `f1`, `f_beta`, `balanced_accuracy`,
+`roc_auc`, `pr_auc`. Run `dtk autotune --help` to confirm the live flags. Use
 `--dry-run` to search without writing anything.
 
 **Unsupervised runs** (no labels) do **not** optimize MCC or any labeled metric —
@@ -191,9 +193,9 @@ The `#` comment header walks the whole decision; summarize for the user:
   `Objective : unsupervised (band-fit + flag-budget) = …` (it never claims an
   `mcc =` score it didn't compute). Read off the value + the per-fold CV spread.
 
-Offer alternatives: a re-run with a different `--scoring` (e.g. precision vs
-recall trade-off) or a nudged parameter. See `autotune.md` for the
-`_dtk_autotune_runs` audit table.
+Offer alternatives: a re-run with a different `--scoring` (e.g. `f_beta` with a
+higher `beta` to favor recall, or `f1` for balance) or a nudged parameter. See
+`autotune.md` for the `_dtk_autotune_runs` audit table.
 
 ## Step 5 — Show how the monitoring behaves (DB inspection query)
 

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/cli/commands/init_claude.py

@@ -10,9 +10,9 @@ It writes three things into the target directory:
 - ``CLAUDE.md`` — created if absent, otherwise a managed detectkit block is
   injected/refreshed between HTML-comment markers (existing content is kept).
 - ``.claude/rules/detectkit/`` — the reference docs the assistant reads on
-  demand (overview, cli, project, metrics, detectors, alerting).
+  demand (overview, cli, project, metrics, detectors, alerting, autotune).
 - ``.claude/skills/`` — user-facing skills (``dtk-setup-project``,
-  ``dtk-new-metric``, ``dtk-feedback``).
+  ``dtk-new-metric``, ``dtk-autotune``, ``dtk-feedback``).
 
 The source of truth for all of the above lives in ``detectkit/cli/assets/claude``
 and ships with the package, so re-running this command after upgrading detectkit
@@ -38,12 +38,15 @@ if TYPE_CHECKING:
     # strings, so it is never evaluated at runtime — safe on 3.10).
     from importlib.resources.abc import Traversable
 
-# Region in CLAUDE.md owned by this command. The BEGIN marker carries the
-# detectkit version (informational); the regex below matches any version so a
-# refresh replaces the whole region in place rather than appending a duplicate.
+# Region in CLAUDE.md owned by this command. The BEGIN marker is intentionally
+# version-less: stamping the version here made the block churn on every release
+# (a no-op upgrade still rewrote the marker), pushing users to re-run for nothing.
+# The block now changes only when its content actually changes, so a refresh is a
+# true no-op otherwise. The regex still matches the old *versioned* markers
+# (`<!-- BEGIN detectkit v0.23.2 ... -->`), so refreshing an existing file
+# replaces the whole region in place rather than appending a duplicate.
 _BEGIN = (
-    f"<!-- BEGIN detectkit v{__version__} "
-    "(managed by `dtk init-claude` — do not edit between these markers) -->"
+    "<!-- BEGIN detectkit (managed by `dtk init-claude` — do not edit between these markers) -->"
 )
 _END = "<!-- END detectkit -->"
 _BLOCK_RE = re.compile(r"<!-- BEGIN detectkit.*?-->.*?<!-- END detectkit -->", re.DOTALL)

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/database/internal_tables/_datapoints.py

@@ -40,6 +40,21 @@ class _DatapointsMixin(_InternalTablesBase):
         last_ts = self._manager.get_last_timestamp(full_table_name, metric_name)
         return self._normalize_max_timestamp(last_ts)
 
+    def get_first_datapoint_timestamp(self, metric_name: str) -> datetime | None:
+        """Return the earliest timestamp stored for *metric_name*, if any."""
+        full_table_name = self._manager.get_full_table_name(TABLE_DATAPOINTS, use_internal=True)
+        query = f"""
+        SELECT min(timestamp) AS first_ts
+        FROM {full_table_name}
+        WHERE metric_name = %(metric_name)s
+        """
+        result = self._manager.execute_query(query, {"metric_name": metric_name})
+        if not result:
+            return None
+        # ClickHouse min() over an empty selection yields the epoch sentinel
+        # rather than NULL; _normalize_max_timestamp maps that back to None.
+        return self._normalize_max_timestamp(result[0].get("first_ts"))
+
     def get_value_at(self, metric_name: str, timestamp: datetime) -> float | None:
         """Return the stored ``value`` for an exact timestamp.
 

{detectkit-0.24.0 → detectkit-0.24.2}/detectkit/orchestration/task_manager/_detect_step.py

@@ -78,6 +78,16 @@ class _DetectStepMixin(_TaskManagerBase):
                 actual_from = max(actual_from, start_time) if actual_from else start_time
 
             actual_from = to_naive_utc(actual_from)
+
+            # No lower bound from --from, the resume point, or the detector's
+            # `start_time`: a first-ever detect for a detector that omits
+            # `start_time` (every `dtk autotune` config does). Fall back to the
+            # metric's load start so the run detects across all loaded history,
+            # instead of mistaking "no lower bound" for "nothing to do" and
+            # silently reporting "already up to date" without ever detecting.
+            if actual_from is None:
+                actual_from = self._detect_fallback_start(config)
+
             if not actual_from or actual_from >= actual_to:
                 click.echo("  │   Nothing to detect (already up to date)")
                 continue
@@ -200,3 +210,17 @@ class _DetectStepMixin(_TaskManagerBase):
             )
         )
         return {"anomalies_count": anomalies_count}
+
+    def _detect_fallback_start(self, config: MetricConfig) -> datetime | None:
+        """Lower bound for a first-ever detect when nothing else pins it.
+
+        Mirrors the LOAD step: prefer the configured ``loading_start_time``,
+        else the metric's earliest stored datapoint. Returns ``None`` only when
+        the metric has no configured start and no data at all (genuinely nothing
+        to detect).
+        """
+        if config.loading_start_time:
+            return to_naive_utc(
+                datetime.fromisoformat(config.loading_start_time.replace("Z", "+00:00"))
+            )
+        return to_naive_utc(self.internal.get_first_datapoint_timestamp(config.name))

{detectkit-0.24.0 → detectkit-0.24.2/detectkit.egg-info}/PKG-INFO

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