<?php

declare(strict_types=1);

namespace App\Framework\MachineLearning\Core;

use App\Framework\MachineLearning\ValueObjects\Feature;
use App\Framework\MachineLearning\ValueObjects\FeatureType;

/**
 * Generic interface for extracting features from domain-specific data
 *
 * This interface is domain-agnostic and can be used for:
 * - WAF: Extract features from HTTP requests
 * - Query Optimization: Extract features from SQL queries
 * - Performance Monitoring: Extract features from performance metrics
 * - Security Events: Extract features from security logs
 */
interface FeatureExtractorInterface
{
    /**
     * Get the feature type this extractor handles
     */
    public function getFeatureType(): FeatureType;

    /**
     * Check if extractor can process the given data
     *
     * @param mixed $data Domain-specific data (RequestAnalysisData, QueryLog, PerformanceMetrics, etc.)
     */
    public function canExtract(mixed $data): bool;

    /**
     * Extract features from domain-specific data
     *
     * @param mixed $data Domain-specific data
     * @param array<string, mixed> $context Additional context for feature extraction
     * @return Feature[]
     */
    public function extractFeatures(mixed $data, array $context = []): array;

    /**
     * Get feature names this extractor produces
     *
     * @return string[]
     */
    public function getFeatureNames(): array;

    /**
     * Get extractor configuration
     *
     * @return array<string, mixed>
     */
    public function getConfiguration(): array;

    /**
     * Check if extractor is enabled
     */
    public function isEnabled(): bool;

    /**
     * Get processing priority (higher = runs earlier)
     *
     * Priority ranges:
     * - 1000+: Critical features (must run first)
     * - 500-999: High priority features
     * - 100-499: Normal priority features
     * - 1-99: Low priority features
     * - 0: Background features (run last)
     */
    public function getPriority(): int;

    /**
     * Get expected processing time in milliseconds
     *
     * Used for timeout management and performance monitoring
     */
    public function getExpectedProcessingTime(): int;

    /**
     * Check if extractor supports parallel execution
     *
     * Extractors that support parallel execution can run concurrently
     * with other parallel extractors for improved performance
     */
    public function supportsParallelExecution(): bool;

    /**
     * Get extractor dependencies (extractors that must run before this one)
     *
     * Return array of FeatureExtractorInterface class names that must
     * complete before this extractor can run
     *
     * @return string[] Array of fully qualified class names
     */
    public function getDependencies(): array;
}
