README.md

metadata

title: VisionAttend API
emoji: 👁️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

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

   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.

   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.

   python init_db.py
   

4. Launch Server

   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:

python test_core_flows.py

GitHub Actions Automation

This repository includes GitHub Actions workflows for Hugging Face Spaces deployment and keep-alive automation.

• HF_TOKEN: required by the deploy workflow to push backend/ to the Space repository.
• HF_SPACE_URL: required by the keep-alive workflow and should point to the public app domain.

The keep-alive workflow runs every 6 hours and sends a lightweight request to / so the free Space does not go inactive due to lack of traffic.