Sync from GitHub via hub-sync

.python-version

@@ -0,0 +1 @@
+3.11

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leandro Patrón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -5,10 +5,8 @@ colorFrom: blue
 colorTo: green
 sdk: gradio
 sdk_version: 6.14.0
-python_version: '3.13'
+python_version: '3.11'
 app_file: app.py
 pinned: false
 license: mit
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---

app.py

@@ -0,0 +1,4 @@
+from faceverification.app import FV_gr
+
+if __name__ == "__main__":
+    FV_gr.launch()

pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "faceverification"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24,<2.0",
+    "datasets>=4.8.5",
+    "facenet-pytorch>=2.5.3",
+    "gradio>=6.14.0",
+    "huggingface-hub>=1.14.0",
+    "python-dotenv>=1.2.2",
+    "pydantic-settings>=2.14.1",
+    "torch>=2.11.0",
+    "torchvision>=0.26.0",
+    "chromadb>=1.5.9",
+    "pytest>=9.0.3",
+]
+
+[project.scripts]
+faceverification = "faceverification.app:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+torch = { index = "pytorch-cu126" }
+torchvision = { index = "pytorch-cu126" }
+
+[[tool.uv.index]]
+name = "pytorch-cu126"
+url = "https://download.pytorch.org/whl/cu126"
+explicit = true
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["test"]
+python_files = ["test_*.py"]
+markers = [
+    "integration: tests that use real external components or models",
+    "e2e: end-to-end tests that exercise complete application workflows",
+]

requirements.txt

@@ -0,0 +1,450 @@
+# This file was autogenerated by uv via the following command:
+#    uv export --locked --no-hashes --format requirements.txt --output-file requirements.txt
+-e .
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.13.5
+    # via fsspec
+aiosignal==1.4.0
+    # via aiohttp
+annotated-doc==0.0.4
+    # via
+    #   fastapi
+    #   typer
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.13.0
+    # via
+    #   gradio
+    #   httpx
+    #   starlette
+    #   watchfiles
+attrs==26.1.0
+    # via
+    #   aiohttp
+    #   jsonschema
+    #   referencing
+audioop-lts==0.2.2 ; python_full_version >= '3.13'
+    # via gradio
+bcrypt==5.0.0
+    # via chromadb
+brotli==1.2.0
+    # via gradio
+build==1.5.0
+    # via chromadb
+certifi==2026.4.22
+    # via
+    #   httpcore
+    #   httpx
+    #   kubernetes
+    #   requests
+charset-normalizer==3.4.7
+    # via requests
+chromadb==1.5.9
+    # via faceverification
+click==8.3.3
+    # via
+    #   typer
+    #   uvicorn
+colorama==0.4.6 ; os_name == 'nt' or sys_platform == 'win32'
+    # via
+    #   build
+    #   click
+    #   pytest
+    #   tqdm
+    #   uvicorn
+cuda-bindings==12.9.6 ; sys_platform == 'linux'
+    # via torch
+cuda-pathfinder==1.5.4 ; sys_platform == 'linux'
+    # via cuda-bindings
+cuda-toolkit==12.6.3 ; sys_platform == 'linux'
+    # via torch
+datasets==4.8.5
+    # via faceverification
+dill==0.4.1
+    # via
+    #   datasets
+    #   multiprocess
+durationpy==0.10
+    # via kubernetes
+facenet-pytorch==2.5.3
+    # via faceverification
+fastapi==0.136.1
+    # via gradio
+filelock==3.29.0
+    # via
+    #   datasets
+    #   huggingface-hub
+    #   torch
+flatbuffers==25.12.19
+    # via onnxruntime
+frozenlist==1.8.0
+    # via
+    #   aiohttp
+    #   aiosignal
+fsspec==2026.2.0
+    # via
+    #   datasets
+    #   gradio-client
+    #   huggingface-hub
+    #   torch
+googleapis-common-protos==1.75.0
+    # via opentelemetry-exporter-otlp-proto-grpc
+gradio==6.14.0
+    # via faceverification
+gradio-client==2.5.0
+    # via
+    #   gradio
+    #   hf-gradio
+groovy==0.1.2
+    # via gradio
+grpcio==1.80.0
+    # via
+    #   chromadb
+    #   opentelemetry-exporter-otlp-proto-grpc
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+hf-gradio==0.4.1
+    # via gradio
+hf-xet==1.5.0 ; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'
+    # via huggingface-hub
+httpcore==1.0.9
+    # via httpx
+httptools==0.7.1
+    # via uvicorn
+httpx==0.28.1
+    # via
+    #   chromadb
+    #   datasets
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   safehttpx
+huggingface-hub==1.14.0
+    # via
+    #   datasets
+    #   faceverification
+    #   gradio
+    #   gradio-client
+    #   tokenizers
+idna==3.14
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+    #   yarl
+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
+    #   torch
+jsonschema==4.26.0
+    # via chromadb
+jsonschema-specifications==2025.9.1
+    # via jsonschema
+kubernetes==35.0.0
+    # via chromadb
+markdown-it-py==4.2.0
+    # via rich
+markupsafe==3.0.3
+    # via
+    #   gradio
+    #   jinja2
+mdurl==0.1.2
+    # via markdown-it-py
+mmh3==5.2.1
+    # via chromadb
+mpmath==1.3.0
+    # via sympy
+multidict==6.7.1
+    # via
+    #   aiohttp
+    #   yarl
+multiprocess==0.70.19
+    # via datasets
+networkx==3.6.1
+    # via torch
+numpy==1.26.4
+    # via
+    #   chromadb
+    #   datasets
+    #   facenet-pytorch
+    #   faceverification
+    #   gradio
+    #   onnxruntime
+    #   pandas
+    #   torchvision
+nvidia-cublas-cu12==12.6.4.1 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cudnn-cu12
+    #   nvidia-cusolver-cu12
+nvidia-cuda-cupti-cu12==12.6.80 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cuda-nvrtc-cu12==12.6.85 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cuda-runtime-cu12==12.6.77 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cudnn-cu12==9.10.2.21 ; sys_platform == 'linux'
+    # via torch
+nvidia-cufft-cu12==11.3.0.4 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cufile-cu12==1.11.1.6 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-curand-cu12==10.3.7.77 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusolver-cu12==11.7.1.2 ; sys_platform == 'linux'
+    # via cuda-toolkit
+nvidia-cusparse-cu12==12.5.4.2 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cusolver-cu12
+nvidia-cusparselt-cu12==0.7.1 ; sys_platform == 'linux'
+    # via torch
+nvidia-nccl-cu12==2.28.9 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvjitlink-cu12==12.6.85 ; sys_platform == 'linux'
+    # via
+    #   cuda-toolkit
+    #   nvidia-cufft-cu12
+    #   nvidia-cusolver-cu12
+    #   nvidia-cusparse-cu12
+nvidia-nvshmem-cu12==3.4.5 ; sys_platform == 'linux'
+    # via torch
+nvidia-nvtx-cu12==12.6.77 ; sys_platform == 'linux'
+    # via cuda-toolkit
+oauthlib==3.3.1
+    # via requests-oauthlib
+onnxruntime==1.26.0
+    # via chromadb
+opentelemetry-api==1.41.1
+    # via
+    #   chromadb
+    #   opentelemetry-exporter-otlp-proto-grpc
+    #   opentelemetry-sdk
+    #   opentelemetry-semantic-conventions
+opentelemetry-exporter-otlp-proto-common==1.41.1
+    # via opentelemetry-exporter-otlp-proto-grpc
+opentelemetry-exporter-otlp-proto-grpc==1.41.1
+    # via chromadb
+opentelemetry-proto==1.41.1
+    # via
+    #   opentelemetry-exporter-otlp-proto-common
+    #   opentelemetry-exporter-otlp-proto-grpc
+opentelemetry-sdk==1.41.1
+    # via
+    #   chromadb
+    #   opentelemetry-exporter-otlp-proto-grpc
+opentelemetry-semantic-conventions==0.62b1
+    # via opentelemetry-sdk
+orjson==3.11.9
+    # via
+    #   chromadb
+    #   gradio
+overrides==7.7.0
+    # via chromadb
+packaging==26.2
+    # via
+    #   build
+    #   datasets
+    #   gradio
+    #   gradio-client
+    #   huggingface-hub
+    #   onnxruntime
+    #   pytest
+pandas==2.3.3 ; python_full_version >= '3.14'
+    # via
+    #   datasets
+    #   gradio
+pandas==3.0.2 ; python_full_version < '3.14'
+    # via
+    #   datasets
+    #   gradio
+pillow==12.2.0
+    # via
+    #   facenet-pytorch
+    #   gradio
+    #   torchvision
+pluggy==1.6.0
+    # via pytest
+propcache==0.5.2
+    # via
+    #   aiohttp
+    #   yarl
+protobuf==6.33.6
+    # via
+    #   googleapis-common-protos
+    #   onnxruntime
+    #   opentelemetry-proto
+pyarrow==24.0.0
+    # via datasets
+pybase64==1.4.3
+    # via chromadb
+pydantic==2.13.4
+    # via
+    #   chromadb
+    #   fastapi
+    #   gradio
+    #   pydantic-settings
+pydantic-core==2.46.4
+    # via pydantic
+pydantic-settings==2.14.1
+    # via
+    #   chromadb
+    #   faceverification
+pydub==0.25.1
+    # via gradio
+pygments==2.20.0
+    # via
+    #   pytest
+    #   rich
+pypika==0.51.1
+    # via chromadb
+pyproject-hooks==1.2.0
+    # via build
+pytest==9.0.3
+    # via faceverification
+python-dateutil==2.9.0.post0
+    # via
+    #   kubernetes
+    #   pandas
+python-dotenv==1.2.2
+    # via
+    #   faceverification
+    #   pydantic-settings
+    #   uvicorn
+python-multipart==0.0.28
+    # via gradio
+pytz==2026.2
+    # via
+    #   gradio
+    #   pandas
+pyyaml==6.0.3
+    # via
+    #   chromadb
+    #   datasets
+    #   gradio
+    #   huggingface-hub
+    #   kubernetes
+    #   uvicorn
+referencing==0.37.0
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+requests==2.33.1
+    # via
+    #   datasets
+    #   facenet-pytorch
+    #   kubernetes
+    #   requests-oauthlib
+requests-oauthlib==2.0.0
+    # via kubernetes
+rich==15.0.0
+    # via
+    #   chromadb
+    #   typer
+rpds-py==0.30.0
+    # via
+    #   jsonschema
+    #   referencing
+safehttpx==0.1.7
+    # via gradio
+semantic-version==2.10.0
+    # via gradio
+setuptools==81.0.0
+    # via torch
+shellingham==1.5.4
+    # via typer
+six==1.17.0
+    # via
+    #   kubernetes
+    #   python-dateutil
+starlette==1.0.0
+    # via
+    #   fastapi
+    #   gradio
+sympy==1.14.0
+    # via torch
+tenacity==9.1.4
+    # via chromadb
+tokenizers==0.23.1
+    # via chromadb
+tomlkit==0.14.0
+    # via gradio
+torch==2.11.0+cu126
+    # via
+    #   faceverification
+    #   torchvision
+torchvision==0.26.0+cu126
+    # via
+    #   facenet-pytorch
+    #   faceverification
+tqdm==4.67.3
+    # via
+    #   chromadb
+    #   datasets
+    #   huggingface-hub
+triton==3.6.0 ; sys_platform == 'linux'
+    # via torch
+typer==0.25.1
+    # via
+    #   chromadb
+    #   gradio
+    #   hf-gradio
+    #   huggingface-hub
+typing-extensions==4.15.0
+    # via
+    #   aiosignal
+    #   anyio
+    #   chromadb
+    #   fastapi
+    #   gradio
+    #   gradio-client
+    #   grpcio
+    #   huggingface-hub
+    #   opentelemetry-api
+    #   opentelemetry-exporter-otlp-proto-grpc
+    #   opentelemetry-sdk
+    #   opentelemetry-semantic-conventions
+    #   pydantic
+    #   pydantic-core
+    #   referencing
+    #   starlette
+    #   torch
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via
+    #   fastapi
+    #   pydantic
+    #   pydantic-settings
+tzdata==2026.2 ; python_full_version >= '3.14' or sys_platform == 'emscripten' or sys_platform == 'win32'
+    # via pandas
+urllib3==2.7.0
+    # via
+    #   kubernetes
+    #   requests
+uvicorn==0.46.0
+    # via
+    #   chromadb
+    #   gradio
+uvloop==0.22.1 ; platform_python_implementation != 'PyPy' and sys_platform != 'cygwin' and sys_platform != 'win32'
+    # via uvicorn
+watchfiles==1.1.1
+    # via uvicorn
+websocket-client==1.9.0
+    # via kubernetes
+websockets==16.0
+    # via uvicorn
+xxhash==3.7.0
+    # via datasets
+yarl==1.23.0
+    # via aiohttp
+zipp==3.23.1
+    # via importlib-metadata

src/faceverification/app.py

@@ -0,0 +1,65 @@
+import gradio as gr
+from PIL import Image
+
+from faceverification.core.image_processor import FaceNotDetectedError
+from faceverification.services.face_verification import add_person, verify_person
+
+
+def add_person_ui(image: Image.Image, name: str) -> Image.Image:
+    try:
+        return add_person(image, name)
+    except FaceNotDetectedError as exc:
+        raise gr.Error(str(exc)) from exc
+    except Exception as exc:
+        raise gr.Error(str(exc)) from exc
+
+
+def verify_person_ui(image: Image.Image) -> tuple[str, Image.Image]:
+    try:
+        return verify_person(image)
+    except FaceNotDetectedError as exc:
+        raise gr.Error(str(exc)) from exc
+    except Exception as exc:
+        raise gr.Error(str(exc)) from exc
+
+
+with gr.Blocks() as FV_gr:
+    gr.Markdown(
+        "# Face Verification Tool\n"
+        "Upload an image and assign a name to add it to the embeddings database."
+    )
+    with gr.Tabs():
+        with gr.TabItem("Add Person"):
+            with gr.Row():
+                input_image = gr.Image(
+                    label="Upload an image with a clear face", type="pil"
+                )
+                input_name = gr.Textbox(
+                    label="Person name", placeholder="Example: John Doe"
+                )
+            output_image = gr.Image(label="Detection result")
+            submit_btn = gr.Button("Add to database")
+            submit_btn.click(
+                fn=add_person_ui,
+                inputs=[input_image, input_name],
+                outputs=output_image,
+            )
+        with gr.TabItem("Verify Identity"):
+            with gr.Row():
+                verify_image = gr.Image(label="Upload an image to verify", type="pil")
+            verify_btn = gr.Button("Verify identity")
+            verify_output_name = gr.Textbox(label="Verification result")
+            verify_output_image = gr.Image(label="Detected face")
+            verify_btn.click(
+                fn=verify_person_ui,
+                inputs=verify_image,
+                outputs=[verify_output_name, verify_output_image],
+            )
+
+
+def main():
+    FV_gr.launch()
+
+
+if __name__ == "__main__":
+    main()

src/faceverification/config.py

@@ -0,0 +1,24 @@
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    vector_db_distance_metric: str = "l2"
+    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
+
+    device: Literal["auto", "cpu", "cuda"] = "auto"
+    mtcnn_thresholds: tuple[float, float, float] = (0.6, 0.7, 0.95)
+    facenet_pretrained: str = "vggface2"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="FACEVERIFICATION_",
+        extra="ignore",
+    )
+
+
+settings = Settings()

src/faceverification/core/__init__.py

@@ -0,0 +1 @@
+

src/faceverification/core/image_processor.py

@@ -0,0 +1,116 @@
+"""Face detection and embedding extraction utilities.
+
+This module centralizes the computer vision models used by the application:
+MTCNN detects faces and draws bounding boxes, while FaceNet converts a detected
+face into a normalized embedding suitable for vector search.
+"""
+
+from collections.abc import Sequence
+
+import torch
+import torch.nn.functional as F
+from facenet_pytorch import MTCNN, InceptionResnetV1
+from PIL import Image, ImageDraw
+
+from faceverification.config import settings
+
+
+class FaceNotDetectedError(ValueError):
+    """Raised when no face can be detected in an image."""
+
+
+class ImageProcessor:
+    """Detect faces and generate FaceNet embeddings.
+
+    The processor owns the model lifecycle for MTCNN and InceptionResnetV1. It
+    accepts explicit configuration for tests or experiments, and falls back to
+    application settings when arguments are omitted.
+    """
+
+    def __init__(
+        self,
+        device: str | None = None,
+        mtcnn_thresholds: Sequence[float] | None = None,
+        facenet_pretrained: str | None = None,
+    ):
+        """Initialize face detection and embedding models.
+
+        Args:
+            device: Device used for model inference. Use `"auto"` to select
+                CUDA when available, otherwise CPU.
+            mtcnn_thresholds: Detection thresholds for the three MTCNN stages.
+            facenet_pretrained: Pretrained FaceNet weights identifier.
+
+        Raises:
+            ValueError: If `device` is not `"auto"`, `"cpu"`, or `"cuda"`.
+        """
+        if device is None:
+            device = settings.device
+        if mtcnn_thresholds is None:
+            mtcnn_thresholds = settings.mtcnn_thresholds
+        if facenet_pretrained is None:
+            facenet_pretrained = settings.facenet_pretrained
+
+        if device == "auto":
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        else:
+            self.device = device.lower()
+            if self.device not in ["cpu", "cuda"]:
+                raise ValueError("Device must be 'auto', 'cpu' or 'cuda'.")
+        self.mtcnn = MTCNN(
+            select_largest=False,
+            device=self.device,
+            thresholds=list(mtcnn_thresholds),
+        )
+        self.facenet = (
+            InceptionResnetV1(pretrained=facenet_pretrained).eval().to(self.device)
+        )
+
+    def get_embedding(self, image: Image.Image) -> torch.Tensor:
+        """Return a normalized embedding for the detected face in an image.
+
+        Args:
+            image: PIL image containing a face.
+
+        Returns:
+            A one-dimensional normalized FaceNet embedding tensor.
+
+        Raises:
+            FaceNotDetectedError: If no face can be detected in the image.
+        """
+        face_tensor = self.mtcnn(image)
+        if face_tensor is None:
+            raise FaceNotDetectedError("No face detected in the image.")
+
+        face_tensor = (
+            face_tensor.unsqueeze(0) if face_tensor.ndim == 3 else face_tensor
+        ).to(self.device)
+
+        with torch.no_grad():
+            features = self.facenet(face_tensor)
+            features = F.normalize(features, p=2, dim=1)
+
+        return features.squeeze(0)
+
+    def detect_faces(self, image: Image.Image) -> tuple[Image.Image, bool]:
+        """Draw detected face bounding boxes on an image.
+
+        Args:
+            image: PIL image to inspect and annotate.
+
+        Returns:
+            A tuple with the annotated image and a boolean indicating whether at
+            least one face was detected.
+        """
+        boxes, probs = self.mtcnn.detect(image)
+
+        if boxes is None:
+            return image, False
+
+        draw = ImageDraw.Draw(image)
+        for box, prob in zip(boxes, probs):
+            x1, y1, x2, y2 = [int(v) for v in box]
+            draw.rectangle([x1, y1, x2, y2], outline="red", width=2)
+            draw.text((x1, max(0, y1 - 12)), f"{prob:.4f}", fill="red")
+
+        return image, True

src/faceverification/core/vectordb.py

@@ -0,0 +1,123 @@
+"""Vector database adapter for face embedding storage and lookup.
+
+This module wraps ChromaDB behind a small project-specific interface. The rest
+of the application only needs to add face embeddings and query the nearest
+stored embedding, while this class owns the Chroma collection setup and result
+filtering.
+"""
+
+import uuid
+from typing import Any, Mapping
+
+import chromadb
+import numpy as np
+from chromadb.config import Settings as ChromaSettings
+
+from faceverification.config import settings
+
+
+class VectorDB:
+    """Store and query face embeddings in a ChromaDB collection.
+
+    The collection is configured with the selected HNSW distance metric and can
+    run either in memory or against a persistent directory when one is provided.
+    Query results are post-processed with NumPy so the service layer receives a
+    simple `(metadata, distance)` pair.
+    """
+
+    def __init__(
+        self,
+        distance_metric: str | None = None,
+        name_collection: str | None = None,
+        persist_directory: str | None = None,
+    ):
+        """Initialize the ChromaDB client and face embeddings collection.
+
+        Args:
+            distance_metric: HNSW distance metric used by ChromaDB. Common
+                values are `"l2"`, `"cosine"`, and `"ip"`.
+            name_collection: Name of the collection that stores face
+                embeddings.
+            persist_directory: Optional directory where ChromaDB should persist
+                data. When omitted, the database runs in memory.
+        """
+        if distance_metric is None:
+            distance_metric = settings.vector_db_distance_metric
+        if name_collection is None:
+            name_collection = settings.vector_db_collection
+        if persist_directory is None:
+            persist_directory = settings.vector_db_persist_directory
+
+        chroma_settings = ChromaSettings(
+            is_persistent=bool(persist_directory),
+            persist_directory=persist_directory or "",
+        )
+        self.client = chromadb.Client(chroma_settings)
+
+        self.collection = self.client.get_or_create_collection(
+            name=name_collection, metadata={"hnsw:space": distance_metric}
+        )
+
+    def add_embedding(self, embedding: np.ndarray, metadata: Mapping[str, Any]) -> None:
+        """Add one face embedding and its metadata to the collection.
+
+        Args:
+            embedding: Face embedding vector produced by the face recognition
+                model.
+            metadata: Metadata associated with the embedding, such as the
+                person's name.
+        """
+        self.collection.add(
+            embeddings=[embedding],
+            metadatas=[metadata],
+            ids=[str(uuid.uuid4())],
+        )
+
+    def query_embedding(
+        self,
+        embedding: np.ndarray,
+        threshold: float | None = None,
+        n_results: int | None = None,
+    ) -> tuple[Mapping[str, Any] | None, float]:
+        """Find the closest stored embedding within the configured threshold.
+
+        Args:
+            embedding: Query embedding vector to compare against stored
+                embeddings.
+            threshold: Maximum Euclidean distance accepted as a match.
+            n_results: Number of nearest ChromaDB candidates to inspect.
+
+        Returns:
+            A tuple containing the matched metadata and its distance. If no
+            candidate is within the threshold, metadata is `None` and the best
+            distance is still returned.
+        """
+        if threshold is None:
+            threshold = settings.face_match_threshold
+        if n_results is None:
+            n_results = settings.vector_db_n_results
+
+        result = self.collection.query(
+            query_embeddings=[embedding],
+            include=["metadatas", "distances", "embeddings"],
+            n_results=n_results,
+        )
+        embeddings = result.get("embeddings")
+        if not embeddings or embeddings[0] is None or len(embeddings[0]) == 0:
+            raise ValueError(
+                "No record found in the vector database. "
+                "Add a person before verifying faces."
+            )
+
+        best_dist = 100000
+        best_idx = 0
+        for i, emb_res in enumerate(result["embeddings"][0]):
+            dist = np.linalg.norm(embedding - emb_res)
+            if dist < best_dist:
+                best_dist = dist
+                best_idx = i
+
+        if best_dist <= threshold:
+            return result["metadatas"][0][best_idx], best_dist
+        else:
+            return None, best_dist

src/faceverification/services/face_verification.py

@@ -0,0 +1,73 @@
+"""Application service functions for face enrollment and verification.
+
+This module coordinates image preprocessing, embedding extraction, and vector
+database operations for the Gradio interface.
+"""
+
+from PIL import Image
+
+from faceverification.core.image_processor import FaceNotDetectedError, ImageProcessor
+from faceverification.core.vectordb import VectorDB
+
+image_processor = ImageProcessor()
+
+vector_db = VectorDB()
+
+
+def add_person(image: Image.Image, name: str) -> Image.Image:
+    """Enroll a person by extracting and storing their face embedding.
+
+    Args:
+        image: Input image provided by the UI as a PIL image.
+        name: Person name to store as embedding metadata.
+
+    Returns:
+        The input image annotated with detected face bounding boxes.
+
+    Raises:
+        FaceNotDetectedError: If no face is detected in the input image.
+        TypeError: If embedding extraction does not return the expected tensor.
+    """
+
+    img, presence = image_processor.detect_faces(image)
+
+    if not presence:
+        raise FaceNotDetectedError("No faces were detected in the image.")
+
+    faces_pt = image_processor.get_embedding(img)
+    if faces_pt is not None:
+        vector_db.add_embedding(faces_pt.cpu().numpy(), {"name": name})
+    else:
+        raise TypeError("The extracted face embedding is not a torch.Tensor.")
+
+    return img
+
+
+def verify_person(image: Image.Image) -> tuple[str, Image.Image]:
+    """Verify whether the input face matches a stored person.
+
+    Args:
+        image: Input image provided by the UI as a PIL image.
+
+    Returns:
+        A tuple with the matched person name, or `"Unregistered Person"` when no match is
+        found, and the image annotated with detected face bounding boxes.
+
+    Raises:
+        FaceNotDetectedError: If no face is detected in the input image.
+    """
+    detected_faces, presence = image_processor.detect_faces(image.copy())
+
+    if not presence:
+        raise FaceNotDetectedError("No faces were detected in the image.")
+
+    faces_pt = image_processor.get_embedding(image)
+    if faces_pt is not None:
+        metadata, _ = vector_db.query_embedding(faces_pt.cpu().numpy())
+
+        if metadata:
+            return metadata["name"], detected_faces
+
+        return "Unregistered Person", detected_faces
+
+    raise FaceNotDetectedError("No faces were detected in the image.")

test/test_face_verification.py

@@ -0,0 +1,150 @@
+import importlib
+import sys
+from unittest.mock import Mock
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from faceverification.core import image_processor as image_processor_module
+from faceverification.core import vectordb as vectordb_module
+from faceverification.core.image_processor import FaceNotDetectedError
+
+
+class FakeEmbedding:
+    def __init__(self, value):
+        self.value = value
+
+    def cpu(self):
+        return self
+
+    def numpy(self):
+        return self.value
+
+
+@pytest.fixture
+def service_module(monkeypatch):
+    fake_image_processor = Mock()
+    fake_vector_db = Mock()
+
+    monkeypatch.setattr(
+        image_processor_module,
+        "ImageProcessor",
+        lambda: fake_image_processor,
+    )
+    monkeypatch.setattr(vectordb_module, "VectorDB", lambda: fake_vector_db)
+
+    sys.modules.pop("faceverification.services.face_verification", None)
+    module = importlib.import_module("faceverification.services.face_verification")
+
+    return module, fake_image_processor, fake_vector_db
+
+
+def test_add_person_stores_embedding_and_returns_annotated_image(service_module):
+    service, image_processor, vector_db = service_module
+    original_image = Image.new("RGB", (10, 10), "white")
+    annotated_image = Image.new("RGB", (10, 10), "black")
+    embedding = np.array([0.1, 0.2, 0.3])
+    image_processor.detect_faces.return_value = (annotated_image, True)
+    image_processor.get_embedding.return_value = FakeEmbedding(embedding)
+
+    result = service.add_person(original_image, "Ada")
+
+    assert result is annotated_image
+    image_processor.detect_faces.assert_called_once_with(original_image)
+    image_processor.get_embedding.assert_called_once_with(annotated_image)
+    vector_db.add_embedding.assert_called_once()
+    args = vector_db.add_embedding.call_args.args
+    np.testing.assert_array_equal(args[0], embedding)
+    assert args[1] == {"name": "Ada"}
+
+
+def test_add_person_raises_when_no_face_is_detected(service_module):
+    service, image_processor, vector_db = service_module
+    image_processor.detect_faces.return_value = (Image.new("RGB", (10, 10)), False)
+
+    with pytest.raises(FaceNotDetectedError, match="No faces were detected"):
+        service.add_person(Image.new("RGB", (10, 10)), "Ada")
+
+    image_processor.get_embedding.assert_not_called()
+    vector_db.add_embedding.assert_not_called()
+
+
+def test_add_person_raises_type_error_when_embedding_is_none(service_module):
+    service, image_processor, vector_db = service_module
+    image = Image.new("RGB", (10, 10))
+    image_processor.detect_faces.return_value = (image, True)
+    image_processor.get_embedding.return_value = None
+
+    with pytest.raises(TypeError, match="extracted face embedding"):
+        service.add_person(image, "Ada")
+
+    vector_db.add_embedding.assert_not_called()
+
+
+def test_verify_person_returns_matched_name_and_annotated_image(service_module):
+    service, image_processor, vector_db = service_module
+    original_image = Image.new("RGB", (10, 10), "white")
+    detected_faces = Image.new("RGB", (10, 10), "black")
+    embedding = np.array([0.4, 0.5, 0.6])
+    image_processor.detect_faces.return_value = (detected_faces, True)
+    image_processor.get_embedding.return_value = FakeEmbedding(embedding)
+    vector_db.query_embedding.return_value = ({"name": "Grace"}, 0.2)
+
+    name, image = service.verify_person(original_image)
+
+    assert name == "Grace"
+    assert image is detected_faces
+    detected_input = image_processor.detect_faces.call_args.args[0]
+    assert detected_input is not original_image
+    image_processor.get_embedding.assert_called_once_with(original_image)
+    vector_db.query_embedding.assert_called_once()
+    np.testing.assert_array_equal(vector_db.query_embedding.call_args.args[0], embedding)
+
+
+def test_verify_person_returns_unregistered_when_no_metadata_matches(service_module):
+    service, image_processor, vector_db = service_module
+    detected_faces = Image.new("RGB", (10, 10))
+    image_processor.detect_faces.return_value = (detected_faces, True)
+    image_processor.get_embedding.return_value = FakeEmbedding(np.array([0.1, 0.2]))
+    vector_db.query_embedding.return_value = (None, 1.5)
+
+    name, image = service.verify_person(Image.new("RGB", (10, 10)))
+
+    assert name == "Unregistered Person"
+    assert image is detected_faces
+
+
+def test_verify_person_raises_when_vector_db_has_no_records(service_module):
+    service, image_processor, vector_db = service_module
+    detected_faces = Image.new("RGB", (10, 10))
+    image_processor.detect_faces.return_value = (detected_faces, True)
+    image_processor.get_embedding.return_value = FakeEmbedding(np.array([0.1, 0.2]))
+    vector_db.query_embedding.side_effect = ValueError(
+        "No record found in the vector database. Add a person before verifying faces."
+    )
+
+    with pytest.raises(ValueError, match="Add a person before verifying faces"):
+        service.verify_person(Image.new("RGB", (10, 10)))
+
+
+def test_verify_person_raises_when_no_face_is_detected(service_module):
+    service, image_processor, vector_db = service_module
+    image_processor.detect_faces.return_value = (Image.new("RGB", (10, 10)), False)
+
+    with pytest.raises(FaceNotDetectedError, match="No faces were detected"):
+        service.verify_person(Image.new("RGB", (10, 10)))
+
+    image_processor.get_embedding.assert_not_called()
+    vector_db.query_embedding.assert_not_called()
+
+
+def test_verify_person_raises_when_embedding_is_none(service_module):
+    service, image_processor, vector_db = service_module
+    image_processor.detect_faces.return_value = (Image.new("RGB", (10, 10)), True)
+    image_processor.get_embedding.return_value = None
+
+    with pytest.raises(FaceNotDetectedError, match="No faces were detected"):
+        service.verify_person(Image.new("RGB", (10, 10)))
+
+    vector_db.query_embedding.assert_not_called()

test/test_face_verification_e2e.py

@@ -0,0 +1,59 @@
+import importlib
+import sys
+import uuid
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from faceverification.core import vectordb as vectordb_module
+from faceverification.core.vectordb import VectorDB
+
+pytestmark = [pytest.mark.integration, pytest.mark.e2e]
+
+IMAGES_DIR = Path(__file__).parent / "images"
+
+
+@pytest.fixture
+def service_with_test_vectordb(monkeypatch):
+    vector_db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_service_e2e_faces_{uuid.uuid4().hex}",
+    )
+
+    monkeypatch.setattr(vectordb_module, "VectorDB", lambda: vector_db)
+    sys.modules.pop("faceverification.services.face_verification", None)
+    service = importlib.import_module("faceverification.services.face_verification")
+
+    yield service
+
+    sys.modules.pop("faceverification.services.face_verification", None)
+
+
+def test_service_enrolls_and_verifies_person_with_real_models(service_with_test_vectordb):
+    service = service_with_test_vectordb
+    anchor_image = Image.open(IMAGES_DIR / "person_anchor.jpg").convert("RGB")
+    positive_image = Image.open(IMAGES_DIR / "person_positive.jpg").convert("RGB")
+
+    service.add_person(anchor_image, "Ada")
+    name, annotated_image = service.verify_person(positive_image)
+
+    assert name == "Ada"
+    assert annotated_image is not positive_image
+
+
+def test_service_raises_before_enrollment(monkeypatch):
+    vector_db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_empty_service_e2e_faces_{uuid.uuid4().hex}",
+    )
+
+    monkeypatch.setattr(vectordb_module, "VectorDB", lambda: vector_db)
+    sys.modules.pop("faceverification.services.face_verification", None)
+    service = importlib.import_module("faceverification.services.face_verification")
+    image = Image.open(IMAGES_DIR / "person_anchor.jpg").convert("RGB")
+
+    with pytest.raises(ValueError, match="Add a person before verifying faces"):
+        service.verify_person(image)
+
+    sys.modules.pop("faceverification.services.face_verification", None)

test/test_face_verification_integration.py

@@ -0,0 +1,88 @@
+import importlib
+import sys
+import uuid
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from faceverification.core import image_processor as image_processor_module
+from faceverification.core import vectordb as vectordb_module
+from faceverification.core.vectordb import VectorDB
+
+pytestmark = pytest.mark.integration
+
+
+class FakeEmbedding:
+    def __init__(self, value):
+        self.value = value
+
+    def cpu(self):
+        return self
+
+    def numpy(self):
+        return self.value
+
+
+class FakeImageProcessor:
+    def __init__(self):
+        self.embeddings = []
+
+    def detect_faces(self, image):
+        return image, True
+
+    def get_embedding(self, _image):
+        return FakeEmbedding(self.embeddings.pop(0))
+
+
+@pytest.fixture
+def service_with_real_vectordb(monkeypatch):
+    fake_image_processor = FakeImageProcessor()
+    vector_db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_service_faces_{uuid.uuid4().hex}",
+    )
+
+    monkeypatch.setattr(
+        image_processor_module,
+        "ImageProcessor",
+        lambda: fake_image_processor,
+    )
+    monkeypatch.setattr(vectordb_module, "VectorDB", lambda: vector_db)
+
+    sys.modules.pop("faceverification.services.face_verification", None)
+    service = importlib.import_module("faceverification.services.face_verification")
+
+    return service, fake_image_processor
+
+
+def test_add_then_verify_person_with_real_vectordb(service_with_real_vectordb):
+    service, image_processor = service_with_real_vectordb
+    image_processor.embeddings = [
+        np.array([0.1, 0.2, 0.3]),
+        np.array([0.11, 0.19, 0.31]),
+    ]
+    image = Image.new("RGB", (10, 10), "white")
+
+    service.add_person(image, "Ada")
+    name, annotated_image = service.verify_person(image)
+
+    assert name == "Ada"
+    assert annotated_image is not None
+
+
+def test_verify_person_returns_unregistered_when_real_vectordb_match_is_too_far(
+    service_with_real_vectordb,
+):
+    service, image_processor = service_with_real_vectordb
+    image_processor.embeddings = [
+        np.array([0.0, 0.0, 0.0]),
+        np.array([10.0, 10.0, 10.0]),
+    ]
+    image = Image.new("RGB", (10, 10), "white")
+
+    service.add_person(image, "Ada")
+    name, annotated_image = service.verify_person(image)
+
+    assert name == "Unregistered Person"
+    assert annotated_image is not None

test/test_face_workflow_integration.py

@@ -0,0 +1,36 @@
+import uuid
+from pathlib import Path
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from faceverification.core.image_processor import ImageProcessor
+from faceverification.core.vectordb import VectorDB
+
+pytestmark = [pytest.mark.integration, pytest.mark.e2e]
+
+IMAGES_DIR = Path(__file__).parent / "images"
+
+
+def test_real_image_embedding_can_be_enrolled_and_matched_in_vectordb():
+    processor = ImageProcessor(device="cpu")
+    vector_db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_real_image_faces_{uuid.uuid4().hex}",
+    )
+    anchor_image = Image.open(IMAGES_DIR / "person_anchor.jpg").convert("RGB")
+    positive_image = Image.open(IMAGES_DIR / "person_positive.jpg").convert("RGB")
+
+    anchor_embedding = processor.get_embedding(anchor_image).cpu().numpy()
+    positive_embedding = processor.get_embedding(positive_image).cpu().numpy()
+    vector_db.add_embedding(anchor_embedding, {"name": "Ada"})
+
+    metadata, distance = vector_db.query_embedding(
+        positive_embedding,
+        threshold=1.08,
+        n_results=1,
+    )
+
+    assert metadata == {"name": "Ada"}
+    assert distance == pytest.approx(np.linalg.norm(positive_embedding - anchor_embedding))

test/test_image_processor.py

@@ -0,0 +1,126 @@
+from unittest.mock import Mock
+
+import pytest
+import torch
+from PIL import Image
+
+from faceverification.core import image_processor
+from faceverification.core.image_processor import FaceNotDetectedError, ImageProcessor
+
+
+class FakeMTCNN:
+    instances = []
+
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+        FakeMTCNN.instances.append(self)
+
+
+class FakeFacenet:
+    instances = []
+
+    def __init__(self, pretrained):
+        self.pretrained = pretrained
+        self.eval_called = False
+        self.device = None
+        FakeFacenet.instances.append(self)
+
+    def eval(self):
+        self.eval_called = True
+        return self
+
+    def to(self, device):
+        self.device = device
+        return self
+
+
+def test_init_uses_cpu_when_auto_and_cuda_is_unavailable(monkeypatch):
+    FakeMTCNN.instances = []
+    FakeFacenet.instances = []
+    monkeypatch.setattr(image_processor.torch.cuda, "is_available", lambda: False)
+    monkeypatch.setattr(image_processor, "MTCNN", FakeMTCNN)
+    monkeypatch.setattr(image_processor, "InceptionResnetV1", FakeFacenet)
+
+    processor = ImageProcessor(
+        device="auto",
+        mtcnn_thresholds=(0.1, 0.2, 0.3),
+        facenet_pretrained="test-weights",
+    )
+
+    assert processor.device == "cpu"
+    assert FakeMTCNN.instances[0].kwargs == {
+        "select_largest": False,
+        "device": "cpu",
+        "thresholds": [0.1, 0.2, 0.3],
+    }
+    assert FakeFacenet.instances[0].pretrained == "test-weights"
+    assert FakeFacenet.instances[0].eval_called is True
+    assert FakeFacenet.instances[0].device == "cpu"
+
+
+def test_init_rejects_invalid_device():
+    with pytest.raises(ValueError, match="Device must be"):
+        ImageProcessor(device="gpu")
+
+
+def test_get_embedding_returns_normalized_embedding():
+    processor = ImageProcessor.__new__(ImageProcessor)
+    processor.device = "cpu"
+    processor.mtcnn = Mock(return_value=torch.ones((3, 2, 2)))
+    processor.facenet = Mock(return_value=torch.tensor([[3.0, 4.0]]))
+    image = Image.new("RGB", (10, 10))
+
+    embedding = processor.get_embedding(image)
+
+    torch.testing.assert_close(embedding, torch.tensor([0.6, 0.8]))
+    processor.mtcnn.assert_called_once_with(image)
+    assert processor.facenet.call_args.args[0].shape == torch.Size([1, 3, 2, 2])
+
+
+def test_get_embedding_keeps_batched_face_tensor_shape():
+    processor = ImageProcessor.__new__(ImageProcessor)
+    processor.device = "cpu"
+    processor.mtcnn = Mock(return_value=torch.ones((1, 3, 2, 2)))
+    processor.facenet = Mock(return_value=torch.tensor([[3.0, 4.0]]))
+    image = Image.new("RGB", (10, 10))
+
+    embedding = processor.get_embedding(image)
+
+    torch.testing.assert_close(embedding, torch.tensor([0.6, 0.8]))
+    assert processor.facenet.call_args.args[0].shape == torch.Size([1, 3, 2, 2])
+
+
+def test_get_embedding_raises_when_no_face_is_detected():
+    processor = ImageProcessor.__new__(ImageProcessor)
+    processor.mtcnn = Mock(return_value=None)
+
+    with pytest.raises(FaceNotDetectedError, match="No face detected"):
+        processor.get_embedding(Image.new("RGB", (10, 10)))
+
+
+def test_detect_faces_draws_boxes_and_returns_true():
+    processor = ImageProcessor.__new__(ImageProcessor)
+    processor.mtcnn = Mock()
+    processor.mtcnn.detect.return_value = (
+        [[1.0, 1.0, 8.0, 8.0]],
+        [0.98765],
+    )
+    image = Image.new("RGB", (10, 10), "white")
+
+    annotated_image, presence = processor.detect_faces(image)
+
+    assert annotated_image is image
+    assert presence is True
+    assert image.getpixel((1, 1)) == (255, 0, 0)
+
+
+def test_detect_faces_returns_false_when_no_boxes_are_detected():
+    processor = ImageProcessor.__new__(ImageProcessor)
+    processor.mtcnn = Mock()
+    processor.mtcnn.detect.return_value = (None, None)
+    image = Image.new("RGB", (10, 10), "white")
+
+    annotated_image, presence = processor.detect_faces(image)
+
+    assert annotated_image is image
+    assert presence is False

test/test_image_processor_integration.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+import pytest
+import torch
+from PIL import Image
+
+from faceverification.core.image_processor import ImageProcessor
+
+pytestmark = pytest.mark.integration
+
+IMAGES_DIR = Path(__file__).parent / "images"
+
+
+@pytest.fixture(scope="module")
+def processor():
+    return ImageProcessor(device="cpu")
+
+
+@pytest.fixture(scope="module")
+def anchor_image():
+    return Image.open(IMAGES_DIR / "person_anchor.jpg").convert("RGB")
+
+
+@pytest.fixture(scope="module")
+def positive_image():
+    return Image.open(IMAGES_DIR / "person_positive.jpg").convert("RGB")
+
+
+@pytest.fixture(scope="module")
+def negative_image():
+    return Image.open(IMAGES_DIR / "other_people_negative.jpg").convert("RGB")
+
+
+@pytest.mark.parametrize(
+    "image_name",
+    [
+        "person_anchor.jpg",
+        "person_positive.jpg",
+        "other_people_negative.jpg",
+    ],
+)
+def test_detect_faces_finds_faces_in_fixture_images(processor, image_name):
+    image = Image.open(IMAGES_DIR / image_name).convert("RGB")
+
+    annotated_image, presence = processor.detect_faces(image)
+
+    assert annotated_image is image
+    assert presence is True
+
+
+def test_get_embedding_returns_normalized_facenet_vector(processor, anchor_image):
+    embedding = processor.get_embedding(anchor_image)
+
+    assert embedding.ndim == 1
+    assert embedding.shape[0] == 512
+    torch.testing.assert_close(torch.linalg.norm(embedding), torch.tensor(1.0))
+
+
+def test_positive_image_embedding_is_closer_than_negative_image(
+    processor,
+    anchor_image,
+    positive_image,
+    negative_image,
+):
+    anchor_embedding = processor.get_embedding(anchor_image)
+    positive_embedding = processor.get_embedding(positive_image)
+    negative_embedding = processor.get_embedding(negative_image)
+
+    positive_distance = torch.linalg.norm(anchor_embedding - positive_embedding)
+    negative_distance = torch.linalg.norm(anchor_embedding - negative_embedding)
+
+    assert positive_distance < negative_distance

test/test_vectordb.py

@@ -0,0 +1,149 @@
+from unittest.mock import Mock
+
+import numpy as np
+import pytest
+
+from faceverification.core import vectordb
+from faceverification.core.vectordb import VectorDB
+
+
+class FakeClient:
+    def __init__(self, settings):
+        self.settings = settings
+        self.collection = Mock()
+
+    def get_or_create_collection(self, **kwargs):
+        self.collection_kwargs = kwargs
+        return self.collection
+
+
+def test_init_creates_in_memory_collection_with_configured_metric(monkeypatch):
+    clients = []
+
+    def fake_client(settings):
+        client = FakeClient(settings)
+        clients.append(client)
+        return client
+
+    monkeypatch.setattr(vectordb.chromadb, "Client", fake_client)
+
+    db = VectorDB(distance_metric="cosine", name_collection="faces")
+
+    assert db.client is clients[0]
+    assert clients[0].settings.is_persistent is False
+    assert clients[0].settings.persist_directory == ""
+    assert clients[0].collection_kwargs == {
+        "name": "faces",
+        "metadata": {"hnsw:space": "cosine"},
+    }
+    assert db.collection is clients[0].collection
+
+
+def test_init_passes_persist_directory_when_configured(monkeypatch):
+    clients = []
+
+    def fake_client(settings):
+        client = FakeClient(settings)
+        clients.append(client)
+        return client
+
+    monkeypatch.setattr(vectordb.chromadb, "Client", fake_client)
+
+    VectorDB(
+        distance_metric="l2",
+        name_collection="faces",
+        persist_directory="tmp/chroma",
+    )
+
+    assert clients[0].settings.is_persistent is True
+    assert clients[0].settings.persist_directory == "tmp/chroma"
+
+
+def test_add_embedding_stores_embedding_metadata_and_generated_id(monkeypatch):
+    collection = Mock()
+    db = VectorDB.__new__(VectorDB)
+    db.collection = collection
+    embedding = np.array([0.1, 0.2, 0.3])
+    metadata = {"name": "Ada"}
+
+    monkeypatch.setattr(vectordb.uuid, "uuid4", lambda: "fixed-id")
+
+    db.add_embedding(embedding, metadata)
+
+    collection.add.assert_called_once()
+    kwargs = collection.add.call_args.kwargs
+    np.testing.assert_array_equal(kwargs["embeddings"][0], embedding)
+    assert kwargs["metadatas"] == [metadata]
+    assert kwargs["ids"] == ["fixed-id"]
+
+
+def test_query_embedding_returns_closest_metadata_within_threshold():
+    collection = Mock()
+    collection.query.return_value = {
+        "embeddings": [
+            [
+                np.array([3.0, 4.0]),
+                np.array([0.2, 0.1]),
+                np.array([1.0, 1.0]),
+            ]
+        ],
+        "metadatas": [[{"name": "Far"}, {"name": "Near"}, {"name": "Middle"}]],
+        "distances": [[5.0, 0.22, 1.41]],
+    }
+    db = VectorDB.__new__(VectorDB)
+    db.collection = collection
+    query_embedding = np.array([0.0, 0.0])
+
+    metadata, distance = db.query_embedding(
+        query_embedding,
+        threshold=0.5,
+        n_results=3,
+    )
+
+    assert metadata == {"name": "Near"}
+    assert distance == np.linalg.norm(query_embedding - np.array([0.2, 0.1]))
+    collection.query.assert_called_once()
+    assert collection.query.call_args.kwargs["include"] == [
+        "metadatas",
+        "distances",
+        "embeddings",
+    ]
+    assert collection.query.call_args.kwargs["n_results"] == 3
+    np.testing.assert_array_equal(
+        collection.query.call_args.kwargs["query_embeddings"][0],
+        query_embedding,
+    )
+
+
+def test_query_embedding_returns_none_when_closest_distance_exceeds_threshold():
+    collection = Mock()
+    collection.query.return_value = {
+        "embeddings": [[np.array([2.0, 0.0]), np.array([0.0, 3.0])]],
+        "metadatas": [[{"name": "Ada"}, {"name": "Grace"}]],
+        "distances": [[2.0, 3.0]],
+    }
+    db = VectorDB.__new__(VectorDB)
+    db.collection = collection
+
+    metadata, distance = db.query_embedding(
+        np.array([0.0, 0.0]),
+        threshold=1.0,
+        n_results=2,
+    )
+
+    assert metadata is None
+    assert distance == 2.0
+
+
+def test_query_embedding_raises_when_database_has_no_embeddings():
+    collection = Mock()
+    collection.query.return_value = {
+        "embeddings": [np.array([], dtype=float)],
+        "metadatas": [[]],
+        "distances": [[]],
+    }
+    db = VectorDB.__new__(VectorDB)
+    db.collection = collection
+
+    with pytest.raises(ValueError, match="Add a person before verifying faces"):
+        db.query_embedding(np.array([0.0, 0.0]), threshold=1.0, n_results=2)

test/test_vectordb_integration.py

@@ -0,0 +1,66 @@
+import uuid
+
+import numpy as np
+import pytest
+
+from faceverification.core.vectordb import VectorDB
+
+pytestmark = pytest.mark.integration
+
+
+def test_vectordb_adds_and_queries_embedding_with_real_chromadb():
+    db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_faces_{uuid.uuid4().hex}",
+    )
+    stored_embedding = np.array([0.1, 0.2, 0.3])
+    query_embedding = np.array([0.11, 0.19, 0.31])
+
+    db.add_embedding(stored_embedding, {"name": "Ada"})
+
+    metadata, distance = db.query_embedding(
+        query_embedding,
+        threshold=0.1,
+        n_results=1,
+    )
+
+    assert metadata == {"name": "Ada"}
+    assert distance == pytest.approx(np.linalg.norm(query_embedding - stored_embedding))
+
+
+def test_vectordb_raises_when_real_chromadb_collection_is_empty():
+    db = VectorDB(
+        distance_metric="l2",
+        name_collection=f"test_empty_faces_{uuid.uuid4().hex}",
+    )
+
+    with pytest.raises(ValueError, match="Add a person before verifying faces"):
+        db.query_embedding(np.array([0.1, 0.2, 0.3]), threshold=0.1, n_results=1)
+
+
+def test_vectordb_persists_embeddings_between_instances(tmp_path):
+    persist_directory = tmp_path / "chroma"
+    collection_name = f"test_persistent_faces_{uuid.uuid4().hex}"
+    stored_embedding = np.array([0.1, 0.2, 0.3])
+    query_embedding = np.array([0.11, 0.19, 0.31])
+
+    first_db = VectorDB(
+        distance_metric="l2",
+        name_collection=collection_name,
+        persist_directory=str(persist_directory),
+    )
+    first_db.add_embedding(stored_embedding, {"name": "Ada"})
+
+    second_db = VectorDB(
+        distance_metric="l2",
+        name_collection=collection_name,
+        persist_directory=str(persist_directory),
+    )
+    metadata, distance = second_db.query_embedding(
+        query_embedding,
+        threshold=0.1,
+        n_results=1,
+    )
+
+    assert metadata == {"name": "Ada"}
+    assert distance == pytest.approx(np.linalg.norm(query_embedding - stored_embedding))