StillWorking's picture
Upload README.md with huggingface_hub
b6eecc5 verified
|
Raw History Blame Contribute Delete
6.95 kB
---
language:
- en
license: mit
tags:
- face-recognition
- computer-vision
- celeba
- faiss
- semantic-search
- gemini-ai
datasets:
- celeba
---
# 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
```bash
# 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
```bash
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:**
```python
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:
```env
# 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
```bash
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:
```bash
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:
```bibtex
@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
```bash
git clone https://huggingface.co/StillWorking/sentinel-face-recognition
cd sentinel-face-recognition
git lfs pull
```
Start exploring! πŸš€