openspeechapi 0.1.0__py3-none-any.whl

openspeech/dispatch/context.py

@@ -0,0 +1,34 @@
+"""InvokeContext — request-scoped metadata for invocation lifecycle."""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from openspeech.core.enums import ExecMode
+
+
+@dataclass
+class InvokeContext:
+    provider_name: str
+    method: str
+    exec_mode: ExecMode
+    request_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    start_time_ns: int = field(default_factory=time.time_ns)
+    ttfb_ns: int | None = None
+    end_time_ns: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    parent_id: str | None = None
+
+    def record_ttfb(self) -> None:
+        if self.ttfb_ns is None:
+            self.ttfb_ns = time.time_ns()
+
+    def record_end(self) -> None:
+        self.end_time_ns = time.time_ns()
+
+    @property
+    def elapsed_ms(self) -> float:
+        end = self.end_time_ns or time.time_ns()
+        return (end - self.start_time_ns) / 1_000_000

openspeech/dispatch/dispatcher.py

@@ -0,0 +1,661 @@
+"""ServiceDispatcher — config-driven orchestrator for speech provider execution."""
+from __future__ import annotations
+
+import asyncio
+from openspeech.logging_config import logger
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+import warnings
+
+from openspeech.config import EngineConfig, load_config
+from openspeech.core.base import SpeechProvider
+from openspeech.core.enums import ExecMode
+from openspeech.core.models import AudioData, STTOptions, TTSOptions, Transcription
+from openspeech.core.registry import ProviderRegistry
+from openspeech.core.settings import BaseSettings
+from openspeech.dispatch.context import InvokeContext
+from openspeech.dispatch.executors.base import Executor
+from openspeech.dispatch.executors.in_process import InProcessExecutor
+from openspeech.dispatch.executors.remote import RemoteExecutor
+from openspeech.dispatch.executors.subprocess_exec import SubprocessExecutor
+from openspeech.dispatch.fanout import FirstCompleted, MergeStrategy, fan_out
+from openspeech.dispatch.lifecycle import ProviderLifecycleManager
+from openspeech.exceptions import ProviderNotFoundError
+from openspeech.logging_config import bind_context
+from openspeech.observe.base import DispatchObserver, ObserverManager
+from openspeech.telemetry.perf import Event, PerfTimer, milestone
+
+@dataclass
+class _EngineHandle:
+    """Internal handle pairing a provider class with its executor and settings dict."""
+    name: str
+    provider_cls: type[SpeechProvider]
+    executor: Executor
+    exec_mode: ExecMode = ExecMode.IN_PROCESS
+    settings_dict: dict[str, Any] = field(default_factory=dict)
+    preload: bool = False
+    keepalive: int = 0
+
+# Backward compatibility alias
+_ProviderHandle = _EngineHandle
+
+def _exec_mode_desc(mode: str) -> str:
+    """Human-readable description of an execution mode."""
+    m = str(mode).strip().lower()
+    if m == "subprocess":
+        return "Worker subprocess + IPC"
+    if m == "local":
+        return "Local engine service + HTTP(S)"
+    if m == "remote":
+        return "Cloud/remote API over network"
+    if m == "in_process":
+        return "In-process model execution"
+    return "Unknown"
+
+
+def _make_executor(mode: ExecMode) -> Executor:
+    if mode == ExecMode.IN_PROCESS:
+        return InProcessExecutor()
+    if mode == ExecMode.SUBPROCESS:
+        return SubprocessExecutor()
+    if mode in {ExecMode.REMOTE, ExecMode.LOCAL}:
+        return RemoteExecutor()
+    raise ValueError(f"Unknown exec_mode: {mode!r}")
+
+# Providers that genuinely run in-process (no network/subprocess).
+_TRUE_IN_PROCESS_PROVIDERS = {
+    "macos-say", "macos-stt",
+    "windows-tts", "windows-stt",
+    "native-tts", "native-stt",
+}
+
+def _resolve_exec_mode(alias: str, provider_name: str, raw_mode: str) -> ExecMode:
+    m = str(raw_mode).strip().lower()
+    if m == ExecMode.IN_PROCESS.value:
+        # True in-process providers: keep IN_PROCESS
+        if provider_name in _TRUE_IN_PROCESS_PROVIDERS:
+            return ExecMode.IN_PROCESS
+        # Backward compatibility: old configs used in_process for both local-service and cloud providers.
+        if provider_name == "fish-speech":
+            warnings.warn(
+                f"Provider '{alias}' uses legacy exec_mode='in_process'; auto-mapped to 'local'. "
+                "Please update config to exec_mode='local'.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return ExecMode.LOCAL
+        warnings.warn(
+            f"Provider '{alias}' uses legacy exec_mode='in_process'; auto-mapped to 'remote'. "
+            "Please update config to exec_mode='remote' (or keep 'in_process' only for true in-process models).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return ExecMode.REMOTE
+    return ExecMode(m)
+
+class _STTNamespace:
+    """Namespaced STT operations on a ServiceDispatcher."""
+
+    def __init__(self, dispatcher: "ServiceDispatcher") -> None:
+        self._dispatcher = dispatcher
+
+    async def transcribe(
+        self,
+        provider: str,
+        audio: "AudioData",
+        opts: "STTOptions | None" = None,
+    ) -> "Transcription":
+        """Transcribe audio using the named provider."""
+        return await self._dispatcher._transcribe(provider, audio, opts)
+
+    async def transcribe_stream(
+        self,
+        provider: str,
+        stream: "AsyncIterator[bytes]",
+    ) -> "AsyncIterator[Transcription]":
+        """Stream audio chunks to the named provider and yield transcriptions."""
+        async for item in self._dispatcher._transcribe_stream(provider, stream):
+            yield item
+
+    async def fanout(
+        self,
+        providers: list[str],
+        audio: "AudioData",
+        opts: "STTOptions | None" = None,
+        strategy: "MergeStrategy | None" = None,
+    ) -> Any:
+        """Dispatch transcription to multiple providers concurrently."""
+        return await self._dispatcher._fanout_transcribe(providers, audio, opts, strategy)
+
+class _TTSNamespace:
+    """Namespaced TTS operations on a ServiceDispatcher."""
+
+    def __init__(self, dispatcher: "ServiceDispatcher") -> None:
+        self._dispatcher = dispatcher
+
+    async def synthesize(
+        self,
+        provider: str,
+        text: str,
+        opts: "TTSOptions | None" = None,
+    ) -> "AudioData":
+        """Synthesize speech using the named provider."""
+        return await self._dispatcher._synthesize(provider, text, opts)
+
+    async def synthesize_stream(
+        self,
+        provider: str,
+        text: str,
+        opts: "TTSOptions | None" = None,
+    ) -> "AsyncIterator[Any]":
+        """Stream synthesized speech using the named provider."""
+        async for chunk in self._dispatcher._synthesize_stream(provider, text, opts):
+            yield chunk
+
+class ServiceDispatcher:
+    """Orchestrates multiple speech providers via config-driven executor routing."""
+
+    def __init__(self, handles: dict[str, _EngineHandle]) -> None:
+        self._handles = handles
+        self._observer_mgr = ObserverManager()
+        self._lifecycle = ProviderLifecycleManager()
+        self.stt = _STTNamespace(self)
+        self.tts = _TTSNamespace(self)
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_config(cls, path: Path, registry: ProviderRegistry) -> "ServiceDispatcher":
+        """Load YAML config and construct a ServiceDispatcher.
+
+        Raises ProviderNotFoundError if any configured provider name is not in the registry.
+        """
+        config = load_config(path)
+        handles: dict[str, _EngineHandle] = {}
+
+        for alias, eng_cfg in config.engines.items():
+            handles[alias] = cls._build_handle(alias, eng_cfg, registry)
+
+        return cls(handles)
+
+    @staticmethod
+    def _build_handle(
+        alias: str,
+        eng_cfg: Any,
+        registry: ProviderRegistry,
+    ) -> _EngineHandle:
+        """Construct an _EngineHandle from an EngineConfig entry."""
+        provider_cls = registry.get(eng_cfg.provider)  # raises ProviderNotFoundError
+        mode = _resolve_exec_mode(alias, eng_cfg.provider, eng_cfg.exec_mode)
+        executor = _make_executor(mode)
+
+        # Store provider info so health_check works before lazy-start
+        if hasattr(executor, "set_provider_info"):
+            settings_cls = getattr(provider_cls, "settings_cls", None)
+            if settings_cls:
+                try:
+                    settings_obj = settings_cls(**eng_cfg.settings)
+                except Exception:
+                    settings_obj = settings_cls()
+                executor.set_provider_info(provider_cls, settings_obj)
+
+        return _EngineHandle(
+            name=alias,
+            provider_cls=provider_cls,
+            executor=executor,
+            exec_mode=mode,
+            settings_dict=eng_cfg.settings,
+            preload=eng_cfg.preload,
+            keepalive=eng_cfg.keepalive,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        """Register all providers in lifecycle manager and start preloaded ones."""
+        # Create a shared httpx.AsyncClient up-front so all cloud providers
+        # reuse the same SSL/transport resources (avoids N × 5 s cold-start
+        # on Windows where SSL certificate chain loading is expensive).
+        import httpx
+
+        self._shared_http_client = httpx.AsyncClient(timeout=60.0)
+        self._lifecycle.set_shared_http_client(self._shared_http_client)
+
+        for handle in self._handles.values():
+            self._lifecycle.register(handle.name, handle, handle.keepalive)
+        self._lifecycle.start_idle_checker()
+        for handle in self._handles.values():
+            if handle.preload:
+                await self._lifecycle.ensure_ready(handle.name)
+
+    async def stop(self) -> None:
+        """Stop all configured provider executors via lifecycle manager."""
+        await self._lifecycle.stop_all()
+        # Close the shared HTTP client *after* all providers have stopped
+        # so no in-flight requests are interrupted.
+        if getattr(self, "_shared_http_client", None) is not None:
+            await self._shared_http_client.aclose()
+            self._shared_http_client = None
+
+    async def reload_config(
+        self, config_path: Path, registry: ProviderRegistry
+    ) -> dict[str, list[str]]:
+        """Hot-reload: re-read config, diff with current state, apply changes.
+
+        Returns a dict with keys added/removed/updated/unchanged listing provider aliases.
+        """
+        new_config = load_config(config_path)
+        old_names = set(self._handles.keys())
+        new_names = set(new_config.engines.keys())
+
+        added = new_names - old_names
+        removed = old_names - new_names
+        potentially_changed = old_names & new_names
+
+        updated: list[str] = []
+        unchanged: list[str] = []
+
+        # Remove deleted providers
+        for name in removed:
+            await self._lifecycle.stop_provider(name)
+            self._lifecycle.unregister(name)
+            del self._handles[name]
+
+        # Check for changed settings in existing providers
+        for name in potentially_changed:
+            old_handle = self._handles[name]
+            new_cfg = new_config.engines[name]
+            if (
+                old_handle.settings_dict != new_cfg.settings
+                or old_handle.exec_mode
+                != _resolve_exec_mode(name, new_cfg.provider, new_cfg.exec_mode)
+                or old_handle.provider_cls != registry.get(new_cfg.provider)
+            ):
+                # Settings changed — stop old, rebuild handle
+                await self._lifecycle.stop_provider(name)
+                self._lifecycle.unregister(name)
+                new_handle = self._build_handle(name, new_cfg, registry)
+                self._handles[name] = new_handle
+                self._lifecycle.register(name, new_handle, new_cfg.keepalive)
+                updated.append(name)
+            else:
+                unchanged.append(name)
+
+        # Add new engines
+        for name in added:
+            eng_cfg = new_config.engines[name]
+            new_handle = self._build_handle(name, eng_cfg, registry)
+            self._handles[name] = new_handle
+            self._lifecycle.register(name, new_handle, eng_cfg.keepalive)
+            if eng_cfg.preload:
+                await self._lifecycle.ensure_ready(name)
+
+        return {
+            "added": sorted(added),
+            "removed": sorted(removed),
+            "updated": sorted(updated),
+            "unchanged": sorted(unchanged),
+        }
+
+    def provider_states(self) -> dict[str, str]:
+        """Return lifecycle state for each registered provider."""
+        return self._lifecycle.list_states()
+
+    # ------------------------------------------------------------------
+    # Provider lookup
+    # ------------------------------------------------------------------
+
+    def list_engines(self) -> list[str]:
+        """Return the list of configured engine aliases."""
+        return list(self._handles.keys())
+
+    # Backward compatibility alias
+    def list_providers(self) -> list[str]:
+        """Return the list of configured engine aliases (deprecated, use list_engines)."""
+        return self.list_engines()
+
+    # Display-friendly settings keys extracted for UI display_info
+    _DISPLAY_INFO_KEYS = (
+        "model", "model_size", "model_name", "voice", "voice_id", "voice_type",
+        "voice_name", "language", "engine_type", "dev_pid", "base_url", "region",
+        "api_url", "cluster",
+    )
+
+    def list_engines_info(self, *, engine_type: str | None = None) -> list[dict]:
+        """Return detailed information for all configured engines.
+
+        Equivalent to the ``GET /v1/engines`` response payload but available
+        as a library API — no HTTP server required.
+
+        Args:
+            engine_type: Optional filter — ``"stt"`` or ``"tts"``.
+                         ``None`` returns all engines.
+
+        Returns:
+            A list of dicts, each containing::
+
+                {
+                    "name":          str,   # config alias
+                    "display_name":  str,   # human-friendly name (from catalog)
+                    "provider":      str,   # provider engine name
+                    "type":          str,   # "stt" | "tts"
+                    "category":      str,   # "cloud" | "local" | "native"
+                    "state":         str,   # lifecycle state
+                    "capabilities":  list,  # e.g. ["batch", "streaming"]
+                    "exec_mode":     str,   # "remote" | "local" | "in_process" | ...
+                    "exec_mode_desc": str,  # human-readable exec_mode
+                    "display_info":  dict,  # key settings (model, voice, ...)
+                }
+        """
+        from openspeech.engine_catalog import get_catalog_entry
+
+        states = self.provider_states()
+        result: list[dict] = []
+
+        for name, handle in self._handles.items():
+            provider_cls = handle.provider_cls
+            provider_type = getattr(provider_cls, "provider_type", None)
+            type_str = (
+                provider_type.value
+                if provider_type and hasattr(provider_type, "value")
+                else "unknown"
+            )
+
+            if engine_type and type_str != engine_type:
+                continue
+
+            catalog_entry = get_catalog_entry(name)
+            exec_mode_value = (
+                handle.exec_mode.value
+                if hasattr(handle.exec_mode, "value")
+                else str(handle.exec_mode)
+            )
+
+            # Capabilities from provider class
+            caps = getattr(provider_cls, "capabilities", set())
+            capabilities = sorted(
+                c.value if hasattr(c, "value") else str(c) for c in caps
+            )
+
+            # Pick display-friendly settings
+            display_info = {}
+            for key in self._DISPLAY_INFO_KEYS:
+                val = handle.settings_dict.get(key)
+                if val:
+                    display_info[key] = val
+
+            result.append({
+                "name": name,
+                "display_name": (
+                    (catalog_entry.display_name or catalog_entry.name)
+                    if catalog_entry
+                    else name
+                ),
+                "provider": getattr(provider_cls, "name", ""),
+                "type": type_str,
+                "category": catalog_entry.category if catalog_entry else "unknown",
+                "state": states.get(name, "unknown"),
+                "capabilities": capabilities,
+                "exec_mode": exec_mode_value,
+                "exec_mode_desc": _exec_mode_desc(exec_mode_value),
+                "display_info": display_info,
+            })
+
+        return result
+
+    def _get_handle(self, alias: str) -> _ProviderHandle:
+        if alias not in self._handles:
+            raise ProviderNotFoundError(alias)
+        return self._handles[alias]
+
+    # ------------------------------------------------------------------
+    # STT
+    # ------------------------------------------------------------------
+
+    async def _transcribe(
+        self,
+        provider: str,
+        audio: AudioData,
+        opts: STTOptions | None = None,
+    ) -> Transcription:
+        handle = self._get_handle(provider)
+        await self._lifecycle.ensure_ready(provider)
+        ctx = InvokeContext(
+            provider_name=provider,
+            method="transcribe",
+            exec_mode=handle.exec_mode,
+        )
+        kwargs: dict[str, Any] = {"audio": audio}
+        if opts is not None:
+            kwargs["opts"] = opts
+        with bind_context(
+            provider=provider,
+            engine=provider,
+            request_id=ctx.request_id,
+        ):
+            milestone(
+                Event.DISPATCH_INVOKE_START,
+                level="verbose",
+                method="transcribe",
+                exec_mode=handle.exec_mode.value,
+            )
+            await self._observer_mgr.notify_invoke_start(ctx)
+            with PerfTimer(
+                Event.DISPATCH_TOTAL,
+                method="transcribe",
+                exec_mode=handle.exec_mode.value,
+            ) as t:
+                try:
+                    result = await handle.executor.invoke("transcribe", **kwargs)
+                    ctx.record_end()
+                    t.add(bytes=len(getattr(audio, "data", b"") or b""))
+                    await self._observer_mgr.notify_invoke_end(ctx, result)
+                    self._lifecycle.touch(provider)
+                    milestone(
+                        Event.DISPATCH_INVOKE_END,
+                        level="verbose",
+                        method="transcribe",
+                        elapsed_ms=ctx.elapsed_ms,
+                    )
+                    return result
+                except Exception as exc:
+                    ctx.record_end()
+                    await self._observer_mgr.notify_invoke_error(ctx, exc)
+                    milestone(
+                        Event.DISPATCH_INVOKE_ERROR,
+                        method="transcribe",
+                        error_type=type(exc).__name__,
+                        error_message=str(exc),
+                    )
+                    raise
+
+    async def _transcribe_stream(
+        self,
+        provider: str,
+        stream: AsyncIterator[bytes],
+    ) -> AsyncIterator[Transcription]:
+        """Stream audio chunks to the provider and yield Transcription results."""
+        handle = self._get_handle(provider)
+        await self._lifecycle.ensure_ready(provider)
+        ctx = InvokeContext(
+            provider_name=provider,
+            method="transcribe_stream",
+            exec_mode=handle.exec_mode,
+        )
+        with bind_context(
+            provider=provider, engine=provider, request_id=ctx.request_id
+        ):
+            milestone(Event.DISPATCH_STREAM_START, method="transcribe_stream")
+            with PerfTimer(
+                Event.DISPATCH_TOTAL,
+                method="transcribe_stream",
+                exec_mode=handle.exec_mode.value,
+            ) as t:
+                count = 0
+                try:
+                    async for item in handle.executor.invoke_stream(
+                        "transcribe_stream", stream=stream
+                    ):
+                        count += 1
+                        yield item
+                finally:
+                    t.add(stream_items=count)
+            milestone(Event.DISPATCH_STREAM_END, method="transcribe_stream", items=count)
+            self._lifecycle.touch(provider)
+
+    # ------------------------------------------------------------------
+    # TTS
+    # ------------------------------------------------------------------
+
+    async def _synthesize(
+        self,
+        provider: str,
+        text: str,
+        opts: TTSOptions | None = None,
+    ) -> AudioData:
+        handle = self._get_handle(provider)
+        await self._lifecycle.ensure_ready(provider)
+        ctx = InvokeContext(
+            provider_name=provider,
+            method="synthesize",
+            exec_mode=handle.exec_mode,
+            metadata={"text": text},
+        )
+        kwargs: dict[str, Any] = {"text": text}
+        if opts is not None:
+            kwargs["opts"] = opts
+        with bind_context(
+            provider=provider, engine=provider, request_id=ctx.request_id
+        ):
+            milestone(
+                Event.DISPATCH_INVOKE_START,
+                level="verbose",
+                method="synthesize",
+                exec_mode=handle.exec_mode.value,
+                text_len=len(text),
+            )
+            await self._observer_mgr.notify_invoke_start(ctx)
+            with PerfTimer(
+                Event.DISPATCH_TOTAL,
+                method="synthesize",
+                exec_mode=handle.exec_mode.value,
+            ) as t:
+                try:
+                    result = await handle.executor.invoke("synthesize", **kwargs)
+                    ctx.record_end()
+                    t.add(audio_bytes=len(getattr(result, "data", b"") or b""))
+                    await self._observer_mgr.notify_invoke_end(ctx, result)
+                    self._lifecycle.touch(provider)
+                    milestone(
+                        Event.DISPATCH_INVOKE_END,
+                        level="verbose",
+                        method="synthesize",
+                        elapsed_ms=ctx.elapsed_ms,
+                    )
+                    return result
+                except Exception as exc:
+                    ctx.record_end()
+                    await self._observer_mgr.notify_invoke_error(ctx, exc)
+                    milestone(
+                        Event.DISPATCH_INVOKE_ERROR,
+                        method="synthesize",
+                        error_type=type(exc).__name__,
+                        error_message=str(exc),
+                    )
+                    raise
+
+    async def _synthesize_stream(
+        self,
+        provider: str,
+        text: str,
+        opts: TTSOptions | None = None,
+    ) -> AsyncIterator[Any]:
+        """Stream synthesis — yields AudioChunk objects from the provider."""
+        handle = self._get_handle(provider)
+        await self._lifecycle.ensure_ready(provider)
+        ctx = InvokeContext(
+            provider_name=provider,
+            method="synthesize_stream",
+            exec_mode=handle.exec_mode,
+            metadata={"text_len": len(text)},
+        )
+        kwargs: dict[str, Any] = {"text": text}
+        if opts is not None:
+            kwargs["opts"] = opts
+        with bind_context(
+            provider=provider, engine=provider, request_id=ctx.request_id
+        ):
+            milestone(Event.DISPATCH_STREAM_START, method="synthesize_stream", text_len=len(text))
+            with PerfTimer(
+                Event.DISPATCH_TOTAL,
+                method="synthesize_stream",
+                exec_mode=handle.exec_mode.value,
+            ) as t:
+                count = 0
+                try:
+                    async for chunk in handle.executor.invoke_stream(
+                        "synthesize_stream", **kwargs
+                    ):
+                        count += 1
+                        yield chunk
+                finally:
+                    t.add(stream_items=count)
+            milestone(Event.DISPATCH_STREAM_END, method="synthesize_stream", items=count)
+            self._lifecycle.touch(provider)
+
+    # ------------------------------------------------------------------
+    # FanOut
+    # ------------------------------------------------------------------
+
+    async def _fanout_transcribe(
+        self,
+        providers: list[str],
+        audio: AudioData,
+        opts: STTOptions | None = None,
+        strategy: MergeStrategy | None = None,
+    ) -> Any:
+        """Dispatch transcription to multiple providers concurrently."""
+        if strategy is None:
+            strategy = FirstCompleted()
+
+        tasks = {
+            alias: self._transcribe(alias, audio, opts)
+            for alias in providers
+        }
+        return await fan_out(tasks, strategy)
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    async def health(self) -> dict[str, bool]:
+        """Return health status for all configured providers."""
+        results = await asyncio.gather(
+            *[h.executor.health_check() for h in self._handles.values()],
+            return_exceptions=True,
+        )
+        return {
+            alias: (result is True)
+            for alias, result in zip(self._handles.keys(), results)
+        }
+
+    # ------------------------------------------------------------------
+    # Observer management (Chunk 5 will add notification calls)
+    # ------------------------------------------------------------------
+
+    def add_observer(self, observer: DispatchObserver) -> None:
+        """Register an observer for future lifecycle notifications."""
+        self._observer_mgr.add(observer)
+
+    def remove_observer(self, observer: DispatchObserver) -> None:
+        """Unregister an observer. No-op if the observer is not registered."""
+        try:
+            self._observer_mgr.remove(observer)
+        except ValueError:
+            pass