openspeechapi 0.1.0__py3-none-any.whl

openspeech/config.py

@@ -0,0 +1,212 @@
+"""YAML configuration loading with environment variable interpolation."""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from openspeech.exceptions import ConfigError
+
+_ENV_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+
+def interpolate_env(value: str) -> str:
+    """Interpolate ${VAR} references in a string. $$ escapes to literal $."""
+    if "$$" in value:
+        value = value.replace("$$", "\x00")
+
+    def _replace(match: re.Match) -> str:
+        var_name = match.group(1)
+        val = os.environ.get(var_name)
+        if val is None:
+            raise ConfigError(f"Environment variable '{var_name}' not set")
+        return val
+
+    result = _ENV_PATTERN.sub(_replace, value)
+    return result.replace("\x00", "$")
+
+
+def _interpolate_recursive(obj: Any) -> Any:
+    if isinstance(obj, str):
+        return interpolate_env(obj)
+    if isinstance(obj, dict):
+        return {k: _interpolate_recursive(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_interpolate_recursive(item) for item in obj]
+    return obj
+
+
+@dataclass
+class EngineConfig:
+    """Configuration for a single engine instance.
+
+    The `provider` field serves dual purpose:
+    - If it matches a key in the top-level `providers:` section, it references
+      shared credentials from that provider, and the factory key is resolved
+      from the engine catalog.
+    - If it does not match (or providers section is absent), it is treated as
+      the factory key directly (backward compatibility with old config format).
+    """
+    provider: str
+    exec_mode: str
+    settings: dict[str, Any] = field(default_factory=dict)
+    filters: list[dict[str, Any]] = field(default_factory=list)
+    endpoint: str | None = None
+    preload: bool = False
+    keepalive: int = 0
+    module: str | None = None
+    provider_class: str | None = None
+
+
+# Backward compatibility alias
+ProviderConfig = EngineConfig
+
+
+@dataclass
+class ProviderCredentials:
+    """A cloud provider's shared credentials."""
+    settings: dict[str, Any] = field(default_factory=dict)
+
+
+# Keep old name as alias
+CloudProviderConfig = ProviderCredentials
+
+
+@dataclass
+class ServerConfig:
+    host: str = "0.0.0.0"
+    port: int = 8600
+    auth_enabled: bool = False
+    api_keys: list[str] = field(default_factory=list)
+
+
+@dataclass
+class OpenSpeechConfig:
+    engines: dict[str, EngineConfig]
+    providers: dict[str, ProviderCredentials] = field(default_factory=dict)
+    server: ServerConfig = field(default_factory=ServerConfig)
+
+
+def _resolve_factory_key(alias: str, provider_ref: str) -> str:
+    """Resolve the factory key for an engine that references a provider.
+
+    Looks up the engine catalog to find the factory key from the alias.
+    Falls back to the provider_ref if catalog lookup fails.
+    """
+    try:
+        from openspeech.engine_catalog import get_catalog
+        for entry in get_catalog():
+            if entry.default_alias == alias:
+                return entry.provider
+    except Exception:
+        pass
+    # Fallback: use provider ref as factory key
+    return provider_ref
+
+
+def load_config(path: Path) -> OpenSpeechConfig:
+    """Load and validate providers.yaml configuration.
+
+    Supports both formats:
+    - New: `providers:` (shared credentials) + `engines:` (engine instances)
+    - Old: `providers:` (engine instances, no `engines:` key)
+    """
+    if not path.exists():
+        raise ConfigError(f"Config file not found: {path}")
+
+    with open(path, encoding="utf-8") as f:
+        raw = yaml.safe_load(f)
+
+    if not isinstance(raw, dict):
+        raise ConfigError("Config must be a YAML mapping")
+
+    # Detect format: if 'engines' key exists → new format
+    is_new_format = "engines" in raw
+
+    if is_new_format:
+        engines_raw = raw.get("engines") or {}
+        providers_raw = raw.get("providers") or {}
+    else:
+        # Old format: 'providers' key contains engine configs
+        engines_raw = raw.get("providers") or {}
+        providers_raw = {}
+
+    if not engines_raw:
+        raise ConfigError("Config must contain an 'engines' (or 'providers') key with entries")
+
+    raw = _interpolate_recursive(raw)
+
+    # Re-read after interpolation
+    if is_new_format:
+        engines_raw = raw.get("engines") or {}
+        providers_raw = raw.get("providers") or {}
+    else:
+        engines_raw = raw.get("providers") or {}
+        providers_raw = {}
+
+    # Parse providers section (shared credentials)
+    cred_providers: dict[str, ProviderCredentials] = {}
+    for name, spec in providers_raw.items():
+        cred_providers[name] = ProviderCredentials(settings=dict(spec))
+
+    engines: dict[str, EngineConfig] = {}
+    for alias, spec in engines_raw.items():
+        provider_value = spec.get("provider", "")
+
+        # Determine if provider references shared credentials or is a factory key
+        if is_new_format and provider_value in cred_providers:
+            # New format: provider references credential provider
+            # Resolve factory key from catalog
+            factory_key = _resolve_factory_key(alias, provider_value)
+        elif is_new_format and not provider_value:
+            # No provider field — resolve factory key from catalog by alias
+            factory_key = _resolve_factory_key(alias, "")
+        else:
+            # Old format or direct factory key
+            factory_key = provider_value
+
+        cfg = EngineConfig(
+            provider=factory_key,
+            exec_mode=spec.get("exec_mode", "remote"),
+            settings=spec.get("settings", {}),
+            filters=spec.get("filters", []),
+            endpoint=spec.get("endpoint"),
+            preload=bool(spec.get("preload", False)),
+            keepalive=int(spec.get("keepalive", 0)),
+            module=spec.get("module"),
+            provider_class=spec.get("class"),
+        )
+
+        # Merge provider credentials into engine settings
+        # Vendor credentials serve as defaults; non-empty engine settings override.
+        # Empty engine settings do NOT override valid vendor credentials.
+        if provider_value in cred_providers:
+            merged = dict(cred_providers[provider_value].settings)
+            for k, v in cfg.settings.items():
+                if k in merged and merged[k] and not v and v != 0 and v is not False:
+                    continue  # keep vendor value when engine value is empty
+                merged[k] = v
+            cfg.settings = merged
+
+        engines[alias] = cfg
+
+    # Parse optional server section
+    server_cfg = ServerConfig()
+    if "server" in raw:
+        srv = raw["server"]
+        server_cfg.host = srv.get("host", server_cfg.host)
+        server_cfg.port = srv.get("port", server_cfg.port)
+        auth = srv.get("auth", {})
+        if auth:
+            server_cfg.auth_enabled = bool(auth.get("enabled", False))
+            server_cfg.api_keys = list(auth.get("api_keys", []))
+
+    return OpenSpeechConfig(
+        engines=engines,
+        providers=cred_providers,
+        server=server_cfg,
+    )

openspeech/core/base.py

@@ -0,0 +1,75 @@
+"""Provider abstract base classes."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, STTOptions, TTSOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+
+class SpeechProvider(ABC):
+    """Base class for all speech providers."""
+
+    name: str
+    provider_type: ProviderType
+    execution_mode: ExecMode
+    settings: BaseSettings
+    settings_cls: type[BaseSettings] = BaseSettings  # Override in subclass
+    capabilities: set[Capability]
+    field_options: dict[str, list] = {}  # Dropdown choices per setting key (override in subclass)
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def health_check(self) -> bool: ...
+
+    def set_http_client(self, client: Any) -> None:
+        """Inject a shared HTTP client before ``start()`` is called.
+
+        Override in providers that use ``httpx.AsyncClient`` so they can
+        reuse a single client instance (and its SSL/transport resources)
+        instead of each creating their own.  Providers that receive a
+        shared client must **not** close it in ``stop()``.
+
+        The default implementation is a no-op — providers that don't use
+        HTTP (WebSocket-only, local inference, etc.) simply ignore it.
+        """
+
+
+class STTProvider(SpeechProvider):
+    """Base class for speech-to-text providers."""
+
+    @abstractmethod
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription: ...
+
+    @abstractmethod
+    def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]: ...
+
+
+class TTSProvider(SpeechProvider):
+    """Base class for text-to-speech providers."""
+
+    @abstractmethod
+    async def synthesize(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AudioData: ...
+
+    @abstractmethod
+    def synthesize_stream(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AsyncIterator[AudioChunk]: ...
+
+    async def list_voices(self) -> list[dict]:
+        """Return available voices. Override in subclass to provide voice list."""
+        return []

openspeech/core/enums.py

@@ -0,0 +1,39 @@
+"""Core enumerations for OpenSpeech."""
+from enum import Enum
+
+
+class ProviderType(str, Enum):
+    STT = "stt"
+    TTS = "tts"
+    BOTH = "both"
+
+
+class ExecMode(str, Enum):
+    # True in-process model execution (reserved for ultra-low-latency local models).
+    IN_PROCESS = "in_process"
+    # Local service engine (managed separately; provider talks over HTTP/HTTPS).
+    LOCAL = "local"
+    # Provider worker subprocess + IPC.
+    SUBPROCESS = "subprocess"
+    # Cloud/remote service over network API.
+    REMOTE = "remote"
+
+
+class AudioFormat(str, Enum):
+    PCM_16K = "pcm_16k"
+    PCM_44K = "pcm_44k"
+    WAV = "wav"
+    AIFF = "aiff"
+    MP3 = "mp3"
+    OGG = "ogg"
+    FLAC = "flac"
+    OPUS = "opus"
+
+
+class Capability(str, Enum):
+    STREAMING = "streaming"
+    BATCH = "batch"
+    MULTILINGUAL = "multilingual"
+    VOICE_CLONE = "voice_clone"
+    EMOTION = "emotion"
+    WORD_TIMESTAMPS = "word_timestamps"

openspeech/core/models.py

@@ -0,0 +1,61 @@
+"""Core data models — plain dataclasses for data transfer."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from openspeech.core.enums import AudioFormat
+
+
+@dataclass
+class AudioData:
+    data: bytes
+    sample_rate: int
+    channels: int
+    format: AudioFormat
+    duration_ms: int | None = None
+
+
+@dataclass
+class Word:
+    text: str
+    start_ms: int
+    end_ms: int
+    confidence: float | None = None
+
+
+@dataclass
+class Transcription:
+    text: str
+    language: str | None = None
+    confidence: float | None = None
+    words: list[Word] | None = None
+    duration_ms: int | None = None
+    is_partial: bool = False  # True for intermediate results from streaming STT
+
+
+@dataclass
+class AudioChunk:
+    data: bytes
+    sequence: int
+    is_final: bool = False
+
+
+@dataclass
+class STTOptions:
+    language: str | None = None
+    prompt: str | None = None
+    temperature: float | None = None
+    model: str | None = None
+    device: str | None = None
+    beam_size: int | None = None
+    compute_type: str | None = None
+    fp16: bool | None = None
+
+
+@dataclass
+class TTSOptions:
+    voice: str | None = None
+    speed: float = 1.0
+    output_format: AudioFormat = AudioFormat.PCM_16K
+    model: str | None = None
+    stream_transport: str | None = None

openspeech/core/registry.py

@@ -0,0 +1,37 @@
+"""Provider registry — lookup by name, type, or capability."""
+from __future__ import annotations
+
+from typing import Any
+
+from openspeech.core.enums import Capability, ProviderType
+from openspeech.exceptions import ProviderNotFoundError
+
+
+class ProviderRegistry:
+    """Registry for provider classes. Lookup by name, type, or capability."""
+
+    def __init__(self) -> None:
+        self._providers: dict[str, Any] = {}
+
+    def register(self, name: str, provider_cls: Any) -> None:
+        self._providers[name] = provider_cls
+
+    def get(self, name: str) -> Any:
+        if name not in self._providers:
+            raise ProviderNotFoundError(name)
+        return self._providers[name]
+
+    def find_by_type(self, provider_type: ProviderType) -> list[tuple[str, Any]]:
+        return [
+            (name, cls) for name, cls in self._providers.items()
+            if getattr(cls, "provider_type", None) == provider_type
+        ]
+
+    def find_by_capability(self, capability: Capability) -> list[tuple[str, Any]]:
+        return [
+            (name, cls) for name, cls in self._providers.items()
+            if capability in getattr(cls, "capabilities", set())
+        ]
+
+    def list_all(self) -> list[tuple[str, Any]]:
+        return list(self._providers.items())

openspeech/core/settings.py

@@ -0,0 +1,8 @@
+"""Base settings for provider configuration."""
+from dataclasses import dataclass
+
+
+@dataclass
+class BaseSettings:
+    """Base class for provider-specific settings. Subclass as a dataclass."""
+    pass