"""Greeks calculator interface.

希腊值与隐含波动率计算器抽象接口（Track B）。
"""

from abc import ABC, abstractmethod
from typing import Literal

import pandas as pd

OptionType = Literal["call", "put"]
GreeksModel = Literal["black76", "bs"]


class GreeksCalculator(ABC):
    """Greeks calculator interface.

    希腊值与隐含波动率计算器抽象接口（Track B）。

    Default pricing model is Black-76 (``model='black76'``), used for options
    on futures/forwards. BS (``model='bs'``) is available for spot options.
    """

    @abstractmethod
    def calculate_greeks(
        self,
        S: float,
        K: float,
        T: float,
        r: float,
        sigma: float,
        option_type: OptionType,
        model: GreeksModel = "black76",
    ) -> pd.DataFrame:
        """Calculate Greeks and theoretical price for a single option.

        计算单个期权的希腊值与理论价格。

        Args:
            S: Underlying price (spot for BS, futures/forward for Black-76).
            K: Strike price / 行权价.
            T: Time to expiry in years / 距到期年化时间.
            r: Risk-free rate (annualized) / 无风险利率.
            sigma: Volatility (annualized, e.g., 0.2 = 20%) / 波动率.
            option_type: 'call' or 'put'.
            model: Pricing model, default 'black76'.

        Returns:
            pd.DataFrame (single row):
            - delta, gamma, theta, vega, rho
            - iv: implied volatility (equals ``sigma``)
            - theoretical_value: theoretical option price

        Raises:
            ValueError: If parameters are invalid (e.g., non-positive S/K/T/sigma).
        """
        pass

    @abstractmethod
    def calculate_iv(
        self,
        S: float,
        K: float,
        T: float,
        r: float,
        option_price: float,
        option_type: OptionType,
        model: GreeksModel = "black76",
    ) -> float:
        """Solve implied volatility from option market price.

        根据期权市场价格反解隐含波动率。

        Args:
            S: Underlying price.
            K: Strike price / 行权价.
            T: Time to expiry in years / 距到期年化时间.
            r: Risk-free rate (annualized) / 无风险利率.
            option_price: Option market price / 期权市场价格.
            option_type: 'call' or 'put'.
            model: Pricing model, default 'black76'.

        Returns:
            float: Implied volatility (annualized).

        Raises:
            ValueError: If no solution exists or parameters are invalid.
        """
        pass
