Metadata-Version: 2.1
Name: proctor_audit
Version: 0.1.5
Summary: An AI-powered proctoring service for examinations
Home-page: https://github.com/yourusername/proctor_audit
Author: KeerthiKeswaran
Author-email: keshwarankeerthi@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <=3.12
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: mediapipe
Requires-Dist: asyncpg
Requires-Dist: python-dotenv

# Proctor-Audit

## Overview

**Proctor-Audit** is a real-time AI-powered proctoring tool designed to ensure the integrity of online assessments. This system utilizes facial landmark detection, eye tracking, and anomaly detection techniques to continuously monitor candidates during an online exam session. By analyzing facial movements, pupil direction, and overall behavior, **Proctor-Audit** can detect potential fraudulent activities such as looking away from the screen, multiple people in the frame, or excessive facial movement.

This package is designed to be implemented seamlessly in any Python-based backend using WebSockets for continuous video stream processing. It is capable of handling real-time detection, sending anomaly alerts, and providing insightful reports on suspicious behavior.

## Features

- **Continuous Face Tracking**: Monitors facial landmarks and movement in real time.
- **Eye Aspect Ratio (EAR) Calculation**: Detects blinking patterns and potential eye movement anomalies.
- **Pupil Tracking & Movement Analysis**: Identifies unusual gaze behavior to detect possible cheating.
- **Multiple Face Detection**: Detects if more than one person appears in the frame.
- **Real-time Anomaly Reporting**: Flags any unusual activity during the exam session.
- **WebSocket-Based Communication**: Ensures seamless integration into any Python-based backend for live proctoring.

## Installation

To install **Proctor-Audit**, use the following command:

```sh
pip install proctor-audit
```

> **Note:** This package is not currently uploaded to the Python Package Index (PyPI). To use it, clone the repository and install it manually.

## Usage

Once installed, **Proctor-Audit** can be integrated into your backend. It provides WebSocket-based endpoints to handle real-time proctoring.

### **1. Authentication Endpoint (`get_auth`)**

The `get_auth` function is responsible for managing authentication when connecting to the WebSocket. 
*(You can get the API_KEY from the api-docs-proctor-audit site)*

#### **Functionality:**
- Generates a secure session token.
- Ensures that only authorized users can access the proctoring service.
- Validates user identity before allowing a WebSocket connection.

**How It Works:**
1. A user initiates an authentication request before starting the exam session.
2. The function verifies the credentials and issues a token.
3. This token is then used to establish a secure WebSocket connection for real-time monitoring.

**Example Workflow:**
```python
from proctor_audit import get_auth

auth_token = get_auth(key="YOUR_API_KEY")
print(auth_token)  # Secure token for WebSocket connection
```

---

### **2. Real-Time Proctoring (`detect_frame`)**

The `detect_frame` function is the core of **Proctor-Audit**. It processes each video frame received via WebSocket and performs real-time analysis to detect anomalies.

#### **Functionality:**
- Decodes base64-encoded video frames.
- Uses **MediaPipe Face Mesh** to analyze facial landmarks.
- Calculates **Eye Aspect Ratio (EAR)** to monitor eye openness.
- Tracks **pupil movement** to detect unusual gaze patterns.
- Compares **current face position with previous frames** to detect excessive movement.
- Identifies **multiple faces in the frame** to flag unauthorized participants.
- Sends a response back via WebSocket indicating whether an anomaly was detected.

**How It Works:**
1. The client captures video frames from the candidateâ€™s webcam and sends them via WebSocket.
2. The `detect_frame` function receives the frame, decodes it, and processes the image.
3. It extracts key facial features and calculates metrics like EAR and pupil movement.
4. Based on these calculations, it determines whether any anomalies are present.
5. A response is sent back to the client, including the anomaly status and an alert if necessary.

**Example WebSocket Response:**
```json
{
    "anomaly": true,
    "pupil_movement_status": "unusual",
    "frame": "base64-encoded-image"
}
```

#### **Detection Logic in Detail:**

- **Eye Aspect Ratio (EAR) Calculation:**
    - A low EAR value indicates that the userâ€™s eyes are closed for an extended period (possible drowsiness or intentional cheating attempt).
    - If EAR drops below `0.18`, it is flagged as an anomaly.

- **Pupil Movement Tracking:**
    - If the pupil movement is minimal (`avg_movement < 0.002`), it means the candidate is looking straight.
    - If movement is between `0.002 - 0.008`, it is considered normal.
    - If movement exceeds `0.008`, the system flags it as unusual gaze behavior.

- **Face Movement Analysis:**
    - Detects the movement of the entire face compared to previous frames.
    - If excessive movement is detected beyond a threshold (`0.05` distance), it is flagged.

- **Multiple Face Detection:**
    - If more than one face appears in the frame, an anomaly is reported.

---

## WebSocket Integration

To integrate **Proctor-Audit** into your backend, establish a WebSocket connection and continuously send video frames.

**Client-Side WebSocket Example:**
```javascript
const socket = new WebSocket("wss://your-backend-server/ws");

socket.onopen = function() {
    console.log("WebSocket connected");
    startStreaming();  // Function to capture and send frames
};

socket.onmessage = function(event) {
    const response = JSON.parse(event.data);
    if (response.anomaly) {
        alert("Anomaly detected: " + response.pupil_movement_status);
    }
};

socket.onerror = function(error) {
    console.error("WebSocket error:", error);
};
```

---

## Advantages of Proctor-Audit

- **Non-Intrusive Monitoring**: Does not require installing any additional software.
- **Real-Time Analysis**: Provides instant feedback on any anomalies detected.
- **Scalable Solution**: Can handle multiple exam sessions simultaneously.
- **Minimal Latency**: Optimized for real-time detection without lag.
- **Highly Secure**: Authentication and encrypted WebSocket communication.

---

## Future Enhancements

The following improvements are planned for upcoming versions:
- **Voice Detection**: Detect and flag conversations during the exam.
- **Head Pose Estimation**: More advanced 3D head tracking.
- **Cheating Score Metric**: Assign a confidence score for suspected cheating.
- **Browser Activity Monitoring**: Detect switching tabs or accessing unauthorized materials.

---

## Conclusion

**Proctor-Audit** is a powerful AI-driven proctoring solution that ensures online assessment integrity through real-time monitoring and anomaly detection. Designed for seamless integration into Python-based backends, it provides a non-intrusive and scalable way to maintain exam fairness. 

Start integrating **Proctor-Audit** today and take your online assessments to the next level! ðŸš€
