"""任务抽象基类

定义 Task 接口，所有具体任务必须实现此接口。
"""

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


class BaseTask(ABC):
    """任务抽象基类

    所有训练任务（回归、排序学习、分类等）必须继承此类。
    提供统一的接口：Label处理、模型训练、预测、评估。

    Attributes:
        label_name: Label 列名
        model_params: 模型参数字典
    """

    def __init__(self, model_params: Dict[str, Any], label_name: str):
        """初始化任务

        Args:
            model_params: 模型参数字典
            label_name: Label 列名
        """
        self.model_params = model_params
        self.label_name = label_name
        self.model = None

    @abstractmethod
    def prepare_labels(self, data: Dict[str, Dict]) -> Dict[str, Dict]:
        """准备标签

        子类可实现特定的 Label 转换逻辑（如排序学习的分位数转换）。

        Args:
            data: 数据字典

        Returns:
            处理后的数据字典
        """
        raise NotImplementedError

    @abstractmethod
    def fit(self, train_data: Dict, val_data: Dict) -> None:
        """训练模型

        Args:
            train_data: 训练数据字典 {"X": DataFrame, "y": Series, ...}
            val_data: 验证数据字典
        """
        raise NotImplementedError

    @abstractmethod
    def predict(self, test_data: Dict) -> np.ndarray:
        """生成预测

        Args:
            test_data: 测试数据字典

        Returns:
            预测结果数组
        """
        raise NotImplementedError

    def get_model(self):
        """获取底层模型

        Returns:
            训练后的模型实例
        """
        return self.model

    def plot_training_metrics(self) -> None:
        """绘制训练指标曲线（可选）"""
        pass
