"""Stable fitting helpers for NeuroWeave validation workflows."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

from neuroweave.models import BaseEncodingModel

if TYPE_CHECKING:
    from neuroweave.results import EncodingResult
else:
    EncodingResult = Any


def fit_encoding_model(model: BaseEncodingModel, X: Any, y: Any) -> EncodingResult:
    """Fit an encoding model.

    Parameters
    ----------
    model : neuroweave.models.BaseEncodingModel
        User-facing encoding model instance.
    X : Any
        Feature matrix or design input.
    y : Any
        Neural response targets.

    Returns
    -------
    EncodingResult
        Result object for the fitted encoding model.
    """

    raise NotImplementedError()


def cross_validate_model(
    model: BaseEncodingModel,
    X: Any,
    y: Any,
    cv: int | Any = 5,
) -> EncodingResult:
    """Cross-validate an encoding model.

    Parameters
    ----------
    model : neuroweave.models.BaseEncodingModel
        User-facing encoding model instance.
    X : Any
        Feature matrix or design input.
    y : Any
        Neural response targets.
    cv : int | Any, optional
        Cross-validation specification.

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

    raise NotImplementedError()


def nested_cv(
    model: BaseEncodingModel,
    X: Any,
    y: Any,
    outer_cv: int | Any = 5,
    inner_cv: int | Any = 3,
) -> EncodingResult:
    """Run nested cross-validation for an encoding model.

    Parameters
    ----------
    model : neuroweave.models.BaseEncodingModel
        User-facing encoding model instance.
    X : Any
        Feature matrix or design input.
    y : Any
        Neural response targets.
    outer_cv : int | Any, optional
        Outer cross-validation specification.
    inner_cv : int | Any, optional
        Inner cross-validation specification.

    Returns
    -------
    EncodingResult
        Result object containing nested cross-validation outputs.
    """

    raise NotImplementedError()


__all__ = ["fit_encoding_model", "cross_validate_model", "nested_cv"]
