from abc import ABC, abstractmethod
import numpy as np
from typing import Dict, Any, Optional


class UtilityEvaluator(ABC):
    """
    效用评估基类。
    所有具体效用评估（如分类准确率、查询精度等）必须继承此类并实现 evaluate 方法。
    """

    @abstractmethod
    def evaluate(self, original: np.ndarray, perturbed: np.ndarray,
                 task: Optional[Dict[str, Any]] = None) -> float:
        """
        评估扰动后数据的效用。

        Parameters
        ----------
        original : np.ndarray
            原始数据（可用于监督学习任务）。
        perturbed : np.ndarray
            扰动后的数据。
        task : Dict[str, Any], optional
            任务描述，例如 {'type': 'classification', 'labels': y}。

        Returns
        -------
        float
            效用值，越大越好。
        """
        pass