Face AI

State-of-the-art unbiased facial recognition system.

Overview

Face AI is a comprehensive facial recognition pipeline designed with a focus on fairness and bias mitigation. It integrates state-of-the-art detection and recognition models with advanced fairness-aware techniques to ensure equitable performance across different demographic groups.

Key Features

• Unified Pipeline: Seamless integration of face detection, alignment, embedding extraction, and recognition.
• Fairness-First Design: Built-in bias detection and mitigation strategies.
• Demographic Calibration: Tools to calibrate thresholds per demographic group to ensure equal error rates.
• Production Ready: Designed for deployment with optimized Docker builds and robust error handling.

Installation

Prerequisites

• Python 3.9+
• Docker (optional, for containerized deployment)

Local Setup

1. Clone the repository:

   git clone https://github.com/yourusername/face-ai.git
   cd face-ai

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -e .

   For development dependencies:

   pip install -e ".[dev]"

Usage

Basic Example

from face_ai.core.pipeline import FaceAIPipeline

# Initialize the pipeline
pipeline = FaceAIPipeline()

# Detect faces
faces = pipeline.detect_faces("path/to/image.jpg")
print(f"Detected {len(faces)} faces")

# Verify identity
is_same, score = pipeline.verify("photo1.jpg", "photo2.jpg")
print(f"Match: {is_same}, Score: {score}")

Fairness Aware Recognition

from face_ai.core.pipeline import FaceAIPipeline

pipeline = FaceAIPipeline(enable_fairness=True)

# Register identity with metadata
pipeline.register_identity(
    name="user_123",
    images=["user_photo.jpg"],
    metadata={"demographic": "group_a"}
)

# Generate fairness report
report = pipeline.get_fairness_report()
print(report)

Configuration

Runtime settings are loaded from environment variables (edge, API, Docker):

Variable	Default	Description
FACE_AI_THRESHOLD	0.5	Cosine similarity match threshold
FACE_AI_MODEL_PACK	buffalo_l	InsightFace model pack
FACE_AI_DEVICE	cpu	cpu or cuda
FACE_AI_GALLERY_FUSION	max	max, mean, or quality_weighted
FACE_AI_STORAGE_BACKEND	memory	memory or qdrant
FACE_AI_MAX_FACES	10	Max faces per image
FACE_AI_MIN_QUALITY_SCORE	0.35	Min face quality for enrollment
FACE_AI_TARGET_FAR	0.001	Target false positive rate for calibration
FACE_AI_CALIBRATION_PATH	data/calibration.json	Saved threshold calibration
FACE_AI_CALIBRATION_DIR	—	Server directory with pairs.csv for API /calibrate
FACE_AI_REQUIRE_LIVENESS_VERIFY	false	Require liveness on /verify by default
FACE_AI_LIVENESS_FAIL_CLOSED	true	Reject when anti-spoof model unavailable
FACE_AI_LIVENESS_MODEL	liveness/minifasnet.onnx	ONNX path under FACE_AI_MODEL_PATH

from face_ai.core.pipeline import FaceAIPipeline
from face_ai.config import get_settings

pipeline = FaceAIPipeline.from_settings(get_settings())

API endpoints (Phase 2)

Method	Path	Description
POST	/liveness	Anti-spoof check per face
POST	/verify?require_liveness=true	1:1 verify with liveness gate
POST	/calibrate	Threshold calibration from FACE_AI_CALIBRATION_DIR
GET	/calibration	Current calibrated threshold

Place MiniFASNet ONNX at models/liveness/minifasnet.onnx for silent anti-spoof.

Threshold calibration

# Offline calibration
python benchmarks/calibrate_threshold.py --data-dir data/calibration

# Verification benchmark
python benchmarks/run_verification.py --dataset lfw --data-dir /path/to/lfw

Benchmarks

Measure verification accuracy on standard datasets (requires downloaded LFW / CFP-FP):

pip install scikit-learn  # if not already installed
python benchmarks/run_verification.py --dataset lfw --data-dir /path/to/lfw

Reports accuracy at EER threshold, EER, ROC AUC, and TAR@FAR=1e-3.

Testing

Run the test suite using pytest:

pytest

Docker Support

Build and run the API server:

docker-compose up --build