Merge pull request #243 from itsDNNS/feat/237-smart-capture-ui-surfaces

feat: Smart Capture UI surfaces in settings, events, speedtest, and correlation

Author: itsDNNS

app/blueprints/__init__.py

@@ -10,6 +10,7 @@ def register_blueprints(app):
     from .modules_bp import modules_bp
     from .metrics_bp import metrics_bp
     from .segment_bp import segment_bp
+    from .smart_capture_bp import smart_capture_bp
 
     app.register_blueprint(config_bp)
     app.register_blueprint(polling_bp)
@@ -19,3 +20,4 @@ def register_blueprints(app):
     app.register_blueprint(modules_bp)
     app.register_blueprint(metrics_bp)
     app.register_blueprint(segment_bp)
+    app.register_blueprint(smart_capture_bp)

app/blueprints/analysis_bp.py

@@ -200,7 +200,7 @@ def api_correlation():
 
     sources_param = request.args.get("sources", "")
     if sources_param:
-        valid = {"modem", "speedtest", "events", "bnetz"}
+        valid = {"modem", "speedtest", "events", "bnetz", "capture"}
         sources = valid & set(s.strip() for s in sources_param.split(","))
         if not sources:
             sources = valid

app/blueprints/smart_capture_bp.py

@@ -0,0 +1,21 @@
+"""Smart Capture API endpoints."""
+
+from flask import Blueprint, jsonify, request
+
+from ..web import require_auth, get_storage
+
+smart_capture_bp = Blueprint("smart_capture", __name__)
+
+
+@smart_capture_bp.route("/api/smart-capture/executions")
+@require_auth
+def api_smart_capture_executions():
+    """Return Smart Capture execution history."""
+    _storage = get_storage()
+    if not _storage:
+        return jsonify({"executions": []})
+    limit = request.args.get("limit", 50, type=int)
+    offset = request.args.get("offset", 0, type=int)
+    status = request.args.get("status", None)
+    executions = _storage.get_executions(limit=limit, offset=offset, status=status)
+    return jsonify({"executions": executions})

app/config.py

@@ -54,6 +54,10 @@
     "sc_max_actions_per_hour": 4,
     "sc_flapping_window": 3600,
     "sc_flapping_threshold": 3,
+    "sc_trigger_modulation": True,
+    "sc_trigger_snr": False,
+    "sc_trigger_error_spike": False,
+    "sc_trigger_health": False,
 }
 
 ENV_MAP = {
@@ -100,6 +104,10 @@
     "sc_max_actions_per_hour": "SC_MAX_ACTIONS_PER_HOUR",
     "sc_flapping_window": "SC_FLAPPING_WINDOW",
     "sc_flapping_threshold": "SC_FLAPPING_THRESHOLD",
+    "sc_trigger_modulation": "SC_TRIGGER_MODULATION",
+    "sc_trigger_snr": "SC_TRIGGER_SNR",
+    "sc_trigger_error_spike": "SC_TRIGGER_ERROR_SPIKE",
+    "sc_trigger_health": "SC_TRIGGER_HEALTH",
 }
 
 # Deprecated env vars (FRITZ_* -> MODEM_*) - checked as fallback
@@ -119,7 +127,8 @@
 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"}
-BOOL_KEYS = {"demo_mode", "gaming_quality_enabled", "segment_utilization_enabled", "sc_enabled"}
+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"}
 
 URL_KEYS = {"modem_url", "bqm_url", "speedtest_tracker_url", "notify_webhook_url"}
 _ALLOWED_URL_SCHEMES = {"http", "https"}

app/i18n/de.json

@@ -790,5 +790,40 @@
     "seg_unavailable": "Konfiguration nicht verfügbar.",
     "seg_correlation_ds": "Segment DS Last (%)",
     "seg_correlation_us": "Segment US Last (%)",
-    "sidebar_analysis": "Analyse"
-}
+    "sidebar_analysis": "Analyse",
+    "smart_capture": "Smart Capture",
+    "sc_enable": "Smart Capture aktivieren",
+    "sc_enable_desc": "Automatisch Messungen starten, wenn Signalverschlechterungen erkannt werden",
+    "sc_triggers": "Trigger-Ereignisse",
+    "sc_triggers_desc": "Welche Signalverschlechterungen sollen eine Messung auslösen",
+    "sc_trigger_modulation": "Modulationsverschlechterung",
+    "sc_trigger_modulation_desc": "Wird ausgelöst wenn der QAM-Pegel auf einem Kanal sinkt (z.B. 256QAM auf 64QAM). Nur Verschlechterungen mit Warnung oder Kritisch.",
+    "sc_trigger_snr": "SNR-Verschlechterung",
+    "sc_trigger_snr_desc": "Wird ausgelöst wenn das Signal-Rausch-Verhältnis unter den Warnschwellwert fällt.",
+    "sc_trigger_error_spike": "Fehler-Spitze",
+    "sc_trigger_error_spike_desc": "Wird ausgelöst wenn unkorrigierbare Fehler zwischen Abfragen stark ansteigen.",
+    "sc_trigger_health": "Gesundheitsänderung",
+    "sc_trigger_health_desc": "Wird ausgelöst wenn die Verbindungsqualität auf Grenzwertig oder Kritisch absinkt.",
+    "sc_guardrails": "Schutzmechanismen",
+    "sc_guardrails_desc": "Ratenbegrenzung um übermäßige Test-Auslöser zu verhindern",
+    "sc_global_cooldown": "Globale Abklingzeit (Sekunden)",
+    "sc_trigger_cooldown_label": "Pro-Trigger Abklingzeit (Sekunden)",
+    "sc_max_actions_per_hour": "Max. Aktionen pro Stunde",
+    "sc_history": "Ausführungsverlauf",
+    "sc_history_empty": "Noch keine Ausführungen. Smart Capture protokolliert Aktivitäten hier sobald es aktiviert ist.",
+    "sc_history_error": "Ausführungsverlauf konnte nicht geladen werden",
+    "sc_status_pending": "Ausstehend",
+    "sc_status_fired": "Ausgelöst",
+    "sc_status_completed": "Abgeschlossen",
+    "sc_status_suppressed": "Unterdrückt",
+    "sc_status_expired": "Abgelaufen",
+    "sc_col_timestamp": "Zeitstempel",
+    "sc_col_trigger": "Trigger",
+    "sc_col_status": "Status",
+    "sc_col_details": "Details",
+    "sc_action_capture": "Speedtest ausgelöst",
+    "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"
+}

app/i18n/en.json

@@ -790,5 +790,40 @@
     "seg_unavailable": "Configuration unavailable.",
     "seg_correlation_ds": "Segment DS Load (%)",
     "seg_correlation_us": "Segment US Load (%)",
-    "sidebar_analysis": "Analysis"
-}
+    "sidebar_analysis": "Analysis",
+    "smart_capture": "Smart Capture",
+    "sc_enable": "Enable Smart Capture",
+    "sc_enable_desc": "Automatically trigger measurements when signal degradation is detected",
+    "sc_triggers": "Trigger Events",
+    "sc_triggers_desc": "Choose which signal degradation events should trigger a measurement",
+    "sc_trigger_modulation": "Modulation downgrade",
+    "sc_trigger_modulation_desc": "Triggers when QAM level drops on any channel (e.g. 256QAM to 64QAM). Only downgrades with severity warning or critical.",
+    "sc_trigger_snr": "SNR degradation",
+    "sc_trigger_snr_desc": "Triggers when signal-to-noise ratio drops below warning threshold.",
+    "sc_trigger_error_spike": "Error spike",
+    "sc_trigger_error_spike_desc": "Triggers when uncorrectable errors jump significantly between polls.",
+    "sc_trigger_health": "Health change",
+    "sc_trigger_health_desc": "Triggers when connection health degrades to marginal or critical.",
+    "sc_guardrails": "Guardrails",
+    "sc_guardrails_desc": "Rate limiting to prevent excessive test triggers",
+    "sc_global_cooldown": "Global cooldown (seconds)",
+    "sc_trigger_cooldown_label": "Per-trigger cooldown (seconds)",
+    "sc_max_actions_per_hour": "Max actions per hour",
+    "sc_history": "Execution History",
+    "sc_history_empty": "No executions yet. Smart Capture will log activity here once enabled.",
+    "sc_history_error": "Failed to load execution history",
+    "sc_status_pending": "Pending",
+    "sc_status_fired": "Fired",
+    "sc_status_completed": "Completed",
+    "sc_status_suppressed": "Suppressed",
+    "sc_status_expired": "Expired",
+    "sc_col_timestamp": "Timestamp",
+    "sc_col_trigger": "Trigger",
+    "sc_col_status": "Status",
+    "sc_col_details": "Details",
+    "sc_action_capture": "Speedtest triggered",
+    "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"
+}

app/i18n/es.json

@@ -785,5 +785,40 @@
     "seg_unavailable": "Configuracion no disponible.",
     "seg_correlation_ds": "Carga segmento DS (%)",
     "seg_correlation_us": "Carga segmento US (%)",
-    "sidebar_analysis": "Analisis"
-}
+    "sidebar_analysis": "Analisis",
+    "smart_capture": "Smart Capture",
+    "sc_enable": "Activar Smart Capture",
+    "sc_enable_desc": "Activar automaticamente mediciones cuando se detecta degradacion de senal",
+    "sc_triggers": "Eventos de activacion",
+    "sc_triggers_desc": "Elegir que eventos de degradacion de senal deben activar una medicion",
+    "sc_trigger_modulation": "Degradacion de modulacion",
+    "sc_trigger_modulation_desc": "Se activa cuando el nivel QAM baja en cualquier canal (ej. 256QAM a 64QAM). Solo degradaciones con severidad advertencia o critica.",
+    "sc_trigger_snr": "Degradacion SNR",
+    "sc_trigger_snr_desc": "Se activa cuando la relacion senal/ruido cae por debajo del umbral de advertencia.",
+    "sc_trigger_error_spike": "Pico de errores",
+    "sc_trigger_error_spike_desc": "Se activa cuando los errores incorregibles aumentan significativamente entre sondeos.",
+    "sc_trigger_health": "Cambio de salud",
+    "sc_trigger_health_desc": "Se activa cuando la salud de la conexion se degrada a marginal o critica.",
+    "sc_guardrails": "Protecciones",
+    "sc_guardrails_desc": "Limitacion de velocidad para evitar activaciones excesivas de pruebas",
+    "sc_global_cooldown": "Enfriamiento global (segundos)",
+    "sc_trigger_cooldown_label": "Enfriamiento por activador (segundos)",
+    "sc_max_actions_per_hour": "Acciones max por hora",
+    "sc_history": "Historial de ejecuciones",
+    "sc_history_empty": "Sin ejecuciones aun. Smart Capture registrara la actividad aqui una vez activado.",
+    "sc_history_error": "Error al cargar el historial de ejecuciones",
+    "sc_status_pending": "Pendiente",
+    "sc_status_fired": "Activado",
+    "sc_status_completed": "Completado",
+    "sc_status_suppressed": "Suprimido",
+    "sc_status_expired": "Expirado",
+    "sc_col_timestamp": "Marca de tiempo",
+    "sc_col_trigger": "Activador",
+    "sc_col_status": "Estado",
+    "sc_col_details": "Detalles",
+    "sc_action_capture": "Speedtest activado",
+    "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"
+}

app/i18n/fr.json

@@ -782,5 +782,40 @@
     "seg_unavailable": "Configuration non disponible.",
     "seg_correlation_ds": "Charge segment DS (%)",
     "seg_correlation_us": "Charge segment US (%)",
-    "sidebar_analysis": "Analyse"
-}
+    "sidebar_analysis": "Analyse",
+    "smart_capture": "Smart Capture",
+    "sc_enable": "Activer Smart Capture",
+    "sc_enable_desc": "Declencher automatiquement des mesures lorsque des degradations du signal sont detectees",
+    "sc_triggers": "Evenements declencheurs",
+    "sc_triggers_desc": "Choisir quels evenements de degradation du signal doivent declencher une mesure",
+    "sc_trigger_modulation": "Degradation de modulation",
+    "sc_trigger_modulation_desc": "Se declenche lorsque le niveau QAM baisse sur un canal (ex. 256QAM vers 64QAM). Uniquement les degradations avec severite avertissement ou critique.",
+    "sc_trigger_snr": "Degradation SNR",
+    "sc_trigger_snr_desc": "Se declenche lorsque le rapport signal/bruit descend sous le seuil d'avertissement.",
+    "sc_trigger_error_spike": "Pic d'erreurs",
+    "sc_trigger_error_spike_desc": "Se declenche lorsque les erreurs non corrigeables augmentent significativement entre les interrogations.",
+    "sc_trigger_health": "Changement de sante",
+    "sc_trigger_health_desc": "Se declenche lorsque la sante de la connexion se degrade vers marginal ou critique.",
+    "sc_guardrails": "Garde-fous",
+    "sc_guardrails_desc": "Limitation du debit pour eviter les declenchements excessifs de tests",
+    "sc_global_cooldown": "Temps de refroidissement global (secondes)",
+    "sc_trigger_cooldown_label": "Temps de refroidissement par declencheur (secondes)",
+    "sc_max_actions_per_hour": "Actions max par heure",
+    "sc_history": "Historique des executions",
+    "sc_history_empty": "Aucune execution pour le moment. Smart Capture enregistrera les activites ici une fois active.",
+    "sc_history_error": "Echec du chargement de l'historique des executions",
+    "sc_status_pending": "En attente",
+    "sc_status_fired": "Declenche",
+    "sc_status_completed": "Termine",
+    "sc_status_suppressed": "Supprime",
+    "sc_status_expired": "Expire",
+    "sc_col_timestamp": "Horodatage",
+    "sc_col_trigger": "Declencheur",
+    "sc_col_status": "Statut",
+    "sc_col_details": "Details",
+    "sc_action_capture": "Speedtest declenche",
+    "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"
+}

app/main.py

@@ -106,19 +106,27 @@ def polling_loop(config_mgr, storage, stop_event):
         notifier = NotificationDispatcher(config_mgr)
         log.info("Notifications: webhook configured")
 
-    # Smart Capture (optional)
-    smart_capture = None
-    if config_mgr.get("sc_enabled", False):
-        from .smart_capture import SmartCaptureEngine, Trigger
-        smart_capture = SmartCaptureEngine(storage, config_mgr)
-        # Default trigger: modulation downgrades (v1 scope)
-        smart_capture.register_trigger(Trigger(
-            event_type="modulation_change",
-            action_type="capture",
-            min_severity="warning",
-            require_details={"direction": "downgrade"},
-        ))
-        log.info("Smart Capture: enabled with %d trigger(s)", len(smart_capture.triggers))
+    # Smart Capture (always instantiated — _is_enabled() gates at runtime)
+    from .smart_capture import SmartCaptureEngine, Trigger
+    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"},
+    ))
+    smart_capture.register_trigger(Trigger(
+        event_type="snr_change", action_type="capture",
+        config_key="sc_trigger_snr", min_severity="warning",
+    ))
+    smart_capture.register_trigger(Trigger(
+        event_type="error_spike", action_type="capture",
+        config_key="sc_trigger_error_spike",
+    ))
+    smart_capture.register_trigger(Trigger(
+        event_type="health_change", action_type="capture",
+        config_key="sc_trigger_health", min_severity="warning",
+    ))
+    log.info("Smart Capture: registered %d trigger(s)", len(smart_capture.triggers))
 
     web.update_state(poll_interval=config["poll_interval"])
 
@@ -128,8 +136,8 @@ def polling_loop(config_mgr, storage, stop_event):
         notifier=notifier, smart_capture=smart_capture,
     )
 
-    # Wire STT adapter if Smart Capture enabled, STT configured, and not demo mode
-    if smart_capture and config_mgr.is_speedtest_configured() and not config_mgr.is_demo_mode():
+    # Wire STT adapter if STT configured and not demo mode
+    if config_mgr.is_speedtest_configured() and not config_mgr.is_demo_mode():
         from .smart_capture.adapters.speedtest import SpeedtestAdapter
         stt_adapter = SpeedtestAdapter(storage, config_mgr)
         smart_capture.register_adapter("capture", stt_adapter)
@@ -245,7 +253,7 @@ def _run_collector(collector):
                         future.cancel()
 
             # ── Smart Capture expiry check (every 60s) ──
-            if smart_capture and smart_capture.adapter_action_types:
+            if smart_capture:
                 if not hasattr(polling_loop, '_sc_expiry_counter'):
                     polling_loop._sc_expiry_counter = 0
                 polling_loop._sc_expiry_counter += 1
@@ -258,6 +266,11 @@ def _run_collector(collector):
                         if expired:
                             log.info("Smart Capture: expired %d stale %s executions",
                                      expired, action_type)
+                    # Expire orphaned PENDING executions (no adapter registered)
+                    pending_expired = storage.expire_stale_pending(cutoff)
+                    if pending_expired:
+                        log.info("Smart Capture: expired %d orphaned pending executions",
+                                 pending_expired)
 
             stop_event.wait(1)
     finally:

app/modules/speedtest/routes.py

@@ -62,6 +62,23 @@ def _enrich_speedtest(result):
     return result
 
 
+def _annotate_smart_capture(results, db_path):
+    """Annotate speedtest results with smart_capture flag."""
+    try:
+        import sqlite3
+        with sqlite3.connect(db_path) as conn:
+            rows = conn.execute(
+                "SELECT linked_result_id FROM smart_capture_executions "
+                "WHERE status = 'completed' AND linked_result_id IS NOT NULL"
+            ).fetchall()
+            sc_ids = {r[0] for r in rows}
+        for r in results:
+            r["smart_capture"] = r.get("id") in sc_ids
+    except Exception:
+        for r in results:
+            r["smart_capture"] = False
+
+
 def _get_lang():
     from flask import request as req
     return req.cookies.get("lang", "en")
@@ -80,7 +97,9 @@ def api_speedtest():
     # Demo mode: return seeded data without external API call
     if _config_manager.is_demo_mode() and ss:
         results = ss.get_speedtest_results(limit=count)
-        return jsonify([_enrich_speedtest(r) for r in results])
+        enriched = [_enrich_speedtest(r) for r in results]
+        _annotate_smart_capture(enriched, ss.db_path)
+        return jsonify(enriched)
     # Delta fetch: get new results from STT API and cache them
     if ss:
         try:
@@ -101,7 +120,9 @@ def api_speedtest():
         except Exception as e:
             log.warning("Speedtest delta fetch failed: %s", e)
         results = ss.get_speedtest_results(limit=count)
-        return jsonify([_enrich_speedtest(r) for r in results])
+        enriched = [_enrich_speedtest(r) for r in results]
+        _annotate_smart_capture(enriched, ss.db_path)
+        return jsonify(enriched)
     # Fallback: no storage, fetch directly
     from .client import SpeedtestClient
     client = SpeedtestClient(