"""ASR protocols defining contracts for ASR components."""

from __future__ import annotations

from collections.abc import Iterator
from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    import numpy as np
    from numpy.typing import NDArray

    from noteflow.infrastructure.asr.dto import AsrResult


class AsrEngine(Protocol):
    """Protocol for ASR transcription engine.

    Implementations should handle model loading, caching, and inference.
    """

    def load_model(self, model_size: str = "base") -> None:
        """Load the ASR model.

        Downloads the model if not cached.

        Args:
            model_size: Model size ("tiny", "base", "small", "medium", "large").

        Raises:
            ValueError: If model_size is invalid.
            RuntimeError: If model loading fails.
        """
        ...

    def transcribe(
        self,
        audio: NDArray[np.float32],
        language: str | None = None,
    ) -> Iterator[AsrResult]:
        """Transcribe audio and yield results.

        Args:
            audio: Audio samples as float32 array (16kHz mono, normalized).
            language: Optional language code (e.g., "en"). Auto-detected if None.

        Yields:
            AsrResult segments.

        Raises:
            RuntimeError: If model not loaded.
        """
        ...

    @property
    def is_loaded(self) -> bool:
        """Return True if model is loaded."""
        ...

    @property
    def model_size(self) -> str | None:
        """Return the loaded model size, or None if not loaded."""
        ...

    def unload(self) -> None:
        """Unload the model to free memory."""
        ...
