"""Type aliases for the public API.

Uses Python 3.12 ``type`` statement. These will be replaced with
precise union types as the model modules are built out.
"""

from pathlib import Path

import numpy as np
import numpy.typing as npt

from radiens_core.models.dataset import DatasetMetadata
from radiens_core.models.signals import KeyIndex

# These are defined inline to avoid forward-reference import issues.
# They will be progressively tightened as model modules land.
type DatasetRef = str | Path | DatasetMetadata
"""Reference to a dataset: file path string or Path (DatasetMetadata added later)."""

type TimeRangeInput = list[float] | npt.NDArray[np.float64] | float | None
"""Any accepted time range format (TimeRangeSpec, TimeRange added later)."""

type ChannelIndices = list[int] | npt.NDArray[np.int64] | None
"""Channel index specification."""

type KeyIdxArrays = dict[KeyIndex, npt.NDArray[np.int64]]
"""Mapping from KeyIndex to channel index arrays."""
