detectkit 0.9.0__tar.gz → 0.11.0__tar.gz

{detectkit-0.9.0 → detectkit-0.11.0}/MANIFEST.in

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

{detectkit-0.9.0/detectkit.egg-info → detectkit-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: detectkit
-Version: 0.9.0
+Version: 0.11.0
 Summary: Metric monitoring with automatic anomaly detection
 Author: detectkit team
 License: MIT
@@ -61,7 +61,9 @@ Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Provides-Extra: integration
-Requires-Dist: testcontainers[clickhouse]>=4.0; extra == "integration"
+Requires-Dist: testcontainers[clickhouse,mysql,postgres]>=4.0; extra == "integration"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "integration"
+Requires-Dist: pymysql>=1.0.0; extra == "integration"
 Dynamic: license-file
 
 # detectkit
@@ -85,6 +87,7 @@ Dynamic: license-file
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
+- **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + a metric-scaffolding skill) so an assistant can help you build metrics out of the box
 
 ## Installation
 
@@ -108,6 +111,10 @@ pip install detectkit[all-db]       # All databases
 dtk init my_monitoring
 cd my_monitoring
 
+# Optional: set up Claude Code context so an AI assistant can help you
+# write metrics, tune detectors and configure alerts (re-run after upgrades)
+dtk init-claude
+
 # Configure database in profiles.yml, then:
 dtk run --select cpu_usage
 dtk run --select tag:critical

{detectkit-0.9.0 → detectkit-0.11.0}/README.md

@@ -19,6 +19,7 @@
 - **Database agnostic** — ClickHouse, PostgreSQL, MySQL
 - **Idempotent** — resume from interruptions, no duplicate processing
 - **CLI** — `dtk init`, `dtk run --select`, `dtk unlock`, `dtk clean`, tag-based selectors
+- **AI-native onboarding** — `dtk init-claude` sets up Claude Code context (CLAUDE.md + rules + a metric-scaffolding skill) so an assistant can help you build metrics out of the box
 
 ## Installation
 
@@ -42,6 +43,10 @@ pip install detectkit[all-db]       # All databases
 dtk init my_monitoring
 cd my_monitoring
 
+# Optional: set up Claude Code context so an AI assistant can help you
+# write metrics, tune detectors and configure alerts (re-run after upgrades)
+dtk init-claude
+
 # Configure database in profiles.yml, then:
 dtk run --select cpu_usage
 dtk run --select tag:critical

{detectkit-0.9.0 → detectkit-0.11.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.9.0"
+__version__ = "0.11.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

detectkit-0.11.0/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -0,0 +1,54 @@
+## detectkit — metric anomaly monitoring
+
+This workspace contains one or more **detectkit** projects. detectkit is a
+dbt-like Python tool for monitoring time-series metrics: each metric is a SQL
+query plus one or more anomaly **detectors** defined in YAML, run through a
+`load → detect → alert` pipeline with the `dtk` CLI. A directory is a detectkit
+project when it contains a `detectkit_project.yml` file.
+
+**Help the user operate detectkit**: create and edit metrics, tune detectors,
+configure alerting and channels, run the pipeline, and debug why an alert did
+(or didn't) fire. Stay numpy/SQL/YAML-first and follow the project's existing
+conventions.
+
+### Where to look (read the matching file before answering)
+
+The full, authoritative reference lives in `.claude/rules/detectkit/`. These
+files are generated by `dtk init-claude` and track the installed detectkit
+version — **read the relevant one on demand** instead of guessing:
+
+| If the task is about… | Read |
+|---|---|
+| What detectkit is, the pipeline, internal tables, glossary | `.claude/rules/detectkit/overview.md` |
+| `dtk` commands, selectors, backfills, locks, cleanup | `.claude/rules/detectkit/cli.md` |
+| `detectkit_project.yml`, `profiles.yml`, DB connections, channels | `.claude/rules/detectkit/project.md` |
+| A metric YAML: query, interval, seasonality, loading | `.claude/rules/detectkit/metrics.md` |
+| Choosing/tuning detectors, preprocessing, trends, seasonality | `.claude/rules/detectkit/detectors.md` |
+| Alert rules (quorum/direction/consecutive), cooldown, recovery, templates | `.claude/rules/detectkit/alerting.md` |
+
+### Set up & scaffold (skills)
+
+- **First-time setup** — use the **`dtk-setup-project`** skill to configure the
+  database connection in `profiles.yml` (the `dtk init` placeholder ships example
+  values that need your real connection details) and, optionally, a first alert
+  channel.
+- **A new metric** — use the **`dtk-new-metric`** skill; it walks the config out
+  to a YAML file that validates and is ready to run.
+
+### Gotchas that bite (keep these in mind)
+
+- **Every loading query MUST filter its time range** on `{{ dtk_start_time }}`
+  and `{{ dtk_end_time }}` (rendered as `'YYYY-MM-DD HH:MM:SS'`, so quote them).
+  Without it, incremental/batched loading cannot work.
+- **Metric `name` must be unique** across the whole project — it is the
+  database key, not the filename. Keep filename and `name` in sync.
+- **Changing a detector parameter changes the detector's identity** and
+  recomputes its detections from scratch; the old rows are orphaned. After
+  retuning a live metric, run `dtk clean --select <metric>` to prune them.
+- **`alert_cooldown` defaults to `null`** = a persisting anomaly re-alerts on
+  *every* `dtk run`. Always set a cooldown for production metrics.
+- The pipeline is **idempotent**: it resumes from the last saved timestamp.
+  Don't reprocess history unless you mean to (`--full-refresh` / `--from`).
+
+> Generated by `dtk init-claude`. Re-run it after upgrading detectkit to refresh
+> these instructions and the files under `.claude/rules/detectkit/`.

detectkit-0.11.0/detectkit/cli/assets/claude/rules/alerting.md

@@ -0,0 +1,192 @@
+# detectkit — Alerting
+
+detectkit is **alert-centric**: the *alert* is the primary entity and a detector
+anomaly is secondary evidence a rule interprets (the same anomaly means
+different things under different rules). Configure alerting per metric under
+`alerting:`. Channels themselves are defined in `profiles.yml` (see
+`project.md`).
+
+```yaml
+alerting:
+  enabled: true
+  channels: [mattermost_ops]
+  min_detectors: 1
+  direction: "same"
+  consecutive_anomalies: 3
+  alert_cooldown: "30min"
+```
+
+## The alert rule (quorum × direction × consecutive)
+
+At the alert step, detectkit looks at the most recent detections and applies one
+combined contract:
+
+1. **Quorum** — at each timestamp, group all detectors' anomalies. The point
+   satisfies the quorum when at least `min_detectors` of them match the
+   `direction` policy.
+2. **Consecutive** — an alert fires only when the latest `consecutive_anomalies`
+   timestamps each satisfy the quorum **and** are grid-adjacent (exactly one
+   `interval` apart). A missing detection row between two anomalies breaks the
+   chain.
+
+### `min_detectors` (default 1)
+
+How many detectors must qualify at **every** point in the chain. `1` = any one
+detector (high recall); `N` = all must agree (high precision).
+
+### `direction` (default `"same"`)
+
+Which anomalies count toward the quorum:
+
+- `"same"` — at the latest point, ≥`min_detectors` detectors must agree on **one**
+  direction (up and down counted separately — disagreement is not consensus).
+  The winning direction is **locked for the whole chain**. Ties: more detectors
+  win, then the more severe side.
+- `"any"` — every anomaly counts regardless of direction (1 up + 1 down
+  satisfies `min_detectors: 2`).
+- `"up"` — only anomalies above the interval count (others ignored, never block).
+- `"down"` — only anomalies below the interval count.
+
+Pick by meaning: `"up"` for CPU/error rate (high is bad), `"down"` for cache hit
+rate/uptime (low is bad), `"any"` for single-detector "any deviation matters",
+`"same"` for multi-detector consensus.
+
+### `consecutive_anomalies` (default 3)
+
+Grid-adjacent quorum points required before alerting. `1` = alert immediately
+(critical metrics); `3` = balanced; `5+` = noisy metrics. Gaps in the detection
+grid break the chain.
+
+### Worked example (two detectors A, B; `min_detectors: 2`)
+
+| `direction` | A | B | Result |
+|---|---|---|---|
+| `same` | up | down | no alert (disagreement) |
+| `same` | up | up | quorum; "up" locked for the chain |
+| `up` | up | down | no quorum (only one "up", needs 2) |
+| `down` | up | up | no quorum ("up" ignored) |
+| `any` | up | down | quorum (every anomaly counts) |
+
+## Cooldown (spam control) — **set it in production**
+
+`alert_cooldown` defaults to **`null` = no cooldown**, meaning a persisting
+anomaly re-alerts on **every** `dtk run` (e.g. every cron tick). Always set a
+cooldown for production metrics.
+
+```yaml
+alert_cooldown: "30min"            # or seconds: 1800
+cooldown_reset_on_recovery: true   # default — reset the timer when the metric recovers
+```
+
+- With `cooldown_reset_on_recovery: true` (recommended): alert on first
+  occurrence, suppress duplicates while it persists, alert again on a fresh
+  incident after recovery.
+- With `false` (strict): an absolute minimum time between any alerts, regardless
+  of recovery — for very noisy metrics.
+- No-data and anomaly alerts **share** the same cooldown state within an alert
+  block. State lives in `_dtk_alert_states`.
+
+## Recovery notifications
+
+```yaml
+notify_on_recovery: true        # default false
+template_recovery: null         # optional custom body
+```
+
+Sends one notification per incident when the metric returns to normal after an
+alert fired. **Direction-aware**: after a "down" alert, a fresh "up" anomaly
+does not block recovery (the original condition no longer holds). Independent of
+`alert_cooldown` (recovery always sends once per incident). Default body is
+alert-centric (`✅ Alert cleared: <metric>`).
+
+## No-data alerts
+
+```yaml
+no_data_alert: true             # default false
+template_no_data: null          # optional custom body
+```
+
+Fires when the **last complete interval** (now floored to a boundary, minus one
+interval) has no datapoint, or the row's value is `NULL`/`NaN`. `min_detectors`
+and `consecutive_anomalies` do **not** apply (it's a single binary signal).
+Honors `alert_cooldown` and `suppress_until`. Webhook channels render it amber.
+Use for cron loaders where source absence is a real failure; **don't** enable on
+naturally sparse metrics.
+
+## Temporary suppression
+
+```yaml
+suppress_until: "2026-04-11 18:00:00"   # UTC; default null
+```
+
+Load and detect keep running; only alerting is paused until that time, then it
+auto-resumes (no second edit needed). For permanent off, use `enabled: false`.
+
+## Mentions
+
+```yaml
+mentions: [oncall_engineer, here]   # plain names, no @
+```
+
+Channel-agnostic: you write plain usernames and each channel renders them
+natively. Special broadcast keywords: `here`, `channel`, `all`. Available as
+`{mentions}` / `{mentions_line}` template variables (appended automatically if
+not placed in a template). Slack `@username` is display-only — use Slack user
+IDs (`U…`) for real pings.
+
+## Multiple alert configs per metric
+
+`alerting:` may be a **list** of independent blocks, each with its own channels,
+timezone, template, and rule — evaluated and sent independently:
+
+```yaml
+alerting:
+  - {enabled: true, channels: [mattermost_ops], consecutive_anomalies: 3}
+  - {enabled: true, channels: [slack_critical], consecutive_anomalies: 1, direction: "up"}
+```
+
+Each block's state is keyed by a hash of its functional fields; editing those
+fields or removing a block orphans its `_dtk_alert_states` row (prune with
+`dtk clean`). Disabling with `enabled: false` keeps the hash, so a paused alert
+is never treated as orphaned.
+
+## Templates
+
+Defaults are alert-centric. Override with:
+- `template_single` — alerts with `consecutive_count` ≤ 1.
+- `template_consecutive` — streaks (`> 1`); falls back to `template_single`.
+- `template_recovery`, `template_no_data` — recovery / no-data bodies.
+
+Templates are plain `{var}` strings (or Jinja2 `.j2` files under `templates_dir`
+referenced by path). Key variables:
+
+| Variable | Meaning |
+|---|---|
+| `{metric_name}`, `{description}` / `{description_line}` | identity |
+| `{timestamp}`, `{timezone}` | when (display tz via `alerting.timezone`, default UTC) |
+| `{value}` / `{value_display}` | metric value (`value_display` is NaN-safe) |
+| `{confidence_lower}` / `{confidence_upper}` / `{confidence_interval}` | bounds |
+| `{expected_range}` | one-sided-aware band (`>= 7.00`, `<= 1.10`, `[lo, hi]`, `N/A`) |
+| `{detector_name}`, `{detector_count}` | who fired (`"N detectors"` for multi) |
+| `{min_detectors}` / `{direction_policy}` / `{consecutive_required}` | the configured rule |
+| `{direction}`, `{consecutive_count}`, `{severity}` | observed values |
+| `{status}` | `ANOMALY` / `RECOVERED` / `NO_DATA` / `ERROR` |
+| `{mentions}` / `{mentions_line}` | formatted mentions |
+
+> For no-data/error alerts there is no numeric value — avoid `{value:.2f}` in
+> those templates (detectkit falls back to the default template rather than
+> crashing, but write kind-appropriate templates).
+
+## Test, tune, debug
+
+```bash
+dtk test-alert <metric>     # mock alert through the real channels, using this rule
+```
+
+- **Too many alerts** → raise `consecutive_anomalies`, raise detector
+  `threshold`, use `min_detectors: 2`, add seasonality, or set a `direction`.
+- **No alerts** → check `enabled: true`, channels exist in `profiles.yml`,
+  detections exist (`dtk run --steps detect`), the quorum/consecutive thresholds
+  aren't too high, and `direction` isn't filtering the move out.
+- **Wrong direction** (alerting when CPU drops) → set `direction: "up"`.
+- Aim for **< 5 alerts/day/team** to avoid fatigue.

detectkit-0.11.0/detectkit/cli/assets/claude/rules/cli.md

@@ -0,0 +1,138 @@
+# detectkit — CLI (`dtk`)
+
+Run all commands from a project directory (the one containing
+`detectkit_project.yml`). `dtk --help` and `dtk <command> --help` always work.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `dtk init <name>` | Scaffold a new project directory |
+| `dtk init-claude` | (Re)generate this Claude context (CLAUDE.md + `.claude/rules/detectkit/` + skills) |
+| `dtk run --select <sel>` | Run the load → detect → alert pipeline |
+| `dtk test-alert <metric>` | Send a mock alert to the metric's channels |
+| `dtk unlock --select <sel>` | Clear a stuck pipeline lock |
+| `dtk clean --select <sel>` | Prune internal data that no longer matches the config |
+| `dtk --version` | Show installed detectkit version |
+
+## Selectors (`--select` / `-s`)
+
+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.
+- **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 "*" --exclude "metrics/staging/*"`). Metric names must be unique
+across the project; duplicates raise an error listing the conflicting files.
+
+## `dtk run`
+
+```bash
+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).
+- `--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.
+- `--full-refresh` — **destructive**: deletes the metric's datapoints and
+  detections, then reloads from `loading_start_time`/`--from`. Use after
+  changing the query or to recompute detections over history.
+- `--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).
+
+## `dtk test-alert <metric>`
+
+Sends a mock alert (fake value/CI/severity) through the metric's configured
+channels, using that alert config's own rule (`min_detectors` / `direction` /
+`consecutive_anomalies`), so the preview matches a real firing. Use it to
+verify webhook URLs, channel permissions, and custom templates.
+
+## `dtk unlock --select <sel>`
+
+Every run records a `running` lock in `_dtk_tasks` and clears it on exit. If a
+run is killed mid-flight (commonly the **DB restarting mid-run**), the lock is
+left behind and later non-`--force` runs fail with
+`Failed to acquire lock … Use --force`. `dtk unlock` clears it immediately
+without running the pipeline. (Stuck locks also auto-expire after ~1 hour, so
+the next normal run recovers on its own.)
+
+## `dtk clean`
+
+Editing metrics over time leaves stale rows in the internal tables. `dtk clean`
+removes that drift. **Both modes dry-run by default** — pass `--execute` to
+actually delete.
+
+- **Drift mode** — `dtk clean --select <sel>`: for each still-existing metric,
+  deletes `_dtk_detections` rows for `detector_id`s the config no longer
+  produces (you changed a detector param / `seasonality_components`, or removed
+  a detector), and `_dtk_alert_states` rows for alert blocks the config no
+  longer produces. Datapoints are never touched (keyed only by timestamp).
+- **GC mode** — `dtk clean --orphaned-metrics`: deletes all internal rows for
+  metric names present in the DB but no longer defined by any YAML (renamed or
+  deleted metrics). Ignores `--select`; asks for confirmation on `--execute`
+  unless `-y/--yes`; refuses to run if the project defines no metrics or configs
+  fail to parse (so a wrong directory can't wipe valid data).
+
+## Common workflows
+
+```bash
+# First run of a metric
+dtk run --select my_metric
+
+# Cron loop (every interval)
+dtk run --select "*"
+dtk run --select "tag:critical"
+
+# Backfill history
+dtk run --select my_metric --from "2024-01-01"
+dtk run --select my_metric --from "2024-01-01" --to "2024-02-01"
+
+# Reprocess after config changes
+dtk run --select my_metric --full-refresh                 # query changed → reload
+dtk run --select my_metric --steps detect --full-refresh  # detector changed → recompute detections
+dtk clean --select my_metric                              # then prune orphaned old detector/alert rows
+dtk clean --select my_metric --execute
+
+# Debug
+dtk run --select my_metric --steps load     # does the query return data?
+dtk run --select my_metric --steps detect    # does the detector fire?
+dtk test-alert my_metric                      # do the channels work?
+
+# Recover a stuck lock
+dtk unlock --select my_metric
+```
+
+## Scheduling
+
+detectkit has no built-in scheduler — drive `dtk run` from cron / systemd
+timers / Windows Task Scheduler. Always `cd` into the project first:
+
+```cron
+*/10 * * * * cd /path/to/project && dtk run --select "*" >> /var/log/detectkit.log 2>&1
+```
+
+Pair scheduling with `error_alerting` (in `detectkit_project.yml`) so in-process
+failures page someone; cron monitoring covers `dtk run` not running at all.
+
+## Troubleshooting
+
+- **"Metric not found"** — selector doesn't match. Use the bare name
+  (`cpu_usage`, not `cpu_usage.yml`) for root metrics; check `ls metrics/`.
+- **"Failed to acquire lock"** — a crashed run left a lock. `dtk unlock --select <m>`
+  (or wait ~1h for auto-expiry).
+- **"Connection refused"** — check `profiles.yml` and DB connectivity.
+- **"No data loaded"** — run the query manually with sample dates; verify the
+  `{{ dtk_start_time }}` / `{{ dtk_end_time }}` filter.
+- **All points "insufficient_data"** — not enough history before `min_samples`;
+  lower `min_samples`, or backfill more history with `--from`.

detectkit-0.11.0/detectkit/cli/assets/claude/rules/detectors.md

@@ -0,0 +1,193 @@
+# detectkit — Detectors
+
+A metric's `detectors:` is a list; each entry runs independently and writes its
+own detection rows. A detector flags points whose value falls outside an
+expected confidence interval it computes from history.
+
+```yaml
+detectors:
+  - type: mad
+    params:
+      threshold: 3.0
+      window_size: 288
+```
+
+## Choosing a detector
+
+| Detector | Use when | Robust to outliers | Seasonality |
+|---|---|---|---|
+| `manual_bounds` | You know the acceptable bounds (SLA, hard limit) | n/a | no |
+| `mad` | General-purpose default; outliers / non-normal data | yes | yes |
+| `zscore` | Clean, normally distributed data | no | yes |
+| `iqr` | Skewed distributions, percentile metrics (p95/p99) | yes | yes |
+
+Quick decision: known bounds → `manual_bounds`; seasonal → `mad` with
+`seasonality_components`; normal & clean → `zscore`; skewed/heavy-tailed →
+`mad` or `iqr`; unsure → `mad`.
+
+You can combine detectors — e.g. a `manual_bounds` hard cap plus a `mad`
+pattern detector. The alerting `min_detectors` quorum then decides how many
+must agree (see `alerting.md`).
+
+## `manual_bounds`
+
+Fixed thresholds, no window, instant (no warm-up). Supports `input_type` only.
+
+```yaml
+- type: manual_bounds
+  params:
+    upper_bound: 90.0     # alert when value > 90
+    lower_bound: 0.8      # alert when value < 0.8  (use either or both)
+```
+
+## Windowed detectors (`mad`, `zscore`, `iqr`)
+
+These three **share one implementation** and accept an identical parameter set.
+Each computes statistics over a trailing window (current point excluded) and an
+expected interval for the current point.
+
+```yaml
+- type: mad                  # same params for zscore / iqr
+  params:
+    # --- core (all participate in the detector_id hash) ---
+    threshold: 3.0           # defaults: mad 3.0, zscore 3.0, iqr 1.5
+    window_size: 100         # trailing window in points
+    min_samples: 30          # min valid points in window before detection runs
+    seasonality_components: null   # e.g. ["hour"] or [["hour","day_of_week"]]
+    min_samples_per_group: 10      # defaults: mad 10, zscore 3, iqr 4
+    input_type: values       # values | changes | absolute_changes | log_changes
+    smoothing: null          # null | ema | sma
+    smoothing_alpha: 0.3     # EMA factor, 0 < a <= 1
+    smoothing_window: 10     # SMA window in points
+    window_weights: null     # null (uniform) | exponential | linear
+    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
+    batch_size: 500
+```
+
+**Threshold semantics:**
+- `mad` is scaled by the normal-consistency constant 1.4826, so `threshold` is
+  in **σ-equivalents** — `3.0` ≈ 3-sigma, just like `zscore`. Lower = more
+  sensitive.
+- `zscore`: `threshold` = number of standard deviations (3.0 ≈ 99.7%).
+- `iqr`: `threshold` = Tukey fence multiplier (1.5 = standard outliers, 3.0 =
+  extreme only).
+
+**Window sizing:** for non-seasonal metrics 100–500 points; for seasonal
+metrics size the window to contain several full cycles (10-min data: 4320–8640
+≈ 30–60 days; hourly: 672–2016 ≈ 1–3 weeks; daily: 60–90). `min_samples` ≈
+10–30% of `window_size`.
+
+## Seasonality grouping
+
+Statistics are computed within seasonality buckets so peak vs off-peak get
+different expected ranges. Component names must match the metric's seasonality
+feature names (built-in `seasonality_columns` or query-provided — see
+`metrics.md`).
+
+```yaml
+seasonality_components:
+  - "hour"                   # 24 separate per-hour adjustments
+  # - ["hour", "day_of_week"]  # one combined group per hour+day (168 groups)
+```
+
+- `["hour"]` — single component (24 groups).
+- `["hour", "day_of_week"]` — two *separate* adjustments.
+- `[["hour", "day_of_week"]]` — one *combined* group per pair.
+
+`min_samples_per_group` is the floor of points required per bucket.
+
+## Preprocessing — `input_type`
+
+Detect on transformed values (applied after smoothing):
+
+- `values` (default) — raw values; absolute thresholds meaningful (CPU%, latency).
+- `absolute_changes` — `v[t] - v[t-1]`; sudden jumps/drops matter.
+- `changes` — `(v[t] - v[t-1]) / v[t-1]`; relative moves (traffic, revenue).
+- `log_changes` — `log1p(v[t]) - log1p(v[t-1])`; near-symmetric for big % moves,
+  tolerates zeros (values must be > −1).
+
+The first point has no predecessor → NaN; the detect context pulls one extra
+point to compensate.
+
+## Smoothing
+
+Reduce noise before detection: `smoothing: sma` (`smoothing_window`) or
+`smoothing: ema` (`smoothing_alpha`, higher = less smoothing). Trade-off: less
+noise but reduced sensitivity to short spikes.
+
+## Trending metrics (avoid alert spam)
+
+A gradual trend drifts a uniform window's interval behind the current level, so
+every point starts to look "below" → false alerts. Two shared params fix this:
+
+- `window_weights: exponential` + `half_life: "3d"` — recent points weigh more,
+  so the interval follows the new normal. `half_life` is the age at which a
+  point's weight halves (int = points; `"3d"`/`"12h"` converted via the grid
+  step; default `window_size/20`). `linear` weighting is also available.
+- `detrend: linear` — removes a robust in-window linear trend before computing
+  statistics; gradual drift no longer pulls the metric out of its interval,
+  while sharp deviations are still caught.
+
+**Recommended recipe for trending, seasonal metrics:**
+```yaml
+seasonality_columns: [hour]
+detectors:
+  - type: mad
+    params:
+      window_size: 8640
+      min_samples: 1000
+      seasonality_components: ["hour"]
+      window_weights: exponential
+      half_life: "3d"
+      detrend: linear          # optional, on top of weighting
+```
+Trade-off: a shorter `half_life` adapts faster but also "accepts" a real
+sustained degradation as the new normal sooner. (`weight_decay` is a deprecated
+alias for `half_life`; prefer `half_life`.)
+
+## Feature compatibility
+
+| Feature | mad | zscore | iqr | manual_bounds |
+|---|---|---|---|---|
+| `input_type` | ✅ | ✅ | ✅ | ✅ |
+| `smoothing` | ✅ | ✅ | ✅ | ❌ |
+| `window_weights` / `half_life` | ✅ | ✅ | ✅ | ❌ |
+| `detrend` | ✅ | ✅ | ✅ | ❌ |
+| `seasonality_components` | ✅ | ✅ | ✅ | ❌ |
+
+`manual_bounds` has no window, so window-based features don't apply.
+
+## Detector identity & recomputation
+
+Every parameter that affects results (threshold, window_size, min_samples,
+seasonality_components, min_samples_per_group, input_type, smoothing*,
+window_weights, half_life, detrend) is hashed into the `detector_id` — only
+non-default values participate. Execution params (`start_time`, `batch_size`)
+are **not** hashed.
+
+Changing any hashed parameter creates a new `detector_id` and recomputes that
+detector's detections from scratch on the next run; old rows stay under the
+previous id. To recompute over history immediately:
+`dtk run --select <m> --steps detect --full-refresh`. To prune the orphaned old
+rows: `dtk clean --select <m> --execute`.
+
+Parameters are validated when the detector is constructed at the start of the
+`detect` step (per run, not at YAML load) — a typo like `input_type: "diff"`
+fails fast with a clear error.
+
+## Tuning
+
+- Too many false positives → raise `threshold`, add seasonality, add
+  `window_weights`/`detrend` for trends, or raise `consecutive_anomalies` in
+  alerting.
+- Missing real anomalies → lower `threshold`, lower `window_size`, lower
+  `consecutive_anomalies`/`min_detectors`.
+- All "insufficient_data" → lower `min_samples` or backfill more history.
+
+Detection metadata records what the detector saw (`global_median`,
+`adjusted_median`, `ess` = Kish effective sample size when weighting,
+`trend_slope_per_point` when detrending, and a `preprocessing` block) — useful
+for debugging.