Sync from GitHub via hub-sync

README.md

@@ -76,7 +76,16 @@ Interactive API documentation is available at:
 
 Protected endpoints require a bearer token. The default demo credentials are
 `demo` / `demo123`; override them with `FACEVERIFICATION_DEMO_USERNAME` and
-`FACEVERIFICATION_DEMO_PASSWORD` in `.env`.
+`FACEVERIFICATION_DEMO_PASSWORD` in `.env`. The JWT secret is also configurable
+and should be changed outside local demos.
+
+```env
+FACEVERIFICATION_DEMO_USERNAME=demo
+FACEVERIFICATION_DEMO_PASSWORD=demo123
+FACEVERIFICATION_JWT_SECRET_KEY=replace-this-with-a-long-random-secret
+FACEVERIFICATION_JWT_ACCESS_TOKEN_EXPIRE_MINUTES=60
+FACEVERIFICATION_MAX_UPLOAD_BYTES=5242880
+```
 
 ```bash
 curl -X POST http://localhost:8000/auth/login \
@@ -97,6 +106,9 @@ Authorization: Bearer <access_token>
 - `POST /persons`: enrolls a known person from an uploaded image and form `name`.
 - `POST /verify`: verifies whether an uploaded face matches a known person.
 
+Both face endpoints return an annotated image by default. Add
+`?include_image=false` when the client only needs the JSON result.
+
 ## Deployment Notes
 
 For API deployments, the recommended baseline is the FastAPI container running

src/faceverification/config.py

@@ -19,6 +19,7 @@ class Settings(BaseSettings):
     jwt_secret_key: str = "change-me-in-production-demo-secret-32-bytes-min"
     jwt_algorithm: str = "HS256"
     jwt_access_token_expire_minutes: int = 60
+    max_upload_bytes: int = 5 * 1024 * 1024
 
     model_config = SettingsConfigDict(
         env_file=".env",

src/faceverification/core/image_processor.py

@@ -1,9 +1,4 @@
-"""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.
-"""
+"""Face detection and FaceNet embedding utilities."""
 
 from collections.abc import Sequence
 
@@ -20,12 +15,7 @@ class FaceNotDetectedError(ValueError):
 
 
 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.
-    """
+    """Wrap MTCNN detection and FaceNet embedding extraction."""
 
     def __init__(
         self,
@@ -33,16 +23,12 @@ class ImageProcessor:
         mtcnn_thresholds: Sequence[float] | None = None,
         facenet_pretrained: str | None = None,
     ):
-        """Initialize face detection and embedding models.
+        """Load models using explicit values or application settings.
 
         Args:
-            device: Device used for model inference. Use `"auto"` to select
-                CUDA when available, otherwise CPU.
+            device: Inference device. Use `"auto"` to prefer CUDA when available.
             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"`.
+            facenet_pretrained: Pretrained FaceNet weights name.
         """
         if device is None:
             device = settings.device
@@ -65,16 +51,16 @@ class ImageProcessor:
         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.
+        """Return a normalized FaceNet embedding for the detected face.
 
         Args:
-            image: PIL image containing a face.
+            image: PIL image containing a detectable face.
 
         Returns:
-            A one-dimensional normalized FaceNet embedding tensor.
+            One normalized FaceNet embedding tensor.
 
         Raises:
-            FaceNotDetectedError: If no face can be detected in the image.
+            FaceNotDetectedError: If MTCNN cannot extract a face.
         """
         face_tensor = self.mtcnn(image)
         if face_tensor is None:
@@ -91,14 +77,13 @@ class ImageProcessor:
         return features.squeeze(0)
 
     def detect_faces(self, image: Image.Image) -> tuple[Image.Image, bool]:
-        """Draw detected face bounding boxes on an image.
+        """Draw face boxes and return whether any face was found.
 
         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.
+            The annotated image and a flag indicating if at least one face was found.
         """
         boxes, probs = self.mtcnn.detect(image)
 

src/faceverification/core/vectordb.py

@@ -1,10 +1,4 @@
-"""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.
-"""
+"""Small ChromaDB adapter for face embedding storage and lookup."""
 
 import uuid
 from collections.abc import Mapping
@@ -18,13 +12,7 @@ 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.
-    """
+    """Store face embeddings and query the nearest known identity."""
 
     def __init__(
         self,
@@ -32,15 +20,12 @@ class VectorDB:
         name_collection: str | None = None,
         persist_directory: str | None = None,
     ):
-        """Initialize the ChromaDB client and face embeddings collection.
+        """Create an in-memory or persistent Chroma 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.
+            distance_metric: Chroma HNSW metric, such as `"l2"` or `"cosine"`.
+            name_collection: Collection name for stored face embeddings.
+            persist_directory: Directory for persistent storage, or `None` for memory.
         """
         if distance_metric is None:
             distance_metric = settings.vector_db_distance_metric
@@ -60,13 +45,11 @@ class VectorDB:
         )
 
     def add_embedding(self, embedding: np.ndarray, metadata: Mapping[str, Any]) -> None:
-        """Add one face embedding and its metadata to the collection.
+        """Store one embedding with its metadata.
 
         Args:
-            embedding: Face embedding vector produced by the face recognition
-                model.
-            metadata: Metadata associated with the embedding, such as the
-                person's name.
+            embedding: Face embedding vector.
+            metadata: Data associated with the embedding, such as a person's name.
         """
         self.collection.add(
             embeddings=[embedding],
@@ -80,18 +63,16 @@ class VectorDB:
         threshold: float | None = None,
         n_results: int | None = None,
     ) -> tuple[Mapping[str, Any] | None, float]:
-        """Find the closest stored embedding within the configured threshold.
+        """Return matched metadata and distance, or `None` when outside 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.
+            embedding: Query embedding vector.
+            threshold: Maximum accepted distance for a match.
+            n_results: Number of nearest Chroma 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.
+            Matched metadata and best distance. Metadata is `None` when no
+            candidate is close enough.
         """
         if threshold is None:
             threshold = settings.face_match_threshold

src/faceverification/interfaces/fastapi_app.py

@@ -1,40 +1,24 @@
-"""HTTP API for enrolling and verifying faces.
-
-The module exposes a small FastAPI application around the service layer:
-
-- ``POST /auth/login`` issues a short-lived JWT for the demo user.
-- ``POST /persons`` stores a known person embedding from an uploaded image.
-- ``POST /verify`` checks whether an uploaded face matches the local database.
-
-FastAPI uses the route metadata, Pydantic field descriptions, and endpoint
-docstrings below to build the interactive documentation at ``/docs`` and
-``/redoc``.
-"""
-
+import logging
 from base64 import b64encode
 from contextlib import asynccontextmanager
 from datetime import UTC, datetime, timedelta
 from io import BytesIO
 from secrets import compare_digest
-from types import ModuleType
-from typing import Annotated
+from typing import Annotated, Protocol
 
 import jwt
-from fastapi import Depends, FastAPI, File, Form, HTTPException, Request, UploadFile, status
+from fastapi import Depends, FastAPI, File, Form, HTTPException, Query, Request, UploadFile, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from jwt import ExpiredSignatureError, InvalidTokenError
 from PIL import Image, ImageOps, UnidentifiedImageError
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from faceverification.config import settings
 from faceverification.core.image_processor import FaceNotDetectedError
+from faceverification.services.face_verification import UNREGISTERED_PERSON
 
 bearer_scheme = HTTPBearer(auto_error=False)
-
-DATA_URL_DESCRIPTION = (
-    "PNG image encoded as a data URL. The image contains the service annotations "
-    "for the detected face."
-)
+logger = logging.getLogger(__name__)
 
 AUTH_RESPONSES = {
     status.HTTP_401_UNAUTHORIZED: {
@@ -64,6 +48,14 @@ IMAGE_ERROR_RESPONSES = {
             },
         },
     },
+    status.HTTP_413_CONTENT_TOO_LARGE: {
+        "description": "The uploaded image is too large.",
+        "content": {
+            "application/json": {
+                "example": {"detail": "Uploaded image is too large."},
+            },
+        },
+    },
     status.HTTP_422_UNPROCESSABLE_CONTENT: {
         "description": "The request is valid, but no usable face or name was found.",
         "content": {
@@ -83,9 +75,20 @@ IMAGE_ERROR_RESPONSES = {
 }
 
 
+class FaceService(Protocol):
+    """Service contract required by the HTTP layer.
+
+    Implementations must accept normalized PIL images and return annotated PIL
+    images for optional API responses.
+    """
+
+    def add_person(self, image: Image.Image, name: str) -> Image.Image: ...
+
+    def verify_person(self, image: Image.Image) -> tuple[str, Image.Image]: ...
+
+
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """Load the face verification service once when the API starts."""
     from faceverification.services import face_verification
 
     app.state.face_service = face_verification
@@ -94,11 +97,7 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(
     title="Face Verification API",
-    description=(
-        "Demo API for enrolling known people and verifying uploaded face images. "
-        "Authenticate with `/auth/login`, then send the returned bearer token to "
-        "the protected face-verification endpoints."
-    ),
+    description="Enroll known people and verify uploaded face images.",
     version="0.1.0",
     lifespan=lifespan,
     contact={
@@ -109,17 +108,13 @@ app = FastAPI(
 
 
 class HealthResponse(BaseModel):
-    """Health-check payload returned by the system endpoint."""
-
-    status: str = Field(default="ok", description="Current API status.")
+    status: str = "ok"
 
 
 class EnrollResponse(BaseModel):
-    """Response returned after a person is stored in the embeddings database."""
-
-    message: str = Field(description="Human-readable result message.")
-    name: str = Field(description="Normalized person name stored with the embedding.")
-    annotated_image: str = Field(description=DATA_URL_DESCRIPTION)
+    message: str
+    name: str
+    annotated_image: str | None = None
 
     model_config = {
         "json_schema_extra": {
@@ -133,16 +128,9 @@ class EnrollResponse(BaseModel):
 
 
 class VerifyResponse(BaseModel):
-    """Response returned after comparing an uploaded face against known people."""
-
-    name: str = Field(
-        description=(
-            "Matched person name. Returns `Unregistered Person` when the closest "
-            "embedding is outside the configured match threshold."
-        ),
-    )
-    matched: bool = Field(description="Whether the uploaded face matched a known person.")
-    annotated_image: str = Field(description=DATA_URL_DESCRIPTION)
+    name: str
+    matched: bool
+    annotated_image: str | None = None
 
     model_config = {
         "json_schema_extra": {
@@ -156,10 +144,8 @@ class VerifyResponse(BaseModel):
 
 
 class TokenResponse(BaseModel):
-    """Bearer token returned by the demo authentication endpoint."""
-
-    access_token: str = Field(description="JWT access token used in the Authorization header.")
-    token_type: str = Field(default="bearer", description="OAuth2-compatible token type.")
+    access_token: str
+    token_type: str = "bearer"
 
     model_config = {
         "json_schema_extra": {
@@ -171,13 +157,11 @@ class TokenResponse(BaseModel):
     }
 
 
-def get_face_service(request: Request) -> ModuleType:
-    """Return the service module stored during application startup."""
+def get_face_service(request: Request) -> FaceService:
     return request.app.state.face_service
 
 
 def _unauthorized_error(detail: str = "Could not validate credentials.") -> HTTPException:
-    """Build a consistent 401 response with the bearer authentication challenge."""
     return HTTPException(
         status_code=status.HTTP_401_UNAUTHORIZED,
         detail=detail,
@@ -186,14 +170,12 @@ def _unauthorized_error(detail: str = "Could not validate credentials.") -> HTTP
 
 
 def _create_access_token(username: str) -> str:
-    """Create a signed JWT for the authenticated demo user."""
     expires_at = datetime.now(UTC) + timedelta(minutes=settings.jwt_access_token_expire_minutes)
     payload = {"sub": username, "exp": expires_at}
     return jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
 
 
 def _authenticate_demo_user(username: str, password: str) -> bool:
-    """Validate demo credentials using constant-time comparisons."""
     valid_username = compare_digest(username, settings.demo_username)
     valid_password = compare_digest(password, settings.demo_password)
     return valid_username and valid_password
@@ -202,7 +184,6 @@ def _authenticate_demo_user(username: str, password: str) -> bool:
 def get_current_username(
     credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer_scheme)],
 ) -> str:
-    """Decode the bearer token and return the authenticated username."""
     if credentials is None:
         raise _unauthorized_error("Not authenticated")
 
@@ -226,7 +207,18 @@ def get_current_username(
 
 
 async def _read_image(upload: UploadFile) -> Image.Image:
-    """Read an uploaded image, apply EXIF orientation, and return it as RGB."""
+    """Validate an upload and return it as an RGB image.
+
+    Args:
+        upload: Multipart file received by FastAPI.
+
+    Returns:
+        RGB PIL image with EXIF orientation applied.
+
+    Raises:
+        HTTPException: If the file is not an image, is empty, too large, or invalid.
+    """
+
     if upload.content_type and not upload.content_type.startswith("image/"):
         raise HTTPException(
             status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
@@ -239,6 +231,11 @@ async def _read_image(upload: UploadFile) -> Image.Image:
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="Uploaded image is empty.",
         )
+    if len(contents) > settings.max_upload_bytes:
+        raise HTTPException(
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+            detail="Uploaded image is too large.",
+        )
 
     try:
         image = Image.open(BytesIO(contents))
@@ -252,25 +249,28 @@ async def _read_image(upload: UploadFile) -> Image.Image:
 
 
 def _image_to_data_url(image: Image.Image) -> str:
-    """Serialize a PIL image as a PNG data URL for JSON responses."""
     buffer = BytesIO()
     image.save(buffer, format="PNG")
     encoded = b64encode(buffer.getvalue()).decode("ascii")
     return f"data:image/png;base64,{encoded}"
 
 
-def _service_error(exc: Exception) -> HTTPException:
-    """Map service-layer exceptions to API-friendly HTTP errors."""
-    if isinstance(exc, FaceNotDetectedError):
-        return HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
-            detail=str(exc),
-        )
-    if isinstance(exc, ValueError):
-        return HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(exc),
-        )
+def _face_not_detected_error(exc: FaceNotDetectedError) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_422_UNPROCESSABLE_CONTENT,
+        detail=str(exc),
+    )
+
+
+def _bad_service_request(exc: ValueError) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail=str(exc),
+    )
+
+
+def _unexpected_service_error(exc: Exception) -> HTTPException:
+    logger.exception("Face verification service failed")
     return HTTPException(
         status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
         detail="Face verification failed.",
@@ -281,19 +281,16 @@ def _service_error(exc: Exception) -> HTTPException:
     "/health",
     response_model=HealthResponse,
     summary="Check API health",
-    response_description="The API is running.",
     tags=["system"],
 )
 def health() -> HealthResponse:
-    """Return a lightweight status response for uptime checks."""
     return HealthResponse()
 
 
 @app.post(
     "/auth/login",
     response_model=TokenResponse,
-    summary="Issue a demo access token",
-    response_description="JWT bearer token for protected endpoints.",
+    summary="Log in",
     responses={
         status.HTTP_401_UNAUTHORIZED: {
             "description": "The username or password is incorrect.",
@@ -309,14 +306,13 @@ def health() -> HealthResponse:
 def login(
     username: Annotated[
         str,
-        Form(description="Demo username configured with `FACEVERIFICATION_DEMO_USERNAME`."),
+        Form(),
     ],
     password: Annotated[
         str,
-        Form(description="Demo password configured with `FACEVERIFICATION_DEMO_PASSWORD`."),
+        Form(),
     ],
 ) -> TokenResponse:
-    """Authenticate the demo user and return a signed JWT access token."""
     if not _authenticate_demo_user(username, password):
         raise _unauthorized_error("Incorrect username or password.")
 
@@ -326,9 +322,9 @@ def login(
 @app.post(
     "/persons",
     response_model=EnrollResponse,
+    response_model_exclude_none=True,
     status_code=status.HTTP_201_CREATED,
     summary="Enroll a known person",
-    response_description="The person was stored and the annotated upload is returned.",
     responses={**AUTH_RESPONSES, **IMAGE_ERROR_RESPONSES},
     tags=["face verification"],
 )
@@ -342,14 +338,13 @@ async def enroll_person(
         Form(description="Person name to associate with the generated face embedding."),
     ],
     current_username: Annotated[str, Depends(get_current_username)],
-    service: Annotated[ModuleType, Depends(get_face_service)],
+    service: Annotated[FaceService, Depends(get_face_service)],
+    include_image: Annotated[
+        bool,
+        Query(description="Include the annotated image as a base64 data URL."),
+    ] = True,
 ) -> EnrollResponse:
-    """Store a new known person in the embeddings database.
-
-    The endpoint extracts a face embedding from the uploaded image and stores it
-    under the submitted name. It returns the normalized name and a PNG data URL
-    with the annotated detection result.
-    """
+    _ = current_username
     cleaned_name = name.strip()
     if not cleaned_name:
         raise HTTPException(
@@ -360,21 +355,25 @@ async def enroll_person(
     pil_image = await _read_image(image)
     try:
         annotated_image = service.add_person(pil_image, cleaned_name)
+    except FaceNotDetectedError as exc:
+        raise _face_not_detected_error(exc) from exc
+    except ValueError as exc:
+        raise _bad_service_request(exc) from exc
     except Exception as exc:
-        raise _service_error(exc) from exc
+        raise _unexpected_service_error(exc) from exc
 
     return EnrollResponse(
         message="Person added to the embeddings database.",
         name=cleaned_name,
-        annotated_image=_image_to_data_url(annotated_image),
+        annotated_image=_image_to_data_url(annotated_image) if include_image else None,
     )
 
 
 @app.post(
     "/verify",
     response_model=VerifyResponse,
+    response_model_exclude_none=True,
     summary="Verify an uploaded face",
-    response_description="Best match result and the annotated upload.",
     responses={**AUTH_RESPONSES, **IMAGE_ERROR_RESPONSES},
     tags=["face verification"],
 )
@@ -384,23 +383,27 @@ async def verify_identity(
         File(description="Image containing one clear face to compare with known people."),
     ],
     current_username: Annotated[str, Depends(get_current_username)],
-    service: Annotated[ModuleType, Depends(get_face_service)],
+    service: Annotated[FaceService, Depends(get_face_service)],
+    include_image: Annotated[
+        bool,
+        Query(description="Include the annotated image as a base64 data URL."),
+    ] = True,
 ) -> VerifyResponse:
-    """Compare an uploaded face against the local embeddings database.
-
-    A successful response always includes the closest label and whether it is
-    considered a match according to the configured distance threshold.
-    """
+    _ = current_username
     pil_image = await _read_image(image)
     try:
         name, annotated_image = service.verify_person(pil_image)
+    except FaceNotDetectedError as exc:
+        raise _face_not_detected_error(exc) from exc
+    except ValueError as exc:
+        raise _bad_service_request(exc) from exc
     except Exception as exc:
-        raise _service_error(exc) from exc
+        raise _unexpected_service_error(exc) from exc
 
     return VerifyResponse(
         name=name,
-        matched=name != "Unregistered Person",
-        annotated_image=_image_to_data_url(annotated_image),
+        matched=name != UNREGISTERED_PERSON,
+        annotated_image=_image_to_data_url(annotated_image) if include_image else None,
     )
 
 

src/faceverification/services/face_verification.py

@@ -1,32 +1,30 @@
-"""Application service functions for face enrollment and verification.
-
-This module coordinates image preprocessing, embedding extraction, and vector
-database operations for the Gradio interface.
-"""
+"""Application service functions for face enrollment and verification."""
 
 from PIL import Image
 
 from faceverification.core.image_processor import FaceNotDetectedError, ImageProcessor
 from faceverification.core.vectordb import VectorDB
 
+UNREGISTERED_PERSON = "Unregistered Person"
+
 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.
+    """Store a person's face embedding and return the annotated image.
 
     Args:
-        image: Input image provided by the UI as a PIL image.
-        name: Person name to store as embedding metadata.
+        image: PIL image containing the person's face.
+        name: Person name to store with the embedding.
 
     Returns:
-        The input image annotated with detected face bounding boxes.
+        Image annotated with detected face boxes.
 
     Raises:
-        FaceNotDetectedError: If no face is detected in the input image.
-        TypeError: If embedding extraction does not return the expected tensor.
+        FaceNotDetectedError: If no face is detected.
+        TypeError: If embedding extraction returns an unexpected value.
     """
 
     img, presence = image_processor.detect_faces(image)
@@ -35,26 +33,26 @@ def add_person(image: Image.Image, name: str) -> Image.Image:
         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:
+    if faces_pt is None:
         raise TypeError("The extracted face embedding is not a torch.Tensor.")
 
+    vector_db.add_embedding(faces_pt.cpu().numpy(), {"name": name})
+
     return img
 
 
 def verify_person(image: Image.Image) -> tuple[str, Image.Image]:
-    """Verify whether the input face matches a stored person.
+    """Return the closest known person name and the annotated image.
 
     Args:
-        image: Input image provided by the UI as a PIL image.
+        image: PIL image containing the face to verify.
 
     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.
+        Matched person name, or `UNREGISTERED_PERSON`, plus the annotated image.
 
     Raises:
-        FaceNotDetectedError: If no face is detected in the input image.
+        FaceNotDetectedError: If no face is detected.
+        ValueError: If the vector database has no stored embeddings.
     """
     detected_faces, presence = image_processor.detect_faces(image.copy())
 
@@ -62,12 +60,12 @@ def verify_person(image: Image.Image) -> tuple[str, Image.Image]:
         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 faces_pt is None:
+        raise FaceNotDetectedError("No faces were detected in the image.")
 
-        if metadata:
-            return metadata["name"], detected_faces
+    metadata, _ = vector_db.query_embedding(faces_pt.cpu().numpy())
 
-        return "Unregistered Person", detected_faces
+    if metadata:
+        return metadata["name"], detected_faces
 
-    raise FaceNotDetectedError("No faces were detected in the image.")
+    return UNREGISTERED_PERSON, detected_faces

test/test_fastapi_app.py

@@ -3,6 +3,7 @@ from io import BytesIO
 from fastapi.testclient import TestClient
 from PIL import Image
 
+from faceverification.config import settings
 from faceverification.core.image_processor import FaceNotDetectedError
 from faceverification.interfaces.fastapi_app import app, get_face_service
 
@@ -125,6 +126,24 @@ def test_verify_identity_returns_match_result():
     assert body["annotated_image"].startswith("data:image/png;base64,")
 
 
+def test_verify_identity_can_skip_annotated_image():
+    fake_service = FakeService()
+    app.dependency_overrides[get_face_service] = lambda: fake_service
+    try:
+        client = TestClient(app)
+        response = client.post(
+            "/verify?include_image=false",
+            headers=_auth_headers(client),
+            files={"image": ("face.png", _image_bytes(), "image/png")},
+        )
+    finally:
+        app.dependency_overrides.clear()
+
+    body = response.json()
+    assert response.status_code == 200
+    assert body == {"name": "Ada", "matched": True}
+
+
 def test_verify_identity_returns_unprocessable_when_no_face_is_detected():
     class NoFaceService(FakeService):
         def verify_person(self, image):
@@ -145,6 +164,26 @@ def test_verify_identity_returns_unprocessable_when_no_face_is_detected():
     assert response.json() == {"detail": "No faces were detected in the image."}
 
 
+def test_verify_identity_returns_internal_error_for_unexpected_service_failure():
+    class BrokenService(FakeService):
+        def verify_person(self, image):
+            raise RuntimeError("model failed")
+
+    app.dependency_overrides[get_face_service] = lambda: BrokenService()
+    try:
+        client = TestClient(app)
+        response = client.post(
+            "/verify",
+            headers=_auth_headers(client),
+            files={"image": ("face.png", _image_bytes(), "image/png")},
+        )
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 500
+    assert response.json() == {"detail": "Face verification failed."}
+
+
 def test_enroll_person_rejects_blank_name():
     app.dependency_overrides[get_face_service] = lambda: FakeService()
     try:
@@ -176,3 +215,20 @@ def test_upload_rejects_non_image_content_type():
 
     assert response.status_code == 415
     assert response.json() == {"detail": "Uploaded file must be an image."}
+
+
+def test_upload_rejects_large_image(monkeypatch):
+    monkeypatch.setattr(settings, "max_upload_bytes", 1)
+    app.dependency_overrides[get_face_service] = lambda: FakeService()
+    try:
+        client = TestClient(app)
+        response = client.post(
+            "/verify",
+            headers=_auth_headers(client),
+            files={"image": ("face.png", _image_bytes(), "image/png")},
+        )
+    finally:
+        app.dependency_overrides.clear()
+
+    assert response.status_code == 413
+    assert response.json() == {"detail": "Uploaded image is too large."}