Download README_HF.md from StillWorking/sentinel-face-recognition: direct link, hf CLI and curl.
- Browser
- Download file 7.02 kB
-
https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/README_HF.md
- Command line
-
hf download hf://StillWorking/sentinel-face-recognition/README_HF.md
-
curl -L -o README_HF.md https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/README_HF.md
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 checkPOST /api/v1/analyze-frame- Detect and identify faces in an imagePOST /api/v1/search- Semantic search for similar facesPOST /api/v1/generate-person- Generate faces using AIGET /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
.envfiles with real API keys - Use
SENTINEL_API_KEYfor shared deployments - Review
SECURITY.mdfor 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"
- Get key from: https://aistudio.google.com/app/apikey
- Ensure it's valid and has quota remaining
- Check network connectivity
π 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:
- Clone the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- 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! π