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

pipecat/services/cartesia/tts.py

@@ -30,15 +30,19 @@ from pipecat.frames.frames import (
 from pipecat.processors.frame_processor import FrameDirection
 from pipecat.services.tts_service import AudioContextWordTTSService, TTSService
 from pipecat.transcriptions.language import Language
-from pipecat.utils.asyncio.watchdog_async_iterator import WatchdogAsyncIterator
 from pipecat.utils.text.base_text_aggregator import BaseTextAggregator
 from pipecat.utils.text.skip_tags_aggregator import SkipTagsAggregator
 from pipecat.utils.tracing.service_decorators import traced_tts
 
+# Suppress regex warnings from pydub (used by cartesia)
+warnings.filterwarnings("ignore", message="invalid escape sequence", category=SyntaxWarning)
+
+
 # See .env.example for Cartesia configuration needed
 try:
-    import websockets
     from cartesia import AsyncCartesia
+    from websockets.asyncio.client import connect as websocket_connect
+    from websockets.protocol import State
 except ModuleNotFoundError as e:
     logger.error(f"Exception: {e}")
     logger.error("In order to use Cartesia, you need to `pip install pipecat-ai[cartesia]`.")
@@ -91,19 +95,6 @@ class CartesiaTTSService(AudioContextWordTTSService):
     Provides text-to-speech using Cartesia's streaming WebSocket API.
     Supports word-level timestamps, audio context management, and various voice
     customization options including speed and emotion controls.
-
-    Args:
-        api_key: Cartesia API key for authentication.
-        voice_id: ID of the voice to use for synthesis.
-        cartesia_version: API version string for Cartesia service.
-        url: WebSocket URL for Cartesia TTS API.
-        model: TTS model to use (e.g., "sonic-2").
-        sample_rate: Audio sample rate. If None, uses default.
-        encoding: Audio encoding format.
-        container: Audio container format.
-        params: Additional input parameters for voice customization.
-        text_aggregator: Custom text aggregator for processing input text.
-        **kwargs: Additional arguments passed to the parent service.
     """
 
     class InputParams(BaseModel):
@@ -112,7 +103,10 @@ class CartesiaTTSService(AudioContextWordTTSService):
         Parameters:
             language: Language to use for synthesis.
             speed: Voice speed control (string or float).
-            emotion: List of emotion controls (deprecated).
+            emotion: List of emotion controls.
+
+                .. deprecated:: 0.0.68
+                        The `emotion` parameter is deprecated and will be removed in a future version.
         """
 
         language: Optional[Language] = Language.EN
@@ -132,8 +126,25 @@ class CartesiaTTSService(AudioContextWordTTSService):
         container: str = "raw",
         params: Optional[InputParams] = None,
         text_aggregator: Optional[BaseTextAggregator] = None,
+        aggregate_sentences: Optional[bool] = True,
         **kwargs,
     ):
+        """Initialize the Cartesia TTS service.
+
+        Args:
+            api_key: Cartesia API key for authentication.
+            voice_id: ID of the voice to use for synthesis.
+            cartesia_version: API version string for Cartesia service.
+            url: WebSocket URL for Cartesia TTS API.
+            model: TTS model to use (e.g., "sonic-2").
+            sample_rate: Audio sample rate. If None, uses default.
+            encoding: Audio encoding format.
+            container: Audio container format.
+            params: Additional input parameters for voice customization.
+            text_aggregator: Custom text aggregator for processing input text.
+            aggregate_sentences: Whether to aggregate sentences within the TTSService.
+            **kwargs: Additional arguments passed to the parent service.
+        """
         # Aggregating sentences still gives cleaner-sounding results and fewer
         # artifacts than streaming one word at a time. On average, waiting for a
         # full sentence should only "cost" us 15ms or so with GPT-4o or a Llama
@@ -145,7 +156,7 @@ class CartesiaTTSService(AudioContextWordTTSService):
         # can use those to generate text frames ourselves aligned with the
         # playout timing of the audio!
         super().__init__(
-            aggregate_sentences=True,
+            aggregate_sentences=aggregate_sentences,
             push_text_frames=False,
             pause_frame_processing=True,
             sample_rate=sample_rate,
@@ -205,6 +216,54 @@ class CartesiaTTSService(AudioContextWordTTSService):
         """
         return language_to_cartesia_language(language)
 
+    def _is_cjk_language(self, language: str) -> bool:
+        """Check if the given language is CJK (Chinese, Japanese, Korean).
+
+        Args:
+            language: The language code to check.
+
+        Returns:
+            True if the language is Chinese, Japanese, or Korean.
+        """
+        cjk_languages = {"zh", "ja", "ko"}
+        base_lang = language.split("-")[0].lower()
+        return base_lang in cjk_languages
+
+    def _process_word_timestamps_for_language(
+        self, words: List[str], starts: List[float]
+    ) -> List[tuple[str, float]]:
+        """Process word timestamps based on the current language.
+
+        For CJK languages, Cartesia groups related characters in the same timestamp message.
+        For example, in Japanese a single message might be `['こ', 'ん', 'に', 'ち', 'は', '。']`.
+        We combine these into single words so the downstream aggregator can add natural
+        spacing between meaningful units rather than individual characters.
+
+        For non-CJK languages, words are already properly separated and are used as-is.
+
+        Args:
+            words: List of words/characters from Cartesia.
+            starts: List of start timestamps for each word/character.
+
+        Returns:
+            List of (word, start_time) tuples processed for the language.
+        """
+        current_language = self._settings.get("language", "en")
+
+        # Check if this is a CJK language
+        if self._is_cjk_language(current_language):
+            # For CJK languages, combine all characters in this message into one word
+            # using the first character's start time
+            if words and starts:
+                combined_word = "".join(words)
+                first_start = starts[0]
+                return [(combined_word, first_start)]
+            else:
+                return []
+        else:
+            # For non-CJK languages, use as-is
+            return list(zip(words, starts))
+
     def _build_msg(
         self, text: str = "", continue_transcript: bool = True, add_timestamps: bool = True
     ):
@@ -282,10 +341,10 @@ class CartesiaTTSService(AudioContextWordTTSService):
 
     async def _connect_websocket(self):
         try:
-            if self._websocket and self._websocket.open:
+            if self._websocket and self._websocket.state is State.OPEN:
                 return
             logger.debug("Connecting to Cartesia")
-            self._websocket = await websockets.connect(
+            self._websocket = await websocket_connect(
                 f"{self._url}?api_key={self._api_key}&cartesia_version={self._cartesia_version}"
             )
         except Exception as e:
@@ -329,9 +388,7 @@ class CartesiaTTSService(AudioContextWordTTSService):
         self._context_id = None
 
     async def _receive_messages(self):
-        async for message in WatchdogAsyncIterator(
-            self._get_websocket(), manager=self.task_manager
-        ):
+        async for message in self._get_websocket():
             msg = json.loads(message)
             if not msg or not self.audio_context_available(msg["context_id"]):
                 continue
@@ -340,9 +397,11 @@ class CartesiaTTSService(AudioContextWordTTSService):
                 await self.add_word_timestamps([("TTSStoppedFrame", 0), ("Reset", 0)])
                 await self.remove_audio_context(msg["context_id"])
             elif msg["type"] == "timestamps":
-                await self.add_word_timestamps(
-                    list(zip(msg["word_timestamps"]["words"], msg["word_timestamps"]["start"]))
+                # Process the timestamps based on language before adding them
+                processed_timestamps = self._process_word_timestamps_for_language(
+                    msg["word_timestamps"]["words"], msg["word_timestamps"]["start"]
                 )
+                await self.add_word_timestamps(processed_timestamps)
             elif msg["type"] == "chunk":
                 await self.stop_ttfb_metrics()
                 self.start_word_timestamps()
@@ -375,7 +434,7 @@ class CartesiaTTSService(AudioContextWordTTSService):
         logger.debug(f"{self}: Generating TTS [{text}]")
 
         try:
-            if not self._websocket or self._websocket.closed:
+            if not self._websocket or self._websocket.state is State.CLOSED:
                 await self._connect()
 
             if not self._context_id:
@@ -406,18 +465,6 @@ class CartesiaHttpTTSService(TTSService):
     Provides text-to-speech using Cartesia's HTTP API for simpler, non-streaming
     synthesis. Suitable for use cases where streaming is not required and simpler
     integration is preferred.
-
-    Args:
-        api_key: Cartesia API key for authentication.
-        voice_id: ID of the voice to use for synthesis.
-        model: TTS model to use (e.g., "sonic-2").
-        base_url: Base URL for Cartesia HTTP API.
-        cartesia_version: API version string for Cartesia service.
-        sample_rate: Audio sample rate. If None, uses default.
-        encoding: Audio encoding format.
-        container: Audio container format.
-        params: Additional input parameters for voice customization.
-        **kwargs: Additional arguments passed to the parent TTSService.
     """
 
     class InputParams(BaseModel):
@@ -426,7 +473,10 @@ class CartesiaHttpTTSService(TTSService):
         Parameters:
             language: Language to use for synthesis.
             speed: Voice speed control (string or float).
-            emotion: List of emotion controls (deprecated).
+            emotion: List of emotion controls.
+
+                .. deprecated:: 0.0.68
+                        The `emotion` parameter is deprecated and will be removed in a future version.
         """
 
         language: Optional[Language] = Language.EN
@@ -447,6 +497,20 @@ class CartesiaHttpTTSService(TTSService):
         params: Optional[InputParams] = None,
         **kwargs,
     ):
+        """Initialize the Cartesia HTTP TTS service.
+
+        Args:
+            api_key: Cartesia API key for authentication.
+            voice_id: ID of the voice to use for synthesis.
+            model: TTS model to use (e.g., "sonic-2").
+            base_url: Base URL for Cartesia HTTP API.
+            cartesia_version: API version string for Cartesia service.
+            sample_rate: Audio sample rate. If None, uses default.
+            encoding: Audio encoding format.
+            container: Audio container format.
+            params: Additional input parameters for voice customization.
+            **kwargs: Additional arguments passed to the parent TTSService.
+        """
         super().__init__(sample_rate=sample_rate, **kwargs)
 
         params = params or CartesiaHttpTTSService.InputParams()

pipecat/services/cerebras/llm.py

@@ -9,8 +9,7 @@
 from typing import List
 
 from loguru import logger
-from openai import AsyncStream
-from openai.types.chat import ChatCompletionChunk, ChatCompletionMessageParam
+from openai.types.chat import ChatCompletionMessageParam
 
 from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
 from pipecat.services.openai.llm import OpenAILLMService
@@ -21,12 +20,6 @@ class CerebrasLLMService(OpenAILLMService):
 
     This service extends OpenAILLMService to connect to Cerebras's API endpoint while
     maintaining full compatibility with OpenAI's interface and functionality.
-
-    Args:
-        api_key: The API key for accessing Cerebras's API.
-        base_url: The base URL for Cerebras API. Defaults to "https://api.cerebras.ai/v1".
-        model: The model identifier to use. Defaults to "llama-3.3-70b".
-        **kwargs: Additional keyword arguments passed to OpenAILLMService.
     """
 
     def __init__(
@@ -37,6 +30,14 @@ class CerebrasLLMService(OpenAILLMService):
         model: str = "llama-3.3-70b",
         **kwargs,
     ):
+        """Initialize the Cerebras LLM service.
+
+        Args:
+            api_key: The API key for accessing Cerebras's API.
+            base_url: The base URL for Cerebras API. Defaults to "https://api.cerebras.ai/v1".
+            model: The model identifier to use. Defaults to "llama-3.3-70b".
+            **kwargs: Additional keyword arguments passed to OpenAILLMService.
+        """
         super().__init__(api_key=api_key, base_url=base_url, model=model, **kwargs)
 
     def create_client(self, api_key=None, base_url=None, **kwargs):
@@ -53,20 +54,13 @@ class CerebrasLLMService(OpenAILLMService):
         logger.debug(f"Creating Cerebras client with api {base_url}")
         return super().create_client(api_key, base_url, **kwargs)
 
-    async def get_chat_completions(
+    def build_chat_completion_params(
         self, context: OpenAILLMContext, messages: List[ChatCompletionMessageParam]
-    ) -> AsyncStream[ChatCompletionChunk]:
-        """Create a streaming chat completion using Cerebras's API.
+    ) -> dict:
+        """Build parameters for Cerebras chat completion request.
 
-        Args:
-            context: The context object containing tools configuration
-                and other settings for the chat completion.
-            messages: The list of messages comprising
-                the conversation history and current request.
-
-        Returns:
-            A streaming response of chat completion
-                chunks that can be processed asynchronously.
+        Cerebras supports a subset of OpenAI parameters, focusing on core
+        completion settings without advanced features like frequency/presence penalties.
         """
         params = {
             "model": self.model_name,
@@ -81,6 +75,4 @@ class CerebrasLLMService(OpenAILLMService):
         }
 
         params.update(self._settings["extra"])
-
-        chunks = await self._client.chat.completions.create(**params)
-        return chunks
+        return params

pipecat/services/deepgram/stt.py

@@ -15,6 +15,7 @@ from loguru import logger
 from pipecat.frames.frames import (
     CancelFrame,
     EndFrame,
+    ErrorFrame,
     Frame,
     InterimTranscriptionFrame,
     StartFrame,
@@ -50,15 +51,6 @@ class DeepgramSTTService(STTService):
     Provides real-time speech recognition using Deepgram's WebSocket API.
     Supports configurable models, languages, VAD events, and various audio
     processing options.
-
-    Args:
-        api_key: Deepgram API key for authentication.
-        url: Deprecated. Use base_url instead.
-        base_url: Custom Deepgram API base URL.
-        sample_rate: Audio sample rate. If None, uses default or live_options value.
-        live_options: Deepgram LiveOptions for detailed configuration.
-        addons: Additional Deepgram features to enable.
-        **kwargs: Additional arguments passed to the parent STTService.
     """
 
     def __init__(
@@ -72,6 +64,21 @@ class DeepgramSTTService(STTService):
         addons: Optional[Dict] = None,
         **kwargs,
     ):
+        """Initialize the Deepgram STT service.
+
+        Args:
+            api_key: Deepgram API key for authentication.
+            url: Custom Deepgram API base URL.
+
+                .. deprecated:: 0.0.64
+                    Parameter `url` is deprecated, use `base_url` instead.
+
+            base_url: Custom Deepgram API base URL.
+            sample_rate: Audio sample rate. If None, uses default or live_options value.
+            live_options: Deepgram LiveOptions for detailed configuration.
+            addons: Additional Deepgram features to enable.
+            **kwargs: Additional arguments passed to the parent STTService.
+        """
         sample_rate = sample_rate or (live_options.sample_rate if live_options else None)
         super().__init__(sample_rate=sample_rate, **kwargs)
 
@@ -279,6 +286,7 @@ class DeepgramSTTService(STTService):
     async def _on_error(self, *args, **kwargs):
         error: ErrorResponse = kwargs["error"]
         self.logger.warning(f"{self} connection error, will retry: {error}")
+        await self.push_error(ErrorFrame(f"{error}"))
         await self.stop_all_metrics()
         # NOTE(aleix): we don't disconnect (i.e. call finish on the connection)
         # because this triggers more errors internally in the Deepgram SDK. So,
@@ -316,7 +324,7 @@ class DeepgramSTTService(STTService):
                 await self.push_frame(
                     TranscriptionFrame(
                         transcript,
-                        "",
+                        self._user_id,
                         time_now_iso8601(),
                         language,
                         result=result,
@@ -330,7 +338,7 @@ class DeepgramSTTService(STTService):
                 await self.push_frame(
                     InterimTranscriptionFrame(
                         transcript,
-                        "",
+                        self._user_id,
                         time_now_iso8601(),
                         language,
                         result=result,

pipecat/services/deepgram/tts.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Deepgram text-to-speech service implementation.
+
+This module provides integration with Deepgram's text-to-speech API
+for generating speech from text using various voice models.
+"""
+
 from typing import AsyncGenerator, Optional
 
 from loguru import logger
@@ -27,6 +33,13 @@ except ModuleNotFoundError as e:
 
 
 class DeepgramTTSService(TTSService):
+    """Deepgram text-to-speech service.
+
+    Provides text-to-speech synthesis using Deepgram's streaming API.
+    Supports various voice models and audio encoding formats with
+    configurable sample rates and quality settings.
+    """
+
     def __init__(
         self,
         *,
@@ -37,6 +50,16 @@ class DeepgramTTSService(TTSService):
         encoding: str = "linear16",
         **kwargs,
     ):
+        """Initialize the Deepgram TTS service.
+
+        Args:
+            api_key: Deepgram API key for authentication.
+            voice: Voice model to use for synthesis. Defaults to "aura-2-helena-en".
+            base_url: Custom base URL for Deepgram API. Uses default if empty.
+            sample_rate: Audio sample rate in Hz. If None, uses service default.
+            encoding: Audio encoding format. Defaults to "linear16".
+            **kwargs: Additional arguments passed to parent TTSService class.
+        """
         super().__init__(sample_rate=sample_rate, **kwargs)
 
         self._settings = {
@@ -48,10 +71,23 @@ class DeepgramTTSService(TTSService):
         self._deepgram_client = DeepgramClient(api_key, config=client_options)
 
     def can_generate_metrics(self) -> bool:
+        """Check if the service can generate metrics.
+
+        Returns:
+            True, as Deepgram TTS service supports metrics generation.
+        """
         return True
 
     @traced_tts
     async def run_tts(self, text: str) -> AsyncGenerator[Frame, None]:
+        """Generate speech from text using Deepgram's TTS API.
+
+        Args:
+            text: The text to synthesize into speech.
+
+        Yields:
+            Frame: Audio frames containing the synthesized speech, plus start/stop frames.
+        """
         logger.debug(f"{self}: Generating TTS [{text}]")
 
         options = SpeakOptions(

pipecat/services/deepseek/llm.py

@@ -9,8 +9,7 @@
 from typing import List
 
 from loguru import logger
-from openai import AsyncStream
-from openai.types.chat import ChatCompletionChunk, ChatCompletionMessageParam
+from openai.types.chat import ChatCompletionMessageParam
 
 from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
 from pipecat.services.openai.llm import OpenAILLMService
@@ -21,12 +20,6 @@ class DeepSeekLLMService(OpenAILLMService):
 
     This service extends OpenAILLMService to connect to DeepSeek's API endpoint while
     maintaining full compatibility with OpenAI's interface and functionality.
-
-    Args:
-        api_key: The API key for accessing DeepSeek's API.
-        base_url: The base URL for DeepSeek API. Defaults to "https://api.deepseek.com/v1".
-        model: The model identifier to use. Defaults to "deepseek-chat".
-        **kwargs: Additional keyword arguments passed to OpenAILLMService.
     """
 
     def __init__(
@@ -37,6 +30,14 @@ class DeepSeekLLMService(OpenAILLMService):
         model: str = "deepseek-chat",
         **kwargs,
     ):
+        """Initialize the DeepSeek LLM service.
+
+        Args:
+            api_key: The API key for accessing DeepSeek's API.
+            base_url: The base URL for DeepSeek API. Defaults to "https://api.deepseek.com/v1".
+            model: The model identifier to use. Defaults to "deepseek-chat".
+            **kwargs: Additional keyword arguments passed to OpenAILLMService.
+        """
         super().__init__(api_key=api_key, base_url=base_url, model=model, **kwargs)
 
     def create_client(self, api_key=None, base_url=None, **kwargs):
@@ -53,20 +54,12 @@ class DeepSeekLLMService(OpenAILLMService):
         logger.debug(f"Creating DeepSeek client with api {base_url}")
         return super().create_client(api_key, base_url, **kwargs)
 
-    async def get_chat_completions(
+    def _build_chat_completion_params(
         self, context: OpenAILLMContext, messages: List[ChatCompletionMessageParam]
-    ) -> AsyncStream[ChatCompletionChunk]:
-        """Create a streaming chat completion using DeepSeek's API.
+    ) -> dict:
+        """Build parameters for DeepSeek chat completion request.
 
-        Args:
-            context: The context object containing tools configuration
-                and other settings for the chat completion.
-            messages: The list of messages comprising the conversation
-                history and current request.
-
-        Returns:
-            A streaming response of chat completion chunks that can be
-            processed asynchronously.
+        DeepSeek doesn't support some OpenAI parameters like seed and max_completion_tokens.
         """
         params = {
             "model": self.model_name,
@@ -83,6 +76,4 @@ class DeepSeekLLMService(OpenAILLMService):
         }
 
         params.update(self._settings["extra"])
-
-        chunks = await self._client.chat.completions.create(**params)
-        return chunks
+        return params