Skip to main content

ProctorTelemetry Logo

ProctorTelemetry

Lightweight Multimodal Behavioral Telemetry & Test-Taking Work Behavior Fusion Engine

PyPI version GitHub Stars Python 3.9+ License: MIT Tests Zero Dependencies Sub-millisecond Latency

English | Bahasa Indonesia


Overview

ProctorTelemetry is an open-source, privacy-preserving, zero-dependency Python library engineered for academic integrity verification in online assessments and computer-based testing (CBT).

Rather than relying on intrusive video/audio surveillance, ProctorTelemetry performs multimodal behavioral fusion by correlating two primary pillars of student interaction:

  1. Browser Telemetry ($x_f$): Window focus loss episodes, tab background visibility, and hidden duration.
  2. Test-Taking Work Behavior ($x_w$): Item response time distributions, question navigation patterns, and post-blur answer revisions.
  3. Typing Rhythm & Dynamics ($x_k$): Keystroke dwell duration, flight times, interkey intervals, and backspace rates.
  4. Pointer Spatial Entropy ($x_h$): Spatial interaction density and Shannon entropy across UI zones.

By fusing browser telemetry with work behavior, the engine reliably identifies subtle cheating signatures (e.g. switching tabs to consult external resources and returning to revise answers, or mass-submitting answers within milliseconds after prolonged background hidden states).


Key Highlights

  • Zero External Dependencies: Implemented entirely with Python standard libraries (math, time, typing). No NumPy, SciPy, PyTorch, or compiler dependencies.
  • Sub-millisecond Inference: Feature extraction and all multi-model evaluations run in < 1.0 ms per session, easily handling tens of thousands of concurrent examinees.
  • Cross-Modal Correlative Anomaly Detection: Detects temporal correlations between browser focus loss and answer revisions.
  • Privacy-First Design: Never records keystroke text, clipboard contents, webcam feeds, or audio. Only statistical timing differentials and normalized coordinate distributions are evaluated.
  • Comprehensive Ablation Suite: Outputs isolated and fused sub-scores for detailed academic evaluation and model transparency.

Architecture Pipeline

flowchart TD
    subgraph Client ["Client-Side Telemetry Collection"]
        A1["Browser Events (Focus Loss, Tab Hidden Duration)"]
        A2["Work Behavior (Item Times, Navigation, Answer Changes)"]
        A3["Keystroke Timing (Dwell, Flight, Interkey)"]
        A4["Pointer Heatmap (Zonal Spatial Distribution)"]
    end

    subgraph Extraction ["Feature Extraction Engine"]
        B["extract_fusion_features"]
        C1["xf: Browser Telemetry (Focus Loss, Hidden Duration)"]
        C2["xw: Work Behavior (Response Time, Nav, Answer Revisions)"]
        C3["xk: Keystroke Dynamics (Dwell, Flight, Rhythm)"]
        C4["xh: Pointer Spatial Entropy (Shannon H, Zones)"]
    end

    subgraph Models ["Multimodal Inference Suite"]
        D1["XGBoost Ensemble Fusion Representation"]
        D2["1D-CNN Sequential Anomaly Model"]
        D3["Deterministic Heuristic Rule Checker"]
        D4["9-Way Ablation Permutation Suite"]
    end

    subgraph Output ["Standardized Output Vector"]
        E["Normalized Integrity Risk Scores (0.0 to 1.0)<br/>Transparent Inspection Context for Proctors"]
    end

    A1 --> B
    A2 --> B
    A3 --> B
    A4 --> B
    B --> C1
    B --> C2
    B --> C3
    B --> C4
    C1 --> D1
    C2 --> D1
    C3 --> D1
    C4 --> D1
    C1 --> D2
    C2 --> D2
    C3 --> D2
    C1 --> D3
    C2 --> D3
    C1 --> D4
    C2 --> D4
    C3 --> D4
    C4 --> D4
    D1 --> E
    D2 --> E
    D3 --> E
    D4 --> E

Extracted Multimodal Features (23-D Vector)

Modality Feature Key Mathematical Symbol Description
Browser Telemetry ($x_f$) focus_loss_episodes $N_{\text{blur}}$ Total browser tab / window defocus transitions
hidden_duration_ms $T_{\text{hidden}}$ Cumulative time spent outside the exam interface (ms)
hidden_duration_ratio $R_{\text{hidden}}$ Ratio of hidden time relative to total session duration
paste_count $N_{\text{paste}}$ Total clipboard paste occurrences
Work Behavior ($x_w$) answer_change_count $N_{\text{rev}}$ Frequency of answer choices revised after initial selection
answer_change_ratio $R_{\text{rev}}$ Proportion of attempted questions with revised answers
nav_switch_count $N_{\text{nav}}$ Total jumps across question navigation controls
mean_item_time_sec $T_{\text{item}}$ Average active response time allocated per question (sec)
rapid_answer_count $N_{\text{rapid}}$ Number of questions answered in under 2.5 seconds
rapid_answer_ratio $R_{\text{rapid}}$ Ratio of rapid answers relative to attempted questions
Keystroke ($x_k$) dwell_median_ms $\text{Med}(D)$ Median key press hold duration (ms)
dwell_iqr_ms $\text{IQR}(D)$ Interquartile range of dwell times
flight_median_ms $\text{Med}(F)$ Median time between releasing key $i$ and pressing key $i+1$
flight_iqr_ms $\text{IQR}(F)$ Variance/IQR of flight intervals
interkey_median_ms $\text{Med}(I)$ Median inter-keystroke interval
long_pause_ratio $R_{\text{pause}}$ Proportion of interkey pauses exceeding 1500 ms
backspace_ratio $R_{\text{bksp}}$ Frequency of backspace revisions relative to keystrokes
burst_input_ratio $R_{\text{burst}}$ Ratio of sudden bulk/paste typing bursts
typing_cpm $\text{CPM}$ Characters typed per active minute
Pointer ($x_h$) zone_passage_prop $q_{\text{passage}}$ Proportion of pointer interactions over stimulus/passage
zone_answer_prop $q_{\text{answer}}$ Proportion of pointer interactions over answer choices
zone_nav_prop $q_{\text{nav}}$ Proportion of pointer interactions over navigation controls
spatial_entropy_H $H(X)$ Shannon entropy across zones: $-\sum q_i \log_2(q_i)$
total_pointer_events $N_{\text{pointer}}$ Sampled coordinate interaction volume

Installation

From PyPI

pip install proctor-telemetry

From GitHub Repository

pip install git+https://github.com/firdausmntp/proctor_telemetry.git

Local Development / Editable Mode

git clone https://github.com/firdausmntp/proctor_telemetry.git
cd proctor_telemetry
pip install -e .

Quickstart

from proctor_telemetry import extract_features_and_predict

# 1. Telemetry payload captured by frontend client
session_telemetry = {
    # Browser Telemetry
    "focus_loss_episodes": 2,
    "hidden_duration_ms": 14500.0,
    "paste_count": 0,
    "duration_sec": 300.0,
    
    # Test-Taking Work Behavior
    "answer_change_count": 3,
    "nav_switch_count": 12,
    "item_response_times": [14.2, 18.0, 1.8, 1.9, 12.5],
    "total_questions_attempted": 20,

    # Keystroke Dynamics
    "dwell_times": [85.0, 92.0, 78.0, 110.0, 95.0, 88.0],
    "flight_times": [140.0, 120.0, 190.0, 130.0, 150.0],
    "interkey_times": [225.0, 212.0, 268.0, 240.0, 238.0],
    "total_keydowns": 240,
    "backspace_count": 14,
    "bulk_insert_count": 0,

    # Pointer Spatial Distribution
    "zone_counts": {
        "passage": 45,
        "answer": 80,
        "navigation": 15
    }
}

# 2. Execute feature extraction & multimodal evaluation
features, ablation, xgb_score, cnn_score, rule_flag, latency_ms = extract_features_and_predict(session_telemetry)

# 3. Inspect results
print(f"XGBoost Multimodal Score : {xgb_score:.4f} (Range: 0.0 - 1.0)")
print(f"1D-CNN Sequential Score  : {cnn_score:.4f}")
print(f"Rule Flag (Deterministic): {'FLAGGED' if rule_flag else 'CLEAN'}")
print(f"Telemetry-Work Fusion    : {ablation['telemetry_work_fusion']:.4f}")
print(f"Inference Latency        : {latency_ms:.2f} ms")

Advanced Usage: Feature Ablation Analysis

The library outputs 9 distinct ablation configurations to examine isolated and fused contributions:

for modality, score in ablation.items():
    print(f"Subset [{modality:<22}]: Risk Score = {score:.4f}")

Example Output:

Subset [keystroke_only        ]: Risk Score = 0.1611
Subset [focus_only            ]: Risk Score = 0.2142
Subset [heatmap_only          ]: Risk Score = 0.2315
Subset [work_behavior_only    ]: Risk Score = 0.2840
Subset [telemetry_work_fusion ]: Risk Score = 0.4215
Subset [keystroke_focus       ]: Risk Score = 0.2458
Subset [keystroke_heatmap     ]: Risk Score = 0.2589
Subset [focus_heatmap         ]: Risk Score = 0.2641
Subset [full_fusion_xgboost   ]: Risk Score = 0.3892

Web Framework Integration

FastAPI Microservice Example

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Dict, Any
from proctor_telemetry import extract_features_and_predict

app = FastAPI(title="Proctor Telemetry API")

class TelemetryPayload(BaseModel):
    focus_loss_episodes: int = 0
    hidden_duration_ms: float = 0.0
    paste_count: int = 0
    duration_sec: float = 60.0
    answer_change_count: int = 0
    nav_switch_count: int = 0
    item_response_times: List[float] = []
    dwell_times: List[float] = []
    flight_times: List[float] = []
    interkey_times: List[float] = []
    total_keydowns: int = 0
    backspace_count: int = 0
    bulk_insert_count: int = 0
    zone_counts: Dict[str, int] = {}

@app.post("/verify")
def verify_telemetry(payload: TelemetryPayload):
    features, ablation, xgb_score, cnn_score, rule_flag, latency = extract_features_and_predict(payload.dict())
    return {
        "status": "success",
        "scores": {
            "xgboost": xgb_score,
            "cnn1d": cnn_score,
            "rule_flag": bool(rule_flag)
        },
        "ablation": ablation,
        "features": features,
        "latency_ms": latency
    }

Unit Testing

Run the built-in test suite:

python -m unittest discover -s tests

Academic Citation

If you use this library or its multimodal telemetry and work behavior fusion methodology in academic papers, undergraduate theses, or research publications, please cite:

@software{utomo2026proctortelemetry,
  author = {Utomo, Firdaus Satrio and LinguaPulse Research Team},
  title = {ProctorTelemetry: Lightweight Multimodal Behavioral Telemetry & Test-Taking Work Behavior Fusion Engine},
  year = {2026},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/firdausmntp/proctor_telemetry}}
}

License

This project is licensed under the MIT License - free to use in academic, commercial, or personal software.

Metadata

Release files for proctor-telemetry 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for proctor-telemetry 0.2.0
File Size Uploaded Provenance Actions
proctor_telemetry-0.2.0.tar.gz 17.0 kB Without provenance Details for proctor_telemetry-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for proctor-telemetry 0.2.0
File Interpreter ABI Platform Actions
proctor_telemetry-0.2.0-py3-none-any.whl Python 3 none any Details for proctor_telemetry-0.2.0-py3-none-any.whl

Total release size: 29.4 kB

Release files / proctor_telemetry-0.2.0.tar.gz

Download URL proctor_telemetry-0.2.0.tar.gz
Size 17.0 kB
Tags Source
SHA-256 checksum
How to use checksums
ccb96dc6a0bd1405dd15ed98ccb08cd62b866acdb947af19333eb832ffa47e9e
BLAKE2b-256 checksum
How to use checksums
70bdd4930c6450b71e95ffa1dbbc48ebb8530fef80764a1c6468cff7e31090af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Release files / proctor_telemetry-0.2.0-py3-none-any.whl

Download URL proctor_telemetry-0.2.0-py3-none-any.whl
Size 12.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6746616872a6a01487c0b08952d13be2ed499bcc58d9b8a5a7699dcfe5650a17
BLAKE2b-256 checksum
How to use checksums
717b7f7912bf6238f809e39ca7f8b62e5fb350823a7b9888973c7f0f48cf2270
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.3

Security for proctor-telemetry 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page