"""Public API for feature ablation in NeuroWeave."""

from __future__ import annotations

from neuroweave.core.cross_validator import CrossValidator
from neuroweave.data.dataset import Dataset
from neuroweave.model_spec.model_spec import ModelSpec
from neuroweave.models import BaseEncodingModel

from .results import AblationResult


def feature_ablation(
    dataset: Dataset,
    spec: ModelSpec,
    model: BaseEncodingModel,
    cv: CrossValidator | None = None,
) -> AblationResult:
    """Measure predictor importance through feature ablation.

    Parameters
    ----------
    dataset : Dataset
        Dataset providing neural data and precomputed stimulus features.
    spec : ModelSpec
        Full model specification used as the ablation baseline.
    model : BaseEncodingModel
        Encoding model used to fit each reduced specification.
    cv : CrossValidator | None, optional
        Optional cross-validation strategy used during evaluation.

    Returns
    -------
    AblationResult
        Result object describing feature-wise ablation scores.
    """

    raise NotImplementedError()
