Initial commit: set up project skeleton and deploy workflows

.github/workflows/deploy.yml

@@ -0,0 +1,23 @@
+name: Sync to Hugging Face Spaces
+
+on:
+  push:
+    branches: [ main ]
+  # Allow manual trigger from the GitHub Actions tab
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Spaces
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git push --force https://hf_user:$HF_TOKEN@huggingface.co/spaces/YOUR_HF_USERNAME/YOUR_SPACE_NAME main

.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+venv/
+.venv/
+
+# AI Models
+*.pt
+*.pth
+*.onnx
+*.engine
+
+# IDEs & System
+.idea/
+.vscode/
+.project
+.pydevproject
+.DS_Store
+Thumbs.db
+
+# Project Outputs & Temp Files
+outputs/
+outputs_annotated/
+*.mp4
+*.avi
+*.mov
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.pdf
+*.docx
+*.txt
+!requirements.txt
+
+# Local data & environment variables
+.env
+.env.local

app.py

@@ -0,0 +1,237 @@
+import os
+import cv2
+import numpy as np
+import gradio as gr
+import time
+from datetime import datetime
+
+# Ensure project module can be imported
+import sys
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from suspicious_behavior.pipeline.frame_analyzer import FrameAnalyzer
+from suspicious_behavior.pipeline.video_processor import VideoProcessor
+import suspicious_behavior.config as config
+
+# Lazy load analyzer to make space startup quick
+analyzer_instance = None
+
+def get_analyzer():
+    global analyzer_instance
+    if analyzer_instance is None:
+        print("[Gradio] Initializing FrameAnalyzer...")
+        analyzer_instance = FrameAnalyzer(camera_id="demo_cam", violence_stride=8)
+    return analyzer_instance
+
+
+def process_video(video_path, violence_stride, running_threshold, violence_threshold):
+    """
+    Processes the uploaded video file, overlays annotations, and returns the video + log results.
+    """
+    if not video_path:
+        return None, "No video uploaded."
+
+    # Update dynamic configurations from UI sliders
+    config.RUNNING_CONFIDENCE_THRESHOLD = float(running_threshold) / 100.0
+    config.VIOLENCE_CONFIDENCE_THRESHOLD = float(violence_threshold) / 100.0
+    
+    inst = get_analyzer()
+    inst.violence_stride = int(violence_stride)
+    
+    # Reset tracker and frame buffer states
+    inst.frame_idx = 0
+    inst.violence_buffer.clear()
+    inst.alert_manager.reset_cooldowns()
+    
+    processor = VideoProcessor(target_fps=10.0)
+    metadata = processor.get_metadata(video_path)
+    
+    processed_frames = []
+    alert_logs = []
+    
+    start_time = time.time()
+    
+    # Process sampled frames
+    for f_idx, frame, timestamp in processor.extract_frames_generator(video_path):
+        annotated, alerts, frame_meta = inst.analyze(frame, fps=10.0, output_base64=False)
+        processed_frames.append(annotated)
+        
+        # Log any alerts triggered
+        for alert in alerts:
+            alert_logs.append({
+                "time": f"{timestamp:.2f}s",
+                "threat": alert.threat_type.upper(),
+                "confidence": f"{alert.confidence * 100:.1f}%",
+                "severity": alert.severity
+            })
+
+    elapsed_time = time.time() - start_time
+    output_path = "annotated_output.mp4"
+    
+    # Compile output frames to video
+    processor.write_frames_to_video(
+        processed_frames,
+        output_path,
+        fps=10.0,
+        frame_size=(metadata['width'], metadata['height'])
+    )
+    
+    summary = (
+        f"Analysis complete in {elapsed_time:.1f}s!\n"
+        f"Average speed: {len(processed_frames)/elapsed_time:.1f} FPS.\n"
+        f"Alerts triggered: {len(alert_logs)}"
+    )
+    
+    return output_path, alert_logs or "No alerts triggered in this clip."
+
+
+def process_image(image_path, running_threshold):
+    """
+    Processes a single frame. VideoMAE is bypassed (needs 16 frames), but MediaPipe Pose is run.
+    """
+    if image_path is None:
+        return None, "No image uploaded."
+
+    config.RUNNING_CONFIDENCE_THRESHOLD = float(running_threshold) / 100.0
+    
+    # Load image and convert to OpenCV format
+    img = cv2.imread(image_path)
+    if img is None:
+        return None, "Invalid image file."
+
+    inst = get_analyzer()
+    # Reset single frame state
+    inst.frame_idx = 0
+    
+    annotated, alerts, frame_meta = inst.analyze(img, fps=10.0, output_base64=False)
+    
+    alert_list = []
+    for alert in alerts:
+        alert_list.append({
+            "threat": alert.threat_type.upper(),
+            "confidence": f"{alert.confidence * 100:.1f}%",
+            "severity": alert.severity
+        })
+
+    # Render results metadata
+    details = {
+        "active_persons": frame_meta["active_tracks_count"],
+        "alerts": alert_list,
+        "tracks_info": frame_meta["tracks"]
+    }
+    
+    # Convert BGR back to RGB for Gradio display
+    annotated_rgb = cv2.cvtColor(annotated, cv2.COLOR_BGR2RGB)
+    return annotated_rgb, details
+
+
+# Build the Gradio UI Layout
+with gr.Blocks(theme=gr.themes.Soft(), title="SimShieldAI Suspicious Behavior Console") as demo:
+    gr.HTML(
+        """
+        <div style="text-align: center; margin-bottom: 20px;">
+            <h1 style="color: #2D2D2D; font-family: 'Outfit', sans-serif;">SimShieldAI Behavior Console</h1>
+            <p style="color: #666; font-size: 16px;">Production-Grade AI Surveillance Security Suite</p>
+        </div>
+        """
+    )
+    
+    with gr.Tabs():
+        # --- TAB 1: VIDEO ANALYSIS ---
+        with gr.TabItem("Video surveillance stream analyzer"):
+            gr.Markdown(
+                "Upload a CCTV video clip to test violence/fighting detection (VideoMAE) "
+                "and running/sprinting behavior (MediaPipe Pose)."
+            )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    video_input = gr.Video(label="Upload CCTV video")
+                    
+                    gr.Markdown("### Inference Parameters")
+                    violence_stride_slider = gr.Slider(
+                        minimum=2, maximum=16, value=8, step=1,
+                        label="VideoMAE analysis stride (Frames)"
+                    )
+                    run_threshold_slider = gr.Slider(
+                        minimum=30, maximum=95, value=70, step=5,
+                        label="Running detection sensitivity (%)"
+                    )
+                    violence_threshold_slider = gr.Slider(
+                        minimum=30, maximum=95, value=70, step=5,
+                        label="Violence detection sensitivity (%)"
+                    )
+                    
+                    analyze_btn = gr.Button("Analyze surveillance clip", variant="primary")
+                    
+                with gr.Column(scale=2):
+                    video_output = gr.Video(label="Annotated video playback")
+                    alerts_output = gr.JSON(label="Triggered Alert logs")
+            
+            analyze_btn.click(
+                fn=process_video,
+                inputs=[
+                    video_input, 
+                    violence_stride_slider, 
+                    run_threshold_slider, 
+                    violence_threshold_slider
+                ],
+                outputs=[video_output, alerts_output]
+            )
+
+        # --- TAB 2: IMAGE FRAME ANALYSIS ---
+        with gr.TabItem("Single frame analyzer"):
+            gr.Markdown(
+                "Upload a single CCTV screenshot or picture to test keypoint skeleton extraction "
+                "and running/sprinting pose geometry."
+            )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    image_input = gr.Image(type="filepath", label="Upload frame screenshot")
+                    img_run_threshold_slider = gr.Slider(
+                        minimum=30, maximum=95, value=70, step=5,
+                        label="Running detection sensitivity (%)"
+                    )
+                    analyze_img_btn = gr.Button("Analyze frame", variant="primary")
+                    
+                with gr.Column(scale=2):
+                    image_output = gr.Image(label="Annotated frame output")
+                    details_output = gr.JSON(label="Extraction diagnostics")
+                    
+            analyze_img_btn.click(
+                fn=process_image,
+                inputs=[image_input, img_run_threshold_slider],
+                outputs=[image_output, details_output]
+            )
+
+        # --- TAB 3: SYSTEM PARAMETERS & GUIDE ---
+        with gr.TabItem("System guidelines"):
+            gr.Markdown(
+                """
+                ## SimShieldAI behavior detection details
+                
+                This testing console serves as the staging deployment for **Milestone 1** of SimShieldAI.
+                
+                ### How the engines operate:
+                
+                1. **YOLO Person Detection**:
+                   - Identifies all persons in the frame using YOLOv8n (optimized for real-time edge processing).
+                2. **SORT Object Tracker**:
+                   - Maintains persistent IDs for each individual across frames. This allows the system to measure movement velocity and avoid triggering duplicate alerts.
+                3. **Violence Detection (VideoMAE)**:
+                   - Gathers a sliding buffer of 16 frames. Once filled, the VideoMAE crime detector classifies the temporal clip for fighting/assault.
+                4. **Running Detection (MediaPipe Pose)**:
+                   - Calculates real-time 33-point geometric skeleton models.
+                   - Applies a weighted kinematics scorecard based on:
+                     - **Stride angle** (hips-ankles angle)
+                     - **Torso lean** (angle from vertical axis)
+                     - **Displacement speed** (center of mass movement velocity)
+                     - **Knee drive** (height of knee relative to torso length)
+                     
+                ### Cooldown Deduplication:
+                - The system implements a **60-second cooldown** per behavior per camera. If a fight is detected, only one alert is generated, preventing operators from being flooded.
+                """
+            )
+
+# Run Gradio application
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

diagnose_thresholds.py

@@ -0,0 +1,148 @@
+# from pathlib import Path
+
+# from ultralytics import YOLO
+
+
+# root = Path(__file__).resolve().parent
+# model = YOLO(str(root / "model" / "best.pt"))
+# source = root / "samples" / "cctv1image2.jpg"
+
+# print(f"Testing {source.name} with very low confidence thresholds")
+# print(f"Model classes: {model.names}")
+
+# for conf in [0.01, 0.05, 0.10, 0.15, 0.20, 0.25]:
+#     results = model.predict(
+#         source=str(source),
+#         imgsz=1280,
+#         conf=conf,
+#         save=False,
+#         verbose=False,
+#     )
+#     boxes = results[0].boxes
+#     print(f"\nconf={conf:.2f} detections={len(boxes)}")
+#     for box in boxes[:10]:
+#         cls_id = int(box.cls[0])
+#         score = float(box.conf[0])
+#         label = model.names.get(cls_id, str(cls_id))
+#         print(f"- {label}: {score:.4f}")
+# import cv2
+# import supervision as sv
+# from inference import get_model
+
+
+# project = rf.workspace("ddroid6ty").project("weapon-detection-o3pp0")
+
+# model = get_model(model_id="ddroid6ty/weapon-detection-o3pp0/1", api_key="u8tcoa3IPDkjPsBa2CvY")
+
+
+
+
+
+
+import cv2
+import numpy as np
+import supervision as sv
+from roboflow import Roboflow
+import json
+
+# -----------------------------
+# Load Roboflow model
+# -----------------------------
+rf = Roboflow(api_key="u8tcoa3IPDkjPsBa2CvY")
+project = rf.workspace("ddroid6ty").project("weapon-detection-o3pp0")
+model = project.version(1).model
+
+
+# -----------------------------
+# Store detections globally (for debugging)
+# -----------------------------
+all_predictions = []
+
+
+# -----------------------------
+# Callback function
+# -----------------------------
+def callback(image):
+    global all_predictions
+
+    result = model.predict(image, confidence=25).json()
+
+    xyxy, confidences, class_ids = [], [], []
+
+    for pred in result["predictions"]:
+        x1 = pred["x"] - pred["width"] / 2
+        y1 = pred["y"] - pred["height"] / 2
+        x2 = pred["x"] + pred["width"] / 2
+        y2 = pred["y"] + pred["height"] / 2
+
+        xyxy.append([x1, y1, x2, y2])
+        confidences.append(pred["confidence"])
+        class_ids.append(pred["class_id"])
+
+        # 🔥 Save full debug info
+        all_predictions.append(pred)
+
+    if len(xyxy) == 0:
+        return sv.Detections.empty()
+
+    return sv.Detections(
+        xyxy=np.array(xyxy),
+        confidence=np.array(confidences),
+        class_id=np.array(class_ids)
+    )
+
+
+# -----------------------------
+# SAHI slicer
+# -----------------------------
+slicer = sv.InferenceSlicer(
+    callback=callback,
+    slice_wh=(640, 640),
+    overlap_wh=(100, 100),
+)
+
+
+# -----------------------------
+# Load image
+# -----------------------------
+image = cv2.imread("cctvimage2.jpg")
+
+detections = slicer(image)
+
+
+# -----------------------------
+# Annotate image
+# -----------------------------
+box_annotator = sv.BoxAnnotator()
+
+annotated = box_annotator.annotate(
+    scene=image.copy(),
+    detections=detections
+)
+
+cv2.imwrite("outputs/sahi_result.jpg", annotated)
+
+
+# -----------------------------
+# PRINT CLEAN RESULTS (IMPORTANT)
+# -----------------------------
+print("\n===== DETECTION SUMMARY =====")
+print(f"Total detections: {len(detections)}\n")
+
+for i, pred in enumerate(all_predictions):
+    print(f"[{i+1}]")
+    print(f"  Class      : {pred.get('class', 'unknown')}")
+    print(f"  Confidence : {pred['confidence']*100:.2f}%")
+    print(f"  Center X   : {pred['x']}")
+    print(f"  Center Y   : {pred['y']}")
+    print("---------------------------")
+
+
+# -----------------------------
+# SAVE JSON FILE (VERY USEFUL)
+# -----------------------------
+with open("outputs/detections.json", "w") as f:
+    json.dump(all_predictions, f, indent=4)
+
+print("\nSaved: outputs/detections.json")
+print("Saved: outputs/sahi_result.jpg")

model/classes.json

@@ -0,0 +1,6 @@
+{
+  "1": "Gun",
+  "2": "Explosive",
+  "3": "Grenade",
+  "4": "Knife"
+}

model_results_comparison.md

@@ -0,0 +1,51 @@
+# Side-by-Side Model Comparison: Roboflow V4 vs. YOLOv11
+
+Below is a comparison of the detections on the key CCTV test images. You can see how each model performs on the same scene.
+
+---
+
+## 1. CCTV Image 3 (Client Reported Issue)
+* **Roboflow V4:** Missed the gun at standard thresholds (detected gun at 28% only when padded).
+* **YOLOv11:** Successfully detected the gun at **76% confidence**.
+
+````carousel
+![Roboflow V4 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/roboflow_v4_results/cctvimage3.jpg)
+<!-- slide -->
+![YOLOv11 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/yolov11_results/cctvimage3.jpg)
+````
+
+---
+
+## 2. CCTV Image 2
+* **Roboflow V4:** Detected both the shooter (89%) and the gun (46%).
+* **YOLOv11:** Detected the gun (49.5%).
+
+````carousel
+![Roboflow V4 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/roboflow_v4_results/cctvimage2.jpg)
+<!-- slide -->
+![YOLOv11 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/yolov11_results/cctvimage2.jpg)
+````
+
+---
+
+## 3. CCTV Image 6
+* **Roboflow V4:** Detected the shooter (81.4%).
+* **YOLOv11:** Detected the gun (39.6%).
+
+````carousel
+![Roboflow V4 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/roboflow_v4_results/cctvimage6.jpg)
+<!-- slide -->
+![YOLOv11 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/yolov11_results/cctvimage6.jpg)
+````
+
+---
+
+## 4. CCTV 1 Image
+* **Roboflow V4:** No detections when padded (23% gun on direct).
+* **YOLOv11:** Detected the gun (23%).
+
+````carousel
+![Roboflow V4 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/roboflow_v4_results/cctv1image.jpg)
+<!-- slide -->
+![YOLOv11 Result](/C:/Users/Admin/.gemini/antigravity/brain/a6bb55bc-fb11-4b23-93c4-2b7a3eec14f1/yolov11_results/cctv1image.jpg)
+````

read_docx.py

@@ -0,0 +1,45 @@
+import zipfile
+import xml.etree.ElementTree as ET
+import os
+import sys
+
+# Set encoding to utf-8 for stdout if possible
+try:
+    sys.stdout.reconfigure(encoding='utf-8')
+except AttributeError:
+    pass
+
+docx_path = r"C:\Users\Admin\Downloads\SimShieldAI_Phase2_Report.docx"
+
+if not os.path.exists(docx_path):
+    print(f"File not found at: {docx_path}")
+else:
+    try:
+        with zipfile.ZipFile(docx_path) as docx:
+            xml_content = docx.read('word/document.xml')
+            root = ET.fromstring(xml_content)
+            
+            # XML namespaces
+            namespaces = {'w': 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'}
+            
+            paragraphs = []
+            for paragraph in root.iter('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}p'):
+                texts = [node.text for node in paragraph.iter('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}t') if node.text]
+                if texts:
+                    paragraphs.append("".join(texts))
+            
+            content = "\n".join(paragraphs)
+            
+            # Save to txt file
+            txt_path = r"c:\Users\Admin\Desktop\testing_model\extracted_text.txt"
+            with open(txt_path, "w", encoding="utf-8") as f:
+                f.write(content)
+            
+            print(f"Successfully extracted text to: {txt_path}")
+            
+            # Print with errors='replace' to avoid console crashes
+            print("\n--- CONTENT OF DOCX ---")
+            print(content.encode('ascii', errors='replace').decode('ascii'))
+            print("-----------------------\n")
+    except Exception as e:
+        print(f"Error reading docx: {e}")

requirements.txt

@@ -0,0 +1,20 @@
+# Core AI & Computer Vision
+ultralytics>=8.4.0
+transformers>=4.40.0
+torch
+torchvision
+mediapipe>=0.10.0
+opencv-python-headless
+numpy<2.0.0
+protobuf==4.25.3
+
+# Object Tracking
+scipy
+filterpy
+
+# API & UI Server
+gradio>=4.0.0
+fastapi
+uvicorn
+python-multipart
+pydantic

suspicious_behavior/__init__.py

@@ -0,0 +1 @@
+# Suspicious Behavior Package

suspicious_behavior/alerts/__init__.py

@@ -0,0 +1 @@
+# Alerts submodule

suspicious_behavior/alerts/alert_manager.py

@@ -0,0 +1,70 @@
+import time
+from datetime import datetime
+from suspicious_behavior.config import ALERT_COOLDOWN_SECONDS, ALERT_SEVERITY_MAPPING
+from suspicious_behavior.alerts.alert_models import AlertPayload
+
+class AlertManager:
+    """
+    Production-grade Alert Deduplication and Event Manager.
+    Enforces cooldown rules per camera and behavior to prevent alert flooding.
+    """
+    def __init__(self, cooldown_seconds=ALERT_COOLDOWN_SECONDS):
+        self.cooldown_seconds = cooldown_seconds
+        # Stores the last triggered timestamp: {(camera_id, threat_type): float_timestamp}
+        self.alert_history = {}
+
+    def trigger_alert(self, threat_type, confidence, camera_id="camera_1", track_id=None, bbox=None, frame_image=None, metadata=None, current_time=None):
+        """
+        Processes a threat event. Generates a validated AlertPayload if cooldown criteria is met.
+        
+        Args:
+            threat_type (str): The type of threat (e.g. "fighting", "running")
+            confidence (float): The detection confidence (0.0 to 1.0)
+            camera_id (str): Camera identifier
+            track_id (int, optional): Persistent tracker ID of the subject
+            bbox (list, optional): Bounding box of the subject [x1, y1, x2, y2]
+            frame_image (str, optional): Base64 JPEG representation of the frame
+            metadata (dict, optional): Contextual statistics and metrics
+            current_time (float, optional): Timeline timestamp (e.g. video seconds). Defaults to time.time().
+            
+        Returns:
+            AlertPayload or None: Returns the alert payload if successfully triggered, or None if deduplicated.
+        """
+        if current_time is None:
+            current_time = time.time()
+        history_key = (camera_id, threat_type.lower())
+        
+        # Cooldown check
+        if history_key in self.alert_history:
+            elapsed = current_time - self.alert_history[history_key]
+            if elapsed < self.cooldown_seconds:
+                # Deduplicated (suppressed due to active cooldown)
+                return None
+        
+        # Update last alert timestamp
+        self.alert_history[history_key] = current_time
+        
+        # Resolve severity mapping
+        severity = ALERT_SEVERITY_MAPPING.get(threat_type.lower(), "MEDIUM")
+        
+        # Construct and validate alert payload
+        alert = AlertPayload(
+            timestamp=datetime.now().isoformat(),
+            camera_id=camera_id,
+            threat_type=threat_type,
+            confidence=confidence,
+            severity=severity,
+            track_id=track_id,
+            bounding_box=[float(coord) for coord in bbox] if bbox is not None else None,
+            frame_image=frame_image,
+            metadata=metadata or {}
+        )
+        
+        print(f"[AlertManager] [{severity}] Alert triggered: {threat_type} ({confidence*100:.1f}%) on {camera_id}!")
+        return alert
+
+    def reset_cooldowns(self):
+        """
+        Resets all active alert cooldown states.
+        """
+        self.alert_history.clear()

suspicious_behavior/alerts/alert_models.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Any
+
+class AlertPayload(BaseModel):
+    """
+    Standardized payload format for system alerts.
+    Ready to be consumed by client webhooks or pushed via Firebase.
+    """
+    timestamp: str = Field(..., description="ISO 8601 formatted timestamp of the alert")
+    camera_id: str = Field(default="camera_1", description="Identifier of the source camera")
+    threat_type: str = Field(..., description="Detected behavior/threat type (e.g. fighting, running)")
+    confidence: float = Field(..., description="AI confidence score between 0.0 and 1.0")
+    severity: str = Field(..., description="Alert severity (CRITICAL, HIGH, MEDIUM, LOW)")
+    track_id: Optional[int] = Field(None, description="Persistent tracker ID of the subject")
+    bounding_box: Optional[List[float]] = Field(None, description="Bounding box of the subject [x1, y1, x2, y2]")
+    frame_image: Optional[str] = Field(None, description="Base64 encoded JPEG frame containing the detection")
+    metadata: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Additional debugging metrics or raw outputs")

suspicious_behavior/api/__init__.py

@@ -0,0 +1 @@
+# API submodule

suspicious_behavior/api/server.py

@@ -0,0 +1,196 @@
+import os
+import cv2
+import numpy as np
+import uuid
+import shutil
+from fastapi import FastAPI, File, UploadFile, Query, HTTPException
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from typing import List, Dict, Any
+
+from suspicious_behavior.config import API_HOST, API_PORT
+from suspicious_behavior.pipeline.frame_analyzer import FrameAnalyzer
+from suspicious_behavior.pipeline.video_processor import VideoProcessor
+
+# Initialize FastAPI application
+app = FastAPI(
+    title="SimShieldAI Suspicious Behavior API",
+    description="Production-grade API for detecting fighting, violence, and running/sprinting in CCTV surveillance.",
+    version="1.0.0"
+)
+
+# Add CORS Middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Workspace directories for temporary assets
+WORKSPACE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+TEMP_DIR = os.path.join(WORKSPACE_DIR, "temp")
+os.makedirs(TEMP_DIR, exist_ok=True)
+
+# Lazy loading of FrameAnalyzer to speed up initial server startup
+analyzer = None
+
+def get_analyzer():
+    global analyzer
+    if analyzer is None:
+        analyzer = FrameAnalyzer(camera_id="api_camera_1")
+    return analyzer
+
+
+@app.get("/api/health")
+async def health_check():
+    """
+    Checks system health and returns model status and execution device (CPU/GPU).
+    """
+    try:
+        # Initialize analyzer to verify models load successfully
+        inst = get_analyzer()
+        return {
+            "status": "healthy",
+            "device": str(inst.violence_engine.device),
+            "yolo_model": str(inst.yolo.model_name),
+            "violence_model": inst.violence_engine.labels,
+            "timestamp": str(np.datetime64('now'))
+        }
+    except Exception as e:
+        return JSONResponse(
+            status_code=500,
+            content={"status": "unhealthy", "error": str(e)}
+        )
+
+
+@app.post("/api/detect")
+async def detect_image(
+    file: UploadFile = File(..., description="JPEG/PNG image file containing the scene to analyze"),
+    return_image: bool = Query(True, description="If true, returns base64 annotated image in the JSON response")
+):
+    """
+    Analyzes a single image for suspicious behavior (such as running poses).
+    """
+    if not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="Uploaded file must be an image.")
+
+    try:
+        contents = await file.read()
+        nparr = np.frombuffer(contents, np.uint8)
+        img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        
+        if img is None:
+            raise HTTPException(status_code=400, detail="Invalid image data.")
+
+        # Process image using our frame analyzer
+        # (VideoMAE is skipped for single frames if buffer is not full, which is normal)
+        inst = get_analyzer()
+        annotated_frame, alerts, metadata = inst.analyze(img, fps=10.0, output_base64=return_image)
+
+        response_data = {
+            "metadata": metadata,
+            "alerts_triggered": [alert.model_dump() for alert in alerts]
+        }
+        
+        if return_image and len(alerts) > 0:
+            response_data["annotated_frame_base64"] = alerts[0].frame_image
+        elif return_image:
+            # If no alerts, manually encode the frame to base64
+            _, buffer = cv2.imencode('.jpg', annotated_frame)
+            import base64
+            response_data["annotated_frame_base64"] = base64.b64encode(buffer).decode('utf-8')
+
+        return response_data
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Image processing failed: {str(e)}")
+
+
+@app.post("/api/analyze-video")
+async def analyze_video(
+    file: UploadFile = File(..., description="MP4, AVI, or MOV video file to process")
+):
+    """
+    Processes an entire video clip. Annotates the video with tracking skeletons
+    and alert banners, and returns the fully processed video file for download.
+    """
+    # Check video extension
+    filename = file.filename
+    ext = os.path.splitext(filename)[1].lower()
+    if ext not in [".mp4", ".avi", ".mov", ".mkv"]:
+        raise HTTPException(status_code=400, detail="File must be a valid video format (mp4, avi, mov, mkv)")
+
+    # Define temporary file paths
+    unique_id = str(uuid.uuid4())
+    input_path = os.path.join(TEMP_DIR, f"input_{unique_id}{ext}")
+    output_path = os.path.join(TEMP_DIR, f"output_{unique_id}.mp4")
+
+    try:
+        # Save uploaded file to disk
+        with open(input_path, "wb") as buffer:
+            shutil.copyfileobj(file.file, buffer)
+
+        # Initialize processor and frame analyzer
+        processor = VideoProcessor(target_fps=10.0)
+        metadata = processor.get_metadata(input_path)
+        
+        inst = get_analyzer()
+        # Reset state (so frame indices start clean for this video)
+        inst.frame_idx = 0
+        inst.violence_buffer.clear()
+        inst.alert_manager.reset_cooldowns()
+
+        processed_frames = []
+        all_metadata = []
+        all_alerts = []
+
+        print(f"[API] Processing video: {filename} ({metadata['frame_count']} frames at {metadata['fps']:.1f} FPS)...")
+
+        # Iterate through sampled frames
+        for f_idx, frame, timestamp in processor.extract_frames_generator(input_path):
+            annotated, alerts, frame_meta = inst.analyze(frame, fps=10.0, output_base64=False)
+            processed_frames.append(annotated)
+            all_metadata.append(frame_meta)
+            for alert in alerts:
+                all_alerts.append(alert.model_dump())
+
+        # Compile processed frames back to output video
+        # We process at 10.0 FPS, so output video should play back at 10.0 FPS
+        processor.write_frames_to_video(
+            processed_frames, 
+            output_path, 
+            fps=10.0, 
+            frame_size=(metadata['width'], metadata['height'])
+        )
+
+        # Return the processed video file for immediate playback/download
+        # FastAPI will handle cleaning up files if we use background tasks, but for simple VM,
+        # we can return it and let the user delete it or keep a cache.
+        return FileResponse(
+            path=output_path, 
+            filename=f"annotated_{filename}", 
+            media_type="video/mp4"
+        )
+
+    except Exception as e:
+        # Cleanup input file if it was created
+        if os.path.exists(input_path):
+            os.remove(input_path)
+        raise HTTPException(status_code=500, detail=f"Video processing failed: {str(e)}")
+
+    finally:
+        # Clean up input file after processing is complete
+        if os.path.exists(input_path):
+            try:
+                os.remove(input_path)
+            except Exception:
+                pass
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print(f"[API] Starting FastAPI server on {API_HOST}:{API_PORT}...")
+    uvicorn.run("server:app", host=API_HOST, port=API_PORT, reload=True)

suspicious_behavior/config.py

@@ -0,0 +1,68 @@
+import os
+
+# --- System Environment ---
+ENV = os.getenv("ENV", "development")
+
+# --- Model Configurations ---
+# Standard YOLOv8n for fast person detection (class 0 is person)
+YOLO_MODEL_PATH = os.getenv("YOLO_MODEL_PATH", "yolov8n.pt")
+
+# VideoMAE Violence Detection model from Hugging Face
+VIOLENCE_MODEL_NAME = os.getenv("VIOLENCE_MODEL_NAME", "Nikeytas/videomae-crime-detector-ultra-v1")
+VIOLENCE_PROCESSOR_NAME = os.getenv("VIOLENCE_PROCESSOR_NAME", "MCG-NJU/videomae-base")
+
+# --- Violence Detection Parameters ---
+VIOLENCE_CONFIDENCE_THRESHOLD = 0.70  # Alert if confidence above this
+VIOLENCE_FRAME_COUNT = 16  # VideoMAE expects exactly 16 frames
+
+# --- Running/Sprinting Parameters (MediaPipe Rules) ---
+RUNNING_CONFIDENCE_THRESHOLD = 0.70
+MIN_RUNNING_FRAMES = 4  # Temporal persistence (must persist for 4 frames)
+
+# Weighted scoring rule parameters
+RULE_STRIDE_THRESHOLD = 45.0  # degrees
+RULE_STRIDE_WEIGHT = 0.30
+
+RULE_LEAN_THRESHOLD = 18.0   # degrees
+RULE_LEAN_WEIGHT = 0.20
+
+RULE_DISPLACEMENT_THRESHOLD = 5.0  # normalized displacement (speed)
+RULE_DISPLACEMENT_WEIGHT = 0.30
+
+RULE_KNEE_DRIVE_THRESHOLD = 0.30   # ratio to thigh/leg length
+RULE_KNEE_DRIVE_WEIGHT = 0.20
+
+# Anti-Fight Filter: prevents fighting from being classified as running
+DIRECTION_CONSISTENCY_THRESHOLD = 0.5  # At least 50% of frames must have consistent direction
+MIN_DISPLACEMENT_FOR_RUNNING = 1.5     # Minimum net displacement (in torso heights) over tracking window
+
+# Minimum person crop size (pixels) — skip pose analysis on tiny distant people
+MIN_PERSON_CROP_SIZE = 80  # Both width and height must exceed this
+
+# --- Person Tracker Parameters (SORT) ---
+TRACKER_MAX_AGE = 30       # Maximum frames to keep lost track alive (increased for fight occlusion)
+TRACKER_MIN_HITS = 3       # Minimum hits before track is confirmed
+TRACKER_IOU_THRESHOLD = 0.2 # Lowered to improve re-association during close contact
+
+# --- Violence State Smoothing ---
+VIOLENCE_DECAY_SECONDS = 5.0     # Keep violence active for 5s after last positive detection
+VIOLENCE_EMA_ALPHA = 0.3         # Exponential moving average weight (lower = smoother, 0.3 is conservative)
+
+# --- Violence Escalation ---
+VIOLENCE_ESCALATION_SECONDS = 10.0   # Sustained violence duration to trigger escalation
+VIOLENCE_ESCALATION_THRESHOLD = 0.95 # Confidence must stay above this for escalation
+
+# --- Alert Manager Parameters ---
+ALERT_COOLDOWN_SECONDS = 60.0  # Cooldown per camera per threat type
+ALERT_SEVERITY_MAPPING = {
+    "fighting": "CRITICAL",
+    "violence": "CRITICAL",
+    "violence_escalated": "CRITICAL",
+    "running": "HIGH",
+    "sprinting": "HIGH",
+    "suspicious": "MEDIUM"
+}
+
+# --- FastAPI API Configurations ---
+API_HOST = "0.0.0.0"
+API_PORT = 8000

suspicious_behavior/engines/__init__.py

@@ -0,0 +1 @@
+# Engines submodule

suspicious_behavior/engines/running_engine.py

@@ -0,0 +1,309 @@
+import math
+import numpy as np
+import mediapipe as mp
+from suspicious_behavior.config import (
+    RULE_STRIDE_THRESHOLD, RULE_STRIDE_WEIGHT,
+    RULE_LEAN_THRESHOLD, RULE_LEAN_WEIGHT,
+    RULE_DISPLACEMENT_THRESHOLD, RULE_DISPLACEMENT_WEIGHT,
+    RULE_KNEE_DRIVE_THRESHOLD, RULE_KNEE_DRIVE_WEIGHT,
+    RUNNING_CONFIDENCE_THRESHOLD, MIN_RUNNING_FRAMES,
+    DIRECTION_CONSISTENCY_THRESHOLD, MIN_DISPLACEMENT_FOR_RUNNING
+)
+
+class RunningEngine:
+    """
+    MediaPipe Pose-based running and sprinting detection engine.
+    Analyzes body skeleton landmarks and kinematics to calculate a running confidence score.
+    """
+    def __init__(self):
+        # Initialize MediaPipe Pose
+        self.mp_pose = mp.solutions.pose
+        self.pose = self.mp_pose.Pose(
+            static_image_mode=False,
+            model_complexity=1,  # Balanced for speed/accuracy on CPU
+            enable_segmentation=False,
+            min_detection_confidence=0.5,
+            min_tracking_confidence=0.5
+        )
+        
+        # Track history for displacement speed calculation
+        # Format: {track_id: [(frame_idx, hip_center_x, hip_center_y, torso_height), ...]}
+        self.track_history = {}
+        self.max_history_len = 10
+        
+        # Direction history for consistency check (filters out erratic fight movement)
+        # Format: {track_id: [direction_angle_radians, ...]}
+        self.direction_history = {}
+        self.max_direction_history = 6
+        
+        # Consecutive running frame count per track (temporal persistence filter)
+        # Format: {track_id: int}
+        self.running_streak = {}
+
+    def clean_history(self, active_track_ids):
+        """
+        Cleans up tracking history for IDs that are no longer active to prevent memory leaks.
+        """
+        for store in [self.track_history, self.direction_history, self.running_streak]:
+            inactive_ids = [tid for tid in store if tid not in active_track_ids]
+            for tid in inactive_ids:
+                del store[tid]
+
+    def _calculate_angle_2d(self, a, b, c):
+        """
+        Calculate angle ABC in degrees (vertex is b).
+        a, b, c are tuples or numpy arrays of (x, y).
+        """
+        ba = np.array(a) - np.array(b)
+        bc = np.array(c) - np.array(b)
+
+        cosine_angle = np.dot(ba, bc) / (np.linalg.norm(ba) * np.linalg.norm(bc) + 1e-6)
+        cosine_angle = np.clip(cosine_angle, -1.0, 1.0)
+        angle = np.arccos(cosine_angle)
+
+        return np.degrees(angle)
+
+    def analyze_pose(self, person_crop, track_id, frame_idx, fps=10.0):
+        """
+        Processes a person crop to extract skeleton landmarks and calculate running confidence.
+        
+        Args:
+            person_crop (numpy.ndarray): Bounding box crop of the person from the frame
+            track_id (int): Persistent ID of the person from the tracker
+            frame_idx (int): Current frame index in the video
+            fps (float): Video processing framerate
+            
+        Returns:
+            dict: Detection results containing keypoints, rule scores, and final confidence.
+        """
+        if person_crop is None or person_crop.size == 0:
+            return self._empty_result()
+
+        # Convert BGR to RGB for MediaPipe
+        rgb_crop = person_crop[:, :, ::-1]
+        results = self.pose.process(rgb_crop)
+
+        if not results.pose_landmarks:
+            return self._empty_result()
+
+        landmarks = results.pose_landmarks.landmark
+        h_crop, w_crop, _ = person_crop.shape
+
+        # Helper to convert landmark to pixel coordinates relative to crop
+        def lm_point(lm):
+            return np.array([lm.x * w_crop, lm.y * h_crop])
+
+        # Extract landmarks needed for rules
+        try:
+            # Hips
+            left_hip = lm_point(landmarks[self.mp_pose.PoseLandmark.LEFT_HIP])
+            right_hip = lm_point(landmarks[self.mp_pose.PoseLandmark.RIGHT_HIP])
+            hip_center = (left_hip + right_hip) / 2.0
+
+            # Shoulders
+            left_shoulder = lm_point(landmarks[self.mp_pose.PoseLandmark.LEFT_SHOULDER])
+            right_shoulder = lm_point(landmarks[self.mp_pose.PoseLandmark.RIGHT_SHOULDER])
+            shoulder_center = (left_shoulder + right_shoulder) / 2.0
+
+            # Knees
+            left_knee = lm_point(landmarks[self.mp_pose.PoseLandmark.LEFT_KNEE])
+            right_knee = lm_point(landmarks[self.mp_pose.PoseLandmark.RIGHT_KNEE])
+
+            # Ankles
+            left_ankle = lm_point(landmarks[self.mp_pose.PoseLandmark.LEFT_ANKLE])
+            right_ankle = lm_point(landmarks[self.mp_pose.PoseLandmark.RIGHT_ANKLE])
+            
+            # Torso height acts as our normalizer for displacement and knee height
+            torso_vector = shoulder_center - hip_center
+            torso_height = np.linalg.norm(torso_vector) + 1e-6
+
+        except (IndexError, ValueError):
+            return self._empty_result()
+
+        # --- RULE 1: Stride Angle ---
+        # Angle between left ankle -> hip center -> right ankle
+        stride_angle = self._calculate_angle_2d(left_ankle, hip_center, right_ankle)
+        # Normalize stride score: 0 to 1 based on threshold
+        stride_score = min(stride_angle / RULE_STRIDE_THRESHOLD, 1.5)
+        # We cap the score at 1.0 but allow a small boost for extreme strides
+        stride_score = min(stride_score, 1.0)
+
+        # --- RULE 2: Body Lean ---
+        # Torso vector angle relative to the vertical axis (0, -1) pointing up
+        # In screen space, y decreases upwards.
+        torso_dy = hip_center[1] - shoulder_center[1]  # positive if shoulder is above hip
+        torso_dx = shoulder_center[0] - hip_center[0]
+        
+        # Calculate angle of torso from vertical
+        lean_angle_rad = math.atan2(abs(torso_dx), torso_dy)
+        lean_angle = math.degrees(lean_angle_rad)
+        
+        lean_score = min(lean_angle / RULE_LEAN_THRESHOLD, 1.0)
+
+        # --- RULE 3: Knee Drive ---
+        # Vertical distance from knee to hip normalized by torso height
+        # Higher knee drive = running.
+        left_knee_lift = (hip_center[1] - left_knee[1]) / torso_height
+        right_knee_lift = (hip_center[1] - right_knee[1]) / torso_height
+        max_knee_lift = max(left_knee_lift, right_knee_lift)
+        
+        knee_drive_score = min(max(max_knee_lift, 0.0) / RULE_KNEE_DRIVE_THRESHOLD, 1.0)
+
+        # --- RULE 4: Displacement Speed + Direction Consistency ---
+        speed_score = 0.0
+        normalized_speed = 0.0
+        direction_consistency = 0.0
+        net_displacement = 0.0
+        
+        # Update history for track ID
+        if track_id is not None:
+            if track_id not in self.track_history:
+                self.track_history[track_id] = []
+            if track_id not in self.direction_history:
+                self.direction_history[track_id] = []
+            if track_id not in self.running_streak:
+                self.running_streak[track_id] = 0
+            
+            self.track_history[track_id].append((frame_idx, hip_center[0], hip_center[1], torso_height))
+            
+            # Keep history within limit
+            if len(self.track_history[track_id]) > self.max_history_len:
+                self.track_history[track_id].pop(0)
+                
+            # Compute speed and direction if we have history
+            history = self.track_history[track_id]
+            if len(history) >= 2:
+                # Frame-to-frame displacement for direction tracking
+                prev_frame, prev_x, prev_y, prev_th = history[-2]
+                dx_frame = hip_center[0] - prev_x
+                dy_frame = hip_center[1] - prev_y
+                frame_dist = math.sqrt(dx_frame**2 + dy_frame**2)
+                
+                # Track direction angle if person actually moved
+                if frame_dist > 2.0:  # Minimum pixel movement to register direction
+                    direction_angle = math.atan2(dy_frame, dx_frame)
+                    self.direction_history[track_id].append(direction_angle)
+                    if len(self.direction_history[track_id]) > self.max_direction_history:
+                        self.direction_history[track_id].pop(0)
+                
+                # Compare current frame with the oldest frame in history for speed
+                old_frame, old_x, old_y, old_th = history[0]
+                frame_diff = frame_idx - old_frame
+                
+                if frame_diff > 0:
+                    time_diff = frame_diff / fps
+                    # Compute pixel displacement
+                    dx = hip_center[0] - old_x
+                    dy = hip_center[1] - old_y
+                    pixel_dist = math.sqrt(dx**2 + dy**2)
+                    
+                    # Normalize displacement by average torso height of the person
+                    avg_torso_height = (torso_height + old_th) / 2.0
+                    normalized_dist = pixel_dist / avg_torso_height
+                    net_displacement = normalized_dist
+                    
+                    # Normalized Speed is: torso heights moved per second
+                    normalized_speed = normalized_dist / time_diff
+                    speed_score = min(normalized_speed / RULE_DISPLACEMENT_THRESHOLD, 1.0)
+                
+                # --- Direction Consistency Check ---
+                # Running has consistent directional movement.
+                # Fighting has erratic, back-and-forth movement with low net displacement.
+                dir_hist = self.direction_history[track_id]
+                if len(dir_hist) >= 3:
+                    # Compute angular differences between consecutive directions
+                    angle_diffs = []
+                    for i in range(1, len(dir_hist)):
+                        diff = abs(dir_hist[i] - dir_hist[i-1])
+                        # Normalize to [0, pi]
+                        if diff > math.pi:
+                            diff = 2 * math.pi - diff
+                        angle_diffs.append(diff)
+                    
+                    # Consistency = fraction of frames where direction change is small (<45 degrees)
+                    consistent_count = sum(1 for d in angle_diffs if d < math.pi / 4)
+                    direction_consistency = consistent_count / len(angle_diffs)
+                else:
+                    # Not enough direction history — default to low consistency (safer)
+                    direction_consistency = 0.0
+
+        # --- Weighted Running Score ---
+        running_confidence = (
+            (stride_score * RULE_STRIDE_WEIGHT) +
+            (lean_score * RULE_LEAN_WEIGHT) +
+            (knee_drive_score * RULE_KNEE_DRIVE_WEIGHT) +
+            (speed_score * RULE_DISPLACEMENT_WEIGHT)
+        )
+
+        # --- Anti-Fight Filter ---
+        # Suppress running classification if movement is erratic (fighting pattern).
+        # Real running requires: consistent direction + meaningful net displacement.
+        is_running_raw = running_confidence >= RUNNING_CONFIDENCE_THRESHOLD
+        is_running = False
+        
+        if is_running_raw:
+            has_consistent_direction = direction_consistency >= DIRECTION_CONSISTENCY_THRESHOLD
+            has_net_displacement = net_displacement >= MIN_DISPLACEMENT_FOR_RUNNING
+            
+            if has_consistent_direction and has_net_displacement:
+                # Temporal persistence: must be running for MIN_RUNNING_FRAMES consecutive frames
+                self.running_streak[track_id] = self.running_streak.get(track_id, 0) + 1
+                if self.running_streak[track_id] >= MIN_RUNNING_FRAMES:
+                    is_running = True
+            else:
+                # Erratic movement detected — likely fighting, not running
+                self.running_streak[track_id] = 0
+        else:
+            self.running_streak[track_id] = 0
+
+        # Structure normalized landmarks for overlays (relative to crop)
+        keypoints = {}
+        for lm_enum in self.mp_pose.PoseLandmark:
+            lm = landmarks[lm_enum.value]
+            keypoints[lm_enum.name] = {
+                "x": lm.x, "y": lm.y, "z": lm.z, "visibility": lm.visibility
+            }
+
+        return {
+            "is_detected": is_running,
+            "confidence": float(running_confidence) if is_running else float(running_confidence * 0.5),
+            "class_label": "running" if is_running else "walking/standing",
+            "metrics": {
+                "stride_angle": float(stride_angle),
+                "lean_angle": float(lean_angle),
+                "knee_drive_ratio": float(max_knee_lift),
+                "normalized_speed": float(normalized_speed),
+                "direction_consistency": float(direction_consistency),
+                "net_displacement": float(net_displacement)
+            },
+            "rule_scores": {
+                "stride": float(stride_score),
+                "lean": float(lean_score),
+                "knee_drive": float(knee_drive_score),
+                "speed": float(speed_score)
+            },
+            "pose_landmarks": results.pose_landmarks
+        }
+
+    def _empty_result(self):
+        """
+        Returns a default empty result structure when landmarks cannot be detected.
+        """
+        return {
+            "is_detected": False,
+            "confidence": 0.0,
+            "class_label": "unknown",
+            "metrics": {
+                "stride_angle": 0.0,
+                "lean_angle": 0.0,
+                "knee_drive_ratio": 0.0,
+                "normalized_speed": 0.0
+            },
+            "rule_scores": {
+                "stride": 0.0,
+                "lean": 0.0,
+                "knee_drive": 0.0,
+                "speed": 0.0
+            },
+            "pose_landmarks": None
+        }

suspicious_behavior/engines/violence_engine.py

@@ -0,0 +1,76 @@
+import torch
+import numpy as np
+from transformers import VideoMAEForVideoClassification, VideoMAEImageProcessor
+from suspicious_behavior.config import VIOLENCE_MODEL_NAME, VIOLENCE_PROCESSOR_NAME, VIOLENCE_CONFIDENCE_THRESHOLD
+
+class ViolenceEngine:
+    """
+    VideoMAE-based violence detection engine.
+    Analyzes temporal cues across a 16-frame clip to detect fighting/assault.
+    """
+    def __init__(self):
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        print(f"[ViolenceEngine] Loading VideoMAE model '{VIOLENCE_MODEL_NAME}' on {self.device}...")
+        
+        # Load pre-trained models
+        self.model = VideoMAEForVideoClassification.from_pretrained(VIOLENCE_MODEL_NAME).to(self.device)
+        self.processor = VideoMAEImageProcessor.from_pretrained(VIOLENCE_PROCESSOR_NAME)
+        self.model.eval()
+        
+        # Load labels from model configuration
+        self.labels = self.model.config.id2label
+        print(f"[ViolenceEngine] Model loaded successfully. Labels: {self.labels}")
+
+    def predict(self, frames):
+        """
+        Predict behavior class from a list of 16 frames.
+        
+        Args:
+            frames (list): List of 16 numpy arrays (frames in BGR color space)
+            
+        Returns:
+            dict: Classification results containing detection status, confidence, and score breakdown.
+        """
+        if len(frames) != 16:
+            raise ValueError(f"ViolenceEngine expects exactly 16 frames, got {len(frames)}")
+
+        # Convert BGR (OpenCV default) to RGB and make a contiguous copy to avoid negative strides
+        rgb_frames = []
+        for frame in frames:
+            if isinstance(frame, np.ndarray):
+                rgb_frames.append(frame[:, :, ::-1].copy())
+            else:
+                rgb_frames.append(frame)
+
+        # Preprocess and prepare tensor batch
+        inputs = self.processor(rgb_frames, return_tensors="pt")
+        inputs = {k: v.to(self.device) for k, v in inputs.items()}
+
+        with torch.no_grad():
+            outputs = self.model(**inputs)
+            logits = outputs.logits
+            probs = torch.softmax(logits, dim=-1)[0]
+
+        # Extract raw scores
+        raw_results = {}
+        for idx, prob in enumerate(probs):
+            label = self.labels[idx].lower()
+            raw_results[label] = float(prob.cpu().numpy())
+
+        # Map binary classifications (label_0 = normal, label_1 = violent)
+        results = {
+            "normal": raw_results.get("label_0", raw_results.get("0", 0.0)),
+            "violence": raw_results.get("label_1", raw_results.get("1", 0.0))
+        }
+
+        # Define targets that warrant immediate alerts
+        max_violence_prob = results.get("violence", 0.0)
+        detected_class = "violence"
+        is_detected = max_violence_prob >= VIOLENCE_CONFIDENCE_THRESHOLD
+
+        return {
+            "is_detected": is_detected,
+            "confidence": max_violence_prob if is_detected else results.get("normal", 1.0 - max_violence_prob),
+            "class_label": detected_class if is_detected else "normal",
+            "all_scores": results
+        }

suspicious_behavior/pipeline/__init__.py

@@ -0,0 +1 @@
+# Pipeline submodule

suspicious_behavior/pipeline/annotator.py

@@ -0,0 +1,239 @@
+import cv2
+import numpy as np
+import mediapipe as mp
+
+class Annotator:
+    """
+    Renders professional-grade computer vision annotations on frames.
+    Draws custom skeletons, sleek bounding boxes, and security alert banners.
+    """
+    def __init__(self):
+        self.mp_pose = mp.solutions.pose
+        
+        # Premium color palette (BGR format)
+        self.COLOR_LEFT = (230, 180, 50)       # Sleek teal/cyan
+        self.COLOR_RIGHT = (80, 80, 250)       # Coral/salmon pink
+        self.COLOR_MIDDLE = (50, 220, 240)     # Warm yellow
+        self.COLOR_TEXT = (255, 255, 255)       # White
+        self.COLOR_NORMAL_BOX = (200, 200, 200) # Soft gray
+        self.COLOR_ALERT_FIGHT = (45, 45, 230)  # Crimson red
+        self.COLOR_ALERT_RUN = (0, 140, 255)    # Amber orange
+
+    def draw_skeleton(self, frame, landmarks, bbox):
+        """
+        Draws a customized, color-coded skeleton within the person's bounding box.
+        """
+        if not landmarks:
+            return frame
+
+        h_img, w_img, _ = frame.shape
+        x1, y1, x2, y2 = bbox
+        w_box = x2 - x1
+        h_box = y2 - y1
+
+        # Extract landmarks and project from crop-space to full image coordinates
+        pts = {}
+        for idx, lm in enumerate(landmarks.landmark):
+            # Coordinates are normalized relative to the crop dimensions
+            px = int(x1 + lm.x * w_box)
+            py = int(y1 + lm.y * h_box)
+            # Clip coordinates to image borders
+            px = max(0, min(px, w_img - 1))
+            py = max(0, min(py, h_img - 1))
+            pts[idx] = (px, py, lm.visibility)
+
+        # Define connection segments with color codes
+        connections = [
+            # Torso (Middle)
+            (self.mp_pose.PoseLandmark.LEFT_SHOULDER, self.mp_pose.PoseLandmark.RIGHT_SHOULDER, self.COLOR_MIDDLE),
+            (self.mp_pose.PoseLandmark.LEFT_HIP, self.mp_pose.PoseLandmark.RIGHT_HIP, self.COLOR_MIDDLE),
+            (self.mp_pose.PoseLandmark.LEFT_SHOULDER, self.mp_pose.PoseLandmark.LEFT_HIP, self.COLOR_MIDDLE),
+            (self.mp_pose.PoseLandmark.RIGHT_SHOULDER, self.mp_pose.PoseLandmark.RIGHT_HIP, self.COLOR_MIDDLE),
+            
+            # Left Arm (Teal)
+            (self.mp_pose.PoseLandmark.LEFT_SHOULDER, self.mp_pose.PoseLandmark.LEFT_ELBOW, self.COLOR_LEFT),
+            (self.mp_pose.PoseLandmark.LEFT_ELBOW, self.mp_pose.PoseLandmark.LEFT_WRIST, self.COLOR_LEFT),
+            
+            # Right Arm (Coral)
+            (self.mp_pose.PoseLandmark.RIGHT_SHOULDER, self.mp_pose.PoseLandmark.RIGHT_ELBOW, self.COLOR_RIGHT),
+            (self.mp_pose.PoseLandmark.RIGHT_ELBOW, self.mp_pose.PoseLandmark.RIGHT_WRIST, self.COLOR_RIGHT),
+            
+            # Left Leg (Teal)
+            (self.mp_pose.PoseLandmark.LEFT_HIP, self.mp_pose.PoseLandmark.LEFT_KNEE, self.COLOR_LEFT),
+            (self.mp_pose.PoseLandmark.LEFT_KNEE, self.mp_pose.PoseLandmark.LEFT_ANKLE, self.COLOR_LEFT),
+            
+            # Right Leg (Coral)
+            (self.mp_pose.PoseLandmark.RIGHT_HIP, self.mp_pose.PoseLandmark.RIGHT_KNEE, self.COLOR_RIGHT),
+            (self.mp_pose.PoseLandmark.RIGHT_KNEE, self.mp_pose.PoseLandmark.RIGHT_ANKLE, self.COLOR_RIGHT),
+        ]
+
+        # Draw connection lines
+        for start_enum, end_enum, color in connections:
+            start_pt = pts[start_enum.value]
+            end_pt = pts[end_enum.value]
+            
+            # Only draw if landmarks are visible enough
+            if start_pt[2] > 0.5 and end_pt[2] > 0.5:
+                cv2.line(frame, start_pt[:2], end_pt[:2], color, 2, cv2.LINE_AA)
+
+        # Draw joint keypoints
+        for idx, pt in pts.items():
+            if pt[2] > 0.5:
+                # Exclude face features (0-10) for cleaner physical motion display
+                if idx > 10:
+                    color = self.COLOR_LEFT if idx % 2 == 1 else self.COLOR_RIGHT
+                    cv2.circle(frame, pt[:2], 3, color, -1, cv2.LINE_AA)
+
+        return frame
+
+    def draw_predictions(self, frame, tracked_objects, behaviors):
+        """
+        Draws bounding boxes, labels, and skeletons for all tracked persons.
+        
+        Args:
+            frame (numpy.ndarray): BGR image frame
+            tracked_objects (list): List of tuples (bbox, track_id)
+            behaviors (dict): Mapping {track_id: behavior_dict}
+            
+        Returns:
+            numpy.ndarray: Annotated frame
+        """
+        for bbox, track_id in tracked_objects:
+            x1, y1, x2, y2 = [int(c) for c in bbox]
+            
+            # Fetch behavior information for this ID
+            bh = behaviors.get(track_id, {"class_label": "normal", "confidence": 0.0, "pose_landmarks": None})
+            label = bh["class_label"]
+            conf = bh["confidence"]
+            landmarks = bh["pose_landmarks"]
+            
+            # Determine color based on severity of state
+            if label in ["fighting", "violence", "assault"]:
+                color = self.COLOR_ALERT_FIGHT
+            elif label == "running":
+                color = self.COLOR_ALERT_RUN
+            else:
+                color = self.COLOR_NORMAL_BOX
+
+            # Draw sleek bounding box
+            cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2, cv2.LINE_AA)
+
+            # Draw skeleton overlay
+            if landmarks is not None:
+                self.draw_skeleton(frame, landmarks, (x1, y1, x2, y2))
+
+            # Draw label plaque above bounding box
+            label_text = f"ID {track_id}: {label.upper()} ({conf*100:.0f}%)"
+            (text_w, text_h), baseline = cv2.getTextSize(label_text, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1)
+            
+            # Draw plaque background
+            cv2.rectangle(
+                frame, 
+                (x1, y1 - text_h - 10), 
+                (x1 + text_w + 10, y1), 
+                color, 
+                -1
+            )
+            # Write text on plaque
+            cv2.putText(
+                frame, 
+                label_text, 
+                (x1 + 5, y1 - 5), 
+                cv2.FONT_HERSHEY_SIMPLEX, 
+                0.5, 
+                self.COLOR_TEXT, 
+                1, 
+                cv2.LINE_AA
+            )
+
+        return frame
+
+    def draw_alert_banners(self, frame, active_alerts):
+        """
+        Renders eye-catching alert banners at the top of the screen for active threats.
+        
+        Args:
+            frame (numpy.ndarray): Frame to annotate
+            active_alerts (list): List of strings indicating active behaviors (e.g. ["FIGHTING", "RUNNING"])
+            
+        Returns:
+            numpy.ndarray: Frame with alert banners
+        """
+        if not active_alerts:
+            return frame
+
+        h_img, w_img, _ = frame.shape
+        banner_h = int(h_img * 0.08)  # Banner takes 8% of vertical space
+        
+        # Sort so CRITICAL alerts are processed first
+        sorted_alerts = sorted(active_alerts, key=lambda a: 0 if a in ["FIGHTING", "VIOLENCE", "ASSAULT"] else 1)
+        primary_alert = sorted_alerts[0]
+        
+        # Set banner color and text
+        if primary_alert in ["FIGHTING", "VIOLENCE", "ASSAULT"]:
+            color = self.COLOR_ALERT_FIGHT
+            banner_text = f"ALERT: ACTIVE {primary_alert.upper()} DETECTED"
+        else:
+            color = self.COLOR_ALERT_RUN
+            banner_text = f"ALERT: SUSPICIOUS {primary_alert.upper()} MOTION"
+
+        # Create semi-transparent overlay banner
+        overlay = frame.copy()
+        cv2.rectangle(overlay, (0, 0), (w_img, banner_h), color, -1)
+        # Apply overlay with alpha blend (opacity 85%)
+        cv2.addWeighted(overlay, 0.85, frame, 0.15, 0, frame)
+
+        # Draw a highlighted bottom stripe on the banner
+        cv2.line(frame, (0, banner_h), (w_img, banner_h), (255, 255, 255), 2, cv2.LINE_AA)
+
+        # Render alert text centered
+        font_scale = max(0.6, banner_h / 60.0)
+        thickness = max(2, int(banner_h / 25))
+        (text_w, text_h), _ = cv2.getTextSize(banner_text, cv2.FONT_HERSHEY_SIMPLEX, font_scale, thickness)
+        
+        text_x = int((w_img - text_w) / 2)
+        text_y = int((banner_h + text_h) / 2)
+        
+        cv2.putText(
+            frame, 
+            banner_text, 
+            (text_x, text_y), 
+            cv2.FONT_HERSHEY_SIMPLEX, 
+            font_scale, 
+            self.COLOR_TEXT, 
+            thickness, 
+            cv2.LINE_AA
+        )
+
+        return frame
+
+    def draw_timestamp_overlay(self, frame, timestamp_str):
+        """
+        Draws system details and timestamp in the bottom-right corner.
+        """
+        h_img, w_img, _ = frame.shape
+        info_text = f"SimShieldAI Secure | {timestamp_str}"
+        
+        (text_w, text_h), _ = cv2.getTextSize(info_text, cv2.FONT_HERSHEY_SIMPLEX, 0.45, 1)
+        
+        # Semi-transparent backing rectangle for timestamp
+        cv2.rectangle(
+            frame, 
+            (w_img - text_w - 20, h_img - text_h - 20), 
+            (w_img - 5, h_img - 5), 
+            (0, 0, 0), 
+            -1
+        )
+        
+        cv2.putText(
+            frame, 
+            info_text, 
+            (w_img - text_w - 12, h_img - 10), 
+            cv2.FONT_HERSHEY_SIMPLEX, 
+            0.45, 
+            (180, 180, 180), 
+            1, 
+            cv2.LINE_AA
+        )
+        
+        return frame

suspicious_behavior/pipeline/frame_analyzer.py

@@ -0,0 +1,302 @@
+import cv2
+import numpy as np
+import time
+import base64
+from datetime import datetime
+from ultralytics import YOLO
+
+from suspicious_behavior.config import (
+    YOLO_MODEL_PATH, VIOLENCE_FRAME_COUNT, MIN_PERSON_CROP_SIZE,
+    VIOLENCE_DECAY_SECONDS, VIOLENCE_EMA_ALPHA,
+    VIOLENCE_ESCALATION_SECONDS, VIOLENCE_ESCALATION_THRESHOLD
+)
+from suspicious_behavior.engines.violence_engine import ViolenceEngine
+from suspicious_behavior.engines.running_engine import RunningEngine
+from suspicious_behavior.tracking.sort_tracker import SortTracker
+from suspicious_behavior.pipeline.annotator import Annotator
+from suspicious_behavior.alerts.alert_manager import AlertManager
+
+class FrameAnalyzer:
+    """
+    Main pipeline orchestrator.
+    Combines person detection, tracking, running pose analysis, and video clip violence classification.
+    """
+    def __init__(self, camera_id="camera_1", violence_stride=8):
+        self.camera_id = camera_id
+        self.violence_stride = violence_stride
+        self.frame_idx = 0
+        
+        # Initialize sub-modules
+        print(f"[FrameAnalyzer] Initializing person detection model: {YOLO_MODEL_PATH}...")
+        self.yolo = YOLO(YOLO_MODEL_PATH)
+        
+        self.tracker = SortTracker()
+        self.running_engine = RunningEngine()
+        self.violence_engine = ViolenceEngine()
+        self.annotator = Annotator()
+        self.alert_manager = AlertManager()
+        
+        # Sliding buffer for violence detection (stores RGB frames)
+        self.violence_buffer = []
+        # Stores the actual coordinates, labels, and landmarks of tracked people
+        # Format: {track_id: behavior_result_dict}
+        self.current_behaviors = {}
+        
+        # --- Violence State Smoothing ---
+        self._violence_active = False
+        self._violence_confidence = 0.0
+        self._violence_last_detected_time = 0.0  # Timestamp of last positive violence detection
+        self._violence_ema_score = 0.0            # Exponentially smoothed violence confidence
+        
+        # --- Violence Escalation ---
+        self._violence_sustained_start = None     # Timestamp when sustained violence began
+        self._violence_escalation_fired = False   # Whether escalation alert was already sent
+
+    def analyze(self, frame, fps=10.0, output_base64=False):
+        """
+        Processes a single video frame.
+        
+        Args:
+            frame (numpy.ndarray): OpenCV BGR image frame
+            fps (float): Target processing FPS
+            output_base64 (bool): If true, returns the annotated frame as a base64 string
+            
+        Returns:
+            tuple: (annotated_frame, list_of_triggered_alerts, metadata)
+        """
+        self.frame_idx += 1
+        current_time = self.frame_idx / fps
+        h_img, w_img, _ = frame.shape
+        start_time = time.time()
+        
+        # 1. Person Detection (YOLO)
+        # Class 0 is person in COCO dataset
+        yolo_results = self.yolo(frame, classes=[0], conf=0.4, verbose=False)
+        detections = []
+        for res in yolo_results:
+            for box in res.boxes:
+                xyxy = box.xyxy[0].cpu().numpy()
+                conf = float(box.conf[0].cpu().numpy())
+                detections.append([xyxy[0], xyxy[1], xyxy[2], xyxy[3], conf])
+
+        detections = np.array(detections) if len(detections) > 0 else np.empty((0, 5))
+
+        # 2. Track Association (SORT)
+        tracked_objects = self.tracker.update(detections)
+        active_track_ids = [tid for _, tid in tracked_objects]
+        
+        # Clean up running engine history for dead tracks
+        self.running_engine.clean_history(active_track_ids)
+
+        # 3. Analyze running/sprinting behavior for each person
+        new_behaviors = {}
+        active_alarms = set()
+        triggered_alerts = []
+        
+        for bbox, track_id in tracked_objects:
+            x1, y1, x2, y2 = [int(c) for c in bbox]
+            
+            # Clip bounds to frame borders
+            x1 = max(0, min(x1, w_img - 1))
+            y1 = max(0, min(y1, h_img - 1))
+            x2 = max(0, min(x2, w_img - 1))
+            y2 = max(0, min(y2, h_img - 1))
+            
+            # Extract person crop
+            person_crop = frame[y1:y2, x1:x2]
+            crop_h, crop_w = person_crop.shape[:2]
+            
+            # Improvement 3: Skip pose analysis on tiny distant people
+            # Small crops produce unreliable skeleton estimates that cause false positives
+            if crop_w < MIN_PERSON_CROP_SIZE or crop_h < MIN_PERSON_CROP_SIZE:
+                pose_result = self.running_engine._empty_result()
+            else:
+                # Analyze kinematics using MediaPipe Pose
+                pose_result = self.running_engine.analyze_pose(
+                    person_crop, track_id, self.frame_idx, fps
+                )
+            
+            # Store results
+            new_behaviors[track_id] = pose_result
+            
+            # Handle running alarms
+            if pose_result["is_detected"]:
+                active_alarms.add("RUNNING")
+                
+                # Check for alert trigger
+                alert = self.alert_manager.trigger_alert(
+                    threat_type="running",
+                    confidence=pose_result["confidence"],
+                    camera_id=self.camera_id,
+                    track_id=track_id,
+                    bbox=bbox,
+                    metadata=pose_result["metrics"],
+                    current_time=current_time
+                )
+                if alert:
+                    triggered_alerts.append(alert)
+
+        # 4. Violence Detection (VideoMAE over sliding frame clip)
+        # Store a resized version of the frame to keep memory usage low
+        resized_frame = cv2.resize(frame, (224, 224))
+        self.violence_buffer.append(resized_frame)
+        if len(self.violence_buffer) > VIOLENCE_FRAME_COUNT:
+            self.violence_buffer.pop(0)
+
+        violence_confidence = 0.0
+        violence_label = "normal"
+        is_violence_detected = False
+        raw_violence_score = 0.0
+
+        # Only run VideoMAE classification once buffer is full and matches stride
+        if len(self.violence_buffer) == VIOLENCE_FRAME_COUNT and len(tracked_objects) > 0:
+            if self.frame_idx % self.violence_stride == 0:
+                violence_res = self.violence_engine.predict(self.violence_buffer)
+                raw_violence_score = violence_res["confidence"] if violence_res["is_detected"] else 0.0
+                
+                # Improvement 2: Exponential Moving Average smoothing
+                # Prevents confidence from jumping wildly between inference windows
+                self._violence_ema_score = (
+                    VIOLENCE_EMA_ALPHA * raw_violence_score +
+                    (1 - VIOLENCE_EMA_ALPHA) * self._violence_ema_score
+                )
+                
+                if violence_res["is_detected"]:
+                    # Violence detected — update state and record timestamp
+                    self._violence_active = True
+                    self._violence_confidence = self._violence_ema_score
+                    self._violence_last_detected_time = current_time
+                    
+                    # Trigger alert
+                    alert = self.alert_manager.trigger_alert(
+                        threat_type="violence",
+                        confidence=self._violence_ema_score,
+                        camera_id=self.camera_id,
+                        metadata=violence_res["all_scores"],
+                        current_time=current_time
+                    )
+                    if alert:
+                        triggered_alerts.append(alert)
+                    
+                    # Improvement 5: Violence Escalation tracking
+                    if self._violence_ema_score >= VIOLENCE_ESCALATION_THRESHOLD:
+                        if self._violence_sustained_start is None:
+                            self._violence_sustained_start = current_time
+                        elif (current_time - self._violence_sustained_start >= VIOLENCE_ESCALATION_SECONDS
+                              and not self._violence_escalation_fired):
+                            # Sustained high-confidence violence — fire escalation alert
+                            esc_alert = self.alert_manager.trigger_alert(
+                                threat_type="violence_escalated",
+                                confidence=self._violence_ema_score,
+                                camera_id=self.camera_id,
+                                metadata={"sustained_seconds": current_time - self._violence_sustained_start},
+                                current_time=current_time
+                            )
+                            if esc_alert:
+                                triggered_alerts.append(esc_alert)
+                            self._violence_escalation_fired = True
+                    else:
+                        # Below escalation threshold — reset sustained timer
+                        self._violence_sustained_start = None
+                else:
+                    # Improvement 1: Decay timer instead of instant off
+                    # Violence lingers for VIOLENCE_DECAY_SECONDS after last positive detection
+                    self._violence_ema_score *= 0.7  # Gentle decay of EMA score
+                    if self._violence_sustained_start is not None:
+                        self._violence_sustained_start = None
+                        self._violence_escalation_fired = False
+
+        # Improvement 1: Apply decay timer — violence stays active for N seconds
+        # after the last positive detection even if current inference says "normal"
+        if self._violence_active:
+            elapsed_since_detection = current_time - self._violence_last_detected_time
+            if elapsed_since_detection < VIOLENCE_DECAY_SECONDS:
+                # Still within decay window — keep violence active
+                is_violence_detected = True
+                violence_confidence = self._violence_confidence
+                violence_label = "violence"
+                active_alarms.add("VIOLENCE")
+            else:
+                # Decay window expired — clear violence state
+                self._violence_active = False
+                self._violence_confidence = 0.0
+                self._violence_ema_score = 0.0
+                self._violence_sustained_start = None
+                self._violence_escalation_fired = False
+        
+        # 5. Violence-Suppresses-Running Logic
+        # When violence IS detected, fighting body movements must NOT be labeled as running.
+        # Override any running behavior to "fighting" and remove false running alerts.
+        if is_violence_detected:
+            # Remove false "RUNNING" alarm — violence takes priority
+            active_alarms.discard("RUNNING")
+            
+            # Override all tracked person behaviors from "running" to "fighting"
+            for track_id in new_behaviors:
+                bh = new_behaviors[track_id]
+                if bh["is_detected"] and bh["class_label"] == "running":
+                    bh["class_label"] = "fighting"
+                    bh["confidence"] = violence_confidence
+                    bh["is_detected"] = True
+            
+            # Remove any false running alerts from this frame
+            triggered_alerts = [a for a in triggered_alerts if a.threat_type != "running"]
+
+        # 6. Render Visual overlays
+        annotated_frame = frame.copy()
+        
+        # Draw skeletons and labels for tracked people
+        annotated_frame = self.annotator.draw_predictions(
+            annotated_frame, tracked_objects, new_behaviors
+        )
+        
+        # Draw active alert banner if any threat is active
+        if active_alarms:
+            annotated_frame = self.annotator.draw_alert_banners(
+                annotated_frame, list(active_alarms)
+            )
+            
+        # Draw timestamp and brand logo
+        timestamp_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        annotated_frame = self.annotator.draw_timestamp_overlay(
+            annotated_frame, timestamp_str
+        )
+        
+        # 7. Build response metadata
+        latency_ms = (time.time() - start_time) * 1000.0
+        
+        # Serialize annotated frame to base64 if requested (useful for APIs)
+        frame_base64 = None
+        if output_base64:
+            _, buffer = cv2.imencode('.jpg', annotated_frame)
+            frame_base64 = base64.b64encode(buffer).decode('utf-8')
+            
+            # Attach the base64 image to alerts generated in this frame
+            for alert in triggered_alerts:
+                alert.frame_image = frame_base64
+
+        metadata = {
+            "frame_idx": self.frame_idx,
+            "latency_ms": latency_ms,
+            "active_tracks_count": len(tracked_objects),
+            "threats_detected": list(active_alarms),
+            "violence_metrics": {
+                "detected": is_violence_detected,
+                "label": violence_label,
+                "confidence": violence_confidence
+            },
+            "tracks": [
+                {
+                    "track_id": tid,
+                    "bbox": [float(c) for c in bbox],
+                    "behavior": new_behaviors[tid]["class_label"],
+                    "behavior_confidence": new_behaviors[tid]["confidence"]
+                }
+                for bbox, tid in tracked_objects
+            ]
+        }
+
+        # Keep current behaviors state updated
+        self.current_behaviors = new_behaviors
+
+        return annotated_frame, triggered_alerts, metadata

suspicious_behavior/pipeline/video_processor.py

@@ -0,0 +1,88 @@
+import cv2
+import os
+import time
+
+class VideoProcessor:
+    """
+    Handles video ingestion, frame extraction, smart sampling, 
+    and compilation of processed frames back to video files.
+    """
+    def __init__(self, target_fps=10.0):
+        self.target_fps = target_fps
+
+    def get_metadata(self, video_path):
+        """
+        Retrieves video metadata from the file.
+        """
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise FileNotFoundError(f"Could not open video file at {video_path}")
+            
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        cap.release()
+        
+        return {
+            "fps": fps,
+            "frame_count": frame_count,
+            "width": width,
+            "height": height,
+            "duration": frame_count / (fps + 1e-6)
+        }
+
+    def extract_frames_generator(self, video_path):
+        """
+        A generator that yields frames at target FPS.
+        Yields: (frame_idx, frame, timestamp)
+        """
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise FileNotFoundError(f"Could not open video file at {video_path}")
+            
+        source_fps = cap.get(cv2.CAP_PROP_FPS)
+        if source_fps <= 0:
+            source_fps = 30.0  # Fallback
+            
+        # Calculate frame step based on target FPS
+        frame_step = max(1, int(round(source_fps / self.target_fps)))
+        
+        frame_idx = 0
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+                
+            # Yield frame if it matches the sampling step
+            if frame_idx % frame_step == 0:
+                timestamp = frame_idx / source_fps
+                yield frame_idx, frame, timestamp
+                
+            frame_idx += 1
+            
+        cap.release()
+
+    def write_frames_to_video(self, frames, output_path, fps=10.0, frame_size=None):
+        """
+        Compiles a list or generator of frames into an output video file (MP4 format).
+        """
+        if len(frames) == 0:
+            return
+            
+        if frame_size is None:
+            height, width, _ = frames[0].shape
+            frame_size = (width, height)
+            
+        # Use mp4v codec for broad compatibility
+        fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+        out = cv2.VideoWriter(output_path, fourcc, fps, frame_size)
+        
+        for frame in frames:
+            # Ensure frame matches the target dimensions
+            if (frame.shape[1], frame.shape[0]) != frame_size:
+                frame = cv2.resize(frame, frame_size)
+            out.write(frame)
+            
+        out.release()
+        print(f"[VideoProcessor] Video saved successfully to {output_path} ({len(frames)} frames)")

suspicious_behavior/tracking/__init__.py

@@ -0,0 +1 @@
+# Tracking submodule

suspicious_behavior/tracking/sort_tracker.py

@@ -0,0 +1,158 @@
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+from suspicious_behavior.tracking.track import Track
+from suspicious_behavior.config import TRACKER_MAX_AGE, TRACKER_MIN_HITS, TRACKER_IOU_THRESHOLD
+
+def iou_batch(bboxes1, bboxes2):
+    """
+    Computes Intersection over Union (IoU) between two sets of bounding boxes.
+    
+    Args:
+        bboxes1 (numpy.ndarray): N x 4 bounding boxes
+        bboxes2 (numpy.ndarray): M x 4 bounding boxes
+        
+    Returns:
+        numpy.ndarray: N x M IoU matrix
+    """
+    if len(bboxes1) == 0 or len(bboxes2) == 0:
+        return np.empty((len(bboxes1), len(bboxes2)))
+
+    # Expand dimensions for vectorization
+    bboxes2 = np.expand_dims(bboxes2, 0)
+    bboxes1 = np.expand_dims(bboxes1, 1)
+    
+    # Calculate intersections
+    xx1 = np.maximum(bboxes1[..., 0], bboxes2[..., 0])
+    yy1 = np.maximum(bboxes1[..., 1], bboxes2[..., 1])
+    xx2 = np.minimum(bboxes1[..., 2], bboxes2[..., 2])
+    yy2 = np.minimum(bboxes1[..., 3], bboxes2[..., 3])
+    
+    w = np.maximum(0.0, xx2 - xx1)
+    h = np.maximum(0.0, yy2 - yy1)
+    intersection = w * h
+    
+    # Calculate union
+    area1 = (bboxes1[..., 2] - bboxes1[..., 0]) * (bboxes1[..., 3] - bboxes1[..., 1])
+    area2 = (bboxes2[..., 2] - bboxes2[..., 0]) * (bboxes2[..., 3] - bboxes2[..., 1])
+    union = area1 + area2 - intersection
+    
+    return intersection / (union + 1e-6)
+
+
+class SortTracker:
+    """
+    Simple Online and Realtime Tracking (SORT) orchestrator.
+    Associates object detections to persistent object tracks.
+    """
+    def __init__(self, max_age=TRACKER_MAX_AGE, min_hits=TRACKER_MIN_HITS, iou_threshold=TRACKER_IOU_THRESHOLD):
+        self.max_age = max_age
+        self.min_hits = min_hits
+        self.iou_threshold = iou_threshold
+        self.tracks = []
+        self.frame_count = 0
+
+    def update(self, detections):
+        """
+        Updates the tracker with new detections.
+        
+        Args:
+            detections (numpy.ndarray): N x 5 array containing bounding boxes and confidences [x1, y1, x2, y2, score]
+            
+        Returns:
+            list: List of active tracks containing: [x1, y1, x2, y2, track_id]
+        """
+        self.frame_count += 1
+        
+        # Get predictions from existing tracks
+        predicted_bboxes = []
+        to_delete = []
+        
+        for idx, track in enumerate(self.tracks):
+            pos = track.predict()[0]
+            # Handle invalid bounding boxes from prediction
+            if np.any(np.isnan(pos)):
+                to_delete.append(idx)
+            else:
+                predicted_bboxes.append(pos)
+                
+        # Remove corrupted predictions
+        for idx in sorted(to_delete, reverse=True):
+            self.tracks.pop(idx)
+            
+        predicted_bboxes = np.array(predicted_bboxes)
+        
+        # Match predicted tracks to current detections
+        matched, unmatched_detections, unmatched_tracks = self._associate_detections_to_tracks(
+            detections, predicted_bboxes
+        )
+        
+        # Update matched tracks
+        for track_idx, detection_idx in matched:
+            self.tracks[track_idx].update(detections[detection_idx][:4])
+            
+        # Create new tracks for unmatched detections
+        for detection_idx in unmatched_detections:
+            new_track = Track(detections[detection_idx][:4])
+            self.tracks.append(new_track)
+            
+        # Filter out dead tracks
+        active_tracks = []
+        to_remove = []
+        
+        for idx, track in enumerate(self.tracks):
+            # Keep tracks that were updated recently
+            if track.time_since_update > self.max_age:
+                to_remove.append(idx)
+            else:
+                # Confirmed if it has enough hits and is active
+                if track.hits >= self.min_hits or self.frame_count <= self.min_hits:
+                    bbox = track.get_state()
+                    active_tracks.append((bbox, track.id))
+                    
+        # Remove dead tracks in reverse order to keep indices correct
+        for idx in sorted(to_remove, reverse=True):
+            self.tracks.pop(idx)
+            
+        return active_tracks
+
+    def _associate_detections_to_tracks(self, detections, predicted_tracks):
+        """
+        Associates detections to predicted tracks using the Hungarian algorithm.
+        """
+        if len(predicted_tracks) == 0:
+            return np.empty((0, 2), dtype=int), np.arange(len(detections)), np.empty((0,), dtype=int)
+            
+        if len(detections) == 0:
+            return np.empty((0, 2), dtype=int), np.empty((0,), dtype=int), np.arange(len(predicted_tracks))
+            
+        # Compute cost matrix (1 - IoU)
+        iou_matrix = iou_batch(detections[:, :4], predicted_tracks)
+        
+        # SciPy Hungarian Algorithm solver
+        row_ind, col_ind = linear_sum_assignment(-iou_matrix)
+        
+        matched = []
+        unmatched_detections = []
+        unmatched_tracks = []
+        
+        # Filter matches based on IoU threshold
+        matched_detections_set = set()
+        matched_tracks_set = set()
+        
+        for d, t in zip(row_ind, col_ind):
+            if iou_matrix[d, t] >= self.iou_threshold:
+                matched.append((t, d))
+                matched_detections_set.add(d)
+                matched_tracks_set.add(t)
+                
+        # Find unmatched detections
+        for d in range(len(detections)):
+            if d not in matched_detections_set:
+                unmatched_detections.append(d)
+                
+        # Find unmatched tracks
+        for t in range(len(predicted_tracks)):
+            if t not in matched_tracks_set:
+                unmatched_tracks.append(t)
+                
+        return np.array(matched), np.array(unmatched_detections), np.array(unmatched_tracks)

suspicious_behavior/tracking/track.py

@@ -0,0 +1,131 @@
+import numpy as np
+from filterpy.kalman import KalmanFilter
+
+class Track:
+    """
+    Represents an individual tracked object (person) with a Kalman Filter.
+    Adapts the classical SORT tracking state vector.
+    """
+    count = 0
+
+    def __init__(self, bbox):
+        """
+        Initializes a track using an initial bounding box.
+        
+        Args:
+            bbox (list/numpy.ndarray): Bounding box [x1, y1, x2, y2]
+        """
+        # State vector: [u, v, s, r, u_dot, v_dot, s_dot]^T
+        # u, v: center coordinates of the bounding box
+        # s: scale (area)
+        # r: aspect ratio (width / height)
+        # u_dot, v_dot, s_dot: corresponding velocities
+        self.kf = KalmanFilter(dim_x=7, dim_z=4)
+        
+        # State Transition Matrix F
+        self.kf.F = np.array([
+            [1, 0, 0, 0, 1, 0, 0],
+            [0, 1, 0, 0, 0, 1, 0],
+            [0, 0, 1, 0, 0, 0, 1],
+            [0, 0, 0, 1, 0, 0, 0],
+            [0, 0, 0, 0, 1, 0, 0],
+            [0, 0, 0, 0, 0, 1, 0],
+            [0, 0, 0, 0, 0, 0, 1]
+        ])
+        
+        # Measurement Matrix H
+        self.kf.H = np.array([
+            [1, 0, 0, 0, 0, 0, 0],
+            [0, 1, 0, 0, 0, 0, 0],
+            [0, 0, 1, 0, 0, 0, 0],
+            [0, 0, 0, 1, 0, 0, 0]
+        ])
+        
+        # Covariance matrices
+        self.kf.R[2:, 2:] *= 10.0
+        self.kf.P[4:, 4:] *= 1000.0  # High uncertainty to unobserved initial velocities
+        self.kf.P *= 10.0
+        self.kf.Q[-1, -1] *= 0.01
+        self.kf.Q[4:, 4:] *= 0.01
+        
+        # Initialize state with measured bounding box
+        self.kf.x[:4] = self.bbox_to_z(bbox)
+        
+        self.id = Track.count
+        Track.count += 1
+        
+        self.time_since_update = 0
+        self.history = []
+        self.hits = 0
+        self.hit_streak = 0
+        self.age = 0
+
+    def predict(self):
+        """
+        Advances the state estimate using the Kalman filter prediction step.
+        """
+        if (self.kf.x[6] + self.kf.x[2]) <= 0:
+            self.kf.x[6] *= 0.0
+        self.kf.predict()
+        self.age += 1
+        
+        if self.time_since_update > 0:
+            self.hit_streak = 0
+        self.time_since_update += 1
+        
+        predicted_bbox = self.z_to_bbox(self.kf.x)
+        self.history.append(predicted_bbox)
+        return self.history[-1]
+
+    def update(self, bbox):
+        """
+        Updates the track state with an observed bounding box measurement.
+        
+        Args:
+            bbox (list/numpy.ndarray): Observed bounding box [x1, y1, x2, y2]
+        """
+        self.time_since_update = 0
+        self.history = []
+        self.hits += 1
+        self.hit_streak += 1
+        self.kf.update(self.bbox_to_z(bbox))
+
+    def get_state(self):
+        """
+        Returns the current bounding box estimate.
+        
+        Returns:
+            numpy.ndarray: [x1, y1, x2, y2]
+        """
+        return self.z_to_bbox(self.kf.x)[0]
+
+    @staticmethod
+    def bbox_to_z(bbox):
+        """
+        Converts [x1, y1, x2, y2] bounding box to [u, v, s, r] measurement.
+        """
+        w = bbox[2] - bbox[0]
+        h = bbox[3] - bbox[1]
+        x = bbox[0] + w / 2.0
+        y = bbox[1] + h / 2.0
+        s = w * h
+        r = w / (float(h) + 1e-6)
+        return np.array([x, y, s, r]).reshape((4, 1))
+
+    @staticmethod
+    def z_to_bbox(x, score=None):
+        """
+        Converts [u, v, s, r] state estimate back to [x1, y1, x2, y2] bounding box.
+        """
+        w = np.sqrt(x[2] * x[3])
+        h = x[2] / (w + 1e-6)
+        
+        x1 = x[0] - w / 2.0
+        y1 = x[1] - h / 2.0
+        x2 = x[0] + w / 2.0
+        y2 = x[1] + h / 2.0
+        
+        if score is None:
+            return np.array([x1, y1, x2, y2]).reshape((1, 4))
+        else:
+            return np.array([x1, y1, x2, y2, score]).reshape((1, 5))

testMOdel.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+
+
+def main():
+    try:
+        from ultralytics import YOLO
+    except ImportError as exc:
+        raise SystemExit(
+            "Ultralytics is not installed in this environment.\n"
+            "Run: pip install ultralytics opencv-python pillow"
+        ) from exc
+
+    root = Path(__file__).resolve().parent
+    model_path = root / "model" / "best.pt"
+    samples_dir = root / "samples"
+    output_dir = root / "outputs"
+    output_dir.mkdir(exist_ok=True)
+
+    if not model_path.exists():
+        raise SystemExit(f"Model file not found: {model_path}")
+
+    image_paths = sorted(
+        list(samples_dir.glob("*.jpg"))
+        + list(samples_dir.glob("*.jpeg"))
+        + list(samples_dir.glob("*.png"))
+    )
+    if not image_paths:
+        raise SystemExit(f"No test images found in: {samples_dir}")
+
+    model = YOLO(str(model_path))
+    print(f"Loaded model: {model_path}")
+    print(f"Model classes: {model.names}")
+    print()
+
+    for image_path in image_paths:
+        print("=" * 80)
+        print(f"Testing: {image_path.name}")
+
+        results = model.predict(
+            source=str(image_path),
+            imgsz=960,
+            conf=0.25,
+            save=False,
+            verbose=False,
+        )
+
+        result = results[0]
+        detections = []
+        for box in result.boxes:
+            cls_id = int(box.cls[0])
+            conf = float(box.conf[0])
+            label = model.names.get(cls_id, str(cls_id))
+            detections.append((label, conf))
+
+        if detections:
+            for label, conf in detections:
+                print(f"- {label}: {conf:.3f}")
+        else:
+            print("- No detections above confidence threshold")
+
+        annotated = result.plot()
+        output_path = output_dir / f"{image_path.stem}_detected.jpg"
+
+        try:
+            import cv2
+        except ImportError as exc:
+            raise SystemExit(
+                "OpenCV is not installed in this environment.\n"
+                "Run: pip install opencv-python"
+            ) from exc
+
+        cv2.imwrite(str(output_path), annotated)
+        print(f"Saved: {output_path}")
+
+
+if __name__ == "__main__":
+    main()

tests/analyze_sample.py

@@ -0,0 +1,166 @@
+"""
+Analyze 'sample video.mp4' through the SimShieldAI suspicious behavior pipeline.
+Prints detailed per-frame diagnostics for violence and running detection.
+"""
+import os
+import sys
+import time
+import cv2
+import numpy as np
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from suspicious_behavior.pipeline.frame_analyzer import FrameAnalyzer
+from suspicious_behavior.pipeline.video_processor import VideoProcessor
+
+
+def main():
+    video_path = r"C:\Users\Admin\Downloads\sample video.mp4"
+    
+    print("=" * 70)
+    print("SimShieldAI — Suspicious Behavior Detection Analysis")
+    print(f"Video: {video_path}")
+    print("=" * 70)
+    
+    # Get video metadata
+    processor = VideoProcessor(target_fps=10.0)
+    metadata = processor.get_metadata(video_path)
+    print(f"Resolution: {metadata['width']}x{metadata['height']}")
+    print(f"Duration: {metadata['duration']:.1f}s | Frames: {metadata['frame_count']} @ {metadata['fps']:.1f} FPS")
+    print(f"Processing at 10 FPS (every {int(metadata['fps']/10)} frames)")
+    print("=" * 70)
+    
+    # Initialize analyzer
+    print("\n[Init] Loading models (YOLOv8n + VideoMAE + MediaPipe)...")
+    analyzer = FrameAnalyzer(camera_id="test_cam", violence_stride=4)
+    
+    # Reset state
+    analyzer.frame_idx = 0
+    analyzer.violence_buffer.clear()
+    analyzer.alert_manager.reset_cooldowns()
+    
+    # Process video
+    frames_processed = 0
+    violence_scores = []
+    running_detections = []
+    all_alerts = []
+    output_frames = []
+    
+    start_time = time.time()
+    
+    print("\n--- Per-Frame Analysis ---\n")
+    
+    for f_idx, frame, timestamp in processor.extract_frames_generator(video_path):
+        annotated, frame_alerts, frame_meta = analyzer.analyze(frame, fps=10.0, output_base64=False)
+        frames_processed += 1
+        output_frames.append(annotated)
+        
+        # Collect metrics
+        v_meta = frame_meta["violence_metrics"]
+        if v_meta["confidence"] > 0:
+            violence_scores.append({
+                "frame": f_idx,
+                "time": timestamp,
+                "label": v_meta["label"],
+                "conf": v_meta["confidence"]
+            })
+        
+        for track in frame_meta["tracks"]:
+            running_detections.append({
+                "frame": f_idx,
+                "time": timestamp,
+                "track_id": track["track_id"],
+                "behavior": track["behavior"],
+                "conf": track["behavior_confidence"]
+            })
+        
+        for alert in frame_alerts:
+            all_alerts.append({"time": timestamp, "alert": alert})
+        
+        # Print frame details
+        tracks_info = ", ".join([
+            f"ID{t['track_id']}:{t['behavior']}({t['behavior_confidence']*100:.0f}%)" 
+            for t in frame_meta["tracks"]
+        ]) or "no people"
+        
+        violence_info = ""
+        if v_meta['confidence'] > 0:
+            emoji = "🔴" if v_meta['detected'] else "🟢"
+            violence_info = f" | {emoji} Violence: {v_meta['label']}({v_meta['confidence']*100:.1f}%)"
+        
+        alert_info = ""
+        if frame_meta['threats_detected']:
+            alert_info = f" | ⚠️ THREATS: {frame_meta['threats_detected']}"
+        
+        print(f"  [{f_idx:04d}] {timestamp:5.1f}s | {frame_meta['active_tracks_count']} people | "
+              f"[{tracks_info}]{violence_info}{alert_info}")
+    
+    elapsed = time.time() - start_time
+    
+    # Save annotated output
+    os.makedirs("outputs", exist_ok=True)
+    output_path = os.path.join("outputs", "sample_video_annotated.mp4")
+    processor.write_frames_to_video(
+        output_frames, output_path, fps=10.0,
+        frame_size=(metadata['width'], metadata['height'])
+    )
+    
+    # Print summary
+    print("\n" + "=" * 70)
+    print("ANALYSIS SUMMARY")
+    print("=" * 70)
+    print(f"Frames processed: {frames_processed}")
+    print(f"Processing time: {elapsed:.1f}s ({frames_processed/elapsed:.1f} FPS)")
+    
+    print(f"\n--- Violence Detection (VideoMAE) ---")
+    if violence_scores:
+        confs = [s["conf"] for s in violence_scores]
+        violence_detected = [s for s in violence_scores if s["label"] != "normal"]
+        normal_scores = [s for s in violence_scores if s["label"] == "normal"]
+        
+        print(f"Total inference runs: {len(violence_scores)}")
+        if violence_detected:
+            print(f"🔴 VIOLENCE DETECTED in {len(violence_detected)} frames:")
+            for v in violence_detected:
+                print(f"   Frame {v['frame']:04d} ({v['time']:.1f}s): {v['label']} at {v['conf']*100:.1f}%")
+        else:
+            print(f"🟢 No violence detected. All {len(normal_scores)} checks returned 'normal'")
+            if normal_scores:
+                normal_confs = [s["conf"] for s in normal_scores]
+                print(f"   Normal confidence: min={min(normal_confs)*100:.1f}%, max={max(normal_confs)*100:.1f}%, avg={np.mean(normal_confs)*100:.1f}%")
+    else:
+        print("⚠️ VideoMAE never ran (need 16 frames + people in scene)")
+    
+    print(f"\n--- Running Detection (MediaPipe) ---")
+    if running_detections:
+        running_found = [r for r in running_detections if r["behavior"] == "running"]
+        walking = [r for r in running_detections if r["behavior"] == "walking/standing"]
+        unknown = [r for r in running_detections if r["behavior"] == "unknown"]
+        
+        print(f"Total person-frame analyses: {len(running_detections)}")
+        if running_found:
+            print(f"🟠 RUNNING DETECTED in {len(running_found)} person-frames:")
+            for r in running_found[:10]:
+                print(f"   Frame {r['frame']:04d} ({r['time']:.1f}s): ID{r['track_id']} running at {r['conf']*100:.1f}%")
+        else:
+            print(f"🟢 No running detected. {len(walking)} walking/standing, {len(unknown)} unknown")
+    else:
+        print("⚠️ No people detected in any frame")
+    
+    print(f"\n--- Alerts ---")
+    if all_alerts:
+        print(f"🚨 {len(all_alerts)} ALERTS TRIGGERED:")
+        for a in all_alerts:
+            alert = a["alert"]
+            print(f"   [{a['time']:.1f}s] [{alert.severity}] {alert.threat_type} "
+                  f"(confidence: {alert.confidence*100:.1f}%)")
+    else:
+        print("No alerts triggered")
+    
+    print(f"\n--- Output ---")
+    print(f"Annotated video saved to: {os.path.abspath(output_path)}")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    main()

tests/test_accuracy.py

@@ -0,0 +1,233 @@
+"""
+Test script to verify violence/fighting detection accuracy.
+Downloads sample fight clips and runs them through the pipeline,
+printing detailed per-frame analysis to verify detection works.
+"""
+import os
+import sys
+import time
+import cv2
+import numpy as np
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from suspicious_behavior.pipeline.frame_analyzer import FrameAnalyzer
+from suspicious_behavior.pipeline.video_processor import VideoProcessor
+
+
+def create_synthetic_fight_clip(output_path, num_frames=48, width=640, height=480):
+    """
+    Creates a synthetic video simulating two people in close proximity with
+    rapid arm movements — this tests whether the VideoMAE model responds
+    to motion patterns that resemble fighting.
+    """
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+    out = cv2.VideoWriter(output_path, fourcc, 10.0, (width, height))
+    
+    for i in range(num_frames):
+        # Create a frame with simulated scene
+        frame = np.zeros((height, width, 3), dtype=np.uint8)
+        # Add gray floor
+        frame[height//2:, :] = (80, 80, 80)
+        # Add background variation
+        frame[:height//2, :] = (40, 30, 20)
+        
+        # Person 1: oscillating arm movements
+        cx1 = width // 3
+        cy1 = height // 2 - 50
+        arm_offset = int(40 * np.sin(i * 0.8))
+        
+        # Body
+        cv2.rectangle(frame, (cx1-20, cy1-60), (cx1+20, cy1+60), (150, 100, 80), -1)
+        # Head
+        cv2.circle(frame, (cx1, cy1-80), 20, (180, 140, 120), -1)
+        # Arms (rapid movement)
+        cv2.line(frame, (cx1+20, cy1-30), (cx1+60+arm_offset, cy1-50+abs(arm_offset)), (150, 100, 80), 8)
+        cv2.line(frame, (cx1-20, cy1-30), (cx1-60-arm_offset, cy1-40-abs(arm_offset)//2), (150, 100, 80), 8)
+        # Legs
+        cv2.line(frame, (cx1-10, cy1+60), (cx1-20, cy1+120), (100, 70, 50), 8)
+        cv2.line(frame, (cx1+10, cy1+60), (cx1+20, cy1+120), (100, 70, 50), 8)
+        
+        # Person 2: close proximity, also swinging arms
+        cx2 = width // 3 + 100
+        cy2 = height // 2 - 40
+        arm_offset2 = int(35 * np.cos(i * 0.9))
+        
+        # Body
+        cv2.rectangle(frame, (cx2-20, cy2-60), (cx2+20, cy2+60), (80, 120, 160), -1)
+        # Head
+        cv2.circle(frame, (cx2, cy2-80), 20, (120, 160, 180), -1)
+        # Arms
+        cv2.line(frame, (cx2-20, cy2-30), (cx2-70+arm_offset2, cy2-60+abs(arm_offset2)), (80, 120, 160), 8)
+        cv2.line(frame, (cx2+20, cy2-30), (cx2+50-arm_offset2, cy2-30-abs(arm_offset2)//2), (80, 120, 160), 8)
+        # Legs
+        cv2.line(frame, (cx2-10, cy2+60), (cx2-15, cy2+120), (60, 90, 120), 8)
+        cv2.line(frame, (cx2+10, cy2+60), (cx2+15, cy2+120), (60, 90, 120), 8)
+        
+        out.write(frame)
+    
+    out.release()
+    print(f"[Test] Created synthetic fight clip: {output_path} ({num_frames} frames)")
+
+
+def test_with_video(video_path, analyzer, label="Unknown"):
+    """
+    Runs video through the pipeline and prints detailed frame-by-frame diagnostics.
+    """
+    if not os.path.exists(video_path):
+        print(f"[Test] Skipping {label}: file not found at {video_path}")
+        return
+        
+    processor = VideoProcessor(target_fps=10.0)
+    metadata = processor.get_metadata(video_path)
+    print(f"\n{'='*60}")
+    print(f"Testing: {label}")
+    print(f"File: {video_path}")
+    print(f"Duration: {metadata['duration']:.1f}s, {metadata['frame_count']} frames @ {metadata['fps']:.1f} FPS")
+    print(f"{'='*60}")
+    
+    # Reset analyzer state for clean test
+    analyzer.frame_idx = 0
+    analyzer.violence_buffer.clear()
+    analyzer.alert_manager.reset_cooldowns()
+    
+    frames_processed = 0
+    violence_scores = []
+    running_scores = []
+    alerts = []
+    
+    output_dir = "outputs"
+    os.makedirs(output_dir, exist_ok=True)
+    output_frames = []
+    
+    for f_idx, frame, timestamp in processor.extract_frames_generator(video_path):
+        annotated, frame_alerts, frame_meta = analyzer.analyze(frame, fps=10.0, output_base64=False)
+        frames_processed += 1
+        output_frames.append(annotated)
+        
+        # Collect violence and running metrics
+        v_meta = frame_meta["violence_metrics"]
+        if v_meta["confidence"] > 0:
+            violence_scores.append(v_meta["confidence"])
+            
+        for track in frame_meta["tracks"]:
+            running_scores.append(track["behavior_confidence"])
+        
+        for alert in frame_alerts:
+            alerts.append((timestamp, alert))
+        
+        # Print every frame's details for full diagnostic visibility
+        tracks_info = ", ".join([
+            f"ID{t['track_id']}:{t['behavior']}({t['behavior_confidence']*100:.0f}%)" 
+            for t in frame_meta["tracks"]
+        ]) or "none"
+        
+        violence_info = f"violence={v_meta['label']}({v_meta['confidence']*100:.1f}%)" if v_meta['confidence'] > 0 else ""
+        
+        print(f"  Frame {f_idx:04d} ({timestamp:5.1f}s) | People: {frame_meta['active_tracks_count']} | "
+              f"Tracks: [{tracks_info}] {violence_info} "
+              f"| Threats: {frame_meta['threats_detected']}")
+    
+    # Save annotated output
+    safe_label = label.replace(" ", "_").replace("/", "_")
+    output_path = os.path.join(output_dir, f"test_{safe_label}.mp4")
+    processor.write_frames_to_video(output_frames, output_path, fps=10.0, 
+                                     frame_size=(metadata['width'], metadata['height']))
+    
+    # Print summary
+    print(f"\n--- Results for: {label} ---")
+    print(f"Frames processed: {frames_processed}")
+    if violence_scores:
+        print(f"Violence scores: min={min(violence_scores)*100:.1f}%, max={max(violence_scores)*100:.1f}%, avg={np.mean(violence_scores)*100:.1f}%")
+    else:
+        print("Violence scores: No VideoMAE inference ran (need 16 frames + people in scene)")
+    if running_scores:
+        print(f"Running scores: min={min(running_scores)*100:.1f}%, max={max(running_scores)*100:.1f}%, avg={np.mean(running_scores)*100:.1f}%")
+    else:
+        print("Running scores: No people detected")
+    print(f"Alerts triggered: {len(alerts)}")
+    for ts, alert in alerts:
+        print(f"  [{ts:.1f}s] [{alert.severity}] {alert.threat_type} ({alert.confidence*100:.1f}%)")
+    print(f"Output: {output_path}")
+    
+
+def main():
+    print("=" * 60)
+    print("SimShieldAI — Violence & Running Detection Accuracy Test")
+    print("=" * 60)
+    
+    # Create synthetic test videos
+    os.makedirs("samples", exist_ok=True)
+    
+    # 1. Synthetic fight clip (48 frames = ~5s at 10fps)
+    synthetic_fight = "samples/synthetic_fight.mp4"
+    create_synthetic_fight_clip(synthetic_fight, num_frames=48)
+    
+    # 2. Synthetic normal/walking clip (person standing still)
+    synthetic_normal = "samples/synthetic_normal.mp4"
+    create_synthetic_normal_clip(synthetic_normal, num_frames=48)
+    
+    print("\n[Test] Initializing FrameAnalyzer (loading all models)...")
+    analyzer = FrameAnalyzer(camera_id="test_cam", violence_stride=4)
+    
+    # Test 1: Client CCTV (should be NORMAL — no fighting)
+    test_with_video("samples/FullSizeRender.mov", analyzer, label="Client CCTV (Normal)")
+    
+    # Test 2: Synthetic fight (test if the system processes it)
+    test_with_video(synthetic_fight, analyzer, label="Synthetic Fight")
+    
+    # Test 3: Synthetic normal (test false positive rate)
+    test_with_video(synthetic_normal, analyzer, label="Synthetic Normal")
+    
+    print("\n" + "=" * 60)
+    print("All tests complete!")
+    print("=" * 60)
+    print("\nIMPORTANT: To properly verify violence detection accuracy, you need")
+    print("real fighting video clips. Download from one of these sources:")
+    print("  1. Real-Life Violence Situations (RLVS) Dataset on Kaggle:")
+    print("     https://www.kaggle.com/datasets/mohamedmustafa/real-life-violence-situations-dataset")
+    print("  2. RWF-2000 Dataset on Kaggle:")
+    print("     https://www.kaggle.com/datasets/hwang033/rwf2000-video-database-for-violence-detection")
+    print("  3. Hockey Fight Dataset on Kaggle:")
+    print("     https://www.kaggle.com/datasets/yassershrief/hockey-fight-vidoes")
+    print("\nDownload a few 'fight' and 'non-fight' MP4 clips and place them in:")
+    print("  c:\\Users\\Admin\\Desktop\\testing_model\\samples\\")
+    print("Then re-run this script to verify detection accuracy.")
+
+
+def create_synthetic_normal_clip(output_path, num_frames=48, width=640, height=480):
+    """
+    Creates a synthetic video with a single person standing still — 
+    this should NOT trigger any violence or running alerts.
+    """
+    fourcc = cv2.VideoWriter_fourcc(*'mp4v')
+    out = cv2.VideoWriter(output_path, fourcc, 10.0, (width, height))
+    
+    for i in range(num_frames):
+        frame = np.zeros((height, width, 3), dtype=np.uint8)
+        frame[:] = (60, 50, 40)  # Dark background
+        frame[height//2:, :] = (80, 80, 80)  # Floor
+        
+        # Static person standing
+        cx = width // 2
+        cy = height // 2 - 30
+        
+        # Body
+        cv2.rectangle(frame, (cx-18, cy-55), (cx+18, cy+55), (140, 110, 90), -1)
+        # Head
+        cv2.circle(frame, (cx, cy-75), 18, (170, 140, 120), -1)
+        # Arms down
+        cv2.line(frame, (cx-18, cy-25), (cx-30, cy+40), (140, 110, 90), 7)
+        cv2.line(frame, (cx+18, cy-25), (cx+30, cy+40), (140, 110, 90), 7)
+        # Legs
+        cv2.line(frame, (cx-8, cy+55), (cx-12, cy+115), (100, 80, 60), 7)
+        cv2.line(frame, (cx+8, cy+55), (cx+12, cy+115), (100, 80, 60), 7)
+        
+        out.write(frame)
+    
+    out.release()
+    print(f"[Test] Created synthetic normal clip: {output_path} ({num_frames} frames)")
+
+
+if __name__ == "__main__":
+    main()

tests/validate_system.py

@@ -0,0 +1,89 @@
+import os
+import sys
+import time
+
+# Add project root to sys.path
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from suspicious_behavior.pipeline.frame_analyzer import FrameAnalyzer
+from suspicious_behavior.pipeline.video_processor import VideoProcessor
+
+def main():
+    video_path = "samples/FullSizeRender.mov"
+    output_dir = "outputs"
+    output_path = os.path.join(output_dir, "FullSizeRender_annotated.mp4")
+    
+    os.makedirs(output_dir, exist_ok=True)
+    
+    if not os.path.exists(video_path):
+        print(f"Error: Sample video not found at {video_path}")
+        sys.exit(1)
+        
+    print(f"[Validation] Opening video file: {video_path}...")
+    processor = VideoProcessor(target_fps=10.0)
+    metadata = processor.get_metadata(video_path)
+    print(f"[Validation] Video metadata: {metadata}")
+    
+    print("[Validation] Initializing FrameAnalyzer (loading models)...")
+    analyzer = FrameAnalyzer(camera_id="val_camera_1", violence_stride=8)
+    
+    processed_frames = []
+    latencies = []
+    all_alerts = []
+    
+    print("[Validation] Starting frame-by-frame analysis...")
+    start_total_time = time.time()
+    
+    try:
+        for frame_idx, frame, timestamp in processor.extract_frames_generator(video_path):
+            t0 = time.time()
+            annotated, alerts, frame_meta = analyzer.analyze(frame, fps=10.0, output_base64=False)
+            t_elapsed = (time.time() - t0) * 1000.0
+            
+            latencies.append(t_elapsed)
+            processed_frames.append(annotated)
+            
+            for alert in alerts:
+                all_alerts.append((frame_idx, alert))
+                
+            # Print frame summary every 10 processed frames
+            if len(processed_frames) % 10 == 0:
+                print(
+                    f"Frame {frame_idx:04d} ({timestamp:.2f}s) | "
+                    f"Latency: {t_elapsed:.1f}ms | "
+                    f"People: {frame_meta['active_tracks_count']} | "
+                    f"Threats: {frame_meta['threats_detected']}"
+                )
+    except KeyboardInterrupt:
+        print("[Validation] Interrupted by user. Compiling what we have...")
+        
+    total_time = time.time() - start_total_time
+    
+    if not latencies:
+        print("[Validation] No frames processed.")
+        sys.exit(1)
+        
+    avg_latency = sum(latencies) / len(latencies)
+    throughput_fps = len(processed_frames) / total_time
+    
+    print("\n--- Validation Statistics ---")
+    print(f"Frames Processed: {len(processed_frames)}")
+    print(f"Total Analysis Time: {total_time:.2f} seconds")
+    print(f"System Throughput: {throughput_fps:.2f} FPS")
+    print(f"Average Frame Latency: {avg_latency:.1f} ms")
+    print(f"Active Alerts Triggered: {len(all_alerts)}")
+    
+    for f_idx, alert in all_alerts:
+        print(f"  - Frame {f_idx}: [{alert.severity}] {alert.threat_type} ({alert.confidence*100:.1f}%)")
+        
+    print(f"\n[Validation] Compiling output video to: {output_path}...")
+    processor.write_frames_to_video(
+        processed_frames,
+        output_path,
+        fps=10.0,
+        frame_size=(metadata['width'], metadata['height'])
+    )
+    print("[Validation] Finished successfully!")
+
+if __name__ == "__main__":
+    main()