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

pipecat/transports/services/tavus.py

@@ -1,3 +1,16 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Tavus transport implementation for Pipecat.
+
+This module provides integration with the Tavus platform for creating conversational
+AI applications with avatars. It manages conversation sessions and provides real-time
+audio/video streaming capabilities through the Tavus API.
+"""
+
 import os
 from functools import partial
 from typing import Any, Awaitable, Callable, Mapping, Optional
@@ -7,7 +20,6 @@ from daily.daily import AudioData
 from loguru import logger
 from pydantic import BaseModel
 
-from pipecat.audio.utils import create_default_resampler
 from pipecat.frames.frames import (
     CancelFrame,
     EndFrame,
@@ -31,8 +43,10 @@ from pipecat.transports.services.daily import (
 
 
 class TavusApi:
-    """
-    A helper class for interacting with the Tavus API (v2).
+    """Helper class for interacting with the Tavus API (v2).
+
+    Provides methods for creating and managing conversations with Tavus avatars,
+    including conversation lifecycle management and persona information retrieval.
     """
 
     BASE_URL = "https://tavusapi.com/v2"
@@ -40,12 +54,11 @@ class TavusApi:
     MOCK_PERSONA_NAME = "TestTavusTransport"
 
     def __init__(self, api_key: str, session: aiohttp.ClientSession):
-        """
-        Initialize the TavusApi client.
+        """Initialize the TavusApi client.
 
         Args:
-            api_key (str): Tavus API key.
-            session (aiohttp.ClientSession): An aiohttp session for making HTTP requests.
+            api_key: Tavus API key for authentication.
+            session: An aiohttp session for making HTTP requests.
         """
         self._api_key = api_key
         self._session = session
@@ -54,6 +67,15 @@ class TavusApi:
         self._dev_room_url = os.getenv("TAVUS_SAMPLE_ROOM_URL")
 
     async def create_conversation(self, replica_id: str, persona_id: str) -> dict:
+        """Create a new conversation with the specified replica and persona.
+
+        Args:
+            replica_id: ID of the replica to use in the conversation.
+            persona_id: ID of the persona to use in the conversation.
+
+        Returns:
+            Dictionary containing conversation_id and conversation_url.
+        """
         if self._dev_room_url:
             return {
                 "conversation_id": self.MOCK_CONVERSATION_ID,
@@ -73,6 +95,11 @@ class TavusApi:
             return response
 
     async def end_conversation(self, conversation_id: str):
+        """End an existing conversation.
+
+        Args:
+            conversation_id: ID of the conversation to end.
+        """
         if conversation_id is None or conversation_id == self.MOCK_CONVERSATION_ID:
             return
 
@@ -82,6 +109,14 @@ class TavusApi:
             logger.debug(f"Ended Tavus conversation {conversation_id}")
 
     async def get_persona_name(self, persona_id: str) -> str:
+        """Get the name of a persona by ID.
+
+        Args:
+            persona_id: ID of the persona to retrieve.
+
+        Returns:
+            The name of the persona.
+        """
         if self._dev_room_url is not None:
             return self.MOCK_PERSONA_NAME
 
@@ -94,11 +129,11 @@ class TavusApi:
 
 
 class TavusCallbacks(BaseModel):
-    """Callback handlers for the Tavus events.
+    """Callback handlers for Tavus events.
 
-    Attributes:
-        on_participant_joined: Called when a participant joins.
-        on_participant_left: Called when a participant leaves.
+    Parameters:
+        on_participant_joined: Called when a participant joins the conversation.
+        on_participant_left: Called when a participant leaves the conversation.
     """
 
     on_participant_joined: Callable[[Mapping[str, Any]], Awaitable[None]]
@@ -106,7 +141,13 @@ class TavusCallbacks(BaseModel):
 
 
 class TavusParams(DailyParams):
-    """Configuration parameters for the Tavus transport."""
+    """Configuration parameters for the Tavus transport.
+
+    Parameters:
+        audio_in_enabled: Whether to enable audio input from participants.
+        audio_out_enabled: Whether to enable audio output to participants.
+        microphone_out_enabled: Whether to enable microphone output track.
+    """
 
     audio_in_enabled: bool = True
     audio_out_enabled: bool = True
@@ -114,24 +155,14 @@ class TavusParams(DailyParams):
 
 
 class TavusTransportClient:
-    """
+    """Transport client that integrates Pipecat with the Tavus platform.
+
     A transport client that integrates a Pipecat Bot with the Tavus platform by managing
     conversation sessions using the Tavus API.
 
     This client uses `TavusApi` to interact with the Tavus backend services. When a conversation
     is started via `TavusApi`, Tavus provides a `roomURL` that can be used to connect the Pipecat Bot
     into the same virtual room where the TavusBot is operating.
-
-    Args:
-        bot_name (str): The name of the Pipecat bot instance.
-        params (TavusParams): Optional parameters for Tavus operation. Defaults to `TavusParams()`.
-        callbacks (TavusCallbacks): Callback handlers for Tavus-related events.
-        api_key (str): API key for authenticating with Tavus API.
-        replica_id (str): ID of the replica to use in the Tavus conversation.
-        persona_id (str): ID of the Tavus persona. Defaults to "pipecat-stream", which signals Tavus to use
-                          the TTS voice of the Pipecat bot instead of a Tavus persona voice.
-        session (aiohttp.ClientSession): The aiohttp session for making async HTTP requests.
-        sample_rate: Audio sample rate to be used by the client.
     """
 
     def __init__(
@@ -145,6 +176,19 @@ class TavusTransportClient:
         persona_id: str = "pipecat-stream",
         session: aiohttp.ClientSession,
     ) -> None:
+        """Initialize the Tavus transport client.
+
+        Args:
+            bot_name: The name of the Pipecat bot instance.
+            params: Optional parameters for Tavus operation.
+            callbacks: Callback handlers for Tavus-related events.
+            api_key: API key for authenticating with Tavus API.
+            replica_id: ID of the replica to use in the Tavus conversation.
+            persona_id: ID of the Tavus persona. Defaults to "pipecat-stream",
+                which signals Tavus to use the TTS voice of the Pipecat bot
+                instead of a Tavus persona voice.
+            session: The aiohttp session for making async HTTP requests.
+        """
         self._bot_name = bot_name
         self._api = TavusApi(api_key, session)
         self._replica_id = replica_id
@@ -155,11 +199,17 @@ class TavusTransportClient:
         self._params = params
 
     async def _initialize(self) -> str:
+        """Initialize the conversation and return the room URL."""
         response = await self._api.create_conversation(self._replica_id, self._persona_id)
         self._conversation_id = response["conversation_id"]
         return response["conversation_url"]
 
     async def setup(self, setup: FrameProcessorSetup):
+        """Setup the client and initialize the conversation.
+
+        Args:
+            setup: The frame processor setup configuration.
+        """
         if self._conversation_id is not None:
             logger.debug(f"Conversation ID already defined: {self._conversation_id}")
             return
@@ -195,6 +245,10 @@ class TavusTransportClient:
                 on_recording_started=partial(self._on_handle_callback, "on_recording_started"),
                 on_recording_stopped=partial(self._on_handle_callback, "on_recording_stopped"),
                 on_recording_error=partial(self._on_handle_callback, "on_recording_error"),
+                on_transcription_stopped=partial(
+                    self._on_handle_callback, "on_transcription_stopped"
+                ),
+                on_transcription_error=partial(self._on_handle_callback, "on_transcription_error"),
             )
             self._client = DailyTransportClient(
                 room_url, None, "Pipecat", self._params, daily_callbacks, self._bot_name
@@ -206,29 +260,44 @@ class TavusTransportClient:
             self._conversation_id = None
 
     async def cleanup(self):
+        """Cleanup client resources."""
         try:
             await self._client.cleanup()
         except Exception as e:
             logger.exception(f"Exception during cleanup: {e}")
 
     async def _on_joined(self, data):
+        """Handle joined event."""
         logger.debug("TavusTransportClient joined!")
 
     async def _on_left(self):
+        """Handle left event."""
         logger.debug("TavusTransportClient left!")
 
     async def _on_handle_callback(self, event_name, *args, **kwargs):
+        """Handle generic callback events."""
         logger.trace(f"[Callback] {event_name} called with args={args}, kwargs={kwargs}")
 
     async def get_persona_name(self) -> str:
+        """Get the persona name from the API.
+
+        Returns:
+            The name of the current persona.
+        """
         return await self._api.get_persona_name(self._persona_id)
 
     async def start(self, frame: StartFrame):
+        """Start the client and join the room.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         logger.debug("TavusTransportClient start invoked!")
         await self._client.start(frame)
         await self._client.join()
 
     async def stop(self):
+        """Stop the client and end the conversation."""
         await self._client.leave()
         await self._api.end_conversation(self._conversation_id)
         self._conversation_id = None
@@ -241,6 +310,15 @@ class TavusTransportClient:
         video_source: str = "camera",
         color_format: str = "RGB",
     ):
+        """Capture video from a participant.
+
+        Args:
+            participant_id: ID of the participant to capture video from.
+            callback: Callback function to handle video frames.
+            framerate: Desired framerate for video capture.
+            video_source: Video source to capture from.
+            color_format: Color format for video frames.
+        """
         await self._client.capture_participant_video(
             participant_id, callback, framerate, video_source, color_format
         )
@@ -253,22 +331,47 @@ class TavusTransportClient:
         sample_rate: int = 16000,
         callback_interval_ms: int = 20,
     ):
+        """Capture audio from a participant.
+
+        Args:
+            participant_id: ID of the participant to capture audio from.
+            callback: Callback function to handle audio data.
+            audio_source: Audio source to capture from.
+            sample_rate: Desired sample rate for audio capture.
+            callback_interval_ms: Interval between audio callbacks in milliseconds.
+        """
         await self._client.capture_participant_audio(
             participant_id, callback, audio_source, sample_rate, callback_interval_ms
         )
 
     async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+        """Send a message to participants.
+
+        Args:
+            frame: The message frame to send.
+        """
         await self._client.send_message(frame)
 
     @property
     def out_sample_rate(self) -> int:
+        """Get the output sample rate.
+
+        Returns:
+            The output sample rate in Hz.
+        """
         return self._client.out_sample_rate
 
     @property
     def in_sample_rate(self) -> int:
+        """Get the input sample rate.
+
+        Returns:
+            The input sample rate in Hz.
+        """
         return self._client.in_sample_rate
 
     async def send_interrupt_message(self) -> None:
+        """Send an interrupt message to the conversation."""
         transport_frame = TransportMessageUrgentFrame(
             message={
                 "message_type": "conversation",
@@ -279,6 +382,12 @@ class TavusTransportClient:
         await self.send_message(transport_frame)
 
     async def update_subscriptions(self, participant_settings=None, profile_settings=None):
+        """Update subscription settings for participants.
+
+        Args:
+            participant_settings: Per-participant subscription settings.
+            profile_settings: Global subscription profile settings.
+        """
         if not self._client:
             return
 
@@ -287,11 +396,21 @@ class TavusTransportClient:
         )
 
     async def write_audio_frame(self, frame: OutputAudioRawFrame):
+        """Write an audio frame to the transport.
+
+        Args:
+            frame: The audio frame to write.
+        """
         if not self._client:
             return
         await self._client.write_audio_frame(frame)
 
     async def register_audio_destination(self, destination: str):
+        """Register an audio destination for output.
+
+        Args:
+            destination: The destination identifier to register.
+        """
         if not self._client:
             return
 
@@ -299,29 +418,51 @@ class TavusTransportClient:
 
 
 class TavusInputTransport(BaseInputTransport):
+    """Input transport for receiving audio and events from Tavus conversations.
+
+    Handles incoming audio streams from participants and manages audio capture
+    from the Daily room connected to the Tavus conversation.
+    """
+
     def __init__(
         self,
         client: TavusTransportClient,
         params: TransportParams,
         **kwargs,
     ):
+        """Initialize the Tavus input transport.
+
+        Args:
+            client: The Tavus transport client instance.
+            params: Transport configuration parameters.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(params, **kwargs)
         self._client = client
         self._params = params
-        self._resampler = create_default_resampler()
-
         # Whether we have seen a StartFrame already.
         self._initialized = False
 
     async def setup(self, setup: FrameProcessorSetup):
+        """Setup the input transport.
+
+        Args:
+            setup: The frame processor setup configuration.
+        """
         await super().setup(setup)
         await self._client.setup(setup)
 
     async def cleanup(self):
+        """Cleanup input transport resources."""
         await super().cleanup()
         await self._client.cleanup()
 
     async def start(self, frame: StartFrame):
+        """Start the input transport.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._initialized:
@@ -333,14 +474,29 @@ class TavusInputTransport(BaseInputTransport):
         await self.set_transport_ready(frame)
 
     async def stop(self, frame: EndFrame):
+        """Stop the input transport.
+
+        Args:
+            frame: The end frame signaling transport shutdown.
+        """
         await super().stop(frame)
         await self._client.stop()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the input transport.
+
+        Args:
+            frame: The cancel frame signaling immediate cancellation.
+        """
         await super().cancel(frame)
         await self._client.stop()
 
     async def start_capturing_audio(self, participant):
+        """Start capturing audio from a participant.
+
+        Args:
+            participant: The participant to capture audio from.
+        """
         if self._params.audio_in_enabled:
             logger.info(
                 f"TavusTransportClient start capturing audio for participant {participant['id']}"
@@ -354,6 +510,7 @@ class TavusInputTransport(BaseInputTransport):
     async def _on_participant_audio_data(
         self, participant_id: str, audio: AudioData, audio_source: str
     ):
+        """Handle received participant audio data."""
         frame = InputAudioRawFrame(
             audio=audio.audio_frames,
             sample_rate=audio.audio_frames,
@@ -364,12 +521,25 @@ class TavusInputTransport(BaseInputTransport):
 
 
 class TavusOutputTransport(BaseOutputTransport):
+    """Output transport for sending audio and events to Tavus conversations.
+
+    Handles outgoing audio streams to participants and manages the custom
+    audio track expected by the Tavus platform.
+    """
+
     def __init__(
         self,
         client: TavusTransportClient,
         params: TransportParams,
         **kwargs,
     ):
+        """Initialize the Tavus output transport.
+
+        Args:
+            client: The Tavus transport client instance.
+            params: Transport configuration parameters.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(params, **kwargs)
         self._client = client
         self._params = params
@@ -380,14 +550,25 @@ class TavusOutputTransport(BaseOutputTransport):
         self._transport_destination: Optional[str] = "stream"
 
     async def setup(self, setup: FrameProcessorSetup):
+        """Setup the output transport.
+
+        Args:
+            setup: The frame processor setup configuration.
+        """
         await super().setup(setup)
         await self._client.setup(setup)
 
     async def cleanup(self):
+        """Cleanup output transport resources."""
         await super().cleanup()
         await self._client.cleanup()
 
     async def start(self, frame: StartFrame):
+        """Start the output transport.
+
+        Args:
+            frame: The start frame containing initialization parameters.
+        """
         await super().start(frame)
 
         if self._initialized:
@@ -403,51 +584,72 @@ class TavusOutputTransport(BaseOutputTransport):
         await self.set_transport_ready(frame)
 
     async def stop(self, frame: EndFrame):
+        """Stop the output transport.
+
+        Args:
+            frame: The end frame signaling transport shutdown.
+        """
         await super().stop(frame)
         await self._client.stop()
 
     async def cancel(self, frame: CancelFrame):
+        """Cancel the output transport.
+
+        Args:
+            frame: The cancel frame signaling immediate cancellation.
+        """
         await super().cancel(frame)
         await self._client.stop()
 
     async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame):
+        """Send a message to participants.
+
+        Args:
+            frame: The message frame to send.
+        """
         logger.info(f"TavusOutputTransport sending message {frame}")
         await self._client.send_message(frame)
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames and handle interruptions.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
         if isinstance(frame, StartInterruptionFrame):
             await self._handle_interruptions()
 
     async def _handle_interruptions(self):
+        """Handle interruption events by sending interrupt message."""
         await self._client.send_interrupt_message()
 
     async def write_audio_frame(self, frame: OutputAudioRawFrame):
+        """Write an audio frame to the Tavus transport.
+
+        Args:
+            frame: The audio frame to write.
+        """
         # This is the custom track destination expected by Tavus
         frame.transport_destination = self._transport_destination
         await self._client.write_audio_frame(frame)
 
     async def register_audio_destination(self, destination: str):
+        """Register an audio destination.
+
+        Args:
+            destination: The destination identifier to register.
+        """
         await self._client.register_audio_destination(destination)
 
 
 class TavusTransport(BaseTransport):
-    """
-    Transport implementation for Tavus video calls.
+    """Transport implementation for Tavus video calls.
 
     When used, the Pipecat bot joins the same virtual room as the Tavus Avatar and the user.
     This is achieved by using `TavusTransportClient`, which initiates the conversation via
     `TavusApi` and obtains a room URL that all participants connect to.
-
-    Args:
-        bot_name (str): The name of the Pipecat bot.
-        session (aiohttp.ClientSession): aiohttp session used for async HTTP requests.
-        api_key (str): Tavus API key for authentication.
-        replica_id (str): ID of the replica model used for voice generation.
-        persona_id (str): ID of the Tavus persona. Defaults to "pipecat-stream" to use the Pipecat TTS voice.
-        params (TavusParams): Optional Tavus-specific configuration parameters.
-        input_name (Optional[str]): Optional name for the input transport.
-        output_name (Optional[str]): Optional name for the output transport.
     """
 
     def __init__(
@@ -461,6 +663,19 @@ class TavusTransport(BaseTransport):
         input_name: Optional[str] = None,
         output_name: Optional[str] = None,
     ):
+        """Initialize the Tavus transport.
+
+        Args:
+            bot_name: The name of the Pipecat bot.
+            session: aiohttp session used for async HTTP requests.
+            api_key: Tavus API key for authentication.
+            replica_id: ID of the replica model used for voice generation.
+            persona_id: ID of the Tavus persona. Defaults to "pipecat-stream"
+                to use the Pipecat TTS voice.
+            params: Optional Tavus-specific configuration parameters.
+            input_name: Optional name for the input transport.
+            output_name: Optional name for the output transport.
+        """
         super().__init__(input_name=input_name, output_name=output_name)
         self._params = params
 
@@ -487,11 +702,13 @@ class TavusTransport(BaseTransport):
         self._register_event_handler("on_client_disconnected")
 
     async def _on_participant_left(self, participant, reason):
+        """Handle participant left events."""
         persona_name = await self._client.get_persona_name()
         if participant.get("info", {}).get("userName", "") != persona_name:
             await self._on_client_disconnected(participant)
 
     async def _on_participant_joined(self, participant):
+        """Handle participant joined events."""
         # get persona, look up persona_name, set this as the bot name to ignore
         persona_name = await self._client.get_persona_name()
 
@@ -513,23 +730,41 @@ class TavusTransport(BaseTransport):
                 await self._input.start_capturing_audio(participant)
 
     async def update_subscriptions(self, participant_settings=None, profile_settings=None):
+        """Update subscription settings for participants.
+
+        Args:
+            participant_settings: Per-participant subscription settings.
+            profile_settings: Global subscription profile settings.
+        """
         await self._client.update_subscriptions(
             participant_settings=participant_settings,
             profile_settings=profile_settings,
         )
 
     def input(self) -> FrameProcessor:
+        """Get the input transport for receiving media and events.
+
+        Returns:
+            The Tavus input transport instance.
+        """
         if not self._input:
             self._input = TavusInputTransport(client=self._client, params=self._params)
         return self._input
 
     def output(self) -> FrameProcessor:
+        """Get the output transport for sending media and events.
+
+        Returns:
+            The Tavus output transport instance.
+        """
         if not self._output:
             self._output = TavusOutputTransport(client=self._client, params=self._params)
         return self._output
 
     async def _on_client_connected(self, participant: Any):
+        """Handle client connected events."""
         await self._call_event_handler("on_client_connected", participant)
 
     async def _on_client_disconnected(self, participant: Any):
+        """Handle client disconnected events."""
         await self._call_event_handler("on_client_disconnected", participant)