openspeechapi 0.1.0__py3-none-any.whl

openspeech/providers/stt/azure_speech.py

@@ -0,0 +1,99 @@
+"""Azure Speech STT provider adapter (batch, httpx)."""
+from __future__ import annotations
+
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class AzureSpeechSTTSettings(BaseSettings):
+    subscription_key: str = ""
+    region: str = "eastus"
+    language: str = "en-US"
+
+class AzureSpeechSTT(STTProvider):
+    name = "azure-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.REMOTE
+    settings_cls = AzureSpeechSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"language": ["en-US", "zh-CN", "ja-JP", "ko-KR", "es-ES", "fr-FR", "de-DE", "pt-BR", "it-IT", "ru-RU", "ar-SA", "hi-IN"], "region": ["eastus", "westus2", "westeurope", "eastasia", "southeastasia"]}
+
+    def __init__(self, settings: AzureSpeechSTTSettings | None = None) -> None:
+        self.settings = settings or AzureSpeechSTTSettings()
+        self._client: httpx.AsyncClient | None = None
+        self._owns_client: bool = True
+
+    def set_http_client(self, client) -> None:
+        self._client = client
+        self._owns_client = False
+
+    async def start(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client and self._owns_client:
+            await self._client.aclose()
+        self._client = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return bool(self.settings.subscription_key)
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, audio={} bytes", self.name, len(audio.data))
+        _t0 = time.perf_counter()
+        opts = opts or STTOptions()
+        language = opts.language or self.settings.language
+        region = self.settings.region
+
+        url = (
+            f"https://{region}.stt.speech.microsoft.com"
+            f"/speech/recognition/conversation/cognitiveservices/v1"
+            f"?language={language}"
+        )
+        headers = {
+            "Ocp-Apim-Subscription-Key": self.settings.subscription_key,
+            "Content-Type": "audio/wav",
+        }
+        response = await self._client.post(url, headers=headers, content=audio.data)
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"Azure Speech STT API error {response.status_code}: {response.text}"
+            )
+        data = response.json()
+        recognition_status = data.get("RecognitionStatus", "")
+        if recognition_status != "Success":
+            return Transcription(text="", language=language)
+        result = Transcription(
+            text=data.get("DisplayText", ""),
+            language=language,
+            confidence=data.get("Confidence"),
+        )
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+        return result
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError(
+            "Azure Speech STT batch provider does not support streaming input"
+        )
+        yield  # pragma: no cover

openspeech/providers/stt/baidu.py

@@ -0,0 +1,135 @@
+"""Baidu Cloud ASR STT provider adapter."""
+from __future__ import annotations
+
+import base64
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class BaiduSTTSettings(BaseSettings):
+    api_key: str = ""
+    secret_key: str = ""
+    dev_pid: int = 1537  # 1537=普通话, 1737=英语, 1637=粤语
+
+class BaiduSTT(STTProvider):
+    name = "baidu-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = BaiduSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"dev_pid": [1537, 1737, 1637, 1936, 1836]}
+
+    def __init__(self, settings: BaiduSTTSettings | None = None) -> None:
+        self.settings = settings or BaiduSTTSettings()
+        self._client: httpx.AsyncClient | None = None
+        self._owns_client: bool = True
+        self._token: str | None = None
+        self._token_expires_at: float = 0.0
+
+    def set_http_client(self, client) -> None:
+        self._client = client
+        self._owns_client = False
+
+    async def start(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client and self._owns_client:
+            await self._client.aclose()
+        self._client = None
+        self._token = None
+        self._token_expires_at = 0.0
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return bool(self.settings.api_key) and bool(self.settings.secret_key)
+
+    async def _get_token(self) -> str:
+        """Fetch or return cached OAuth access token."""
+        if self._token and time.time() < self._token_expires_at:
+            return self._token
+
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+
+        resp = await self._client.get(
+            "https://aip.baidubce.com/oauth/2.0/token",
+            params={
+                "grant_type": "client_credentials",
+                "client_id": self.settings.api_key,
+                "client_secret": self.settings.secret_key,
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        if "access_token" not in data:
+            raise RuntimeError(
+                f"Baidu OAuth error: {data.get('error_description', 'unknown')}"
+            )
+
+        self._token = data["access_token"]
+        self._token_expires_at = time.time() + data.get("expires_in", 2592000) - 60
+        return self._token  # type: ignore[return-value]
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, audio={} bytes", self.name, len(audio.data))
+        _t0 = time.perf_counter()
+
+        token = await self._get_token()
+        base64_audio = base64.b64encode(audio.data).decode("utf-8")
+
+        payload = {
+            "format": "wav",
+            "rate": 16000,
+            "channel": 1,
+            "cuid": "openspeech",
+            "token": token,
+            "dev_pid": self.settings.dev_pid,
+            "speech": base64_audio,
+            "len": len(audio.data),
+        }
+
+        resp = await self._client.post(
+            "https://vop.baidu.com/server_api",
+            json=payload,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        err_no = data.get("err_no", 0)
+        if err_no != 0:
+            raise RuntimeError(
+                f"Baidu ASR error [{err_no}]: {data.get('err_msg', 'unknown')}"
+            )
+
+        results = data.get("result", [])
+        text = results[0] if results else ""
+
+        result = Transcription(text=text)
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+        return result
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError("Baidu STT streaming not implemented")
+        yield  # noqa: unreachable — makes this an async generator

openspeech/providers/stt/deepgram.py

@@ -0,0 +1,311 @@
+"""Deepgram STT provider adapter (batch + streaming, httpx-based, no SDK needed)."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription, Word
+from openspeech.core.settings import BaseSettings
+
+
+def _ws_connect_with_headers(websockets_mod, url: str, headers: dict[str, str]):
+    """Compatible connect kwargs across websockets versions."""
+    try:
+        sig = inspect.signature(websockets_mod.connect)
+        if "additional_headers" in sig.parameters:
+            return websockets_mod.connect(url, additional_headers=headers)
+    except Exception:
+        pass
+    return websockets_mod.connect(url, extra_headers=headers)
+
+
+@dataclass
+class DeepgramSTTSettings(BaseSettings):
+    api_key: str = ""
+    model: str = "nova-2"
+    language: str = "en-US"
+    punctuate: bool = True
+    smart_format: bool = True
+
+class DeepgramSTT(STTProvider):
+    name = "deepgram"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = DeepgramSTTSettings
+    capabilities = {
+        Capability.STREAMING,
+        Capability.BATCH,
+        Capability.MULTILINGUAL,
+    }
+    field_options = {
+        "model": [
+            "nova-3", "nova-3-general", "nova-3-medical",
+            "nova-2", "nova-2-general", "nova-2-meeting", "nova-2-phonecall",
+            "nova-2-voicemail", "nova-2-finance", "nova-2-medical",
+            "enhanced", "enhanced-general",
+            "base", "base-general",
+            "whisper-large", "whisper-medium", "whisper-small",
+        ],
+        "language": [
+            "multi", "en", "en-US", "en-GB", "en-AU", "en-IN",
+            "zh", "zh-CN", "zh-TW", "zh-HK",
+            "ja", "ko", "ko-KR",
+            "es", "es-419", "fr", "fr-CA", "de", "de-CH",
+            "pt", "pt-BR", "pt-PT", "it", "nl", "nl-BE",
+            "ru", "uk", "pl", "cs", "sk",
+            "sv", "sv-SE", "da", "da-DK", "no", "fi",
+            "tr", "el", "ro", "hu", "bg",
+            "ar", "he", "fa", "hi", "hi-Latn", "bn", "ta", "te", "ur",
+            "id", "ms", "th", "th-TH", "vi", "tl",
+        ],
+    }
+
+    def __init__(self, settings: DeepgramSTTSettings | None = None) -> None:
+        self.settings = settings or DeepgramSTTSettings()
+        self._client: httpx.AsyncClient | None = None
+        self._owns_client: bool = True
+
+    def set_http_client(self, client) -> None:
+        self._client = client
+        self._owns_client = False
+
+    async def start(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client and self._owns_client:
+            await self._client.aclose()
+        self._client = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        # Cloud provider: healthy if API key is configured (client is lazy-started)
+        return bool(self.settings.api_key)
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, audio={} bytes", self.name, len(audio.data))
+        _t0 = time.perf_counter()
+        opts = opts or STTOptions()
+
+        language = opts.language or self.settings.language
+        params = {
+            "model": self.settings.model,
+            "language": language,
+            "punctuate": str(self.settings.punctuate).lower(),
+            "smart_format": str(self.settings.smart_format).lower(),
+        }
+        headers = {
+            "Authorization": f"Token {self.settings.api_key}",
+            "Content-Type": "audio/wav",
+        }
+
+        resp = await self._client.post(
+            "https://api.deepgram.com/v1/listen",
+            params=params,
+            headers=headers,
+            content=audio.data,
+        )
+        if resp.status_code != 200:
+            raise RuntimeError(f"Deepgram API error ({resp.status_code}): {resp.text}")
+
+        data = resp.json()
+        channel = data.get("results", {}).get("channels", [{}])[0]
+        alt = channel.get("alternatives", [{}])[0]
+
+        words: list[Word] = []
+        for w in alt.get("words", []):
+            words.append(
+                Word(
+                    text=w.get("word", ""),
+                    start_ms=int(w.get("start", 0) * 1000),
+                    end_ms=int(w.get("end", 0) * 1000),
+                    confidence=w.get("confidence"),
+                )
+            )
+
+        result = Transcription(
+            text=alt.get("transcript", ""),
+            language=channel.get("detected_language"),
+            confidence=alt.get("confidence"),
+            words=words if words else None,
+        )
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+        return result
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        """Stream audio chunks to Deepgram via WebSocket and yield transcriptions.
+
+        Deepgram streaming protocol (``interim_results=true``):
+        - Each ``Results`` message contains an utterance-level transcript with
+          ``is_final`` (bool) indicating whether the utterance is finalized.
+        - ``speech_final`` (bool) indicates end-of-speech (VAD silence).
+        - This implementation accumulates finalized utterances and appends the
+          latest interim text so each yield is a **full-text snapshot** that
+          the frontend can display directly via ``streamTextSnapshot``.
+        - ``is_partial`` on the yielded ``Transcription`` is set according to
+          ``speech_final`` so the server can forward ``"type": "final"`` and
+          trigger auto-stop on the client.
+        """
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+
+        import websockets
+
+        _t0 = time.perf_counter()
+        _frames_sent = 0
+
+        params = (
+            f"model={self.settings.model}"
+            f"&language={self.settings.language}"
+            f"&punctuate={'true' if self.settings.punctuate else 'false'}"
+            f"&smart_format={'true' if self.settings.smart_format else 'false'}"
+            f"&encoding=linear16&sample_rate=16000"
+            f"&interim_results=true"
+            f"&vad_events=true"
+        )
+        url = f"wss://api.deepgram.com/v1/listen?{params}"
+        headers = {"Authorization": f"Token {self.settings.api_key}"}
+
+        results: asyncio.Queue[Transcription | None] = asyncio.Queue()
+        _sender_stop = asyncio.Event()
+
+        logger.debug("{}: connecting to Deepgram WebSocket...", self.name)
+        async with _ws_connect_with_headers(websockets, url, headers) as ws:
+            _t_connected = time.perf_counter()
+            logger.info("{}: WS connected in {:.0f}ms", self.name,
+                        (_t_connected - _t0) * 1000)
+
+            async def send_audio() -> None:
+                nonlocal _frames_sent
+                try:
+                    async for chunk in stream:
+                        if _sender_stop.is_set():
+                            break
+                        if chunk:
+                            await ws.send(chunk)
+                            _frames_sent += 1
+                            if _frames_sent == 1:
+                                logger.debug("{}: first frame sent at {:.0f}ms",
+                                             self.name, (time.perf_counter() - _t0) * 1000)
+                    if not _sender_stop.is_set():
+                        await ws.send(json.dumps({"type": "CloseStream"}))
+                except websockets.exceptions.ConnectionClosed:
+                    pass
+                finally:
+                    logger.debug(
+                        "{}: stream sender done, sent {} frames in {:.0f}ms",
+                        self.name, _frames_sent, (time.perf_counter() - _t0) * 1000,
+                    )
+
+            async def receive_results() -> None:
+                # Accumulate finalized utterance parts so each yield is a
+                # full-text snapshot (not just the latest utterance fragment).
+                confirmed_parts: list[str] = []
+                _resp_count = 0
+
+                try:
+                    async for msg in ws:
+                        data = json.loads(msg)
+                        if data.get("type") != "Results":
+                            continue
+
+                        _resp_count += 1
+                        channel = data.get("channel", {})
+                        alts = channel.get("alternatives", [])
+                        if not alts:
+                            continue
+                        transcript = alts[0].get("transcript", "").strip()
+                        is_final = data.get("is_final", False)
+                        speech_final = data.get("speech_final", False)
+                        detected_language = channel.get(
+                            "detected_language", self.settings.language
+                        )
+                        confidence = alts[0].get("confidence")
+
+                        if _resp_count == 1:
+                            logger.debug("{}: first response at {:.0f}ms  is_final={}  speech_final={}",
+                                         self.name, (time.perf_counter() - _t0) * 1000,
+                                         is_final, speech_final)
+
+                        if is_final and transcript:
+                            confirmed_parts.append(transcript)
+
+                        # Build full-text snapshot: confirmed + current interim
+                        if is_final:
+                            snapshot = " ".join(confirmed_parts)
+                        else:
+                            parts = list(confirmed_parts)
+                            if transcript:
+                                parts.append(transcript)
+                            snapshot = " ".join(parts)
+
+                        if not snapshot:
+                            continue
+
+                        # speech_final = Deepgram VAD detected end of speech
+                        is_partial = not speech_final
+                        await results.put(Transcription(
+                            text=snapshot,
+                            confidence=confidence,
+                            language=detected_language or self.settings.language,
+                            is_partial=is_partial,
+                        ))
+
+                        if speech_final:
+                            _sender_stop.set()
+                            logger.info("{}: final result at {:.0f}ms  responses={}  text='{}'",
+                                        self.name, (time.perf_counter() - _t0) * 1000,
+                                        _resp_count, snapshot[:60])
+                            break
+                except websockets.exceptions.ConnectionClosed:
+                    # Emit whatever we have as final
+                    snapshot = " ".join(confirmed_parts).strip()
+                    if snapshot:
+                        await results.put(Transcription(
+                            text=snapshot, is_partial=False,
+                            language=self.settings.language,
+                        ))
+                    _sender_stop.set()
+                finally:
+                    _sender_stop.set()
+                    await results.put(None)
+
+            send_task = asyncio.create_task(send_audio())
+            recv_task = asyncio.create_task(receive_results())
+
+            while True:
+                item = await results.get()
+                if item is None:
+                    break
+                yield item
+
+            logger.info(
+                "{}: stream completed in {:.0f}ms, frames={}",
+                self.name, (time.perf_counter() - _t0) * 1000, _frames_sent,
+            )
+            send_task.cancel()
+            try:
+                await send_task
+            except asyncio.CancelledError:
+                pass
+            await recv_task