Merge pull request #246 from itsDNNS/feat/245-smart-capture-sub-settings

feat: Smart Capture configurable trigger sub-settings and Connection Monitor integration

Author: itsDNNS

app/config.py

@@ -55,9 +55,15 @@
     "sc_flapping_window": 3600,
     "sc_flapping_threshold": 3,
     "sc_trigger_modulation": True,
+    "sc_trigger_modulation_direction": "both",
+    "sc_trigger_modulation_min_qam": "",
     "sc_trigger_snr": False,
     "sc_trigger_error_spike": False,
+    "sc_trigger_error_spike_min_delta": 0,
     "sc_trigger_health": False,
+    "sc_trigger_health_level": "any_degradation",
+    "sc_trigger_packet_loss": False,
+    "sc_trigger_packet_loss_min_pct": "5.0",
 }
 
 ENV_MAP = {
@@ -105,9 +111,15 @@
     "sc_flapping_window": "SC_FLAPPING_WINDOW",
     "sc_flapping_threshold": "SC_FLAPPING_THRESHOLD",
     "sc_trigger_modulation": "SC_TRIGGER_MODULATION",
+    "sc_trigger_modulation_direction": "SC_TRIGGER_MODULATION_DIRECTION",
+    "sc_trigger_modulation_min_qam": "SC_TRIGGER_MODULATION_MIN_QAM",
     "sc_trigger_snr": "SC_TRIGGER_SNR",
     "sc_trigger_error_spike": "SC_TRIGGER_ERROR_SPIKE",
+    "sc_trigger_error_spike_min_delta": "SC_TRIGGER_ERROR_SPIKE_MIN_DELTA",
     "sc_trigger_health": "SC_TRIGGER_HEALTH",
+    "sc_trigger_health_level": "SC_TRIGGER_HEALTH_LEVEL",
+    "sc_trigger_packet_loss": "SC_TRIGGER_PACKET_LOSS",
+    "sc_trigger_packet_loss_min_pct": "SC_TRIGGER_PACKET_LOSS_MIN_PCT",
 }
 
 # Deprecated env vars (FRITZ_* -> MODEM_*) - checked as fallback
@@ -126,9 +138,11 @@
 
 INT_KEYS = {"poll_interval", "web_port", "history_days", "notify_cooldown", "health_hysteresis",
             "sc_global_cooldown", "sc_trigger_cooldown", "sc_max_actions_per_hour",
-            "sc_flapping_window", "sc_flapping_threshold"}
+            "sc_flapping_window", "sc_flapping_threshold",
+            "sc_trigger_error_spike_min_delta"}
 BOOL_KEYS = {"demo_mode", "gaming_quality_enabled", "segment_utilization_enabled", "sc_enabled",
-             "sc_trigger_modulation", "sc_trigger_snr", "sc_trigger_error_spike", "sc_trigger_health"}
+             "sc_trigger_modulation", "sc_trigger_snr", "sc_trigger_error_spike", "sc_trigger_health",
+             "sc_trigger_packet_loss"}
 
 URL_KEYS = {"modem_url", "bqm_url", "speedtest_tracker_url", "notify_webhook_url"}
 _ALLOWED_URL_SCHEMES = {"http", "https"}

app/docsis_utils.py

@@ -0,0 +1,40 @@
+"""Shared DOCSIS utilities — QAM hierarchy and modulation ranking."""
+
+import re
+
+# QAM hierarchy: higher value = better modulation
+QAM_ORDER = {
+    "QPSK": 1, "4QAM": 1,
+    "8QAM": 2,
+    "16QAM": 3,
+    "32QAM": 4,
+    "64QAM": 5,
+    "128QAM": 6,
+    "256QAM": 7,
+    "512QAM": 8,
+    "1024QAM": 9,
+    "2048QAM": 10,
+    "4096QAM": 11,
+}
+
+
+def qam_rank(modulation):
+    """Get QAM rank for any modulation format.
+
+    Handles both driver formats: "256QAM" (Ultra Hub 7, CM3500)
+    and "qam_256" (Vodafone Station, CH7465, TC4400).
+
+    Returns 0 for unknown/empty modulation.
+    """
+    if not modulation:
+        return 0
+    rank = QAM_ORDER.get(modulation)
+    if rank is not None:
+        return rank
+    mod = modulation.upper().replace("-", "").replace("_", "")
+    if mod == "QPSK":
+        return QAM_ORDER["QPSK"]
+    m = re.search(r"(\d+)", mod)
+    if m and "QAM" in mod:
+        return QAM_ORDER.get(f"{m.group(1)}QAM", 0)
+    return 0

app/event_detector.py

@@ -1,7 +1,6 @@
 """Detect significant signal changes between consecutive DOCSIS snapshots."""
 
 import logging
-import re
 import threading
 
 from .tz import utc_now
@@ -15,44 +14,12 @@
 # Import SNR thresholds from analyzer (loaded from thresholds.json)
 from app.analyzer import _get_snr_thresholds as _snr_thresholds
 
-# QAM hierarchy: higher value = better modulation
-QAM_ORDER = {
-    "QPSK": 1, "4QAM": 1,
-    "8QAM": 2,
-    "16QAM": 3,
-    "32QAM": 4,
-    "64QAM": 5,
-    "128QAM": 6,
-    "256QAM": 7,
-    "512QAM": 8,
-    "1024QAM": 9,
-    "2048QAM": 10,
-    "4096QAM": 11,
-}
+from .docsis_utils import QAM_ORDER, qam_rank as _qam_rank
+
 # A drop of this many levels or more counts as critical (e.g. 256QAM → 16QAM = 4 levels)
 QAM_CRITICAL_DROP = 3
 
 
-def _qam_rank(modulation):
-    """Get QAM rank for any modulation format.
-
-    Handles both driver formats: "256QAM" (Ultra Hub 7, CM3500)
-    and "qam_256" (Vodafone Station, CH7465, TC4400).
-    """
-    if not modulation:
-        return 0
-    rank = QAM_ORDER.get(modulation)
-    if rank is not None:
-        return rank
-    mod = modulation.upper().replace("-", "").replace("_", "")
-    if mod == "QPSK":
-        return QAM_ORDER["QPSK"]
-    m = re.search(r"(\d+)", mod)
-    if m and "QAM" in mod:
-        return QAM_ORDER.get(f"{m.group(1)}QAM", 0)
-    return 0
-
-
 class EventDetector:
     """Compare consecutive analyses and emit event dicts."""
 
@@ -253,6 +220,8 @@ def _check_modulation(self, events, ts, cur_analysis, prev_analysis):
                 entry = {"channel": ch_id, "direction": "DS", "prev": prev_ds[ch_id], "current": cur_ds[ch_id]}
                 cur_rank = _qam_rank(cur_ds[ch_id])
                 prev_rank = _qam_rank(prev_ds[ch_id])
+                entry["prev_rank"] = prev_rank
+                entry["current_rank"] = cur_rank
                 entry["rank_drop"] = prev_rank - cur_rank
                 if cur_rank < prev_rank:
                     downgrades.append(entry)
@@ -263,6 +232,8 @@ def _check_modulation(self, events, ts, cur_analysis, prev_analysis):
                 entry = {"channel": ch_id, "direction": "US", "prev": prev_us[ch_id], "current": cur_us[ch_id]}
                 cur_rank = _qam_rank(cur_us[ch_id])
                 prev_rank = _qam_rank(prev_us[ch_id])
+                entry["prev_rank"] = prev_rank
+                entry["current_rank"] = cur_rank
                 entry["rank_drop"] = prev_rank - cur_rank
                 if cur_rank < prev_rank:
                     downgrades.append(entry)

app/i18n/de.json

@@ -825,5 +825,24 @@
     "sc_no_adapter_warning": "Kein Aktionsadapter konfiguriert. Aktiviere Speedtest Tracker um Smart Capture zu nutzen.",
     "sc_badge_label": "Smart Capture",
     "correlation_source_capture": "Capture",
-    "event_type_smart_capture_triggered": "Smart Capture"
+    "event_type_smart_capture_triggered": "Smart Capture",
+    "sc_trigger_direction": "Richtung",
+    "sc_trigger_direction_both": "Beide",
+    "sc_trigger_direction_ds": "Nur Downstream",
+    "sc_trigger_direction_us": "Nur Upstream",
+    "sc_trigger_min_qam": "Min. QAM-Stufe",
+    "sc_trigger_min_qam_any": "Jede Verschlechterung",
+    "sc_trigger_min_qam_256": "Unter 256QAM",
+    "sc_trigger_min_qam_64": "Unter 64QAM",
+    "sc_trigger_min_qam_16": "Unter 16QAM",
+    "sc_trigger_min_delta": "Min. Fehlerdelta",
+    "sc_trigger_min_delta_hint": "0 = bei jedem Fehlersprung auslösen",
+    "sc_trigger_health_level": "Gesundheitsstufe",
+    "sc_trigger_health_level_any": "Jede Verschlechterung",
+    "sc_trigger_health_level_critical": "Nur Kritisch",
+    "sc_trigger_packet_loss": "Paketverlust-Warnung",
+    "sc_trigger_packet_loss_desc": "Wird ausgelöst wenn der Connection Monitor hohen Paketverlust auf einem Ziel erkennt",
+    "sc_trigger_packet_loss_min_pct": "Min. Paketverlust %",
+    "sc_trigger_packet_loss_min_pct_hint": "Benötigt Connection Monitor Modul. Löst nur aus wenn der Paketverlust sowohl diesen Schwellwert als auch den Connection Monitor Warnschwellwert überschreitet.",
+    "event_type_cm_packet_loss_warning": "Paketverlust-Warnung"
 }

app/i18n/en.json

@@ -825,5 +825,24 @@
     "sc_no_adapter_warning": "No action adapter configured. Enable Speedtest Tracker to use Smart Capture.",
     "sc_badge_label": "Smart Capture",
     "correlation_source_capture": "Capture",
-    "event_type_smart_capture_triggered": "Smart Capture"
+    "event_type_smart_capture_triggered": "Smart Capture",
+    "sc_trigger_direction": "Direction",
+    "sc_trigger_direction_both": "Both",
+    "sc_trigger_direction_ds": "Downstream only",
+    "sc_trigger_direction_us": "Upstream only",
+    "sc_trigger_min_qam": "Min QAM level",
+    "sc_trigger_min_qam_any": "Any downgrade",
+    "sc_trigger_min_qam_256": "Below 256QAM",
+    "sc_trigger_min_qam_64": "Below 64QAM",
+    "sc_trigger_min_qam_16": "Below 16QAM",
+    "sc_trigger_min_delta": "Min error delta",
+    "sc_trigger_min_delta_hint": "0 = trigger on any spike",
+    "sc_trigger_health_level": "Health level",
+    "sc_trigger_health_level_any": "Any degradation",
+    "sc_trigger_health_level_critical": "Critical only",
+    "sc_trigger_packet_loss": "Packet loss warning",
+    "sc_trigger_packet_loss_desc": "Triggers when Connection Monitor detects high packet loss on any target",
+    "sc_trigger_packet_loss_min_pct": "Min packet loss %",
+    "sc_trigger_packet_loss_min_pct_hint": "Requires Connection Monitor module. Only fires when packet loss exceeds both this threshold and the Connection Monitor warning threshold.",
+    "event_type_cm_packet_loss_warning": "Packet Loss Warning"
 }

app/i18n/es.json

@@ -820,5 +820,24 @@
     "sc_no_adapter_warning": "Ningun adaptador de accion configurado. Active Speedtest Tracker para usar Smart Capture.",
     "sc_badge_label": "Smart Capture",
     "correlation_source_capture": "Capture",
-    "event_type_smart_capture_triggered": "Smart Capture"
+    "event_type_smart_capture_triggered": "Smart Capture",
+    "sc_trigger_direction": "Direccion",
+    "sc_trigger_direction_both": "Ambos",
+    "sc_trigger_direction_ds": "Solo descendente",
+    "sc_trigger_direction_us": "Solo ascendente",
+    "sc_trigger_min_qam": "Nivel QAM minimo",
+    "sc_trigger_min_qam_any": "Cualquier degradacion",
+    "sc_trigger_min_qam_256": "Por debajo de 256QAM",
+    "sc_trigger_min_qam_64": "Por debajo de 64QAM",
+    "sc_trigger_min_qam_16": "Por debajo de 16QAM",
+    "sc_trigger_min_delta": "Delta de errores minimo",
+    "sc_trigger_min_delta_hint": "0 = activar en cualquier pico",
+    "sc_trigger_health_level": "Nivel de salud",
+    "sc_trigger_health_level_any": "Cualquier degradacion",
+    "sc_trigger_health_level_critical": "Solo critico",
+    "sc_trigger_packet_loss": "Alerta de perdida de paquetes",
+    "sc_trigger_packet_loss_desc": "Se activa cuando el Connection Monitor detecta alta perdida de paquetes",
+    "sc_trigger_packet_loss_min_pct": "Perdida de paquetes min %",
+    "sc_trigger_packet_loss_min_pct_hint": "Requiere el modulo Connection Monitor. Solo se activa cuando la perdida supera este umbral y el umbral de advertencia del Connection Monitor.",
+    "event_type_cm_packet_loss_warning": "Alerta perdida de paquetes"
 }

app/i18n/fr.json

@@ -817,5 +817,24 @@
     "sc_no_adapter_warning": "Aucun adaptateur d'action configure. Activez Speedtest Tracker pour utiliser Smart Capture.",
     "sc_badge_label": "Smart Capture",
     "correlation_source_capture": "Capture",
-    "event_type_smart_capture_triggered": "Smart Capture"
+    "event_type_smart_capture_triggered": "Smart Capture",
+    "sc_trigger_direction": "Direction",
+    "sc_trigger_direction_both": "Les deux",
+    "sc_trigger_direction_ds": "Descendant uniquement",
+    "sc_trigger_direction_us": "Montant uniquement",
+    "sc_trigger_min_qam": "Niveau QAM minimum",
+    "sc_trigger_min_qam_any": "Toute degradation",
+    "sc_trigger_min_qam_256": "En dessous de 256QAM",
+    "sc_trigger_min_qam_64": "En dessous de 64QAM",
+    "sc_trigger_min_qam_16": "En dessous de 16QAM",
+    "sc_trigger_min_delta": "Delta d erreurs minimum",
+    "sc_trigger_min_delta_hint": "0 = declencher sur tout pic",
+    "sc_trigger_health_level": "Niveau de sante",
+    "sc_trigger_health_level_any": "Toute degradation",
+    "sc_trigger_health_level_critical": "Critique uniquement",
+    "sc_trigger_packet_loss": "Alerte perte de paquets",
+    "sc_trigger_packet_loss_desc": "Se declenche lorsque le Connection Monitor detecte une perte de paquets elevee",
+    "sc_trigger_packet_loss_min_pct": "Perte de paquets min %",
+    "sc_trigger_packet_loss_min_pct_hint": "Necessite le module Connection Monitor. Ne se declenche que lorsque la perte depasse ce seuil et le seuil d avertissement du Connection Monitor.",
+    "event_type_cm_packet_loss_warning": "Alerte perte de paquets"
 }

app/main.py

@@ -108,23 +108,36 @@ def polling_loop(config_mgr, storage, stop_event):
 
     # Smart Capture (always instantiated — _is_enabled() gates at runtime)
     from .smart_capture import SmartCaptureEngine, Trigger
+    from .smart_capture.sub_filters import (
+        modulation_sub_filter, snr_sub_filter, error_spike_sub_filter,
+        health_sub_filter, packet_loss_sub_filter,
+    )
     smart_capture = SmartCaptureEngine(storage, config_mgr)
     smart_capture.register_trigger(Trigger(
         event_type="modulation_change", action_type="capture",
         config_key="sc_trigger_modulation",
         min_severity="warning", require_details={"direction": "downgrade"},
+        sub_filter=modulation_sub_filter,
     ))
     smart_capture.register_trigger(Trigger(
         event_type="snr_change", action_type="capture",
         config_key="sc_trigger_snr", min_severity="warning",
+        sub_filter=snr_sub_filter,
     ))
     smart_capture.register_trigger(Trigger(
         event_type="error_spike", action_type="capture",
         config_key="sc_trigger_error_spike",
+        sub_filter=error_spike_sub_filter,
     ))
     smart_capture.register_trigger(Trigger(
         event_type="health_change", action_type="capture",
         config_key="sc_trigger_health", min_severity="warning",
+        sub_filter=health_sub_filter,
+    ))
+    smart_capture.register_trigger(Trigger(
+        event_type="cm_packet_loss_warning", action_type="capture",
+        config_key="sc_trigger_packet_loss",
+        sub_filter=packet_loss_sub_filter,
     ))
     log.info("Smart Capture: registered %d trigger(s)", len(smart_capture.triggers))
 
@@ -146,6 +159,12 @@ def polling_loop(config_mgr, storage, stop_event):
             stt_collector.on_import = stt_adapter.on_results_imported
             log.info("Smart Capture: STT adapter wired to speedtest collector")
 
+    # Wire Smart Capture to Connection Monitor collector
+    cm_collector = next((c for c in collectors if c.name == "connection_monitor"), None)
+    if cm_collector and hasattr(cm_collector, 'set_smart_capture'):
+        cm_collector.set_smart_capture(smart_capture)
+        log.info("Smart Capture: wired to Connection Monitor collector")
+
     # Inject collectors into web layer for manual polling and status endpoint
     modem_collector = next((c for c in collectors if c.name in ("modem", "demo")), None)
     if modem_collector:

app/modules/connection_monitor/collector.py

@@ -41,6 +41,11 @@ def __init__(self, config_mgr, storage, web, **kwargs):
         self._cm_storage = ConnectionMonitorStorage(db_path)
 
         self._seeded = False
+        self._smart_capture = None
+
+    def set_smart_capture(self, smart_capture):
+        """Inject Smart Capture engine for event evaluation."""
+        self._smart_capture = smart_capture
 
     def is_enabled(self) -> bool:
         return bool(self._config_mgr.get("connection_monitor_enabled", False))
@@ -148,8 +153,10 @@ def _check_events(self, samples: list[dict]):
             )
             all_events.extend(events)
 
-        if all_events and hasattr(self._core_storage, "save_events"):
-            self._core_storage.save_events(all_events)
+        if all_events and hasattr(self._core_storage, "save_events_with_ids"):
+            self._core_storage.save_events_with_ids(all_events)
+            if self._smart_capture:
+                self._smart_capture.evaluate(all_events)
 
     def _ensure_default_targets(self):
         """Seed default targets on first enable."""

app/smart_capture/engine.py

@@ -78,6 +78,14 @@ def _evaluate_event(self, event: dict):
         if not matches:
             return
 
+        # Apply sub-filter if set
+        matches = [
+            (t, ev) for t, ev in matches
+            if t.sub_filter is None or t.sub_filter(self._config, ev)
+        ]
+        if not matches:
+            return
+
         results = self._guardrails.check_batch(matches)
 
         for trigger, ev, allowed, reason in results: