Implemented the first version of the application, handled the UI, face recognition, and database handling

Dockerfile

@@ -0,0 +1,36 @@
+# Use the official Python 3.10 image as a base
+FROM python:3.10-slim
+
+# Install necessary system dependencies for OpenCV and other heavy ML tools
+# DeepFace and OpenCV require libgl1 and libglib2.0
+RUN apt-get update && apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory to /app
+WORKDIR /app
+
+# Copy requirement files first to cache dependencies correctly
+COPY requirements.txt .
+
+# Install dependencies using pip
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Create a non-root user required by Hugging Face Spaces environment
+# Since HF Spaces run on port 7860 by default under non-root
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR $HOME/app
+
+# Copy the rest of the application files in the directory
+COPY --chown=user . $HOME/app
+
+# Hugging Face Spaces expose port 7860 by default
+EXPOSE 7860
+
+# Run uvicorn on port 7860, bound to 0.0.0.0
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,64 @@
+# VisionAttend Backend
+
+The backend of `VisionAttend` handles the computational heavy lifting. It exposes the API endpoints necessary for student management and uses a DeepFace model for instantaneous facial embedding extraction.
+
+## Features
+
+- **FastAPI Core**: Utilizes asynchronous endpoints for maximum concurrency.
+- **DeepFace Integration**: Leverages the `Facenet` model for robust 128-dimensional encodings. Uses the `opencv` detector backend for rapid alignment performance compared to `retinaface` or `mtcnn`.
+- **Postgres pgvector Matchmaking**: Embeddings are stored in Neon Postgres using `pgvector`. A student is recognized instantly using the `<=>` cosine distance operator to find the closest match under a set confidence threshold (0.40).
+
+## Requirements
+
+Before starting, ensure you have a standard Python 3.10+ environment.
+
+- `fastapi`
+- `uvicorn`
+- `deepface`
+- `psycopg` (with pool and pgvector integration)
+- `python-dotenv`
+- `numpy` & `pillow`
+
+## Setup & Running
+
+1. **Virtual Environment Setup**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   ```
+
+2. **Environment Configuration**
+   Create a `.env` file referencing your Neon Postgres database containing the `pgvector` extension.
+   ```env
+   DATABASE_URL="postgres://user:password@host/dbname?sslmode=require"
+   ```
+
+3. **Initialize the Database**
+   Before running the app, execute the init script to build the exact table architecture needed.
+   ```bash
+   python init_db.py
+   ```
+
+4. **Launch Server**
+   ```bash
+   uvicorn main:app --reload --port 8000
+   ```
+
+## REST API Overview
+
+All routes accept appropriate `multipart/form-data` for image payloads or generic `application/json` strings.
+
+- `POST /api/register`: Stores a new student photo representation.
+- `POST /api/recognize`: Validates a live frame against existing students and marks attendance.
+- `GET /api/attendance`: Retrieves attendance logs, optionally filtered by `?date_filter=YYYY-MM-DD`.
+- `PUT /api/students/{id}`: Manual override to rename or change a roll number.
+- `DELETE /api/students/{id}`: Purges a student and all historical logs.
+- `POST /api/attendance/manual`: Enables manual toggling of "Present" status without the camera.
+
+## Testing
+
+A programmatic integration test suite mimicking camera requests is available:
+```bash
+python test_core_flows.py
+```

init_db.py

@@ -0,0 +1,56 @@
+import os
+import psycopg
+from dotenv import load_dotenv
+
+load_dotenv()
+
+DATABASE_URL = os.getenv("DATABASE_URL")
+
+if not DATABASE_URL:
+    raise ValueError("DATABASE_URL environment variable is not set")
+
+print(f"Connecting to database...")
+
+def init_db():
+    try:
+        # Connect to the Neon database
+        with psycopg.connect(DATABASE_URL) as conn:
+            with conn.cursor() as cur:
+                print("Connected! Enabling vector extension...")
+                cur.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+                
+                print("Creating students table...")
+                cur.execute("""
+                    CREATE TABLE IF NOT EXISTS students (
+                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                        name VARCHAR(255) NOT NULL,
+                        roll_number VARCHAR(100) UNIQUE NOT NULL,
+                        -- Note: We use an arbitrary vector dimension size
+                        -- However, we must specify the exact dimension if we want pgvector HNSW index.
+                        -- dlib face embeddings (used by face_recognition) are 128 dimensions.
+                        -- deepface (VGG-Face) is 2622, Facenet is 128, ArcFace is 512, Datashape is 512.
+                        -- By default deepface uses VGG-Face (2622) or Facenet (128). Let's use 128 (Facenet or Dlib) or we can leave it dynamic without dimension limit.
+                        -- Since we switched to deepface, let's just use `vector` (dynamic)
+                        face_encoding vector NOT NULL,
+                        created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+                    );
+                """)
+                
+                print("Creating attendance table...")
+                cur.execute("""
+                    CREATE TABLE IF NOT EXISTS attendance (
+                        id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                        student_id UUID REFERENCES students(id) ON DELETE CASCADE,
+                        timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+                        status VARCHAR(50) DEFAULT 'Present'
+                    );
+                """)
+                
+                conn.commit()
+                print("Database initialized successfully!")
+                
+    except Exception as e:
+        print(f"Error initializing database: {e}")
+
+if __name__ == "__main__":
+    init_db()

main.py

@@ -0,0 +1,317 @@
+import os
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+import psycopg
+from pgvector.psycopg import register_vector
+import numpy as np
+import uuid
+import io
+from PIL import Image
+from deepface import DeepFace
+from datetime import date
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = FastAPI(title="VisionAttend API")
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, replace with frontend URL
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+DATABASE_URL = os.getenv("DATABASE_URL")
+
+class MatchResponse(BaseModel):
+    message: str
+    student_name: str
+    roll_number: str
+
+from psycopg_pool import ConnectionPool
+
+def configure_conn(conn):
+    register_vector(conn)
+
+# By using a ConnectionPool, we keep the TCP connection alive to Neon.
+# This eliminates the ~6-8 second TLS/SSL handshake delay on every request.
+db_pool = ConnectionPool(
+    conninfo=DATABASE_URL, 
+    configure=configure_conn, 
+    min_size=1, 
+    max_size=5,
+    timeout=30.0
+)
+
+def get_db_connection():
+    return db_pool.connection()
+
+def extract_face_embedding(file_bytes: bytes) -> tuple[list[float], str]:
+    try:
+        image = Image.open(io.BytesIO(file_bytes)).convert("RGB")
+        img_array = np.array(image)
+        
+        results = DeepFace.represent(
+            img_path=img_array, 
+            enforce_detection=True, 
+            model_name="Facenet",
+            detector_backend="opencv"
+        )
+        
+        if len(results) == 0:
+            raise ValueError("No face detected.")
+        if len(results) > 1:
+            raise ValueError("Multiple faces detected. Please show only one face.")
+            
+        embedding = results[0]["embedding"]
+        return embedding, "success"
+    except ValueError as ve:
+        return [], str(ve)
+    except Exception as e:
+        return [], f"An error occurred during face extraction: {str(e)}"
+
+@app.post("/api/register")
+async def register_student(
+    name: str = Form(...),
+    roll_number: str = Form(...),
+    image: UploadFile = File(...)
+):
+    file_bytes = await image.read()
+    
+    embedding, error = extract_face_embedding(file_bytes)
+    if not embedding:
+        raise HTTPException(status_code=400, detail=error)
+        
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT id FROM students WHERE roll_number = %s", (roll_number,))
+                if cur.fetchone():
+                    raise HTTPException(status_code=400, detail="Student with this roll number already exists.")
+                    
+                cur.execute(
+                    "INSERT INTO students (name, roll_number, face_encoding) VALUES (%s, %s, %s) RETURNING id",
+                    (name, roll_number, str(embedding))
+                )
+                student_id = cur.fetchone()[0]
+                conn.commit()
+                
+        return {"message": "Student registered successfully", "student_id": student_id}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+
+@app.post("/api/recognize", response_model=MatchResponse)
+async def recognize_student(image: UploadFile = File(...)):
+    file_bytes = await image.read()
+    
+    embedding, error = extract_face_embedding(file_bytes)
+    if not embedding:
+        raise HTTPException(status_code=400, detail=error)
+        
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("""
+                    SELECT id, name, roll_number, (face_encoding <=> %s::vector) AS distance
+                    FROM students
+                    ORDER BY distance ASC
+                    LIMIT 1;
+                """, (str(embedding),))
+                
+                result = cur.fetchone()
+                
+                if not result:
+                    raise HTTPException(status_code=404, detail="No match found in database.")
+                    
+                student_id, name, roll_number, distance = result
+                print(f"Discovered {name} with distance {distance}")
+                
+                if distance > 0.40: # Threshold for Facenet
+                    raise HTTPException(status_code=404, detail="Face recognized but distance exceeds confidence threshold.")
+                    
+                cur.execute("""
+                    SELECT id FROM attendance 
+                    WHERE student_id = %s AND timestamp::date = %s
+                """, (student_id, date.today()))
+                
+                if not cur.fetchone():
+                    cur.execute(
+                        "INSERT INTO attendance (student_id, status) VALUES (%s, 'Present')",
+                        (student_id,)
+                    )
+                    conn.commit()
+                    message = "Attendance marked."
+                else:
+                    message = "Attendance already marked for today."
+                    
+                return MatchResponse(message=message, student_name=name, roll_number=roll_number)
+                
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+@app.get("/api/attendance")
+async def get_attendance(date_filter: str = None):
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                if date_filter:
+                    cur.execute("""
+                        SELECT s.id, s.name, s.roll_number, a.timestamp, 
+                               CASE WHEN a.id IS NOT NULL THEN 'Present' ELSE 'Absent' END as status,
+                               s.id as student_id
+                        FROM students s
+                        LEFT JOIN attendance a ON s.id = a.student_id AND DATE(a.timestamp) = %s
+                        ORDER BY 
+                            CASE WHEN a.id IS NOT NULL THEN 0 ELSE 1 END,
+                            s.name ASC
+                        LIMIT 100;
+                    """, (date_filter,))
+                    rows = cur.fetchall()
+                    logs = [
+                        {
+                            "id": str(row[0]),
+                            "name": row[1],
+                            "roll_number": row[2],
+                            "timestamp": row[3],
+                            "status": row[4],
+                            "student_id": str(row[5])
+                        } for row in rows
+                    ]
+                else:
+                    cur.execute("""
+                        SELECT a.id, s.name, s.roll_number, a.timestamp, a.status, s.id as student_id
+                        FROM attendance a
+                        JOIN students s ON a.student_id = s.id
+                        ORDER BY a.timestamp DESC
+                        LIMIT 100;
+                    """)
+                    rows = cur.fetchall()
+                    logs = [
+                        {
+                            "id": str(row[0]),
+                            "name": row[1],
+                            "roll_number": row[2],
+                            "timestamp": row[3],
+                            "status": row[4],
+                            "student_id": str(row[5])
+                        } for row in rows
+                    ]
+                return {"logs": logs}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+class StudentUpdate(BaseModel):
+    name: str
+    roll_number: str
+
+@app.put("/api/students/{student_id}")
+async def update_student(student_id: uuid.UUID, data: StudentUpdate):
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT id FROM students WHERE roll_number = %s AND id != %s", (data.roll_number, student_id))
+                if cur.fetchone():
+                    raise HTTPException(status_code=400, detail="Another student with this roll number already exists.")
+                
+                cur.execute(
+                    "UPDATE students SET name = %s, roll_number = %s WHERE id = %s RETURNING id",
+                    (data.name, data.roll_number, student_id)
+                )
+                if not cur.fetchone():
+                    raise HTTPException(status_code=404, detail="Student not found.")
+                conn.commit()
+                return {"message": "Student updated successfully."}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+@app.delete("/api/students/{student_id}")
+async def delete_student(student_id: uuid.UUID):
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute("DELETE FROM students WHERE id = %s RETURNING id", (student_id,))
+                if not cur.fetchone():
+                    raise HTTPException(status_code=404, detail="Student not found.")
+                conn.commit()
+                return {"message": "Student deleted successfully."}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+@app.put("/api/students/{student_id}/photo")
+async def update_student_photo(student_id: uuid.UUID, image: UploadFile = File(...)):
+    file_bytes = await image.read()
+    embedding, error = extract_face_embedding(file_bytes)
+    if not embedding:
+        raise HTTPException(status_code=400, detail=error)
+        
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "UPDATE students SET face_encoding = %s WHERE id = %s RETURNING id",
+                    (str(embedding), student_id)
+                )
+                if not cur.fetchone():
+                    raise HTTPException(status_code=404, detail="Student not found.")
+                conn.commit()
+                return {"message": "Student photo updated successfully."}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+class ManualAttendance(BaseModel):
+    student_id: uuid.UUID
+    date: str  # YYYY-MM-DD
+    status: str # "Present" or "Absent"
+
+@app.post("/api/attendance/manual")
+async def mark_manual_attendance(data: ManualAttendance):
+    try:
+        with get_db_connection() as conn:
+            with conn.cursor() as cur:
+                if data.status == "Present":
+                    cur.execute("""
+                        SELECT id FROM attendance 
+                        WHERE student_id = %s AND timestamp::date = %s
+                    """, (data.student_id, data.date))
+                    
+                    if not cur.fetchone():
+                        cur.execute(
+                            "INSERT INTO attendance (student_id, status, timestamp) VALUES (%s, 'Present', %s)",
+                            (data.student_id, f"{data.date} 12:00:00") # Default to noon for manual entries
+                        )
+                        conn.commit()
+                        return {"message": "Marked present successfully."}
+                    else:
+                        return {"message": "Already marked present for this date."}
+                elif data.status == "Absent":
+                    cur.execute("""
+                        DELETE FROM attendance 
+                        WHERE student_id = %s AND timestamp::date = %s
+                    """, (data.student_id, data.date))
+                    conn.commit()
+                    return {"message": "Marked absent successfully."}
+                else:
+                    raise HTTPException(status_code=400, detail="Invalid status.")
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+@app.get("/")
+def read_root():
+    return {"status": "ok", "message": "VisionAttend API is active"}

requirements.txt

@@ -0,0 +1,11 @@
+fastapi
+uvicorn
+psycopg[binary]
+pgvector
+python-multipart
+numpy
+deepface
+tf-keras
+pydantic
+python-dotenv
+cors

test_core_flows.py

@@ -0,0 +1,132 @@
+import requests
+import os
+import sys
+import uuid
+from datetime import date
+
+# Base URL for the FastAPI server
+BASE_URL = "http://localhost:8000"
+
+# Path to the test image
+IMAGE_PATH = "test_face.jpg"
+
+def download_test_image():
+    if not os.path.exists(IMAGE_PATH):
+        print(f"Downloading test image to {IMAGE_PATH}...")
+        url = "https://raw.githubusercontent.com/opencv/opencv/master/samples/data/lena.jpg"
+        response = requests.get(url)
+        if response.status_code == 200:
+            with open(IMAGE_PATH, 'wb') as f:
+                f.write(response.content)
+            print("Downloaded successfully.")
+        else:
+            print("Failed to download test image.")
+            sys.exit(1)
+
+def run_tests():
+    print("--- VisionAttend Integration Tests ---")
+    
+    # Generate unique roll number to avoid constraint errors
+    roll_number = f"TEST-{uuid.uuid4().hex[:6].upper()}"
+    student_name = "Test Student"
+    student_id = None
+    
+    print("\n[1] Testing Registration...")
+    try:
+        with open(IMAGE_PATH, 'rb') as f:
+            files = {'image': (IMAGE_PATH, f, 'image/jpeg')}
+            data = {'name': student_name, 'roll_number': roll_number}
+            response = requests.post(f"{BASE_URL}/api/register", data=data, files=files)
+            
+            if response.status_code == 200:
+                result = response.json()
+                student_id = result.get('student_id')
+                print(f"✅ Registration successful. Student ID: {student_id}")
+            else:
+                print(f"❌ Registration failed: {response.text}")
+                return
+    except Exception as e:
+        print(f"❌ Registration exception: {e}")
+        return
+
+    print("\n[2] Testing Recognition & Attendance Marking...")
+    try:
+        with open(IMAGE_PATH, 'rb') as f:
+            files = {'image': (IMAGE_PATH, f, 'image/jpeg')}
+            response = requests.post(f"{BASE_URL}/api/recognize", files=files)
+            
+            if response.status_code == 200:
+                result = response.json()
+                print(f"✅ Recognition successful: {result['message']} - {result['student_name']} ({result['roll_number']})")
+                assert result['roll_number'] == roll_number
+            else:
+                print(f"❌ Recognition failed: {response.text}")
+    except Exception as e:
+         print(f"❌ Recognition exception: {e}")
+
+    print("\n[3] Testing Attendance Logs Query...")
+    try:
+        today_str = date.today().strftime("%Y-%m-%d")
+        response = requests.get(f"{BASE_URL}/api/attendance?date_filter={today_str}")
+        if response.status_code == 200:
+            logs = response.json().get('logs', [])
+            found = False
+            for log in logs:
+                if log.get('student_id') == str(student_id):
+                    found = True
+                    print(f"✅ Found student in logs. Status: {log.get('status')}")
+                    assert log.get('status') == 'Present'
+                    break
+            if not found:
+                print("❌ Student not found in attendance logs.")
+        else:
+           print(f"❌ Attendance query failed: {response.text}")
+    except Exception as e:
+         print(f"❌ Attendance query exception: {e}")
+
+    print("\n[4] Testing Manual Attendance Update...")
+    try:
+        data = {
+            "student_id": str(student_id),
+            "date": date.today().strftime("%Y-%m-%d"),
+            "status": "Absent"
+        }
+        response = requests.post(f"{BASE_URL}/api/attendance/manual", json=data)
+        if response.status_code == 200:
+            print("✅ Manual attendance marked successfully.")
+        else:
+            print(f"❌ Manual attendance failed: {response.text}")
+    except Exception as e:
+         print(f"❌ Manual attendance exception: {e}")
+
+    print("\n[5] Testing Student Details Update...")
+    try:
+        new_name = "Updated Test Student"
+        # We'll use the same roll_number as checking existing logic
+        data = {
+            "name": new_name,
+            "roll_number": roll_number
+        }
+        response = requests.put(f"{BASE_URL}/api/students/{student_id}", json=data)
+        if response.status_code == 200:
+            print("✅ Student details updated successfully.")
+        else:
+            print(f"❌ Student detail update failed: {response.text}")
+    except Exception as e:
+         print(f"❌ Student detail update exception: {e}")
+
+    print("\n[6] Testing Student Deletion (Cleanup)...")
+    if student_id:
+        try:
+             response = requests.delete(f"{BASE_URL}/api/students/{student_id}")
+             if response.status_code == 200:
+                  print("✅ Student deleted successfully.")
+             else:
+                  print(f"❌ Student deletion failed: {response.text}")
+        except Exception as e:
+             print(f"❌ Student deletion exception: {e}")
+
+
+if __name__ == "__main__":
+    download_test_image()
+    run_tests()

test_db.py

@@ -0,0 +1,14 @@
+import psycopg
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+db_url = os.environ.get("DATABASE_URL")
+
+conn = psycopg.connect(db_url)
+print("Connected.", conn.closed)
+
+with conn:
+    print("Inside with block")
+    
+print("After with block, closed:", conn.closed)