StillWorking commited on
Commit
9057bbd
Β·
verified Β·
1 Parent(s): b6eecc5

Upload README_HF.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README_HF.md +326 -0
README_HF.md ADDED
@@ -0,0 +1,326 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Sentinel Face Recognition - Complete AI Infrastructure
2
+
3
+ A comprehensive computer vision system for celebrity face recognition with semantic search, built with Python, FastAPI, and Gemini AI.
4
+
5
+ **πŸ”— Repository:** https://huggingface.co/StillWorking/sentinel-face-recognition
6
+
7
+ ---
8
+
9
+ ## πŸ“¦ What's Included
10
+
11
+ βœ… **Complete Backend** (Python + FastAPI)
12
+ - Face detection & recognition using AdaFace and MTCNN
13
+ - FAISS vector search for semantic similarity
14
+ - Gemini AI integration for intelligent querying
15
+ - REST API endpoints for analysis, search, and generation
16
+
17
+ βœ… **Frontend** (React + TypeScript + Vite)
18
+ - Interactive web interface
19
+ - Real-time face analysis
20
+ - Search and discovery features
21
+ - Responsive design
22
+
23
+ βœ… **Full CelebA Dataset** (~1.35 GB)
24
+ - 200,000+ aligned celebrity face images
25
+ - Attribute metadata
26
+ - Ready-to-use for training and inference
27
+
28
+ βœ… **Pre-trained Models**
29
+ - AdaFace IR50 weights
30
+ - MTCNN face detection models
31
+ - FAISS index artifacts
32
+
33
+ ---
34
+
35
+ ## πŸš€ Quick Start
36
+
37
+ ### Prerequisites
38
+ - Python 3.9+
39
+ - Git with Git LFS support
40
+ - Node.js 18+ (for frontend)
41
+
42
+ ### Installation
43
+
44
+ **1. Clone the repository:**
45
+ ```bash
46
+ git clone https://huggingface.co/StillWorking/sentinel-face-recognition
47
+ cd sentinel-face-recognition
48
+ ```
49
+
50
+ **2. Ensure Git LFS is installed and pull large files:**
51
+ ```bash
52
+ # Install Git LFS (if not already installed)
53
+ git lfs install
54
+
55
+ # Pull all LFS-tracked files (dataset, models, etc.)
56
+ git lfs pull
57
+ ```
58
+
59
+ **3. Set up backend:**
60
+ ```bash
61
+ cd backend
62
+ python -m venv venv
63
+
64
+ # Activate virtual environment
65
+ # Windows:
66
+ venv\Scripts\activate
67
+ # macOS/Linux:
68
+ source venv/bin/activate
69
+
70
+ # Install dependencies
71
+ pip install -r ../requirements.txt
72
+ ```
73
+
74
+ **4. Configure API keys:**
75
+ ```bash
76
+ # Copy the example environment file
77
+ cp .env.example .env
78
+
79
+ # Edit .env and add your Gemini API key
80
+ # Get it from: https://aistudio.google.com/app/apikey
81
+ ```
82
+
83
+ **5. Run the backend:**
84
+ ```bash
85
+ python main.py
86
+ # Server runs on http://localhost:8000
87
+ ```
88
+
89
+ **6. Set up frontend (in another terminal):**
90
+ ```bash
91
+ cd frontend
92
+ npm install
93
+ npm run dev
94
+ # Opens on http://localhost:5173
95
+ ```
96
+
97
+ ---
98
+
99
+ ## πŸ“‹ Features
100
+
101
+ ### Backend API Endpoints
102
+ - `GET /health` - Health check
103
+ - `POST /api/v1/analyze-frame` - Detect and identify faces in an image
104
+ - `POST /api/v1/search` - Semantic search for similar faces
105
+ - `POST /api/v1/generate-person` - Generate faces using AI
106
+ - `GET /api/v1/index-status` - Check index information
107
+
108
+ ### Frontend Features
109
+ - Upload images for face detection
110
+ - Search through the entire celebrity database
111
+ - View matched celebrity profiles with similarity scores
112
+ - Interactive UI with real-time feedback
113
+
114
+ ---
115
+
116
+ ## πŸ—‚οΈ Project Structure
117
+
118
+ ```
119
+ sentinel-face-recognition/
120
+ β”œβ”€β”€ backend/
121
+ β”‚ β”œβ”€β”€ api/ # FastAPI routes & schemas
122
+ β”‚ β”œβ”€β”€ core/ # Core ML logic (detection, embedding, search)
123
+ β”‚ β”œβ”€β”€ models_cache/ # Pre-trained models (AdaFace, MTCNN)
124
+ β”‚ β”œβ”€β”€ index_artifacts/ # FAISS index & metadata
125
+ β”‚ β”œβ”€β”€ main.py # FastAPI app entry point
126
+ β”‚ └── requirements.txt # Python dependencies
127
+ β”œβ”€β”€ frontend/
128
+ β”‚ β”œβ”€β”€ src/ # React components & pages
129
+ β”‚ β”œβ”€β”€ public/ # Static assets
130
+ β”‚ └── package.json # Node dependencies
131
+ β”œβ”€β”€ Data/ # CelebA dataset (1.35 GB)
132
+ β”‚ β”œβ”€β”€ img_align_celeba/ # Face images
133
+ β”‚ └── list_attr_celeba.csv
134
+ β”œβ”€β”€ deploy/ # Nginx config for production
135
+ └── README.md # This file
136
+ ```
137
+
138
+ ---
139
+
140
+ ## πŸ”‘ Environment Variables
141
+
142
+ Create a `.env` file in the root directory:
143
+
144
+ ```env
145
+ # Google Gemini API (required for search/analysis)
146
+ GEMINI_API_KEY=your_key_here
147
+ GEMINI_MODEL=gemini-2.5-flash
148
+
149
+ # Optional LLM fallbacks
150
+ GROQ_API_KEY=
151
+ COHERE_API_KEY=
152
+
153
+ # Hardware
154
+ TORCH_DEVICE=cuda # or 'cpu' for CPU-only
155
+
156
+ # Face detection parameters
157
+ MTCNN_MIN_FACE_SIZE=20
158
+ DETECTION_CONFIDENCE=0.6
159
+ MATCH_SIMILARITY_THRESHOLD=0.50
160
+
161
+ # API security
162
+ SENTINEL_API_KEY= # Leave empty for open access
163
+ RATE_LIMIT_PER_MINUTE=60
164
+
165
+ # CORS
166
+ CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
167
+
168
+ # Paths
169
+ CELEBA_IMAGES_DIR=./Data/img_align_celeba
170
+ CELEBA_ATTR_CSV=./Data/list_attr_celeba.csv
171
+ FAISS_INDEX_PATH=./backend/index_artifacts/celeb_index.faiss
172
+ ```
173
+
174
+ ---
175
+
176
+ ## πŸ§ͺ Testing
177
+
178
+ ```bash
179
+ cd backend
180
+ pytest tests/ -v
181
+ ```
182
+
183
+ ---
184
+
185
+ ## πŸ“Š Dataset Information
186
+
187
+ **CelebA Dataset:**
188
+ - 202,599 aligned face images
189
+ - 40 binary attribute annotations
190
+ - Pre-processed and ready to use
191
+ - Each face: 178 Γ— 218 pixels
192
+ - Format: JPEG
193
+
194
+ **Access the data:**
195
+ ```python
196
+ import os
197
+ import pandas as pd
198
+ from PIL import Image
199
+
200
+ # Load metadata
201
+ df = pd.read_csv('Data/list_attr_celeba.csv')
202
+ print(df.head())
203
+
204
+ # Load an image
205
+ img = Image.open('Data/img_align_celeba/000001.jpg')
206
+ img.show()
207
+ ```
208
+
209
+ ---
210
+
211
+ ## πŸ€– Model Information
212
+
213
+ **AdaFace (IR50)**
214
+ - State-of-the-art face recognition model
215
+ - Trained on MS1MV2 dataset
216
+ - 512-dimensional embeddings
217
+ - High accuracy on wild faces
218
+
219
+ **MTCNN**
220
+ - Multi-task Cascaded Convolutional Networks
221
+ - Reliable face detection
222
+ - Handles multiple scales and orientations
223
+
224
+ ---
225
+
226
+ ## πŸ”§ Advanced Configuration
227
+
228
+ ### GPU Acceleration
229
+ ```bash
230
+ # Install CUDA support
231
+ pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
232
+
233
+ # Set in .env
234
+ TORCH_DEVICE=cuda
235
+ ```
236
+
237
+ ### Building FAISS Index
238
+ ```bash
239
+ cd backend
240
+ python build_index.py
241
+ ```
242
+
243
+ ---
244
+
245
+ ## πŸ“ License & Attribution
246
+
247
+ This project uses:
248
+ - **CelebA Dataset**: See `PRIVACY.md`
249
+ - **AdaFace Model**: Research use
250
+ - **MTCNN**: Original implementation
251
+ - **FAISS**: Meta AI
252
+
253
+ See `LICENSE` files in subdirectories for details.
254
+
255
+ ---
256
+
257
+ ## ⚠️ Security Notes
258
+
259
+ - **Never commit `.env` files** with real API keys
260
+ - Use `SENTINEL_API_KEY` for shared deployments
261
+ - Review `SECURITY.md` for detailed security guidelines
262
+ - Keep dependencies updated: `pip install --upgrade -r requirements.txt`
263
+
264
+ ---
265
+
266
+ ## πŸ› Troubleshooting
267
+
268
+ **Issue: "LFS files not downloading"**
269
+ ```bash
270
+ # Ensure Git LFS is installed
271
+ git lfs install
272
+
273
+ # Pull all LFS files
274
+ git lfs pull
275
+
276
+ # Verify LFS is working
277
+ git lfs ls-files
278
+ ```
279
+
280
+ **Issue: "CUDA out of memory"**
281
+ ```bash
282
+ # Set to CPU mode in .env
283
+ TORCH_DEVICE=cpu
284
+
285
+ # Or reduce batch size in code
286
+ ```
287
+
288
+ **Issue: "Gemini API key not working"**
289
+ - Get key from: https://aistudio.google.com/app/apikey
290
+ - Ensure it's valid and has quota remaining
291
+ - Check network connectivity
292
+
293
+ ---
294
+
295
+ ## πŸ“š Documentation
296
+
297
+ - **API Documentation:** http://localhost:8000/docs (Swagger UI)
298
+ - **Security:** See `SECURITY.md`
299
+ - **Design:** See `design.md`
300
+ - **Audit Findings:** See `SENTINEL_AUDIT_FINDINGS.md`
301
+
302
+ ---
303
+
304
+ ## 🀝 Contributing
305
+
306
+ To contribute improvements:
307
+ 1. Clone the repository
308
+ 2. Create a feature branch
309
+ 3. Make your changes
310
+ 4. Test thoroughly
311
+ 5. Submit a pull request
312
+
313
+ ---
314
+
315
+ ## πŸ“ž Support
316
+
317
+ For issues or questions:
318
+ - Check existing issues on Hugging Face
319
+ - Review the documentation files
320
+ - Check the test suite for usage examples
321
+
322
+ ---
323
+
324
+ **Last Updated:** November 10, 2026
325
+
326
+ Enjoy building with Sentinel Face Recognition! πŸš€