<?php

declare(strict_types=1);

namespace App\Framework\MachineLearning\ModelManagement\ValueObjects;

/**
 * Model Type - Classification of ML Model Learning Paradigm
 *
 * Defines the learning paradigm used by the ML model:
 * - SUPERVISED: Trained on labeled data (features + ground truth labels)
 * - UNSUPERVISED: No labeled data, finds patterns in data
 * - SEMI_SUPERVISED: Combination of labeled and unlabeled data
 * - REINFORCEMENT: Learns through trial-and-error with rewards
 */
enum ModelType: string
{
    /**
     * Supervised Learning
     *
     * Requires labeled training data (input features + expected output).
     * Examples:
     * - Classification (spam detection, anomaly detection with labels)
     * - Regression (price prediction, time series forecasting)
     *
     * Metrics: Accuracy, Precision, Recall, F1-Score
     */
    case SUPERVISED = 'supervised';

    /**
     * Unsupervised Learning
     *
     * No labeled data required, algorithm finds patterns/structure in data.
     * Examples:
     * - Clustering (customer segmentation)
     * - Anomaly detection (statistical methods, isolation forest)
     * - Dimensionality reduction (PCA)
     *
     * Current framework models:
     * - N+1 Detection (pattern similarity)
     * - WAF Behavioral Analysis (statistical outlier detection)
     * - Queue Job Anomaly Detection (feature-based anomaly scoring)
     *
     * Metrics: Silhouette score, Davies-Bouldin index, anomaly scores
     */
    case UNSUPERVISED = 'unsupervised';

    /**
     * Semi-Supervised Learning
     *
     * Uses small amount of labeled data + large amount of unlabeled data.
     * Examples:
     * - Text classification with limited labels
     * - Anomaly detection with some known anomalies
     *
     * Metrics: Mix of supervised and unsupervised metrics
     */
    case SEMI_SUPERVISED = 'semi_supervised';

    /**
     * Reinforcement Learning
     *
     * Agent learns through interaction with environment, receiving rewards/penalties.
     * Examples:
     * - Auto-tuning systems (threshold optimization)
     * - Adaptive rate limiting
     * - Resource allocation
     *
     * Metrics: Cumulative reward, convergence rate
     */
    case REINFORCEMENT = 'reinforcement';

    /**
     * Get human-readable description
     */
    public function getDescription(): string
    {
        return match ($this) {
            self::SUPERVISED => 'Supervised learning with labeled training data',
            self::UNSUPERVISED => 'Unsupervised learning finding patterns in unlabeled data',
            self::SEMI_SUPERVISED => 'Semi-supervised learning combining labeled and unlabeled data',
            self::REINFORCEMENT => 'Reinforcement learning through trial-and-error with rewards',
        };
    }

    /**
     * Check if model requires labeled training data
     */
    public function requiresLabels(): bool
    {
        return match ($this) {
            self::SUPERVISED => true,
            self::SEMI_SUPERVISED => true,  // Partially
            self::UNSUPERVISED => false,
            self::REINFORCEMENT => false,  // Uses rewards, not labels
        };
    }

    /**
     * Get typical evaluation metrics for this model type
     *
     * @return array<string>
     */
    public function getTypicalMetrics(): array
    {
        return match ($this) {
            self::SUPERVISED => [
                'accuracy',
                'precision',
                'recall',
                'f1_score',
                'false_positive_rate',
                'false_negative_rate',
                'confusion_matrix',
                'roc_auc',
            ],
            self::UNSUPERVISED => [
                'anomaly_score',
                'silhouette_score',
                'davies_bouldin_index',
                'detection_rate',
                'false_positive_rate',
            ],
            self::SEMI_SUPERVISED => [
                'accuracy',
                'precision',
                'recall',
                'f1_score',
                'unlabeled_data_quality',
            ],
            self::REINFORCEMENT => [
                'cumulative_reward',
                'average_reward',
                'convergence_rate',
                'exploration_rate',
            ],
        };
    }

    /**
     * Get color for UI representation
     */
    public function getColor(): string
    {
        return match ($this) {
            self::SUPERVISED => '#4CAF50',      // Green
            self::UNSUPERVISED => '#2196F3',    // Blue
            self::SEMI_SUPERVISED => '#FF9800', // Orange
            self::REINFORCEMENT => '#9C27B0',   // Purple
        };
    }
}
