<?php

declare(strict_types=1);

namespace App\Framework\MachineLearning\Core;

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

/**
 * Generic interface for anomaly detection algorithms
 *
 * This interface is domain-agnostic and can be used for:
 * - WAF: Detect malicious request patterns
 * - Query Optimization: Detect N+1 query patterns and performance issues
 * - Performance Monitoring: Detect performance degradation and bottlenecks
 * - Security Events: Detect attack patterns and suspicious activities
 */
interface AnomalyDetectorInterface
{
    /**
     * Get detector name
     */
    public function getName(): string;

    /**
     * Get supported feature types
     *
     * @return FeatureType[]
     */
    public function getSupportedFeatureTypes(): array;

    /**
     * Check if detector can analyze the given features
     *
     * @param Feature[] $features
     */
    public function canAnalyze(array $features): bool;

    /**
     * Detect anomalies in features
     *
     * @param Feature[] $features Features to analyze
     * @param Baseline|null $baseline Optional baseline for comparison
     * @return AnomalyDetection[] Detected anomalies
     */
    public function detectAnomalies(array $features, ?Baseline $baseline = null): array;

    /**
     * Update detector model with new data
     *
     * This method allows the detector to learn from new data and adapt
     * its detection algorithms over time (online learning)
     *
     * @param Feature[] $features
     */
    public function updateModel(array $features): void;

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

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

    /**
     * Get detector confidence threshold
     *
     * Detections below this threshold will be filtered out
     * Range: 0.0 to 1.0 (0% to 100% confidence)
     */
    public function getConfidenceThreshold(): float;

    /**
     * Set detector confidence threshold
     *
     * @param float $threshold Confidence threshold (0.0 to 1.0)
     */
    public function setConfidenceThreshold(float $threshold): void;

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

    /**
     * Check if detector supports real-time analysis
     *
     * Real-time detectors can analyze data as it arrives without
     * requiring batch processing
     */
    public function supportsRealTime(): bool;
}
