"""Temporal segment interfaces for NeuroWeave."""

from __future__ import annotations

from typing import Any

import numpy as np


class TimelineSegments:
    """Represent labeled temporal intervals.

    Parameters
    ----------
    name : str
        Name of the segment set.
    start_times : np.ndarray
        Segment start times.
    end_times : np.ndarray
        Segment end times.
    labels : np.ndarray | None, optional
        Optional segment labels.
    metadata : dict[str, Any] | None, optional
        Additional segment metadata.
    """

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

    def duration(self) -> np.ndarray:
        """Return segment durations.

        Returns
        -------
        np.ndarray
            Duration of each segment.
        """

        raise NotImplementedError()

    def summary(self) -> str:
        """Summarize the segment collection.

        Returns
        -------
        str
            Human-readable overview of the segment collection.
        """

        raise NotImplementedError()
