"""Continuous timeline signal interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class TimelineSignal:
    """Represent continuous stimulus features over time.

    Parameters
    ----------
    name : str
        Name of the signal.
    data : np.ndarray
        Continuous signal values.
    sampling_rate : float
        Sampling rate of the signal.
    metadata : dict[str, Any] | None, optional
        Additional signal metadata.
    """

    def __init__(
        self,
        name: str,
        data: np.ndarray,
        sampling_rate: float,
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.name = name
        self.data = data
        self.sampling_rate = sampling_rate
        self.time_axis: np.ndarray | None = None
        self.metadata = metadata if metadata is not None else {}

    def resample(self, sampling_rate: float) -> TimelineSignal:
        """Resample the signal to a new sampling rate.

        Parameters
        ----------
        sampling_rate : float
            Target sampling rate.

        Returns
        -------
        TimelineSignal
            Resampled signal object.
        """

        raise NotImplementedError()

    def duration(self) -> float:
        """Return the signal duration.

        Returns
        -------
        float
            Signal duration in seconds.
        """

        raise NotImplementedError()
