Skip to content

CLAUDE.md

Latest commit

 

History

History
95 lines (66 loc) · 4.58 KB

CLAUDE.md

File metadata and controls

95 lines (66 loc) · 4.58 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Face API is a production-ready RESTful API wrapper for DeepFace, providing face verification, recognition, analysis, and embedding generation capabilities. Built with FastAPI, SQLModel, and Pydantic for type safety and auto-documentation.

Development Commands

Setup

# Install dependencies (uses uv for package management)
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env and set API_KEY

Running the Application

# Development mode (auto-reload enabled)
face-api

# Production mode
uvicorn face_api.main:app --host 0.0.0.0 --port 8000

The API runs on http://localhost:8000 with interactive docs at http://localhost:8000/docs.

Architecture

Core Design Pattern

The project follows a layered architecture with clear separation of concerns:

  1. API Layer (src/face_api/api/routes/) - FastAPI route handlers for each endpoint (verify, analyze, embed, recognize)
  2. Service Layer (src/face_api/services/deepface_service.py) - Wrapper around DeepFace library with default configurations
  3. Data Layer (src/face_api/models/) - SQLModel database models and Pydantic schemas
  4. Configuration (src/face_api/config.py) - Centralized settings using pydantic-settings

Key Components

DeepFaceService (src/face_api/services/deepface_service.py)

  • Global singleton wrapping DeepFace operations
  • Manages default model configurations from settings
  • Provides: verify(), analyze(), represent(), extract_faces()
  • All methods accept optional overrides for model_name, detector_backend, etc.

Database Models (src/face_api/models/face.py)

  • FaceEmbedding: Stores face embeddings with person_id, model metadata, and JSON-serialized embedding vectors
  • VerificationLog: Audit trail for verification requests with results and metadata

Authentication (src/face_api/api/dependencies.py)

  • Header-based API key authentication via X-API-Key header
  • verify_api_key() dependency used across all routes

Request/Response Schemas (src/face_api/models/schemas.py)

  • Full Pydantic validation for all endpoints
  • Images can be base64-encoded strings or file paths
  • All requests support optional overrides for model_name, detector_backend, distance_metric

Face Recognition Flow

The recognize endpoint (src/face_api/api/routes/recognize.py) implements custom matching logic:

  1. Generate embedding for input image using DeepFace
  2. Query database for stored embeddings (filtered by model_name and optionally person_id)
  3. Calculate distances using numpy (calculate_distance() function supports cosine, euclidean, euclidean_l2)
  4. Filter matches below threshold (default: 0.4 for cosine distance)
  5. Return sorted results with distance and similarity scores

This is different from verify endpoint which uses DeepFace's built-in verification.

Configuration Management

Settings are loaded from .env file via pydantic-settings (src/face_api/config.py):

  • Required: API_KEY
  • Optional with defaults: DATABASE_URL, FACE_DETECTOR_BACKEND, FACE_RECOGNITION_MODEL, DISTANCE_METRIC, etc.

All DeepFace parameters (models, detectors, distance metrics) can be configured globally via environment variables or overridden per-request.

Database Initialization

The application uses SQLite by default. Database tables are created automatically on startup via the lifespan context manager in src/face_api/main.py.

Sessions are managed via dependency injection using get_session() from src/face_api/database.py.

Important Notes

  • Image Format: All endpoints accept images as either file paths or base64-encoded strings
  • Embedding Storage: Embeddings are stored as JSON strings in the database (not binary)
  • Model Consistency: When recognizing faces, ensure the same model_name is used for both storing and querying embeddings
  • Distance Metrics: Lower distance = higher similarity. Default thresholds vary by metric (cosine: ~0.4, euclidean: ~10, euclidean_l2: ~1.0)
  • Entry Point: The CLI entry point face-api is defined in src/face_api/init.py:9 and runs uvicorn with reload enabled