friday-framework-speech 0.1.0a0__py3-none-any.whl

friday_framework_speech-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: friday-framework-speech
+Version: 0.1.0a0
+Summary: Speech services (TTS, wake word) for Friday
+Project-URL: Homepage, https://github.com/CIChuck/agent-framework
+Project-URL: Repository, https://github.com/CIChuck/agent-framework
+Project-URL: Issues, https://github.com/CIChuck/agent-framework/issues
+Project-URL: Documentation, https://github.com/CIChuck/agent-framework/tree/main/docs
+Project-URL: Source, https://github.com/CIChuck/agent-framework/tree/main/packages/friday-speech
+Author: Friday Team
+License-Expression: MIT
+Keywords: assistant,audio,speech,tts,wakeword
+Requires-Python: >=3.10
+Requires-Dist: friday-framework-core==0.1.0a0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: elevenlabs
+Requires-Dist: elevenlabs>=1.0.0; extra == 'elevenlabs'
+Provides-Extra: picovoice
+Requires-Dist: pvcobra>=2.0.0; extra == 'picovoice'
+Requires-Dist: pvleopard>=2.0.0; extra == 'picovoice'
+Requires-Dist: pvorca>=0.1.0; extra == 'picovoice'
+Requires-Dist: pvporcupine>=3.0.0; extra == 'picovoice'
+Requires-Dist: pvrecorder>=1.2.0; extra == 'picovoice'
+Requires-Dist: pvrhino>=2.0.0; extra == 'picovoice'
+Requires-Dist: pvspeaker>=0.1.0; extra == 'picovoice'
+Description-Content-Type: text/markdown
+
+# Friday Framework Speech
+
+Speech service package for the Friday Framework.
+
+This package provides speech service abstractions and optional text-to-speech,
+wake-word, recording, playback, and speech-provider integrations.
+
+## Install
+
+```bash
+pip install friday-framework-speech
+```
+
+Optional speech providers are available through extras such as `elevenlabs` and
+`picovoice`.
+
+## Import Package
+
+```python
+import friday_speech
+```
+
+## License
+
+MIT

friday_framework_speech-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,15 @@
+friday_speech/__init__.py,sha256=Bf8Z-ly2faSZB2zpSNteFqflVffHDuMNvJpf4NYcb9c,830
+friday_speech/chunking.py,sha256=lgf2JlvV_l00R6J31T-GPvJ5GA5UfrwCMIgO5ih_8EY,2041
+friday_speech/config.py,sha256=2yr7JxrCmsAjd_eL98v9zl0SEovFzmM21UM0DjXtBNw,11064
+friday_speech/errors.py,sha256=82s6pYLJ53b_f_VkPOkY_13xg63hXuCDzyCig4jvFgA,778
+friday_speech/harness.py,sha256=K5JPGBXf2mPbIR7DFbooWMJfCvftOHWJbxO__7WGaYY,3055
+friday_speech/interfaces.py,sha256=MqGiBmxYiPIhKGKBhIsrPRpv6bcp62clAOuKxs11bMg,1700
+friday_speech/playback.py,sha256=R712SwwNAHNIdfyDID53hCmMNZIj_7X2APigO6vbAG0,8167
+friday_speech/selection.py,sha256=mX2kvxRY8-O-jpZbqWH5DLWg4ht9-Ju3fjkab3125-o,4562
+friday_speech/service.py,sha256=9_RPqk2-jN3iJA3-I4krDJJcO6JzJry2FcBTsyBtE1s,4456
+friday_speech/adapters/__init__.py,sha256=IEbOWJ04XR5XpRlbeYNhi4B5MMPsRRJv58KRvmH_Ias,1644
+friday_speech/adapters/elevenlabs.py,sha256=WPG5ffdOyV8TgJd3I2qcPi3qwJnY0w5M2KCcgSRyyRg,6315
+friday_speech/adapters/picovoice.py,sha256=doFCdrutVcGzaTHOFik2jp3Qp4JZbHIJw0rUBr4LW_I,9166
+friday_framework_speech-0.1.0a0.dist-info/METADATA,sha256=ne6dfM8afdV7dB5djS6pju0sZMYObWvBGsACS5JYtIE,1822
+friday_framework_speech-0.1.0a0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+friday_framework_speech-0.1.0a0.dist-info/RECORD,,

friday_framework_speech-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

friday_speech/__init__.py

@@ -0,0 +1,44 @@
+# mypy: ignore-errors
+"""Friday speech package."""
+
+from .config import SpeechConfig
+from .errors import (
+    AdapterError,
+    DependencyError,
+    PlaybackError,
+    SelectionError,
+    SpeechConfigError,
+    SpeechError,
+    STTError,
+    WakeWordError,
+)
+from .harness import SpeechHarness
+from .interfaces import (
+    AdapterRegistry,
+    AudioFormat,
+    AudioStream,
+    STTAdapter,
+    TTSAdapter,
+    WakeWordAdapter,
+)
+from .service import SpeechService
+
+__all__ = [
+    "AdapterError",
+    "AdapterRegistry",
+    "AudioFormat",
+    "AudioStream",
+    "DependencyError",
+    "PlaybackError",
+    "SelectionError",
+    "SpeechConfig",
+    "SpeechConfigError",
+    "SpeechError",
+    "SpeechHarness",
+    "SpeechService",
+    "STTAdapter",
+    "STTError",
+    "TTSAdapter",
+    "WakeWordAdapter",
+    "WakeWordError",
+]

friday_speech/adapters/__init__.py

@@ -0,0 +1,43 @@
+# mypy: ignore-errors
+"""Adapter factory helpers for friday-speech."""
+
+from __future__ import annotations
+
+from ..config import SpeechConfig, TTSProvider, WakeWordProvider
+from ..errors import AdapterError
+from ..interfaces import STTAdapter, TTSAdapter, WakeWordAdapter
+
+
+def build_tts_adapter(config: SpeechConfig) -> TTSAdapter:
+    """Create a TTS adapter for the configured provider."""
+    if config.tts.provider == TTSProvider.ELEVENLABS:
+        from .elevenlabs import ElevenLabsAdapter
+
+        return ElevenLabsAdapter(config.elevenlabs)
+    if config.tts.provider == TTSProvider.PICOVOICE:
+        from .picovoice import PicovoiceOrcaAdapter
+
+        return PicovoiceOrcaAdapter(config.picovoice)
+    raise AdapterError(f"Unsupported TTS provider: {config.tts.provider}")
+
+
+def build_wakeword_adapter(config: SpeechConfig) -> WakeWordAdapter | None:
+    """Create a wake word adapter if enabled."""
+    if not config.wakeword.enabled:
+        return None
+    if config.wakeword.provider == WakeWordProvider.PICOVOICE:
+        from .picovoice import PicovoicePorcupineAdapter
+
+        return PicovoicePorcupineAdapter(config.picovoice)
+    raise AdapterError(f"Unsupported wake word provider: {config.wakeword.provider}")
+
+
+def build_stt_adapter(config: SpeechConfig) -> STTAdapter | None:
+    """Create a speech-to-text adapter if enabled."""
+    if not config.stt.enabled:
+        return None
+    if config.stt.provider.value == "picovoice":
+        from .picovoice import PicovoiceLeopardAdapter
+
+        return PicovoiceLeopardAdapter(config.picovoice)
+    raise AdapterError(f"Unsupported STT provider: {config.stt.provider}")

friday_speech/adapters/elevenlabs.py

@@ -0,0 +1,183 @@
+# mypy: ignore-errors
+"""ElevenLabs TTS adapter (best-effort streaming)."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import threading
+from collections.abc import AsyncIterator, Iterable
+from typing import Any
+
+from ..config import ElevenLabsConfig, VoiceSettingsConfig
+from ..errors import AdapterError, DependencyError
+from ..interfaces import AudioFormat, AudioStream, TTSAdapter
+
+
+class ElevenLabsAdapter(TTSAdapter):
+    """ElevenLabs adapter using the official Python SDK when available."""
+
+    def __init__(self, config: ElevenLabsConfig) -> None:
+        self._config = config
+        self.output_format = _infer_audio_format(config.output_format)
+        self.sample_rate = _infer_sample_rate(config.output_format)
+        self.channels = None
+
+    async def stream(
+        self,
+        text: str,
+        voice_id: str | None,
+        settings: VoiceSettingsConfig,
+    ) -> AudioStream:
+        if not self._config.api_key:
+            raise AdapterError("ElevenLabs API key is required")
+
+        elevenlabs = _import_elevenlabs()
+        client = _build_client(elevenlabs, self._config.api_key)
+        payload = _build_voice_settings(settings)
+
+        text_to_speech = getattr(client, "text_to_speech", None)
+        if text_to_speech is None:
+            raise AdapterError("ElevenLabs client missing text_to_speech interface")
+
+        if hasattr(text_to_speech, "convert_as_stream"):
+            sync_stream = text_to_speech.convert_as_stream(
+                text=text,
+                voice_id=voice_id or self._config.voice_id,
+                model_id=self._config.model_id,
+                output_format=self._config.output_format,
+                voice_settings=payload or None,
+            )
+            chunks = _async_from_sync_iterator(sync_stream)
+            return AudioStream(
+                format=self.output_format,
+                chunks=chunks,
+                sample_rate=self.sample_rate,
+                channels=self.channels,
+            )
+
+        if hasattr(text_to_speech, "convert"):
+            audio = await asyncio.to_thread(
+                text_to_speech.convert,
+                text=text,
+                voice_id=voice_id or self._config.voice_id,
+                model_id=self._config.model_id,
+                output_format=self._config.output_format,
+                voice_settings=payload or None,
+            )
+            chunks = _async_single_chunk(audio)
+            return AudioStream(
+                format=self.output_format,
+                chunks=chunks,
+                sample_rate=self.sample_rate,
+                channels=self.channels,
+            )
+
+        raise AdapterError(
+            "Unsupported ElevenLabs SDK: expected text_to_speech.convert[_as_stream]"
+        )
+
+
+def _import_elevenlabs() -> Any:
+    try:
+        import elevenlabs  # type: ignore
+
+        return elevenlabs
+    except Exception as exc:  # pragma: no cover - dependency gate
+        raise DependencyError(
+            "ElevenLabs SDK not installed. Install with: pip install elevenlabs"
+        ) from exc
+
+
+def _build_client(module: Any, api_key: str) -> Any:
+    for path in ("client", None):
+        try:
+            if path:
+                client_mod = __import__(f"elevenlabs.{path}", fromlist=["ElevenLabs"])
+                client_cls = getattr(client_mod, "ElevenLabs", None)
+            else:
+                client_cls = getattr(module, "ElevenLabs", None)
+            if client_cls:
+                return client_cls(api_key=api_key)
+        except Exception:
+            continue
+    raise AdapterError("Unable to initialize ElevenLabs client")
+
+
+def _build_voice_settings(settings: VoiceSettingsConfig) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    if settings.stability is not None:
+        payload["stability"] = settings.stability
+    if settings.similarity_boost is not None:
+        payload["similarity_boost"] = settings.similarity_boost
+    if settings.style is not None:
+        payload["style"] = settings.style
+    if settings.speed is not None:
+        payload["speed"] = settings.speed
+    return payload
+
+
+def _infer_audio_format(output_format: str) -> AudioFormat:
+    value = output_format.lower()
+    if value.startswith("mp3"):
+        return AudioFormat.MP3
+    if value.startswith("pcm"):
+        return AudioFormat.PCM
+    raise AdapterError(f"Unsupported ElevenLabs output_format: {output_format}")
+
+
+def _infer_sample_rate(output_format: str) -> int | None:
+    match = re.search(r"(\d{4,6})", output_format)
+    if not match:
+        return None
+    try:
+        return int(match.group(1))
+    except ValueError:
+        return None
+
+
+def _async_single_chunk(audio: Any) -> AsyncIterator[bytes]:
+    async def _generator() -> AsyncIterator[bytes]:
+        if isinstance(audio, (bytes, bytearray)):
+            yield bytes(audio)
+            return
+        if isinstance(audio, Iterable):
+            for chunk in audio:
+                if isinstance(chunk, (bytes, bytearray)):
+                    yield bytes(chunk)
+                else:
+                    raise AdapterError("ElevenLabs stream yielded non-bytes chunk")
+            return
+        raise AdapterError("ElevenLabs audio payload is not bytes or iterable")
+
+    return _generator()
+
+
+def _async_from_sync_iterator(stream: Iterable[Any]) -> AsyncIterator[bytes]:
+    async def _generator() -> AsyncIterator[bytes]:
+        queue: asyncio.Queue[Any] = asyncio.Queue()
+        sentinel = object()
+        loop = asyncio.get_running_loop()
+
+        def _worker() -> None:
+            try:
+                for chunk in stream:
+                    loop.call_soon_threadsafe(queue.put_nowait, chunk)
+            except Exception as exc:
+                loop.call_soon_threadsafe(queue.put_nowait, exc)
+            finally:
+                loop.call_soon_threadsafe(queue.put_nowait, sentinel)
+
+        threading.Thread(target=_worker, daemon=True).start()
+
+        while True:
+            item = await queue.get()
+            if item is sentinel:
+                break
+            if isinstance(item, Exception):
+                raise item
+            if not isinstance(item, (bytes, bytearray)):
+                raise AdapterError("ElevenLabs stream yielded non-bytes chunk")
+            yield bytes(item)
+
+    return _generator()

friday_speech/adapters/picovoice.py

@@ -0,0 +1,277 @@
+# mypy: ignore-errors
+"""Picovoice adapters for wake word and TTS."""
+
+from __future__ import annotations
+
+import asyncio
+import unicodedata
+from array import array
+from collections.abc import AsyncIterator
+from typing import Any
+
+from friday_core.logging import get_logger
+
+from ..config import PicovoiceConfig, VoiceSettingsConfig
+from ..errors import AdapterError, DependencyError, STTError, WakeWordError
+from ..interfaces import (
+    AudioFormat,
+    AudioStream,
+    STTAdapter,
+    TTSAdapter,
+    WakeWordAdapter,
+)
+
+logger = get_logger(__name__)
+
+
+class PicovoiceOrcaAdapter(TTSAdapter):
+    """Picovoice Orca TTS adapter."""
+
+    def __init__(self, config: PicovoiceConfig) -> None:
+        self._config = config
+        self._logger = get_logger(__name__)
+        self.output_format = AudioFormat.PCM
+        self.sample_rate = None
+        self.channels = 1
+
+    async def stream(
+        self,
+        text: str,
+        voice_id: str | None,
+        settings: VoiceSettingsConfig,
+    ) -> AudioStream:
+        if not self._config.access_key:
+            raise AdapterError("Picovoice access_key is required")
+
+        try:
+            import pvorca  # type: ignore
+        except Exception as exc:  # pragma: no cover - dependency gate
+            raise DependencyError(
+                "Picovoice Orca not installed. Install with: pip install pvorca"
+            ) from exc
+
+        create_kwargs: dict[str, Any] = {
+            "access_key": self._config.access_key,
+            "model_path": self._config.orca.model_path,
+        }
+
+        try:
+            import inspect
+
+            supported = inspect.signature(pvorca.create).parameters
+            filtered = {
+                k: v
+                for k, v in create_kwargs.items()
+                if k in supported and v is not None
+            }
+            dropped = {k for k in create_kwargs if k not in filtered}
+            if dropped:
+                self._logger.warning(
+                    "Picovoice Orca create() does not support parameters; ignoring.",
+                    dropped=sorted(dropped),
+                )
+            orca = pvorca.create(**filtered)
+        except TypeError as exc:
+            self._logger.error(
+                "Picovoice Orca create() failed with configured parameters; retrying with minimal args.",  # noqa: E501
+                error=str(exc),
+            )
+            orca = pvorca.create(
+                access_key=self._config.access_key,
+                model_path=self._config.orca.model_path,
+            )
+
+        try:
+            sanitized = _sanitize_for_orca(
+                text, getattr(orca, "valid_characters", None)
+            )
+            pcm_data = orca.synthesize(
+                sanitized, speech_rate=self._config.orca.speech_rate
+            )
+            if isinstance(pcm_data, tuple):
+                pcm_data = pcm_data[0] if pcm_data else None
+            pcm_bytes = _ensure_pcm_bytes(pcm_data)
+
+            self.sample_rate = getattr(orca, "sample_rate", None)
+
+        finally:
+            if hasattr(orca, "delete"):
+                orca.delete()
+
+        async def _generator() -> AsyncIterator[bytes]:
+            yield pcm_bytes
+
+        if not pcm_bytes:
+            raise AdapterError("Picovoice Orca returned no audio")
+
+        return AudioStream(
+            format=self.output_format,
+            chunks=_generator(),
+            sample_rate=self.sample_rate,
+            channels=self.channels,
+        )
+
+
+def _ensure_pcm_bytes(payload: Any) -> bytes:
+    if payload is None:
+        return b""
+    if isinstance(payload, (bytes, bytearray)):
+        return bytes(payload)
+    if isinstance(payload, memoryview):
+        return payload.tobytes()
+    if isinstance(payload, array):
+        return payload.tobytes()
+    if isinstance(payload, list):
+        if not payload:
+            return b""
+        if any(isinstance(item, float) for item in payload):
+            max_abs = max(abs(float(item)) for item in payload)
+            if max_abs <= 1.0:
+                scaled = [
+                    int(max(-1.0, min(1.0, float(item))) * 32767) for item in payload
+                ]
+                return array("h", scaled).tobytes()
+        return array("h", payload).tobytes()
+    if isinstance(payload, tuple):
+        for item in payload:
+            try:
+                return _ensure_pcm_bytes(item)
+            except AdapterError:
+                continue
+        return array("h", payload).tobytes()
+    if isinstance(payload, dict):
+        for key in ("pcm", "pcm_data", "audio", "data"):
+            if key in payload:
+                return _ensure_pcm_bytes(payload[key])
+    if hasattr(payload, "pcm"):
+        return _ensure_pcm_bytes(payload.pcm)
+    if hasattr(payload, "tobytes"):
+        try:
+            return payload.tobytes()
+        except Exception:
+            pass
+    try:
+        import numpy as np  # type: ignore
+
+        if isinstance(payload, np.ndarray):
+            if payload.dtype != np.int16:
+                payload = payload.astype(np.int16)
+            return payload.tobytes()
+    except Exception:
+        pass
+    logger.error(
+        "Unsupported PCM payload from Picovoice Orca",
+        payload_type=type(payload).__name__,
+    )
+    raise AdapterError("Unsupported PCM payload from Picovoice Orca")
+
+
+def _sanitize_for_orca(text: str, valid_characters: str | None) -> str:
+    if not text:
+        return ""
+    normalized = unicodedata.normalize("NFKC", text)
+    translation = str.maketrans(
+        {
+            "“": '"',
+            "”": '"',
+            "‘": "'",
+            "’": "'",
+            "—": "-",
+            "–": "-",
+            "…": "...",
+            "\u00a0": " ",
+        }
+    )
+    normalized = normalized.translate(translation)
+    if not valid_characters:
+        return normalized
+    allowed = set(valid_characters)
+    sanitized = "".join(ch if ch in allowed else " " for ch in normalized)
+    return " ".join(sanitized.split())
+
+
+class PicovoicePorcupineAdapter(WakeWordAdapter):
+    """Picovoice Porcupine wake word adapter."""
+
+    def __init__(self, config: PicovoiceConfig) -> None:
+        self._config = config
+        self._logger = get_logger(__name__)
+        self._porcupine = None
+        self._recorder = None
+        self._active = False
+
+    async def wait_for_wakeword(self) -> None:
+        if not self._config.access_key:
+            raise WakeWordError("Picovoice access_key is required")
+        await asyncio.to_thread(self._blocking_wait)
+
+    def _blocking_wait(self) -> None:
+        if not self._active:
+            self._initialize()
+        if not self._porcupine or not self._recorder:
+            raise WakeWordError("Wake word adapter not initialized")
+        while True:
+            pcm = self._recorder.read()
+            result = self._porcupine.process(pcm)
+            if result >= 0:
+                return
+
+    def _initialize(self) -> None:
+        try:
+            import pvporcupine  # type: ignore
+            from pvrecorder import PvRecorder  # type: ignore
+        except Exception as exc:  # pragma: no cover - dependency gate
+            raise DependencyError(
+                "Picovoice Porcupine not installed. Install with: pip install pvporcupine pvrecorder"  # noqa: E501
+            ) from exc
+
+        porcupine_config = self._config.porcupine
+        keywords = porcupine_config.keywords
+        keyword_paths = porcupine_config.keyword_paths
+
+        if not keywords and not keyword_paths:
+            raise WakeWordError("Porcupine requires keywords or keyword_paths")
+
+        self._porcupine = pvporcupine.create(
+            access_key=self._config.access_key,
+            keywords=keywords if keywords else None,
+            keyword_paths=keyword_paths if keyword_paths else None,
+            sensitivities=porcupine_config.sensitivities,
+            model_path=porcupine_config.model_path,
+        )
+
+        frame_length = self._porcupine.frame_length
+        recorder_config = self._config.recorder
+        self._recorder = PvRecorder(
+            device_index=recorder_config.device_index,
+            frame_length=recorder_config.frame_length or frame_length,
+        )
+        self._recorder.start()
+        self._active = True
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._shutdown)
+
+    def _shutdown(self) -> None:
+        if self._recorder:
+            self._recorder.stop()
+            if hasattr(self._recorder, "delete"):
+                self._recorder.delete()
+        if self._porcupine and hasattr(self._porcupine, "delete"):
+            self._porcupine.delete()
+        self._recorder = None
+        self._porcupine = None
+        self._active = False
+
+
+class PicovoiceLeopardAdapter(STTAdapter):
+    """Picovoice Leopard speech-to-text adapter (capture handled externally)."""
+
+    def __init__(self, config: PicovoiceConfig) -> None:
+        self._config = config
+        self._logger = get_logger(__name__)
+
+    async def transcribe(self) -> str:
+        raise STTError(
+            "Picovoice STT is not wired yet. Provide a custom STT adapter or implement capture."  # noqa: E501
+        )