# 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:** ```bash git clone https://huggingface.co/StillWorking/sentinel-face-recognition cd sentinel-face-recognition ``` **2. Ensure Git LFS is installed and pull large files:** ```bash # 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:** ```bash 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:** ```bash # 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:** ```bash python main.py # Server runs on http://localhost:8000 ``` **6. Set up frontend (in another terminal):** ```bash 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: ```env # 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 ```bash 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:** ```python 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 ```bash # 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 ```bash 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"** ```bash # 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"** ```bash # 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: 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! ๐Ÿš€