class FIMethod(StrEnum):
    """Feature importance computation methods."""

    INTERNAL = "internal"
    PERMUTATION = "permutation"
    SHAP = "shap"
    LOFO = "lofo"
    CONSTANT = "constant"
    COUNTS = "counts"
    COUNTS_RELATIVE = "counts_relative"

class FIResultLabel(StrEnum):
    """Standardized labels for the ``fi_method`` column in feature importance DataFrames.

    These values are written to the ``fi_method`` column of
    ``feature_importances.parquet`` files when modules save results to disk.
    They serve as a serialization/output concern — identifying *how* a stored
    importance value was produced.

    This is a superset of :class:`FIComputeMethod` plus EFS-specific labels
    (``COUNTS``, ``COUNTS_RELATIVE``) that only appear in EFS result output.
    """

    INTERNAL = "internal"
    PERMUTATION = "permutation"
    SHAP = "shap"
    LOFO = "lofo"
    CONSTANT = "constant"
    COUNTS = "counts"
    COUNTS_RELATIVE = "counts_relative"


class FIComputeMethod(StrEnum):
    """Feature importance computation methods.

    Specifies *which* algorithm to use when calculating feature importances.
    Used in three contexts:

    - **Model registration** — ``ModelConfig.feature_method``: declares which
      FI method a model natively supports for constrained HPO.
    - **Module configuration** — ``Octo.fi_methods_bestbag``,
      ``Rfe2.fi_method_rfe``, ``Mrmr.feature_importance_method``: user-facing
      parameters that control which FI computations to run.
    - **Bag orchestration** — ``Bag.calculate_feature_importances()``,
      ``Bag.get_selected_features()``: internal dispatch to the appropriate
      FI calculation on training objects.

    Each usage site restricts the accepted subset via attrs validators, e.g.
    ``Rfe2.fi_method_rfe`` only accepts ``PERMUTATION`` and ``SHAP``.
    """

    INTERNAL = "internal"
    PERMUTATION = "permutation"
    SHAP = "shap"
    LOFO = "lofo"
    CONSTANT = "constant"


class FIType(StrEnum):
    """Feature importance analysis types for the public prediction API.

    Used as the ``fi_type`` parameter in :meth:`TaskPredictor.calculate_fi`
    and :meth:`TaskPredictorTest.calculate_fi` to select the kind of
    post-hoc feature importance analysis to perform on new or held-out data.

    Unlike :class:`FIComputeMethod` (which operates within the training
    pipeline on inner-CV folds), these run *after* a study is complete,
    using the saved outer-split models.
    """

    PERMUTATION = "permutation"
    GROUP_PERMUTATION = "group_permutation"
    SHAP = "shap"


class ShapExplainerType(StrEnum):
    """SHAP explainer implementations.

    Selects which ``shap`` library explainer to use when computing
    SHAP-based feature importances. Used as the ``shap_type`` parameter
    in both the training pipeline (``Training.calculate_fi_shap``) and
    the prediction API (``TaskPredictor.calculate_fi(fi_type='shap', shap_type=...)``).

    - ``KERNEL`` — Model-agnostic :class:`shap.KernelExplainer`. Works with
      any model but is the slowest.
    - ``PERMUTATION`` — Model-agnostic :class:`shap.PermutationExplainer`.
      Faster than kernel for many models.
    - ``EXACT`` — :class:`shap.ExactExplainer`. Computes exact SHAP values;
      slowest but most accurate.

    Note: ``PERMUTATION`` here refers to the SHAP permutation explainer
    algorithm, not to permutation feature importance (:class:`FIComputeMethod`).
    """

    KERNEL = "kernel"
    PERMUTATION = "permutation"
    EXACT = "exact"


class FIDataset(StrEnum):
    """Dataset partitions for feature importance computation."""

    TRAIN = "train"
    DEV = "dev"
    TEST = "test"