<?php

/**
 * JCOGS Image Pro - Face Recognition Provider Interface
 * Extension Architecture Foundation
 * 
 * @category   ExpressionEngine Add-on
 * @package    JCOGS Image Pro
 * @author     JCOGS Design <contact@jcogs.net>
 * @copyright  Copyright (c) 2021 - 2025 JCOGS Design
 * @license    https://jcogs.net/add-ons/license/jcogs_img_pro
 * @version    2.0.6
 * @link       https://JCOGS.net/
 * @since      Extension Architecture v1.0
 */

namespace JCOGSDesign\JCOGSImagePro\Service\Provider;

/**
 * Face Recognition Provider Interface
 * 
 * Allows external add-ons to register face recognition implementations
 * that extend core face detection capabilities.
 * 
 * Priority Levels:
 * - 10: Core HAARPHP implementation (baseline)
 * - 20-50: Premium local algorithms (future)
 * - 100+: Cloud API providers (highest accuracy)
 * 
 * Extension add-ons can implement this interface and register their
 * providers via the 'jcogs_img_pro_register_providers' extension hook.
 */
interface FaceRecognitionProviderInterface 
{
    /**
     * Get provider name for logging/debugging
     * 
     * @return string Provider identifier (e.g., 'aws_rekognition', 'core_haar')
     */
    public function getName(): string;
    
    /**
     * Get provider priority (higher = preferred)
     * 
     * Core HAARPHP uses priority 10. Extensions should use 20+ for local
     * algorithms or 100+ for cloud APIs.
     * 
     * @return int Priority value
     */
    public function getPriority(): int;
    
    /**
     * Check if provider is available and configured
     * 
     * Should verify:
     * - Required libraries/extensions present
     * - API credentials configured (if applicable)
     * - Network connectivity (if applicable)
     * 
     * IMPORTANT: Must NOT throw exceptions. Return false on any error.
     * 
     * @return bool True if provider can be used
     */
    public function isAvailable(): bool;
    
    /**
     * Detect faces with additional metadata
     * 
     * @param resource|\GdImage $image GD image resource
     * @param array $options Detection options:
     *   - sensitivity: int (1-9, for compatibility)
     *   - quality: string ('fast'|'balanced'|'accurate')
     *   - max_faces: int|null (limit results, null = unlimited)
     *   - min_confidence: float (0.0-1.0, filter low-confidence results)
     * 
     * @return array Face regions with metadata:
     *   [
     *     [
     *       'x' => int,           // Top-left X coordinate
     *       'y' => int,           // Top-left Y coordinate
     *       'width' => int,       // Face width in pixels
     *       'height' => int,      // Face height in pixels
     *       'confidence' => float, // Detection confidence (0.0-1.0)
     *       'metadata' => [       // Optional provider-specific metadata
     *         'emotions' => [...],
     *         'age_range' => [...],
     *         'gender' => [...],
     *         // etc.
     *       ]
     *     ],
     *     // ... additional faces
     *   ]
     * 
     * @throws \Exception on detection failure (caller should catch and fall back)
     */
    public function detectFaces($image, array $options = []): array;
    
    /**
     * Get provider capabilities
     * 
     * Allows core to discover what metadata the provider returns.
     * 
     * @return array Capability flags:
     *   [
     *     'emotions' => bool,      // Emotion detection (happy, sad, etc.)
     *     'age_estimation' => bool, // Age range estimation
     *     'gender' => bool,        // Gender classification
     *     'landmarks' => bool,     // Facial landmarks (eyes, nose, mouth)
     *     'pose' => bool,          // Head pose estimation
     *     'quality' => bool,       // Face quality metrics
     *     'attributes' => bool,    // Other attributes (glasses, beard, etc.)
     *   ]
     */
    public function getCapabilities(): array;
    
    /**
     * Get estimated cost per detection (if applicable)
     * 
     * @return float|null Cost in USD, or null if free/included
     */
    public function getCostPerDetection(): ?float;
}
