detectkit 0.47.0__tar.gz → 0.49.0__tar.gz

{detectkit-0.47.0 → detectkit-0.49.0}/MANIFEST.in

@@ -5,6 +5,7 @@ recursive-include detectkit *.py
 recursive-include detectkit/cli/assets *.md
 recursive-include detectkit/reporting/assets *.js
 recursive-include detectkit/tuning/assets *.js
+recursive-include detectkit/ui/assets *.js
 recursive-exclude tests *
 recursive-exclude * __pycache__
 recursive-exclude * *.pyc

{detectkit-0.47.0/detectkit.egg-info → detectkit-0.49.0}/PKG-INFO

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

{detectkit-0.47.0 → detectkit-0.49.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.47.0"
+__version__ = "0.49.0"
 
 from detectkit.core.interval import Interval
 from detectkit.core.models import ColumnDefinition, TableModel

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/cli/assets/claude/CLAUDE.section.md

@@ -40,6 +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` |
 | 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.47.0 → detectkit-0.49.0}/detectkit/cli/assets/claude/rules/cli.md

@@ -12,6 +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 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 |
@@ -97,7 +98,14 @@ anomalies**) and the **y = 0** toggle — stay visible in every mode. The chart
 **zoomable** (scroll/drag + navigator strip) with a **"Points shown"** trim slider.
 Clicking **Apply** writes the chosen
 config back into the metric YAML **in place** (autotune, by contrast, writes a new
-`__tuned_<id>.yml` and never edits the original). Reads the metric's loaded
+`__tuned_<id>.yml` and never edits the original). Apply **merges** — it rewrites
+only the detector(s) you tuned and keeps every **other** detector unchanged, so a
+`manual_bounds` floor alongside a `mad` detector (and a `min_detectors: 2` alert)
+survives a retune. If a metric configures **more than one detector**, a **Tuning
+detector** picker in the Tune rail lets you choose which one to tune (the cockpit
+shows one band at a time); switching re-seeds every knob from that detector, and
+non-tunable detectors (`prophet`/`timesfm`) plus the ones you didn't touch are
+listed as "preserved on Apply". Reads the metric's loaded
 datapoints (run `dtk run --steps load` first if empty); the selector must resolve
 to a single metric.
 
@@ -155,12 +163,53 @@ relative to zero.
 
 Safe write-back: the config is validated before anything is written, the previous
 YAML is archived under `metrics/.history/<metric>/`, and only then is the metric
-overwritten. Takes **no pipeline lock** (it only edits a config file); re-run
-`dtk run` afterward to recompute detections under the new config.
+overwritten (the merge keeps your other detectors verbatim; the re-emitted header
+names what was updated vs preserved). The `.history/` archive is **not** discovered
+as a live metric, so a tuned metric never collides with its own snapshots as a
+"duplicate metric name". Takes **no pipeline lock** (it only edits a config file);
+re-run `dtk run` afterward to recompute detections under the new config.
 `--no-serve` writes a static read-only preview HTML instead (no write-back —
 **Save incidents** downloads the labels file); `--from` / `--to` bound the window;
 `--no-open` prints the URL without opening a browser.
 
+## `dtk ui`
+
+A **project-wide** localhost cockpit over every selected metric's alerting
+behavior — the live counterpart to a one-off `--report` file. Opens an
+**overview** table (grouped by `metrics/` subfolder, filterable by tag) with,
+per metric: alerts in the selected window + per-day rate + last alert,
+no-data events, anomaly rate, data freshness, and a sparkline — all
+**replayed** from stored detections through the same seam `dtk run --report`
+uses, so the counts match what the pipeline would actually have alerted.
+When `incidents/<metric>/` labels exist (from `dtk tune`'s Label/Review +
+Save incidents), the row also shows recall / false-alert rate / reviewed,
+matched the same way the `dtk tune` cockpit's metrics bar does; without
+labels the row still shows frequency stats to eyeball.
+
+```bash
+dtk ui [-s/--select "*"] [--window 24h|7d|30d|90d|all] [--profile NAME] [--no-open]
+```
+
+- `--select` — same selector syntax as `dtk run`; scopes which metrics the
+  overview and pipeline panel cover (default `*`, everything).
+- `--window` — the preset selected when the page opens (default `30d`);
+  switch freely in the browser afterward.
+- `--profile` — forwarded to the DB connection **and** to every subprocess
+  the pipeline panel spawns.
+- `--no-open` — print the URL instead of opening a browser tab.
+
+Clicking a metric's **Open** shows the existing self-contained HTML report
+(the same one `--report` writes) in an overlay. A **pipeline panel** drives
+the real CLI as subprocesses — `dtk run` (select/steps/from/to/force/
+full-refresh), `dtk autotune`, `dtk unlock` — streaming their terminal
+output live; **only one of these three runs at a time** (they'd contend for
+the same pipeline lock anyway). **Tune** launches `dtk tune --select
+<metric>` for a metric and opens its cockpit in a new tab — unlike
+run/autotune/unlock, **multiple tune jobs run concurrently**, since each is
+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.
+
 ## `dtk test-alert <metric>`
 
 Sends a mock alert (fake value/CI/severity) through the metric's configured

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/cli/assets/claude/skills/dtk-tune/SKILL.md

@@ -146,9 +146,17 @@ false-alert rate exceeds it (tuning-only; labeling stays optional).
 When the user is happy, they click **Apply to metric**. detectkit then, in order:
 **validates** the config (a bad/untunable config is rejected and **nothing is
 written**), **archives** the current YAML verbatim under
-`metrics/.history/<metric>/`, and **re-emits** the metric in place with the tuned
-detector (and updates the first alerting block's `consecutive_anomalies` if it has
-one). Applying ends the session; saving incidents does not.
+`metrics/.history/<metric>/`, and **re-emits** the metric in place, **merging** the
+tuned detector(s) back in (and updating the first alerting block's
+`consecutive_anomalies` if it has one). Applying ends the session; saving incidents
+does not. **Merge, not replace:** only the detector(s) the user tuned are
+rewritten; every other detector is kept **verbatim** — so a metric with a
+`manual_bounds` floor alongside a `mad` detector (and a `min_detectors: 2` alert)
+keeps both. When a metric has more than one detector, the Tune rail shows a
+**Tuning detector** picker to choose which one to tune. If the user asks to tune a
+metric that has several detectors, reassure them the others are preserved. (The
+`.history/` archive is not discovered as a live metric, so it never causes a
+"duplicate metric name" error.)
 
 ## Step 5 — Recompute under the new config
 

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/cli/commands/run.py

@@ -12,7 +12,11 @@ import click
 from detectkit.config.metric_config import MetricConfig
 from detectkit.config.profile import ProfilesConfig
 from detectkit.config.project_config import ProjectConfig
-from detectkit.config.validator import validate_metric_uniqueness
+from detectkit.config.validator import (
+    discover_metric_files,
+    is_discoverable_metric_file,
+    validate_metric_uniqueness,
+)
 from detectkit.database.internal_tables import InternalTablesManager
 from detectkit.orchestration.error_dispatch import dispatch_project_error_alert
 from detectkit.orchestration.task_manager import PipelineStep, TaskManager
@@ -433,17 +437,16 @@ def select_metrics(selector: str, project_root: Path) -> list[tuple[Path, Metric
         if selector == "*":
             # "all metrics" — search recursively so nested metrics are included
             # (mirrors validate_project_metrics); a plain glob of "metrics/*"
-            # would only see the top level.
-            metric_paths = [p for sub in ("**/*.yml", "**/*.yaml") for p in metrics_dir.glob(sub)]
+            # would only see the top level. Excludes the metrics/.history/ archive.
+            metric_paths = discover_metric_files(metrics_dir)
         else:
             pattern = selector if selector.startswith("metrics/") else f"metrics/{selector}"
             # Keep only metric files: a bare glob also matches the `.gitkeep`
-            # stub created by `dtk init`, any other non-YAML files, and
-            # directories — all of which would crash the YAML parser.
+            # stub created by `dtk init`, any other non-YAML files, directories, and
+            # the metrics/.history/ archive dtk tune writes (whose snapshots keep the
+            # original name:) — all of which would crash the parser or collide on name.
             metric_paths = [
-                p
-                for p in project_root.glob(pattern)
-                if p.is_file() and p.suffix in (".yml", ".yaml")
+                p for p in project_root.glob(pattern) if is_discoverable_metric_file(p, metrics_dir)
             ]
     # Metric name selector
     else:
@@ -485,26 +488,25 @@ def find_metrics_by_tag(metrics_dir: Path, tag: str) -> list[Path]:
 
     matching_metrics = []
 
-    # Search both .yml and .yaml extensions (consistent with find_metric_by_name)
-    for pattern in ["**/*.yml", "**/*.yaml"]:
-        for metric_file in metrics_dir.glob(pattern):
-            try:
-                with open(metric_file) as f:
-                    config = yaml.safe_load(f)
-
-                if config and "tags" in config:
-                    if tag in config["tags"]:
-                        matching_metrics.append(metric_file)
-            except Exception as e:
-                # Warn about unparseable files but continue searching
-                click.echo(
-                    click.style(
-                        f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
-                        fg="yellow",
-                    ),
-                    err=True,
-                )
-                continue
+    # Live metric files only (excludes the metrics/.history/ archive).
+    for metric_file in discover_metric_files(metrics_dir):
+        try:
+            with open(metric_file) as f:
+                config = yaml.safe_load(f)
+
+            if config and "tags" in config:
+                if tag in config["tags"]:
+                    matching_metrics.append(metric_file)
+        except Exception as e:
+            # Warn about unparseable files but continue searching
+            click.echo(
+                click.style(
+                    f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            continue
 
     return matching_metrics
 
@@ -522,25 +524,24 @@ def find_metric_by_name(metrics_dir: Path, name: str) -> Path | None:
     """
     import yaml
 
-    # Search both .yml and .yaml extensions
-    for pattern in ["**/*.yml", "**/*.yaml"]:
-        for metric_file in metrics_dir.glob(pattern):
-            try:
-                with open(metric_file) as f:
-                    config = yaml.safe_load(f)
-
-                if config and config.get("name") == name:
-                    return metric_file
-            except Exception as e:
-                # Warn about unparseable files but continue searching
-                click.echo(
-                    click.style(
-                        f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
-                        fg="yellow",
-                    ),
-                    err=True,
-                )
-                continue
+    # Live metric files only (excludes the metrics/.history/ archive).
+    for metric_file in discover_metric_files(metrics_dir):
+        try:
+            with open(metric_file) as f:
+                config = yaml.safe_load(f)
+
+            if config and config.get("name") == name:
+                return metric_file
+        except Exception as e:
+            # Warn about unparseable files but continue searching
+            click.echo(
+                click.style(
+                    f"Warning: Skipping {metric_file.relative_to(metrics_dir.parent)}: {e}",
+                    fg="yellow",
+                ),
+                err=True,
+            )
+            continue
 
     return None
 

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/cli/commands/tune.py

@@ -153,6 +153,11 @@ def run_tune(
         return False
 
     click.echo(f"  Archived previous config: {applied.archived.relative_to(project_root)}")
-    echo_done(f"{name}: applied tuned detector → {applied.saved.relative_to(project_root)}")
+    updated = ", ".join(applied.updated) or "detector"
+    echo_done(
+        f"{name}: applied tuned detector(s) [{updated}] → {applied.saved.relative_to(project_root)}"
+    )
+    if applied.preserved:
+        click.echo(f"  Preserved the metric's other detector(s): {', '.join(applied.preserved)}")
     click.echo(f"  Re-run `dtk run --select {name}` to recompute detections under the new config.")
     return True

detectkit-0.49.0/detectkit/cli/commands/ui.py

@@ -0,0 +1,97 @@
+"""``dtk ui`` — the project-level monitoring cockpit.
+
+Opens a localhost web UI over the already-persisted ``_dtk_*`` tables: an
+overview of every selected metric's alerting behavior, a per-metric detail
+view (the existing HTML report in an iframe), and a pipeline control panel
+that drives the real ``dtk run`` / ``dtk autotune`` / ``dtk unlock`` / ``dtk
+tune`` commands as subprocesses. Like ``dtk tune`` it takes no pipeline lock —
+it only reads the internal tables and spawns other ``dtk`` invocations, each
+of which takes its own lock exactly as if run from the terminal.
+"""
+
+from __future__ import annotations
+
+import click
+
+from detectkit.cli.commands.run import find_project_root, select_metrics
+from detectkit.config.profile import ProfilesConfig
+from detectkit.config.project_config import ProjectConfig
+from detectkit.database.internal_tables import InternalTablesManager
+from detectkit.ui.overview import ALL_WINDOW_PRESETS
+from detectkit.ui.server import serve_ui
+
+
+def run_ui(
+    *,
+    select: str = "*",
+    profile: str | None = None,
+    window: str = "30d",
+    no_open: bool = False,
+) -> None:
+    """Bootstrap the project and serve the cockpit until Ctrl-C."""
+    if window not in ALL_WINDOW_PRESETS:
+        allowed = ", ".join(sorted(ALL_WINDOW_PRESETS))
+        click.echo(
+            click.style(
+                f"Error: invalid --window '{window}'. Choose one of: {allowed}.",
+                fg="red",
+                bold=True,
+            )
+        )
+        raise SystemExit(1)
+
+    project_root = find_project_root()
+    if not project_root:
+        click.echo(click.style("Error: Not in a detectkit project directory!", fg="red", bold=True))
+        click.echo("Run 'dtk init <project_name>' to create a new project.")
+        raise SystemExit(1)
+
+    click.echo(f"Project root: {project_root}")
+
+    try:
+        project_config = ProjectConfig.from_yaml_file(project_root / "detectkit_project.yml")
+    except Exception as exc:
+        click.echo(click.style(f"Error loading detectkit_project.yml: {exc}", fg="red", bold=True))
+        raise SystemExit(1) from exc
+
+    try:
+        metrics = select_metrics(select, project_root)
+    except ValueError as exc:
+        click.echo(click.style(f"Error: {exc}", fg="red", bold=True))
+        raise SystemExit(1) from exc
+    if not metrics:
+        click.echo(click.style(f"No metrics found matching selector: {select}", fg="yellow"))
+        raise SystemExit(1)
+    metrics = sorted(metrics, key=lambda item: str(item[0]))
+
+    profiles_path = project_root / "profiles.yml"
+    if not profiles_path.exists():
+        click.echo(click.style("Error: profiles.yml not found!", fg="red", bold=True))
+        click.echo(f"Expected at: {profiles_path}")
+        raise SystemExit(1)
+
+    try:
+        profiles_config = ProfilesConfig.from_yaml(profiles_path)
+        db_manager = profiles_config.create_manager(profile)
+        internal_manager = InternalTablesManager(db_manager)
+        internal_manager.ensure_tables()
+    except Exception as exc:
+        click.echo(click.style(f"Error connecting to the database: {exc}", fg="red", bold=True))
+        raise SystemExit(1) from exc
+
+    click.echo(click.style(f"detectkit UI: {project_config.name}", fg="cyan", bold=True))
+    click.echo(f"  {len(metrics)} metric(s) covered by --select {select} (window: {window})")
+
+    try:
+        serve_ui(
+            project_config=project_config,
+            project_root=project_root,
+            metrics=metrics,
+            internal_manager=internal_manager,
+            initial_window=window,
+            profile=profile,
+            echo=click.echo,
+            open_browser=not no_open,
+        )
+    except KeyboardInterrupt:
+        pass

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/cli/main.py

@@ -307,6 +307,60 @@ def autotune(
     )
 
 
+@cli.command()
+@click.option(
+    "--select",
+    "-s",
+    default="*",
+    show_default=True,
+    help="Selector for the metrics the UI covers (metric name, path, or tag)",
+)
+@click.option(
+    "--profile",
+    help="Profile to use (default: from project config)",
+)
+@click.option(
+    "--window",
+    default="30d",
+    show_default=True,
+    help="Initial window preset: 24h, 7d, 30d, 90d, or all",
+)
+@click.option(
+    "--no-open",
+    is_flag=True,
+    help="Don't auto-open the browser (just print the local URL)",
+)
+def ui(select: str, profile: str, window: str, no_open: bool) -> None:
+    """
+    Open the project-level monitoring cockpit.
+
+    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 runs
+    `dtk run` / `dtk autotune` / `dtk unlock` / `dtk tune` as subprocesses —
+    exactly as if typed at a terminal. Alert counts are replayed from stored
+    detections, so the numbers match what the pipeline would actually have
+    alerted.
+
+    Takes no pipeline lock itself; spawned commands take their own lock.
+    Selector semantics match `dtk run`.
+
+    Examples:
+        # Cover every metric, starting on the last 30 days
+        dtk ui
+
+        # Only metrics tagged critical, starting on the last 7 days
+        dtk ui --select "tag:critical" --window 7d
+
+        # Don't auto-open the browser
+        dtk ui --no-open
+    """
+    from detectkit.cli.commands.ui import run_ui
+
+    run_ui(select=select, profile=profile, window=window, no_open=no_open)
+
+
 @cli.command()
 @click.option(
     "--select",

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/config/validator.py

@@ -10,6 +10,44 @@ from pathlib import Path
 from detectkit.config.metric_config import MetricConfig
 
 
+def is_discoverable_metric_file(path: Path, metrics_dir: Path) -> bool:
+    """True for a *live* metric YAML — excludes the ``metrics/.history/`` archive.
+
+    ``dtk tune`` archives the previous metric config under
+    ``metrics/.history/<metric>/`` before writing the tuned version in place. Those
+    snapshots keep the original ``name:``, so discovering them as live metrics would
+    (a) flag every tuned metric as a duplicate-name conflict and (b) run stale
+    configs. Python's ``pathlib`` glob traverses hidden directories (unlike shell
+    globbing), so they must be filtered out explicitly. Any hidden path component
+    (a leading dot) *under* ``metrics/`` is skipped — this covers ``.history`` and
+    any editor/VCS scratch dir a user drops there, while a project rooted under a
+    dot-directory (checked only below ``metrics/``) is unaffected.
+    """
+    if not path.is_file() or path.suffix not in (".yml", ".yaml"):
+        return False
+    try:
+        parts = path.relative_to(metrics_dir).parts
+    except ValueError:
+        parts = path.parts
+    return not any(part.startswith(".") for part in parts)
+
+
+def discover_metric_files(metrics_dir: Path) -> list[Path]:
+    """All live metric YAMLs under ``metrics/`` (recursive), excluding the ``.history`` archive.
+
+    The single discovery seam shared by project validation and CLI metric selection,
+    so the ``.history`` exclusion can't drift between them. Returns a sorted list for
+    deterministic ordering.
+    """
+    files = [
+        p
+        for pattern in ("**/*.yml", "**/*.yaml")
+        for p in metrics_dir.glob(pattern)
+        if is_discoverable_metric_file(p, metrics_dir)
+    ]
+    return sorted(set(files))
+
+
 def validate_metric_uniqueness(metric_paths: list[Path]) -> list[tuple[Path, MetricConfig]]:
     """
     Load all metrics and validate that metric names are unique.
@@ -106,10 +144,8 @@ def validate_project_metrics(project_root: Path) -> list[tuple[Path, MetricConfi
             f"      your_metric.yml\n"
         )
 
-    # Find all metric files recursively
-    metric_paths = []
-    for pattern in ["**/*.yml", "**/*.yaml"]:
-        metric_paths.extend(metrics_dir.glob(pattern))
+    # Find all metric files recursively (excluding the metrics/.history/ archive).
+    metric_paths = discover_metric_files(metrics_dir)
 
     if not metric_paths:
         raise ValueError(

{detectkit-0.47.0 → detectkit-0.49.0}/detectkit/database/internal_tables/_base.py

@@ -9,7 +9,7 @@ look for those helpers.
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 
 from detectkit.database.manager import BaseDatabaseManager
 
@@ -24,12 +24,19 @@ class _InternalTablesBase:
 
     @staticmethod
     def _normalize_max_timestamp(value: datetime | None) -> datetime | None:
-        """Treat the Unix epoch sentinel as a missing value.
+        """Treat the Unix epoch sentinel as a missing value; return naive UTC.
 
         ClickHouse's ``max(timestamp)`` over an empty selection returns
         ``1970-01-01 00:00:00`` instead of NULL. Without normalisation,
         idempotency checks would think we already processed everything up
         to 1970 and refuse to do work.
+
+        The driver may also hand back an *aware* datetime (clickhouse-driver
+        attaches the server column's timezone), while everything in-memory in
+        detectkit is naive UTC — mixing the two raises ``TypeError`` on the
+        first comparison/subtraction. Cursor reads are normalized to naive
+        UTC here, at the single seam every reader shares, instead of at each
+        call site.
         """
         if value is None:
             return None
@@ -38,4 +45,6 @@ class _InternalTablesBase:
             epoch = epoch.replace(tzinfo=value.tzinfo)
         if value == epoch:
             return None
+        if value.tzinfo is not None:
+            return value.astimezone(timezone.utc).replace(tzinfo=None)
         return value