File size: 6,945 Bytes
b6eecc5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
---
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! πŸš€