"""Core design-matrix interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class DesignMatrix:
    """Representation of a lag-expanded encoding-model design matrix.

    Parameters
    ----------
    X : np.ndarray
        Design matrix, typically with shape ``(time, predictor)``.
    feature_names : list[str]
        Names of predictor columns.
    lags : np.ndarray | None, optional
        Lag coordinates associated with the design matrix.
    metadata : dict[str, Any] | None, optional
        Additional design-matrix metadata.
    """

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

    def n_samples(self) -> int:
        """Return the number of time points.

        Returns
        -------
        int
            Number of samples in the design matrix.
        """

        raise NotImplementedError()

    def n_predictors(self) -> int:
        """Return the number of predictors.

        Returns
        -------
        int
            Number of predictor columns in the design matrix.
        """

        raise NotImplementedError()

    def get_feature_index(self, name: str) -> int:
        """Return the column index of a feature.

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

        Returns
        -------
        int
            Index of the corresponding predictor column.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the design matrix.

        Returns
        -------
        str
            Human-readable design-matrix overview.
        """

        raise NotImplementedError()
