openspeechapi 0.1.0__py3-none-any.whl

openspeech/observe/base.py

@@ -0,0 +1,79 @@
+"""DispatchObserver ABC and ObserverManager with error isolation."""
+from __future__ import annotations
+from abc import ABC
+from typing import Any
+from openspeech.logging_config import logger
+from openspeech.core.enums import ExecMode
+from openspeech.dispatch.context import InvokeContext
+
+
+class DispatchObserver(ABC):
+    """Base class for dispatch observers. All methods are optional no-ops."""
+
+    async def on_invoke_start(self, ctx: InvokeContext) -> None: pass
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None: pass
+    async def on_invoke_error(self, ctx: InvokeContext, error: Exception) -> None: pass
+    async def on_stream_chunk(self, ctx: InvokeContext, chunk: Any) -> None: pass
+    async def on_provider_start(self, provider: str, exec_mode: ExecMode) -> None: pass
+    async def on_provider_stop(self, provider: str) -> None: pass
+    async def on_health_change(self, provider: str, healthy: bool) -> None: pass
+
+
+class ObserverManager:
+    """Manages observers with error isolation and auto-deregistration."""
+
+    def __init__(self, max_consecutive_errors: int = 10) -> None:
+        self._observers: list[DispatchObserver] = []
+        self._error_counts: dict[int, int] = {}
+        self._max_errors = max_consecutive_errors
+
+    def add(self, observer: DispatchObserver) -> None:
+        self._observers.append(observer)
+        self._error_counts[id(observer)] = 0
+
+    def remove(self, observer: DispatchObserver) -> None:
+        self._observers.remove(observer)
+        self._error_counts.pop(id(observer), None)
+
+    def list(self) -> list[DispatchObserver]:
+        return list(self._observers)
+
+    async def _notify(self, method: str, *args: Any, **kwargs: Any) -> None:
+        to_remove = []
+        for obs in self._observers:
+            try:
+                fn = getattr(obs, method)
+                await fn(*args, **kwargs)
+                self._error_counts[id(obs)] = 0
+            except Exception as e:
+                obs_id = id(obs)
+                self._error_counts[obs_id] = self._error_counts.get(obs_id, 0) + 1
+                logger.warning(f"Observer {type(obs).__name__} raised {type(e).__name__}: {e}")
+                if self._error_counts[obs_id] >= self._max_errors:
+                    to_remove.append(obs)
+                    logger.warning(
+                        f"Auto-deregistering {type(obs).__name__} after {self._max_errors} consecutive errors"
+                    )
+        for obs in to_remove:
+            self.remove(obs)
+
+    async def notify_invoke_start(self, ctx: InvokeContext) -> None:
+        await self._notify("on_invoke_start", ctx)
+
+    async def notify_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        await self._notify("on_invoke_end", ctx, result)
+
+    async def notify_invoke_error(self, ctx: InvokeContext, error: Exception) -> None:
+        await self._notify("on_invoke_error", ctx, error)
+
+    async def notify_stream_chunk(self, ctx: InvokeContext, chunk: Any) -> None:
+        await self._notify("on_stream_chunk", ctx, chunk)
+
+    async def notify_provider_start(self, provider: str, exec_mode: ExecMode) -> None:
+        await self._notify("on_provider_start", provider, exec_mode)
+
+    async def notify_provider_stop(self, provider: str) -> None:
+        await self._notify("on_provider_stop", provider)
+
+    async def notify_health_change(self, provider: str, healthy: bool) -> None:
+        await self._notify("on_health_change", provider, healthy)

openspeech/observe/debug.py

@@ -0,0 +1,44 @@
+"""DebugLogObserver — emits loguru debug output for every lifecycle event."""
+from __future__ import annotations
+from typing import Any
+from openspeech.logging_config import logger
+from openspeech.core.enums import ExecMode
+from openspeech.dispatch.context import InvokeContext
+from openspeech.observe.base import DispatchObserver
+
+
+class DebugLogObserver(DispatchObserver):
+    """Logs all dispatch lifecycle events at DEBUG level via loguru."""
+
+    async def on_invoke_start(self, ctx: InvokeContext) -> None:
+        logger.debug(
+            "[openspeech] invoke_start provider={} method={} request_id={}",
+            ctx.provider_name, ctx.method, ctx.request_id,
+        )
+
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        logger.debug(
+            "[openspeech] invoke_end provider={} method={} request_id={} elapsed_ms={:.2f}",
+            ctx.provider_name, ctx.method, ctx.request_id, ctx.elapsed_ms,
+        )
+
+    async def on_invoke_error(self, ctx: InvokeContext, error: Exception) -> None:
+        logger.debug(
+            "[openspeech] invoke_error provider={} method={} request_id={} error={}",
+            ctx.provider_name, ctx.method, ctx.request_id, repr(error),
+        )
+
+    async def on_stream_chunk(self, ctx: InvokeContext, chunk: Any) -> None:
+        logger.debug(
+            "[openspeech] stream_chunk provider={} method={} request_id={}",
+            ctx.provider_name, ctx.method, ctx.request_id,
+        )
+
+    async def on_provider_start(self, provider: str, exec_mode: ExecMode) -> None:
+        logger.debug("[openspeech] provider_start provider={} exec_mode={}", provider, exec_mode)
+
+    async def on_provider_stop(self, provider: str) -> None:
+        logger.debug("[openspeech] provider_stop provider={}", provider)
+
+    async def on_health_change(self, provider: str, healthy: bool) -> None:
+        logger.debug("[openspeech] health_change provider={} healthy={}", provider, healthy)

openspeech/observe/latency.py

@@ -0,0 +1,19 @@
+"""LatencyObserver — records total_ms and ttfb_ms latency samples."""
+from __future__ import annotations
+from typing import Any
+from openspeech.dispatch.context import InvokeContext
+from openspeech.observe.base import DispatchObserver
+
+
+class LatencyObserver(DispatchObserver):
+    """Accumulates per-invocation latency samples (total duration and TTFB)."""
+
+    def __init__(self) -> None:
+        self.total_ms: list[float] = []
+        self.ttfb_ms: list[float] = []
+
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        self.total_ms.append(ctx.elapsed_ms)
+        if ctx.ttfb_ns is not None:
+            ttfb = (ctx.ttfb_ns - ctx.start_time_ns) / 1_000_000
+            self.ttfb_ms.append(ttfb)

openspeech/observe/metrics.py

@@ -0,0 +1,47 @@
+"""MetricsObserver — tracks TTFB, duration, and error counts per provider+method."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+from openspeech.dispatch.context import InvokeContext
+from openspeech.observe.base import DispatchObserver
+
+
+@dataclass
+class _ProviderMethodMetrics:
+    total_calls: int = 0
+    error_count: int = 0
+    durations_ms: list[float] = field(default_factory=list)
+    ttfb_ms: list[float] = field(default_factory=list)
+
+
+class MetricsObserver(DispatchObserver):
+    """Collects invocation metrics (call counts, durations, TTFB, errors) keyed by provider+method."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, _ProviderMethodMetrics] = {}
+
+    def _key(self, ctx: InvokeContext) -> str:
+        return f"{ctx.provider_name}.{ctx.method}"
+
+    def _get(self, key: str) -> _ProviderMethodMetrics:
+        if key not in self._data:
+            self._data[key] = _ProviderMethodMetrics()
+        return self._data[key]
+
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        key = self._key(ctx)
+        m = self._get(key)
+        m.total_calls += 1
+        m.durations_ms.append(ctx.elapsed_ms)
+        if ctx.ttfb_ns is not None:
+            ttfb = (ctx.ttfb_ns - ctx.start_time_ns) / 1_000_000
+            m.ttfb_ms.append(ttfb)
+
+    async def on_invoke_error(self, ctx: InvokeContext, error: Exception) -> None:
+        key = self._key(ctx)
+        m = self._get(key)
+        m.error_count += 1
+
+    def get(self, provider: str, method: str) -> _ProviderMethodMetrics | None:
+        """Return accumulated metrics for the given provider+method, or None if not seen."""
+        return self._data.get(f"{provider}.{method}")

openspeech/observe/tracing.py

@@ -0,0 +1,44 @@
+"""TracingObserver — OpenTelemetry tracing stub, graceful if not installed."""
+from __future__ import annotations
+from typing import Any
+from openspeech.dispatch.context import InvokeContext
+from openspeech.observe.base import DispatchObserver
+
+
+class TracingObserver(DispatchObserver):
+    """Wraps each invocation in an OpenTelemetry span.  Falls back to a no-op when
+    the ``opentelemetry`` package is not installed."""
+
+    def __init__(self, service_name: str = "openspeech") -> None:
+        try:
+            from opentelemetry import trace
+            self._tracer = trace.get_tracer(service_name)
+        except ImportError:
+            self._tracer = None
+        self._spans: dict[str, Any] = {}
+
+    async def on_invoke_start(self, ctx: InvokeContext) -> None:
+        if self._tracer is None:
+            return
+        span = self._tracer.start_span(
+            f"{ctx.provider_name}.{ctx.method}",
+            attributes={
+                "provider": ctx.provider_name,
+                "method": ctx.method,
+                "exec_mode": ctx.exec_mode.value,
+                "request_id": ctx.request_id,
+            },
+        )
+        self._spans[ctx.request_id] = span
+
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        span = self._spans.pop(ctx.request_id, None)
+        if span:
+            span.end()
+
+    async def on_invoke_error(self, ctx: InvokeContext, error: Exception) -> None:
+        span = self._spans.pop(ctx.request_id, None)
+        if span:
+            from opentelemetry.trace import StatusCode
+            span.set_status(StatusCode.ERROR, str(error))
+            span.end()

openspeech/observe/usage.py

@@ -0,0 +1,27 @@
+"""UsageObserver — tracks call counts, audio duration, and character counts."""
+from __future__ import annotations
+from typing import Any
+from openspeech.dispatch.context import InvokeContext
+from openspeech.observe.base import DispatchObserver
+
+
+class UsageObserver(DispatchObserver):
+    """Accumulates usage statistics: invocation counts, audio duration, and text characters."""
+
+    def __init__(self) -> None:
+        self.call_count: int = 0
+        self.total_audio_duration_ms: int = 0
+        self.total_characters: int = 0
+
+    async def on_invoke_end(self, ctx: InvokeContext, result: Any) -> None:
+        self.call_count += 1
+
+        # Accumulate audio duration from AudioData results (STT input or TTS output)
+        audio_duration = getattr(result, "duration_ms", None)
+        if audio_duration is not None:
+            self.total_audio_duration_ms += audio_duration
+
+        # Accumulate text characters from ctx.metadata["text"] (set by caller for TTS)
+        text = ctx.metadata.get("text")
+        if isinstance(text, str):
+            self.total_characters += len(text)

openspeech/providers/_template.py

@@ -0,0 +1,101 @@
+"""
+Provider adapter template — copy-paste starting point for new adapters.
+
+Steps to create a new adapter:
+1. Copy this file to providers/stt/<name>.py or providers/tts/<name>.py
+2. Replace MyProvider* placeholders with the real names
+3. Fill in the correct name, provider_type, execution_mode, capabilities
+4. Implement start() to import the SDK and build the client
+5. Implement transcribe() / synthesize() (and streaming variants if supported)
+6. Add the provider to openspeech/core/registry.py if auto-registration is desired
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from openspeech.core.base import STTProvider  # swap for TTSProvider as needed
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+
+# ---------------------------------------------------------------------------
+# Settings dataclass — one field per provider-specific config value
+# ---------------------------------------------------------------------------
+@dataclass
+class MyProviderSettings(BaseSettings):
+    api_key: str = ""
+    model: str = "default-model"
+    # add more fields as needed
+
+
+# ---------------------------------------------------------------------------
+# Provider class
+# ---------------------------------------------------------------------------
+class MyProviderSTT(STTProvider):
+    # --- class-level metadata (required by SpeechProvider ABC) ---
+    name = "my-provider"
+    provider_type = ProviderType.STT            # or ProviderType.TTS
+    execution_mode = ExecMode.IN_PROCESS        # or SUBPROCESS / REMOTE
+    settings_cls = MyProviderSettings
+    capabilities = {Capability.BATCH}           # choose from enums.Capability
+
+    def __init__(self, settings: MyProviderSettings | None = None) -> None:
+        self.settings = settings or MyProviderSettings()
+        self._client: Any = None
+
+    # --- lifecycle ---
+
+    async def start(self) -> None:
+        """Import SDK and initialise the client."""
+        try:
+            import my_sdk  # noqa: F401  replace with real import
+            self._client = object()  # replace with real client construction
+        except ImportError:
+            raise ImportError(
+                "Install the SDK: pip install openspeech[my-provider]"
+            )
+
+    async def stop(self) -> None:
+        """Release resources."""
+        self._client = None
+
+    async def health_check(self) -> bool:
+        return self._client is not None
+
+    # --- STT interface (remove if implementing TTSProvider) ---
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        opts = opts or STTOptions()
+        raise NotImplementedError("Implement transcribe() for MyProviderSTT")
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError(
+            "Streaming transcription is not supported by MyProviderSTT"
+        )
+        yield  # pragma: no cover
+
+    # --- TTS interface (uncomment if implementing TTSProvider) ---
+
+    # async def synthesize(
+    #     self, text: str, opts: TTSOptions | None = None
+    # ) -> AudioData:
+    #     if self._client is None:
+    #         raise RuntimeError("Provider not started — call start() first")
+    #     raise NotImplementedError("Implement synthesize() for MyProviderTTS")
+
+    # async def synthesize_stream(
+    #     self, text: str, opts: TTSOptions | None = None
+    # ) -> AsyncIterator[AudioChunk]:
+    #     raise NotImplementedError(
+    #         "Streaming synthesis is not supported by MyProviderTTS"
+    #     )
+    #     yield  # pragma: no cover

openspeech/providers/stt/alibaba.py

@@ -0,0 +1,86 @@
+"""Alibaba Cloud (Bailian/DashScope) STT provider adapter — OpenAI-compatible."""
+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 AlibabaSTTSettings(BaseSettings):
+    api_key: str = ""
+    model: str = "paraformer-v2"
+    base_url: str = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+
+class AlibabaSTT(STTProvider):
+    name = "alibaba-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = AlibabaSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"model": ["paraformer-v2", "paraformer-realtime-v2", "paraformer-8k-v1"]}
+
+    def __init__(self, settings: AlibabaSTTSettings | None = None) -> None:
+        self.settings = settings or AlibabaSTTSettings()
+        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.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()
+        model = opts.model or self.settings.model
+        url = f"{self.settings.base_url}/audio/transcriptions"
+
+        headers = {"Authorization": f"Bearer {self.settings.api_key}"}
+        files = {"file": ("audio.wav", audio.data, "audio/wav")}
+        data = {"model": model}
+
+        resp = await self._client.post(
+            url, headers=headers, files=files, data=data
+        )
+        resp.raise_for_status()
+        result = resp.json()
+
+        transcription = Transcription(text=result.get("text", ""))
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(transcription.text))
+        return transcription
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError("Alibaba STT streaming not implemented")
+        yield  # noqa: unreachable — makes this an async generator

openspeech/providers/stt/assemblyai.py

@@ -0,0 +1,135 @@
+"""AssemblyAI STT provider adapter (batch, httpx)."""
+from __future__ import annotations
+
+import asyncio
+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 AssemblyAISTTSettings(BaseSettings):
+    api_key: str = ""
+    model: str = "best"
+    language: str = "en"
+
+class AssemblyAISTT(STTProvider):
+    name = "assemblyai-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.REMOTE
+    settings_cls = AssemblyAISTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"model": ["best", "nano"], "language": ["en", "zh", "ja", "ko", "es", "fr", "de", "pt", "it", "nl", "ru", "ar", "hi", "auto"]}
+
+    def __init__(self, settings: AssemblyAISTTSettings | None = None) -> None:
+        self.settings = settings or AssemblyAISTTSettings()
+        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.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
+        headers = {"Authorization": self.settings.api_key}
+
+        # Step 1: Upload audio
+        upload_resp = await self._client.post(
+            "https://api.assemblyai.com/v2/upload",
+            headers=headers,
+            content=audio.data,
+        )
+        if upload_resp.status_code != 200:
+            raise RuntimeError(
+                f"AssemblyAI upload error {upload_resp.status_code}: {upload_resp.text}"
+            )
+        upload_url = upload_resp.json()["upload_url"]
+
+        # Step 2: Create transcript
+        create_resp = await self._client.post(
+            "https://api.assemblyai.com/v2/transcript",
+            headers=headers,
+            json={
+                "audio_url": upload_url,
+                "language_code": language,
+                "speech_model": self.settings.model,
+            },
+        )
+        if create_resp.status_code != 200:
+            raise RuntimeError(
+                f"AssemblyAI transcript creation error "
+                f"{create_resp.status_code}: {create_resp.text}"
+            )
+        transcript_id = create_resp.json()["id"]
+
+        # Step 3: Poll until completed
+        poll_url = f"https://api.assemblyai.com/v2/transcript/{transcript_id}"
+        max_wait = 60.0
+        elapsed = 0.0
+        while elapsed < max_wait:
+            poll_resp = await self._client.get(poll_url, headers=headers)
+            if poll_resp.status_code != 200:
+                raise RuntimeError(
+                    f"AssemblyAI poll error {poll_resp.status_code}: {poll_resp.text}"
+                )
+            data = poll_resp.json()
+            status = data.get("status", "")
+            if status == "completed":
+                result = Transcription(
+                    text=data.get("text", ""),
+                    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
+            if status == "error":
+                raise RuntimeError(
+                    f"AssemblyAI transcription failed: {data.get('error', 'unknown')}"
+                )
+            await asyncio.sleep(1.0)
+            elapsed += 1.0
+
+        raise RuntimeError(
+            f"AssemblyAI transcription timed out after {max_wait}s "
+            f"for transcript {transcript_id}"
+        )
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError(
+            "AssemblyAI batch provider does not support streaming input"
+        )
+        yield  # pragma: no cover