Update backend/agents/risk_agent.py

backend/agents/risk_agent.py

@@ -2,42 +2,24 @@
 HaramGuard — RiskAgent
 ========================
 AISA Layer : Cognitive Agent Layer
-Design Pattern : Sliding Window + Weighted Scoring
-
-Scoring Method: Fruin LoS + ROC + Spatial Grid (4-path)
---------------------------------------------------------
-Based on:
-  - Fruin (1971): count-based density proxy → Path 1 + Path 2
-  - Fruin (1993) FIST model: rate-of-change is critical → Path 3
-  - UQU Haram Research: local clustering detection via spatial grid → Path 4
-
-Four detection paths (final score = max of all four):
-
-  Path 1 — FRUIN SMOOTH (EMA):
-    EMA of window-peak count, normalized to HIGH_COUNT.
-    W_DENSITY=0.60: c_score=1.0 alone exceeds HIGH_THRESHOLD=0.65.
-    Structural ceiling bug fix (was 0.50 → max 0.61, HIGH unreachable).
-
-  Path 2 — INSTANT (zero lag):
-    current frame count >= HIGH_COUNT → floor 0.70 immediately.
-    Fixes Scene D EMA convergence lag (~15 frames).
-
-  Path 3 — PRE-EMPTIVE ROC:
-    5-frame growth >= PRE_ROC AND EMA >= PRE_EMA → floor 0.66.
-    Early escalation detection before count crosses HIGH_COUNT.
-    Full buffer required (prevents cold-start false positives).
-
-  Path 4 — SPATIAL CLUSTERING (UQU research):
-    If any single 3×3 grid cell has >= GRID_CELL_HIGH persons → floor 0.70.
-    Catches local hotspots that global count misses:
-    47 persons in one corner = HIGH risk, even if global score = MEDIUM.
-    GRID_CELL_HIGH = HIGH_COUNT / 4 ≈ 12 persons per cell.
-
-References:
-  Fruin, J.J. (1971). Pedestrian Planning and Design.
-  Fruin, J.J. (1993). Causes and Prevention of Crowd Disasters. ICES.
-  UQU / Hajj-Crowd-2021: Haram-specific crowd density research.
-  Still, G.K. (2000). Crowd Dynamics. PhD, Warwick University.
+Design Pattern : Clip Segmentation + Sliding K-Window Density
+
+A) Clip segmentation
+   - Boundary if |persons[t] - persons[t-1]| >= P_JUMP
+                 OR |density_score[t] - density_score[t-1]| >= D_JUMP
+   - Glitch filter: boundary must persist >= MIN_LEN frames; otherwise merge back.
+
+B) Sliding-window density (updates EVERY frame)
+   - Keep a deque of the last K=17 frames within the current clip.
+   - N_est = count of UNIQUE track IDs across those K frames (union).
+   - density_pct = N_est / N_REF * 100  (N_REF = RISK_HIGH_THRESHOLD from config, capped at 100%)
+
+C) Risk score 0–1.0 based on density_pct
+   - risk_score = density_pct / 100  (0.0–1.0 for downstream compatibility)
+   - risk_level: density_pct <= 20 → LOW, <= 80 → MEDIUM, > 80 → HIGH
+
+Level stabilization: a new level must hold for STABLE_FRAMES consecutive
+frames before it is confirmed and level_changed fires.
 """
 
 import numpy as np
@@ -49,139 +31,167 @@ import config
 
 class RiskAgent:
 
-    WINDOW_SIZE    = config.RISK_WINDOW_SIZE
-    HIGH_THRESHOLD = config.RISK_HIGH_THRESHOLD   # 0.65
-    MED_THRESHOLD  = config.RISK_MED_THRESHOLD    # 0.35
-    HIGH_DENSITY   = config.RISK_HIGH_DENSITY
-    EMA_ALPHA      = config.RISK_EMA_ALPHA        # 0.6
 
-    # ── Fruin-calibrated weights ──────────────────────────────────────
-    W_DENSITY  = 0.60   # count-based primary (Fruin LoS proxy)
-    W_ROC      = 0.20   # rate-of-change escalation signal
-    W_TREND    = 0.10   # sliding-window trend
+    P_JUMP    = getattr(config, 'CLIP_P_JUMP', 40)       # person count jump
+    D_JUMP    = getattr(config, 'CLIP_D_JUMP', 0.4)      # density_score jump
+    MIN_LEN   = getattr(config, 'CLIP_MIN_LEN', 10)      # min frames to confirm clip
+
+    K_WINDOW  = getattr(config, 'CLIP_K_WINDOW', 17)     # frames for unique-ID union
 
-    # ── ROC thresholds ────────────────────────────────────────────────
-    ROC_WINDOW = 5
-    PRE_ROC    = 10     # persons growth over 5 frames = rapid escalation
-    PRE_EMA    = 38     # ~75% of HIGH_COUNT before pre-empting
+    N_REF     = config.RISK_HIGH_THRESHOLD  # density_pct = N_est / N_REF * 100
 
-    # ── Spatial grid threshold (UQU research) ─────────────────────────
-    # HIGH_COUNT / 4: a single 3×3 cell with this many persons = local crush risk
-    # e.g. HIGH_COUNT=50 → 12 persons in one cell of a ~640×360 sub-zone
-    GRID_CELL_HIGH = max(1, config.RISK_HIGH_COUNT // 4)
+    LOW_CEIL  = 20.0     # density_pct <= 20 → LOW
+    MED_CEIL  = 80.0     # density_pct <= 80 → MEDIUM, > 80 → HIGH
+
+    STABLE_FRAMES = 5
+    EMA_ALPHA     = config.RISK_EMA_ALPHA
 
     def __init__(self):
-        self.name        = 'RiskAgent'
-        self.aisa_layer  = 'Cognitive Agent Layer'
-        self._window     = deque(maxlen=self.WINDOW_SIZE)
-        self._roc_buf    = deque(maxlen=self.ROC_WINDOW)
-        self._prev_level = 'LOW'
-        self._peak_ema   = 0.0
-        self._occ_ema    = 0.0
+        self.name       = 'RiskAgent'
+        self.aisa_layer = 'Cognitive Agent Layer'
+
+        self._clip_id         = 0
+        self._boundary_buf    = 0        # consecutive boundary-candidate frames
+        self._in_boundary     = False    # currently in a boundary glitch zone
+        self._prev_count      = 0
+        self._prev_density_sc = 0.0
+
+        self._k_deque     = deque(maxlen=self.K_WINDOW)  # last K FrameResults in clip
+        self._n_est       = 0
+        self._density_pct = 0.0
+
+        self._prev_level      = 'LOW'
+        self._candidate       = None
+        self._candidate_count = 0
+
+        self._peak_ema = 0.0
+        self._occ_ema  = 0.0
+        self._window   = deque(maxlen=config.RISK_WINDOW_SIZE)
+
         print(
-            f'⚠️  [RiskAgent] Ready — Fruin LoS + ROC + Spatial Grid '
-            f'(4-path, cell_high={self.GRID_CELL_HIGH})'
+            f'⚠️  [RiskAgent] Ready — Clip segmentation + sliding K-window({self.K_WINDOW}) '
+            f'(P_JUMP={self.P_JUMP}, D_JUMP={self.D_JUMP}, '
+            f'MIN_LEN={self.MIN_LEN}, LOW<={self.LOW_CEIL}%, MED<={self.MED_CEIL}%)'
         )
 
-    def _label(self, score: float) -> str:
-        if score >= self.HIGH_THRESHOLD: return 'HIGH'
-        if score >= self.MED_THRESHOLD:  return 'MEDIUM'
+
+    def _label(self, density_pct: float) -> str:
+        if density_pct > self.MED_CEIL:
+            return 'HIGH'
+        if density_pct > self.LOW_CEIL:
+            return 'MEDIUM'
         return 'LOW'
 
     def _compute_trend(self) -> str:
         if len(self._window) < 6:
             return 'stable'
-        densities = [f.density_score for f in self._window]
-        half  = len(densities) // 2
-        delta = np.mean(densities[half:]) - np.mean(densities[:half])
-        if delta >  0.05: return 'rising'
-        if delta < -0.05: return 'falling'
+        counts = [f.person_count for f in self._window]
+        half  = len(counts) // 2
+        delta = np.mean(counts[half:]) - np.mean(counts[:half])
+        if delta >  3: return 'rising'
+        if delta < -3: return 'falling'
         return 'stable'
 
-    def process_frame(self, fr: FrameResult) -> RiskResult:
+    def _is_boundary(self, fr: FrameResult) -> bool:
+        """Check if this frame is a clip boundary candidate."""
+        p_jump = abs(fr.person_count - self._prev_count) >= self.P_JUMP
+        d_jump = abs(fr.density_score - self._prev_density_sc) >= self.D_JUMP
+        return p_jump or d_jump
+
+    def _reset_clip(self, frame_id: int, reason: str):
+        """Reset all clip state for a new clip segment."""
+        self._clip_id        += 1
+        self._k_deque.clear()
+        self._n_est           = 0
+        self._density_pct     = 0.0
+        self._prev_level      = 'LOW'
+        self._candidate       = None
+        self._candidate_count = 0
+        self._peak_ema        = 0.0
+        self._occ_ema         = 0.0
+        print(f'🎬 [RiskAgent] Clip {self._clip_id} started at frame {frame_id} ({reason})')
+
+    def _update_density(self):
         """
-        4-path scoring: final = max(smooth, instant, preemptive, spatial).
+        Recompute N_est and density_pct from the current sliding K-window.
+        Called every frame — the deque always holds the latest K frames.
         """
-        self._window.append(fr)
-        self._roc_buf.append(fr.person_count)
-
-        counts   = [f.person_count for f in self._window]
-        spacings = [f.avg_spacing  for f in self._window if f.avg_spacing < 999]
+        all_ids = set()
+        for f in self._k_deque:
+            for tid in f.track_ids:
+                all_ids.add(tid)
+        self._n_est       = len(all_ids)
+        self._density_pct = round(min(self._n_est / self.N_REF * 100, 100.0), 1)
 
-        # ── Path 1: Fruin Smooth EMA ──────────────────────────────────
-        current_count  = float(fr.person_count)
-        self._peak_ema = (
-            self.EMA_ALPHA * current_count +
-            (1.0 - self.EMA_ALPHA) * self._peak_ema
-        )
-        c_score = min(self._peak_ema / config.RISK_HIGH_COUNT, 1.0)
-
-        avg_sp  = np.mean(spacings) if spacings else 999
-        s_score = max(0.0, 1.0 - avg_sp / config.RISK_SPACING_REF)
-
-        trend   = self._compute_trend()
-
-        if len(self._roc_buf) == self.ROC_WINDOW:
-            w_roc = self._roc_buf[-1] - self._roc_buf[0]
-        else:
-            w_roc = 0
+    def process_frame(self, fr: FrameResult) -> RiskResult:
+        self._window.append(fr)
 
-        roc_score = max(min(w_roc / 15.0, 1.0), -0.5)
-        if w_roc > 5:
-            t_score = 0.8
-        elif w_roc < -5:
-            t_score = 0.0
+        # ── A) Clip boundary detection with glitch filtering ─────
+        if fr.frame_id > 1 and self._is_boundary(fr):
+            self._boundary_buf += 1
+            if self._boundary_buf >= self.MIN_LEN:
+                # Confirmed boundary — start new clip
+                self._reset_clip(fr.frame_id, f'boundary held {self._boundary_buf} frames')
+                self._boundary_buf = 0
+                self._in_boundary  = False
+            else:
+                self._in_boundary = True
         else:
-            t_score = 0.3
-
-        smooth_score = max(
-            c_score   * self.W_DENSITY +
-            roc_score * self.W_ROC     +
-            t_score   * self.W_TREND,
-            0.0
-        )
-
-        # ── Path 2: Instant floor ─────────────────────────────────────
-        instant_floor = 0.70 if fr.person_count >= config.RISK_HIGH_COUNT else 0.0
-
-        # ── Path 3: Pre-emptive ROC ───────────────────────────────────
-        preemptive = 0.0
-        if (len(self._roc_buf) == self.ROC_WINDOW
-                and w_roc >= self.PRE_ROC
-                and self._peak_ema >= self.PRE_EMA):
-            preemptive = 0.66
-
-        # ── Path 4: Spatial clustering (UQU Haram research) ──────────
-        # If any single cell in the 3×3 grid has >= GRID_CELL_HIGH persons
-        # → local crush risk regardless of global count → floor 0.70.
-        # This catches Mataf-style bottlenecks: dense corner, sparse rest.
-        spatial_floor = 0.0
-        if hasattr(fr, 'grid_max') and fr.grid_max >= self.GRID_CELL_HIGH:
-            spatial_floor = 0.70
-            # Only log when it's the deciding factor
-            if spatial_floor > max(smooth_score, instant_floor, preemptive):
+            if self._in_boundary and self._boundary_buf < self.MIN_LEN:
+                # Glitch — boundary didn't persist, merge back
+                self._boundary_buf = 0
+                self._in_boundary  = False
+            self._boundary_buf = 0
+
+        self._prev_count      = fr.person_count
+        self._prev_density_sc = fr.density_score
+
+        self._k_deque.append(fr)
+        self._update_density()
+
+        density_pct = self._density_pct
+        risk_score  = round(density_pct / 100.0, 4)  # 0.0–1.0
+
+        raw_level = self._label(density_pct)
+
+        # Suppress level_changed until K-window is full (warmup period).
+        # Prevents false P0/P1 triggers in the first K frames of each clip.
+        k_ready = len(self._k_deque) >= self.K_WINDOW
+
+        if raw_level != self._prev_level:
+            if raw_level == self._candidate:
+                self._candidate_count += 1
+            else:
+                self._candidate       = raw_level
+                self._candidate_count = 1
+
+            if k_ready and self._candidate_count >= self.STABLE_FRAMES:
+                risk_level    = raw_level
+                level_changed = True
+                self._prev_level      = raw_level
+                self._candidate       = None
+                self._candidate_count = 0
                 print(
-                    f'   🗺️  [RiskAgent] Spatial hotspot: {fr.hotspot_zone} '
-                    f'({fr.grid_max}p in cell, threshold={self.GRID_CELL_HIGH})'
+                    f'📊 [RiskAgent] Level confirmed: {risk_level} '
+                    f'(density_pct={density_pct:.1f}%, N_est={self._n_est}, '
+                    f'frame={fr.frame_id})'
                 )
+            else:
+                risk_level    = self._prev_level
+                level_changed = False
+        else:
+            risk_level    = self._prev_level
+            level_changed = False
+            self._candidate       = None
+            self._candidate_count = 0
 
-        # ── Final: max of all four paths ──────────────────────────────
-        risk_score = round(
-            float(np.clip(
-                max(smooth_score, instant_floor, preemptive, spatial_floor),
-                0.0, 1.0
-            )),
-            4
+        self._peak_ema = (
+            self.EMA_ALPHA * float(fr.person_count) +
+            (1.0 - self.EMA_ALPHA) * self._peak_ema
         )
 
-        risk_level    = self._label(risk_score)
-        level_changed = risk_level != self._prev_level
-        self._prev_level = risk_level
-
-        self._occ_ema = (
-            self.EMA_ALPHA * fr.occupation_pct +
-            (1.0 - self.EMA_ALPHA) * self._occ_ema
-        )
+        trend  = self._compute_trend()
+        counts = [f.person_count for f in self._window]
 
         return RiskResult(
             frame_id      = fr.frame_id,
@@ -193,5 +203,5 @@ class RiskAgent:
             window_avg    = round(float(np.mean(counts)), 1),
             window_max    = int(max(counts)),
             density_ema   = round(self._peak_ema, 1),
-            density_pct   = round(self._occ_ema, 1),
-        )
+            density_pct   = density_pct,
+        )