"""Feature-space interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any


class FeatureSpace:
    """Represent a logical group of related predictors.

    Parameters
    ----------
    name : str
        Name of the feature space.
    features : list[str]
        Names of dataset features belonging to the space.
    metadata : dict[str, Any] | None, optional
        Additional metadata describing the feature space.
    """

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

    def list_features(self) -> list[str]:
        """Return features belonging to this feature space.

        Returns
        -------
        list[str]
            Feature names in the space.
        """

        raise NotImplementedError()

    def size(self) -> int:
        """Return the number of features in the space.

        Returns
        -------
        int
            Number of features referenced by the space.
        """

        raise NotImplementedError()

    def contains(self, feature: str) -> bool:
        """Check whether a feature belongs to the space.

        Parameters
        ----------
        feature : str
            Feature name to test.

        Returns
        -------
        bool
            Whether the feature belongs to the space.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the feature space.

        Returns
        -------
        str
            Human-readable overview of the feature space.
        """

        raise NotImplementedError()


class FeatureSpaceCollection:
    """Container managing multiple feature spaces.

    Parameters
    ----------
    spaces : list[FeatureSpace]
        Feature spaces included in the collection.
    """

    def __init__(self, spaces: list[FeatureSpace]) -> None:
        self.spaces = spaces

    def get_space(self, name: str) -> FeatureSpace:
        """Return a feature space by name.

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

        Returns
        -------
        FeatureSpace
            Requested feature space.
        """

        raise NotImplementedError()

    def list_spaces(self) -> list[str]:
        """Return names of known feature spaces.

        Returns
        -------
        list[str]
            Names of spaces in the collection.
        """

        raise NotImplementedError()

    def get_features(self, space_name: str) -> list[str]:
        """Return features belonging to a named feature space.

        Parameters
        ----------
        space_name : str
            Feature-space name.

        Returns
        -------
        list[str]
            Feature names in the requested space.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the feature-space collection.

        Returns
        -------
        str
            Human-readable overview of the collection.
        """

        raise NotImplementedError()
