"""Cross-validation helpers for NeuroWeave encoding models."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from .base_model import BaseEncodingModel
    from .result import EncodingResult


class CrossValidator:
    """Cross-validation helper for encoding models.

    This class defines a stable interface for blocked, run-wise, and
    nested cross-validation strategies without exposing implementation
    details from lower layers.

    Parameters
    ----------
    strategy : str, optional
        Cross-validation strategy name.
    n_splits : int, optional
        Number of folds or splits.
    **params : Any
        Additional cross-validation configuration parameters.
    """

    def __init__(
        self,
        strategy: str = "blocked",
        n_splits: int = 5,
        **params: Any,
    ) -> None:
        self.strategy = strategy
        self.n_splits = n_splits
        self.params = dict(params)

    def split(self, X: Any, y: Any) -> Any:
        """Generate cross-validation splits.

        Parameters
        ----------
        X : Any
            Design matrix or feature representation.
        y : Any
            Neural response targets.

        Returns
        -------
        Any
            Cross-validation split iterator or split specification.
        """

        raise NotImplementedError()

    def evaluate(
        self,
        model: BaseEncodingModel,
        X: Any,
        y: Any,
    ) -> EncodingResult:
        """Evaluate a model with cross-validation.

        Parameters
        ----------
        model : neuroweave.core.base_model.BaseEncodingModel
            Encoding model to evaluate.
        X : Any
            Design matrix or feature representation.
        y : Any
            Neural response targets.

        Returns
        -------
        neuroweave.results.EncodingResult
            Result object containing cross-validation outputs.
        """

        raise NotImplementedError()
