initial: stateless architecture with automated model downloads

.env.template

@@ -0,0 +1,26 @@
+# App Configuration
+APP_NAME="Examify AI Services"
+APP_ENV="development"
+DEBUG=true
+API_V1_STR="/api/v1"
+
+# Security
+SECRET_KEY="your-super-secret-key-here"
+ACCESS_TOKEN_EXPIRE_MINUTES=11520
+
+# AI Providers
+GROQ_API_KEY="gsk_..."
+GEMINI_API_KEY="..."
+OPENAI_API_KEY="sk-..."
+
+# Models
+DEFAULT_CHAT_MODEL="llama-3-70b-8192"
+DEFAULT_EXAM_MODEL="gemini-1.5-pro-latest"
+
+# Logging
+LOG_LEVEL="INFO"
+
+# Proctoring Configuration
+FACE_VERIFY_THRESHOLD=0.80
+OBJECT_DETECTION_CONFIDENCE=0.50
+MAX_IMAGE_SIZE_MB=5

.gitignore

@@ -0,0 +1,40 @@
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Pytest / Coverage
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+
+# Huggingface/DeepFace Weights & ONNX Models
+.deepface/
+*.h5
+*.onnx
+facenet_weights.h5
+openface_weights.h5
+vgg_face_weights.h5
+
+# Redundant backup folders (The ones causing issues)
+Ai Things/
+Examify_AI_Services/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

Dockerfile

@@ -0,0 +1,46 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# تنصيب مكتبات النظام الأساسية للتعامل مع الصور (OpenCV) وتحميل الملفات
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libgl1-mesa-glx \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# تنصيب الباكيدجات
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# إنشاء مستخدم Hugging Face القياسي (User ID 1000)
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user
+ENV PATH=/home/user/.local/bin:$PATH
+
+# تجهيز مجلدات الموديلات
+RUN mkdir -p /home/user/.deepface/weights \
+    && mkdir -p /app/app/ml_models
+
+# تحميل أوزان وموديلات الذكاء الاصطناعي (أثناء الـ Build عشان الـ Git يكون خفيف)
+# 1. Facenet Weights
+RUN wget -q -O /home/user/.deepface/weights/facenet_weights.h5 \
+    https://huggingface.co/junjiang/GestureFace/resolve/main/facenet_weights.h5
+
+# 2. Face Detection (YuNet)
+RUN wget -q -O /app/app/ml_models/face_detection_yunet.onnx \
+    https://github.com/opencv/opencv_zoo/raw/master/models/face_detection_yunet/face_detection_yunet_2023mar.onnx
+
+# 3. Object Detection (YOLOv8n)
+RUN wget -q -O /app/app/ml_models/yolov8n.onnx \
+    https://github.com/ultralytics/assets/releases/download/v8.2.0/yolov8n.onnx
+
+# نسخ الكود وإعطاء الصلاحيات للمستخدم الجديد
+COPY --chown=user:user . /app
+
+# السماح للـ API بالاستماع على بورت 7860 (Hugging Face Default)
+EXPOSE 7860
+
+# تشغيل السيرفر!
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,136 @@
+# Examify AI Services 🎓🤖
+
+**Examify AI Services** is a robust, modular, and production-ready **FastAPI** backend designed to power AI-driven educational and assessment platforms. 
+
+It provides advanced generative AI capabilities (for exam generation and intelligent tutoring) alongside state-of-the-art **AI Proctoring** utilizing Computer Vision and Deep Learning models entirely accessible via fast, stateless HTTP endpoints.
+
+---
+
+## 🌟 Key Features
+
+### 1. 👁️‍🗨️ Intelligent AI Proctoring (`/api/v1/proctoring`)
+A complete suite of tools to maintain exam integrity via webcam feed analysis:
+*   **Real-time Face Detection**: Powered by **YuNet (ONNX)**, instantly detects if a face is missing from the frame or if there are multiple faces.
+*   **Object & Violation Detection**: Powered by **YOLOv8n (ONNX)**, spots unauthorized items such as mobile phones, laptops, and books. It also detects if an extra person enters the frame.
+*   **Face Recognition (Identity Verification)**: Built on **DeepFace (FaceNet)**, registers the student's face before the exam (saving biometric embeddings physically as `.npy` files) and verifies their identity continuously during the exam via cosine similarity.
+*   **Combined Frame Analysis**: An all-in-one endpoint (`/analyze-frame`) that runs face detection, object detection, and identity verification in parallel, automatically calculating a `safe`, `warning`, or `critical` risk level for the analyzed frame.
+
+### 2. 📝 Exam Generation (`/api/v1/exams`)
+*   Generates customized quiz questions (Multiple Choice, True/False, Short Answer) from provided study material content using Generative AI (e.g., Gemini, Groq, OpenAI).
+
+### 3. 💬 AI Chat & Tutoring (`/api/v1/chat`)
+*   Provides both standard and streaming (SSE) conversational endpoints to power AI assistants and interactive student tutors.
+
+---
+
+## 🏗️ Project Architecture
+
+```plaintext
+Examify_AI_Services/
+├── app/
+│   ├── api/                  # FastAPI routers and endpoint definitions (chat, exams, proctoring)
+│   ├── core/                 # App configuration and logging (Pydantic Settings)
+│   ├── ml_artifacts/         # Stores student face embeddings (.npy) generated by DeepFace
+│   ├── ml_models/            # Local ONNX models (yolov8n.onnx, face_detection_yunet.onnx)
+│   ├── schemas/              # Pydantic validation models (Requests/Responses)
+│   ├── services/             # Core business logic and AI integration implementations
+│   └── utils/                # Helper tools like OpenCV base64 image decoding/encoding
+├── main.py                   # FastAPI application entry point & Lifespan loading
+├── .env.template             # Environment variables template
+├── Dockerfile                # Configured for Headless OpenCV execution
+└── requirements.txt          # Python dependencies
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+*   **Python 3.10+** installed on your system.
+*   Virtual Environment (Highly Recommended)
+
+### 1. Installation
+
+Clone the repository and install the required dependencies.
+
+```powershell
+# Create and activate a virtual environment
+python -m venv venv
+.\venv\Scripts\activate   # On Windows
+# source venv/bin/activate # On Mac/Linux
+
+# Install dependencies
+python -m pip install -r requirements.txt
+```
+
+### 2. Configuration
+
+Create a `.env` file in the root directory and copy the contents from `.env.template`. Adjust the keys based on your environment.
+
+```env
+# Example .env
+APP_NAME="Examify AI Services"
+DEBUG=true
+
+# AI Provider Keys (for Chat and Exams)
+GROQ_API_KEY="your_groq_key"
+GEMINI_API_KEY="your_gemini_key"
+OPENAI_API_KEY="your_openai_key"
+
+# Proctoring Configuration
+FACE_VERIFY_THRESHOLD=0.80
+OBJECT_DETECTION_CONFIDENCE=0.50
+```
+
+### 3. Running the Server
+
+Start the FastAPI application using Uvicorn:
+
+```powershell
+python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+You can now view the auto-generated interactive API documentation at:
+*   **Swagger UI:** [http://localhost:8000/docs](http://localhost:8000/docs)
+*   **ReDoc:** [http://localhost:8000/redoc](http://localhost:8000/redoc)
+
+---
+
+## 🎯 Important Proctoring Endpoints
+
+All proctoring endpoints expect the webcam images formatted as **Base64 strings**.
+
+*   `POST /api/v1/proctoring/register-face`
+    *   **Purpose:** Register a new student's face before the exam.
+    *   **Payload:** `{"student_id": "ST-101", "images": ["<base64_str>", "<base64_str>...", ...]}` (Recommend sending 5 poses)
+*   `POST /api/v1/proctoring/detect-face`
+    *   **Purpose:** Detect face presence and bounds.
+    *   **Payload:** `{"image": "<base64_str>"}`
+*   `POST /api/v1/proctoring/detect-objects`
+    *   **Purpose:** Scan for forbidden items.
+    *   **Payload:** `{"image": "<base64_str>", "detect_books": true}`
+*   `POST /api/v1/proctoring/verify-face`
+    *   **Purpose:** Match the current face against the registered student.
+    *   **Payload:** `{"student_id": "ST-101", "image": "<base64_str>"}`
+*   `POST /api/v1/proctoring/analyze-frame`
+    *   **Purpose:** All-in-one check for the exam frontend. Returns `risk_level: "safe" | "warning" | "critical"`.
+    *   **Payload:**
+        ```json
+        {
+          "student_id": "ST-101",
+          "image": "<base64_str>",
+          "detect_books": true,
+          "return_annotated": false
+        }
+        ```
+
+---
+
+## 🐳 Docker Deployment
+
+A `Dockerfile` is provided for containerized deployment. It is pre-configured with the necessary system libraries (`libglib2.0-0` and `libgl1-mesa-glx`) required by headless OpenCV.
+
+```bash
+docker build -t examify-ai-services .
+docker run -p 8000:8000 --env-file .env examify-ai-services
+```

app/api/chat.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+from app.schemas import ChatRequest, ChatResponse
+from app.services.chat_service import chat_service
+from loguru import logger
+
+router = APIRouter(prefix="/chat", tags=["AI Chat"])
+
+@router.post("/", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+    """General AI chat endpoint"""
+    try:
+        response = await chat_service.get_chat_response(request)
+        return response
+    except Exception as e:
+        logger.error(f"Chat error: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal AI service error")
+
+@router.post("/stream")
+async def chat_stream(request: ChatRequest):
+    """Streaming AI chat endpoint using SSE"""
+    try:
+        return StreamingResponse(
+            chat_service.stream_chat_response(request),
+            media_type="text/event-stream"
+        )
+    except Exception as e:
+        logger.error(f"Chat stream error: {str(e)}")
+        raise HTTPException(status_code=500, detail="Internal AI streaming error")

app/api/exams.py

@@ -0,0 +1,16 @@
+from fastapi import APIRouter, HTTPException
+from app.schemas import ExamGenerateRequest, ExamResponse
+from app.services.exam_service import exam_service
+from loguru import logger
+
+router = APIRouter(prefix="/exams", tags=["Exam Generation"])
+
+@router.post("/generate", response_model=ExamResponse)
+async def generate_exam(request: ExamGenerateRequest):
+    """Generate exam from content"""
+    try:
+        response = await exam_service.generate_exam(request)
+        return response
+    except Exception as e:
+        logger.error(f"Generate exam error: {str(e)}")
+        raise HTTPException(status_code=500, detail="Failed to generate exam")

app/api/proctoring.py

@@ -0,0 +1,236 @@
+import asyncio
+import json
+import time
+from typing import List, Optional
+from fastapi import APIRouter, HTTPException, UploadFile, File, Form
+from loguru import logger
+
+from app.schemas.proctoring import (
+    FaceDetectionResponse,
+    ObjectDetectionResponse,
+    FaceEmbeddingResponse,
+    FaceVerifyResponse,
+    ProctorFrameResponse
+)
+from app.services.face_detection_service import face_detection_service
+from app.services.object_detection_service import object_detection_service
+from app.services.face_recognition_service import face_recognition_service
+from app.utils.image_utils import decode_image_from_bytes, decode_base64_image
+
+router = APIRouter(prefix="/proctoring", tags=["AI Proctoring"])
+
+
+# ─────────────────────────────────────────────
+# Face Detection (مش متغير)
+# ─────────────────────────────────────────────
+
+@router.post("/detect-face", response_model=FaceDetectionResponse)
+async def detect_face(file: UploadFile = File(...)):
+    """Detect faces and return bounding box and cropped face"""
+    try:
+        contents = await file.read()
+        image = decode_image_from_bytes(contents)
+        return await face_detection_service.detect(image)
+    except ValueError as e:
+        logger.error(f"Invalid image format: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Face detection failed: {e}")
+        raise HTTPException(status_code=500, detail="Internal processing error")
+
+
+# ─────────────────────────────────────────────
+# Object Detection (مش متغير)
+# ─────────────────────────────────────────────
+
+@router.post("/detect-objects", response_model=ObjectDetectionResponse)
+async def detect_objects(
+    detect_books: bool = Form(True),
+    confidence_threshold: float = Form(0.50),
+    return_annotated: bool = Form(False),
+    file: UploadFile = File(...)
+):
+    """Detect objects/violations in the provided image file"""
+    try:
+        contents = await file.read()
+        image = decode_image_from_bytes(contents)
+        return await object_detection_service.detect(
+            image=image,
+            detect_books=detect_books,
+            conf_threshold=confidence_threshold,
+            return_annotated=return_annotated
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Object detection failed: {e}")
+        raise HTTPException(status_code=500, detail="Internal processing error")
+
+
+# ─────────────────────────────────────────────
+# Face Registration (Stateless - يرجع الـ Embedding للـ .NET)
+# ─────────────────────────────────────────────
+
+@router.post("/register-face", response_model=FaceEmbeddingResponse)
+async def register_face(
+    student_id: str = Form(...),
+    file: UploadFile = File(...)
+):
+    """
+    ## Register a Student's Face
+    
+    Extracts a 512-dimensional embedding array from the uploaded image.
+    
+    ### How it works with .NET:
+    1. Send a clear portrait image of the student's face.
+    2. The API calculates the `embedding` vector (a mathematical representation).
+    3. The `.NET API` must store this `embedding` array in **PostgreSQL** alongside the `student_id`.
+    4. **No data is stored locally by this service.**
+    """
+    try:
+        contents = await file.read()
+        image = decode_image_from_bytes(contents)
+            
+        return await face_recognition_service.register_student(
+            student_id=student_id,
+            face_images=[image]
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Face registration failed: {e}")
+        raise HTTPException(status_code=500, detail="Internal processing error")
+
+
+# ─────────────────────────────────────────────
+# Face Verification (Stateless - يستقبل الـ Embedding من الـ .NET)
+# ─────────────────────────────────────────────
+
+@router.post("/verify-face", response_model=FaceVerifyResponse)
+async def verify_face(
+    student_id: str = Form(...),
+    reference_embedding: str = Form(
+        ..., 
+        description="JSON array of floats (the stored embedding from .NET DB). "
+                    "Example: [0.12, -0.34, 0.56, ...]"
+    ),
+    file: UploadFile = File(...)
+):
+    """
+    ## Verify a Student's Identity (During Exam)
+    
+    Compares a live camera frame against the stored embedding to detect cheating/impersonation.
+    
+    ### How it works with .NET:
+    1. Fetch the student's `embedding` array from the **PostgreSQL** database.
+    2. Pass that array as a JSON string to `reference_embedding`. *(Example: `[0.12, -0.34, 0.56, ...]`. Do NOT pass the literal string `"string"`).*
+    3. Provide the new `image` from the student's webcam.
+    4. The API calculates the `Cosine Distance`. If it's `< 0.40`, the student is `verified: true`.
+    """
+    try:
+        # Parse the reference embedding from JSON string to List[float]
+        try:
+            embedding_list = json.loads(reference_embedding)
+            if not isinstance(embedding_list, list):
+                raise ValueError("reference_embedding must be a JSON array of numbers")
+        except json.JSONDecodeError:
+            raise ValueError(
+                "Invalid reference_embedding format. Must be a valid JSON array. "
+                "Example: [0.12, -0.34, 0.56, ...]"
+            )
+        
+        contents = await file.read()
+        image = decode_image_from_bytes(contents)
+        
+        return await face_recognition_service.verify_face(
+            student_id=student_id,
+            face_image=image,
+            reference_embedding=embedding_list
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Face verification failed: {e}")
+        raise HTTPException(status_code=500, detail="Internal processing error")
+
+
+# ─────────────────────────────────────────────
+# Full Frame Analysis (Stateless)
+# ─────────────────────────────────────────────
+
+@router.post("/analyze-frame", response_model=ProctorFrameResponse)
+async def analyze_frame(
+    student_id: str = Form(...),
+    detect_books: bool = Form(True),
+    return_annotated: bool = Form(False),
+    reference_embedding: Optional[str] = Form(
+        None, 
+        description="Optional JSON array of floats for face verification. "
+                    "If not provided, verification will be skipped."
+    ),
+    file: UploadFile = File(...)
+):
+    """
+    Full AI proctoring flow in one request.
+    
+    If `reference_embedding` is provided, face verification will be performed.
+    Otherwise, only face detection and object detection will run.
+    """
+    start_total = time.perf_counter()
+    try:
+        contents = await file.read()
+        image = decode_image_from_bytes(contents)
+        
+        # Run Face and Object detection in parallel
+        face_task = face_detection_service.detect(image)
+        object_task = object_detection_service.detect(
+            image=image,
+            detect_books=detect_books,
+            return_annotated=return_annotated
+        )
+        face_result, obj_result = await asyncio.gather(face_task, object_task)
+
+        # Optional Verification (only if reference_embedding is provided)
+        verify_result = None
+        if face_result.status == "single_face" and reference_embedding:
+            try:
+                embedding_list = json.loads(reference_embedding)
+                cropped_face_img = decode_base64_image(face_result.face_image)
+                verify_result = await face_recognition_service.verify_face(
+                    student_id=student_id,
+                    face_image=cropped_face_img,
+                    reference_embedding=embedding_list
+                )
+            except (json.JSONDecodeError, ValueError) as ve:
+                logger.warning(f"Skipping verification: {ve}")
+
+        # Compute Risk
+        violations_count = int(face_result.violation) + obj_result.violation_count
+        
+        risk = "safe"
+        if violations_count > 0:
+            if face_result.violation or (verify_result and not verify_result.verified):
+                risk = "critical"
+            else:
+                critical_types = ["extra_person", "mobile_detected", "laptop_detected"]
+                has_critical = any(v.type in critical_types for v in obj_result.violations)
+                risk = "critical" if has_critical else "warning"
+        elif verify_result and not verify_result.verified:
+            risk = "critical"
+
+        processing_time_ms = (time.perf_counter() - start_total) * 1000
+
+        return ProctorFrameResponse(
+            face_detection=face_result,
+            object_detection=obj_result,
+            face_verification=verify_result,
+            total_violations=violations_count,
+            risk_level=risk,
+            processing_time_ms=processing_time_ms
+        )
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Analyze frame failed: {e}")
+        raise HTTPException(status_code=500, detail="Internal processing error")

app/api/router.py

@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+from app.api.chat import router as chat_router
+from app.api.exams import router as exam_router
+from app.api.proctoring import router as proctoring_router
+
+api_router = APIRouter()
+
+api_router.include_router(chat_router)
+api_router.include_router(exam_router)
+api_router.include_router(proctoring_router)

app/core/config.py

@@ -0,0 +1,55 @@
+import os
+from typing import List, Optional
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore"
+    )
+
+    # App
+    APP_NAME: str = "Examify AI Services"
+    APP_ENV: str = "development"
+    DEBUG: bool = True
+    API_V1_STR: str = "/api/v1"
+    
+    # Security
+    SECRET_KEY: str = "placeholder-key-for-dev"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 8  # 8 days
+
+    # AI Providers
+    GROQ_API_KEY: Optional[str] = None
+    GEMINI_API_KEY: Optional[str] = None
+    OPENAI_API_KEY: Optional[str] = None
+
+    # Models
+    DEFAULT_CHAT_MODEL: str = "llama3-70b-8192"
+    DEFAULT_EXAM_MODEL: str = "gemini-1.5-pro"
+
+    # Middleware
+    CORS_ORIGINS: List[str] = ["*"]
+    GZIP_MIN_SIZE: int = 500
+
+    # Project Paths
+    ROOT_DIR: str = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    ML_ARTIFACTS_DIR: str = os.path.join(ROOT_DIR, "app", "ml_artifacts")
+
+    # Proctoring Models
+    FACE_DETECTION_MODEL_PATH: str = os.path.join(ROOT_DIR, "app", "ml_models", "face_detection_yunet.onnx")
+    OBJECT_DETECTION_MODEL_PATH: str = os.path.join(ROOT_DIR, "app", "ml_models", "yolov8n.onnx")
+
+    # Proctoring Thresholds
+    FACE_VERIFY_THRESHOLD: float = 0.80
+    FACE_VERIFY_HARD_REJECT: float = 1.00
+    OBJECT_DETECTION_CONFIDENCE: float = 0.50
+    OBJECT_DETECTION_NMS: float = 0.45
+
+    # Image Limits
+    MAX_IMAGE_SIZE_MB: int = 5
+    MAX_IMAGE_WIDTH: int = 1920
+    MAX_IMAGE_HEIGHT: int = 1080
+
+settings = Settings()

app/core/logging_config.py

@@ -0,0 +1,56 @@
+import sys
+import os
+import time
+import logging
+from loguru import logger
+from fastapi import Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        start_time = time.time()
+        request_id = request.headers.get("X-Request-ID", "internal")
+        
+        # Add correlation ID to context
+        logger.configure(extra={"request_id": request_id})
+        
+        response = await call_next(request)
+        
+        process_time = (time.time() - start_time) * 1000
+        formatted_process_time = "{0:.2f}".format(process_time)
+        
+        logger.info(
+            f"RID: {request_id} | {request.method} {request.url.path} | "
+            f"Status: {response.status_code} | Duration: {formatted_process_time}ms"
+        )
+        
+        return response
+
+def setup_logging():
+    # Remove default handlers
+    logging.getLogger().handlers = []
+    
+    # Configure Loguru
+    logger.remove()
+    logger.add(
+        sys.stdout, 
+        format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+        level="INFO"
+    )
+    
+    # Intercept standard logging
+    class InterceptHandler(logging.Handler):
+        def emit(self, record):
+            try:
+                level = logger.level(record.levelname).name
+            except ValueError:
+                level = record.levelno
+
+            frame, depth = logging.currentframe(), 2
+            while frame.f_code.co_filename == logging.__file__:
+                frame = frame.f_back
+                depth += 1
+
+            logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+    logging.basicConfig(handlers=[InterceptHandler()], level=0)

app/schemas/__init__.py

@@ -0,0 +1,46 @@
+"""
+schemas/__init__.py
+-------------------
+Backward-compatible re-export of all schemas.
+Existing imports like `from app.schemas import ChatRequest` continue to work.
+"""
+# Common
+from .common import ErrorResponse
+
+# Chat
+from .chat import Role, Message, ChatRequest, ChatResponse
+
+# Exam
+from .exam import QuestionType, ExamGenerateRequest, QuestionSchema, ExamResponse
+
+# Proctoring
+from .proctoring import (
+    BoundingBox,
+    FaceDetectionRequest,
+    FaceDetectionResponse,
+    ObjectDetectionRequest,
+    ViolationItem,
+    ObjectDetectionResponse,
+    FaceEmbeddingRequest,
+    FaceEmbeddingResponse,
+    FaceVerifyRequest,
+    FaceVerifyResponse,
+    ProctorFrameRequest,
+    ProctorFrameResponse,
+)
+
+__all__ = [
+    # common
+    "ErrorResponse",
+    # chat
+    "Role", "Message", "ChatRequest", "ChatResponse",
+    # exam
+    "QuestionType", "ExamGenerateRequest", "QuestionSchema", "ExamResponse",
+    # proctoring
+    "BoundingBox",
+    "FaceDetectionRequest", "FaceDetectionResponse",
+    "ObjectDetectionRequest", "ViolationItem", "ObjectDetectionResponse",
+    "FaceEmbeddingRequest", "FaceEmbeddingResponse",
+    "FaceVerifyRequest", "FaceVerifyResponse",
+    "ProctorFrameRequest", "ProctorFrameResponse",
+]

app/schemas/chat.py

@@ -0,0 +1,27 @@
+from typing import Dict, Any, Optional
+from pydantic import BaseModel
+from enum import Enum
+
+
+class Role(str, Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+
+
+class Message(BaseModel):
+    role: Role
+    content: str
+
+
+class ChatRequest(BaseModel):
+    messages: list[Message]
+    model: Optional[str] = None
+    stream: bool = False
+    temperature: float = 0.7
+
+
+class ChatResponse(BaseModel):
+    content: str
+    model: str
+    usage: Dict[str, Any]

app/schemas/common.py

@@ -0,0 +1,8 @@
+from typing import Optional
+from pydantic import BaseModel
+
+
+class ErrorResponse(BaseModel):
+    error: str
+    detail: Optional[str] = None
+    request_id: str

app/schemas/exam.py

@@ -0,0 +1,31 @@
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from enum import Enum
+
+
+class QuestionType(str, Enum):
+    MCQ = "mcq"
+    TRUE_FALSE = "true_false"
+    SHORT_ANSWER = "short_answer"
+
+
+class ExamGenerateRequest(BaseModel):
+    content: str = Field(..., description="Text or source to generate questions from")
+    num_questions: int = Field(default=5, ge=1, le=20)
+    difficulty: str = "medium"
+    question_types: List[QuestionType] = [QuestionType.MCQ]
+
+
+class QuestionSchema(BaseModel):
+    id: str
+    text: str
+    type: QuestionType
+    options: Optional[List[str]] = None
+    answer: str
+    explanation: Optional[str] = None
+
+
+class ExamResponse(BaseModel):
+    exam_id: str
+    title: str
+    questions: List[QuestionSchema]

app/schemas/proctoring.py

@@ -0,0 +1,128 @@
+"""
+proctoring.py
+-------------
+Pydantic schemas for all AI Proctoring endpoints:
+- Face Detection
+- Object Detection
+- Face Recognition (register + verify)
+- Combined frame analysis
+"""
+from __future__ import annotations
+
+from typing import List, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+# ─────────────────────────────────────────────
+# Shared sub-schemas
+# ─────────────────────────────────────────────
+
+class BoundingBox(BaseModel):
+    x: int
+    y: int
+    width: int
+    height: int
+
+
+# ─────────────────────────────────────────────
+# Face Detection
+# ─────────────────────────────────────────────
+
+class FaceDetectionRequest(BaseModel):
+    image: str = Field(..., description="Base64-encoded BGR image")
+    session_id: Optional[str] = Field(None, description="Exam session ID for tracking")
+
+
+class FaceDetectionResponse(BaseModel):
+    face_count: int = Field(..., description="Number of faces detected")
+    status: Literal["no_face", "single_face", "multiple_faces"]
+    bounding_box: Optional[BoundingBox] = Field(None, description="Bounding box of single detected face")
+    face_image: Optional[str] = Field(None, description="Base64 cropped face image (only when 1 face found)")
+    violation: bool = Field(..., description="True if face_count != 1")
+    processing_time_ms: float
+
+
+# ─────────────────────────────────────────────
+# Object Detection
+# ─────────────────────────────────────────────
+
+class ObjectDetectionRequest(BaseModel):
+    image: str = Field(..., description="Base64-encoded BGR image")
+    detect_books: bool = Field(True, description="Set False for open-book exams")
+    confidence_threshold: float = Field(0.50, ge=0.1, le=1.0,
+                                        description="Minimum detection confidence")
+    return_annotated: bool = Field(False, description="Return frame with drawn bounding boxes")
+    session_id: Optional[str] = None
+
+
+class ViolationItem(BaseModel):
+    type: Literal["mobile_detected", "laptop_detected", "book_detected", "extra_person"]
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    bounding_box: BoundingBox
+
+
+class ObjectDetectionResponse(BaseModel):
+    violations: List[ViolationItem]
+    violation_count: int
+    has_violations: bool
+    annotated_image: Optional[str] = Field(None,
+        description="Base64 image with drawn bounding boxes (only if return_annotated=True)")
+    processing_time_ms: float
+
+
+# ─────────────────────────────────────────────
+# Face Recognition — Register
+# ─────────────────────────────────────────────
+
+class FaceEmbeddingRequest(BaseModel):
+    images: List[str] = Field(..., min_length=1, max_length=10,
+                              description="List of Base64 face images (ideally 5 poses)")
+    student_id: str = Field(..., min_length=1, description="Unique student identifier")
+
+
+class FaceEmbeddingResponse(BaseModel):
+    student_id: str = Field(..., description="The unique identifier of the registered student.")
+    embeddings_count: int = Field(..., description="Number of face images processed to create the embedding.")
+    registered: bool = Field(..., description="Indicates if the registration was successful.")
+    embedding: List[float] = Field(
+        ...,
+        description="The 512-dimensional face embedding vector generated by Facenet. "
+                    "**IMPORTANT FOR .NET API:** Serialize this array as JSON or store it as a `vector`/`double precision[]` in PostgreSQL, and provide it back to the `/verify-face` endpoint during exams."
+    )
+
+
+# ─────────────────────────────────────────────
+# Face Recognition — Verify
+# ─────────────────────────────────────────────
+
+class FaceVerifyRequest(BaseModel):
+    image: str = Field(..., description="Base64 encoded live face image to verify (captured during the exam).")
+    student_id: str = Field(..., description="The student ID to verify against.")
+
+
+class FaceVerifyResponse(BaseModel):
+    verified: bool = Field(..., description="True if the face matches the stored reference embedding within the allowed threshold.")
+    distance: float = Field(..., description="The calculated Cosine distance between the live face and the reference embedding. (Lower is better/closer match).")
+    threshold: float = Field(0.40, description="The maximum allowed distance threshold used for verification.")
+    status: Literal["verified", "suspicious", "rejected"] = Field(..., description="The final decision status (verified < 0.40, suspicious < 0.60, rejected >= 0.60).")
+
+
+# ─────────────────────────────────────────────
+# Combined Frame Analysis
+# ─────────────────────────────────────────────
+
+class ProctorFrameRequest(BaseModel):
+    image: str = Field(..., description="Base64-encoded webcam frame")
+    student_id: str = Field(..., description="Student ID for face verification")
+    detect_books: bool = Field(True, description="Set False for open-book exams")
+    return_annotated: bool = Field(False, description="Return annotated image with violations drawn")
+    session_id: Optional[str] = None
+
+
+class ProctorFrameResponse(BaseModel):
+    face_detection: FaceDetectionResponse
+    object_detection: ObjectDetectionResponse
+    face_verification: Optional[FaceVerifyResponse] = None
+    total_violations: int = Field(..., description="Total number of violations detected")
+    risk_level: Literal["safe", "warning", "critical"]
+    processing_time_ms: float = Field(..., description="Total round-trip processing time")

app/services/chat_service.py

@@ -0,0 +1,69 @@
+import json
+from typing import AsyncGenerator, Dict, Any
+from groq import AsyncGroq
+from loguru import logger
+
+from app.schemas import ChatRequest, ChatResponse
+from app.core.config import settings
+
+class ChatService:
+    def __init__(self):
+        self.model = settings.DEFAULT_CHAT_MODEL
+        self.api_key = settings.GROQ_API_KEY
+        self._client = None
+
+    @property
+    def client(self):
+        if not self.api_key or self.api_key == "gsk_...":
+            raise ValueError("GROQ_API_KEY is missing. Please set it in your .env file.")
+        if self._client is None:
+            self._client = AsyncGroq(api_key=self.api_key)
+        return self._client
+
+    async def get_chat_response(self, request: ChatRequest) -> ChatResponse:
+        """Non-streaming response logic"""
+        model_to_use = request.model or self.model
+        logger.info(f"Processing chat request with model: {model_to_use}")
+        
+        # Prepare messages format for Groq
+        messages = [{"role": msg.role.value, "content": msg.content} for msg in request.messages]
+        
+        response = await self.client.chat.completions.create(
+            model=model_to_use,
+            messages=messages,
+            temperature=request.temperature,
+            stream=False
+        )
+        
+        content = response.choices[0].message.content
+        usage = response.usage.model_dump() if response.usage else {}
+        
+        return ChatResponse(
+            content=content or "",
+            model=response.model or model_to_use,
+            usage=usage
+        )
+
+    async def stream_chat_response(self, request: ChatRequest) -> AsyncGenerator[str, None]:
+        """Streaming response logic using SSE"""
+        model_to_use = request.model or self.model
+        logger.info(f"Starting stream for model: {model_to_use}")
+        
+        messages = [{"role": msg.role.value, "content": msg.content} for msg in request.messages]
+        
+        stream = await self.client.chat.completions.create(
+            model=model_to_use,
+            messages=messages,
+            temperature=request.temperature,
+            stream=True
+        )
+        
+        async for chunk in stream:
+            content = chunk.choices[0].delta.content
+            if content is not None:
+                data = {"content": content, "done": False}
+                yield f"data: {json.dumps(data)}\n\n"
+                
+        yield f"data: {json.dumps({'content': '', 'done': True})}\n\n"
+
+chat_service = ChatService()

app/services/exam_service.py

@@ -0,0 +1,87 @@
+import uuid
+import json
+from loguru import logger
+from groq import AsyncGroq
+
+from app.schemas import ExamGenerateRequest, ExamResponse, QuestionSchema
+from app.core.config import settings
+
+class ExamService:
+    def __init__(self):
+        # We enforce a Groq model for this feature to utilize JSON mode easily
+        self.model = "llama3-70b-8192" 
+        self.api_key = settings.GROQ_API_KEY
+        self._client = None
+
+    @property
+    def client(self):
+        if not self.api_key or self.api_key == "gsk_...":
+            raise ValueError("GROQ_API_KEY is missing. Please set it in your .env file.")
+        if self._client is None:
+            self._client = AsyncGroq(api_key=self.api_key)
+        return self._client
+
+    async def generate_exam(self, request: ExamGenerateRequest) -> ExamResponse:
+        logger.info(f"Generating {request.num_questions} questions via Groq JSON mode logic.")
+        
+        allowed_types = [qt.value for qt in request.question_types]
+        
+        system_prompt = f"""
+        You are an expert academic examiner. Your task is to extract information from the user's provided content and generate exactly {request.num_questions} questions.
+        The difficulty level should be: {request.difficulty}.
+        Allowed question types: {allowed_types}.
+        
+        IMPORTANT: Your output must be a pure JSON object using the following schema:
+        {{
+            "title": "A short descriptive title for the generated exam",
+            "questions": [
+                {{
+                    "text": "The question text",
+                    "type": "mcq" or "true_false" or "short_answer",
+                    "options": ["List", "of", "Choices"], // ONLY include this if type is mcq
+                    "answer": "The correct answer exactly as extracted/written",
+                    "explanation": "Brief explanation of why this answer is correct"
+                }}
+            ]
+        }}
+        """
+
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": f"Content to generate questions from:\n\n{request.content}"}
+                ],
+                response_format={"type": "json_object"},
+                temperature=0.3
+            )
+            
+            raw_output = response.choices[0].message.content
+            parsed = json.loads(raw_output)
+            
+            questions = []
+            for q in parsed.get("questions", []):
+                questions.append(QuestionSchema(
+                    id=str(uuid.uuid4())[:8],
+                    text=q.get("text", "Error generating text"),
+                    type=q.get("type", "short_answer"),
+                    options=q.get("options"),
+                    answer=q.get("answer", "No answer provided"),
+                    explanation=q.get("explanation")
+                ))
+                
+            return ExamResponse(
+                exam_id=str(uuid.uuid4()),
+                title=parsed.get("title", "AI Generated Exam"),
+                questions=questions
+            )
+            
+        except json.JSONDecodeError as je:
+            logger.error(f"Failed to parse JSON from Groq: {je}")
+            raise ValueError("The AI did not return a valid JSON structure.")
+        except Exception as e:
+            logger.error(f"Failed to generate exam via Groq: {e}")
+            raise
+
+exam_service = ExamService()

app/services/face_detection_service.py

@@ -0,0 +1,72 @@
+import asyncio
+import time
+import cv2
+import numpy as np
+from loguru import logger
+from app.schemas.proctoring import FaceDetectionResponse, BoundingBox
+from app.utils.image_utils import encode_image_to_base64
+
+class FaceDetectionService:
+    def __init__(self):
+        self._detector = None
+
+    def load_model(self, model_path: str):
+        """Called once during app startup via lifespan"""
+        self._detector = cv2.FaceDetectorYN.create(model_path, "", (320, 320))
+        logger.info(f"YuNet face detector loaded: {model_path}")
+
+    async def detect(self, image: np.ndarray) -> FaceDetectionResponse:
+        """Run face detection on a single frame"""
+        # Run in threadpool since OpenCV is sync/CPU-bound
+        return await asyncio.to_thread(self._detect_sync, image)
+
+    def _detect_sync(self, image: np.ndarray) -> FaceDetectionResponse:
+        start_time = time.perf_counter()
+        h, w = image.shape[:2]
+        self._detector.setInputSize((w, h))
+        
+        _, faces = self._detector.detect(image)
+        
+        processing_time_ms = (time.perf_counter() - start_time) * 1000
+
+        if faces is None:
+            return FaceDetectionResponse(
+                face_count=0,
+                status="no_face",
+                violation=True,
+                processing_time_ms=processing_time_ms
+            )
+
+        face_count = len(faces)
+        if face_count > 1:
+            return FaceDetectionResponse(
+                face_count=face_count,
+                status="multiple_faces",
+                violation=True,
+                processing_time_ms=processing_time_ms
+            )
+
+        # face_count == 1 -> extract bbox and crop face
+        x, y, w_box, h_box = faces[0][:4].astype(int)
+        
+        # Ensure bounding box is within image bounds
+        x = max(0, x)
+        y = max(0, y)
+        w_box = min(w - x, w_box)
+        h_box = min(h - y, h_box)
+        
+        face_img = image[y:y+h_box, x:x+w_box]
+        face_b64 = encode_image_to_base64(face_img)
+        bbox = BoundingBox(x=x, y=y, width=w_box, height=h_box)
+
+        return FaceDetectionResponse(
+            face_count=1,
+            status="single_face",
+            bounding_box=bbox,
+            face_image=face_b64,
+            violation=False,
+            processing_time_ms=processing_time_ms
+        )
+
+# Singleton instance
+face_detection_service = FaceDetectionService()

app/services/face_recognition_service.py

@@ -0,0 +1,153 @@
+import asyncio
+from typing import List
+
+import numpy as np
+from deepface import DeepFace
+from scipy.spatial.distance import cosine
+from loguru import logger
+
+from app.schemas.proctoring import FaceEmbeddingResponse, FaceVerifyResponse
+
+
+class FaceRecognitionService:
+    """
+    خدمة التعرف على الوجوه (Face Recognition Service) - Stateless Architecture.
+    
+    الخدمة دي بقت "محرك تحليل فقط":
+    1. تسجيل الوجه (Register): بتاخد صورة ← تطلع منها "بصمة رقمية" (Embedding) ← ترجعها أرقام للـ .NET يسيفها.
+    2. التحقق (Verify): بتاخد صورة جديدة + البصمة القديمة (من الـ .NET) ← تقارن بينهم ← ترجع النتيجة.
+    
+    ⚠️ الخدمة دي مش بتحفظ أي حاجة على الهارد ديسك! كل التخزين مسؤولية الـ .NET API.
+    """
+
+    def __init__(self):
+        # اسم الموديل الذكي (Facenet من جوجل - دقة عالية جداً)
+        self._model_name = "Facenet"
+        
+        # Threshold: لو المسافة أقل من 0.40 يبقى نفس الشخص (Verified)
+        # Facenet cosine distance default threshold
+        self._threshold = 0.40
+        
+        # لو المسافة بين 0.40 و 0.60 يبقى مشبوه (Suspicious)
+        # لو أكبر من 0.60 يبقى شخص تاني (Rejected)
+        self._hard_reject = 0.60
+
+    # ─────────────────────────────────────────────
+    # Registration: استخراج البصمة وإرجاعها للـ .NET
+    # ─────────────────────────────────────────────
+
+    async def register_student(self, student_id: str, face_images: List[np.ndarray]) -> FaceEmbeddingResponse:
+        """
+        تسجيل الطالب (Async).
+        بنشغل الموديل في Thread منفصل عشان السيرفر مايتعلقش.
+        """
+        return await asyncio.to_thread(self._register_sync, student_id, face_images)
+
+    def _register_sync(self, student_id: str, face_images: List[np.ndarray]) -> FaceEmbeddingResponse:
+        """
+        الشغل الفعلي لتسجيل الطالب:
+        1. بياخد الصورة.
+        2. يستخرج البصمة (Embedding) منها.
+        3. يرجع الأرقام للـ .NET عشان يسيفها في PostgreSQL.
+        ⚠️ لا يتم حفظ أي ملفات على الهارد ديسك.
+        """
+        embeddings = []
+        last_error = "Unknown Error"
+        
+        for img in face_images:
+            try:
+                emb = self._get_embedding(img)
+                embeddings.append(emb)
+            except Exception as e:
+                last_error = str(e)
+                logger.exception(f"Failed to get embedding during registration: {e}")
+                
+        if not embeddings:
+            raise ValueError(f"Could not extract any embeddings for student {student_id}. Reason: {last_error}")
+        
+        # بنحسب متوسط كل الـ embeddings عشان نرجع بصمة واحدة موحدة
+        avg_embedding = np.mean(embeddings, axis=0)
+        
+        return FaceEmbeddingResponse(
+            student_id=student_id,
+            embeddings_count=len(embeddings),
+            registered=True,
+            embedding=avg_embedding.tolist()  # ← دي الأرقام اللي الـ .NET هيسيفها
+        )
+
+    # ─────────────────────────────────────────────
+    # Verification: مقارنة صورة جديدة ببصمة قديمة
+    # ─────────────────────────────────────────────
+
+    async def verify_face(
+        self, 
+        student_id: str, 
+        face_image: np.ndarray, 
+        reference_embedding: List[float]
+    ) -> FaceVerifyResponse:
+        """
+        التحقق من الوجه (Async).
+        الـ .NET بيبعتلنا الصورة الجديدة + البصمة القديمة اللي متسيفة عنده.
+        """
+        return await asyncio.to_thread(
+            self._verify_sync, student_id, face_image, reference_embedding
+        )
+
+    def _verify_sync(
+        self, 
+        student_id: str, 
+        face_image: np.ndarray, 
+        reference_embedding: List[float]
+    ) -> FaceVerifyResponse:
+        """
+        الشغل الفعلي للتحقق:
+        1. بيطلع البصمة من الصورة الجديدة (Live).
+        2. بيقارنها بالبصمة اللي الـ .NET بعتهاله (Reference).
+        3. بيحسب المسافة (Cosine Distance) ويقرر النتيجة.
+        ⚠️ لا يتم قراءة أي ملفات من الهارد ديسك.
+        """
+        try:
+            live_emb = self._get_embedding(face_image)
+        except Exception as e:
+            logger.error(f"Failed to get embedding during verification: {e}")
+            raise ValueError("Failed to extract embedding from the live image")
+        
+        # تحويل البصمة المرسلة من الـ .NET لـ numpy array
+        stored_emb = np.array(reference_embedding)
+        
+        # حساب المسافة (الاختلاف) بين الصورتين
+        distance = cosine(live_emb, stored_emb)
+
+        # تحديد النتيجة بناءً على الـ Threshold
+        if distance < self._threshold:
+            status = "verified"      # الطالب هو هو ✅
+        elif distance < self._hard_reject:
+            status = "suspicious"    # مشبوه ⚠️
+        else:
+            status = "rejected"      # شخص تاني ❌
+
+        return FaceVerifyResponse(
+            verified=(status == "verified"),
+            distance=round(float(distance), 4),
+            status=status,
+            threshold=self._threshold
+        )
+
+    # ─────────────────────────────────────────────
+    # Core: استخراج البصمة من الصورة
+    # ─────────────────────────────────────────────
+
+    def _get_embedding(self, face_img: np.ndarray) -> np.ndarray:
+        """
+        الدالة الأساسية: بتتواصل مع DeepFace وتستخرج البصمة.
+        البصمة = مصفوفة 512 رقم عشري بتمثل ملامح الوش.
+        """
+        result = DeepFace.represent(
+            face_img, 
+            model_name=self._model_name,
+            enforce_detection=False 
+        )
+        return np.array(result[0]["embedding"])
+
+
+face_recognition_service = FaceRecognitionService()

app/services/object_detection_service.py

@@ -0,0 +1,181 @@
+import asyncio
+import time
+import os
+from typing import List
+
+import cv2
+import numpy as np
+import onnxruntime as ort
+from loguru import logger
+
+from app.schemas.proctoring import ObjectDetectionResponse, ViolationItem, BoundingBox
+from app.utils.image_utils import encode_image_to_base64
+
+EXAM_CLASSES: dict[int, str] = {
+    0:  "extra_person",
+    63: "laptop_detected",
+    67: "mobile_detected",
+    73: "book_detected",
+}
+
+VIOLATION_COLORS: dict[str, tuple] = {
+    "extra_person":    (0,   0,   255),   # red
+    "laptop_detected": (255, 200, 0  ),   # cyan-yellow
+    "mobile_detected": (0,   140, 255),   # orange
+    "book_detected":   (255, 0,   180),   # purple
+}
+
+INPUT_SIZE = 640
+NMS_THRESHOLD = 0.45
+
+
+class ObjectDetectionService:
+    def __init__(self):
+        self._session: ort.InferenceSession | None = None
+
+    def load_model(self, model_path: str):
+        """Load YOLOv8 ONNX session during startup"""
+        if not os.path.exists(model_path):
+            raise FileNotFoundError(f"ONNX model not found: {model_path}")
+        
+        self._session = ort.InferenceSession(
+            model_path,
+            providers=["CPUExecutionProvider"],
+        )
+        logger.info(f"YOLOv8 ONNX session ready: {model_path}")
+
+    async def detect(self, image: np.ndarray, 
+                     detect_books: bool = True,
+                     conf_threshold: float = 0.50,
+                     return_annotated: bool = False
+                     ) -> ObjectDetectionResponse:
+        """Run object detection — delegates to threadpool"""
+        return await asyncio.to_thread(
+            self._detect_sync, image, detect_books, conf_threshold, return_annotated
+        )
+
+    def _preprocess(self, frame: np.ndarray) -> tuple[np.ndarray, float, int, int]:
+        h, w = frame.shape[:2]
+        scale = INPUT_SIZE / max(h, w)
+        new_w, new_h = int(w * scale), int(h * scale)
+        resized = cv2.resize(frame, (new_w, new_h))
+
+        pad_x = (INPUT_SIZE - new_w) // 2
+        pad_y = (INPUT_SIZE - new_h) // 2
+        canvas = np.zeros((INPUT_SIZE, INPUT_SIZE, 3), dtype=np.uint8)
+        canvas[pad_y:pad_y + new_h, pad_x:pad_x + new_w] = resized
+
+        # HWC BGR  ->  CHW RGB  ->  NCHW float32
+        tensor = canvas[:, :, ::-1].transpose(2, 0, 1).astype(np.float32) / 255.0
+        tensor = tensor[np.newaxis]   # [1, 3, H, W]
+        return tensor, scale, pad_x, pad_y
+
+    def _detect_sync(self, image: np.ndarray, detect_books: bool, 
+                     conf_threshold: float, return_annotated: bool) -> ObjectDetectionResponse:
+                     
+        start_time = time.perf_counter()
+        
+        input_name = self._session.get_inputs()[0].name
+        tensor, scale, pad_x, pad_y = self._preprocess(image)
+        outputs = self._session.run(None, {input_name: tensor})
+        preds = outputs[0][0]  # [84, N]
+        
+        boxes_raw, scores_raw, class_ids_raw = [], [], []
+        person_count = 0
+
+        num_detections = preds.shape[1]
+        for i in range(num_detections):
+            col = preds[:, i]
+            class_confs = col[4:]
+            class_id = int(np.argmax(class_confs))
+            confidence = float(class_confs[class_id])
+
+            if confidence < conf_threshold:
+                continue
+            if class_id not in EXAM_CLASSES:
+                continue
+            if EXAM_CLASSES[class_id] == "book_detected" and not detect_books:
+                continue
+
+            cx = (col[0] - pad_x) / scale
+            cy = (col[1] - pad_y) / scale
+            bw = col[2] / scale
+            bh = col[3] / scale
+            x = int(cx - bw / 2)
+            y = int(cy - bh / 2)
+
+            boxes_raw.append([x, y, int(bw), int(bh)])
+            scores_raw.append(confidence)
+            class_ids_raw.append(class_id)
+
+        violations: List[ViolationItem] = []
+        annotated_image = None
+        
+        if boxes_raw:
+            indices = cv2.dnn.NMSBoxes(boxes_raw, scores_raw, conf_threshold, NMS_THRESHOLD)
+            
+            if len(indices) > 0:
+                for idx in indices.flatten():
+                    cid = class_ids_raw[idx]
+                    vtype = EXAM_CLASSES[cid]
+                    conf = round(scores_raw[idx], 3)
+                    
+                    # Prevent negative box coordinates
+                    bx, by, bw, bh = boxes_raw[idx]
+                    bx = max(0, bx)
+                    by = max(0, by)
+                    
+                    bbox = BoundingBox(x=bx, y=by, width=bw, height=bh)
+
+                    if vtype == "extra_person":
+                        person_count += 1
+                        continue
+
+                    violations.append(ViolationItem(type=vtype, confidence=conf, bounding_box=bbox))
+
+                if person_count >= 2:
+                    violations.append(ViolationItem(
+                        type="extra_person", 
+                        confidence=1.0, 
+                        bounding_box=BoundingBox(x=0, y=0, width=0, height=0)
+                    ))
+        
+        processing_time_ms = (time.perf_counter() - start_time) * 1000
+        
+        if return_annotated and (violations or person_count >= 2):
+            annotated_frame = self._draw_violations(image.copy(), violations, person_count)
+            annotated_image = encode_image_to_base64(annotated_frame)
+            
+        return ObjectDetectionResponse(
+            violations=violations,
+            violation_count=len(violations),
+            has_violations=bool(violations),
+            annotated_image=annotated_image,
+            processing_time_ms=processing_time_ms
+        )
+
+    def _draw_violations(self, frame: np.ndarray, violations: List[ViolationItem], person_count: int) -> np.ndarray:
+        for v in violations:
+            if v.type == "extra_person":
+                continue # no specific box for extra person usually, handled by full frame warning if needed
+            
+            x, y, w, h = v.bounding_box.x, v.bounding_box.y, v.bounding_box.width, v.bounding_box.height
+            color = VIOLATION_COLORS.get(v.type, (0, 0, 255))
+            label = f"{v.type}  {v.confidence:.0%}"
+            cv2.rectangle(frame, (x, y), (x + w, y + h), color, 2)
+            cv2.putText(
+                frame, label,
+                (x, max(y - 8, 16)),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2,
+            )
+            
+        if person_count >= 2:
+            cv2.putText(
+                frame, "EXTRA PERSON DETECTED", (10, 30),
+                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 0, 255), 2
+            )
+            
+        return frame
+
+
+object_detection_service = ObjectDetectionService()

app/utils/__init__.py

@@ -0,0 +1 @@
+# Utils package

app/utils/image_utils.py

@@ -0,0 +1,125 @@
+"""
+image_utils.py
+--------------
+Utilities for converting between Base64 strings and OpenCV BGR numpy arrays.
+Used by all proctoring services to decode incoming API images.
+"""
+import base64
+import binascii
+import re
+
+import cv2
+import numpy as np
+
+
+# ─────────────────────────────────────────────
+# Public API
+# ─────────────────────────────────────────────
+
+def decode_base64_image(b64_str: str) -> np.ndarray:
+    """
+    Decode a Base64-encoded image string into a BGR numpy array.
+
+    Accepts:
+    - Raw base64 string
+    - Data URI: ``data:image/jpeg;base64,<data>``
+
+    Returns:
+        np.ndarray: BGR image (OpenCV format)
+
+    Raises:
+        ValueError: If the string is not valid base64 or not a valid image.
+    """
+    if not b64_str:
+        raise ValueError("Image string is empty.")
+
+    # Strip data URI prefix if present (e.g. "data:image/png;base64,")
+    if b64_str.startswith("data:"):
+        match = re.match(r"data:[a-zA-Z0-9+/]+;base64,(.+)", b64_str, re.DOTALL)
+        if not match:
+            raise ValueError("Invalid data URI format.")
+        b64_str = match.group(1)
+
+    # Decode base64
+    try:
+        img_bytes = base64.b64decode(b64_str, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"Invalid base64 encoding: {exc}") from exc
+
+    # Decode image bytes
+    img_array = np.frombuffer(img_bytes, dtype=np.uint8)
+    image = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
+
+    if image is None:
+        raise ValueError("Could not decode image from provided bytes. "
+                         "Ensure the image is a valid JPEG, PNG, or WebP.")
+    return image
+
+
+def decode_image_from_bytes(img_bytes: bytes) -> np.ndarray:
+    """
+    Decode raw image bytes into a BGR numpy array.
+    """
+    img_array = np.frombuffer(img_bytes, dtype=np.uint8)
+    image = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
+    if image is None:
+        raise ValueError("Could not decode image from provided bytes.")
+    return image
+
+
+def encode_image_to_base64(image: np.ndarray, fmt: str = ".jpg",
+                            quality: int = 85) -> str:
+    """
+    Encode a BGR numpy array to a Base64 string.
+
+    Args:
+        image:   BGR numpy array.
+        fmt:     Output format extension (".jpg", ".png", ".webp").
+        quality: JPEG/WebP compression quality (0-100).
+
+    Returns:
+        str: Base64-encoded image string (no data URI prefix).
+
+    Raises:
+        ValueError: If encoding fails.
+    """
+    encode_params: list = []
+    if fmt in (".jpg", ".jpeg"):
+        encode_params = [cv2.IMWRITE_JPEG_QUALITY, quality]
+    elif fmt == ".webp":
+        encode_params = [cv2.IMWRITE_WEBP_QUALITY, quality]
+
+    ok, buffer = cv2.imencode(fmt, image, encode_params)
+    if not ok:
+        raise ValueError(f"Failed to encode image as {fmt}.")
+
+    return base64.b64encode(buffer.tobytes()).decode("utf-8")
+
+
+def validate_and_resize(
+    image: np.ndarray,
+    max_width: int = 1920,
+    max_height: int = 1080,
+    min_width: int = 32,
+    min_height: int = 32,
+) -> np.ndarray:
+    """
+    Validate image dimensions and resize if it exceeds the max size.
+
+    Raises:
+        ValueError: If image is smaller than minimum dimensions.
+    """
+    h, w = image.shape[:2]
+
+    if w < min_width or h < min_height:
+        raise ValueError(
+            f"Image too small ({w}x{h}). Minimum is {min_width}x{min_height}."
+        )
+
+    if w > max_width or h > max_height:
+        scale = min(max_width / w, max_height / h)
+        new_w = int(w * scale)
+        new_h = int(h * scale)
+        image = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_AREA)
+
+    return image

main.py

@@ -0,0 +1,88 @@
+import time
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.responses import JSONResponse
+from app.api.router import api_router
+from app.core.config import settings
+from app.core.logging_config import setup_logging, RequestLoggingMiddleware
+from loguru import logger
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: Load ML models or init clients
+    logger.info("--- Starting up Examify AI Services ---")
+    
+    from app.services.face_detection_service import face_detection_service
+    from app.services.object_detection_service import object_detection_service
+    
+    # Load models (Face Recognition is stateless - no initialization needed)
+    face_detection_service.load_model(settings.FACE_DETECTION_MODEL_PATH)
+    object_detection_service.load_model(settings.OBJECT_DETECTION_MODEL_PATH)
+    
+    app.state.models = {
+        "face_detection": "loaded",
+        "object_detection": "loaded",
+        "face_recognition": "stateless (no local storage)"
+    } 
+    logger.info("All ML models loaded successfully (Face Recognition is stateless)")
+    
+    yield
+    
+    # Shutdown: Cleanup
+    logger.info("--- Shutting down Examify AI Services ---")
+    app.state.models.clear()
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.APP_NAME,
+        version="1.0.0",
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+    )
+
+    # Setup Logging
+    setup_logging()
+
+    # Add Middlewares
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.CORS_ORIGINS,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    
+    app.add_middleware(GZipMiddleware, minimum_size=settings.GZIP_MIN_SIZE)
+    app.add_middleware(RequestLoggingMiddleware)
+
+    # Exception Handlers
+    @app.exception_handler(Exception)
+    async def global_exception_handler(request: Request, exc: Exception):
+        logger.error(f"Global Error: {str(exc)}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": "Internal Server Error",
+                "detail": str(exc) if settings.DEBUG else None,
+                "request_id": request.headers.get("X-Request-ID", "unknown")
+            }
+        )
+
+    # Include Routes
+    app.include_router(api_router, prefix=settings.API_V1_STR)
+
+    @app.get("/health", tags=["Health"])
+    async def health_check():
+        return {"status": "healthy", "timestamp": time.time()}
+
+    return app
+
+app = create_app()
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)
+ 

requirements.txt

@@ -0,0 +1,16 @@
+fastapi[all]>=0.110.0
+pydantic-settings>=2.2.1
+python-dotenv>=1.0.1
+loguru>=0.7.2
+python-multipart>=0.0.9
+uvicorn>=0.29.0
+# === AI Providers ===
+groq>=0.5.0
+
+# === AI Proctoring ===
+opencv-python-headless>=4.9.0
+onnxruntime>=1.17.0
+numpy>=1.26.0
+deepface>=0.0.89
+tf-keras>=2.16.0
+scipy>=1.12.0