"""Axis-aware array interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class AxisArray:
    """Wrap a NumPy array together with named axes and coordinates.

    Parameters
    ----------
    data : np.ndarray
        Underlying array data.
    axes : list[str]
        Ordered names of array dimensions.
    coords : dict[str, np.ndarray] | None, optional
        Coordinate labels keyed by axis name.
    """

    def __init__(
        self,
        data: np.ndarray,
        axes: list[str],
        coords: dict[str, np.ndarray] | None = None,
    ) -> None:
        self.data = data
        self.axes = axes
        self.coords = coords if coords is not None else {}
        self.shape = data.shape

    def axis_index(self, name: str) -> int:
        """Return the integer index of a named axis.

        Parameters
        ----------
        name : str
            Axis name.

        Returns
        -------
        int
            Integer position of the named axis.
        """

        raise NotImplementedError()

    def select(self, **kwargs: Any) -> AxisArray:
        """Select elements along named axes.

        Parameters
        ----------
        **kwargs : Any
            Axis selections keyed by axis name.

        Returns
        -------
        AxisArray
            Selected axis-aware array view.
        """

        raise NotImplementedError()

    def mean(self, axis: str) -> AxisArray:
        """Compute the mean along a named axis.

        Parameters
        ----------
        axis : str
            Axis name to reduce.

        Returns
        -------
        AxisArray
            Reduced axis-aware array.
        """

        raise NotImplementedError()

    def transpose(self, *axes: str) -> AxisArray:
        """Reorder named axes.

        Parameters
        ----------
        *axes : str
            Desired axis order.

        Returns
        -------
        AxisArray
            Transposed axis-aware array.
        """

        raise NotImplementedError()

    def rename_axis(self, old: str, new: str) -> AxisArray:
        """Rename an axis.

        Parameters
        ----------
        old : str
            Existing axis name.
        new : str
            Replacement axis name.

        Returns
        -------
        AxisArray
            Axis-aware array with renamed axis metadata.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the axis-aware array structure.

        Returns
        -------
        str
            Human-readable summary of array axes and coordinates.
        """

        raise NotImplementedError()
