"""Public API for model comparison 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 ModelComparisonResult


def compare_models(
    dataset: Dataset,
    specs: list[ModelSpec],
    model: BaseEncodingModel,
    cv: CrossValidator | None = None,
) -> ModelComparisonResult:
    """Compare multiple encoding model specifications.

    Parameters
    ----------
    dataset : Dataset
        Dataset providing neural data and precomputed stimulus features.
    specs : list[ModelSpec]
        Model specifications to evaluate and compare.
    model : BaseEncodingModel
        Encoding model used to fit each design matrix.
    cv : CrossValidator | None, optional
        Optional cross-validation strategy used during evaluation.

    Returns
    -------
    ModelComparisonResult
        Result object describing comparison scores and the best model.
    """

    raise NotImplementedError()
