"""Public API for variance partitioning 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 VariancePartitionResult


def variance_partition(
    dataset: Dataset,
    spec: ModelSpec,
    model: BaseEncodingModel,
    cv: CrossValidator | None = None,
    lagwise: bool = False,
) -> VariancePartitionResult:
    """Compute unique and shared variance explained by feature groups.

    Parameters
    ----------
    dataset : Dataset
        Dataset providing neural data and precomputed stimulus features.
    spec : ModelSpec
        Full model specification defining predictors and feature groups.
    model : BaseEncodingModel
        Encoding model used to fit each design matrix.
    cv : CrossValidator | None, optional
        Optional cross-validation strategy used during evaluation.
    lagwise : bool, optional
        Whether to request lag-wise variance contributions.

    Returns
    -------
    VariancePartitionResult
        Result object describing full, unique, and shared variance.
    """

    raise NotImplementedError()
