Asguard Face Service

Asguard Face is a robust and scalable facial recognition service built with Go. It provides API endpoints for analyzing images, extracting face embeddings, comparing faces, and managing API keys with usage quotas. The service is designed for easy deployment using Docker.

Features

• Face Detection & Embedding Extraction: Analyze images to detect faces and extract unique facial embeddings.
• Face Comparison: Compare a probe image against a reference embedding to determine a match and confidence score.
• Image Quality Checks: Optional quality checks during analysis for sharpness, brightness, and face size ratio.
• API Key Authentication: Secure access to the service using API keys.
• Usage Quotas: Manage and track monthly API usage for different tenants.
• Admin API: Endpoints for creating and managing API keys.
• Containerized Deployment: Easily deployable with Docker and Docker Compose.

Technologies Used

• Go: The primary programming language for the service.
• Gin Web Framework: A high-performance HTTP web framework for Go.
• go-face: Go binding for dlib's face recognition model.
• SQLite: Used for persistent storage of API keys and usage data.
• Docker: For containerization and simplified deployment.

Installation

The easiest way to get Asguard Face running is by using Docker Compose.

Prerequisites

• Docker
• Docker Compose

Steps

1. Clone the repository:

   git clone https://github.com/your-repo/asguard-face.git
   cd asguard-face

   (Note: Replace https://github.com/your-repo/asguard-face.git with the actual repository URL)

2. Prepare environment variables: Create a .env file in the root directory with the following content:

   ADMIN_SECRET=your_admin_secret_key_here
   PORT=8082
   

   Replace your_admin_secret_key_here with a strong, unique secret for accessing admin functionalities.

3. Run with Docker Compose:

   docker-compose up --build -d

   This will build the Docker image, start the service, and expose it on port 8082 (or the port specified in your .env file).

API Endpoints

The Asguard Face service exposes the following API endpoints:

Public Endpoints

• GET /health
  • Description: Checks the health status of the service.
  • Response: {"status": "healthy", "service": "asguard-face", "version": "1.0.0"}

Protected Endpoints (Requires API Key)

These endpoints require an API key to be provided in the X-API-Key header or as a Bearer token in the Authorization header.

• POST /v1/analyze

  • Description: Analyzes an image to detect faces and extract a 128-dimensional face embedding. Optionally performs quality checks.
  • Request Body:

    {
        "image": "base64_encoded_image_string",
        "quality_checks": true
    }

  • Response: AnalyzeResponse object containing embedding, quality_score, sharpness, brightness, face_size_ratio, and warnings.

• POST /v1/compare

  • Description: Compares a probe image against a provided reference face embedding.
  • Request Body:

    {
        "probe_image": "base64_encoded_image_string",
        "reference_embedding": [float32, ... (128 dimensions)],
        "threshold": 0.6
    }

  • Response: CompareResponse object indicating match, confidence, distance, and probe_quality.

Admin Endpoints (Requires Admin Secret)

These endpoints require the ADMIN_SECRET to be provided in the X-API-Key header.

• POST /admin/keys/create
  • Description: Creates a new API key for a tenant with an optional monthly quota.
  • Request Body:

    {
        "name": "Tenant Name",
        "quota": 10000
    }

  • Response: Object containing tenantID and the newly generated apiKey.

Authentication

Access to protected API endpoints is controlled via API keys. You can provide your API key in one of two ways:

1. X-API-Key Header: Include your API key directly in the X-API-Key HTTP header. X-API-Key: your_api_key_here
2. Authorization Header (Bearer Token): Include your API key as a Bearer token in the Authorization HTTP header. Authorization: Bearer your_api_key_here

Admin endpoints require the ADMIN_SECRET (configured via environment variable) to be passed in the X-API-Key header.

Configuration

The service can be configured using the following environment variables:

• ADMIN_SECRET: (Required for admin endpoints) A secret key used to authenticate requests to admin endpoints.
• PORT: (Optional, default: 8082) The port on which the service will listen for incoming requests.
• MODELS_PATH: (Optional, default: ./models) The path to the directory containing the dlib face recognition models. When running with Docker, this is typically /app/models.

Contributing

(Add contributing guidelines here)

License

This project is licensed under the MIT License. See the LICENSE file for details.