"""Core dataset interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class Dataset:
    """Central container storing neural data and stimulus features.

    Parameters
    ----------
    neural : np.ndarray
        Neural recording matrix, typically with shape ``(time, channel)``.
    features : dict[str, np.ndarray]
        Stimulus features indexed by feature name.
    metadata : dict[str, Any] | None, optional
        Additional dataset metadata.
    """

    def __init__(
        self,
        neural: np.ndarray,
        features: dict[str, np.ndarray],
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.neural = neural
        self.features = features
        self.metadata = metadata if metadata is not None else {}

    def get_feature(self, name: str) -> np.ndarray:
        """Return a feature vector by name.

        Parameters
        ----------
        name : str
            Feature name.

        Returns
        -------
        np.ndarray
            Requested feature array.
        """

        raise NotImplementedError()

    def list_features(self) -> list[str]:
        """Return available feature names.

        Returns
        -------
        list[str]
            Names of available stimulus features.
        """

        raise NotImplementedError()

    def get_neural(self, channel: int | str) -> np.ndarray:
        """Return neural data for a channel.

        Parameters
        ----------
        channel : int | str
            Channel index or channel label.

        Returns
        -------
        np.ndarray
            Neural time series for the requested channel.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the dataset contents.

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

        raise NotImplementedError()
