Add generic peak cycle detector

scripts/validate_k7_roll_length.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Validate the generic peak detector against an ignored local K7 capture.
+
+This developer utility reads no network data and does not modify the capture.
+Run it from the repository root when data/raw/enlyze/k7-roll-length-2h.raw.json
+is available.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from production_analytics.calculations import (
+    PeakCycleDetector,
+    PeakDetectorConfig,
+    TimeSeriesSample,
+)
+
+
+CAPTURE = Path("data/raw/enlyze/k7-roll-length-2h.raw.json")
+VARIABLE_UUID = "bf81c547-dccf-4709-aee2-0f78366d1dfc"
+
+
+def main() -> int:
+    if not CAPTURE.is_file():
+        print(f"K7 capture is not available: {CAPTURE}")
+        return 1
+
+    payload = json.loads(CAPTURE.read_text(encoding="utf-8"))
+    data = payload["response"]["body"]["data"]
+    value_index = data["columns"].index(VARIABLE_UUID)
+    samples = (
+        TimeSeriesSample(
+            datetime.fromisoformat(record[0].replace("Z", "+00:00")),
+            float(record[value_index]),
+        )
+        for record in data["records"]
+        if record[value_index] is not None
+    )
+    detector = PeakCycleDetector(
+        PeakDetectorConfig(
+            min_peak=10.0,
+            drop_ratio=0.75,
+            hold_seconds=60.0,
+            max_sample_gap_seconds=20.0,
+        )
+    )
+    peaks = list(detector.process_many(samples))
+    print(f"Detected peaks: {len(peaks)}")
+    for peak in peaks:
+        print(
+            f"peak={peak.value:.6f} at {peak.peak_timestamp.isoformat()} "
+            f"confirmed={peak.confirmed_at.isoformat()}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())