Initial commit for ProctorVision AI Docker backend

.gitignore

@@ -0,0 +1,7 @@
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.log
+model/*.h5
+model/*.keras

Dockerfile

@@ -0,0 +1,38 @@
+# ------------------------------------------------------------
+# Hugging Face Spaces - Docker Flask + TensorFlow + MediaPipe
+# ------------------------------------------------------------
+
+# Base image (Python + system deps)
+FROM python:3.10-slim
+
+# Disable interactive prompts
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Install system packages
+RUN apt-get update && apt-get install -y \
+    libgl1 \
+    libglib2.0-0 \
+    libopencv-core-dev \
+    libatlas-base-dev \
+ && rm -rf /var/lib/apt/lists/*
+
+# Set work directory
+WORKDIR /app
+
+# Copy dependency list
+COPY requirements.txt .
+
+# Upgrade pip and install dependencies
+RUN pip install --no-cache-dir --upgrade pip \
+ && pip install --no-cache-dir -r requirements.txt
+
+# Copy the full project
+COPY . .
+
+# Expose Space default port
+EXPOSE 7860
+
+# Command to run the Flask server
+CMD ["python", "app.py"]

app.py

@@ -0,0 +1,66 @@
+import os
+
+# -------------------------------------------------------------
+# Environment Configuration
+# -------------------------------------------------------------
+os.environ["TF_CPP_MIN_LOG_LEVEL"] = "3"   # Suppress TensorFlow INFO/WARN
+os.environ["GLOG_minloglevel"] = "2"       # Suppress Mediapipe logs
+
+from flask import Flask, jsonify
+from flask_cors import CORS
+
+# -------------------------------------------------------------
+# Flask Initialization
+# -------------------------------------------------------------
+app = Flask(__name__)
+
+# CORS Configuration
+CORS(
+    app,
+    resources={
+        r"/api/*": {
+            "origins": [
+                "http://localhost:3000",
+                "http://127.0.0.1:3000",
+                "https://proctorvision-client.vercel.app",  # your frontend
+                "https://<your-hf-space>.hf.space"           # if using Hugging Face
+            ]
+        }
+    },
+    supports_credentials=True,
+)
+
+# -------------------------------------------------------------
+# Import Blueprints
+# -------------------------------------------------------------
+try:
+    from routes.classification_routes import classification_bp
+    from routes.webrtc_routes import webrtc_bp
+    app.register_blueprint(classification_bp, url_prefix="/api")
+    app.register_blueprint(webrtc_bp, url_prefix="/api")
+    print("✅ Blueprints registered successfully.")
+except Exception as e:
+    print(f"⚠️ Warning: Failed to import one or more routes: {e}")
+
+# -------------------------------------------------------------
+# Root & Health Check Route
+# -------------------------------------------------------------
+@app.route("/")
+def home():
+    return jsonify({
+        "status": "ok",
+        "message": "✅ ProctorVision AI Backend Running",
+        "available_routes": [
+            "/api/classify_multiple",
+            "/api/classify_behavior_logs",
+            "/api/webrtc"
+        ]
+    })
+
+# -------------------------------------------------------------
+# Main Entrypoint
+# -------------------------------------------------------------
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 7860))  # Hugging Face / Railway default
+    debug = os.environ.get("DEBUG", "False").lower() == "true"
+    app.run(host="0.0.0.0", port=port, debug=debug)

database/connection.py

@@ -0,0 +1,12 @@
+import os
+import mysql.connector
+
+def get_db_connection():
+    connection = mysql.connector.connect(
+        host=os.getenv("DB_HOST", "localhost"),
+        port=os.getenv("DB_PORT", "3306"),
+        user=os.getenv("DB_USER", "root"),
+        password=os.getenv("DB_PASSWORD", ""),
+        database=os.getenv("DB_NAME", "proctorvision_db")
+    )
+    return connection

database/db_query.txt

@@ -0,0 +1,79 @@
+CREATE DATABASE proctorvision_db;
+
+USE proctorvision_db;
+
+CREATE TABLE admin (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  admin_id VARCHAR(50),
+  name VARCHAR(100),
+  username VARCHAR(50),
+  email VARCHAR(100),
+  password VARCHAR(255)
+);
+
+CREATE TABLE users (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  user_id VARCHAR(50),
+  name VARCHAR(100),
+  username VARCHAR(50),
+  email VARCHAR(100),
+  password VARCHAR(255),
+  user_type VARCHAR(50)
+);
+
+INSERT INTO admin (admin_id, name, username, email, password)
+VALUES 
+  ('ADM001', 'Gwen Nuqui', 'gwenadmin', 'gwen@example.com', '$2b$12$XrXNhJK8Gv5y6gXXQFZxJeHuqA6Z/hOZ.Af2okyWd8BpRU7hZzS3C')  -- password123
+
+SELECT * FROM admin;
+SELECT * FROM users;
+
+USE proctorvision_db;
+
+SELECT * FROM admin;
+SELECT * FROM users;
+SELECT * FROM exams;
+SELECT * FROM exam_students;
+SELECT * FROM instructor_assignment;
+
+CREATE TABLE suspicious_behavior_logs (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  user_id INT NOT NULL,
+  exam_id INT NOT NULL,
+  image_base64 LONGTEXT,
+  warning_type VARCHAR(255),
+  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+  FOREIGN KEY (exam_id) REFERENCES exams(id) ON DELETE CASCADE
+);
+
+SELECT * FROM suspicious_behavior_logs;
+
+
+ALTER TABLE suspicious_behavior_logs
+ADD COLUMN classification_label VARCHAR(50) DEFAULT NULL;
+
+CREATE TABLE exam_submissions (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  user_id INT NOT NULL,
+  exam_id INT NOT NULL,
+  submitted_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY unique_submission (user_id, exam_id)
+);
+
+SELECT * FROM exam_submissions;
+
+DELETE FROM suspicious_behavior_logs WHERE id = 1;
+
+CREATE TABLE student_profiles (
+  user_id VARCHAR(50) PRIMARY KEY,
+  course VARCHAR(100),
+  section VARCHAR(100),
+  FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE
+);
+
+
+
+
+

database/manual_insert.py

@@ -0,0 +1,58 @@
+import bcrypt
+import mysql.connector
+
+# Database connection
+from connection import get_db_connection  
+conn = get_db_connection()
+cursor = conn.cursor()
+
+# List of (name, username) tuples
+users = [
+    ("Melojean C. Marave", "melojean"),
+    ("Carl Angelo S. Pamploma", "carl"),
+    ("Geoffrey S. Sepillo", "geoffrey"),
+    ("Hansel S. Ada", "hansel"),
+    ("John Lenon E. Agatep", "john"),
+    ("Israel M. Cabasug", "israel"),
+    ("Niemea M. Galang", "niemea"),
+    ("Jason S. Arates", "jason"),
+    ("Fiel M. Dullas", "fiel"),
+    ("Darwin M. Morana", "darwin"),
+    ("Ronnel M. Mesia", "ronnel"),
+    ("May Ann A. Acera", "may"),
+    ("Joseph J. Juliano", "joseph"),
+    ("Daniel A. Bachillar", "daniel"),
+    ("Darly John Ragadio", "darly"),
+    ("Eufemia Sion", "eufemia"),
+    ("Marionne Joyce F. Tapado", "marionne"),
+    ("Rowela Gongora", "rowela"),
+    ("Joseph S. Cortez", "joseph2"),
+    ("King Myer Mantolino", "king"),
+    ("Jamil Tan Elamparo", "jamil"),
+    ("Rowena Orboc", "rowena"),
+    ("Hicel Mae Mas", "hicel"),
+    ("Karen Quintoriano", "karen"),
+    ("Ashley Rambuyong", "ashley"),
+    ("Kie Ann Josafat", "kie"),
+    ("Jio Erika Pelinio", "jio"),
+    ("Dane Nalicat", "dane"),
+    ("Radowena Payumo", "radowena"),
+    ("Michael G. Albino", "michael"),
+    ("Apple Escalante", "apple"),
+    ("Katherine Uy", "katherine"),
+]
+
+# Insert each instructor with hashed password
+for name, username in users:
+    email = f"{username}@email.com"
+    raw_password = f"{username}123"
+    hashed_password = bcrypt.hashpw(raw_password.encode('utf-8'), bcrypt.gensalt())
+
+    cursor.execute("""
+        INSERT INTO users (name, username, email, password, user_type)
+        VALUES (%s, %s, %s, %s, %s)
+    """, (name, username, email, hashed_password, "Instructor"))
+
+conn.commit()
+cursor.close()
+conn.close()

requirements.txt

@@ -0,0 +1,8 @@
+Flask==3.0.3
+Flask-Cors==4.0.0
+numpy==1.26.4
+opencv-python-headless==4.9.0.80
+mediapipe==0.10.14
+Pillow==10.3.0
+gunicorn==21.2.0
+tensorflow-cpu==2.15.0

routes/classification_routes.py

@@ -0,0 +1,171 @@
+import os, io, base64
+from pathlib import Path
+from flask import Blueprint, request, jsonify
+import tensorflow as tf
+import numpy as np
+import cv2
+from PIL import Image
+
+try:
+    # TF-bundled Keras (common with TensorFlow installs)
+    from tensorflow.keras.applications import mobilenet_v2 as _mv2  # type: ignore
+except Exception:
+    # Standalone Keras 3
+    from keras.applications import mobilenet_v2 as _mv2  # type: ignore
+
+preprocess_input = _mv2.preprocess_input
+
+from database.connection import get_db_connection
+
+classification_bp = Blueprint('classification_bp', __name__)
+
+# ---------- Model & threshold loading ----------
+BASE_DIR  = Path(__file__).resolve().parent.parent   # -> server/
+MODEL_DIR = BASE_DIR / "model"
+
+CANDIDATES = [
+    "cheating_mobilenetv2_final.keras",  # your chosen deploy name
+    "mnv2_clean_best.keras",
+    "mnv2_continue.keras",
+    "mnv2_finetune_best.keras",
+]
+
+model_path = next((MODEL_DIR / f for f in CANDIDATES if (MODEL_DIR / f).exists()), None)
+if model_path and model_path.exists():
+    model = tf.keras.models.load_model(model_path, compile=False)
+    print(f" Model loaded: {model_path}")
+else:
+    model = None
+    print(f" No model file found in {MODEL_DIR}. Put one of: {CANDIDATES}")
+
+thr_file = MODEL_DIR / "best_threshold.npy"
+THRESHOLD = float(np.load(thr_file)[0]) if thr_file.exists() else 0.555
+print(f"Using decision threshold: {THRESHOLD:.3f}")
+
+# Input size
+if model is not None:
+    H, W = model.input_shape[1:3]
+else:
+    H, W = 224, 224  # fallback
+
+# Class mapping used in training:
+# class 0 -> "cheating", class 1 -> "non-cheating"
+LABELS = ["Cheating", "Not Cheating"]
+
+def preprocess_pil(pil_img: Image.Image) -> np.ndarray:
+    """Convert PIL -> model-ready tensor (1, H, W, 3) using MobileNetV2 preprocessing."""
+    img = pil_img.convert("RGB")
+    if img.size != (W, H):
+        img = img.resize((W, H), Image.BILINEAR)
+    x = np.asarray(img, dtype=np.float32)
+    x = preprocess_input(x)          # <- IMPORTANT: same preprocessing as training
+    return np.expand_dims(x, 0)
+
+def predict_batch(batch_np: np.ndarray) -> np.ndarray:
+    """batch_np: (N, H, W, 3) already preprocessed; returns probs of class 1 (non-cheating)."""
+    probs = model.predict(batch_np, verbose=0).ravel()
+    # If model outputs 2 logits (softmax), convert to class-1 prob
+    if probs.ndim == 0:    # single item edge case
+        probs = np.array([probs])
+    if len(probs) != batch_np.shape[0]:
+        # Handle (N,2) softmax output
+        raw = model.predict(batch_np, verbose=0)
+        if raw.ndim == 2 and raw.shape[1] == 2:
+            probs = raw[:, 1]  # prob for class index 1 => "Not Cheating"
+        else:
+            probs = raw.ravel()
+    return probs
+
+def label_from_prob(prob_non_cheating: float) -> str:
+    """prob = P(class 1 = 'Not Cheating')"""
+    return LABELS[int(prob_non_cheating >= THRESHOLD)]
+# ------------------------------------------------
+
+
+# -------- Route 1: classify uploaded multiple files --------
+@classification_bp.route('/classify_multiple', methods=['POST'])
+def classify_multiple():
+    if model is None:
+        return jsonify({"error": "Model not loaded."}), 500
+
+    files = request.files.getlist('files') if 'files' in request.files else []
+    if not files:
+        return jsonify({"error": "No files uploaded"}), 400
+
+    # Preprocess all, predict in one batch (faster & avoids TF retracing spam)
+    batch = []
+    for f in files:
+        try:
+            pil = Image.open(io.BytesIO(f.read()))
+            batch.append(preprocess_pil(pil)[0])  # (H,W,3)
+        except Exception as e:
+            return jsonify({"error": f"Error reading an image: {str(e)}"}), 400
+
+    batch_np = np.stack(batch, axis=0)  # (N,H,W,3)
+    probs = predict_batch(batch_np)     # prob of class 1 (Not Cheating)
+    labels = [label_from_prob(p) for p in probs]
+
+    return jsonify({
+        "threshold": THRESHOLD,
+        "results": [{"label": lbl, "prob_non_cheating": float(p)} for lbl, p in zip(labels, probs)]
+    })
+
+
+# -------- Route 2: auto-classify behavior logs --------
+@classification_bp.route('/classify_behavior_logs', methods=['POST'])
+def classify_behavior_logs():
+    if model is None:
+        return jsonify({"error": "Model not loaded."}), 500
+
+    data = request.get_json(silent=True) or {}
+    user_id = data.get('user_id')
+    exam_id = data.get('exam_id')
+    if not user_id or not exam_id:
+        return jsonify({"error": "Missing user_id or exam_id"}), 400
+
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor(dictionary=True)
+
+        cursor.execute("""
+            SELECT id, image_base64 FROM suspicious_behavior_logs
+            WHERE user_id = %s AND exam_id = %s AND image_base64 IS NOT NULL
+        """, (user_id, exam_id))
+        logs = cursor.fetchall()
+
+        # Vectorized predict in chunks
+        CHUNK = 64
+        for i in range(0, len(logs), CHUNK):
+            chunk = logs[i:i+CHUNK]
+            batch = []
+            ids = []
+            for log in chunk:
+                try:
+                    img_data = base64.b64decode(log['image_base64'])
+                    pil = Image.open(io.BytesIO(img_data))
+                    batch.append(preprocess_pil(pil)[0])
+                    ids.append(log['id'])
+                except Exception as e:
+                    print(f" Failed to read image ID {log['id']}: {e}")
+
+            if not batch:
+                continue
+
+            batch_np = np.stack(batch, axis=0)
+            probs = predict_batch(batch_np)
+            labels = [label_from_prob(p) for p in probs]
+
+            # write back
+            cur2 = conn.cursor()
+            for _id, lbl in zip(ids, labels):
+                cur2.execute(
+                    "UPDATE suspicious_behavior_logs SET classification_label=%s WHERE id=%s",
+                    (lbl, _id)
+                )
+            conn.commit()
+
+        conn.close()
+        return jsonify({"message": "Classification complete.", "threshold": THRESHOLD}), 200
+
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500

routes/webrtc_routes.py

@@ -0,0 +1,511 @@
+# routes/webrtc_routes.py
+from flask import Blueprint, request, jsonify
+import asyncio, time, traceback, os, threading, base64
+from collections import defaultdict, deque
+from aiortc import RTCPeerConnection, RTCSessionDescription
+from aiortc.contrib.media import MediaBlackhole
+import cv2, numpy as np
+import mediapipe as mp
+
+from services.behavior_service import save_behavior_log_async  # save image to DB (async)
+from services.instructor_services import increment_suspicious_for_student_async  # bump counter (async)
+
+webrtc_bp = Blueprint("webrtc", __name__)
+
+# -------- logging / config --------
+SUMMARY_EVERY_S = float(os.getenv("PROCTOR_SUMMARY_EVERY_S", "1.0"))
+RECV_TIMEOUT_S  = float(os.getenv("PROCTOR_RECV_TIMEOUT_S", "5.0"))   # timeout for track.recv
+HEARTBEAT_S     = float(os.getenv("PROCTOR_HEARTBEAT_S", "10.0"))     # reader heartbeat log
+
+def log(event, sid="-", eid="-", **kv):
+    tail = " ".join(f"{k}={v}" for k, v in kv.items())
+    print(f"[{event}] sid={sid} eid={eid} {tail}".strip(), flush=True)
+
+# -------- persistent asyncio loop (aiortc needs this) --------
+_loop = asyncio.new_event_loop()
+threading.Thread(target=_loop.run_forever, daemon=True).start()
+def run_coro(coro):
+    return asyncio.run_coroutine_threadsafe(coro, _loop).result()
+
+# -------- global state --------
+pcs = set()
+last_warning = defaultdict(lambda: {"warning": "Looking Forward", "at": 0})
+last_metrics = defaultdict(lambda: {"yaw": None, "pitch": None, "dx": None, "dy": None, "fps": None, "label": "n/a", "at": 0})
+last_capture = defaultdict(lambda: {"label": None, "at": 0})
+
+# -------- thresholds (env tunable) --------
+# head pose
+YAW_DEG_TRIG        = float(os.getenv("PROCTOR_YAW_DEG", "12"))     # left/right
+PITCH_DEG_TRIG_UP   = float(os.getenv("PROCTOR_PITCH_UP_DEG", "10")) # up
+PITCH_DEG_TRIG_DOWN = float(os.getenv("PROCTOR_PITCH_DOWN_DEG", "16")) # down (less sensitive than before)
+DX_TRIG             = float(os.getenv("PROCTOR_DX", "0.06"))
+DY_TRIG_UP          = float(os.getenv("PROCTOR_DY_UP", "0.08"))
+DY_TRIG_DOWN        = float(os.getenv("PROCTOR_DY_DOWN", "0.10"))     # down (less sensitive)
+SMOOTH_N            = int(os.getenv("PROCTOR_SMOOTH_N", "5"))
+
+# capture policy
+CAPTURE_MIN_MS        = int(os.getenv("PROCTOR_CAPTURE_MIN_MS", "1200"))
+HOLD_FRAMES_HEAD      = int(os.getenv("PROCTOR_HOLD_FRAMES_HEAD", "3"))
+HOLD_FRAMES_NOFACE    = int(os.getenv("PROCTOR_HOLD_FRAMES_NOFACE", "3"))
+HOLD_FRAMES_HAND      = int(os.getenv("PROCTOR_HOLD_FRAMES_HAND", "5"))  # stricter for hands
+
+# hand filters (reduce sensitivity)
+HAND_MIN_BOX_FRAC     = float(os.getenv("PROCTOR_HAND_MIN_BOX_FRAC", "0.025"))  # 2.5% of frame area
+HAND_MAX_BOX_FRAC     = float(os.getenv("PROCTOR_HAND_MAX_BOX_FRAC", "0.60"))   # ignore near-full-frame noise
+HAND_REQUIRE_LANDMARK = int(os.getenv("PROCTOR_HAND_REQUIRE_LANDMARK", "7"))    # at least N landmarks in-box
+
+# -------- MediaPipe --------
+mp_face_mesh = mp.solutions.face_mesh
+face_mesh = mp_face_mesh.FaceMesh(
+    static_image_mode=False, max_num_faces=1, refine_landmarks=True,
+    min_detection_confidence=0.6, min_tracking_confidence=0.6
+)
+mp_hands = mp.solutions.hands
+hands = mp_hands.Hands(
+    static_image_mode=False, max_num_hands=2,
+    min_detection_confidence=0.6, min_tracking_confidence=0.6
+)
+
+# FaceMesh indices + 3D model
+IDX_NOSE, IDX_CHIN = 1, 152
+IDX_LE, IDX_RE     = 263, 33
+IDX_LM, IDX_RM     = 291, 61
+MODEL_3D = np.array([
+    [ 0.0,   0.0,   0.0],
+    [ 0.0, -63.6, -12.5],
+    [-43.3,  32.7, -26.0],
+    [ 43.3,  32.7, -26.0],
+    [-28.9, -28.9, -24.1],
+    [ 28.9, -28.9, -24.1],
+], dtype=np.float32)
+
+def _landmarks_to_pts(lms, w, h):
+    ids = [IDX_NOSE, IDX_CHIN, IDX_LE, IDX_RE, IDX_LM, IDX_RM]
+    return np.array([[lms[i].x * w, lms[i].y * h] for i in ids], dtype=np.float32)
+
+def _bbox_from_landmarks(lms, w, h, pad=0.03):
+    xs = [p.x for p in lms]; ys = [p.y for p in lms]
+    x1n, y1n = max(0.0, min(xs) - pad), max(0.0, min(ys) - pad)
+    x2n, y2n = min(1.0, max(xs) + pad), min(1.0, max(ys) + pad)
+    return (int(x1n*w), int(y1n*h), int(x2n*w), int(y2n*h))
+
+# -------- detector --------
+class ProctorDetector:
+    def __init__(self):
+        self.yaw_hist   = deque(maxlen=SMOOTH_N)
+        self.pitch_hist = deque(maxlen=SMOOTH_N)
+        self.dx_hist    = deque(maxlen=SMOOTH_N)
+        self.dy_hist    = deque(maxlen=SMOOTH_N)
+        self.last_print = 0.0
+        self.base_yaw = None
+        self.base_pitch = None
+        self.last_capture_ms = 0
+
+        # streaks for noface / hand capture holds
+        self.noface_streak = 0
+        self.hand_streak   = 0
+
+    def _update_baseline(self, yaw, pitch):
+        alpha = 0.10
+        if yaw is not None:
+            self.base_yaw = yaw if self.base_yaw is None else (1-alpha)*self.base_yaw + alpha*yaw
+        if pitch is not None:
+            self.base_pitch = pitch if self.base_pitch is None else (1-alpha)*self.base_pitch + alpha*pitch
+
+    def _pose_angles(self, lms, w, h):
+        try:
+            pts2d = _landmarks_to_pts(lms, w, h)
+            cam = np.array([[w, 0, w/2],
+                            [0, w, h/2],
+                            [0, 0, 1     ]], dtype=np.float32)
+            dist = np.zeros((4,1), dtype=np.float32)
+            ok, rvec, _ = cv2.solvePnP(MODEL_3D, pts2d, cam, dist, flags=cv2.SOLVEPNP_ITERATIVE)
+            if not ok: return None, None
+            R, _ = cv2.Rodrigues(rvec)
+            *_, euler = cv2.RQDecomp3x3(R)
+            pitch, yaw, _ = map(float, euler)
+            return yaw, pitch
+        except Exception:
+            return None, None
+
+    def detect(self, bgr, sid="-", eid="-"):
+        h, w = bgr.shape[:2]
+        rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB)
+        res = face_mesh.process(rgb)
+
+        if not res.multi_face_landmarks:
+            now = time.time()
+            if now - self.last_print >= SUMMARY_EVERY_S:
+                log("FRAME", sid, eid, note="no_face")
+                self.last_print = now
+            return "No Face", None, rgb, None, None, None, None
+
+        lms = res.multi_face_landmarks[0].landmark
+        box = _bbox_from_landmarks(lms, w, h, pad=0.03)
+
+        # pixel offsets
+        x1, y1, x2, y2 = box
+        fw, fh = max(1, x2-x1), max(1, y2-y1)
+        cx, cy = x1 + fw/2.0, y1 + fh/2.0
+        nose_x, nose_y = lms[IDX_NOSE].x * w, lms[IDX_NOSE].y * h
+        dx = (nose_x - cx) / fw   # + right
+        dy = (nose_y - cy) / fh   # + down
+        self.dx_hist.append(dx); self.dy_hist.append(dy)
+        dx_s = float(np.median(self.dx_hist))
+        dy_s = float(np.median(self.dy_hist))
+
+        # angles (may be None on some frames)
+        yaw, pitch = self._pose_angles(lms, w, h)
+        yaw_s = pitch_s = None
+        if yaw is not None:
+            self.yaw_hist.append(yaw);   yaw_s   = float(np.median(self.yaw_hist))
+        if pitch is not None:
+            self.pitch_hist.append(pitch); pitch_s = float(np.median(self.pitch_hist))
+
+        # triggers
+        yaw_trigger   = (yaw_s is not None and abs(yaw_s) > YAW_DEG_TRIG) or (abs(dx_s) > DX_TRIG)
+
+        # For "Down", require BOTH pitch and DY to exceed higher thresholds
+        pitch_down_trigger = (
+            (pitch_s is not None and pitch_s > PITCH_DEG_TRIG_DOWN) and
+            (dy_s > DY_TRIG_DOWN)
+        )
+        # For "Up", keep original sensitivity (OR) unless you also want stricter:
+        pitch_up_trigger = (
+            (pitch_s is not None and -pitch_s > PITCH_DEG_TRIG_UP) or
+            (dy_s < -DY_TRIG_UP)
+        )
+
+        label = "Looking Forward"
+        if yaw_trigger and (abs(dx_s) >= abs(dy_s) or not (pitch_up_trigger or pitch_down_trigger)):
+            label = "Looking Right" if dx_s > 0 else "Looking Left"
+        elif pitch_down_trigger:
+            label = "Looking Down"
+        elif pitch_up_trigger:
+            label = "Looking Up"
+
+        if label == "Looking Forward":
+            self._update_baseline(yaw_s, pitch_s)
+
+        now = time.time()
+        if now - self.last_print >= SUMMARY_EVERY_S:
+            log("FRAME", sid, eid,
+                yaw=f"{yaw_s:.1f}" if yaw_s is not None else "na",
+                pitch=f"{pitch_s:.1f}" if pitch_s is not None else "na",
+                dx=f"{dx_s:.3f}", dy=f"{dy_s:.3f}", choose=label)
+            self.last_print = now
+
+        return label, box, rgb, yaw_s, pitch_s, dx_s, dy_s
+
+    def detect_hands_anywhere(self, rgb):
+        """
+        Less sensitive hand detection:
+        - requires a minimum hand bounding box area vs frame (HAND_MIN_BOX_FRAC)
+        - ignores absurdly large boxes (HAND_MAX_BOX_FRAC)
+        - returns ('Hand Detected', count) only if at least one qualified hand is present
+        """
+        h, w = rgb.shape[:2]
+        frame_area = float(h * w)
+        res = hands.process(rgb)
+        if not res.multi_hand_landmarks:
+            return None, 0
+
+        qualified = 0
+        for hlms in res.multi_hand_landmarks:
+            xs = [p.x for p in hlms.landmark]; ys = [p.y for p in hlms.landmark]
+            x1 = max(0, int(min(xs) * w)); y1 = max(0, int(min(ys) * h))
+            x2 = min(w, int(max(xs) * w)); y2 = min(h, int(max(ys) * h))
+            bw, bh = max(1, x2 - x1), max(1, y2 - y1)
+            box_area_frac = (bw * bh) / frame_area
+
+            # crude landmark-count-in-box sanity (they all are, but keep option)
+            lm_in_box = sum(
+                1 for p in hlms.landmark
+                if (x1 <= int(p.x * w) <= x2 and y1 <= int(p.y * h) <= y2)
+            )
+
+            if HAND_MIN_BOX_FRAC <= box_area_frac <= HAND_MAX_BOX_FRAC and lm_in_box >= HAND_REQUIRE_LANDMARK:
+                qualified += 1
+
+        if qualified > 0:
+            return "Hand Detected", qualified
+        return None, 0
+
+    # capture throttles (shared for all capture kinds)
+    def _throttle_ok(self):
+        return int(time.time()*1000) - self.last_capture_ms >= CAPTURE_MIN_MS
+    def _mark_captured(self):
+        self.last_capture_ms = int(time.time()*1000)
+
+    # head (left/right/up/down)
+    def should_capture_head(self, head_label, sid="-", eid="-"):
+        if head_label in ("Looking Forward", "No Face"):
+            return False
+        if not self._throttle_ok():
+            return False
+
+        # Pixel hold
+        pixel_hold_ok = False
+        if len(self.dx_hist) >= HOLD_FRAMES_HEAD and len(self.dy_hist) >= HOLD_FRAMES_HEAD:
+            dxs = list(self.dx_hist)[-HOLD_FRAMES_HEAD:]
+            dys = list(self.dy_hist)[-HOLD_FRAMES_HEAD:]
+            if head_label in ("Looking Left", "Looking Right"):
+                pixel_hold_ok = all(abs(x) > DX_TRIG for x in dxs)
+            elif head_label in ("Looking Up", "Looking Down"):
+                # For "Down", mirror the stricter rule: require DY hold above down threshold
+                if head_label == "Looking Down":
+                    pixel_hold_ok = all(y > DY_TRIG_DOWN for y in dys)
+                else:  # Looking Up
+                    pixel_hold_ok = all(-y > DY_TRIG_UP for y in dys)
+            else:
+                pixel_hold_ok = (all(abs(x) > DX_TRIG for x in dxs) or
+                                 all(abs(y) > max(DY_TRIG_UP, DY_TRIG_DOWN) for y in dys))
+
+        # Angle hold
+        angle_hold_ok = False
+        if len(self.yaw_hist) >= HOLD_FRAMES_HEAD and len(self.pitch_hist) >= HOLD_FRAMES_HEAD:
+            by = self.base_yaw if self.base_yaw is not None else 0.0
+            bp = self.base_pitch if self.base_pitch is not None else 0.0
+            recent_yaw   = list(self.yaw_hist)[-HOLD_FRAMES_HEAD:]
+            recent_pitch = list(self.pitch_hist)[-HOLD_FRAMES_HEAD:]
+            if head_label in ("Looking Left", "Looking Right"):
+                angle_hold_ok = all(abs(y - by) > YAW_DEG_TRIG for y in recent_yaw)
+            elif head_label == "Looking Down":
+                angle_hold_ok = all((p - bp) > PITCH_DEG_TRIG_DOWN for p in recent_pitch)
+            elif head_label == "Looking Up":
+                angle_hold_ok = all((bp - p) > PITCH_DEG_TRIG_UP for p in recent_pitch)
+
+        ok = pixel_hold_ok or angle_hold_ok
+        if ok:
+            log("CAPTURE_DECISION_HEAD", sid, eid, label=head_label,
+                pixel_hold=pixel_hold_ok, angle_hold=angle_hold_ok,
+                hold_frames=HOLD_FRAMES_HEAD, ok=True)
+            self._mark_captured()
+        return ok
+
+    # no face
+    def should_capture_noface(self, sid="-", eid="-"):
+        if not self._throttle_ok():
+            return False
+        ok = self.noface_streak >= HOLD_FRAMES_NOFACE
+        if ok:
+            log("CAPTURE_DECISION_NOFACE", sid, eid,
+                streak=self.noface_streak, hold_frames=HOLD_FRAMES_NOFACE, ok=True)
+            self._mark_captured()
+        return ok
+
+    # hands
+    def should_capture_hand(self, hand_label, sid="-", eid="-"):
+        if not hand_label:
+            return False
+        if not self._throttle_ok():
+            return False
+        ok = self.hand_streak >= HOLD_FRAMES_HAND
+        if ok:
+            log("CAPTURE_DECISION_HAND", sid, eid,
+                streak=self.hand_streak, hold_frames=HOLD_FRAMES_HAND, ok=True)
+            self._mark_captured()
+        return ok
+
+detectors = defaultdict(ProctorDetector)
+
+# -------- capture helper --------
+def _maybe_capture(student_id: str, exam_id: str, bgr, label: str):
+    ok, buf = cv2.imencode(".jpg", bgr)
+    if not ok:
+        log("CAPTURE_SKIP", student_id, exam_id, reason="encode_failed")
+        return
+
+    img_b64 = base64.b64encode(buf).decode("utf-8")
+    log("CAPTURE_ENQUEUE", student_id, exam_id, label=label, bytes=len(buf))
+
+    # Save image to DB (async)
+    save_behavior_log_async(
+        int(student_id), int(exam_id), img_b64, label,
+        on_error=lambda e: log("CAPTURE_ERR", student_id, exam_id, err=str(e))
+    )
+
+    # bump suspicious counter (async)
+    increment_suspicious_for_student_async(int(student_id))
+
+    # update in-memory cache for frontend beep
+    ts = int(time.time() * 1000)
+    last_capture[(student_id, exam_id)] = {"label": label, "at": ts}
+    log("LAST_CAPTURE_SET", student_id, exam_id, label=label, at=ts)
+
+# -------- aiortc helpers --------
+async def _wait_ice_complete(pc: RTCPeerConnection):
+    if pc.iceGatheringState == "complete":
+        return
+    done = asyncio.Event()
+    @pc.on("icegatheringstatechange")
+    def _(_ev=None):
+        if pc.iceGatheringState == "complete":
+            done.set()
+    await asyncio.wait_for(done.wait(), timeout=5.0)
+
+async def handle_offer(data: dict):
+    student_id = str(data.get("student_id", "0"))
+    exam_id    = str(data.get("exam_id", "0"))
+    key = (student_id, exam_id)
+    log("OFFER_HANDLE", student_id, exam_id)
+
+    offer = RTCSessionDescription(sdp=data["sdp"], type=data["type"])
+    pc = RTCPeerConnection()
+    pcs.add(pc)
+    log("PC_CREATED", student_id, exam_id, pc=id(pc))
+
+    @pc.on("connectionstatechange")
+    async def _():
+        log("PC_STATE", student_id, exam_id, state=pc.connectionState)
+        if pc.connectionState in ("failed", "closed", "disconnected"):
+            try:
+                await pc.close()
+            finally:
+                pcs.discard(pc)
+                for d in (detectors, last_warning, last_metrics, last_capture):
+                    d.pop(key, None)
+                log("PC_CLOSED", student_id, exam_id, pc=id(pc))
+
+    @pc.on("track")
+    def on_track(track):
+        log("TRACK", student_id, exam_id, kind=track.kind)
+        if track.kind == "video":
+            async def reader():
+                det = detectors[key]
+                t_fps = time.time(); frames = 0
+                last_heartbeat = time.time()
+
+                while True:
+                    # --- receive with timeout ---
+                    try:
+                        frame = await asyncio.wait_for(track.recv(), timeout=RECV_TIMEOUT_S)
+                    except asyncio.TimeoutError:
+                        # lightweight heartbeat on timeouts
+                        now = time.time()
+                        if now - last_heartbeat >= HEARTBEAT_S:
+                            log("TRACK_RECV_TIMEOUT", student_id, exam_id, timeout_s=RECV_TIMEOUT_S)
+                            last_heartbeat = now
+                        continue
+                    except Exception as e:
+                        log("TRACK_RECV_END", student_id, exam_id, err=str(e))
+                        break
+
+                    # fps window
+                    frames += 1
+                    now = time.time()
+                    if now - t_fps >= 2.0:
+                        fps = frames / max(1e-6, (now - t_fps))
+                        lm = last_metrics.get(key, {})
+                        lm["fps"] = fps
+                        last_metrics[key] = lm
+                        log("FPS", student_id, exam_id, fps=f"{fps:.1f}")
+                        t_fps = now; frames = 0
+
+                    # --- per-frame detection protected ---
+                    try:
+                        bgr = frame.to_ndarray(format="bgr24")
+                        head_label, face_box, rgb, yaw_s, pitch_s, dx_s, dy_s = det.detect(bgr, sid=student_id, eid=exam_id)
+                        hand_label, _ = det.detect_hands_anywhere(rgb)
+                    except Exception as e:
+                        log("DETECT_ERR", student_id, exam_id, err=str(e))
+                        continue
+
+                    # maintain streaks with stricter holds for hand/noface
+                    det.noface_streak = det.noface_streak + 1 if head_label == "No Face" else 0
+                    det.hand_streak   = det.hand_streak + 1 if hand_label else 0
+
+                    # choose UI label
+                    if head_label == "No Face":
+                        warn = "No Face (Hand Detected)" if hand_label else "No Face"
+                    elif head_label != "Looking Forward":
+                        warn = head_label
+                    elif hand_label:
+                        warn = hand_label
+                    else:
+                        warn = "Looking Forward"
+
+                    # --- capture priority with holds/throttle ---
+                    if head_label == "No Face" and det.should_capture_noface(sid=student_id, eid=exam_id):
+                        _maybe_capture(student_id, exam_id, bgr, "No Face")
+                    elif head_label not in ("Looking Forward", "No Face") and det.should_capture_head(head_label, sid=student_id, eid=exam_id):
+                        _maybe_capture(student_id, exam_id, bgr, head_label)
+                    elif hand_label and det.should_capture_hand(hand_label, sid=student_id, eid=exam_id):
+                        _maybe_capture(student_id, exam_id, bgr, "Hand Detected")
+
+                    ts = int(time.time() * 1000)
+                    last_warning[key] = {"warning": warn, "at": ts}
+                    last_metrics[key] = {
+                        "yaw": yaw_s, "pitch": pitch_s, "dx": dx_s, "dy": dy_s,
+                        "fps": last_metrics.get(key, {}).get("fps"), "label": warn, "at": ts
+                    }
+
+                    # reader heartbeat (when frames flow)
+                    if now - last_heartbeat >= HEARTBEAT_S:
+                        log("READER_ALIVE", student_id, exam_id, label=warn)
+                        last_heartbeat = now
+
+            asyncio.ensure_future(reader(), loop=_loop)
+        else:
+            MediaBlackhole().addTrack(track)
+
+    await pc.setRemoteDescription(offer)
+    answer = await pc.createAnswer()
+    await pc.setLocalDescription(answer)
+    await _wait_ice_complete(pc)
+    log("ICE_DONE", student_id, exam_id)
+    return pc.localDescription
+
+# -------- routes --------
+@webrtc_bp.route("/webrtc/offer", methods=["POST"])
+def webrtc_offer():
+    try:
+        data = request.get_json(force=True)
+    except Exception as e:
+        return jsonify({"error": f"invalid json: {e}"}), 400
+    sid = str(data.get("student_id", "0")); eid = str(data.get("exam_id", "0"))
+    log("OFFER_RX", sid, eid)
+    try:
+        desc = run_coro(handle_offer(data))
+    except Exception as e:
+        traceback.print_exc()
+        log("OFFER_ERR", sid, eid, err=str(e))
+        return jsonify({"error": str(e)}), 500
+    log("ANSWER_TX", sid, eid)
+    return jsonify({"sdp": desc.sdp, "type": desc.type})
+
+@webrtc_bp.route("/webrtc/cleanup", methods=["POST"])
+def webrtc_cleanup():
+    async def _close_all():
+        for pc in list(pcs):
+            try:
+                await pc.close()
+            finally:
+                pcs.discard(pc)
+    run_coro(_close_all())
+    print("[CLEANUP] closed all RTCPeerConnections", flush=True)
+    return jsonify({"ok": True})
+
+@webrtc_bp.route("/proctor/last_warning")
+def proctor_last_warning():
+    student_id = request.args.get("student_id")
+    exam_id = request.args.get("exam_id")
+    if not student_id or not exam_id:
+        return jsonify(error="missing student_id or exam_id"), 400
+    return jsonify(last_warning.get((student_id, exam_id), {"warning": "Looking Forward", "at": 0}))
+
+@webrtc_bp.route("/proctor/last_capture")
+def proctor_last_capture():
+    student_id = request.args.get("student_id")
+    exam_id = request.args.get("exam_id")
+    if not student_id or not exam_id:
+        return jsonify(error="missing student_id or exam_id"), 400
+    return jsonify(last_capture.get((student_id, exam_id), {"label": None, "at": 0}))
+
+@webrtc_bp.route("/proctor/metrics")
+def proctor_metrics():
+    student_id = request.args.get("student_id")
+    exam_id = request.args.get("exam_id")
+    if not student_id or not exam_id:
+        return jsonify(error="missing student_id or exam_id"), 400
+    return jsonify(last_metrics.get((student_id, exam_id), {}))

runtime.txt

@@ -0,0 +1 @@
+python-3.10.13

services/behavior_service.py

@@ -0,0 +1,59 @@
+# services/behavior_service.py
+from database.connection import get_db_connection
+import threading
+
+def save_behavior_log(user_id: int, exam_id: int, image_base64: str, warning_type: str):
+    """Persist a behavior log. Returns inserted row id when available."""
+    conn = get_db_connection()
+    cur = None
+    try:
+        cur = conn.cursor()
+        row_id = None
+        try:
+            # Postgres path (supports RETURNING)
+            cur.execute(
+                """
+                INSERT INTO suspicious_behavior_logs (user_id, exam_id, image_base64, warning_type)
+                VALUES (%s, %s, %s, %s)
+                RETURNING id
+                """,
+                (user_id, exam_id, image_base64, warning_type),
+            )
+            row = cur.fetchone()
+            if row:
+                row_id = row[0]
+        except Exception:
+            # Fallback for MySQL/MariaDB (no RETURNING)
+            cur.execute(
+                """
+                INSERT INTO suspicious_behavior_logs (user_id, exam_id, image_base64, warning_type)
+                VALUES (%s, %s, %s, %s)
+                """,
+                (user_id, exam_id, image_base64, warning_type),
+            )
+            try:
+                row_id = getattr(cur, "lastrowid", None)
+            except Exception:
+                row_id = None
+
+        conn.commit()
+        return row_id
+    except Exception:
+        conn.rollback()
+        raise
+    finally:
+        try:
+            cur.close()
+        except Exception:
+            pass
+        conn.close()
+
+def save_behavior_log_async(user_id: int, exam_id: int, image_base64: str, warning_type: str, on_error=None):
+    """Fire-and-forget background insert so the WebRTC loop never blocks."""
+    def _worker():
+        try:
+            save_behavior_log(user_id, exam_id, image_base64, warning_type)
+        except Exception as e:
+            if on_error:
+                on_error(e)
+    threading.Thread(target=_worker, daemon=True).start()

services/instructor_services.py

@@ -0,0 +1,93 @@
+# services/instructor_service.py increment if the suspicous capture 
+from database.connection import get_db_connection
+import threading
+import sys
+
+def _find_instructor_id_for_student(conn, student_id: int):
+    """
+    Return an instructor_id for this student.
+    Adjust the query if your schema is different (e.g., join to exams).
+    """
+    cur = conn.cursor()
+    try:
+        # If you can have multiple assignments, pick the latest.
+        cur.execute(
+            """
+            SELECT instructor_id
+            FROM instructor_assignments
+            WHERE student_id = %s
+            ORDER BY id DESC
+            LIMIT 1
+            """,
+            (student_id,),
+        )
+        row = cur.fetchone()
+        return row[0] if row else None
+    finally:
+        cur.close()
+
+def increment_suspicious(student_id: int, instructor_id: int) -> int:
+    """Direct bump: requires instructor_id; returns affected rows."""
+    conn = get_db_connection()
+    cur = None
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            """
+            UPDATE instructor_assignments
+            SET suspicious_behavior_count = suspicious_behavior_count + 1
+            WHERE student_id = %s AND instructor_id = %s
+            """,
+            (student_id, instructor_id),
+        )
+        conn.commit()
+        return cur.rowcount
+    except Exception:
+        try: conn.rollback()
+        except Exception: pass
+        raise
+    finally:
+        try: cur.close()
+        except Exception: pass
+        conn.close()
+
+def increment_suspicious_for_student(student_id: int) -> int:
+    """
+    Convenience: look up instructor_id for the student and bump the count.
+    Returns affected rows (0 if no assignment found).
+    """
+    conn = get_db_connection()
+    cur = None
+    try:
+        iid = _find_instructor_id_for_student(conn, student_id)
+        if iid is None:
+            return 0
+        cur = conn.cursor()
+        cur.execute(
+            """
+            UPDATE instructor_assignments
+            SET suspicious_behavior_count = suspicious_behavior_count + 1
+            WHERE student_id = %s AND instructor_id = %s
+            """,
+            (student_id, iid),
+        )
+        conn.commit()
+        return cur.rowcount
+    except Exception:
+        try: conn.rollback()
+        except Exception: pass
+        raise
+    finally:
+        try: cur.close()
+        except Exception: pass
+        conn.close()
+
+def increment_suspicious_for_student_async(student_id: int, on_error=None):
+    """Fire-and-forget background increment."""
+    def _worker():
+        try:
+            increment_suspicious_for_student(student_id)
+        except Exception as e:
+            if on_error: on_error(e)
+            else: print(f"[INCR_SUSPICIOUS_ERR] {e}", file=sys.stderr, flush=True)
+    threading.Thread(target=_worker, daemon=True).start()