openspeechapi 0.1.0__py3-none-any.whl

openspeech/dispatch/fanout.py

@@ -0,0 +1,95 @@
+"""FanOut/FanIn — concurrent dispatch to multiple providers with merge strategies."""
+from __future__ import annotations
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+from openspeech.exceptions import FanOutAllFailedError
+
+
+@dataclass
+class FanOutResult:
+    successes: dict[str, Any] = field(default_factory=dict)
+    errors: dict[str, Exception] = field(default_factory=dict)
+
+
+class MergeStrategy(ABC):
+    @abstractmethod
+    async def merge(self, results: dict[str, Any | Exception]) -> Any: ...
+
+
+class FirstCompleted(MergeStrategy):
+    async def merge(self, results: dict[str, Any | Exception]) -> Any:
+        successes = {k: v for k, v in results.items() if not isinstance(v, Exception)}
+        if not successes:
+            errors = {k: v for k, v in results.items() if isinstance(v, Exception)}
+            raise FanOutAllFailedError(errors)
+        return next(iter(successes.values()))
+
+
+class HighestConfidence(MergeStrategy):
+    async def merge(self, results: dict[str, Any | Exception]) -> Any:
+        successes = {k: v for k, v in results.items() if not isinstance(v, Exception)}
+        if not successes:
+            errors = {k: v for k, v in results.items() if isinstance(v, Exception)}
+            raise FanOutAllFailedError(errors)
+        return max(successes.values(), key=lambda r: getattr(r, "confidence", 0) or 0)
+
+
+class CollectAll(MergeStrategy):
+    async def merge(self, results: dict[str, Any | Exception]) -> FanOutResult:
+        fan_result = FanOutResult()
+        for k, v in results.items():
+            if isinstance(v, Exception):
+                fan_result.errors[k] = v
+            else:
+                fan_result.successes[k] = v
+        return fan_result
+
+
+class CustomMerge(MergeStrategy):
+    def __init__(self, fn: Callable[[dict[str, Any | Exception]], Awaitable[Any]]) -> None:
+        self._fn = fn
+
+    async def merge(self, results: dict[str, Any | Exception]) -> Any:
+        return await self._fn(results)
+
+
+async def fan_out(tasks: dict[str, Awaitable[Any]], strategy: MergeStrategy) -> Any:
+    if isinstance(strategy, FirstCompleted):
+        return await _fan_out_first_completed(tasks, strategy)
+
+    results: dict[str, Any | Exception] = {}
+
+    async def _run(name: str, coro: Awaitable[Any]) -> None:
+        try:
+            results[name] = await coro
+        except Exception as e:
+            results[name] = e
+
+    await asyncio.gather(*[_run(name, coro) for name, coro in tasks.items()])
+    return await strategy.merge(results)
+
+
+async def _fan_out_first_completed(tasks: dict[str, Awaitable[Any]], strategy: FirstCompleted) -> Any:
+    results: dict[str, Any | Exception] = {}
+    done_event = asyncio.Event()
+
+    async def _run(name: str, coro: Awaitable[Any]) -> None:
+        try:
+            result = await coro
+            results[name] = result
+            done_event.set()
+        except Exception as e:
+            results[name] = e
+            if len(results) == len(tasks):
+                done_event.set()
+
+    async_tasks = [asyncio.create_task(_run(name, coro)) for name, coro in tasks.items()]
+    await done_event.wait()
+    for t in async_tasks:
+        if not t.done():
+            t.cancel()
+    await asyncio.gather(*async_tasks, return_exceptions=True)
+    return await strategy.merge(results)

openspeech/dispatch/filters.py

@@ -0,0 +1,73 @@
+"""Result filter chain — post-processing filters applied to provider results."""
+from __future__ import annotations
+from abc import ABC
+from typing import Any, Generic, TypeVar
+from openspeech.core.enums import AudioFormat
+from openspeech.core.models import AudioData
+
+T = TypeVar("T")
+
+
+class ResultFilter(ABC, Generic[T]):
+    def should_pass(self, result: T) -> bool:
+        return True
+
+    def transform(self, result: T) -> T:
+        return result
+
+
+class ConfidenceFilter(ResultFilter):
+    def __init__(self, min_confidence: float = 0.8) -> None:
+        self._min = min_confidence
+
+    def should_pass(self, result: Any) -> bool:
+        confidence = getattr(result, "confidence", None)
+        if confidence is None:
+            return True
+        return confidence >= self._min
+
+
+class LanguageFilter(ResultFilter):
+    def __init__(self, allow: list[str]) -> None:
+        self._allow = set(allow)
+
+    def should_pass(self, result: Any) -> bool:
+        language = getattr(result, "language", None)
+        if language is None:
+            return True
+        return language in self._allow
+
+
+class DurationFilter(ResultFilter):
+    def __init__(self, min_ms: int = 100) -> None:
+        self._min_ms = min_ms
+
+    def should_pass(self, result: Any) -> bool:
+        duration = getattr(result, "duration_ms", None)
+        if duration is None:
+            return True
+        return duration >= self._min_ms
+
+
+class AudioFormatFilter(ResultFilter):
+    def __init__(self, target: AudioFormat = AudioFormat.PCM_16K) -> None:
+        self._target = target
+
+    def transform(self, result: Any) -> Any:
+        if isinstance(result, AudioData) and result.format != self._target:
+            return AudioData(data=result.data, sample_rate=result.sample_rate,
+                             channels=result.channels, format=self._target,
+                             duration_ms=result.duration_ms)
+        return result
+
+
+class FilterChain:
+    def __init__(self, filters: list[ResultFilter]) -> None:
+        self._filters = filters
+
+    def apply(self, result: Any) -> Any | None:
+        for f in self._filters:
+            if not f.should_pass(result):
+                return None
+            result = f.transform(result)
+        return result

openspeech/dispatch/lifecycle.py

@@ -0,0 +1,178 @@
+"""Provider lifecycle management — lazy start, TTL-based auto-stop."""
+from __future__ import annotations
+
+import asyncio
+import time
+from enum import Enum
+from typing import Any
+
+from openspeech.logging_config import logger
+
+from openspeech.logging_config import bind_context
+from openspeech.telemetry.perf import Event, PerfTimer, milestone
+
+
+class ProviderState(str, Enum):
+    REGISTERED = "registered"
+    STARTING = "starting"
+    READY = "ready"
+    STOPPED = "stopped"
+
+
+class _ProviderEntry:
+    def __init__(self, name: str, handle: Any, keepalive: int) -> None:
+        self.name = name
+        self.handle = handle
+        self.keepalive = keepalive
+        self.state = ProviderState.REGISTERED
+        self.last_used: float = 0.0
+        self._lock = asyncio.Lock()
+
+
+class ProviderLifecycleManager:
+    """Manages per-provider state, lazy start, and TTL-based auto-stop."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, _ProviderEntry] = {}
+        self._checker_task: asyncio.Task | None = None
+        self._check_interval: float = 30.0
+        self._shared_http_client: Any = None
+
+    def set_shared_http_client(self, client: Any) -> None:
+        """Store a shared httpx.AsyncClient for injection into providers."""
+        self._shared_http_client = client
+
+    def register(self, name: str, handle: Any, keepalive: int = 0) -> None:
+        self._entries[name] = _ProviderEntry(name, handle, keepalive)
+
+    def unregister(self, name: str) -> None:
+        self._entries.pop(name, None)
+
+    def get_state(self, name: str) -> ProviderState | None:
+        entry = self._entries.get(name)
+        return entry.state if entry else None
+
+    def list_states(self) -> dict[str, str]:
+        return {name: entry.state.value for name, entry in self._entries.items()}
+
+    async def ensure_ready(self, name: str) -> None:
+        """Ensure provider is READY. Starts it if needed. Thread-safe."""
+        entry = self._entries.get(name)
+        if entry is None:
+            from openspeech.exceptions import ProviderNotFoundError
+            raise ProviderNotFoundError(name)
+
+        if entry.state == ProviderState.READY:
+            entry.last_used = time.monotonic()
+            return
+
+        async with entry._lock:
+            # Double-check after acquiring lock
+            if entry.state == ProviderState.READY:
+                entry.last_used = time.monotonic()
+                return
+
+            with bind_context(provider=name, engine=name):
+                logger.info("lazy-starting provider '{}'", name)
+                entry.state = ProviderState.STARTING
+                try:
+                    import dataclasses
+                    from openspeech.core.settings import BaseSettings
+                    handle = entry.handle
+                    settings_cls = getattr(handle.provider_cls, "settings_cls", BaseSettings)
+                    # Filter settings to only include fields the class accepts
+                    valid_fields = {f.name for f in dataclasses.fields(settings_cls)}
+                    filtered = {k: v for k, v in handle.settings_dict.items() if k in valid_fields}
+                    settings = settings_cls(**filtered)
+                    with PerfTimer(
+                        Event.LIFECYCLE_PROVIDER_INIT,
+                        exec_mode=handle.exec_mode.value,
+                    ):
+                        await handle.executor.start(
+                            handle.provider_cls, settings,
+                            http_client=self._shared_http_client,
+                        )
+                    entry.state = ProviderState.READY
+                    entry.last_used = time.monotonic()
+                    milestone(
+                        Event.LIFECYCLE_PROVIDER_READY,
+                        exec_mode=handle.exec_mode.value,
+                    )
+                    logger.info("provider '{}' ready", name)
+                except Exception as e:
+                    entry.state = ProviderState.STOPPED
+                    milestone(
+                        Event.PROVIDER_ERROR,
+                        phase="init",
+                        error_type=type(e).__name__,
+                        error_message=str(e),
+                    )
+                    logger.error("failed to start provider '{}': {}", name, e)
+                    raise
+
+    def get_instance(self, name: str) -> Any | None:
+        """Return the running provider instance, or None."""
+        entry = self._entries.get(name)
+        if entry is None or entry.state != ProviderState.READY:
+            return None
+        executor = entry.handle.executor
+        return getattr(executor, "_provider", None)
+
+    def touch(self, name: str) -> None:
+        """Reset idle timer for a provider."""
+        entry = self._entries.get(name)
+        if entry:
+            entry.last_used = time.monotonic()
+
+    async def stop_provider(self, name: str, *, reason: str = "manual") -> None:
+        """Stop a single provider."""
+        entry = self._entries.get(name)
+        if entry is None or entry.state not in (ProviderState.READY, ProviderState.STARTING):
+            return
+        with bind_context(provider=name, engine=name):
+            try:
+                with PerfTimer(Event.LIFECYCLE_PROVIDER_STOP, reason=reason):
+                    await entry.handle.executor.stop()
+                entry.state = ProviderState.STOPPED
+                logger.info("provider '{}' stopped (reason={})", name, reason)
+            except Exception as e:
+                logger.warning("error stopping provider '{}': {}", name, e)
+                entry.state = ProviderState.STOPPED
+
+    async def stop_all(self) -> None:
+        """Stop all running providers and the idle checker."""
+        if self._checker_task:
+            self._checker_task.cancel()
+            try:
+                await self._checker_task
+            except asyncio.CancelledError:
+                pass
+            self._checker_task = None
+
+        for name, entry in self._entries.items():
+            if entry.state == ProviderState.READY:
+                await self.stop_provider(name)
+
+    def start_idle_checker(self) -> None:
+        """Start background task that stops idle providers."""
+        if self._checker_task is None or self._checker_task.done():
+            self._checker_task = asyncio.create_task(self._idle_check_loop())
+
+    async def _idle_check_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._check_interval)
+            now = time.monotonic()
+            for name, entry in list(self._entries.items()):
+                if (entry.state == ProviderState.READY
+                        and entry.keepalive > 0
+                        and entry.last_used > 0
+                        and (now - entry.last_used) > entry.keepalive):
+                    idle_s = now - entry.last_used
+                    milestone(
+                        Event.LIFECYCLE_IDLE_RECYCLE,
+                        provider=name,
+                        engine=name,
+                        idle_seconds=round(idle_s, 2),
+                        keepalive=entry.keepalive,
+                    )
+                    await self.stop_provider(name, reason="idle_ttl")

openspeech/dispatch/watcher.py

@@ -0,0 +1,82 @@
+"""Config file watcher for hot-reload."""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from openspeech.logging_config import logger
+
+
+class ConfigWatcher:
+    """Watches providers.yaml and .env for changes, triggers reload callback."""
+
+    def __init__(
+        self,
+        config_path: Path,
+        on_reload: Callable[[], Awaitable[dict[str, list[str]]]],
+        debounce_s: float = 1.0,
+    ) -> None:
+        self._config_path = config_path
+        self._env_path = config_path.parent / ".env"
+        self._on_reload = on_reload
+        self._debounce_s = debounce_s
+        self._task: asyncio.Task | None = None
+        self._last_config_mtime: float = 0.0
+        self._last_env_mtime: float = 0.0
+        self._poll_interval: float = 2.0  # poll every 2 seconds
+
+    def start(self) -> None:
+        """Start watching in background."""
+        self._last_config_mtime = self._get_mtime(self._config_path)
+        self._last_env_mtime = self._get_mtime(self._env_path)
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(self._watch_loop())
+            logger.info(f"Config watcher started: {self._config_path}")
+
+    async def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+
+    @staticmethod
+    def _get_mtime(path: Path) -> float:
+        try:
+            return path.stat().st_mtime
+        except FileNotFoundError:
+            return 0.0
+
+    async def _watch_loop(self) -> None:
+        """Poll for file changes and trigger reload."""
+        while True:
+            await asyncio.sleep(self._poll_interval)
+            changed = False
+
+            config_mtime = self._get_mtime(self._config_path)
+            if config_mtime > self._last_config_mtime:
+                self._last_config_mtime = config_mtime
+                changed = True
+
+            env_mtime = self._get_mtime(self._env_path)
+            if env_mtime > self._last_env_mtime:
+                self._last_env_mtime = env_mtime
+                # Re-load .env into os.environ
+                try:
+                    from dotenv import load_dotenv
+                    load_dotenv(self._env_path, override=True)
+                except ImportError:
+                    pass
+                changed = True
+
+            if changed:
+                # Debounce: wait a bit to coalesce rapid saves
+                await asyncio.sleep(self._debounce_s)
+                try:
+                    result = await self._on_reload()
+                    logger.info(f"Config reloaded: {result}")
+                except Exception as e:
+                    logger.error(f"Config reload failed: {e}")

openspeech/engine_catalog.py

@@ -0,0 +1,236 @@
+"""Unified engine catalog — loads engine list from registry YAML,
+enriches with runtime metadata (default_settings, field_options) from provider code.
+
+Only "installed" engines appear in providers.yaml and are visible on Dashboard/Config/Lab.
+"""
+from __future__ import annotations
+
+import dataclasses
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class CatalogEntry:
+    """A single engine entry in the catalog."""
+    name: str                   # Unique engine ID, e.g. "openai-stt", "fish-speech"
+    provider: str               # factory _PROVIDER_MAP key
+    type: str                   # "stt" | "tts"
+    category: str               # "cloud" | "local" | "native"
+    description: str            # Human-readable description
+    default_alias: str          # Default alias in config
+    display_name: str = ""      # Human-friendly display name, e.g. "iFlytek STT"
+    vendor: str = ""            # Vendor key from vendor_registry.yaml (cloud engines only)
+    default_settings: dict = field(default_factory=dict)
+    default_exec_mode: str = "remote"
+    pip_deps: list[str] = field(default_factory=list)
+    pip_extras: list[str] = field(default_factory=list)   # pyproject.toml extras names
+    field_options: dict[str, list] = field(default_factory=dict)
+    platforms: list[str] = field(default_factory=list)     # empty = all platforms
+
+    @property
+    def compatible(self) -> bool:
+        """Whether this engine is compatible with the current platform."""
+        return not self.platforms or sys.platform in self.platforms
+
+
+# ---------------------------------------------------------------------------
+# Registry loading
+# ---------------------------------------------------------------------------
+
+_REGISTRY_PATH = Path(__file__).parent / "engine_registry.yaml"
+_VENDOR_REGISTRY_PATH = Path(__file__).parent / "vendor_registry.yaml"
+
+
+def _load_registry(path: Path | None = None) -> list[dict]:
+    """Load engine list from registry YAML file."""
+    path = path or _REGISTRY_PATH
+    if not path.exists():
+        return []
+    with open(path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return raw.get("engines", [])
+
+
+def _load_vendor_registry(path: Path | None = None) -> dict:
+    """Load vendor registry from YAML file."""
+    path = path or _VENDOR_REGISTRY_PATH
+    if not path.exists():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return raw.get("vendors", {})
+
+
+def get_vendor_registry() -> dict:
+    """Get vendor templates for provider credential fields."""
+    return _load_vendor_registry()
+
+
+def _enrich_from_provider(entry: CatalogEntry) -> CatalogEntry:
+    """Enrich a catalog entry with default_settings and field_options from provider code."""
+    try:
+        from openspeech.factory import _resolve
+        provider_cls, settings_cls = _resolve(entry.provider)
+
+        # Extract default_settings from settings dataclass defaults
+        if dataclasses.is_dataclass(settings_cls):
+            defaults = {}
+            for f in dataclasses.fields(settings_cls):
+                if f.default is not dataclasses.MISSING:
+                    defaults[f.name] = f.default
+                elif f.default_factory is not dataclasses.MISSING:
+                    defaults[f.name] = f.default_factory()
+
+            # Filter out vendor shared fields (e.g. api_key, api_secret)
+            # — these are inherited from vendor credentials, not engine settings
+            if entry.vendor:
+                vendor_registry = _load_vendor_registry()
+                vendor_tpl = vendor_registry.get(entry.vendor, {})
+                shared_keys = set(vendor_tpl.get("shared_fields", {}).keys())
+                defaults = {k: v for k, v in defaults.items() if k not in shared_keys}
+
+            entry.default_settings = defaults
+
+        # Extract field_options from provider class attribute
+        fo = getattr(provider_cls, "field_options", None)
+        if fo:
+            entry.field_options = dict(fo)
+
+        # Extract pip_deps from provider class if available
+        pd = getattr(provider_cls, "pip_deps", None)
+        if pd:
+            entry.pip_deps = list(pd)
+
+    except Exception:
+        pass  # Provider not importable (missing deps) — keep registry defaults
+
+    return entry
+
+
+def build_catalog(registry_path: Path | None = None) -> list[CatalogEntry]:
+    """Build the full engine catalog from registry YAML + provider metadata."""
+    raw_entries = _load_registry(registry_path)
+    entries: list[CatalogEntry] = []
+
+    for raw in raw_entries:
+        entry = CatalogEntry(
+            name=raw["name"],
+            provider=raw["provider"],
+            type=raw["type"],
+            category=raw.get("category", "cloud"),
+            description=raw.get("description", ""),
+            default_alias=raw.get("default_alias", raw["name"].replace("-", "_")),
+            display_name=raw.get("display_name", ""),
+            vendor=raw.get("vendor", ""),
+            default_exec_mode=raw.get("default_exec_mode", "remote"),
+            pip_extras=raw.get("pip_extras", []),
+            platforms=raw.get("platforms", []),
+        )
+        # Try to enrich with provider code metadata
+        entry = _enrich_from_provider(entry)
+        entries.append(entry)
+
+    return entries
+
+
+# ---------------------------------------------------------------------------
+# Singleton & helpers
+# ---------------------------------------------------------------------------
+
+_catalog: list[CatalogEntry] | None = None
+
+
+def get_catalog() -> list[CatalogEntry]:
+    """Get the singleton catalog."""
+    global _catalog
+    if _catalog is None:
+        _catalog = build_catalog()
+    return _catalog
+
+
+def get_catalog_entry(name: str) -> CatalogEntry | None:
+    """Look up a catalog entry by name or default_alias.
+
+    For native meta-aliases (native_stt / native_tts), returns the
+    platform-specific entry (e.g. windows-stt on win32).
+    """
+    from openspeech.factory import _NATIVE_ALIASES
+
+    # Check if this is a native meta-alias (by name or default_alias)
+    for meta_name, platform_map in _NATIVE_ALIASES.items():
+        meta_alias = meta_name.replace("-", "_")
+        if name in (meta_name, meta_alias):
+            concrete = platform_map.get(sys.platform)
+            if concrete:
+                for e in get_catalog():
+                    if e.provider == concrete:
+                        return e
+            return None
+
+    for e in get_catalog():
+        if e.name == name or e.default_alias == name:
+            return e
+    return None
+
+
+def get_installed_engines(config_path: Path) -> set[str]:
+    """Return set of catalog engine names that are installed (present in config).
+
+    Native meta-aliases (native_stt/native_tts) are resolved to platform-specific
+    catalog entries (e.g. windows-stt on win32).
+    """
+    if not config_path.exists():
+        return set()
+    with open(config_path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+
+    # Support both new format (engines:) and old format (providers:)
+    engines_raw = raw.get("engines") or {}
+    if not engines_raw:
+        engines_raw = raw.get("providers") or {}
+
+    # Build reverse map: provider key → catalog name
+    installed = set()
+    catalog = get_catalog()
+    provider_to_catalog = {e.provider: e.name for e in catalog}
+
+    # Also build alias → catalog name map
+    alias_to_catalog = {e.default_alias: e.name for e in catalog}
+
+    # Load providers section for credential provider resolution
+    providers_section = raw.get("providers") or {}
+    is_new_format = "engines" in raw
+
+    for alias, spec in engines_raw.items():
+        if not isinstance(spec, dict):
+            continue
+        # Skip credential provider entries (no exec_mode)
+        if "exec_mode" not in spec and "provider" not in spec:
+            continue
+
+        # Resolve via get_catalog_entry (handles native meta-aliases)
+        resolved = get_catalog_entry(alias)
+        if resolved:
+            installed.add(resolved.name)
+            continue
+
+        provider_val = spec.get("provider", "")
+
+        # In new format, provider might reference credential provider
+        if is_new_format and provider_val in providers_section:
+            # Try to resolve via catalog
+            for e in catalog:
+                if e.vendor == provider_val and e.default_alias == alias:
+                    installed.add(e.name)
+                    break
+        else:
+            # Direct factory key
+            if provider_val in provider_to_catalog:
+                installed.add(provider_to_catalog[provider_val])
+
+    return installed