"""Discrete timeline event interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class TimelineEvents:
    """Represent a discrete event stream.

    Parameters
    ----------
    name : str
        Name of the event stream.
    times : np.ndarray
        Event timestamps.
    values : np.ndarray | None, optional
        Optional event labels or values.
    metadata : dict[str, Any] | None, optional
        Additional event-stream metadata.
    """

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

    def count(self) -> int:
        """Return the number of events.

        Returns
        -------
        int
            Number of events in the stream.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the event stream.

        Returns
        -------
        str
            Human-readable overview of the event stream.
        """

        raise NotImplementedError()
