"""Volatility analytics calculator interface.

波动率分析计算器抽象接口（Track B），包含 HV、波动率锥、HV-IV Spread。
"""

from abc import ABC, abstractmethod
from typing import Literal

import pandas as pd

HVMethod = Literal["close_to_close", "parkinson", "garman_klass", "yang_zhang"]


class VolatilityCalculator(ABC):
    """Volatility analytics calculator interface.

    波动率分析计算器抽象接口（Track B）。

    Expected ``ohlc_df`` schema: [timestamp, open, high, low, close]
    """

    @abstractmethod
    def get_hv(
        self,
        ohlc_df: pd.DataFrame,
        method: HVMethod,
        window: int,
        annualization: int = 252,
    ) -> pd.DataFrame:
        """Calculate historical volatility.

        计算历史波动率，支持 C2C/Parkinson/Garman-Klass/Yang-Zhang。

        Args:
            ohlc_df: OHLC DataFrame.
            method: HV estimation method.
            window: Rolling window length.
            annualization: Annualization factor (trading days per year), default 252.

        Returns:
            pd.DataFrame: [timestamp, hv]

        Raises:
            ValueError: If required columns are missing.
        """
        pass

    @abstractmethod
    def get_volatility_cone(
        self,
        ohlc_df: pd.DataFrame,
        windows: list[int],
        percentiles: list[float],
        method: HVMethod = "close_to_close",
        annualization: int = 252,
    ) -> pd.DataFrame:
        """Calculate volatility cone.

        计算波动率锥，输出不同窗口下 HV 的分位数分布。

        Args:
            ohlc_df: OHLC DataFrame.
            windows: Window lengths list.
            percentiles: Percentiles (0-1) list.
            method: HV estimation method, default 'close_to_close'.
            annualization: Annualization factor, default 252.

        Returns:
            pd.DataFrame: [window, percentile, hv]

        Raises:
            ValueError: If inputs are invalid.
        """
        pass

    @abstractmethod
    def get_hv_iv_spread(self, hv_df: pd.DataFrame, iv_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate HV-IV spread.

        计算 HV-IV Spread，衡量隐含溢价/折价。

        Args:
            hv_df: HV DataFrame with [timestamp, hv].
            iv_df: IV DataFrame with [timestamp, iv].

        Returns:
            pd.DataFrame: [timestamp, hv, iv, hv_iv_spread]

        Raises:
            ValueError: If inputs cannot be aligned.
        """
        pass
