openvoiceui 1.0.0

package/providers/llm/clawdbot_provider.py

@@ -0,0 +1,112 @@
+"""
+Clawdbot Gateway WebSocket LLM provider.
+
+Ref: future-dev-plans/02-PROVIDER-SYSTEMS.md (ClawdbotProvider section)
+Routes messages through the Clawdbot Gateway WebSocket for full agent context.
+"""
+
+import json
+import os
+import time
+from typing import Any, Dict, Iterator, List, Optional
+
+from providers.llm.base import LLMError, LLMProvider, LLMResponse
+from providers.registry import ProviderType, registry
+
+
+class ClawdbotProvider(LLMProvider):
+    """Clawdbot Gateway WebSocket provider."""
+
+    def __init__(self, config: Dict[str, Any] = None) -> None:
+        super().__init__(config)
+        self.gateway_url = (
+            self._config.get("gateway_url")
+            or os.getenv("CLAWDBOT_GATEWAY_URL", "ws://127.0.0.1:18791")
+        )
+        self.auth_token = (
+            self._config.get("auth_token")
+            or os.getenv("CLAWDBOT_AUTH_TOKEN", "")
+        )
+        self.default_agent = self._config.get("default_agent", "main")
+        self.default_model = "glm-4-7-flash"  # Gateway uses Z.AI/GLM
+
+    def generate(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: Optional[str] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        try:
+            import websocket  # type: ignore
+        except ImportError:
+            raise LLMError("clawdbot", "websocket-client library not installed")
+
+        # Extract last user message
+        user_message = ""
+        for msg in reversed(messages):
+            if msg.get("role") == "user":
+                user_message = msg.get("content", "")
+                break
+
+        start = time.time()
+        try:
+            ws = websocket.create_connection(self.gateway_url, timeout=10)
+            try:
+                # Handshake
+                ws.send(json.dumps({"type": "connect.challenge", "token": self.auth_token}))
+                challenge = json.loads(ws.recv())
+                ws.send(json.dumps({"type": "connect", "response": challenge.get("challenge", "")}))
+                ws.recv()  # hello frame
+
+                # Send message
+                agent = kwargs.get("agent", self.default_agent)
+                ws.send(json.dumps({"type": "chat.send", "content": user_message, "agent": agent}))
+
+                # Collect response
+                content = ""
+                while True:
+                    raw = json.loads(ws.recv())
+                    if raw.get("type") == "chat.response":
+                        content += raw.get("content", "")
+                    elif raw.get("type") in ("chat.done", "chat.final"):
+                        if not content:
+                            content = raw.get("content", "")
+                        break
+            finally:
+                ws.close()
+        except Exception as exc:
+            raise LLMError("clawdbot", f"Gateway error: {exc}") from exc
+
+        latency_ms = (time.time() - start) * 1000
+        return LLMResponse(
+            content=content,
+            model=self.default_model,
+            provider="clawdbot",
+            usage={},
+            latency_ms=latency_ms,
+        )
+
+    def generate_stream(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: Optional[str] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> Iterator[str]:
+        # Full streaming would require a persistent connection (PG-T2)
+        response = self.generate(messages, system_prompt, model, **kwargs)
+        yield response.content
+
+    def is_available(self) -> bool:
+        return bool(self.auth_token)
+
+    def get_info(self) -> Dict[str, Any]:
+        info = super().get_info()
+        info["name"] = self._config.get("name", "Clawdbot Gateway")
+        info["gateway_url"] = self.gateway_url
+        return info
+
+
+# Auto-register when this module is imported
+registry.register(ProviderType.LLM, "clawdbot", ClawdbotProvider)

package/providers/llm/zai_provider.py

@@ -0,0 +1,115 @@
+"""
+Z.AI GLM-4 LLM provider.
+
+Ref: future-dev-plans/02-PROVIDER-SYSTEMS.md (ZAIProvider section)
+IMPORTANT: This is the primary LLM backend for clawdbot (ADR — NEVER switch clawdbot to Anthropic).
+"""
+
+import os
+import time
+from typing import Any, Dict, Iterator, List, Optional
+
+from providers.llm.base import LLMError, LLMProvider, LLMResponse
+from providers.registry import ProviderType, registry
+
+
+class ZAIProvider(LLMProvider):
+    """Z.AI GLM-4 provider via REST API."""
+
+    API_URL = "https://api.zukijourney.com/v1/chat/completions"
+
+    def __init__(self, config: Dict[str, Any] = None) -> None:
+        super().__init__(config)
+        self.api_key = self._resolve_api_key()
+        self.default_model = self._config.get("default_model", "glm-4-7-flash")
+
+    def _resolve_api_key(self) -> str:
+        key = self._config.get("api_key", "")
+        # Skip unresolved placeholder
+        if key and not key.startswith("${"):
+            return key
+        return os.getenv("ZAI_API_KEY", "")
+
+    def generate(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: Optional[str] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> LLMResponse:
+        try:
+            import requests  # type: ignore
+        except ImportError:
+            raise LLMError("zai", "requests library not installed")
+
+        model = model or self.default_model
+        max_tokens = kwargs.get("max_tokens", 512)
+        timeout = kwargs.get("timeout", 30)
+
+        # Temperature and penalty settings for natural conversation
+        temperature = kwargs.get("temperature", 0.7)
+        frequency_penalty = kwargs.get("frequency_penalty", 0.5)
+        presence_penalty = kwargs.get("presence_penalty", 0.3)
+
+        full_messages: List[Dict[str, str]] = []
+        if system_prompt:
+            full_messages.append({"role": "system", "content": system_prompt})
+        full_messages.extend(messages)
+
+        start = time.time()
+        try:
+            resp = requests.post(
+                self.API_URL,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": model,
+                    "messages": full_messages,
+                    "max_tokens": max_tokens,
+                    "temperature": temperature,
+                    "frequency_penalty": frequency_penalty,
+                    "presence_penalty": presence_penalty,
+                },
+                timeout=timeout,
+            )
+            resp.raise_for_status()
+        except Exception as exc:
+            raise LLMError("zai", f"API request failed: {exc}") from exc
+
+        data = resp.json()
+        latency_ms = (time.time() - start) * 1000
+
+        return LLMResponse(
+            content=data["choices"][0]["message"]["content"],
+            model=model,
+            provider="zai",
+            usage=data.get("usage", {}),
+            latency_ms=latency_ms,
+            finish_reason=data["choices"][0].get("finish_reason", "stop"),
+            raw_response=data,
+        )
+
+    def generate_stream(
+        self,
+        messages: List[Dict[str, str]],
+        system_prompt: Optional[str] = None,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> Iterator[str]:
+        # Z.AI REST API does not support streaming — fall back to non-streaming
+        response = self.generate(messages, system_prompt, model, **kwargs)
+        yield response.content
+
+    def is_available(self) -> bool:
+        return bool(self.api_key)
+
+    def get_info(self) -> Dict[str, Any]:
+        info = super().get_info()
+        info["name"] = self._config.get("name", "Z.AI GLM")
+        return info
+
+
+# Auto-register when this module is imported
+registry.register(ProviderType.LLM, "zai", ZAIProvider)

package/providers/registry.py

@@ -0,0 +1,320 @@
+"""
+Provider registry with singleton pattern and auto-discovery.
+
+P5-T2: Provider registry + auto-discovery
+ADR-003: Abstract base class + registry pattern
+Ref: future-dev-plans/02-PROVIDER-SYSTEMS.md (PluginRegistry section)
+
+Usage:
+    from providers.registry import registry, ProviderType
+
+    # Register a provider
+    registry.register(ProviderType.TTS, 'supertonic', SupertonicProvider)
+
+    # Get a provider instance
+    tts = registry.get_provider(ProviderType.TTS)          # default
+    tts = registry.get_provider(ProviderType.TTS, 'groq')  # specific
+
+    # List available providers
+    providers = registry.list_providers(ProviderType.TTS)
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Type
+
+logger = logging.getLogger(__name__)
+
+
+class ProviderType(Enum):
+    LLM = "llm"
+    TTS = "tts"
+    STT = "stt"
+
+
+class ProviderRegistry:
+    """Singleton registry for all provider types (LLM, TTS, STT).
+
+    Providers are registered with a unique string ID per type.
+    get_provider() returns an instantiated provider with config merged from
+    the providers YAML (if loaded) and any explicit config passed at
+    register() time.
+    """
+
+    _instance: Optional["ProviderRegistry"] = None
+
+    def __init__(self) -> None:
+        self._providers: Dict[ProviderType, Dict[str, Type]] = {
+            ProviderType.LLM: {},
+            ProviderType.TTS: {},
+            ProviderType.STT: {},
+        }
+        # Static config passed at register() time
+        self._static_configs: Dict[str, Dict] = {}
+        # YAML config loaded lazily
+        self._yaml_config: Optional[Dict] = None
+
+    # ------------------------------------------------------------------
+    # Singleton
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def get_instance(cls) -> "ProviderRegistry":
+        if cls._instance is None:
+            cls._instance = ProviderRegistry()
+        return cls._instance
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        provider_type: ProviderType,
+        provider_id: str,
+        provider_class: Type,
+        config: Optional[Dict] = None,
+    ) -> None:
+        """Register a provider implementation.
+
+        Args:
+            provider_type: LLM, TTS, or STT.
+            provider_id:   Unique string key (e.g. 'supertonic', 'zai').
+            provider_class: Class (not instance) implementing the base type.
+            config:         Optional static config dict merged with YAML config.
+        """
+        self._providers[provider_type][provider_id] = provider_class
+        if config:
+            self._static_configs[provider_id] = config
+        logger.debug("Registered %s provider: %s", provider_type.value, provider_id)
+
+    # ------------------------------------------------------------------
+    # Retrieval
+    # ------------------------------------------------------------------
+
+    def get_provider(
+        self,
+        provider_type: ProviderType,
+        provider_id: Optional[str] = None,
+    ) -> Any:
+        """Return an instantiated provider.
+
+        If provider_id is None, the default is read from providers YAML
+        (<type>.default_provider) or falls back to the first registered
+        provider for that type.
+
+        Config is merged: static config (register-time) is the base,
+        YAML config overrides it.
+
+        Raises:
+            ValueError: if the provider_id is not registered.
+        """
+        if provider_id is None:
+            provider_id = self._get_default_id(provider_type)
+
+        if provider_id not in self._providers[provider_type]:
+            available = list(self._providers[provider_type].keys())
+            raise ValueError(
+                f"Unknown {provider_type.value} provider: '{provider_id}'. "
+                f"Available: {available}"
+            )
+
+        provider_class = self._providers[provider_type][provider_id]
+        merged_config = self._build_config(provider_type, provider_id)
+
+        return provider_class(merged_config)
+
+    def list_providers(
+        self,
+        provider_type: ProviderType,
+        include_unavailable: bool = False,
+    ) -> List[Dict]:
+        """Return a sorted list of provider metadata dicts.
+
+        Each dict has keys: id, name, available, priority, info.
+        Sorted ascending by priority (lower number = higher priority).
+        """
+        results = []
+        for pid, provider_class in self._providers[provider_type].items():
+            config = self._build_config(provider_type, pid)
+            try:
+                instance = provider_class(config)
+                available = instance.is_available()
+                info = instance.get_info()
+            except Exception as exc:
+                logger.warning("Error probing provider %s: %s", pid, exc)
+                available = False
+                info = {"name": pid, "status": "error"}
+
+            if include_unavailable or available:
+                results.append(
+                    {
+                        "id": pid,
+                        "name": info.get("name", pid),
+                        "available": available,
+                        "priority": config.get("priority", 100),
+                        "info": info,
+                    }
+                )
+
+        return sorted(results, key=lambda p: p["priority"])
+
+    # ------------------------------------------------------------------
+    # Auto-discovery
+    # ------------------------------------------------------------------
+
+    def autodiscover(self, providers_yaml_path: Optional[str] = None) -> None:
+        """Load providers.yaml and import/register configured providers.
+
+        This is the auto-discovery mechanism: the YAML file declares which
+        provider modules to load, and this method imports them so their
+        __init__.py register() calls fire automatically.
+
+        If providers_yaml_path is None, defaults to config/providers.yaml
+        relative to the project root (detected from this file's location).
+        """
+        if providers_yaml_path is None:
+            providers_yaml_path = self._default_yaml_path()
+
+        try:
+            import yaml  # type: ignore
+        except ImportError:
+            logger.warning("PyYAML not installed — skipping autodiscover")
+            return
+
+        path = Path(providers_yaml_path)
+        if not path.exists():
+            logger.debug("providers.yaml not found at %s — skipping autodiscover", path)
+            return
+
+        with open(path) as f:
+            self._yaml_config = yaml.safe_load(f) or {}
+
+        logger.info("Loaded providers config from %s", path)
+
+        # Import each provider sub-package so their register() calls fire.
+        # The 'modules' key in each provider type section lists module paths.
+        for ptype_str in ("llm", "tts", "stt"):
+            section = self._yaml_config.get(ptype_str, {})
+            for module_path in section.get("modules", []):
+                try:
+                    importlib.import_module(module_path)
+                    logger.debug("Auto-imported provider module: %s", module_path)
+                except ImportError as exc:
+                    logger.warning("Could not import provider module %s: %s", module_path, exc)
+
+    # ------------------------------------------------------------------
+    # Introspection helpers
+    # ------------------------------------------------------------------
+
+    def registered_ids(self, provider_type: ProviderType) -> List[str]:
+        """Return list of registered provider IDs for a type."""
+        return list(self._providers[provider_type].keys())
+
+    def is_registered(self, provider_type: ProviderType, provider_id: str) -> bool:
+        return provider_id in self._providers[provider_type]
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get_default_id(self, provider_type: ProviderType) -> str:
+        """Determine the default provider ID for a type."""
+        # 1. Try YAML config
+        if self._yaml_config:
+            section = self._yaml_config.get(provider_type.value, {})
+            default = section.get("default_provider")
+            if default and default in self._providers[provider_type]:
+                return default
+
+        # 2. Fall back to first registered
+        registered = list(self._providers[provider_type].keys())
+        if registered:
+            return registered[0]
+
+        raise ValueError(
+            f"No {provider_type.value} providers registered. "
+            "Call registry.register() or registry.autodiscover() first."
+        )
+
+    def _build_config(self, provider_type: ProviderType, provider_id: str) -> Dict:
+        """Merge static + YAML config for a provider ID."""
+        # Start with static config (registered at register() time)
+        config = dict(self._static_configs.get(provider_id, {}))
+
+        # Layer YAML config on top
+        if self._yaml_config:
+            section = self._yaml_config.get(provider_type.value, {})
+            yaml_provider_cfg = section.get("providers", {}).get(provider_id, {})
+            config.update(yaml_provider_cfg)
+
+        # Resolve ${ENV_VAR} placeholders
+        config = _resolve_env_vars(config)
+
+        return config
+
+    def _default_yaml_path(self) -> str:
+        """Resolve default config/providers.yaml path from project root."""
+        # This file lives at providers/registry.py; project root is one level up.
+        project_root = Path(__file__).parent.parent
+        return str(project_root / "config" / "providers.yaml")
+
+
+# ---------------------------------------------------------------------------
+# Env-var placeholder resolution
+# ---------------------------------------------------------------------------
+
+def _resolve_env_vars(config: Dict) -> Dict:
+    """Recursively resolve ${ENV_VAR} placeholders in string config values."""
+    import re
+    _PLACEHOLDER = re.compile(r"\$\{([A-Z_][A-Z0-9_]*)\}")
+
+    def _resolve(value: Any) -> Any:
+        if isinstance(value, str):
+            def _sub(m: re.Match) -> str:
+                return os.environ.get(m.group(1), m.group(0))
+            return _PLACEHOLDER.sub(_sub, value)
+        if isinstance(value, dict):
+            return {k: _resolve(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [_resolve(v) for v in value]
+        return value
+
+    return _resolve(config)
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton + convenience aliases
+# ---------------------------------------------------------------------------
+
+registry = ProviderRegistry.get_instance()
+
+
+def get_llm_provider(provider_id: Optional[str] = None) -> Any:
+    """Convenience: get an LLM provider instance."""
+    return registry.get_provider(ProviderType.LLM, provider_id)
+
+
+def get_tts_provider(provider_id: Optional[str] = None) -> Any:
+    """Convenience: get a TTS provider instance."""
+    return registry.get_provider(ProviderType.TTS, provider_id)
+
+
+def get_stt_provider(provider_id: Optional[str] = None) -> Any:
+    """Convenience: get an STT provider instance."""
+    return registry.get_provider(ProviderType.STT, provider_id)
+
+
+__all__ = [
+    "ProviderType",
+    "ProviderRegistry",
+    "registry",
+    "get_llm_provider",
+    "get_tts_provider",
+    "get_stt_provider",
+]

package/providers/stt/__init__.py

@@ -0,0 +1,12 @@
+"""STT provider package.
+
+Importing this package registers all STT providers with the registry.
+"""
+
+from providers.stt.base import STTProvider, TranscriptionResult, STTError
+
+# Import concrete providers so their registry.register() calls fire
+from providers.stt import webspeech_provider  # noqa: F401
+from providers.stt import whisper_provider  # noqa: F401
+
+__all__ = ["STTProvider", "TranscriptionResult", "STTError"]

package/providers/stt/base.py

@@ -0,0 +1,58 @@
+"""
+STT provider abstract base class.
+
+Based on: future-dev-plans/02-PROVIDER-SYSTEMS.md (stt_providers/base.py section)
+ADR-003: Abstract base class + registry pattern.
+"""
+
+from abc import abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from providers.base import BaseProvider, ProviderError
+
+
+@dataclass
+class TranscriptionResult:
+    text: str
+    confidence: float = 0.0
+    language: str = "en"
+    duration_ms: float = 0.0
+    provider: str = ""
+    segments: Optional[List[Dict]] = field(default=None)
+
+
+class STTProvider(BaseProvider):
+    """Abstract base class for STT providers (WebSpeech, Whisper, Deepgram, etc.)."""
+
+    @abstractmethod
+    def transcribe(
+        self,
+        audio_data: bytes,
+        language: Optional[str] = None,
+        **kwargs,
+    ) -> TranscriptionResult:
+        """Transcribe audio bytes to text."""
+        pass
+
+    def list_languages(self) -> List[str]:
+        return self._config.get("languages", ["en-US"])
+
+    def is_available(self) -> bool:
+        return self.get_info().get("status", "inactive") == "active"
+
+    def get_info(self) -> Dict[str, Any]:
+        return {
+            "name": self._config.get("name", self.__class__.__name__),
+            "languages": self.list_languages(),
+            "available": self.is_available(),
+            "status": "active",
+        }
+
+
+class STTError(ProviderError):
+    """STT-specific provider error."""
+    pass
+
+
+__all__ = ["STTProvider", "TranscriptionResult", "STTError"]

package/providers/stt/webspeech_provider.py

@@ -0,0 +1,49 @@
+"""
+Web Speech API STT provider (browser-side stub).
+
+Ref: future-dev-plans/02-PROVIDER-SYSTEMS.md (WebSpeechProvider section)
+The actual recognition runs in the browser; this is the server-side registry entry
+so profiles can reference 'webspeech' as their STT provider.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from providers.stt.base import STTError, STTProvider, TranscriptionResult
+from providers.registry import ProviderType, registry
+
+
+class WebSpeechProvider(STTProvider):
+    """Browser Web Speech API — server-side stub only."""
+
+    def transcribe(
+        self,
+        audio_data: bytes,
+        language: Optional[str] = None,
+        **kwargs,
+    ) -> TranscriptionResult:
+        raise STTError(
+            "webspeech",
+            "WebSpeech API runs in the browser. Server-side transcription is not supported.",
+        )
+
+    def is_available(self) -> bool:
+        # Always "available" as it's a browser-side component
+        return True
+
+    def list_languages(self) -> List[str]:
+        return ["en-US", "en-GB", "es-ES", "fr-FR", "de-DE", "ja-JP", "zh-CN"]
+
+    def get_info(self) -> Dict[str, Any]:
+        return {
+            "name": self._config.get("name", "Web Speech API"),
+            "type": "browser",
+            "status": "active",
+            "languages": self.list_languages(),
+            "available": True,
+        }
+
+
+# Auto-register when this module is imported
+registry.register(ProviderType.STT, "webspeech", WebSpeechProvider)