# License: Apache-2.0 License
# Created by: Patrick Lumbantobing, VertoX-AI
# Copyright (c) 2026 VertoX-AI. All rights reserved.
#
# This work is licensed under the Apache-2.0 License.
# To view a copy of this license, visit
# https://www.apache.org/licenses/LICENSE-2.0

"""Define structural backend contracts consumed by application services."""

from __future__ import annotations

from collections.abc import Sequence
from typing import Protocol, runtime_checkable

from speech_text_data_aligners.core.models import (
    AlignmentOutcome,
    AlignmentRequest,
    AlignmentResult,
)


@runtime_checkable
class AlignmentBackend(Protocol):
    """Expose interchangeable single and ordered batch forced alignment."""

    @property
    def name(self) -> str:
        """Return the backend's stable registry/report name."""
        ...

    def align(self, request: AlignmentRequest) -> AlignmentResult:
        """Align one authoritative transcript against its WAV.

        Parameters
        ----------
            request: Fully populated backend-neutral alignment request.

        Returns
        -------
            A complete backend-neutral alignment result.

        Raises
        ------
            SpeechTextAlignerError: If configuration, execution, parsing, mapping, or
                validation fails. Concrete backends document the precise subclasses.

        """
        ...

    def align_batch(
        self,
        requests: Sequence[AlignmentRequest],
    ) -> tuple[AlignmentOutcome, ...]:
        """Align requests in order and return exactly one outcome per request.

        Parameters
        ----------
            requests: Ordered, fully populated requests.

        Returns
        -------
            Ordered outcomes matching request count and identities.

        Raises
        ------
            SpeechTextAlignerError: For whole-provider or configuration failures that
                cannot be represented as independent per-request outcomes.

        """
        ...