Sync from GitHub via hub-sync

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+images/faceverification_demo.gif filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -8,14 +8,15 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 
 WORKDIR /app
 
-RUN apt-get update && apt-get install -y --no-install-recommends \
+RUN apt-get update && apt-get upgrade -y \
+    && apt-get install -y --no-install-recommends \
     libgl1 \
     libglib2.0-0 \
     && rm -rf /var/lib/apt/lists/*
 
 COPY requirements.txt .
 RUN pip install --no-cache-dir --upgrade pip setuptools "wheel>=0.46.2"
-RUN pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir --extra-index-url https://download.pytorch.org/whl/cpu -r requirements.txt
 
 COPY pyproject.toml README.md ./
 COPY src ./src

README.md

@@ -23,6 +23,18 @@ Try it on Hugging Face Spaces: https://huggingface.co/spaces/leandrodevai/faceve
 
 The app lets users add known people to a local embeddings database and verify whether a new face image matches one of the stored identities.
 
+![Face verification demo](images/faceverification_demo.gif)
+
+This demo was built to show that FaceNet, despite being an older architecture,
+is still a strong and practical baseline for face embedding workflows. Its
+moderate runtime footprint also makes it an interesting candidate for constrained
+deployments, including edge-style scenarios when hardware, latency, and accuracy
+requirements are compatible.
+
+The project is also intended as a reusable AI engineering template: the same
+structure can be adapted to build CI/CD pipelines for other models, or extended
+from image uploads into a video pipeline for near real-time face recognition.
+
 ## Features
 
 - Face detection and preprocessing from uploaded images
@@ -32,6 +44,65 @@ The app lets users add known people to a local embeddings database and verify wh
 - FastAPI interface for containerized API deployments
 - Docker-based Hugging Face Space deployment
 
+## Architecture
+
+```mermaid
+flowchart LR
+    A[Upload] --> B[MTCNN]
+    B --> C[Crop]
+    C --> D[FaceNet]
+    D --> E[Normalize]
+    E --> F[ChromaDB]
+    F --> G[Threshold]
+    G --> H[Match]
+```
+
+Images are first passed through MTCNN for face detection and cropping. FaceNet
+then produces an embedding, which is L2-normalized before being stored or
+queried in ChromaDB. Verification compares the nearest stored embedding against
+the calibrated distance threshold.
+
+## Model Evaluation
+
+The verification threshold was calibrated with a small study on the
+`bitmind/lfw` dataset, a Hugging Face version of Labeled Faces in the Wild
+(LFW). The study builds same-person and different-person image pairs, splits
+them into calibration and held-out evaluation sets, and evaluates L2 distance
+between L2-normalized FaceNet embeddings.
+
+For this demo, the selected threshold is:
+
+```text
+same person if L2 distance <= 1.0764
+different person if L2 distance > 1.0764
+```
+
+This value was chosen on the calibration split because it maximized balanced
+accuracy while staying below the distance region where different-person pairs
+start to dominate. The held-out evaluation split contains 720 same-person and
+720 different-person pairs.
+
+![Evaluation distance distributions](images/Densities.png)
+
+Held-out evaluation results:
+
+| Metric | Value |
+| --- | ---: |
+| AUC-ROC | 0.9838 |
+| Accuracy | 0.9653 |
+| FAR | 0.0097 |
+| FRR | 0.0597 |
+| TPR | 0.9403 |
+| Calibrated threshold | 1.0764 |
+| Calibration EER threshold | 1.1857 |
+
+![Held-out evaluation ROC curve](images/ROC.png)
+
+![Held-out evaluation confusion matrix](images/confusion_matrix.png)
+
+These metrics are intended to justify the threshold for this demo dataset, not
+as a production biometric benchmark.
+
 ## Tech Stack
 
 - Python

pyproject.toml

@@ -14,13 +14,10 @@ dependencies = [
     "pydantic>=2.11.10,<=2.12.5",
     "pydantic-settings>=2.14.1",
     "chromadb>=1.5.9",
-    "pytest>=9.0.3",
-    "pytest-cov>=7.1.0",
     "fastapi>=0.136.1",
     "pyjwt>=2.10.1",
     "python-multipart>=0.0.28",
     "uvicorn[standard]>=0.46.0",
-    "ruff>=0.15.13",
     "torch>=2.12.0",
     "torchvision>=0.27.0",
 ]
@@ -60,3 +57,10 @@ src = ["src", "test"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "B", "UP", "SIM"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.13",
+]

requirements.txt

@@ -1,7 +1,5 @@
 # This file was autogenerated by uv via the following command:
-#    uv --cache-dir .uv-cache export --locked --no-hashes --no-emit-project --format requirements.txt --output-file requirements.txt
---find-links https://download.pytorch.org/whl/cpu/torch/
---find-links https://download.pytorch.org/whl/cpu/torchvision/
+#    uv --cache-dir .uv-cache export --locked --no-dev --no-hashes --no-emit-project --format requirements.txt --index https://download.pytorch.org/whl/cpu --output-file requirements.txt
 aiohappyeyeballs==2.6.1
     # via aiohttp
 aiohttp==3.13.5
@@ -51,11 +49,8 @@ colorama==0.4.6 ; (os_name != 'nt' and sys_platform == 'win32') or (os_name == '
     # via
     #   build
     #   click
-    #   pytest
     #   tqdm
     #   uvicorn
-coverage==7.14.0
-    # via pytest-cov
 datasets==4.8.5
     # via faceverification
 dill==0.4.1
@@ -138,8 +133,6 @@ importlib-metadata==8.7.1
     # via opentelemetry-api
 importlib-resources==7.1.0
     # via chromadb
-iniconfig==2.3.0
-    # via pytest
 jinja2==3.1.6
     # via
     #   gradio
@@ -218,7 +211,6 @@ packaging==26.2
     #   gradio-client
     #   huggingface-hub
     #   onnxruntime
-    #   pytest
 pandas==3.0.2
     # via
     #   datasets
@@ -228,10 +220,6 @@ pillow==12.2.0
     #   facenet-pytorch
     #   gradio
     #   torchvision
-pluggy==1.6.0
-    # via
-    #   pytest
-    #   pytest-cov
 propcache==0.5.2
     # via
     #   aiohttp
@@ -261,21 +249,13 @@ pydantic-settings==2.14.1
 pydub==0.25.1
     # via gradio
 pygments==2.20.0
-    # via
-    #   pytest
-    #   rich
+    # via rich
 pyjwt==2.12.1
     # via faceverification
 pypika==0.51.1
     # via chromadb
 pyproject-hooks==1.2.0
     # via build
-pytest==9.0.3
-    # via
-    #   faceverification
-    #   pytest-cov
-pytest-cov==7.1.0
-    # via faceverification
 python-dateutil==2.9.0.post0
     # via
     #   kubernetes
@@ -319,8 +299,6 @@ rpds-py==0.30.0
     # via
     #   jsonschema
     #   referencing
-ruff==0.15.13
-    # via faceverification
 safehttpx==0.1.7
     # via gradio
 semantic-version==2.10.0
@@ -343,8 +321,6 @@ tenacity==9.1.4
     # via chromadb
 tokenizers==0.23.1
     # via chromadb
-tomli==2.4.1 ; python_full_version <= '3.11'
-    # via coverage
 tomlkit==0.14.0
     # via gradio
 torch==2.12.0 ; sys_platform == 'darwin'

src/faceverification/config.py

@@ -11,7 +11,7 @@ class Settings(BaseSettings):
     vector_db_collection: str = "face_embeddings"
     vector_db_persist_directory: str | None = None
     vector_db_n_results: int = 5
-    face_match_threshold: float = 1.08
+    face_match_threshold: float = 1.0764
 
     device: Literal["auto", "cpu", "cuda"] = "auto"
     mtcnn_thresholds: tuple[float, float, float] = (0.6, 0.7, 0.95)

uv.lock

@@ -568,11 +568,8 @@ dependencies = [
     { name = "pydantic" },
     { name = "pydantic-settings" },
     { name = "pyjwt" },
-    { name = "pytest" },
-    { name = "pytest-cov" },
     { name = "python-dotenv" },
     { name = "python-multipart" },
-    { name = "ruff" },
     { name = "torch", version = "2.12.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform == 'darwin'" },
     { name = "torch", version = "2.12.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform != 'darwin'" },
     { name = "torchvision", version = "0.27.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "sys_platform == 'darwin'" },
@@ -580,6 +577,13 @@ dependencies = [
     { name = "uvicorn", extra = ["standard"] },
 ]
 
+[package.dev-dependencies]
+dev = [
+    { name = "pytest" },
+    { name = "pytest-cov" },
+    { name = "ruff" },
+]
+
 [package.metadata]
 requires-dist = [
     { name = "chromadb", specifier = ">=1.5.9" },
@@ -592,16 +596,20 @@ requires-dist = [
     { name = "pydantic", specifier = ">=2.11.10,<=2.12.5" },
     { name = "pydantic-settings", specifier = ">=2.14.1" },
     { name = "pyjwt", specifier = ">=2.10.1" },
-    { name = "pytest", specifier = ">=9.0.3" },
-    { name = "pytest-cov", specifier = ">=7.1.0" },
     { name = "python-dotenv", specifier = ">=1.2.2" },
     { name = "python-multipart", specifier = ">=0.0.28" },
-    { name = "ruff", specifier = ">=0.15.13" },
     { name = "torch", specifier = ">=2.12.0", index = "https://download.pytorch.org/whl/cpu" },
     { name = "torchvision", specifier = ">=0.27.0", index = "https://download.pytorch.org/whl/cpu" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.46.0" },
 ]
 
+[package.metadata.requires-dev]
+dev = [
+    { name = "pytest", specifier = ">=9.0.3" },
+    { name = "pytest-cov", specifier = ">=7.1.0" },
+    { name = "ruff", specifier = ">=0.15.13" },
+]
+
 [[package]]
 name = "fastapi"
 version = "0.136.1"