README_github.md

Face Intel

Modular image intelligence platform — OSINT, face recognition, forensic metadata, object intelligence, location estimation, AI-image detection, and a true reverse face search engine.

Face Intel 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 object intelligence — with an evidence-first, explainable confidence model.

Runs anywhere Python 3.11+ runs. Default install is lightweight enough for free-tier VPS / Railway / Hugging Face Spaces / Termux. Heavy ML deps (ONNX, dlib, Selenium) are opt-in.

---

Why Face Intel?

Tool	What it does	Pricing	Face Intel advantage
PimEyes	Reverse face search	$30–300/mo	Open source, self-hosted, multi-provider
FaceCheck.ID	Reverse face search	$20–100/mo	Free tier, evidence-first
TinEye	Reverse image search	$200/mo API	Multi-engine (Google/Bing/Yandex/TinEye/Reddit)
DeepFace (library)	Face recognition	Free	Face Intel wraps + extends with forensics + OSINT + AI-detection
Maltego transforms	Image OSINT	$999/yr	Argus-style integration potential

Face Intel collapses 16 providers into a single API call: face detection, recognition, reverse image search, EXIF/GPS, ELA forensics, OCR, NSFW detection, AI-image detection, scene recognition, barcode/QR, and image quality analysis.

---

Key Features

🎯 Reverse Face Search (NEW)

True PimEyes-style "find this face elsewhere" — not just reverse image search.

• Face enrollment API — index faces with metadata (name, source URL, age, etc.)
• Face search API — upload a face photo, get top-k matches from the index
• sqlite-vec backend — zero external dependencies, persists to single file
• 512-d ArcFace embeddings — 99.7% accuracy on LFW
• Optional crawler — seed the index with public Wikipedia/IMDB headshots

🧩 16 Providers Across 11 Capabilities

Category	Providers
Detection	Haar Cascade, OpenCV DNN
Recognition	InsightFace (ArcFace 512-d via ONNX)
Reverse search	SerpAPI, Social Lookup (Google/Bing/Yandex/TinEye/Reddit URL constructor), Face Index (NEW)
Forensics	Image Integrity, Duplicate Detector (pHash+dHash), ELA (Error Level Analysis), Image Similarity
Metadata	EXIF extraction
OCR	RapidOCR (multilingual)
Object detection	YOLOv8
Object intelligence	Barcode, QR Code
Scene recognition	Places365
NSFW	NudeNet
AI image detection	LAID (detect AI-generated images)
Embeddings	MobileNet
Image analysis	Image Quality (brightness/contrast/sharpness/noise), Image Properties

---

Quick Start

Local

git clone https://github.com/marwangpt237/face-intel.git
cd face-intel
pip install -r requirements.txt
cp .env.example .env
# edit .env to enable/disable providers
python app.py
# or: uvicorn app:app --reload

Open:

• http://localhost:8000/docs — Swagger UI
• http://localhost:8000/health — health check
• http://localhost:8000/providers — provider list
• http://localhost:8000/stats — metrics

Docker

docker build -t face-intel .
docker run -p 8000:8000 -v $(pwd)/data:/app/data face-intel

Deploy to free-tier clouds

Cloud	Free tier	Steps
Hugging Face Spaces	16GB RAM, unlimited	New Space → SDK: Docker → upload files → live at https://{user}-face-intel.hf.space
Render	750 hrs/mo	New → Web Service → connect repo → Build: pip install -r requirements.txt → Start: uvicorn app:app --host 0.0.0.0 --port $PORT
Fly.io	3 shared-cpu VMs	flyctl launch (set internal_port = 8000 in fly.toml) → flyctl deploy
Koyeb	1 free web service	koyeb service create face-intel --git github.com/marwangpt237/face-intel --ports 8000:http
Railway	$5 free credit/mo	New project → Deploy from GitHub → auto-detects Dockerfile

---

API Endpoints

Core

Method	Path	Description
POST	/faces/detect	Detect faces in an image
POST	/faces/recognize	Recognize faces against the gallery
POST	/search/reverse	Reverse image search (Google Lens / TinEye URLs)
POST	/search/scrape	Scrape images from a URL
POST	/jobs	Full-pipeline job
GET	/providers	List all providers
GET	/stats	Metrics snapshot
GET	/health/providers	Per-provider health

Reverse Face Search (NEW)

Method	Path	Description
POST	/faces/enroll	Enroll a face into the searchable index
POST	/faces/search	Search the index for matching faces
GET	/faces/list	Paginated list of enrolled faces
GET	/faces/{face_id}	Get details of a specific enrolled face
DELETE	/faces/{face_id}	Remove a face from the index
POST	/faces/crawl	Trigger the public-faces crawler (Wikipedia/IMDB seed)
GET	/faces/stats	Index statistics (count, last update, etc.)

Example: Enroll a face

curl -X POST http://localhost:8000/faces/enroll \
  -F "image=@photo.jpg" \
  -F "name=John Doe" \
  -F "source_url=https://example.com/profile" \
  -F "metadata={\"age\":30,\"location\":\"US\"}"

Response:

{
  "face_id": "f3a2b1c8-...",
  "status": "enrolled",
  "embedding_dim": 512,
  "thumbnail_path": "data/thumbnails/f3a2b1c8.jpg"
}

Example: Search for a face

curl -X POST http://localhost:8000/faces/search \
  -F "image=@query.jpg" \
  -F "top_k=5" \
  -F "threshold=0.5"

Response:

{
  "query_face_detected": true,
  "num_matches": 3,
  "matches": [
    {
      "face_id": "f3a2b1c8-...",
      "name": "John Doe",
      "source_url": "https://example.com/profile",
      "similarity": 0.87,
      "metadata": {"age": 30, "location": "US"}
    }
  ]
}

---

Architecture

Face Intel is built on 11 strict one-way dependency layers with dependency injection throughout. No global state. Every provider is isolated — failures don't cascade.

┌──────────────────────────────────────────────────────────────────┐
│                          FACE INTEL                              │
├──────────────────────────────────────────────────────────────────┤
│  api/         FastAPI routes + middleware + DI container         │
│  services/    High-level orchestration services                  │
│  orchestrator/ Async fan-out, retry, circuit breaker, cache      │
│  pipeline/    Image preprocessing + feature extraction           │
│  providers/   16 providers across 11 capabilities                │
│  cores/       Shared modules (face, vision, onnx, embedding)     │
│  storage/     Database, cache, artifacts, reference store        │
│  config/      Pydantic settings (FI_* env vars)                  │
│  models/      Pydantic schemas for requests/responses            │
│  metrics/     Prometheus-style collector                         │
│  utils/       Logging, audit, helpers                            │
└──────────────────────────────────────────────────────────────────┘

See docs/ARCHITECTURE.md for the full layer dependency graph, execution flow, lifecycle diagrams, and DI container docs.

---

Adding a New Provider

1. Implement providers/<category>/<name>.py (subclass BaseProvider)
2. Add one entry to PROVIDER_MANIFEST in providers/registry.py
3. Add an enable_<name>: bool = False flag to config/settings.py

That's it — the orchestrator, services, API, and UI pick it up automatically. See docs/PROVIDERS.md for the complete step-by-step guide.

---

Configuration

Every config is via FI_* env vars. See .env.example for the full list, or docs/CONFIGURATION.md for type, default, and description of each.

Key ones:

Var	Default	Description
FI_HOST	0.0.0.0	Bind host
FI_PORT	8000	Bind port
FI_ENABLE_INSIGHTFACE	false	Enable ArcFace recognition (requires ONNX)
FI_ENABLE_FACE_INDEX	true	Enable reverse face search
FI_FACE_INDEX_PATH	data/face_index.db	Path to sqlite-vec index
FI_FACE_INDEX_TOP_K	10	Default top_k for search
FI_RATE_LIMIT_PER_MINUTE	30	API rate limit

---

Engineering Principles

• Modular — every provider is isolated; failures don't cascade
• Extensible — new providers require zero orchestrator/API changes
• Production-ready — circuit breakers, retries, caching, rate limiting, audit log
• Evidence-first — raw provider responses preserved verbatim
• Explainable — confidence scores decomposed into weighted sub-scores
• Clean separation — 11 layers, strict one-way dependency direction
• DI throughout — no global stateful objects; everything injectable

---

Documentation

Document	Audience	What's in it
docs/ARCHITECTURE.md	All engineers	Layer dependency graph, execution flow, lifecycle diagrams, DI container, structured logging, metrics subsystem
docs/PROVIDERS.md	Provider authors	Provider Protocol, capability enum, step-by-step guide to adding a new provider, manifest format, health check & error handling patterns, testing pattern
docs/API_REFERENCE.md	API consumers	Every endpoint with method, path, request/response schemas, status codes, curl examples
docs/CONFIGURATION.md	Operators	Every FI_* env var with type, default, and description
docs/DEPLOYMENT.md	SRE / DevOps	Local dev setup, Docker deployment, Kubernetes manifests, reverse proxy config, storage layout, load balancer health probes
docs/TESTING.md	Contributors	Test structure (unit/provider/integration), how to run tests, how to write new tests, fixtures, coverage goals, CI integration
docs/TROUBLESHOOTING.md	On-call	Common errors and fixes: provider not_configured, circuit breaker open, model download failures, dlib compilation, Selenium/Chrome issues, cache issues, performance tuning
docs/ECOSYSTEM_RESEARCH.md	Architects	Open-source ecosystem survey of 42 projects across 18 capability categories, with capability matrix, priority ranking, integration roadmap, effort estimates, and example API designs
docs/OPTIMIZATION_REPORT.md	All engineers	Consolidation report: shared cores/ modules, dependency minimization, vendor-only-what's-necessary strategy, and savings estimates (89% storage reduction, 70% startup improvement)
docs/research/	Researchers	25+ JSON files of curated links across face recognition, forensics, OCR, NSFW, deepfake detection, AI image detection, lightweight models, and more

---

⚠️ Privacy & Legal

Face recognition is regulated in some jurisdictions (EU GDPR, Illinois BIPA, China PIPL). Operators are responsible for:

• Obtaining consent before enrolling faces into the index
• Providing a deletion mechanism (the DELETE /faces/{face_id} endpoint)
• Not storing uploaded query images longer than necessary
• Displaying a clear privacy policy and ToS

The default deployment does not crawl or index any faces automatically. The crawler is opt-in via POST /faces/crawl and only seeds from public-domain sources (Wikipedia profile photos). Social media scraping is intentionally NOT supported due to legal risk.

---

License

MIT — see LICENSE.

Acknowledgments

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