How varad2343/proctor-lens- works
ProctorLens turns webcam or video input into timestamped, explainable observations, not judgments. Its principal workflow is capture or replay → per-frame perception and quality checks → 10 Hz feature rows → temporal scores and event state machines → persisted events and review materials. The same pipeline is exposed through CLI commands and a local candidate/proctor web app; separate data, training, and evaluation modules support the ML lifecycle. Edges reflect README statements and SOURCE INDEX references; unsampled modules are represented only where the tree and documented capabilities support them.
Main entry points: __init__.py Frame perception · extractor.py Feature extraction · cli.py CLI commands · app.py HTTP and live sessions
Components 30
Pipeline runtime
- CLI commands
src/proctorlens/cli.py - Gaze calibration
src/proctorlens/pipeline/calibration.py - Frame perception
src/proctorlens/perception/__init__.py - Face landmarks
src/proctorlens/perception/landmarks.py - Gaze estimation
src/proctorlens/perception/gaze.py - Object detection
src/proctorlens/perception/objects.py - Identity checks
src/proctorlens/perception/identity.py - Observation quality
src/proctorlens/perception/quality.py - Feature extraction
src/proctorlens/features/extractor.py - Feature schema
src/proctorlens/features/schema.py - Temporal scoring
src/proctorlens/temporal/scores_learned.py - Event state machines
src/proctorlens/temporal/state_machine.py - Feature and event files
src/proctorlens/io.py
Review and reporting
- Reports and evidence
src/proctorlens/explain/report.py - Review segments
src/proctorlens/explain/review.py
Local web app
- HTTP and live sessions
src/proctorlens/server/app.py - Session database
src/proctorlens/server/db.py - Live processing
src/proctorlens/server/live.py - Candidate exam page
frontend/src/Candidate.tsx - Proctor dashboard
frontend/src/Proctor.tsx - Review interface
frontend/src/Review.tsx - Web API and stream
frontend/src/lib.ts
ML lifecycle
- Dataset labels
ml/data/labels.py - Dataset manifest
ml/data/build_manifest.py - Model training
ml/training/train_temporal_gbm.py - Identity calibration
ml/training/calibrate_identity.py - Model evaluation
ml/evaluation/run_eval.py
Other components
- Operator
- Candidate
- Video or camera
Connections 34
- Operator → CLI commands: runs commands
- Video or camera → CLI commands: provides input
- CLI commands → Gaze calibration: starts calibration
src/proctorlens/cli.py - Gaze calibration → Gaze estimation: fits calibration
src/proctorlens/pipeline/calibration.py - CLI commands → Frame perception: configures perception
src/proctorlens/cli.py - Frame perception → Face landmarks: detects faces
src/proctorlens/perception/__init__.py - Frame perception → Object detection: detects objects
src/proctorlens/perception/__init__.py - Frame perception → Identity checks: checks identity
src/proctorlens/perception/__init__.py - Frame perception → Observation quality: assesses quality
src/proctorlens/perception/__init__.py - Feature extraction → Gaze estimation: uses gaze signals
src/proctorlens/features/extractor.py - Feature extraction → Feature schema: builds rows
src/proctorlens/features/extractor.py - Video or camera → Frame perception: frames enter
- Frame perception → Feature extraction: produces observations
- Feature extraction → Temporal scoring: scores rows
- Temporal scoring → Event state machines: feeds scores
- Event state machines → Feature and event files: writes events
- Feature extraction → Feature and event files: writes features
- CLI commands → Reports and evidence: generates reports
src/proctorlens/cli.py - Reports and evidence → Review segments: groups events
src/proctorlens/explain/report.py - Reports and evidence → Feature and event files: loads event data
src/proctorlens/explain/report.py - Operator → HTTP and live sessions: reviews sessions
- Candidate → Candidate exam page: uses exam page
- Candidate exam page → Web API and stream: streams frames
frontend/src/Candidate.tsx - Proctor dashboard → Web API and stream: calls API
frontend/src/Proctor.tsx - Review interface → Web API and stream: calls API
frontend/src/Review.tsx - HTTP and live sessions → Session database: stores sessions
src/proctorlens/server/app.py - HTTP and live sessions → Live processing: routes live work
src/proctorlens/server/app.py - HTTP and live sessions → Frame perception: configures perception
src/proctorlens/server/app.py - Dataset manifest → Dataset labels: uses label loaders
ml/data/build_manifest.py - Model training → Dataset labels: loads labels
ml/training/train_temporal_gbm.py - Model training → Feature schema: uses feature schema
ml/training/train_temporal_gbm.py - Identity calibration → Identity checks: calibrates thresholds
ml/training/calibrate_identity.py - Model evaluation → Dataset labels: loads ground truth
ml/evaluation/run_eval.py - Model evaluation → Feature and event files: reads pipeline outputs
ml/evaluation/run_eval.py