akpranav1/liveness_check

Purpose and Entry Points

Real-time exam proctoring service for identity continuity and liveness/replay detection. The FastAPI application in main.py exposes session, baseline, frame, challenge, reporting, and history endpoints. Clients are the browser UI at static/index.html and a headless OpenCV runner at test_harness/run_short_test.py.

Session Lifecycle and API Boundary

main.py owns HTTP/form-data handling, JPEG decoding, in-memory session monitor instances, analyzer caching, error-to-inconclusive handling, and persistence calls. A session is created, baseline images are submitted, frames are streamed, optional challenges are issued/evaluated, then the session is ended and queried. The API boundary returns JSON outcomes and newly raised flags; raw image processing stays server-side.

Paths: main.py, static/index.html, test_harness/run_short_test.py.

Face Analysis Abstraction

face_analyzer.py defines the shared face-analysis contract and DetectedFace result: bounding box, embedding, pose, and detection confidence. InsightFaceAnalyzer is the intended production backend (InsightFace/ONNX Runtime, model download on first use); MockFaceAnalyzer is an offline smoke-test backend using OpenCV detection and texture descriptors. Both feed the same downstream identity logic, allowing runtime model selection without changing monitor code.

Paths: face_analyzer.py, main.py, requirements.txt.

Identity Continuity Pillar

exam_identity_monitor.py builds a baseline embedding from valid baseline frames, estimates device noise, and evaluates each frame as match, mismatch, or inconclusive. It gates extreme pose, applies pose- and device-noise-adjusted mismatch thresholds, and only admits clear match/mismatch evidence into its rolling window. Identity flags arise from sustained mismatch ratio or consecutive mismatches, never a single frame.

Paths: exam_identity_monitor.py, face_analyzer.py, config.py.

Liveness and Active Challenges

liveness_monitor.py combines independent replay signals: low face-crop motion for static photos, perceptual-hash periodicity for loops, FFT high-frequency/moiré scoring for screen recapture, and active raise-hand/head-turn challenges. Suspicious liveness evidence is fused with OR semantics and then debounced through a rolling window. Challenge failure/no response produces a separate flag; head-turn evaluation depends on real pose output, while hand raise uses optional MediaPipe.

Paths: liveness_monitor.py, exam_identity_monitor.py, config.py.

Composition and Frame Flow

FullExamSessionMonitor in session_monitor.py composes the identity monitor with the liveness mixin. Per submitted frame: decode at API layer; analyze face once; classify identity; update identity evidence; reuse detected face bounds/count for liveness checks when exactly one valid face exists; append resulting flags; return the result. No-face and multi-face frames are inconclusive for identity and skip liveness face analysis, avoiding ambiguous evidence and duplicate detection.

Paths: session_monitor.py, exam_identity_monitor.py, liveness_monitor.py.

Persistence, Configuration, and Deployment Constraints

database.py persists SQLite session metadata, per-frame outcomes, flags, and challenge events; it is a single-server/local-file persistence boundary rather than distributed infrastructure. config.py centralizes production and compressed test profiles for windows, thresholds, timing, and challenge behavior. Runtime dependencies are Python/FastAPI/Uvicorn, OpenCV/Numpy, SQLite stdlib, and optionally InsightFace, ONNX Runtime, and MediaPipe; model acquisition may require external network access.

Paths: database.py, config.py, requirements.txt.