"""TTS extension port contracts."""

from __future__ import annotations

from dataclasses import dataclass
from typing import AsyncIterator, Optional, Protocol

from providers.common.base import TTSChunk


@dataclass(frozen=True)
class TTSServiceSpec:
    """Resolved runtime configuration for TTS service creation."""

    provider: str
    voice: str
    sample_rate: int
    speed: float = 1.0
    api_key: Optional[str] = None
    api_url: Optional[str] = None
    model: Optional[str] = None
    mode: str = "commit"


class TTSPort(Protocol):
    """Port for speech synthesis providers."""

    async def connect(self) -> None:
        """Establish connection to TTS provider."""

    async def disconnect(self) -> None:
        """Release TTS resources."""

    async def synthesize(self, text: str) -> bytes:
        """Synthesize complete PCM payload for text."""

    async def synthesize_stream(self, text: str) -> AsyncIterator[TTSChunk]:
        """Stream synthesized PCM chunks for text."""

    async def cancel(self) -> None:
        """Cancel an in-flight synthesis request."""