"""Base abstractions for NeuroWeave estimators."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class BaseEstimator(ABC):
    """Base class for all parameter estimators.

    Estimators define the optimization strategy used to estimate model
    parameters while keeping numerical backend choices encapsulated.

    Parameters
    ----------
    **params : Any
        Estimator configuration parameters stored by the base class.
    """

    def __init__(self, **params: Any) -> None:
        self._params = dict(params)

    @abstractmethod
    def fit(self, X: Any, y: Any) -> Any:
        """Estimate model parameters.

        Parameters
        ----------
        X : Any
            Design matrix or feature representation.
        y : Any
            Neural response targets.

        Returns
        -------
        Any
            Estimated parameter object or coefficient representation.
        """

        raise NotImplementedError()

    def get_params(self) -> dict[str, Any]:
        """Return estimator parameters.

        Returns
        -------
        dict[str, Any]
            Mapping of parameter names to values.
        """

        raise NotImplementedError()

    def set_params(self, **params: Any) -> BaseEstimator:
        """Set estimator parameters.

        Parameters
        ----------
        **params : Any
            Parameter names and values to update.

        Returns
        -------
        BaseEstimator
            The estimator instance.
        """

        raise NotImplementedError()
