StillWorking/sentinel-face-recognition

Sentinel Face Recognition - Complete AI Infrastructure

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

🎯 Overview

Sentinel is an end-to-end face recognition pipeline featuring:

• Real-time face detection using MTCNN
• High-accuracy face embedding using AdaFace
• Semantic search through 200K+ celebrity faces using FAISS
• AI-powered analysis with Gemini integration
• Production-ready REST API built with FastAPI
• Interactive web UI built with React + TypeScript

📦 What's Included

Backend (Python)

✅ Face detection & recognition
✅ FAISS vector search
✅ Gemini AI integration
✅ REST API with Swagger docs
✅ Rate limiting & security
✅ Comprehensive test suite

Frontend (React)

✅ Interactive web interface
✅ Real-time face analysis
✅ Search & discovery
✅ Responsive design
✅ Error handling

Dataset & Models

✅ CelebA dataset (200K+ images, 1.35 GB)
✅ AdaFace IR50 pre-trained weights
✅ MTCNN face detection models
✅ Pre-built FAISS index
✅ Metadata & attributes CSV

🚀 Quick Start

Installation

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

# Install Git LFS and pull large files
git lfs install
git lfs pull

# Setup backend
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r ../requirements.txt

# Configure API key
cp .env.example .env
# Edit .env and add your Gemini API key from https://aistudio.google.com/app/apikey

# Run backend
python main.py
# API available at http://localhost:8000
# Docs at http://localhost:8000/docs

In another terminal - Frontend

cd frontend
npm install
npm run dev
# Frontend at http://localhost:5173

📋 API Endpoints

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

Example Usage:

import requests

# Analyze a face
with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/api/v1/analyze-frame',
        files={'file': f}
    )
    print(response.json())

🗂️ Project Structure

sentinel-face-recognition/
├── backend/
│   ├── api/                    # FastAPI routes
│   ├── core/                   # ML logic
│   ├── models_cache/           # Pre-trained models
│   │   ├── adaface/           # AdaFace model files
│   │   ├── embeddings.pkl     # Pre-computed embeddings
│   ├── index_artifacts/        # FAISS index & metadata
│   ├── tests/                 # Test suite
│   └── main.py                # FastAPI app
├── frontend/                   # React application
├── Data/                       # CelebA dataset (Git LFS)
│   ├── img_align_celeba/      # 200K+ face images
│   └── list_attr_celeba.csv   # Attributes
└── deploy/                     # Nginx config

⚙️ Configuration

Create .env file:

# Gemini API (required)
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.5-flash

# Hardware
TORCH_DEVICE=cuda              # or 'cpu'

# Face detection
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

📊 Dataset Details

CelebA Dataset:

• Size: 1.35 GB (compressed)
• Images: 202,599 aligned face images
• Attributes: 40 binary attribute annotations
• Resolution: 178 × 218 pixels
• Format: JPEG
• Ready to use: Yes, pre-processed

🤖 Model Information

AdaFace (IR50)

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

MTCNN

• Multi-task Cascaded Convolutional Networks
• Reliable multi-scale face detection
• Handles rotations and occlusions
• Pre-trained weights included

🧪 Testing

cd backend
pytest tests/ -v

📈 Performance

• Face Detection: ~50-100ms per image
• Face Embedding: ~20-40ms per face
• Vector Search: <5ms for 200K faces
• GPU Memory: ~4GB (VRAM)
• CPU Fallback: Supported (slower)

🔐 Security

• API key authentication support
• Rate limiting per client
• CORS protection
• Secure credential handling
• Input validation on all endpoints
• See SECURITY.md for details

📚 Documentation

• API Docs: http://localhost:8000/docs
• Security Guide: See SECURITY.md
• Design Document: See design.md
• Audit Report: See SENTINEL_AUDIT_FINDINGS.md

🛠️ Building Index

To rebuild the FAISS index:

cd backend
python build_index.py

⚠️ Known Limitations

• GPU recommended for real-time performance
• CelebA contains western-centric celebrity data
• Model trained on aligned faces (preprocessing needed for wild faces)
• Rate limited for public API access

🚀 Deployment

For production deployment, see deploy/nginx.conf.example for reverse proxy setup.

🤝 Contributing

1. Clone the repository
2. Create a feature branch
3. Make your changes
4. Run tests: pytest tests/ -v
5. Commit and push
6. Submit pull request

📝 License

MIT License - See LICENSE file for details

📖 Citation

If you use this project, please cite:

@software{sentinel2026,
  title={Sentinel Face Recognition},
  author={StillWorking},
  year={2026},
  url={https://huggingface.co/StillWorking/sentinel-face-recognition}
}

🙏 Acknowledgments

• CelebA Dataset: Liu et al., 2015
• AdaFace: Hu et al., ICCV 2023
• MTCNN: Zhang et al., 2016
• FAISS: Meta AI Research
• FastAPI: Sebastián Ramírez
• React: Facebook

📞 Support & Issues

• 📖 Check documentation files first
• 🐛 Review test suite for usage examples
• 💬 Comment on repository issues
• 🔗 Visit: https://huggingface.co/StillWorking/sentinel-face-recognition

---

Status: ✅ Production Ready
Last Updated: November 10, 2026
Python Version: 3.9+
License: MIT

---

Quick Download

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

Start exploring! 🚀