"""High-level orchestration API for encoding analyses."""

from __future__ import annotations

from typing import TYPE_CHECKING

from neuroweave.core.result import EncodingResult
from neuroweave.model_selection.results import (
    AblationResult,
    ModelComparisonResult,
    VariancePartitionResult,
)
from neuroweave.model_spec.model_spec import ModelSpec
from neuroweave.stats.results import (
    ClusterTestResult,
    KernelStatsResult,
)

from .analysis_config import AnalysisConfig
from .analysis_result import CVResult

if TYPE_CHECKING:
    from .steps.base_step import AnalysisStep


class EncodingAnalysis:
    """Orchestrator for full encoding-analysis workflows.

    Parameters
    ----------
    config : AnalysisConfig
        Analysis configuration describing dataset, model, and specification.
    """

    def __init__(self, config: AnalysisConfig) -> None:
        self.config = config

    def fit(self) -> EncodingResult:
        """Run the configured encoding-model fit.

        Returns
        -------
        EncodingResult
            Result of fitting the configured encoding model.
        """

        raise NotImplementedError()

    def cross_validate(self) -> CVResult:
        """Run cross-validated model fitting.

        Returns
        -------
        CVResult
            Cross-validation result for the configured analysis.
        """

        raise NotImplementedError()

    def compare(self, specs: list[ModelSpec]) -> ModelComparisonResult:
        """Compare multiple model specifications.

        Parameters
        ----------
        specs : list[ModelSpec]
            Alternative model specifications to compare.

        Returns
        -------
        ModelComparisonResult
            Result of comparing the provided model specifications.
        """

        raise NotImplementedError()

    def variance_partition(self) -> VariancePartitionResult:
        """Compute feature-group variance partitioning.

        Returns
        -------
        VariancePartitionResult
            Variance partitioning result for the configured analysis.
        """

        raise NotImplementedError()

    def ablation(self) -> AblationResult:
        """Run feature ablation on the configured specification.

        Returns
        -------
        AblationResult
            Result of feature-ablation analysis.
        """

        raise NotImplementedError()

    def kernel_statistics(self) -> KernelStatsResult:
        """Compute kernel-level statistics for the analysis.

        Returns
        -------
        KernelStatsResult
            Kernel statistics associated with the analysis.
        """

        raise NotImplementedError()

    def cluster_test(self) -> ClusterTestResult:
        """Run cluster-based inference for the analysis.

        Returns
        -------
        ClusterTestResult
            Cluster-based statistical result.
        """

        raise NotImplementedError()

    def run(self, steps: list[AnalysisStep]) -> list[object]:
        """Execute analysis steps sequentially.

        Parameters
        ----------
        steps : list[AnalysisStep]
            Ordered analysis steps to execute.

        Returns
        -------
        list[object]
            Step outputs in execution order.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the current analysis workflow.

        Returns
        -------
        str
            Human-readable analysis overview.
        """

        raise NotImplementedError()
