detectkit 0.49.2__tar.gz → 0.50.0__tar.gz

{detectkit-0.49.2/detectkit.egg-info → detectkit-0.50.0}/PKG-INFO

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

{detectkit-0.49.2 → detectkit-0.50.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.49.2"
+__version__ = "0.50.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -40,7 +40,7 @@ version — **read the relevant one on demand** instead of guessing:
 | Alert rules (quorum/direction/consecutive), cooldown, recovery, templates | `.claude/rules/detectkit/alerting.md` |
 | Auto-tuning a detector (`dtk autotune`), labels file, the `autotune:` block, `_dtk_autotune_runs` | `.claude/rules/detectkit/autotune.md` |
 | Manually/interactively tuning a detector in the browser and writing it back in place (`dtk tune`) | `.claude/rules/detectkit/cli.md` |
-| A project-wide live overview + driving the pipeline from the browser (`dtk ui`) | `.claude/rules/detectkit/cli.md` |
+| A project-wide live overview, driving the pipeline, and creating/editing/deleting metric YAMLs from the browser (`dtk ui`) | `.claude/rules/detectkit/cli.md` |
 | OSI (Open Semantic Interchange) interop: import an OSI metric into a native metric / export back (`dtk osi`) | `.claude/rules/detectkit/cli.md` |
 
 ### Skills

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -12,7 +12,7 @@ Run all commands from a project directory (the one containing
 | `dtk run --select <sel>` | Run the load → detect → alert pipeline |
 | `dtk autotune --select <sel>` | Auto-configure a metric's detector (see `autotune.md`) |
 | `dtk tune --select <sel>` | Interactively tune a detector on real data, write it back in place |
-| `dtk ui` | Project-wide live overview + browser pipeline control panel |
+| `dtk ui` | Project-wide live overview + browser pipeline control panel + create/edit/delete metric YAMLs |
 | `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 |
@@ -210,6 +210,32 @@ its own isolated, lock-free session. The `dtk ui` server itself takes **no
 pipeline lock** and never mutates anything — every spawned command behaves
 exactly as if typed into a terminal.
 
+### Managing metrics from the UI
+
+The cockpit header has a **New metric** button — an editor overlay seeded
+with a starter YAML template, with an optional subfolder under `metrics/`;
+saving writes `metrics/[<folder>/]<name>.yml`. Every metric row also has an
+**Edit** action that opens its raw YAML in the same editor. **Save** validates
+server-side **before any write**: YAML syntax → full `MetricConfig` → a deep
+detector-params check (each factory-known detector is actually constructed) —
+an invalid config lands in the editor's error pane with nothing written. A
+successful save **archives the previous file verbatim** to
+`metrics/.history/<metric>/` (the same archive `dtk tune`'s Apply writes,
+excluded from metric discovery) and only then overwrites in place, so the
+text typed is what lands on disk, comments intact (normalized only to end
+with a newline). A save is refused when the file changed on disk after the
+editor was opened (a `dtk tune` Apply or another session saved first) —
+reopen the metric rather than overwrite it. Renaming via `name:`
+is allowed — uniqueness is enforced project-wide — and rows under the old name
+stay in the `_dtk_*` tables until `dtk clean`. **Delete** lives in the edit
+overlay behind an explicit confirmation step, and the server additionally
+requires the request to echo the metric name back; it archives the file
+(`…-deleted.yml`) before removing it, so a delete is reversible by hand, and
+its `_dtk_*` rows likewise remain until `dtk clean`. While a `dtk tune` session
+for that metric is running, Save and Delete are refused (its Apply would race
+the edit). Like the rest of `dtk ui`, metric management takes no pipeline lock
+and never touches the database — it only manages metric YAML files.
+
 ## `dtk test-alert <metric>`
 
 Sends a mock alert (fake value/CI/severity) through the metric's configured

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/cli/assets/claude/rules/overview.md

@@ -97,6 +97,12 @@ series, watch the band recompute live, then write the config back into the metri
 — use `dtk tune --select <m>`, the interactive sibling of `dtk autotune`
 (`cli.md`).
 
+For a **live**, project-wide view instead of a one-off file, run `dtk ui`: the
+same reports in a browser overlay plus an overview table (alert frequency,
+freshness, quality when incidents are labeled), a panel that drives
+`dtk run` / `dtk autotune` / `dtk unlock`, and an in-browser editor to create,
+edit and delete metric YAML files. See `cli.md`.
+
 ## Glossary
 
 - **metric** — a named time series (SQL + interval) you monitor.

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/cli/assets/claude/skills/dtk-new-metric/SKILL.md

@@ -15,6 +15,14 @@ need detail on any field, read the matching file under
 `.claude/rules/detectkit/` (`metrics.md`, `detectors.md`, `alerting.md`,
 `project.md`); this skill is the procedure, those are the reference.
 
+`dtk ui` also has a browser editor for metric YAMLs (a **New metric** button
+and, per row, an **Edit** action), validated the same way before it writes.
+Prefer this skill when scaffolding from scratch — it gathers the query,
+detector and alerting choices and explains each one in context; prefer the UI
+for a quick manual edit while you're already watching the cockpit (nudging a
+threshold, adding a channel) — it's a raw-YAML editor with no procedure behind
+it.
+
 ## Step 0 — Confirm you're in a detectkit project
 
 A project root contains `detectkit_project.yml`. Verify it exists in the target

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/config/metric_config.py

@@ -890,8 +890,9 @@ class MetricConfig(BaseModel):
         if not data:
             raise ValueError(f"Empty metric config file: {path}")
 
-        # Support nested structure: metric: { ... }
-        if "metric" in data and isinstance(data["metric"], dict):
-            data = data["metric"]
+        # Support nested structure: metric: { ... } (shared unwrap seam)
+        from detectkit.config.metric_io import unwrap_metric_mapping
+
+        data = unwrap_metric_mapping(data)
 
         return cls.model_validate(data)

detectkit-0.50.0/detectkit/config/metric_io.py

@@ -0,0 +1,90 @@
+"""Shared low-level seams for metric YAML files.
+
+Three tiny helpers that were previously re-implemented per caller and had
+already started to drift (``tuning/config_writer.py``'s archive write had no
+same-second collision handling; the nested-form unwrap lived in four copies):
+
+- :func:`unwrap_metric_mapping` — the nested ``metric: {...}`` form accepted
+  everywhere a metric YAML is read (``MetricConfig.from_yaml_file``, the tune
+  write-back, the ``dtk ui`` editor).
+- :func:`safe_metric_stem` — a metric name reduced to one safe path component
+  (filenames, ``.history`` archive keys).
+- :func:`archive_metric_text` — the ``metrics/.history/<metric>/`` verbatim
+  archive convention shared by ``dtk tune``'s Apply and ``dtk ui``'s
+  update/delete, collision-safe within one UTC second.
+
+No imports from the rest of detectkit — safe to use from any layer.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_SAFE_CHAR_RE = re.compile(r"[A-Za-z0-9_.\-]")
+
+
+def unwrap_metric_mapping(data: dict[str, Any]) -> dict[str, Any]:
+    """The metric body of a parsed YAML mapping — unwraps the nested ``metric: {...}`` form.
+
+    Returns the **same object reference** for the flat form and the nested
+    body for the wrapped form, so in-place mutations (the tune write-back
+    edits the body inside the original document) behave identically.
+    """
+    nested = data.get("metric")
+    return nested if isinstance(nested, dict) else data
+
+
+def safe_metric_stem(name: str) -> str:
+    """A single safe path component for a metric name — sanitized, never refused.
+
+    ``MetricConfig`` accepts names (unicode letters, a leading ``-``) that make
+    unsafe or awkward filenames; rather than rejecting a valid metric, every
+    character outside the safe set is replaced with ``_`` and leading dots or
+    dashes are stripped. Path separators can never survive, so the result is
+    always one component; a same-stem collision surfaces as "file already
+    exists". Used for created files' stems and ``.history`` archive keys.
+    """
+    stem = "".join(c if _SAFE_CHAR_RE.fullmatch(c) else "_" for c in name)
+    stem = stem.lstrip(".-")
+    return stem or "metric"
+
+
+def metric_stamp(now: datetime | None = None) -> str:
+    """UTC filesystem-safe timestamp (``20260709T101530Z``) used in archive filenames."""
+    now = now or datetime.now(timezone.utc)
+    return now.strftime("%Y%m%dT%H%M%SZ")
+
+
+def archive_metric_text(
+    project_root: Path,
+    metric_name: str,
+    text: str,
+    *,
+    suffix: str = "",
+    stamp: str | None = None,
+    now: datetime | None = None,
+) -> Path:
+    """Write *text* verbatim into ``metrics/.history/<key>/`` and return the path.
+
+    The directory key is the **sanitized** metric name (:func:`safe_metric_stem`)
+    — at archive time the name can be attacker/editor-influenced free text
+    (an on-disk ``name:`` changed after boot), and joining it raw into a path
+    would let ``../`` or an absolute component escape ``metrics/.history/``.
+    Two archives within the same UTC second get ``-1``, ``-2``, … suffixes so
+    a tune Apply and a UI save landing together never overwrite each other's
+    snapshot.
+    """
+    key = safe_metric_stem(metric_name)
+    archive_dir = project_root / "metrics" / ".history" / key
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    base = f"{key}-{stamp or metric_stamp(now)}{suffix}"
+    archive_path = archive_dir / f"{base}.yml"
+    counter = 1
+    while archive_path.exists():
+        archive_path = archive_dir / f"{base}-{counter}.yml"
+        counter += 1
+    archive_path.write_text(text, encoding="utf-8")
+    return archive_path

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/tuning/config_writer.py

@@ -18,13 +18,14 @@ others and, when an alert used ``min_detectors >= 2``, permanently killing it.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import datetime
 from pathlib import Path
 from typing import Any
 
 import yaml
 
 from detectkit.config.metric_config import MetricConfig
+from detectkit.config.metric_io import archive_metric_text, metric_stamp, unwrap_metric_mapping
 from detectkit.detectors.factory import DetectorFactory
 
 # The detector types the interactive tuner can emit: the windowed statistical
@@ -68,12 +69,6 @@ class AppliedConfig:
     preserved: tuple[str, ...] = ()
 
 
-def _stamp(now: datetime | None = None) -> str:
-    """UTC filesystem-safe timestamp (``20260624T101530Z``)."""
-    now = now or datetime.now(timezone.utc)
-    return now.strftime("%Y%m%dT%H%M%SZ")
-
-
 def _apply_consecutive(body: dict[str, Any], consecutive: int) -> None:
     """Set ``consecutive_anomalies`` on the metric's first alerting config.
 
@@ -192,9 +187,9 @@ def apply_tuned_config(
     if not isinstance(raw, dict):
         raise ValueError(f"metric config is empty or malformed: {original_path}")
 
-    # Support the nested `metric: { ... }` form (see MetricConfig.from_yaml_file).
-    nested = isinstance(raw.get("metric"), dict)
-    body: dict[str, Any] = raw["metric"] if nested else raw
+    # Support the nested `metric: { ... }` form (shared unwrap; the body is a
+    # reference into `raw`, so edits below land inside the original document).
+    body: dict[str, Any] = unwrap_metric_mapping(raw)
 
     existing = body.get("detectors")
     merged: list[Any] = list(existing) if isinstance(existing, list) else []
@@ -227,11 +222,10 @@ def apply_tuned_config(
     validated = MetricConfig.model_validate(body)
     metric_name = validated.name
 
-    stamp = _stamp(now)
-    archive_dir = project_root / "metrics" / ".history" / metric_name
-    archive_dir.mkdir(parents=True, exist_ok=True)
-    archive_path = archive_dir / f"{metric_name}-{stamp}.yml"
-    archive_path.write_text(original_text, encoding="utf-8")
+    stamp = metric_stamp(now)
+    # Shared, collision-safe archive seam (config/metric_io.py) — a UI save and
+    # this Apply landing in the same UTC second keep both snapshots.
+    archive_path = archive_metric_text(project_root, metric_name, original_text, stamp=stamp)
 
     try:
         archive_rel = str(archive_path.relative_to(project_root))

{detectkit-0.49.2 → detectkit-0.50.0}/detectkit/ui/__init__.py

@@ -3,9 +3,10 @@
 A localhost web UI over the already-persisted ``_dtk_*`` tables: an overview of
 every selected metric's alerting behavior (how often alerts fire, per metric /
 per tag / per ``metrics/`` folder), a per-metric detail view (the existing HTML
-report in an iframe), and a pipeline control panel that drives the existing CLI
+report in an iframe), a pipeline control panel that drives the existing CLI
 commands (``dtk run`` / ``dtk autotune`` / ``dtk unlock`` as subprocesses,
-``dtk tune`` launched per metric).
+``dtk tune`` launched per metric), and metric management — creating, editing
+and deleting metric YAML files from a browser editor.
 
 ``dtk ui`` is a *superstructure over existing dtk commands*: the server itself
 never runs the pipeline in-process and takes no pipeline lock — spawned ``dtk
@@ -20,6 +21,9 @@ numbers match what the pipeline would actually have alerted.
   pipeline control panel.
 - ``server.py`` — ``build_ui_server`` / ``serve_ui``: routes, token auth, the
   single ``db_lock`` serializing DB-touching requests.
+- ``metric_files.py`` — the metric-YAML create/update/delete seam: validate
+  before write, archive to ``metrics/.history/<metric>/`` before every
+  overwrite or delete.
 - ``html.py`` — ``render_ui_html``: inlines the committed ``assets/ui.js``
   renderer bundle + the boot payload into one self-contained page.
 """