initialcommit

.dockerignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+chroma_data/
+assets/*.pt
+.env
+*.log
+.git/
+.gitignore
+README.md
+.DS_Store
+*.pem
+static/crops/*
+!static/crops/.gitkeep

.env

@@ -0,0 +1,11 @@
+APP_NAME=FaceRecognitionAPI
+APP_VERSION=1.0.0
+APP_VARIENT=v1
+host=0.0.0.0
+port=7860
+DETECTION_MODEL=mtcnn
+YOLOFACE_MODEL_PATH=assets/yolov11n-face.pt
+CHROMA_DB_PATH=./chroma_data
+COLLECTION_NAME=face_embeddings_collection
+SIMILARITY_THRESHOLD=0.7
+MAX_RESULTS=1

.env_example

@@ -0,0 +1,16 @@
+APP_NAME="Auto_Proctor"
+APP_VERSION="0.1"
+APP_VARIENT="FaceRecognitionApi"
+
+
+host="0.0.0.0"
+port=3030
+DETECTION_MODEL="yoloface"   # Options: mtcnn, yoloface
+
+YOLOFACE_MODEL_PATH="assets/yolov12n-face.pt"   # Options: yolov12n-face.pt,  yolov12s-face.pt
+
+CHROMA_DB_PATH = "./chroma_data"
+COLLECTION_NAME = "face_embeddings_collection"
+
+SIMILARITY_THRESHOLD=0.6   # Youstina use them while quering
+MAX_RESULTS=1

Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies for OpenCV and other libraries
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    libsm6 \
+    libxext6 \
+    libxrender-dev \
+    libgomp1 \
+    libglib2.0-0 \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application
+COPY . .
+
+# Create assets directory and download YOLO model
+RUN mkdir -p assets && \
+    wget -O assets/yolov11n-face.pt https://github.com/YapaLab/yolo-face/releases/download/1.0.0/yolov11n-face.pt || true
+
+# Create directories for ChromaDB and static files
+RUN mkdir -p chroma_data static/crops
+
+# Expose port (Hugging Face Spaces uses 7860 by default)
+EXPOSE 7860
+
+# Run the application
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,53 @@
 ---
-title: FaceRecognitionAPI
-emoji: 👁
-colorFrom: gray
-colorTo: gray
+title: Face Recognition API
+emoji: 👁️
+colorFrom: purple
+colorTo: blue
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Face Recognition API with FastAPI
+
+A real-time face detection and recognition API with WebSocket support for streaming video frames.
+
+## Features
+
+- 🎯 **Face Detection**: MTCNN or YOLO face detection
+- 🔍 **Face Recognition**: FaceNet embeddings with ChromaDB vector storage
+- 📡 **WebSocket Streaming**: Real-time face detection over WebSockets
+- 🖼️ **REST API**: Embed, update, delete, and recognize faces
+- 🎨 **Data Augmentation**: Automatic face augmentation for better recognition
+- 📊 **Live Demo UI**: Built-in HTML interface for testing
+
+## Quick Start
+
+1. Access the API at the public URL provided by Hugging Face Spaces
+2. Use the built-in UI at `/AutoProctor/v1/` for live testing
+3. Check API docs at `/docs` for Swagger documentation
+
+## API Endpoints
+
+### Base Endpoints
+- `GET /AutoProctor/v1/` - Web interface for testing
+- `GET /AutoProctor/v1/health` - Health check
+- `GET /AutoProctor/v1/config` - Get current configuration
+- `GET /AutoProctor/v1/count` - Count stored embeddings
+
+### Face Management
+- `POST /AutoProctor/v1/data/embed/{user_id}` - Add face embeddings
+- `POST /AutoProctor/v1/data/update/{user_id}` - Update face embeddings
+- `POST /AutoProctor/v1/data/delete/{user_id}` - Delete user embeddings
+
+### Recognition
+- `POST /AutoProctor/v1/data/detect/frame` - Detect faces in single frame
+- `POST /AutoProctor/v1/data/recognize/frame` - Recognize face in frame
+- `WebSocket /AutoProctor/v1/data/detect/stream` - Real-time streaming
+
+## Example Usage
+
+### Add Face Embedding
+```bash
+curl -X POST "https://your-space.hf.space/AutoProctor/v1/data/embed/user123" \
+  -F "file=@face.jpg"

controllers/EmbeddingController.py

@@ -0,0 +1,200 @@
+import base64
+import cv2
+import os
+from datetime import datetime
+import numpy as np
+import torch
+from facenet_pytorch import MTCNN, InceptionResnetV1
+from ultralytics import YOLO
+from helpers.db import get_chroma
+import uuid
+
+from helpers.Augmentions import FaceAugmentor
+
+class EmbeddingController:
+    def __init__(self, DETECTION_MODEL: str, YOLOFACE_MODEL_PATH=None):
+        self.client, self.collection = get_chroma()
+        self.detection_model = DETECTION_MODEL
+        if DETECTION_MODEL == "yoloface":
+            self.detector = YOLO(model=YOLOFACE_MODEL_PATH)
+        else:
+            self.detector = MTCNN(
+                image_size=160,
+                margin=10,                 # tight crop, small context
+                min_face_size=20,          # allow smaller faces
+                thresholds=[0.6, 0.7, 0.8], # higher recall, fewer misses
+                factor=0.709,
+                post_process=True,
+                keep_all=True,        
+                device=torch.device('cpu')
+            )
+
+        self.facenet = InceptionResnetV1(pretrained="vggface2").eval().to("cpu")
+        self.augmentor = FaceAugmentor()
+
+    def detect_faces(self, image):
+        if isinstance(self.detector, YOLO):
+            results = self.detector(image,verbose=False)
+            boxes = results[0].boxes.xyxy.cpu().numpy()
+        else:
+            boxes, _ = self.detector.detect(image)
+            if boxes is None:
+                return []
+        faces = []
+        for box in boxes:
+            x1, y1, x2, y2 = map(int, box)
+            face = image[y1:y2, x1:x2]
+            if face.size > 0:
+                faces.append(face)
+        return faces
+
+    def get_embedding(self, face):
+        try:
+            face_rgb = cv2.cvtColor(face, cv2.COLOR_BGR2RGB)
+        except Exception:
+            face_rgb = face
+        face_resized = cv2.resize(face_rgb, (160, 160))
+        face_tensor = torch.tensor(face_resized).permute(2, 0, 1).unsqueeze(0).float() / 255.0
+        with torch.no_grad():
+            embedding = self.facenet(face_tensor.to("cpu")).cpu().numpy()
+        return embedding.flatten()
+
+    def face_to_base64(self, face):
+        _, buffer = cv2.imencode('.jpg', face)
+        return base64.b64encode(buffer).decode("utf-8")
+
+    def save_cropped_face(self, face, user_id: str = None, idx: int = 0):
+        try:
+            out_dir = os.path.join(os.getcwd(), 'static', 'crops')
+            os.makedirs(out_dir, exist_ok=True)
+            ts = datetime.now().strftime('%Y%m%d_%H%M%S')
+            user_part = user_id if user_id else 'unknown'
+            filename = f"{user_part}_{self.detection_model}_{idx}_{ts}.jpg"
+            path = os.path.join(out_dir, filename)
+            cv2.imwrite(path, face)
+            return path
+        except Exception:
+            return None
+
+    def add_embedding(self, face, embedding, metadata: dict):
+        user_id = metadata["user_id"]
+        record_id = f"{user_id}_{uuid.uuid4().hex}"
+        face_b64 = self.face_to_base64(face)
+
+        # try:
+        #     self.save_cropped_face(face, user_id=user_id, idx=0)
+        # except Exception:
+        #     pass
+
+        embedding = embedding / np.linalg.norm(embedding)
+        self.collection.add(
+            ids=[record_id],
+            embeddings=[embedding.tolist()],
+            documents=[face_b64],
+            metadatas=[metadata]
+        )
+
+
+        aug_faces = self.augmentor.generate(face)
+
+        for i, aug_face in enumerate(aug_faces):
+            aug_embedding = self.get_embedding(aug_face)
+            aug_metadata = metadata.copy()
+            aug_metadata["augmented"] = True
+            aug_id = f"{user_id}_aug_{i}_{uuid.uuid4().hex}"
+            # try:
+            #     self.save_cropped_face(aug_face, user_id=aug_id, idx=i)
+            # except Exception:
+            #     pass
+
+            aug_embedding = aug_embedding / np.linalg.norm(aug_embedding)
+            self.collection.add(
+                ids=[aug_id],
+                embeddings=[aug_embedding.tolist()],
+                documents=[self.face_to_base64(aug_face)],
+                metadatas=[aug_metadata]
+            )
+
+    def update_embeddings(self, user_id: str, faces: list, embeddings: list, metadata: dict = None):
+        try:
+            self.collection.delete(where={"user_id": user_id})
+        except Exception:
+            pass
+
+        for idx, (face, emb) in enumerate(zip(faces, embeddings)):
+            meta = metadata.copy() if metadata else {}
+            meta.update({"user_id": user_id})
+            # try:
+            #     self.save_cropped_face(face, user_id=user_id, idx=idx)
+            # except Exception:
+            #     pass
+
+            record_id = f"{user_id}_{idx}_{datetime.now().timestamp()}"
+
+            emb = emb / np.linalg.norm(emb)
+            self.collection.add(
+                ids=[record_id],
+                embeddings=[emb.tolist()],
+                documents=[self.face_to_base64(face)],
+                metadatas=[meta]
+            )
+
+            aug_faces = self.augmentor.generate(face)
+            for j, aug_face in enumerate(aug_faces):
+                aug_embedding = self.get_embedding(aug_face)
+                aug_meta = meta.copy()
+                aug_meta["augmented"] = True
+                aug_id = f"{user_id}_upd_aug_{j}_{uuid.uuid4().hex}"
+                aug_embedding = aug_embedding / np.linalg.norm(aug_embedding)
+                self.collection.add(
+                    ids=[aug_id],
+                    embeddings=[aug_embedding.tolist()],
+                    documents=[self.face_to_base64(aug_face)],
+                    metadatas=[aug_meta]
+                )
+
+    def delete_embeddings_by_user(self, user_id: str):
+        try:
+            self.collection.delete(where={"user_id": user_id})
+            return True
+        except Exception as e:
+            print("Deletion error:", e)
+            return False
+
+
+    def query_embedding(self, embedding, n_results=5, threshold=0.6):
+        embedding = embedding / np.linalg.norm(embedding)
+        results = self.collection.query(
+            query_embeddings=[embedding.tolist()],
+            n_results=n_results
+        )
+        if not results or not results.get("distances"):
+            return {
+                "match": False,
+                "reason": "No results from database"
+            }
+
+        distances = results["distances"][0]
+        metadatas = results["metadatas"][0]
+        if not distances or not metadatas:
+            return {
+                "match": False,
+                "reason": "Empty results from database"
+            }
+        best_distance = min(distances)
+        best_index = distances.index(best_distance)
+        best_metadata = metadatas[best_index]
+        similarity = 1 - best_distance
+        if similarity >= threshold:
+            return {
+                "match": True,
+                "user_id": best_metadata.get("user_id"),
+                "similarity": round(similarity, 5),
+                "metadata": best_metadata
+            }
+
+        return {
+            "match": False,
+            "similarity": round(similarity, 5)
+        }
+

controllers/__init__.py

@@ -0,0 +1 @@
+from .EmbeddingController import EmbeddingController

docker-compose.yml

@@ -0,0 +1,23 @@
+version: '3.8'
+
+services:
+  face-recognition-api:
+    build: .
+    ports:
+      - "7860:7860"
+    volumes:
+      - ./chroma_data:/app/chroma_data
+      - ./static/crops:/app/static/crops
+    environment:
+      - APP_NAME=FaceRecognitionAPI
+      - APP_VERSION=1.0.0
+      - APP_VARIENT=v1
+      - HOST=0.0.0.0
+      - PORT=7860
+      - DETECTION_MODEL=mtcnn
+      - YOLOFACE_MODEL_PATH=assets/yolov11n-face.pt
+      - CHROMA_DB_PATH=./chroma_data
+      - COLLECTION_NAME=face_embeddings_collection
+      - SIMILARITY_THRESHOLD=0.7
+      - MAX_RESULTS=1
+    restart: unless-stopped

helpers/Augmentions.py

@@ -0,0 +1,65 @@
+import cv2
+import numpy as np
+import random
+from PIL import Image, ImageEnhance, ImageFilter
+
+
+class FaceAugmentor:
+    #Low light
+    def low_light(self, face_bgr):
+        face_rgb = cv2.cvtColor(face_bgr, cv2.COLOR_BGR2RGB)
+        img = Image.fromarray(face_rgb)
+
+        img = ImageEnhance.Brightness(img).enhance(0.45)
+        img = ImageEnhance.Contrast(img).enhance(0.7)
+        img = img.filter(ImageFilter.GaussianBlur(radius=1))
+
+        return cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR)
+
+    #Bright light
+    def bright(self, face):
+        return cv2.convertScaleAbs(face, alpha=1.3, beta=10)
+
+    # Contrast 3shan lw camera mokhtlfa
+    def contrast(self, face):
+        return cv2.convertScaleAbs(face, alpha=1.2, beta=0)
+
+    #Color jitter
+    def color_jitter(self, face):
+        hsv = cv2.cvtColor(face, cv2.COLOR_BGR2HSV).astype(np.float32)
+        hsv[..., 1] *= random.uniform(0.8, 1.2)
+        hsv[..., 2] *= random.uniform(0.8, 1.2)
+        hsv = np.clip(hsv, 0, 255).astype(np.uint8)
+        return cv2.cvtColor(hsv, cv2.COLOR_HSV2BGR)
+
+    # ---- Noise (low quality webcam) ----
+    def add_noise(self, face):
+        noise = np.random.normal(0,0.9, face.shape).astype(np.uint8)
+        return cv2.add(face, noise)
+
+
+    #Rotation
+    def rotate(self, face, angle=5):
+        h, w = face.shape[:2]
+        M = cv2.getRotationMatrix2D((w // 2, h // 2), angle, 1.0)
+        return cv2.warpAffine(face, M, (w, h))
+
+    #Partial crop
+    def partial_crop(self, face):
+        h, w = face.shape[:2]
+        return face[int(0.15*h):int(0.9*h), int(0.1*w):int(0.9*w)]
+
+    def generate(self, face):
+        variants = [
+            self.low_light(face),
+            self.bright(face),
+            self.contrast(face),
+            self.color_jitter(face),
+            self.add_noise(face),
+            self.rotate(face, 25),
+            self.rotate(face, -25),
+            self.partial_crop(face),
+        ]
+
+        #random.shuffle(variants)
+        return variants[:7]

helpers/configs.py

@@ -0,0 +1,22 @@
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    APP_NAME: str 
+    APP_VERSION: str 
+    APP_VARIENT: str
+    
+    host:str
+    port:int
+    
+    DETECTION_MODEL:str = "mtcnn"  # Options: mtcnn, yoloface
+
+    YOLOFACE_MODEL_PATH: str = "assets/yolov12n-face.pt"
+    CHROMA_DB_PATH:str = "./chroma_data"
+    COLLECTION_NAME:str = "face_embeddings_collection"
+    SIMILARITY_THRESHOLD:float = 0.7
+    MAX_RESULTS:int = 1
+    class Config: 
+        env_file = ".env" 
+
+def get_settings(): ## this makes any got by "get_settings().APP_NAME" 
+    return Settings()

helpers/db.py

@@ -0,0 +1,29 @@
+import chromadb
+from chromadb.config import Settings
+from helpers.configs import get_settings
+
+# Globals
+chroma_client = None
+chroma_collection = None
+
+
+
+def init_chroma():
+    global chroma_client, chroma_collection
+    settings = get_settings()
+
+    chroma_client = chromadb.PersistentClient(
+        path=settings.CHROMA_DB_PATH
+    )
+
+    chroma_collection = chroma_client.get_or_create_collection(
+        name=settings.COLLECTION_NAME,
+        #        metadata={"hnsw:space": "cosine"}
+        metadata={"hnsw:space": "cosine"}
+    )
+
+    return chroma_client, chroma_collection
+
+
+def get_chroma():
+    return chroma_client, chroma_collection

main.py

@@ -0,0 +1,55 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+from routes import base, data
+from helpers.db import init_chroma, chroma_client
+from helpers.configs import get_settings
+from pathlib import Path
+import os
+import urllib.request
+
+ASSETS_DIR = "assets"
+MODEL_URL = "https://github.com/YapaLab/yolo-face/releases/download/1.0.0/yolov11n-face.pt"
+MODEL_PATH = os.path.join(ASSETS_DIR, "yolov11n-face.pt")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("Initializing ChromaDB...")
+    init_chroma()
+    print("ChromaDB Ready.")
+    if not Path(MODEL_PATH).exists():
+        Path(ASSETS_DIR).mkdir(exist_ok=True)
+        print("⬇ Downloading YOLO face model...")
+        urllib.request.urlretrieve(MODEL_URL, MODEL_PATH)
+        print("Model ready.")
+    else:
+        print("Model already exists.")
+    yield
+    if chroma_client is not None:
+        try:
+            chroma_client.persist()
+            print("ChromaDB persisted & closed.")
+        except:
+            pass
+
+
+app = FastAPI(lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(base.base_router)
+app.include_router(data.data_router)
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    settings = get_settings()
+    print(f"Server running at http://127.0.0.1:{settings.port}")
+    uvicorn.run(app, host=settings.host, port=settings.port)

requirements.txt

@@ -0,0 +1,11 @@
+fastapi==0.124.2
+uvicorn[standard]
+pydantic-settings
+chromadb
+ultralytics
+python-dotenv==1.2.1
+facenet-pytorch==2.6.0
+torch==2.2.2
+torchvision==0.17.2
+opencv-python-headless==4.11.0.86
+python-multipart==0.0.20

routes/base.py

@@ -0,0 +1,46 @@
+from fastapi import APIRouter , Depends
+from helpers.configs import Settings , get_settings
+from helpers.db import get_chroma
+from fastapi.responses import FileResponse
+
+
+base_router = APIRouter(
+    prefix=f"/AutoProctor/{get_settings().APP_VARIENT}",
+    tags=["AutoProctor_v1"]) 
+
+
+@base_router.get("/") 
+async def welcome(app_settings: Settings = Depends(get_settings)):
+        return FileResponse('static/index.html')
+        # app_name = app_settings.APP_NAME
+        # app_varient=app_settings.APP_VARIENT
+        # app_version = app_settings.APP_VERSION
+        # return {"app_name": app_name, "app_version": app_version ,"app_varient":app_varient, "status": "healthy"}
+
+
+@base_router.get('/config')
+async def config(app_settings: Settings = Depends(get_settings)):
+        return {
+                'app_name': app_settings.APP_NAME,
+                'app_version': app_settings.APP_VERSION,
+                'app_variant': app_settings.APP_VARIENT,
+                'detection_model': app_settings.DETECTION_MODEL,
+                'yoloface_model_path': app_settings.YOLOFACE_MODEL_PATH,
+                'chroma_db_path': app_settings.CHROMA_DB_PATH,
+                'collection_name': app_settings.COLLECTION_NAME,
+                'similarity_threshold': app_settings.SIMILARITY_THRESHOLD,
+                'max_results': app_settings.MAX_RESULTS
+        }
+
+
+@base_router.get("/health") 
+async def health(app_settings: Settings = Depends(get_settings)):
+    app_name = app_settings.APP_NAME
+    app_version = app_settings.APP_VERSION
+    return {"app_name": app_name, "app_version": app_version , "status": "healthy"}
+
+
+@base_router.get("/count")
+def count_documents():
+    _, collection = get_chroma()
+    return {"documents": collection.count()}

routes/data.py

@@ -0,0 +1,299 @@
+import asyncio
+from fastapi import APIRouter, UploadFile, WebSocket, File, WebSocketDisconnect ,Depends
+from fastapi.responses import JSONResponse
+import logging
+import cv2
+import numpy as np
+import base64
+from helpers.configs import get_settings, Settings
+from controllers.EmbeddingController import EmbeddingController
+
+logger = logging.getLogger('uvicorn.error')
+
+data_router = APIRouter(
+    prefix=f"/AutoProctor/{get_settings().APP_VARIENT}/data",
+    tags=["AutoProctor_v1"]
+)
+
+# Initialize the embedding controller globally
+embedding_controller = None
+
+
+def get_embedding_controller():
+    global embedding_controller
+    if embedding_controller is None:
+        try:
+            logger.info("Initializing EmbeddingController...")
+            embedding_controller = EmbeddingController(
+                DETECTION_MODEL=get_settings().DETECTION_MODEL,
+                YOLOFACE_MODEL_PATH=get_settings().YOLOFACE_MODEL_PATH
+            )
+            logger.info("EmbeddingController initialized successfully")
+            if not hasattr(embedding_controller, 'collection') or embedding_controller.collection is None:
+                logger.error("Collection not initialized in EmbeddingController!")
+                raise Exception("Collection initialization failed")
+        except Exception as e:
+            logger.error(f"Failed to initialize EmbeddingController: {e}")
+            raise
+    return embedding_controller
+
+
+@data_router.post("/embed/{user_id}")
+async def embed_frame_api(user_id: str, file: UploadFile):
+    try:
+        controller = get_embedding_controller()
+        image = await file.read()
+        nparr = np.frombuffer(image, np.uint8)
+        img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        if img is None:
+            logger.error("Failed to decode image")
+            return JSONResponse(status_code=400, content={"message": "Invalid image format"})
+        faces = controller.detect_faces(img)
+        if not faces:
+            return JSONResponse(status_code=404, content={"message": "No faces detected."})
+        logger.info(f"Detected {len(faces)} face(s) for user_id: {user_id}")
+        for idx, face in enumerate(faces):
+            try:
+                embedding = controller.get_embedding(face)
+                metadata = {"user_id": user_id}
+                controller.add_embedding(face, embedding, metadata)
+                logger.info(f"Added embedding {idx + 1}/{len(faces)} for user_id: {user_id}")
+            except Exception as e:
+                logger.error(f"Error adding embedding {idx + 1} for user_id {user_id}: {e}")
+                raise
+        return {
+            "message": f"Embeddings added for user_id: {user_id}",
+            "num_faces": len(faces)
+        }
+    except Exception as e:
+        logger.error(f"Error in embed_frame_api: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"message": f"Internal server error: {str(e)}"})
+
+
+
+@data_router.post("/delete/{user_id}")
+async def delete_embeddings_api(user_id: str):
+    try:
+        controller = get_embedding_controller()
+        delete_result = controller.delete_embeddings_by_user(user_id)
+        return {
+            "message": f"Deleted embeddings for user_id: {user_id}",
+            "details": delete_result
+        }
+    except Exception as e:
+        logger.error(f"Error in delete_embeddings_api: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"message": f"Internal server error: {str(e)}"})
+
+
+@data_router.post("/update/{user_id}")
+async def update_embeddings_api(user_id: str, file: UploadFile, app_settings: Settings = Depends(get_settings)):
+    try:
+        controller = get_embedding_controller()
+        image_bytes = await file.read()
+        nparr = np.frombuffer(image_bytes, np.uint8)
+        img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        if img is None:
+            return JSONResponse(status_code=400, content={"message": "Invalid image format"})
+        
+        faces = controller.detect_faces(img)
+        if not faces:
+            return JSONResponse(status_code=404, content={"message": "No faces detected."})
+        embeddings = [controller.get_embedding(face) for face in faces]
+        metadata = {"user_id": user_id}
+        controller.update_embeddings(
+            user_id=user_id,
+            faces=faces,
+            embeddings=embeddings,
+            metadata=metadata
+        )
+        return {
+            "message": f"Embeddings updated for user_id: {user_id}",
+            "num_faces": len(faces)
+        }
+    except Exception as e:
+        logger.error(f"Error in update_embeddings_api: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"message": f"Internal server error: {str(e)}"})
+
+
+
+@data_router.post("/detect/frame")
+async def detect_frame_api(file: UploadFile = File(...), app_settings: Settings = Depends(get_settings)):
+    controller = get_embedding_controller()
+    image_bytes = await file.read()
+    nparr = np.frombuffer(image_bytes, np.uint8)
+    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    if img is None:
+        return JSONResponse(status_code=400, content={"message": "Invalid image"})
+    faces = controller.detect_faces(img)
+    if not faces:
+        return JSONResponse(status_code=404, content={"message": "No faces detected"})
+    results = []
+    for face in faces:
+        embedding = controller.get_embedding(face)
+        result = controller.query_embedding(
+            embedding,
+            n_results=app_settings.MAX_RESULTS,
+            threshold=app_settings.SIMILARITY_THRESHOLD
+        )
+        results.append(result)
+    print("Detected : " , results)
+    return {
+        "num_faces": len(faces),
+        "results": results
+    }
+
+
+@data_router.post("/recognize/frame")
+async def detect_frame_api(file: UploadFile = File(...), app_settings: Settings = Depends(get_settings)):
+    controller = get_embedding_controller()
+    image_bytes = await file.read()
+    nparr = np.frombuffer(image_bytes, np.uint8)
+    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    if img is None:
+        return JSONResponse(status_code=400, content={"message": "Invalid image"})
+    results = []
+    embedding = controller.get_embedding(img)
+    result = controller.query_embedding(
+        embedding,
+        n_results=app_settings.MAX_RESULTS,
+        threshold=app_settings.SIMILARITY_THRESHOLD
+    )
+    results.append(result)
+    print(results)
+    return {
+        "results": results
+    }
+
+
+@data_router.websocket("/detect/stream")
+async def detect_stream(websocket: WebSocket):
+    await websocket.accept()
+    logger.info("WebSocket connected")
+    controller = get_embedding_controller()
+    frame_queue: asyncio.Queue = asyncio.Queue(maxsize=1)
+    stop_event = asyncio.Event()
+    frame_count = 0
+
+    async def receiver():
+        """Receive frames and keep ONLY the latest one"""
+        try:
+            while not stop_event.is_set():
+                msg = await websocket.receive()
+
+                if msg.get("type") == "websocket.disconnect":
+                    break
+
+                data = None
+                if msg.get("bytes"):
+                    data = msg["bytes"]
+                elif msg.get("text"):
+                    text = msg["text"]
+                    if text.startswith("data:image"):
+                        text = text.split(",", 1)[1]
+                    data = base64.b64decode(text)
+
+                if not data:
+                    continue
+
+                # Drop old frame if queue is full
+                if frame_queue.full():
+                    try:
+                        frame_queue.get_nowait()
+                    except asyncio.QueueEmpty:
+                        pass
+
+                await frame_queue.put(data)
+
+        except WebSocketDisconnect:
+            logger.info("Receiver: client disconnected")
+        except Exception as e:
+            logger.error(f"Receiver error: {e}", exc_info=True)
+        finally:
+            stop_event.set()
+
+    async def processor():
+        """Process ONLY the latest frame"""
+        nonlocal frame_count
+        try:
+            while not stop_event.is_set():
+                try:
+                    data = await asyncio.wait_for(frame_queue.get(), timeout=0.5)
+                except asyncio.TimeoutError:
+                    continue
+
+                if websocket.client_state.name != "CONNECTED":
+                    break
+
+                # Decode image
+                nparr = np.frombuffer(data, np.uint8)
+                frame = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+                if frame is None:
+                    continue
+
+                frame_count += 1
+
+                # Detect faces
+                try:
+                    faces = controller.detect_faces(frame)
+                    if not faces:
+                        await websocket.send_json({
+                            "frame": frame_count,
+                            "faces_detected": 0
+                        })
+                        continue
+                except Exception as e:
+                    await websocket.send_json({"error": f"detection failed: {e}"})
+                    continue
+
+                # Process faces
+                results = []
+                for face in faces:
+                    try:
+                        emb = controller.get_embedding(face)
+                        res = controller.query_embedding(
+                            emb,
+                            n_results=get_settings().MAX_RESULTS,
+                            threshold=get_settings().SIMILARITY_THRESHOLD
+                        )
+                        results.append(res)
+                    except Exception as e:
+                        results.append({"error": str(e)})
+
+                # Send results
+                try:
+                    await websocket.send_json({
+                        "frame": frame_count,
+                        "faces_detected": len(faces),
+                        "results": results
+                    })
+                except Exception:
+                    break
+
+        except Exception as e:
+            logger.error(f"Processor error: {e}", exc_info=True)
+        finally:
+            stop_event.set()
+
+    # Run tasks
+    recv_task = asyncio.create_task(receiver())
+    proc_task = asyncio.create_task(processor())
+
+    # Wait for receiver to finish (disconnect)
+    await recv_task
+
+    # Stop processor immediately
+    proc_task.cancel()
+
+    try:
+        await proc_task
+    except asyncio.CancelledError:
+        pass
+
+    try:
+        await websocket.close()
+    except Exception:
+        pass
+
+    logger.info(f"WebSocket closed (processed {frame_count} frames)")
+
+

static/index.html

@@ -0,0 +1,355 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <title>FaceRecognition - Live Detection</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh;
+      padding: 20px;
+    }
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      background: white;
+      border-radius: 15px;
+      box-shadow: 0 20px 60px rgba(0,0,0,0.3);
+      overflow: hidden;
+    }
+    .header {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      padding: 30px;
+      text-align: center;
+    }
+    .header h1 { font-size: 2.5em; margin-bottom: 10px; }
+    .content {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 30px;
+      padding: 30px;
+    }
+    .video-section {
+      display: flex;
+      flex-direction: column;
+      gap: 15px;
+    }
+    .video-container {
+      position: relative;
+      width: 100%;
+      background: #000;
+      border-radius: 10px;
+      overflow: hidden;
+      aspect-ratio: 4/3;
+    }
+    video {
+      width: 100%;
+      height: 100%;
+      object-fit: cover;
+    }
+    .controls {
+      display: flex;
+      gap: 10px;
+      flex-wrap: wrap;
+    }
+    button {
+      flex: 1;
+      min-width: 120px;
+      padding: 12px 20px;
+      border: none;
+      border-radius: 8px;
+      font-size: 1em;
+      font-weight: 600;
+      cursor: pointer;
+      transition: all 0.3s ease;
+    }
+    button:hover:not(:disabled) { transform: translateY(-2px); box-shadow: 0 5px 15px rgba(0,0,0,0.2); }
+    button:disabled { opacity: 0.5; cursor: not-allowed; }
+    .btn-detect { background: #4CAF50; color: white; }
+    .btn-start { background: #2196F3; color: white; }
+    .btn-stop { background: #f44336; color: white; }
+    .btn-embed { background: #FF9800; color: white; }
+    .output-section {
+      display: flex;
+      flex-direction: column;
+      gap: 15px;
+    }
+    .output-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    .status-badge {
+      padding: 8px 15px;
+      border-radius: 20px;
+      font-weight: 600;
+      font-size: 0.9em;
+    }
+    .status-connected { background: #4CAF50; color: white; }
+    .status-disconnected { background: #999; color: white; }
+    .status-idle { background: #2196F3; color: white; }
+    #output {
+      flex: 1;
+      background: #f5f5f5;
+      border: 2px solid #ddd;
+      border-radius: 8px;
+      padding: 15px;
+      font-family: 'Courier New', monospace;
+      font-size: 0.9em;
+      overflow: auto;
+      max-height: 400px;
+      white-space: pre-wrap;
+      word-wrap: break-word;
+    }
+    .input-group {
+      display: flex;
+      gap: 10px;
+    }
+    input[type="text"] {
+      flex: 1;
+      padding: 10px;
+      border: 2px solid #ddd;
+      border-radius: 8px;
+      font-size: 1em;
+    }
+    .stats {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      gap: 10px;
+      margin-top: 10px;
+    }
+    .stat-box {
+      background: #f0f0f0;
+      padding: 10px;
+      border-radius: 8px;
+      text-align: center;
+    }
+    .stat-label { font-size: 0.8em; color: #666; }
+    .stat-value { font-size: 1.5em; font-weight: bold; color: #333; }
+    @media (max-width: 768px) {
+      .content { grid-template-columns: 1fr; }
+      .header h1 { font-size: 1.8em; }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="header">
+      <h1>🔍 FaceRecognition - Live Detection</h1>
+      <p>Real-time face detection and recognition via WebSocket</p>
+    </div>
+    
+    <div class="content">
+      <div class="video-section">
+        <div class="video-container">
+          <video id="video" autoplay muted playsinline></video>
+        </div>
+        <div class="controls">
+          <button id="snap" class="btn-detect">📸 Single Frame</button>
+          <button id="startStream" class="btn-start">▶️ Start Stream</button>
+          <button id="stopStream" class="btn-stop" disabled>⏹️ Stop Stream</button>
+        </div>
+        <div class="input-group">
+          <input type="text" id="userId" placeholder="Enter user ID (optional)" />
+          <button id="embedBtn" class="btn-embed">➕ Embed</button>
+        </div>
+      </div>
+      
+      <div class="output-section">
+        <div class="output-header">
+          <h3>📊 Results</h3>
+          <span id="status" class="status-badge status-idle">⚪ Idle</span>
+        </div>
+        <div id="output">Waiting for input...</div>
+        <div class="stats">
+          <div class="stat-box">
+            <div class="stat-label">Frames Sent</div>
+            <div class="stat-value" id="frameCount">0</div>
+          </div>
+          <div class="stat-box">
+            <div class="stat-label">Faces Detected</div>
+            <div class="stat-value" id="faceCount">0</div>
+          </div>
+          <div class="stat-box">
+            <div class="stat-label">Connection</div>
+            <div class="stat-value" id="connStatus">—</div>
+          </div>
+          <div class="stat-box">
+            <div class="stat-label">FPS</div>
+            <div class="stat-value" id="fpsCount">0</div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <script>
+    const pathParts = location.pathname.split('/').filter(p => p.length > 0);
+    let variant = 'v1';
+    if (pathParts.length >= 2 && pathParts[0].toLowerCase().includes('autoproctor')) {
+      variant = pathParts[1] || variant;
+    }
+
+    const video = document.getElementById('video');
+    const snapBtn = document.getElementById('snap');
+    const startBtn = document.getElementById('startStream');
+    const stopBtn = document.getElementById('stopStream');
+    const embedBtn = document.getElementById('embedBtn');
+    const userIdInput = document.getElementById('userId');
+    const output = document.getElementById('output');
+    const statusBadge = document.getElementById('status');
+    const frameCountEl = document.getElementById('frameCount');
+    const faceCountEl = document.getElementById('faceCount');
+    const connStatusEl = document.getElementById('connStatus');
+    const fpsCountEl = document.getElementById('fpsCount');
+
+    let ws = null;
+    let streamRunning = false;
+    let frameCount = 0;
+    let totalFaceCount = 0;
+    let lastFrameTime = 0;
+
+    function updateStatus(text, cssClass) {
+      statusBadge.textContent = text;
+      statusBadge.className = `status-badge ${cssClass}`;
+    }
+
+    function logOutput(msg) {
+      output.textContent = typeof msg === 'string' ? msg : JSON.stringify(msg, null, 2);
+      output.scrollTop = output.scrollHeight;
+    }
+
+    navigator.mediaDevices.getUserMedia({ video: true, audio: false })
+      .then(s => { video.srcObject = s; updateStatus('✓ Camera Ready', 'status-idle'); })
+      .catch(e => { logOutput('❌ Camera error: ' + e); updateStatus('✗ Camera Failed', 'status-disconnected'); });
+
+    function canvasToBase64() {
+      const c = document.createElement('canvas');
+      c.width = video.videoWidth || 640;
+      c.height = video.videoHeight || 480;
+      const ctx = c.getContext('2d');
+      ctx.drawImage(video, 0, 0, c.width, c.height);
+      return c.toDataURL('image/jpeg', 0.85).split(',')[1]; // Return only base64 part
+    }
+
+    snapBtn.onclick = async () => {
+      try {
+        updateStatus('Processing...', 'status-idle');
+        const base64 = canvasToBase64();
+        const blob = Uint8Array.from(atob(base64), c => c.charCodeAt(0));
+        const fd = new FormData();
+        fd.append('file', new Blob([blob], { type: 'image/jpeg' }), 'frame.jpg');
+        const res = await fetch(`/AutoProctor/${variant}/data/detect/frame`, { method: 'POST', body: fd });
+        const j = await res.json();
+        logOutput(j);
+        const facesDetected = j.results ? j.results.ids?.length || 0 : 0;
+        totalFaceCount += facesDetected;
+        faceCountEl.textContent = totalFaceCount;
+        updateStatus('✓ Result Ready', 'status-connected');
+      } catch (e) {
+        logOutput('❌ Error: ' + e.message);
+        updateStatus('✗ Error', 'status-disconnected');
+      }
+    };
+
+    startBtn.onclick = async () => {
+      if (ws) { ws.close(); ws = null; }
+      const protocol = location.protocol === 'https:' ? 'wss' : 'ws';
+      const url = `${protocol}://${location.host}/AutoProctor/${variant}/data/detect/stream`;
+      console.log('Connecting to:', url);
+      
+      ws = new WebSocket(url);
+      ws.onopen = () => {
+        logOutput('🟢 WebSocket Connected');
+        updateStatus('🟢 Connected', 'status-connected');
+        connStatusEl.textContent = 'Online';
+        startBtn.disabled = true;
+        stopBtn.disabled = false;
+        frameCount = 0;
+        lastFrameTime = Date.now();
+        streamRunning = true;
+        sendFrames();
+      };
+      
+      ws.onmessage = (ev) => {
+        try {
+          const d = JSON.parse(ev.data);
+          logOutput(d);
+          if (d.faces_detected) {
+            totalFaceCount += d.faces_detected;
+            faceCountEl.textContent = totalFaceCount;
+          }
+          // Update FPS
+          const now = Date.now();
+          if (lastFrameTime > 0) {
+            const fps = Math.round(1000 / (now - lastFrameTime));
+            fpsCountEl.textContent = fps;
+          }
+          lastFrameTime = now;
+        } catch (e) {
+          logOutput('⚠️ ' + ev.data);
+        }
+      };
+      
+      ws.onerror = (err) => {
+        logOutput('❌ WebSocket error: ' + err);
+        updateStatus('✗ Error', 'status-disconnected');
+      };
+      
+      ws.onclose = () => {
+        logOutput('🔴 WebSocket Closed');
+        updateStatus('⚪ Disconnected', 'status-disconnected');
+        connStatusEl.textContent = 'Offline';
+        startBtn.disabled = false;
+        stopBtn.disabled = true;
+        streamRunning = false;
+      };
+    };
+
+    async function sendFrames() {
+      while (streamRunning && ws && ws.readyState === 1) {
+        const base64 = canvasToBase64();
+        frameCount++;
+        frameCountEl.textContent = frameCount;
+        try {
+          ws.send(base64);
+        } catch (e) {
+          console.error('Send error:', e);
+          break;
+        }
+        await new Promise(r => setTimeout(r, 2000)); //  F  P  2S
+      }
+    }
+
+    stopBtn.onclick = () => {
+      streamRunning = false;
+      if (ws) { ws.close(); }
+    };
+
+    embedBtn.onclick = async () => {
+      const userId = userIdInput.value.trim();
+      if (!userId) {
+        logOutput('❌ Please enter a user ID');
+        return;
+      }
+      try {
+        updateStatus('Embedding...', 'status-idle');
+        const base64 = canvasToBase64();
+        const blob = Uint8Array.from(atob(base64), c => c.charCodeAt(0));
+        const fd = new FormData();
+        fd.append('file', new Blob([blob], { type: 'image/jpeg' }), 'frame.jpg');
+        const res = await fetch(`/AutoProctor/${variant}/data/embed/${userId}`, { method: 'POST', body: fd });
+        const j = await res.json();
+        logOutput(j);
+        updateStatus('✓ Embedded', 'status-connected');
+      } catch (e) {
+        logOutput('❌ Embedding error: ' + e.message);
+        updateStatus('✗ Error', 'status-disconnected');
+      }
+    };
+  </script>
+</body>
+</html>