StillWorking's picture
Upload README_HF.md with huggingface_hub
9057bbd verified
|
Raw History Blame Contribute Delete
7.02 kB

Sentinel Face Recognition - Complete AI Infrastructure

A comprehensive computer vision system for celebrity face recognition with semantic search, built with Python, FastAPI, and Gemini AI.

πŸ”— Repository: https://huggingface.co/StillWorking/sentinel-face-recognition


πŸ“¦ What's Included

βœ… Complete Backend (Python + FastAPI)

  • Face detection & recognition using AdaFace and MTCNN
  • FAISS vector search for semantic similarity
  • Gemini AI integration for intelligent querying
  • REST API endpoints for analysis, search, and generation

βœ… Frontend (React + TypeScript + Vite)

  • Interactive web interface
  • Real-time face analysis
  • Search and discovery features
  • Responsive design

βœ… Full CelebA Dataset (~1.35 GB)

  • 200,000+ aligned celebrity face images
  • Attribute metadata
  • Ready-to-use for training and inference

βœ… Pre-trained Models

  • AdaFace IR50 weights
  • MTCNN face detection models
  • FAISS index artifacts

πŸš€ Quick Start

Prerequisites

  • Python 3.9+
  • Git with Git LFS support
  • Node.js 18+ (for frontend)

Installation

1. Clone the repository:

git clone https://huggingface.co/StillWorking/sentinel-face-recognition
cd sentinel-face-recognition

2. Ensure Git LFS is installed and pull large files:

# Install Git LFS (if not already installed)
git lfs install

# Pull all LFS-tracked files (dataset, models, etc.)
git lfs pull

3. Set up backend:

cd backend
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r ../requirements.txt

4. Configure API keys:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Gemini API key
# Get it from: https://aistudio.google.com/app/apikey

5. Run the backend:

python main.py
# Server runs on http://localhost:8000

6. Set up frontend (in another terminal):

cd frontend
npm install
npm run dev
# Opens on http://localhost:5173

πŸ“‹ Features

Backend API Endpoints

  • GET /health - Health check
  • POST /api/v1/analyze-frame - Detect and identify faces in an image
  • POST /api/v1/search - Semantic search for similar faces
  • POST /api/v1/generate-person - Generate faces using AI
  • GET /api/v1/index-status - Check index information

Frontend Features

  • Upload images for face detection
  • Search through the entire celebrity database
  • View matched celebrity profiles with similarity scores
  • Interactive UI with real-time feedback

πŸ—‚οΈ Project Structure

sentinel-face-recognition/
β”œβ”€β”€ backend/
β”‚   β”œβ”€β”€ api/                 # FastAPI routes & schemas
β”‚   β”œβ”€β”€ core/               # Core ML logic (detection, embedding, search)
β”‚   β”œβ”€β”€ models_cache/       # Pre-trained models (AdaFace, MTCNN)
β”‚   β”œβ”€β”€ index_artifacts/    # FAISS index & metadata
β”‚   β”œβ”€β”€ main.py             # FastAPI app entry point
β”‚   └── requirements.txt    # Python dependencies
β”œβ”€β”€ frontend/
β”‚   β”œβ”€β”€ src/               # React components & pages
β”‚   β”œβ”€β”€ public/            # Static assets
β”‚   └── package.json       # Node dependencies
β”œβ”€β”€ Data/                  # CelebA dataset (1.35 GB)
β”‚   β”œβ”€β”€ img_align_celeba/  # Face images
β”‚   └── list_attr_celeba.csv
β”œβ”€β”€ deploy/                # Nginx config for production
└── README.md              # This file

πŸ”‘ Environment Variables

Create a .env file in the root directory:

# Google Gemini API (required for search/analysis)
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.5-flash

# Optional LLM fallbacks
GROQ_API_KEY=
COHERE_API_KEY=

# Hardware
TORCH_DEVICE=cuda  # or 'cpu' for CPU-only

# Face detection parameters
MTCNN_MIN_FACE_SIZE=20
DETECTION_CONFIDENCE=0.6
MATCH_SIMILARITY_THRESHOLD=0.50

# API security
SENTINEL_API_KEY=  # Leave empty for open access
RATE_LIMIT_PER_MINUTE=60

# CORS
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

# Paths
CELEBA_IMAGES_DIR=./Data/img_align_celeba
CELEBA_ATTR_CSV=./Data/list_attr_celeba.csv
FAISS_INDEX_PATH=./backend/index_artifacts/celeb_index.faiss

πŸ§ͺ Testing

cd backend
pytest tests/ -v

πŸ“Š Dataset Information

CelebA Dataset:

  • 202,599 aligned face images
  • 40 binary attribute annotations
  • Pre-processed and ready to use
  • Each face: 178 Γ— 218 pixels
  • Format: JPEG

Access the data:

import os
import pandas as pd
from PIL import Image

# Load metadata
df = pd.read_csv('Data/list_attr_celeba.csv')
print(df.head())

# Load an image
img = Image.open('Data/img_align_celeba/000001.jpg')
img.show()

πŸ€– Model Information

AdaFace (IR50)

  • State-of-the-art face recognition model
  • Trained on MS1MV2 dataset
  • 512-dimensional embeddings
  • High accuracy on wild faces

MTCNN

  • Multi-task Cascaded Convolutional Networks
  • Reliable face detection
  • Handles multiple scales and orientations

πŸ”§ Advanced Configuration

GPU Acceleration

# Install CUDA support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Set in .env
TORCH_DEVICE=cuda

Building FAISS Index

cd backend
python build_index.py

πŸ“ License & Attribution

This project uses:

  • CelebA Dataset: See PRIVACY.md
  • AdaFace Model: Research use
  • MTCNN: Original implementation
  • FAISS: Meta AI

See LICENSE files in subdirectories for details.


⚠️ Security Notes

  • Never commit .env files with real API keys
  • Use SENTINEL_API_KEY for shared deployments
  • Review SECURITY.md for detailed security guidelines
  • Keep dependencies updated: pip install --upgrade -r requirements.txt

πŸ› Troubleshooting

Issue: "LFS files not downloading"

# Ensure Git LFS is installed
git lfs install

# Pull all LFS files
git lfs pull

# Verify LFS is working
git lfs ls-files

Issue: "CUDA out of memory"

# Set to CPU mode in .env
TORCH_DEVICE=cpu

# Or reduce batch size in code

Issue: "Gemini API key not working"


πŸ“š Documentation

  • API Documentation: http://localhost:8000/docs (Swagger UI)
  • Security: See SECURITY.md
  • Design: See design.md
  • Audit Findings: See SENTINEL_AUDIT_FINDINGS.md

🀝 Contributing

To contribute improvements:

  1. Clone the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

πŸ“ž Support

For issues or questions:

  • Check existing issues on Hugging Face
  • Review the documentation files
  • Check the test suite for usage examples

Last Updated: November 10, 2026

Enjoy building with Sentinel Face Recognition! πŸš€