detectkit 0.19.0__tar.gz → 0.20.0__tar.gz

{detectkit-0.19.0/detectkit.egg-info → detectkit-0.20.0}/PKG-INFO

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

{detectkit-0.19.0 → detectkit-0.20.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.19.0"
+__version__ = "0.20.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -11,6 +11,17 @@ 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.
 
+**Database access for _you_ (recommended, not required).** detectkit itself
+connects to the database directly via its drivers — it **never** needs an MCP to
+run. But you assist far better with **read access to the same database** (e.g. a
+database MCP for the project's ClickHouse / PostgreSQL / MySQL): you can inspect
+a metric's series, find real incidents to label for `dtk autotune`, sanity-check
+a metric query before running it, and confirm detections — instead of asking the
+user to run every query by hand. Without it, fall back to
+`dtk autotune --select <metric> --label` (a visual labeler) and to asking the
+user. This access is optional and separate from the `profiles.yml` connection
+detectkit uses for the pipeline.
+
 ### Where to look (read the matching file before answering)
 
 The full, authoritative reference lives in `.claude/rules/detectkit/`. These

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/assets/claude/rules/autotune.md

@@ -35,9 +35,12 @@ dtk autotune --select <sel> [--incidents FILE] [--label] [--scoring METRIC] \
              [--from DATE] [--to DATE] [--profile NAME] [--force] [--dry-run]
 ```
 
-- `--incidents FILE` — a labels file (below) → **supervised** tuning.
-- `--label` — emit a self-contained HTML chart of the series to mark incidents
-  visually; it exports a labels file. Generate-and-exit (no DB writes).
+- `--incidents FILE` — a labels file (below) → **supervised** tuning. With no
+  labels file, an interactive terminal prompts to enter incidents inline;
+  declining (or running non-interactively) tunes **unsupervised**.
+- `--label` — write a self-contained HTML chart of the series to
+  `metrics/<name>__labeler.html`; the user marks incidents in a browser and its
+  **Export** button downloads a labels file. Generate-and-exit (no DB writes).
 - `--scoring` — `mcc` (default), `f1`, `f_beta`, `balanced_accuracy`, `roc_auc`,
   `pr_auc`. MCC uses the whole confusion matrix and suits rare anomalies.
 - `--dry-run` — run the search but persist nothing and write no config.
@@ -76,14 +79,20 @@ autotune:
   detector_types: [mad, zscore]   # restrict candidates (subset of mad/zscore/iqr)
   scoring_metric: mcc             # default optimization target
   beta: 1.0                       # only for scoring_metric: f_beta
-  labels_file: incidents/orders.yml
+  labels_file: incidents/orders.yml   # external labels file, OR inline (below)
+  # incidents:                    # inline labels — mutually exclusive with labels_file
+  #   - {start: "2026-05-02 14:00:00", end: "2026-05-02 16:30:00", label: outage}
+  #   - {at: "2026-05-11 09:05:00", label: deploy spike}
+  # incidents_timezone: UTC       # interprets the naive times above (default UTC)
   seasonality_candidates: [hour, day_of_week]
   fixed_params: {window_size: 4320}  # pin hyperparameters (excluded from search)
   folds: 5
   max_history: 50000              # cap training points
 ```
 
-Precedence: `--scoring`/`--incidents` flags override the block.
+Label precedence (highest first): `--incidents` flag → `labels_file` → inline
+`incidents` → interactive prompt → none. `labels_file` and `incidents` are
+mutually exclusive. `--scoring` likewise overrides `scoring_metric`.
 
 ## The annotated config
 

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/assets/claude/skills/dtk-autotune/SKILL.md

@@ -57,10 +57,13 @@ If there are no extra signals, the built-ins are enough — continue.
 ## Step 2 — Gather incident history → write the labels file
 
 Supervised tuning needs known incidents. The labels file is the contract; you
-fill it from the user's plain-language description. Resolve each incident to
-**UTC** and classify it as an interval (`{start, end}`) for a sustained incident
-or a point (`{at}`) for a spike. Read the resolved times back to confirm, then
-write `incidents/<metric>.yml` (create `incidents/` beside `metrics/`):
+fill it from the user's plain-language description. (If you have read access to
+the database — e.g. a database MCP — query the metric's series yourself to spot
+candidate incidents and propose them for confirmation, rather than relying only
+on memory.) Resolve each incident to **UTC** and classify it as an interval
+(`{start, end}`) for a sustained incident or a point (`{at}`) for a spike. Read
+the resolved times back to confirm, then write `incidents/<metric>.yml` (the
+`dtk init` scaffold already created `incidents/` beside `metrics/`):
 
 ```yaml
 # incidents/<metric>.yml — known anomalies for supervised autotuning.
@@ -76,9 +79,24 @@ incidents:
     label: deploy spike
 ```
 
-The same schema works as JSON. If the user can't enumerate incidents, say so and
-go to Step 3 unsupervised — or offer `dtk autotune --select <name> --label` to
-get a clickable HTML chart they mark visually, which exports this exact file.
+The same schema works as JSON. **Inline alternative:** for just one or two
+incidents, declare the same entries directly under the metric's `autotune:` block
+(`incidents:` + optional `incidents_timezone:`) instead of a separate file —
+mutually exclusive with `labels_file`, and `--incidents` still overrides it:
+
+```yaml
+autotune:
+  incidents:
+    - {start: "2026-05-02 14:00:00", end: "2026-05-02 16:30:00", label: outage}
+    - {at: "2026-05-11 09:05:00", label: deploy spike}
+  incidents_timezone: UTC   # optional; default UTC
+```
+
+If the user can't enumerate incidents, say so and go to Step 3 unsupervised — or
+offer `dtk autotune --select <name> --label`, which writes a clickable HTML chart
+to `metrics/<name>__labeler.html`; they mark incidents in a browser and its
+Export button downloads a labels file in this exact format to feed back via
+`--incidents`.
 
 ## Step 3 — Run autotune
 

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/assets/claude/skills/dtk-setup-project/SKILL.md

@@ -38,6 +38,15 @@ the nearest ancestor that has it). If there is none, ask for a project name and
 run `dtk init <name>`, then work inside that folder. If several projects sit
 side by side, ask which one to set up.
 
+> **Recommended (optional): give _yourself_ read access to the database.**
+> detectkit connects to the DB directly via its drivers and never needs an MCP
+> to run — the `profiles.yml` connection you set up below is all the *tool*
+> needs. But you'll help much better with read access to the same database (e.g.
+> a database MCP): you can inspect metric series, find incidents to label for
+> `dtk autotune`, sanity-check queries, and confirm detections yourself. Suggest
+> the user connect one if they haven't; if they can't, you can still do
+> everything by asking them to run queries and by using `dtk autotune --label`.
+
 ## Step 1 — Pick the database backend
 
 **ClickHouse, PostgreSQL and MySQL are all fully supported.** Ask which one the

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/commands/autotune.py

@@ -101,7 +101,11 @@ def _resolve_labels(
     autotune_cfg: AutoTuneConfig,
     project_root: Path,
 ) -> tuple[IncidentLabels, str]:
-    """Resolve labels by precedence: --incidents > config.labels_file > interactive > none."""
+    """Resolve labels by precedence.
+
+    ``--incidents`` flag > config ``labels_file`` > config inline ``incidents`` >
+    interactive prompt > none (unsupervised).
+    """
     path = incidents_path or autotune_cfg.labels_file
     if path:
         file_path = Path(path)
@@ -112,6 +116,15 @@ def _resolve_labels(
         )
         return labels, f"file {file_path}"
 
+    if autotune_cfg.incidents:
+        labels = parse_incident_labels(
+            {"incidents": autotune_cfg.incidents, "timezone": autotune_cfg.incidents_timezone},
+            interval_seconds=interval_seconds,
+            metric_name=metric_name,
+        )
+        n = len(autotune_cfg.incidents)
+        return labels, f"inline config ({n} incident{'s' if n != 1 else ''})"
+
     if sys.stdin.isatty():
         return _prompt_labels(interval_seconds=interval_seconds), "interactive"
 

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/cli/commands/init.py

@@ -130,6 +130,48 @@ _BUCKET_SQL = {
     ),
 }
 
+# Example incidents (labels) file for supervised `dtk autotune`. Lives in
+# incidents/ beside metrics/; pointed at via `--incidents` or a metric's
+# `autotune.labels_file`. See docs/guides/autotuning.md.
+_EXAMPLE_INCIDENTS = """# Example incidents (labels) file for supervised `dtk autotune`.
+#
+# Tell autotune WHICH points were real incidents so it can pick the detector,
+# threshold, seasonality and alert window that catch them while keeping false
+# positives down. Hand it to autotune with:
+#
+#   dtk autotune --select example_cpu_usage --incidents incidents/example_cpu_usage.yml
+#
+# ...or reference it from the metric's `autotune.labels_file:` (see
+# metrics/example_cpu_usage.yml). Without any labels, autotune falls back to an
+# unsupervised objective (low false-positive rate + stable cross-fold separation).
+#
+# Format:
+# - YAML or JSON. ALL times are UTC unless `timezone:` says otherwise.
+# - Each incident is EITHER an interval ({start, end}) for a sustained problem
+#   OR a point ({at}) for a single spike — never both keys. `end` is inclusive.
+# - `label` is optional free text (documentation only).
+#
+# Tip: can't list incidents from memory? Run
+#   dtk autotune --select example_cpu_usage --label
+# to get a clickable HTML chart; mark incidents in a browser and export this file.
+
+# Optional — must match the metric `name:` it labels (autotune refuses a mismatch).
+metric: example_cpu_usage
+
+# Optional — interprets the naive times below (defaults to UTC).
+timezone: UTC
+
+incidents:
+  # Interval incident (a sustained problem):
+  - start: "2026-05-02 14:00:00"
+    end:   "2026-05-02 16:30:00"
+    label: example sustained spike      # optional, free text
+
+  # Point incident (a single anomalous timestamp):
+  - at: "2026-05-11 09:05:00"
+    label: example one-off spike
+"""
+
 # Alert-channel section (backend-independent); appended after the profiles.
 _ALERT_CHANNELS = """
 # Alert channels (referenced by name from a metric's alerting.channels)
@@ -190,7 +232,9 @@ def run_init(project_name: str, target_dir: str, db_type: str = "clickhouse"):
         ├── detectkit_project.yml
         ├── profiles.yml
         ├── metrics/
-        │   └── .gitkeep
+        │   └── example_cpu_usage.yml
+        ├── incidents/
+        │   └── example_cpu_usage.yml   # labels for supervised `dtk autotune`
         └── sql/
             └── .gitkeep
     """
@@ -216,12 +260,16 @@ def run_init(project_name: str, target_dir: str, db_type: str = "clickhouse"):
 
     # Create subdirectories
     (target_path / "metrics").mkdir(exist_ok=True)
+    (target_path / "incidents").mkdir(exist_ok=True)
     (target_path / "sql").mkdir(exist_ok=True)
 
-    # Create .gitkeep files
+    # Create .gitkeep files (incidents/ is kept by its example file below)
     (target_path / "metrics" / ".gitkeep").touch()
     (target_path / "sql" / ".gitkeep").touch()
 
+    # Example incidents (labels) file for supervised `dtk autotune`
+    (target_path / "incidents" / "example_cpu_usage.yml").write_text(_EXAMPLE_INCIDENTS)
+
     # Create detectkit_project.yml
     project_config = f"""# detectkit project configuration
 name: {project_name_clean}
@@ -337,6 +385,19 @@ alerting:
   no_data_alert: false        # alert when the latest interval has no data
   # alert_cooldown: "2h"      # recommended: suppress repeats of a persisting anomaly
 
+# Auto-tuning (optional) — `dtk autotune --select example_cpu_usage` picks the
+# detector config for you. Supply known incidents to tune supervised; either
+# point at a labels file OR declare them inline (the two are mutually exclusive).
+# autotune:
+#   enabled: true
+#   # (a) external labels file (see incidents/example_cpu_usage.yml):
+#   labels_file: incidents/example_cpu_usage.yml
+#   # (b) — or — inline incidents:
+#   # incidents:
+#   #   - {start: "2026-05-02 14:00:00", end: "2026-05-02 16:30:00", label: outage}
+#   #   - {at: "2026-05-11 09:05:00", label: deploy spike}
+#   # incidents_timezone: UTC   # interprets the naive times above (default UTC)
+
 # Tags for selection
 tags:
   - critical
@@ -368,6 +429,7 @@ detectkit monitoring project.
 - `detectkit_project.yml` - Project configuration
 - `profiles.yml` - Database connection profiles
 - `metrics/` - Metric definitions (YAML files)
+- `incidents/` - Labeled incidents for supervised `dtk autotune` (optional)
 - `sql/` - SQL query files (optional)
 
 ## Commands

{detectkit-0.19.0 → detectkit-0.20.0}/detectkit/config/metric_config.py

@@ -320,7 +320,11 @@ class AutoTuneConfig(BaseModel):
           detector_types: [mad, zscore]   # restrict candidates
           scoring_metric: mcc              # optimization target
           beta: 1.0                        # only for scoring_metric: f_beta
-          labels_file: incidents/orders.yml
+          labels_file: incidents/orders.yml   # external labels file, OR inline:
+          incidents:                          # inline labels (mutually exclusive)
+            - {start: "2026-05-02 14:00:00", end: "2026-05-02 16:30:00"}
+            - {at: "2026-05-11 09:05:00"}
+          incidents_timezone: UTC          # interprets the naive times above
           seasonality_candidates: [hour, day_of_week]
           fixed_params:                    # pinned, not searched
             window_size: 4320
@@ -344,6 +348,16 @@ class AutoTuneConfig(BaseModel):
     labels_file: str | None = Field(
         default=None, description="Project-relative path to a canonical labels file"
     )
+    incidents: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Inline labeled incidents (alternative to labels_file). Each entry is "
+        "{start, end} for a sustained incident or {at} for a single point; an optional "
+        "'label' is free-text documentation.",
+    )
+    incidents_timezone: str | None = Field(
+        default=None,
+        description="Timezone that interprets the naive times in `incidents` (default UTC)",
+    )
     seasonality_candidates: list[str] | None = Field(
         default=None, description="Restrict the seasonality columns the search may use"
     )
@@ -422,6 +436,34 @@ class AutoTuneConfig(BaseModel):
             raise ValueError("max_history must be at least 1")
         return v
 
+    @model_validator(mode="after")
+    def validate_inline_incidents(self) -> "AutoTuneConfig":
+        """Validate inline incidents: not alongside labels_file, and well-formed.
+
+        Reuses the canonical labels parser so an inline block is validated by the
+        same rules as a labels file (timestamp formats, interval-vs-point shape,
+        timezone), failing fast at config load.
+        """
+        if self.labels_file and self.incidents:
+            raise ValueError(
+                "Set either 'labels_file' or 'incidents', not both "
+                "(inline incidents and an external labels file are mutually exclusive)"
+            )
+        if self.incidents_timezone and not self.incidents:
+            raise ValueError("incidents_timezone has no effect without 'incidents'")
+        if self.incidents is not None:
+            # Local import to avoid a config <-> autotune import cycle at module load.
+            from detectkit.autotune.labels import parse_incident_labels
+
+            try:
+                parse_incident_labels(
+                    {"incidents": self.incidents, "timezone": self.incidents_timezone},
+                    interval_seconds=1,
+                )
+            except Exception as exc:  # ValueError, bad timezone (KeyError), etc.
+                raise ValueError(f"invalid 'incidents': {exc}") from exc
+        return self
+
 
 class MetricConfig(BaseModel):
     """

{detectkit-0.19.0 → detectkit-0.20.0/detectkit.egg-info}/PKG-INFO

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