--- 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! πŸš€