dv-pipecat-ai 0.0.74.dev770__py3-none-any.whl → 0.0.82.dev776__py3-none-any.whl

pipecat/services/hamsa/__init__.py

@@ -0,0 +1,9 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+from .stt import HamsaSTTService
+
+__all__ = ["HamsaSTTService"]

pipecat/services/hamsa/stt.py

@@ -0,0 +1,241 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Hamsa Speech-to-Text service implementation.
+
+This module implements speech-to-text transcription using the Hamsa API.
+Hamsa supports Arabic and English languages via HTTP POST requests.
+"""
+
+import asyncio
+import base64
+import json
+from typing import AsyncGenerator, Optional
+
+import aiohttp
+from loguru import logger
+from pydantic import BaseModel, Field
+from typing_extensions import override
+
+from pipecat.frames.frames import (
+    ErrorFrame,
+    Frame,
+    TranscriptionFrame,
+)
+from pipecat.services.stt_service import SegmentedSTTService
+from pipecat.transcriptions.language import Language
+from pipecat.utils.time import time_now_iso8601
+from pipecat.utils.tracing.service_decorators import traced_stt
+
+
+def language_to_hamsa_language(language: Language) -> Optional[str]:
+    """Convert a Language enum to Hamsa's language code format.
+
+    Args:
+        language: The Language enum value to convert
+
+    Returns:
+        The Hamsa language code string or None if not supported
+    """
+    # Hamsa supports Arabic and English
+    language_map = {
+        # Arabic
+        Language.AR: "ar",
+        Language.AR_AE: "ar",
+        Language.AR_BH: "ar",
+        Language.AR_DZ: "ar",
+        Language.AR_EG: "ar",
+        Language.AR_IQ: "ar",
+        Language.AR_JO: "ar",
+        Language.AR_KW: "ar",
+        Language.AR_LB: "ar",
+        Language.AR_LY: "ar",
+        Language.AR_MA: "ar",
+        Language.AR_OM: "ar",
+        Language.AR_QA: "ar",
+        Language.AR_SA: "ar",
+        Language.AR_SY: "ar",
+        Language.AR_TN: "ar",
+        Language.AR_YE: "ar",
+        # English
+        Language.EN: "en",
+        Language.EN_AU: "en",
+        Language.EN_CA: "en",
+        Language.EN_GB: "en",
+        Language.EN_HK: "en",
+        Language.EN_IE: "en",
+        Language.EN_IN: "en",
+        Language.EN_KE: "en",
+        Language.EN_NG: "en",
+        Language.EN_NZ: "en",
+        Language.EN_PH: "en",
+        Language.EN_SG: "en",
+        Language.EN_TZ: "en",
+        Language.EN_US: "en",
+        Language.EN_ZA: "en",
+    }
+    return language_map.get(language)
+
+
+class HamsaSTTService(SegmentedSTTService):
+    """Hamsa Speech-to-Text service implementation.
+
+    This service uses the Hamsa API for speech-to-text transcription.
+    It inherits from SegmentedSTTService to handle audio buffering and
+    processes complete audio segments when the user stops speaking.
+
+    Features:
+    - Supports Arabic and English languages
+    - Uses HTTP POST requests (not streaming)
+    - Configurable End of Speech (EOS) detection
+    - Base64 audio encoding
+
+    Args:
+        api_key: Hamsa API key for authentication
+        language: Language for transcription (defaults to Arabic "ar")
+        eos_threshold: End of speech threshold (0.0-1.0, default 0.3)
+        base_url: Hamsa API base URL
+        aiohttp_session: Optional aiohttp session for connection pooling
+        **kwargs: Additional arguments passed to SegmentedSTTService
+    """
+
+    class InputParams(BaseModel):
+        language: str = Field(default="ar", description="Language code ('ar' or 'en')")
+        eos_threshold: float = Field(default=0.3, description="End of speech threshold")
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        language: Language = Language.AR,
+        eos_threshold: float = 0.3,
+        base_url: str = "https://api.tryhamsa.com",
+        aiohttp_session: Optional[aiohttp.ClientSession] = None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._language = language_to_hamsa_language(language) or "ar"
+        self._eos_threshold = eos_threshold
+        self._aiohttp_session = aiohttp_session
+        self._endpoint = f"{self._base_url}/v1/realtime/stt"
+
+        # Store current settings
+        self._settings = {
+            "language": self._language,
+            "eos_threshold": self._eos_threshold,
+        }
+
+    async def set_language(self, language: Language):
+        """Set the language for speech recognition.
+
+        Args:
+            language: The language to use for speech recognition
+        """
+        hamsa_language = language_to_hamsa_language(language)
+        if hamsa_language:
+            self._language = hamsa_language
+            self._settings["language"] = hamsa_language
+            logger.info(f"Updated Hamsa STT language to: {hamsa_language}")
+        else:
+            logger.warning(f"Language {language} not supported by Hamsa STT")
+
+    @traced_stt
+    @override
+    async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
+        """Run speech-to-text transcription on the provided audio.
+
+        Args:
+            audio: Raw audio bytes (WAV format) to transcribe
+
+        Yields:
+            Frame: TranscriptionFrame with transcription results or ErrorFrame on failure
+        """
+        try:
+            # Convert audio bytes to base64
+            audio_b64 = base64.b64encode(audio).decode("utf-8")
+
+            # Prepare request payload
+            payload = {
+                "audioBase64": audio_b64,
+                "language": self._language,
+                "eos_threshold": self._eos_threshold,
+            }
+
+            headers = {
+                "Authorization": f"Token {self._api_key}",
+                "Content-Type": "application/json",
+            }
+
+            # Use provided session or create a new one
+            session = self._aiohttp_session
+            should_close_session = False
+
+            if not session:
+                session = aiohttp.ClientSession()
+                should_close_session = True
+
+            try:
+                # Make the HTTP POST request
+                async with session.post(
+                    self._endpoint,
+                    json=payload,
+                    headers=headers,
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as response:
+                    if response.status == 200:
+                        result = await response.json()
+
+                        # Extract transcribed text from response
+                        transcription = result.get("text", "").strip()
+
+                        if transcription:
+                            logger.debug(f"Hamsa STT transcription: {transcription}")
+                            yield TranscriptionFrame(
+                                text=transcription,
+                                user_id="user",
+                                timestamp=time_now_iso8601(),
+                            )
+                        else:
+                            logger.debug("Hamsa STT returned empty transcription")
+
+                    elif response.status == 401:
+                        error_msg = "Hamsa STT authentication failed - check API key"
+                        logger.error(error_msg)
+                        yield ErrorFrame(error=error_msg)
+
+                    elif response.status == 400:
+                        error_text = await response.text()
+                        error_msg = f"Hamsa STT bad request: {error_text}"
+                        logger.error(error_msg)
+                        yield ErrorFrame(error=error_msg)
+
+                    else:
+                        error_text = await response.text()
+                        error_msg = f"Hamsa STT request failed: {response.status} - {error_text}"
+                        logger.error(error_msg)
+                        yield ErrorFrame(error=error_msg)
+
+            finally:
+                if should_close_session and session:
+                    await session.close()
+
+        except asyncio.TimeoutError:
+            error_msg = "Hamsa STT request timed out"
+            logger.error(error_msg)
+            yield ErrorFrame(error=error_msg)
+
+        except aiohttp.ClientError as e:
+            error_msg = f"Hamsa STT client error: {str(e)}"
+            logger.error(error_msg)
+            yield ErrorFrame(error=error_msg)
+
+        except Exception as e:
+            error_msg = f"Hamsa STT unexpected error: {str(e)}"
+            logger.error(error_msg)
+            yield ErrorFrame(error=error_msg)

pipecat/services/heygen/__init__.py

@@ -0,0 +1,5 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#

pipecat/services/heygen/api.py

@@ -0,0 +1,281 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""HeyGen API.
+
+API to communicate with HeyGen Streaming API.
+"""
+
+from enum import Enum
+from typing import Any, Dict, Literal, Optional
+
+import aiohttp
+from loguru import logger
+from pydantic import BaseModel, Field
+
+
+class AvatarQuality(str, Enum):
+    """Enum representing different avatar quality levels."""
+
+    low = "low"
+    medium = "medium"
+    high = "high"
+
+
+class VideoEncoding(str, Enum):
+    """Enum representing the video encoding."""
+
+    H264 = "H264"
+    VP8 = "VP8"
+
+
+class VoiceEmotion(str, Enum):
+    """Enum representing different voice emotion types."""
+
+    EXCITED = "excited"
+    SERIOUS = "serious"
+    FRIENDLY = "friendly"
+    SOOTHING = "soothing"
+    BROADCASTER = "broadcaster"
+
+
+class ElevenLabsSettings(BaseModel):
+    """Settings for ElevenLabs voice configuration.
+
+    Parameters:
+        stability (Optional[float]): Stability of the voice synthesis.
+        similarity_boost (Optional[float]): Adjustment for similarity in voice performance.
+        model_id (Optional[str]): Identifier for the ElevenLabs model to use.
+        style (Optional[int]): Style metric to apply for the voice.
+        use_speaker_boost (Optional[bool]): Flag to enable speaker boost.
+    """
+
+    stability: Optional[float] = None
+    similarity_boost: Optional[float] = None
+    model_id: Optional[str] = None
+    style: Optional[int] = None
+    use_speaker_boost: Optional[bool] = None
+
+
+class VoiceSettings(BaseModel):
+    """Voice configuration settings.
+
+    Parameters:
+        voice_id (Optional[str]): ID of the voice to be used.
+        rate (Optional[float]): Speaking rate for the voice.
+        emotion (Optional[VoiceEmotion]): Emotion tone for the voice.
+        elevenlabs_settings (Optional[ElevenLabsSettings]): Details for ElevenLabs configuration.
+    """
+
+    voice_id: Optional[str] = Field(None, alias="voiceId")
+    rate: Optional[float] = None
+    emotion: Optional[VoiceEmotion] = None
+    elevenlabs_settings: Optional[ElevenLabsSettings] = Field(None, alias="elevenlabsSettings")
+
+
+class NewSessionRequest(BaseModel):
+    """Requesting model for creating a new HeyGen session.
+
+    Parameters:
+        quality (Optional[AvatarQuality]): Desired quality of the avatar.
+        avatar_id (Optional[str]): Unique identifier for the avatar.
+        voice (Optional[VoiceSettings]): Voice configurations for the session.
+        video_encoding (Optional[VideoEncoding]): Desired encoding for the video stream.
+        knowledge_id (Optional[str]): Identifier for the knowledge base (if applicable).
+        knowledge_base (Optional[str]): Details of any external knowledge base.
+        version (Literal["v2"]): API version to use.
+        disable_idle_timeout (Optional[bool]): Flag to disable automatic idle timeout.
+        activity_idle_timeout (Optional[int]): Timeout in seconds for activity-based idle detection.
+    """
+
+    quality: Optional[AvatarQuality] = None
+    avatar_id: Optional[str] = None
+    voice: Optional[VoiceSettings] = None
+    video_encoding: Optional[VideoEncoding] = None
+    knowledge_id: Optional[str] = None
+    knowledge_base: Optional[str] = None
+    version: Literal["v2"] = "v2"
+    disable_idle_timeout: Optional[bool] = None
+    activity_idle_timeout: Optional[int] = None
+
+
+class HeyGenSession(BaseModel):
+    """Response model for a HeyGen session.
+
+    Parameters:
+        session_id (str): Unique identifier for the streaming session.
+        access_token (str): Token for accessing the session securely.
+        realtime_endpoint (str): Real-time communication endpoint URL.
+        url (str): Direct URL for the session.
+    """
+
+    session_id: str
+    access_token: str
+    realtime_endpoint: str
+    url: str
+
+
+class HeygenApiError(Exception):
+    """Custom exception for HeyGen API errors."""
+
+    def __init__(self, message: str, status: int, response_text: str) -> None:
+        """Initialize the HeyGen API error.
+
+        Args:
+            message: Error message
+            status: HTTP status code
+            response_text: Raw response text from the API
+        """
+        super().__init__(message)
+        self.status = status
+        self.response_text = response_text
+
+
+class HeyGenApi:
+    """HeyGen Streaming API client."""
+
+    BASE_URL = "https://api.heygen.com/v1"
+
+    def __init__(self, api_key: str, session: aiohttp.ClientSession) -> None:
+        """Initialize the HeyGen API.
+
+        Args:
+            api_key: HeyGen API key
+            session: Optional aiohttp client session
+        """
+        self.api_key = api_key
+        self.session = session
+
+    async def _request(self, path: str, params: Dict[str, Any], expect_data: bool = True) -> Any:
+        """Make a POST request to the HeyGen API.
+
+        Args:
+            path: API endpoint path.
+            params: JSON-serializable parameters.
+            expect_data: Whether to expect and extract 'data' field from response (default: True).
+
+        Returns:
+            Parsed JSON response data.
+
+        Raises:
+            HeygenApiError: If the API response is not successful or data is missing when expected.
+            aiohttp.ClientError: For network-related errors.
+        """
+        url = f"{self.BASE_URL}{path}"
+        headers = {
+            "x-api-key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+        logger.debug(f"HeyGen API request: {url}")
+
+        try:
+            async with self.session.post(url, json=params, headers=headers) as response:
+                if not response.ok:
+                    response_text = await response.text()
+                    logger.error(f"HeyGen API error: {response_text}")
+                    raise HeygenApiError(
+                        f"API request failed with status {response.status}",
+                        response.status,
+                        response_text,
+                    )
+                if expect_data:
+                    json_data = await response.json()
+                    data = json_data.get("data")
+                    return data
+                return await response.text()
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error while calling HeyGen API: {str(e)}")
+            raise
+
+    async def new_session(self, request_data: NewSessionRequest) -> HeyGenSession:
+        """Create a new streaming session.
+
+        https://docs.heygen.com/reference/new-session
+
+        Args:
+            request_data: Session configuration parameters.
+
+        Returns:
+            Session information, including ID and access token.
+        """
+        params = {
+            "quality": request_data.quality,
+            "avatar_id": request_data.avatar_id,
+            "voice": {
+                "voice_id": request_data.voice.voiceId if request_data.voice else None,
+                "rate": request_data.voice.rate if request_data.voice else None,
+                "emotion": request_data.voice.emotion if request_data.voice else None,
+                "elevenlabs_settings": (
+                    request_data.voice.elevenlabsSettings if request_data.voice else None
+                ),
+            },
+            "knowledge_id": request_data.knowledge_id,
+            "knowledge_base": request_data.knowledge_base,
+            "version": request_data.version,
+            "video_encoding": request_data.video_encoding,
+            "disable_idle_timeout": request_data.disable_idle_timeout,
+            "activity_idle_timeout": request_data.activity_idle_timeout,
+        }
+        session_info = await self._request("/streaming.new", params)
+        print("heygen session info", session_info)
+
+        return HeyGenSession.model_validate(session_info)
+
+    async def start_session(self, session_id: str) -> Any:
+        """Start the streaming session.
+
+        https://docs.heygen.com/reference/start-session
+
+        Args:
+            session_id: ID of the session to start.
+
+        Returns:
+            Response data from the start session API call.
+
+        Raises:
+            ValueError: If session ID is not set.
+        """
+        if not session_id:
+            raise ValueError("Session ID is not set. Call new_session first.")
+
+        params = {
+            "session_id": session_id,
+        }
+        return await self._request("/streaming.start", params)
+
+    async def close_session(self, session_id: str) -> Any:
+        """Terminate an active the streaming session.
+
+        https://docs.heygen.com/reference/close-session
+
+        Args:
+            session_id: ID of the session to stop.
+
+        Returns:
+            Response data from the stop session API call.
+
+        Raises:
+            ValueError: If session ID is not set.
+        """
+        if not session_id:
+            raise ValueError("Session ID is not set. Call new_session first.")
+
+        params = {
+            "session_id": session_id,
+        }
+        return await self._request("/streaming.stop", params, expect_data=False)
+
+    async def create_token(self) -> str:
+        """Create a streaming token.
+
+        https://docs.heygen.com/reference/streaming-token
+
+        Returns:
+            str: The generated access token for the streaming session
+        """
+        token_info = await self._request("/streaming.create_token", {})
+        return token_info["token"]