openvoiceui 1.0.0

package/services/speech_normalizer.py

@@ -0,0 +1,285 @@
+"""
+services/speech_normalizer.py — Speech Normalization Service
+
+Cleans and normalizes LLM response text before it is sent to TTS providers.
+Rules are loaded from config/speech_normalization.yaml (ADR-001).
+
+Usage:
+    from services.speech_normalizer import SpeechNormalizer
+
+    normalizer = SpeechNormalizer()
+    clean_text = normalizer.normalize("Hello **world**! Check https://example.com", profile_id="default")
+
+The normalizer supports per-profile rule overrides defined in
+config/speech_normalization.yaml under the `profiles:` key.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Config file location (relative to project root)
+_DEFAULT_CONFIG_PATH = Path(__file__).parent.parent / "config" / "speech_normalization.yaml"
+
+
+class SpeechNormalizer:
+    """
+    Normalizes text for TTS by applying a configurable pipeline of rules:
+
+    1. Strip markdown formatting (headers, bold, code blocks, etc.)
+    2. Strip URLs
+    3. Strip emoji
+    4. Expand abbreviations (API → A P I, etc.)
+    5. Collapse whitespace
+    6. Trim to max_length
+
+    Rules are loaded from speech_normalization.yaml.
+    Per-profile overrides are merged on top of global defaults.
+    """
+
+    def __init__(self, config_path: Optional[str] = None) -> None:
+        self._config_path = Path(config_path) if config_path else _DEFAULT_CONFIG_PATH
+        self._raw_config: Dict[str, Any] = {}
+        self._global: Dict[str, Any] = {}
+        self._profile_overrides: Dict[str, Dict[str, Any]] = {}
+        self._load_config()
+
+    # ── Config loading ─────────────────────────────────────────────────────────
+
+    def _load_config(self) -> None:
+        """Load and parse speech_normalization.yaml."""
+        if not self._config_path.exists():
+            logger.warning(
+                "Speech normalization config not found at %s — using built-in defaults",
+                self._config_path,
+            )
+            self._raw_config = {}
+            self._global = self._builtin_defaults()
+            return
+
+        try:
+            import yaml  # type: ignore
+            with open(self._config_path, "r") as f:
+                self._raw_config = yaml.safe_load(f) or {}
+            self._global = {**self._builtin_defaults(), **self._raw_config.get("global", {})}
+            # Merge global abbreviations with per-section ones
+            global_abbrevs = self._raw_config.get("abbreviations", {})
+            self._global["_abbreviations"] = global_abbrevs
+            # Per-profile overrides
+            self._profile_overrides = self._raw_config.get("profiles", {})
+            logger.info("Speech normalization config loaded from %s", self._config_path)
+        except Exception as exc:
+            logger.error("Failed to load speech normalization config: %s — using defaults", exc)
+            self._global = self._builtin_defaults()
+            self._global["_abbreviations"] = {}
+
+    def _builtin_defaults(self) -> Dict[str, Any]:
+        """Minimal built-in defaults used when config file is absent."""
+        return {
+            "strip_markdown": True,
+            "strip_urls": True,
+            "strip_emoji": True,
+            "collapse_whitespace": True,
+            "trim": True,
+            "max_length": 800,
+            "_abbreviations": {},
+        }
+
+    def reload(self) -> None:
+        """Reload config from disk (e.g. after hot-edit)."""
+        self._load_config()
+        logger.info("Speech normalization config reloaded")
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def normalize(self, text: str, profile_id: Optional[str] = None) -> str:
+        """
+        Apply the full normalization pipeline to *text*.
+
+        Args:
+            text: Raw LLM response text.
+            profile_id: Optional agent profile ID. If provided, per-profile
+                        overrides from speech_normalization.yaml are merged on
+                        top of the global settings.
+
+        Returns:
+            Cleaned string ready for TTS input.
+        """
+        if not text:
+            return text
+
+        cfg = self._merged_config(profile_id)
+
+        # 1. Strip markdown
+        if cfg.get("strip_markdown", True):
+            text = self._strip_markdown(text)
+
+        # 2. Strip URLs
+        if cfg.get("strip_urls", True):
+            text = self._strip_urls(text)
+
+        # 3. Strip emoji
+        if cfg.get("strip_emoji", True):
+            text = self._strip_emoji(text)
+
+        # 4. Expand abbreviations (global + profile-specific)
+        abbreviations = {**self._global.get("_abbreviations", {}), **cfg.get("abbreviations", {})}
+        if abbreviations:
+            text = self._expand_abbreviations(text, abbreviations)
+
+        # 5. Collapse whitespace
+        if cfg.get("collapse_whitespace", True):
+            text = re.sub(r"[ \t]+", " ", text)
+            text = re.sub(r"\n{2,}", " ", text)
+            text = re.sub(r"\n", " ", text)
+
+        # 6. Trim
+        if cfg.get("trim", True):
+            text = text.strip()
+
+        # 7. Enforce max length (hard cap)
+        max_len = cfg.get("max_length", 800)
+        if len(text) > max_len:
+            # Try to break at a sentence boundary
+            cut = text[:max_len].rfind(". ")
+            if cut > max_len // 2:
+                text = text[: cut + 1]
+            else:
+                text = text[:max_len].rstrip() + "..."
+            logger.debug("Speech normalizer truncated text to %d chars", len(text))
+
+        return text
+
+    def get_config_for_profile(self, profile_id: Optional[str] = None) -> Dict[str, Any]:
+        """Return the effective normalized config for a given profile (for inspection/debugging)."""
+        return self._merged_config(profile_id)
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _merged_config(self, profile_id: Optional[str]) -> Dict[str, Any]:
+        """Merge global settings with per-profile overrides."""
+        base = dict(self._global)
+        if profile_id and profile_id in self._profile_overrides:
+            override = self._profile_overrides[profile_id]
+            # Merge abbreviations separately (additive)
+            override_abbrevs = override.pop("abbreviations", {}) if isinstance(override, dict) else {}
+            base.update(override)
+            override["abbreviations"] = override_abbrevs  # restore for future calls
+            base["abbreviations"] = override_abbrevs
+        return base
+
+    def _strip_markdown(self, text: str) -> str:
+        """Remove common markdown syntax from text."""
+        patterns = self._raw_config.get("markdown_patterns", [])
+        if patterns:
+            for entry in patterns:
+                raw_pattern = entry.get("pattern", "")
+                replacement = entry.get("replacement", "")
+                flags_str = entry.get("flags", "")
+                flags = 0
+                if "multiline" in flags_str:
+                    flags |= re.MULTILINE
+                try:
+                    text = re.sub(raw_pattern, replacement, text, flags=flags)
+                except re.error as exc:
+                    logger.warning("Invalid markdown pattern %r: %s", raw_pattern, exc)
+        else:
+            # Built-in fallback patterns when config is absent
+            text = re.sub(r"```[\s\S]*?```", "", text)
+            text = re.sub(r"`[^`]+`", "", text)
+            text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)
+            text = re.sub(r"\*\*(.+?)\*\*", r"\1", text)
+            text = re.sub(r"__(.+?)__", r"\1", text)
+            text = re.sub(r"\*(.+?)\*", r"\1", text)
+            text = re.sub(r"_(.+?)_", r"\1", text)
+            text = re.sub(r"~~(.+?)~~", r"\1", text)
+            text = re.sub(r"^[-*_]{3,}$", "", text, flags=re.MULTILINE)
+            text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+            text = re.sub(r"!\[[^\]]*\]\([^)]+\)", "", text)
+            text = re.sub(r"^>\s*", "", text, flags=re.MULTILINE)
+            text = re.sub(r"^[\-\*\+]\s+", "", text, flags=re.MULTILINE)
+            text = re.sub(r"^\d+\.\s+", "", text, flags=re.MULTILINE)
+        return text
+
+    def _strip_urls(self, text: str) -> str:
+        """Remove HTTP/HTTPS URLs from text."""
+        url_pattern = self._raw_config.get("url_pattern", r"https?://[^\s]+")
+        try:
+            text = re.sub(url_pattern, "", text)
+        except re.error:
+            text = re.sub(r"https?://[^\s]+", "", text)
+        return text
+
+    def _strip_emoji(self, text: str) -> str:
+        """Remove emoji characters from text."""
+        # Broad Unicode emoji range
+        emoji_re = re.compile(
+            "["
+            "\U0001F300-\U0001F9FF"  # Misc symbols and pictographs
+            "\U00002600-\U000027BF"  # Misc symbols
+            "\U0001FA00-\U0001FAFF"  # Chess, medical etc.
+            "\U00002702-\U000027B0"
+            "\U000024C2-\U0001F251"
+            "]+",
+            flags=re.UNICODE,
+        )
+        return emoji_re.sub("", text)
+
+    def _expand_abbreviations(self, text: str, abbreviations: Dict[str, str]) -> str:
+        """
+        Replace abbreviations with their spoken forms.
+
+        Uses word-boundary matching so "API" inside "RAPID" is not replaced.
+        Longer abbreviations are tried first to prevent partial matches.
+        """
+        # Sort by length descending so longer keys match first
+        for abbrev, expansion in sorted(abbreviations.items(), key=lambda x: -len(x[0])):
+            if not abbrev:
+                continue
+            try:
+                # Word-boundary aware, case-sensitive match
+                pattern = r"\b" + re.escape(abbrev) + r"\b"
+                text = re.sub(pattern, expansion, text)
+            except re.error as exc:
+                logger.warning("Invalid abbreviation pattern for %r: %s", abbrev, exc)
+        return text
+
+
+# ── Module-level singleton ─────────────────────────────────────────────────────
+
+_normalizer_instance: Optional[SpeechNormalizer] = None
+
+
+def get_normalizer() -> SpeechNormalizer:
+    """Return the shared SpeechNormalizer singleton (lazy-init)."""
+    global _normalizer_instance
+    if _normalizer_instance is None:
+        _normalizer_instance = SpeechNormalizer()
+    return _normalizer_instance
+
+
+def normalize_for_tts(text: str, profile_id: Optional[str] = None) -> str:
+    """
+    Convenience function: normalize *text* using the global singleton.
+
+    Args:
+        text: Raw text to normalize.
+        profile_id: Optional profile ID for per-profile rule overrides.
+
+    Returns:
+        Cleaned text ready for TTS.
+    """
+    return get_normalizer().normalize(text, profile_id=profile_id)
+
+
+__all__ = [
+    "SpeechNormalizer",
+    "get_normalizer",
+    "normalize_for_tts",
+]

package/services/tts.py

@@ -0,0 +1,270 @@
+"""
+services/tts.py — Unified TTS Service
+
+Consolidates all TTS generation logic from server.py and tts_providers/.
+Provides a single entry point for generating speech audio.
+
+Providers:
+  - Groq Orpheus TTS (primary, cloud-based)
+  - Supertonic TTS (local ONNX, fallback)
+
+Usage:
+    from services.tts import generate_tts_b64, generate_tts_chunked
+
+    audio_b64 = generate_tts_b64(text, voice='M1')
+"""
+
+import base64
+import logging
+import os
+import re
+import struct
+import time
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ===== GROQ TTS =====
+
+_groq_client = None
+
+
+def get_groq_client():
+    """Get or initialize Groq client (lazy, cached)."""
+    global _groq_client
+    if _groq_client is None:
+        api_key = os.getenv('GROQ_API_KEY')
+        if api_key:
+            try:
+                from groq import Groq
+                _groq_client = Groq(api_key=api_key)
+                logger.info("Groq TTS client initialized")
+            except ImportError:
+                logger.warning("groq package not installed — Groq TTS unavailable")
+        else:
+            logger.warning("GROQ_API_KEY not set — Groq TTS unavailable")
+    return _groq_client
+
+
+def generate_groq_tts(text: str, voice: str = 'autumn') -> bytes:
+    """
+    Generate TTS audio using Groq Orpheus (canopylabs/orpheus-v1-english).
+
+    Args:
+        text: Text to synthesize.
+        voice: Orpheus voice name (default 'autumn').
+
+    Returns:
+        MP3 audio bytes.
+
+    Raises:
+        RuntimeError: If Groq client unavailable or API call fails.
+    """
+    groq = get_groq_client()
+    if not groq:
+        raise RuntimeError("Groq client not available")
+    tts_response = groq.audio.speech.create(
+        model="canopylabs/orpheus-v1-english",
+        input=text,
+        voice=voice,
+        response_format="mp3"
+    )
+    audio_bytes = tts_response.content if hasattr(tts_response, 'content') else tts_response.read()
+    logger.info(f"Groq Orpheus TTS generated: {len(audio_bytes)} bytes")
+    return audio_bytes
+
+
+# ===== SUPERTONIC TTS =====
+
+from tts_providers import get_provider, list_providers  # noqa: E402 — after stdlib imports
+
+
+def generate_tts_chunked(provider, text: str, voice: str, max_chars: int = 800) -> bytes:
+    """
+    Generate TTS audio with chunking to avoid Supertonic ONNX overflow.
+
+    Supertonic ONNX crashes with RUNTIME_EXCEPTION when text exceeds ~1000 tokens.
+    Splits long text on sentence boundaries, generates each chunk, then
+    concatenates the raw PCM data into a single WAV file.
+
+    Args:
+        provider: TTSProvider instance (e.g. SupertonicProvider).
+        text: Text to synthesize.
+        voice: Voice identifier (e.g. 'M1').
+        max_chars: Max characters per chunk. Default 800.
+
+    Returns:
+        WAV audio bytes (concatenated from all chunks).
+    """
+    # Short text — no chunking needed
+    if len(text) <= max_chars:
+        return provider.generate_speech(text=text, voice=voice, speed=1.05, total_step=40)
+
+    # Split on sentence boundaries
+    sentences = re.split(r'(?<=[.!?])\s+', text)
+    chunks = []
+    current_chunk = ""
+
+    for sentence in sentences:
+        if len(current_chunk) + len(sentence) + 1 > max_chars and current_chunk:
+            chunks.append(current_chunk.strip())
+            current_chunk = sentence
+        else:
+            current_chunk = (current_chunk + " " + sentence).strip()
+    if current_chunk:
+        chunks.append(current_chunk.strip())
+
+    logger.info(f"TTS chunking: {len(text)} chars -> {len(chunks)} chunks (max {max_chars})")
+
+    all_audio_data = b""
+    sample_rate = None
+    num_channels = None
+    bits_per_sample = None
+
+    for i, chunk in enumerate(chunks):
+        if not chunk.strip():
+            continue
+        try:
+            chunk_audio = provider.generate_speech(text=chunk, voice=voice, speed=1.05, total_step=40)
+            if i == 0:
+                if chunk_audio[:4] == b'RIFF' and chunk_audio[8:12] == b'WAVE':
+                    pos = 12
+                    while pos < len(chunk_audio) - 8:
+                        chunk_id = chunk_audio[pos:pos + 4]
+                        chunk_size = struct.unpack('<I', chunk_audio[pos + 4:pos + 8])[0]
+                        if chunk_id == b'fmt ':
+                            fmt_data = chunk_audio[pos + 8:pos + 8 + chunk_size]
+                            num_channels = struct.unpack('<H', fmt_data[2:4])[0]
+                            sample_rate = struct.unpack('<I', fmt_data[4:8])[0]
+                            bits_per_sample = struct.unpack('<H', fmt_data[14:16])[0]
+                        elif chunk_id == b'data':
+                            all_audio_data += chunk_audio[pos + 8:pos + 8 + chunk_size]
+                            break
+                        pos += 8 + chunk_size
+                else:
+                    return chunk_audio
+            else:
+                if chunk_audio[:4] == b'RIFF':
+                    pos = 12
+                    while pos < len(chunk_audio) - 8:
+                        chunk_id = chunk_audio[pos:pos + 4]
+                        chunk_size = struct.unpack('<I', chunk_audio[pos + 4:pos + 8])[0]
+                        if chunk_id == b'data':
+                            all_audio_data += chunk_audio[pos + 8:pos + 8 + chunk_size]
+                            break
+                        pos += 8 + chunk_size
+            logger.info(f"  Chunk {i + 1}/{len(chunks)}: {len(chunk)} chars OK")
+        except Exception as e:
+            logger.error(f"  Chunk {i + 1}/{len(chunks)} FAILED: {e}")
+
+    if not all_audio_data or sample_rate is None:
+        logger.warning("All TTS chunks failed, trying truncated text")
+        return provider.generate_speech(text=text[:max_chars], voice=voice, speed=1.05, total_step=40)
+
+    # Rebuild WAV with concatenated PCM data
+    byte_rate = sample_rate * num_channels * (bits_per_sample // 8)
+    block_align = num_channels * (bits_per_sample // 8)
+    data_size = len(all_audio_data)
+    file_size = 36 + data_size
+
+    wav_header = struct.pack('<4sI4s', b'RIFF', file_size, b'WAVE')
+    fmt_chunk = struct.pack('<4sIHHIIHH', b'fmt ', 16, 1,
+                            num_channels, sample_rate, byte_rate, block_align, bits_per_sample)
+    data_header = struct.pack('<4sI', b'data', data_size)
+
+    return wav_header + fmt_chunk + data_header + all_audio_data
+
+
+# ===== UNIFIED GENERATE FUNCTION =====
+
+# Fallback order when a provider fails (provider_id → fallback_id)
+_FALLBACK_CHAIN = {
+    'groq': 'supertonic',
+    'qwen3': 'supertonic',
+    'resemble': 'supertonic',
+}
+
+_MAX_RETRIES = 2
+_RETRY_DELAYS = (0.5, 1.5)  # seconds between retries
+
+
+def _generate_with_provider(tts_provider: str, text: str, voice: str) -> bytes:
+    """Generate audio bytes from a single provider (no retry/fallback)."""
+    provider = get_provider(tts_provider)
+    provider_info = provider.get_info()
+    audio_format = provider_info.get('audio_format', 'wav')
+
+    # Cloud providers that return WAV handle their own chunking/limits
+    if audio_format == 'mp3' or tts_provider in ('resemble',):
+        return provider.generate_speech(text=text, voice=voice)
+    # Local WAV providers (supertonic) need ONNX overflow chunking
+    return generate_tts_chunked(provider, text, voice)
+
+
+def generate_tts_b64(
+    text: str,
+    voice: Optional[str] = None,
+    tts_provider: str = 'groq',
+    **kwargs,
+) -> Optional[str]:
+    """
+    Generate TTS audio and return as a base64-encoded string.
+
+    Retries transient failures up to _MAX_RETRIES times, then falls back
+    to an alternate provider (e.g. groq → supertonic).
+
+    Args:
+        text: Text to synthesize.
+        voice: Voice ID (provider-specific). Defaults to provider default.
+        tts_provider: Provider ID ('supertonic', 'groq', 'qwen3', etc.).
+
+    Returns:
+        Base64-encoded audio string, or None on failure.
+    """
+    voice = voice or 'M1'
+
+    # ── Try primary provider (single attempt for cloud, retries for local) ──
+    last_err = None
+    # Cloud providers (groq, qwen3) have their own timeout — don't retry
+    # on timeout, fall back immediately. Only retry local providers.
+    is_cloud = tts_provider in ('groq', 'qwen3', 'resemble')
+    max_attempts = 1 if is_cloud else _MAX_RETRIES + 1
+    for attempt in range(max_attempts):
+        try:
+            audio_bytes = _generate_with_provider(tts_provider, text, voice)
+            logger.info(f"TTS generated: provider={tts_provider}, voice={voice}, attempt={attempt + 1}")
+            return base64.b64encode(audio_bytes).decode('utf-8')
+        except Exception as e:
+            last_err = e
+            if attempt < max_attempts - 1:
+                delay = _RETRY_DELAYS[attempt]
+                logger.warning(f"TTS attempt {attempt + 1} failed (provider={tts_provider}): {e} — retrying in {delay}s")
+                time.sleep(delay)
+            else:
+                logger.warning(f"TTS failed (provider={tts_provider}): {e} — trying fallback")
+
+    # ── Fallback to alternate provider ───────────────────────────────
+    fallback_id = _FALLBACK_CHAIN.get(tts_provider)
+    if fallback_id:
+        logger.info(f"TTS falling back: {tts_provider} → {fallback_id}")
+        try:
+            fallback_provider = get_provider(fallback_id)
+            fallback_voice = fallback_provider.get_default_voice()
+            audio_bytes = _generate_with_provider(fallback_id, text, fallback_voice)
+            logger.info(f"TTS fallback OK: provider={fallback_id}, voice={fallback_voice}")
+            return base64.b64encode(audio_bytes).decode('utf-8')
+        except Exception as fb_err:
+            logger.error(f"TTS fallback also failed (provider={fallback_id}): {fb_err}")
+
+    logger.error(f"TTS generation failed — all providers exhausted for: '{text[:60]}'")
+    return None
+
+
+__all__ = [
+    'get_groq_client',
+    'generate_groq_tts',
+    'generate_tts_chunked',
+    'generate_tts_b64',
+    'get_provider',
+    'list_providers',
+]