intellema-vdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

intellema_vdk/providers/retell/client.py

@@ -0,0 +1,468 @@
+import os  # Used for operating system dependent functionality, like file paths.
+import logging  # Used for logging events.
+import time  # Used for time-related tasks.
+import uuid  # Used for generating unique identifiers.
+import subprocess  # Used for installing packages
+import sys  # Used for sys operations
+from typing import List, Optional, Any, Dict, TYPE_CHECKING  # Used for type hinting.
+
+# Lazy imports - only load when RetellManager is instantiated
+if TYPE_CHECKING:
+    from twilio.rest import Client as TwilioClient
+    from retell import Retell, APIError
+    import boto3
+else:
+    TwilioClient = None
+    Retell = None
+    APIError = None
+    boto3 = None
+
+# Import requests - should be available as a core dependency
+import requests  # Used for making HTTP requests.
+
+from ...config import get_env  # Used to get environment variables.
+from ..protocols import VoiceProvider  # Protocol for voice providers.
+from .exceptions import (
+    RetellConfigurationError,
+    RetellPhoneNumberError,
+    RetellCallError,
+    RetellAPIError,
+    RetellError
+)
+
+# Setup logger for this module.
+logger = logging.getLogger(__name__)
+
+
+class RetellManager(VoiceProvider):
+    """Manages voice calls using the Retell and Twilio APIs.
+
+    This class provides a high-level interface for making outbound calls,
+    managing phone numbers with Retell, and handling call recordings. It uses
+    Twilio for the underlying telephony infrastructure.
+
+    Attributes:
+        twilio_account_sid (str): The Twilio account SID.
+        twilio_auth_token (str): The Twilio auth token.
+        twilio_number (str): The Twilio phone number to use for calls.
+        retell_api_key (str): The Retell API key.
+        retell_agent_id (str): The ID of the Retell agent to use.
+        twilio_client (TwilioClient): The Twilio API client.
+        retell_client (Retell): The Retell API client.
+
+    Example:
+        >>> async def main():
+        ...     retell_manager = VoiceClient("retell")
+        ...     # Import a phone number (run once per number)
+        ...     # retell_manager.import_phone_number()
+        ...     call_id = await retell_manager.start_outbound_call(
+        ...         phone_number="+15551234567",
+        ...         prompt_content="Hello from Retell!"
+        ...     )
+        ...     print(f"Call started with ID: {call_id}")
+        ...     # Wait for the call to connect and then end it.
+        ...     await asyncio.sleep(30)
+        ...     await retell_manager.delete_room(call_id)
+        ...
+        >>> if __name__ == "__main__":
+        ...     import asyncio
+        ...     asyncio.run(main())
+    """
+
+    def __init__(self) -> None:
+        """Initializes the RetellManager.
+
+        Retrieves configuration from environment variables and initializes
+        the Twilio and Retell API clients.
+
+        Raises:
+            RetellConfigurationError: If required environment variables are missing.
+        """
+        # Lazy import dependencies - only install when actually used
+        global TwilioClient, Retell, APIError, boto3
+        
+        if TwilioClient is None:
+            try:
+                from twilio.rest import Client as _TwilioClient
+                TwilioClient = _TwilioClient
+            except ImportError:
+                print("Twilio SDK is not installed. Installing now...")
+                print("Run: pip install intellema-vdk[retell]")
+                try:
+                    subprocess.check_call([sys.executable, "-m", "pip", "install", "twilio>=8.0.0"])
+                    from twilio.rest import Client as _TwilioClient
+                    TwilioClient = _TwilioClient
+                    print("✓ Twilio SDK installed successfully!")
+                except Exception as e:
+                    raise RetellConfigurationError(
+                        "Failed to install twilio. Please install manually:\n"
+                        "  pip install intellema-vdk[retell]\n"
+                        "or:\n"
+                        "  pip install twilio>=8.0.0"
+                    ) from e
+        
+        if Retell is None:
+            try:
+                from retell import Retell as _Retell, APIError as _APIError
+                Retell = _Retell
+                APIError = _APIError
+            except ImportError:
+                print("Retell SDK is not installed. Installing now...")
+                try:
+                    subprocess.check_call([sys.executable, "-m", "pip", "install", "retell-sdk>=2.0.0"])
+                    from retell import Retell as _Retell, APIError as _APIError
+                    Retell = _Retell
+                    APIError = _APIError
+                    print("✓ Retell SDK installed successfully!")
+                except Exception as e:
+                    raise RetellConfigurationError(
+                        "Failed to install retell-sdk. Please install manually:\n"
+                        "  pip install intellema-vdk[retell]\n"
+                        "or:\n"
+                        "  pip install retell-sdk>=2.0.0"
+                    ) from e
+        
+        if boto3 is None:
+            try:
+                import boto3 as _boto3
+                boto3 = _boto3
+            except ImportError:
+                print("boto3 (AWS SDK) is not installed. Installing now...")
+                print("This is required for AWS services like Polly TTS.")
+                try:
+                    subprocess.check_call([sys.executable, "-m", "pip", "install", "boto3>=1.28.0"])
+                    import boto3 as _boto3
+                    boto3 = _boto3
+                    print("✓ boto3 installed successfully!")
+                except Exception as e:
+                    raise RetellConfigurationError(
+                        "Failed to install boto3. Please install manually:\n"
+                        "  pip install boto3>=1.28.0"
+                    ) from e
+        
+        self.twilio_account_sid = get_env("TWILIO_ACCOUNT_SID")
+        self.twilio_auth_token = get_env("TWILIO_AUTH_TOKEN")
+        self.twilio_number = get_env("TWILIO_PHONE_NUMBER")
+        self.retell_api_key = get_env("RETELL_API_KEY")
+        self.retell_agent_id = get_env("RETELL_AGENT_ID")
+
+        if not all([self.twilio_account_sid, self.twilio_auth_token, self.twilio_number, self.retell_api_key, self.retell_agent_id]):
+            raise RetellConfigurationError(
+                "Missing necessary environment variables for RetellManager")
+
+        self.twilio_client = TwilioClient(
+            self.twilio_account_sid, self.twilio_auth_token)
+        self.retell_client = Retell(api_key=self.retell_api_key)
+
+    def import_phone_number(self, termination_uri: Optional[str] = None, outbound_agent_id: Optional[str] = None, inbound_agent_id: Optional[str] = None, nickname: Optional[str] = None, sip_trunk_auth_username: Optional[str] = None, sip_trunk_auth_password: Optional[str] = None) -> Any:
+        """Imports and registers a Twilio phone number with Retell.
+
+        This is a necessary step before making outbound calls with the number.
+
+        Args:
+            termination_uri (Optional[str]): The Twilio SIP trunk termination URI
+                (e.g., "yourtrunk.pstn.twilio.com").
+            outbound_agent_id (Optional[str]): The agent ID for outbound calls.
+                Defaults to `self.retell_agent_id`.
+            inbound_agent_id (Optional[str]): The agent ID for inbound calls.
+            nickname (Optional[str]): A nickname for the phone number.
+            sip_trunk_auth_username (Optional[str]): Username for SIP trunk
+                authentication.
+            sip_trunk_auth_password (Optional[str]): Password for SIP trunk
+                authentication.
+
+        Returns:
+            Any: The phone number registration response from Retell.
+
+        Raises:
+            RetellAPIError: If the Retell API returns an error.
+            RetellPhoneNumberError: For other unexpected errors.
+        """
+        import_kwargs: Dict[str, Any] = {
+            "phone_number": self.twilio_number,
+        }
+
+        if termination_uri:
+            import_kwargs["termination_uri"] = termination_uri
+        if sip_trunk_auth_username and sip_trunk_auth_password:
+            import_kwargs["sip_trunk_auth_username"] = sip_trunk_auth_username
+            import_kwargs["sip_trunk_auth_password"] = sip_trunk_auth_password
+        if outbound_agent_id:
+            import_kwargs["outbound_agent_id"] = outbound_agent_id
+        elif self.retell_agent_id:
+            import_kwargs["outbound_agent_id"] = self.retell_agent_id
+        if inbound_agent_id:
+            import_kwargs["inbound_agent_id"] = inbound_agent_id
+        if nickname:
+            import_kwargs["nickname"] = nickname
+
+        try:
+            response = self.retell_client.phone_number.import_(**import_kwargs)
+            logger.info(
+                f"✓ Phone number {self.twilio_number} successfully imported to Retell!")
+            logger.info(f"  Phone Number: {response.phone_number}")
+            logger.info(f"  Type: {response.phone_number_type}")
+            if hasattr(response, 'outbound_agent_id') and response.outbound_agent_id:
+                logger.info(f"  Outbound Agent: {response.outbound_agent_id}")
+            if hasattr(response, 'inbound_agent_id') and response.inbound_agent_id:
+                logger.info(f"  Inbound Agent: {response.inbound_agent_id}")
+            return response
+        except APIError as e:
+            logger.error(
+                f"Retell API error importing phone number: {e}", exc_info=True)
+            raise RetellAPIError(
+                f"Retell API error importing phone number: {e}") from e
+        except Exception as e:
+            logger.error(
+                f"An unexpected error occurred while importing phone number: {e}", exc_info=True)
+            raise RetellPhoneNumberError(
+                f"An unexpected error occurred while importing phone number: {e}") from e
+
+    async def start_outbound_call(self, phone_number: str, prompt_content: Optional[str] = None, call_id: Optional[str] = None) -> str:
+        """Initiates an outbound call via Retell AI.
+
+        Args:
+            phone_number (str): The destination phone number.
+            prompt_content (Optional[str]): A prompt to override the agent's default.
+            call_id (Optional[str]): A metadata ID for the call.
+
+        Returns:
+            str: The Retell call ID.
+
+        Raises:
+            RetellCallError: If the call fails to start.
+        """
+        call_kwargs: Dict[str, Any] = {
+            "from_number": self.twilio_number,
+            "to_number": phone_number,
+            "override_agent_id": self.retell_agent_id,
+        }
+
+        if call_id:
+            call_kwargs["metadata"] = {"call_id": call_id}
+
+        # Set up dynamic variables for custom prompts.
+        if prompt_content:
+            enhanced_prompt = (
+                f"{prompt_content}\n\n"
+                "SYSTEM INSTRUCTION: Continually check the dynamic variable {{force_end}}. "
+                "If {{force_end}} == 'true', you must IMMEDIATELY say goodbye and "
+                "activate your end_call tool to terminate the call."
+            )
+            call_kwargs["retell_llm_dynamic_variables"] = {
+                "prompt_content": enhanced_prompt,
+                "force_end": "false"
+            }
+
+        try:
+            call_response = self.retell_client.call.create_phone_call(
+                **call_kwargs)
+        except Exception as e:
+            raise RetellCallError(
+                f"Failed to start outbound call: {e}") from e
+
+        logger.info("Call created successfully!")
+        logger.info(f"Retell Call ID: {call_response.call_id}")
+        logger.info(f"Call Status: {call_response.call_status}")
+
+        return call_response.call_id
+
+    async def delete_room(self, call_id: str) -> None:
+        """Ends the call by updating a dynamic variable.
+
+        This method signals the agent to end the call by setting the `force_end`
+        dynamic variable to "true".
+
+        Args:
+            call_id (str): The Retell call ID.
+
+        Raises:
+            RetellCallError: If the call cannot be ended.
+        """
+        try:
+            call_data = self.retell_client.call.retrieve(call_id)
+            logger.info(f"Current call status: {call_data.call_status}")
+
+            if call_data.call_status in ['registered', 'ongoing', 'dialing']:
+                logger.info(f"Triggering end for Retell call {call_id}...")
+                self.retell_client.call.update(
+                    call_id,
+                    override_dynamic_variables={"force_end": "true"}
+                )
+                logger.info("✓ force_end override sent to Retell API")
+            else:
+                logger.info(f"Call already ended: {call_data.call_status}")
+
+        except Exception as e:
+            logger.error(f"Error ending call {call_id}: {e}")
+            raise RetellCallError(f"Error ending call {call_id}: {e}") from e
+
+    async def start_stream(self, call_id: str, rtmp_urls: List[str]) -> None:
+        """Not supported for Retell phone calls.
+
+        Retell deprecated their Audio WebSocket API at the end of 2024.
+        For phone calls, audio is managed internally by Retell and cannot
+        be accessed externally for streaming.
+
+        Use `start_recording()` to retrieve recordings after the call ends.
+
+        Args:
+            call_id (str): The Retell Call ID.
+            rtmp_urls (List[str]): Not used.
+
+        Raises:
+            NotImplementedError: Always raised as streaming is not supported.
+        """
+        raise NotImplementedError(
+            "Real-time audio streaming is not supported for Retell phone calls. "
+            "Retell deprecated their Audio WebSocket API. "
+            "Use start_recording() to retrieve recordings after the call ends."
+        )
+
+
+    async def start_recording(self, call_id: str, output_filepath: Optional[str] = None, upload_to_s3: bool = True, wait_for_completion: bool = True) -> str:
+        """Retrieves the recording from a Retell call.
+
+        Retell automatically records calls. This method polls for the recording
+        URL to become available, then downloads and optionally uploads to S3.
+
+        Args:
+            call_id (str): The Retell Call ID.
+            output_filepath (Optional[str]): A filename for the recording.
+            upload_to_s3 (bool): If True, uploads the recording to S3.
+            wait_for_completion (bool): If True, waits for the recording to
+                be available before proceeding.
+
+        Returns:
+            str: The recording URL from Retell.
+
+        Raises:
+            RetellError: If the recording fails or cannot be downloaded.
+            RetellConfigurationError: If S3 upload is requested but not configured.
+        """
+        logger.info(f"Retrieving recording for call: {call_id}")
+
+        # Poll for call to end and recording to be available.
+        recording_url = None
+        max_attempts = 60  # 5 minutes max wait (5s intervals)
+        attempts = 0
+
+        if wait_for_completion:
+            logger.info("Waiting for call to end and recording to be available...")
+            while attempts < max_attempts:
+                try:
+                    call_data = self.retell_client.call.retrieve(call_id)
+                    
+                    if call_data.call_status == 'ended':
+                        if hasattr(call_data, 'recording_url') and call_data.recording_url:
+                            recording_url = call_data.recording_url
+                            logger.info("Recording is available.")
+                            break
+                        else:
+                            logger.info("Call ended but recording not yet available...")
+                    elif call_data.call_status == 'error':
+                        raise RetellError(f"Call failed with error status")
+                    else:
+                        logger.info(f"Call status: {call_data.call_status}, waiting...")
+                    
+                except Exception as e:
+                    logger.warning(f"Error checking call status: {e}")
+                
+                time.sleep(5)
+                attempts += 1
+
+            if not recording_url:
+                raise RetellError(
+                    f"Recording not available after {max_attempts * 5} seconds. "
+                    "Ensure the call has ended and recording is enabled for the agent."
+                )
+        else:
+            # Just try to get the recording URL once
+            call_data = self.retell_client.call.retrieve(call_id)
+            if hasattr(call_data, 'recording_url') and call_data.recording_url:
+                recording_url = call_data.recording_url
+            else:
+                return call_id  # Return call_id, recording not yet available
+
+        logger.info(f"Recording URL: {recording_url}")
+
+        if not upload_to_s3:
+            return recording_url
+
+        # Download recording from Retell.
+        logger.info(f"Downloading recording from: {recording_url}")
+        response = requests.get(recording_url)
+        if response.status_code != 200:
+            raise RetellError(
+                f"Failed to download recording: {response.status_code} {response.text}")
+
+        # Upload to S3.
+        access_key = get_env("AWS_ACCESS_KEY_ID")
+        secret_key = get_env("AWS_SECRET_ACCESS_KEY")
+        bucket = get_env("AWS_S3_BUCKET")
+        region = get_env("AWS_REGION")
+
+        if not access_key or not secret_key or not bucket:
+            raise RetellConfigurationError(
+                "AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, "
+                "AWS_S3_BUCKET) are required for S3 upload."
+            )
+
+        # Determine file extension from URL or default to .wav (Retell uses .wav)
+        filename = output_filepath if output_filepath else f"{call_id}-{uuid.uuid4().hex[:6]}.wav"
+
+        s3 = boto3.client(
+            's3',
+            aws_access_key_id=access_key,
+            aws_secret_access_key=secret_key,
+            region_name=region
+        )
+
+        logger.info(f"Uploading to S3: s3://{bucket}/{filename}")
+        s3.put_object(Bucket=bucket, Key=filename, Body=response.content)
+        logger.info(f"Upload complete: s3://{bucket}/{filename}")
+
+        # Save locally as well.
+        local_dir = "recordings"
+        os.makedirs(local_dir, exist_ok=True)
+        local_path = os.path.join(local_dir, filename)
+        with open(local_path, 'wb') as f:
+            f.write(response.content)
+        logger.info(f"Recording saved locally: {local_path}")
+
+        return recording_url
+
+    async def mute_participant(self, call_id: str, identity: str, track_sid: str, muted: bool) -> None:
+        """Mutes the participant on the Twilio call.
+
+        Note: Twilio's REST API does not support muting 1:1 calls directly.
+        This method will raise NotImplementedError.
+
+        Args:
+            call_id (str): The Retell call ID.
+            identity (str): Unused.
+            track_sid (str): Unused.
+            muted (bool): True to mute, False to unmute.
+        """
+        logger.warning("Twilio REST API does not support muting 1:1 calls directly.")
+        raise NotImplementedError("Twilio REST API does not support muting 1:1 calls directly.")
+
+    async def kick_participant(self, call_id: str, identity: str) -> None:
+        """Ends the call.
+
+        This is an alias for `delete_room`.
+
+        Args:
+            call_id (str): The call ID.
+            identity (str): Unused in this context.
+        """
+        await self.delete_room(call_id)
+
+    async def send_alert(self, call_id: str, message: str, participant_identity: Optional[str] = None) -> None:
+        """Not supported by this provider.
+
+        Raises:
+            NotImplementedError: This method is not implemented.
+        """
+        raise NotImplementedError(
+            "send_alert is not currently supported in RetellManager")

intellema_vdk/providers/retell/exceptions.py

@@ -0,0 +1,19 @@
+class RetellError(Exception):
+    """Base exception for all Retell-related errors."""
+    pass
+
+class RetellConfigurationError(RetellError):
+    """Raised when configuration (API keys, secrets) is missing or invalid."""
+    pass
+
+class RetellAPIError(RetellError):
+    """Raised when the Retell API returns an error response."""
+    pass
+
+class RetellPhoneNumberError(RetellError):
+    """Raised when there are issues importing or managing phone numbers."""
+    pass
+
+class RetellCallError(RetellError):
+    """Raised when starting, updating, or ending a call fails."""
+    pass

intellema_vdk/{retell_lib → providers/retell}/import_phone_number.py

@@ -4,7 +4,7 @@ import sys
 # Add the project root to the python path so we can import intellema_vdk
 sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
 
-from intellema_vdk.retell_lib.retell_client import RetellManager
+from intellema_vdk import RetellManager
 
 def import_twilio_number():
     """

intellema_vdk/stt/__init__.py

@@ -0,0 +1,17 @@
+from .client import STTManager
+from .exceptions import (
+    STTError,
+    STTConfigurationError,
+    STTFileError,
+    STTTranscriptionError,
+    STTAgentError,
+)
+
+__all__ = [
+    "STTManager",
+    "STTError",
+    "STTConfigurationError",
+    "STTFileError",
+    "STTTranscriptionError",
+    "STTAgentError",
+]