"""Core encoding-result interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import pandas as pd

from neuroweave.core.axis_array import AxisArray


class EncodingResult:
    """Container storing outputs of encoding-model fitting.

    Parameters
    ----------
    kernel : AxisArray
        Kernel array, typically shaped like ``channel x feature x lag``.
    predictions : AxisArray | None, optional
        Predicted responses, typically shaped like ``time x channel``.
    score : float | None, optional
        Scalar model score.
    metadata : dict[str, Any] | None, optional
        Additional result metadata.
    """

    def __init__(
        self,
        kernel: AxisArray,
        predictions: AxisArray | None = None,
        score: float | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.kernel = kernel
        self.predictions = predictions
        self.score = score
        self.metadata = metadata if metadata is not None else {}

    def summary(self) -> str:
        """Summarize encoding-model outputs.

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

        raise NotImplementedError()

    def get_kernel(self) -> AxisArray:
        """Return the kernel array.

        Returns
        -------
        AxisArray
            Kernel stored in the encoding result.
        """

        raise NotImplementedError()

    def to_dataframe(self) -> pd.DataFrame:
        """Convert the kernel representation to a tabular format.

        Returns
        -------
        pandas.DataFrame
            Tabular representation of the encoding kernel.
        """

        raise NotImplementedError()

    def plot_kernel(self) -> object:
        """Placeholder method for kernel plotting.

        Returns
        -------
        object
            Backend-specific plotting object.
        """

        raise NotImplementedError()
