📌 Executive Summary

Large-scale written and computer-based examinations face severe integrity vulnerabilities: subtle paper chit exchanges, concealed micro-electronics (smart watches, earphones, cell phones), coordinated copying networks, and invigilator collusion. Manual invigilation and passive CCTV review suffer from human fatigue, blind spots, and lack of verifiable proof.

SAAKSHI (साक्ष्य) is an enterprise-grade, privacy-preserving video forensics system built specifically for offline examination halls. Operating strictly on-premises without cloud dependencies, SAAKSHI transforms passive CCTV streams into mathematical proof:

1. Zero Biometrics / No Faces: Operates purely on posture geometry, spatial interaction graphs, and optical flow anomalies.
2. Mathematically Calibrated Evidence: Controls False Discovery Rates ($q \le 0.05$) via Benjamini-Hochberg and Extreme Value Theory (EVT) conformal scoring.
3. Multi-Tiered Explainable AI: Combines Huber-loss common mode rejection, SAHI-tiled RF-DETR object detection, and SmolVLM multimodal visual reasoning.
4. End-to-End Forensic Workstation: Complete suite featuring Review Console, Incident Ticketing, Bookmark Library, Floorplan Hall View, and Hash-Chained Chain of Custody Export.

---

🏛️ System Architecture

                                  [ CCTV FOOTAGE (MP4 / AVI / H.264 / HEVC) ]
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                   STAGE 1: DAY-0 VIDEO PROFILER                                           │
 │   • Hardware/Software Decoder Routing     • True FPS vs Container Extraction   • MB Noise-Floor Calibration│
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                STAGE 2: AUTOMATIC SEATMAP DISCOVERY                                       │
 │   • Temporal Persistence Discovery        • Watershed / Voronoi Splitting      • Contested Space Fraction │
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                STAGE 3: MULTI-CHANNEL MOTION PASS                                         │
 │   • DIS Dense Optical Flow                • Global Camera Motion Subtraction   • Native-FPS Cascade       │
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                           STAGE 4: STATISTICAL EVIDENCE CORE & FDR CONTROL                                │
 │   • Huber Common-Mode Nuisance Rejection  • Conformal EVT Tail Scoring         • PELT Segmentation       │
 │   • Benjamini–Hochberg FDR ($q \le 0.05$) • Exchange Graph Permutation Test    • Staff Lookback (2.0 Hz)  │
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                            STAGE 5: DEEP MULTIMODAL AI VERIFICATION                                       │
 │   • RF-DETR + SAHI Micro-Object Detection • Static Background Suppression      • SmolVLM Visual Reasoning │
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                       │
                                                       ▼
 ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                          STAGE 6: FORENSIC CONSOLE & CASE MANAGEMENT                                      │
 │   • Review Console & Annotations          • Incident Ticketing (SAAK-n)        • Persistent Bookmarks     │
 │   • Interactive Hall & Seat Heatmaps      • Timeline & Lookback Player         • Hash-Chained PDF Export  │
 └───────────────────────────────────────────────────────────────────────────────────────────────────────────┘

---

📸 Screenshots

---

🚀 Key Features

🔬 1. AI & Statistical Pipeline

• Common-Mode Rejection (CMR): Eliminates false alerts from room-wide lighting shifts, camera vibrations, and synchronized bell rings using robust Huber regression.
• Conformal P-Values & EVT: Replaces arbitrary confidence scores with statistically rigorous p-values extrapolated via Generalized Pareto Distribution (GPD).
• Exchange Graph Analysis: Circular time-shift permutation tests over adjacent seats to mathematically prove synchronized illicit sharing vs. independent motion.
• Retrospective Staff Lookback: Tracks invigilators at 2.0 Hz native resolution and traces candidate anomalies occurring prior to staff approach.
• SAHI + RF-DETR High-Res Detection: High-resolution cropped object re-scan targeting small contraband (chits, phones, earphones).
• SmolVLM Forensic Explanations: Vision-language multimodal synthesis producing natural language reasoning justifying every flagged frame.

🖥️ 2. Comprehensive Forensic Workstation (Frontend)

• Review Console (/console):
  • Live synchronized SVG annotation overlay (seat polygon + ROI bounding box).
  • Four-tier explainability stack: statistical p/q values, RF-DETR evidence, high-res crop re-scan, and SmolVLM reasoning.
  • One-click Accept / Reject adjudication.
  • Integrated one-click Bookmark and Escalate to Ticket triggers.
• Incident Ticketing System (/tickets):
  • Full-lifecycle ticket management (SAAK-1, SAAK-2, etc.) with state machine transitions (OPEN → IN_REVIEW → RESOLVED → CLOSED).
  • Priority management (P1 Critical, P2 High, P3 Medium, P4 Low).
  • Immutable activity audit log with timestamps, operator identity, comments, and status transitions.
  • Fast search, multi-dropdown filtering, and cross-navigation back to Console.
• Frame Bookmark Library (/bookmarks):
  • Freeze complete evidence snapshots into persistent storage with zero backend dependency.
  • Snapshot honesty guarantee: preserves unreturned analysis states accurately without false negatives.
  • Ambiguity taxonomy tagging (UNCLEAR OBJECT, OCCLUDED, LOW CONFIDENCE, 2ND OPINION).
  • Stale-frame resilience with automated backend re-extraction.
• Interactive Hall View (/hall):
  • Top-down 2D floorplan showing seat occupancy, contested boundary fractions, anomaly heatmaps, and staff trajectories.
• Chronological Timeline (/timeline):
  • Continuous per-seat anomaly ribbons, room-wide activity traces $c(t)$, and interactive brush/zoom exploration.
• Priority Triage Queue (/queue):
  • Ranked incident queue with dynamic budget dial to optimize reviewer time.
• Chain of Custody & PDF Export (/export):
  • Generates tamper-evident audit manifests with SHA-256 verification and GOP-aligned video evidence clips.

---

🛠️ Technology Stack

---

⚡ Quick Start & Installation

Prerequisites

• Python 3.11+ and uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• Node.js 18+ and npm

1. Clone the Repository

git clone https://github.com/Nikshaan/CBT_cheating_detector.git
cd CBT_cheating_detector

2. Start the Backend API Server

cd backend
uv sync
uv run python tools/serve_api.py

The SAAKSHI Bridge API will initialize at http://127.0.0.1:8787.

3. Start the Frontend Forensic Workstation

In a new terminal:

cd frontend
npm install
npm run dev

Access the web application at http://localhost:5173 (or http://localhost:5175).

---

💻 Running the Headless CLI Pipeline

To run the complete 6-stage forensics analysis directly on raw exam hall footage from the CLI:

cd backend
uv run python -m saakshi run /path/to/exam_hall_cctv.mp4 --out-dir reports/cases

Key CLI Flags

• --out-dir: Directory for consolidated case JSON and evidence frames (default: reports/cases).
• --n-samples: Number of frames sampled for seatmap discovery (default: 200).
• --no-intervention: Skip invigilator tracking pass for faster processing.
• --no-vlm: Run RF-DETR object detection while skipping the heavier SmolVLM pass.
• --k-budget: Cap candidate windows evaluated in Stage 4 (default: 200).

---

🔒 Privacy, Security & Legal Compliance

• No Face Recognition / No Biometrics: SAAKSHI strictly forbids face recognition, emotion recognition, or demographic profiling. All tracking is anonymized and spatial.
• Air-Gapped & On-Premises: Video streams and model weights remain entirely on local hardware; zero frames are ever transmitted over external networks.
• Tamper-Evident Hash Chaining: Case artifacts and reviewer decisions are logged in an append-only, SHA-256 hash-chained manifest to ensure legal admissibility in academic disciplinary hearings.
• DPDP Act Compliant: Supports automatic retention schedules and auto-erase policies.