README.md

---
# Model card metadata — required by Hugging Face Hub
license: mit
language:
  - en
tags:
  - osint
  - face-recognition
  - reverse-face-search
  - pimeyes-alternative
  - image-forensics
  - fastapi
  - sqlite-vec
  - arcface
  - insightface
pipeline_tag: image-feature-extraction
library_name: fastapi
---

# Face Intel

**Modular image intelligence platform — OSINT, face recognition, forensic metadata, reverse face search (PimEyes-style), object intelligence, AI-image detection, and more.**

![License](https://img.shields.io/badge/license-MIT-blue)
![Python](https://img.shields.io/badge/python-3.11%2B-blue?logo=python)
![FastAPI](https://img.shields.io/badge/FastAPI-0.110-009688?logo=fastapi)
![Tests](https://img.shields.io/badge/tests-20%2B-brightgreen)

## What this is

Face Intel is a self-hosted, multi-provider image intelligence platform that aggregates **16+ providers** across 11 capability buckets in parallel — face detection, recognition, reverse search, forensics, OCR, metadata, NSFW detection, scene recognition, AI-image detection, and **true reverse face search** (PimEyes-style indexed search).

## Reverse Face Search (NEW)

Unlike PimEyes ($30-300/mo), Face Intel's reverse face search is open-source, self-hosted, and uses sqlite-vec + ArcFace 512-d embeddings:

```bash
# Enroll a face into the index
curl -X POST http://localhost:8000/faces/enroll \
  -F "image=@photo.jpg" \
  -F "name=John Doe"

# Search the index
curl -X POST http://localhost:8000/faces/search \
  -F "image=@query.jpg" \
  -F "top_k=5"
```

## Capabilities

| Category | Providers |
|---|---|
| Detection | Haar Cascade, OpenCV DNN |
| Recognition | InsightFace (ArcFace 512-d via ONNX) |
| Reverse search | SerpAPI, Social Lookup, **Face Index (NEW)** |
| Forensics | Image Integrity, Duplicate Detector, ELA, Image Similarity |
| Metadata | EXIF extraction |
| OCR | RapidOCR (multilingual) |
| Object detection | YOLOv8, Barcode, QR Code |
| Scene | Places365 |
| NSFW | NudeNet |
| AI-image detection | LAID |
| Embeddings | MobileNet |
| Image analysis | Quality, Properties |

## Source code

- **GitHub (primary):** https://github.com/marwangpt237/face-intel
- **Hugging Face (mirror):** this repo

## Quick start

```bash
git clone https://github.com/marwangpt237/face-intel.git
cd face-intel
pip install -r requirements.txt
cp .env.example .env
python app.py
# Open http://localhost:8000/docs
```

## Documentation

See the [`docs/`](https://github.com/marwangpt237/face-intel/tree/main/docs) directory for:
- Architecture (11 layers, DI throughout)
- API reference (all endpoints + curl examples)
- Configuration (every `FI_*` env var)
- Deployment (Docker, Kubernetes, free-tier clouds)
- Providers (how to add a new one in 3 steps)
- Testing
- Troubleshooting
- Ecosystem research (42 projects surveyed)

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgments

Built on the shoulders of giants: InsightFace, DeepFace, OpenCV, RapidOCR, YOLOv8, NudeNet, Places365, LAID, and many other open-source projects.