title	FaceID - Real-Time Recognition & Verification Suite
emoji	🛡️
colorFrom	blue
colorTo	indigo
sdk	docker
short_description	Real-time face recognition & verification engine demo
pinned	false
license	mit

FaceID Recognition Engine - Hugging Face Space Edition

Project Overview

This repository contains a professional Face Verification system. Milestone 4 represents the final "Release" version, featuring a FaceNet-based inference pipeline, comprehensive hardware profiling, and a professional System Card.

🚀 Quick Start & Grader Instructions (Final Release)

1. Local Environment Setup

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install tf-keras

2. Run Inference CLI (Copy-Pastable)

You can run the verification CLI using the final calibrated threshold (0.35). Note: We have provided sample images in the repository for quick testing.

Test Same Identity (Should output SAME):

python scripts/inference.py --img1 reports/roc_curve.png --img2 reports/roc_curve.png

Test Different Identities (Should output DIFFERENT):

python scripts/inference.py --img1 reports/roc_curve.png --img2 reports/false_positives_examples.png

3. Interactive Web Dashboard

Explore the system, view profiling charts, and test custom images via the Streamlit dashboard:

streamlit run scripts/app.py

4. Dockerized Deployment (Alternative)

To verify the system in an isolated container:

# Build the image
docker build -t faceid-final .

# Run inference inside the container
docker run --rm faceid-final --img1 reports/roc_curve.png --img2 reports/false_positives_examples.png

📊 Final Documentation (Milestone 4)

• System Card: Detailed overview of model design, intended use, and fairness.
• Profiling Report: Breakdown of CPU latency and batch-size sensitivity.
• Reproducibility Checklist: Step-by-step guide to reproduce all project results.

Key Features

• State-of-the-Art Representations: Uses FaceNet (InceptionResNetV1) for robust face verification.
• Calibrated Confidence: Similarity scores are mapped to a human-readable confidence interval [0.5, 1.0].
• Production Ready: Fully containerized via Docker with optimized CPU performance.
• Hardware Aware: Detailed profiling provided for deployment planning.

Repository Layout

• configs/: Final release configuration (eval_ms4_final.yaml).
• reports/: System Card, Profiling Report, and Checklists.
• scripts/: Final inference, profiling, and evaluation entry points.
• src/: Core logic for embeddings, similarity, and evaluation.
• Dockerfile: Containerization setup for final release.

Reproducibility

This project follows strict reproducibility standards. To verify the system from a fresh clone, please refer to the Reproducibility Checklist.

Versioning

• Current Version: v1.0-final (Tagged in Git)

License

This project is licensed under the MIT License - see the LICENSE file for details.