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

intellema_vdk/providers/livekit/client.py

@@ -0,0 +1,612 @@
+import os  # Used for operating system dependent functionality, like file paths.
+import json  # Used for encoding and decoding JSON data.
+import uuid  # Used for generating unique identifiers.
+import asyncio  # Used for writing single-threaded concurrent code using coroutines.
+import time  # Used for time-related tasks.
+import logging  # Used for logging events.
+import subprocess  # Used for installing packages
+import sys  # Used for sys operations
+from typing import List, Optional, Dict, Any, TYPE_CHECKING  # Used for type hinting.
+
+# Lazy imports - only load when LiveKitManager is instantiated
+if TYPE_CHECKING:
+    from livekit import api
+    import boto3
+else:
+    api = None
+    boto3 = None
+
+from ...config import get_env  # Used to get environment variables.
+from ..protocols import VoiceProvider  # Protocol for voice providers.
+from .exceptions import (
+    LiveKitConfigurationError,
+    LiveKitRoomError,
+    LiveKitSIPError,
+    LiveKitDispatchError,
+    LiveKitEgressError,
+    LiveKitError,
+)
+
+# Setup logger for this module.
+logger = logging.getLogger(__name__)
+
+
+class LiveKitManager(VoiceProvider):
+    """Manages LiveKit rooms, participants, and SIP calls.
+
+    This class provides a high-level interface to the LiveKit API for managing
+    voice calls, including starting outbound calls, creating tokens, managing rooms,
+    and handling media streams and recordings.
+
+    Attributes:
+        url (str): The URL of the LiveKit server.
+        api_key (str): The LiveKit API key.
+        api_secret (str): The LiveKit API secret.
+        sip_trunk_id (str): The ID of the SIP outbound trunk.
+        lk_api (api.LiveKitAPI): The LiveKit API client.
+
+    Example:
+        >>> async def main():
+        ...     livekit_manager = VoiceClient("livekit")
+        ...     call_id = await livekit_manager.start_outbound_call(
+        ...         phone_number="+15551234567",
+        ...         prompt_content="Hello, this is a test call."
+        ...     )
+        ...     print(f"Call started with ID: {call_id}")
+        ...     await livekit_manager.delete_room(call_id)
+        ...     await livekit_manager.close()
+        ...
+        >>> if __name__ == "__main__":
+        ...     asyncio.run(main())
+    """
+
+    def __init__(self) -> None:
+        """Initializes the LiveKitManager.
+
+        Retrieves LiveKit configuration from environment variables and initializes
+        the LiveKit API client.
+
+        Raises:
+            LiveKitConfigurationError: If required LiveKit environment variables
+                are not set.
+        """
+        # Lazy import LiveKit API and boto3 - only install when actually used
+        global api, boto3
+        if api is None:
+            try:
+                from livekit import api as _api
+                api = _api
+            except ImportError:
+                print("LiveKit API is not installed. Installing now...")
+                print("Run: pip install intellema-vdk[livekit]")
+                try:
+                    subprocess.check_call([sys.executable, "-m", "pip", "install", "livekit-api>=1.1.0"])
+                    from livekit import api as _api
+                    api = _api
+                    print("✓ LiveKit API installed successfully!")
+                except Exception as e:
+                    raise LiveKitConfigurationError(
+                        "Failed to install livekit-api. Please install manually:\n"
+                        "  pip install intellema-vdk[livekit]\n"
+                        "or:\n"
+                        "  pip install livekit-api>=1.1.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 Polly TTS and other AWS features.")
+                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 LiveKitConfigurationError(
+                        "Failed to install boto3. Please install manually:\n"
+                        "  pip install boto3>=1.28.0"
+                    ) from e
+        
+        self.url = get_env("LIVEKIT_URL")
+        self.api_key = get_env("LIVEKIT_API_KEY")
+        self.api_secret = get_env("LIVEKIT_API_SECRET")
+        self.sip_trunk_id = get_env("SIP_OUTBOUND_TRUNK_ID")
+
+        if not self.url or not self.api_key or not self.api_secret:
+            raise LiveKitConfigurationError(
+                "LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET must be set."
+            )
+
+        self.lk_api = api.LiveKitAPI(
+            url=self.url,
+            api_key=self.api_key,
+            api_secret=self.api_secret,
+        )
+
+    async def close(self) -> None:
+        """Closes the underlying LiveKitAPI client connection."""
+        await self.lk_api.aclose()
+
+    async def start_outbound_call(
+        self,
+        phone_number: str,
+        prompt_content: str,
+        call_id: Optional[str] = None,
+        timeout: int = 600,
+    ) -> str:
+        """Initiates an outbound call via a LiveKit SIP trunk.
+
+        This method creates a LiveKit room, dispatches an agent to it, and then
+        initiates a SIP call to the specified phone number.
+
+        Args:
+            phone_number (str): The destination phone number in E.164 format.
+            prompt_content (str): The initial prompt or context for the AI agent.
+            call_id (Optional[str]): A unique identifier for the call. If not
+                provided, a random one is generated. This is used as the room name.
+            timeout (int): The timeout for the room in seconds. Defaults to 600.
+
+        Returns:
+            str: The unique `call_id` (room name) for the call.
+
+        Raises:
+            LiveKitConfigurationError: If the SIP outbound trunk ID is not configured.
+            LiveKitSIPError: If the SIP call fails (e.g., user is busy).
+        """
+        if not call_id:
+            call_id = f"outbound_call_{uuid.uuid4().hex[:12]}"
+
+        logger.info(f"Starting outbound call to {phone_number}...")
+        logger.info(f"  Call ID: {call_id}")
+
+        metadata = json.dumps(
+            {"phone_number": phone_number, "prompt_content": prompt_content}
+        )
+
+        # 1. Create a room with metadata.
+        room = await self.lk_api.room.create_room(
+            api.CreateRoomRequest(
+                name=call_id, empty_timeout=timeout, metadata=metadata
+            )
+        )
+        logger.info(f"✓ Room created successfully!")
+        logger.info(f"  Room Name: {room.name}")
+
+        # 2. Dispatch an agent to the room.
+        await self.lk_api.agent_dispatch.create_dispatch(
+            api.CreateAgentDispatchRequest(
+                room=call_id, agent_name="outbound-caller", metadata=metadata
+            )
+        )
+        logger.info(f"✓ Agent dispatched to room")
+
+        # 3. Initiate the outbound SIP/PSTN call.
+        if not self.sip_trunk_id:
+            logger.error(
+                "SIP_OUTBOUND_TRUNK_ID is not configured in environment.", exc_info=True
+            )
+            raise LiveKitConfigurationError(
+                "SIP_OUTBOUND_TRUNK_ID is not configured in environment."
+            )
+
+        sip_participant_identity = f"phone-{phone_number}"
+
+        try:
+            await self.lk_api.sip.create_sip_participant(
+                api.CreateSIPParticipantRequest(
+                    room_name=call_id,
+                    sip_trunk_id=self.sip_trunk_id,
+                    sip_call_to=phone_number,
+                    participant_identity=sip_participant_identity,
+                    wait_until_answered=True,
+                )
+            )
+            logger.info(f"✓ SIP participant created successfully!")
+            logger.info(f"  Participant Identity: {sip_participant_identity}")
+
+        except api.TwirpError as e:
+            # Extract SIP-specific error information from metadata
+            sip_status_code = e.metadata.get("sip_status_code")
+            sip_status = e.metadata.get("sip_status", "Unknown")
+
+            logger.error(
+                f"SIP call failed: {e.message}, "
+                f"SIP status: {sip_status_code} {sip_status}"
+            )
+
+            # Clean up the room (centralized cleanup for all error paths)
+            await self.delete_room(call_id)
+
+            # Handle case where SIP status code is not available
+            if sip_status_code is None:
+                logger.warning("No SIP status code available in error metadata")
+                raise LiveKitSIPError(f"SIP call failed: {e.message}") from e
+
+            # Handle specific SIP error codes
+            # 486 = Busy Here, 600 = Busy Everywhere
+            if sip_status_code in ("486", "600"):
+                raise LiveKitSIPError(f"User is busy (SIP {sip_status_code})") from e
+
+            # Handle other common SIP errors
+            # 400 = Bad Request
+            # 404 = Not Found
+            # 408 = Request Timeout
+            # 480 = Temporarily Unavailable
+            # 487 = Request Terminated
+            elif sip_status_code in ("400", "404", "408", "480", "487"):
+                raise LiveKitSIPError(
+                    f"Call failed: {sip_status} (SIP {sip_status_code})"
+                ) from e
+
+            # Handle all other SIP error codes
+            else:
+                raise LiveKitSIPError(
+                    f"SIP call failed with status {sip_status_code}: {e.message}"
+                ) from e
+
+        except Exception as e:
+            # Handle non-Twirp exceptions
+            logger.error(
+                f"Unexpected error creating SIP participant: {e}", exc_info=True
+            )
+            await self.delete_room(call_id)
+            raise LiveKitSIPError(f"Failed to create SIP participant: {e}") from e
+
+        logger.info(f"✓ Call started successfully!")
+        logger.info(f"  Call ID: {room.name}")
+        logger.info(f"  Phone Number: {phone_number}")
+
+        return room.name
+
+    async def create_token(self, call_id: str, participant_name: str) -> str:
+        """Creates a JWT token for a participant to join a room.
+
+        Args:
+            call_id (str): The room name (call_id) to join.
+            participant_name (str): The name of the participant.
+
+        Returns:
+            str: The generated JWT token.
+        """
+        logger.info(
+            f"Creating token for participant '{participant_name}' in room '{call_id}'"
+        )
+        token = api.AccessToken(self.api_key, self.api_secret)
+        token.with_identity(participant_name)
+        token.with_name(participant_name)
+        token.with_grants(
+            api.VideoGrants(
+                room_join=True,
+                room=call_id,
+            )
+        )
+        logger.info(f"✓ Token created successfully for {participant_name}")
+        return token.to_jwt()
+
+    async def delete_room(self, call_id: str) -> None:
+        """Ends the call by deleting the LiveKit room.
+
+        Args:
+            call_id (str): The room name (call_id) to delete.
+        """
+        logger.info(f"Ending call by deleting room: {call_id}")
+        try:
+            await self.lk_api.room.delete_room(api.DeleteRoomRequest(room=call_id))
+            logger.info(f"✓ Room '{call_id}' deleted successfully")
+        except Exception as e:
+            logger.error(f"Error deleting room {call_id}: {e}", exc_info=True)
+            raise LiveKitRoomError(f"Error deleting room {call_id}: {e}") from e
+
+    async def start_stream(self, call_id: str, rtmp_urls: List[str]) -> None:
+        """Starts streaming the call to provided RTMP URLs using LiveKit Egress.
+
+        Args:
+            call_id (str): The room name to stream.
+            rtmp_urls (List[str]): A list of RTMP URLs to stream to.
+        """
+        if not rtmp_urls:
+            raise ValueError("No stream URLs provided")
+
+        logger.info(f"Starting stream for room: {call_id}")
+        logger.info(f"  Stream URLs: {rtmp_urls}")
+
+        try:
+            await self.lk_api.egress.start_room_composite_egress(
+                api.RoomCompositeEgressRequest(
+                    room_name=call_id,
+                    layout="speaker",
+                    stream_outputs=[
+                        api.StreamOutput(
+                            protocol=api.StreamProtocol.RTMP, urls=rtmp_urls
+                        )
+                    ],
+                )
+            )
+            logger.info(f"✓ Stream started successfully for room {call_id}")
+        except Exception as e:
+            logger.error(
+                f"Failed to start stream for room {call_id}: {e}", exc_info=True
+            )
+            raise LiveKitEgressError(f"Failed to start stream: {e}") from e
+
+    async def start_recording(
+        self,
+        call_id: str,
+        output_filepath: Optional[str] = None,
+        upload_to_s3: bool = True,
+        wait_for_completion: bool = True,
+    ) -> str:
+        """Starts recording a room.
+
+        The recording can be saved to a file on an Egress server or uploaded to an
+        S3 bucket.
+
+        Args:
+            call_id (str): Name of the room/call to record.
+            output_filepath (Optional[str]): The path or filename for the recording.
+                Defaults to a generated name.
+            upload_to_s3 (bool): If True, uploads to S3. This requires AWS
+                credentials to be configured in the environment. Defaults to True.
+            wait_for_completion (bool): If True and `upload_to_s3` is True, this
+                method will wait for the recording to finish and then download it
+                from S3 to a local 'recordings' directory. Defaults to True.
+
+        Returns:
+            str: The Egress ID of the recording.
+
+        Raises:
+            LiveKitConfigurationError: If S3 upload is requested but AWS
+                credentials are not configured.
+            LiveKitEgressError: If the Egress process fails.
+        """
+        filename = (
+            output_filepath
+            if output_filepath
+            else f"{call_id}-{uuid.uuid4().hex[:6]}.mp4"
+        )
+
+        if 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 LiveKitConfigurationError(
+                    "AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, "
+                    "AWS_S3_BUCKET) are required for S3 upload."
+                )
+
+            file_output = api.EncodedFileOutput(
+                file_type=api.EncodedFileType.MP4,
+                filepath=filename,
+                s3=api.S3Upload(
+                    access_key=access_key,
+                    secret=secret_key,
+                    bucket=bucket,
+                    region=region,
+                ),
+            )
+            logger.info(
+                f"Starting recording. File will be saved to S3: s3://{bucket}/{filename}"
+            )
+        else:
+            file_output = api.EncodedFileOutput(
+                file_type=api.EncodedFileType.MP4,
+                filepath=filename,
+            )
+            logger.info(f"Starting recording. File will be saved locally: {filename}")
+
+        egress_info = await self.lk_api.egress.start_room_composite_egress(
+            api.RoomCompositeEgressRequest(
+                room_name=call_id,
+                layout="grid",
+                preset=api.EncodingOptionsPreset.H264_720P_30,
+                file_outputs=[file_output],
+            )
+        )
+
+        if wait_for_completion and upload_to_s3:
+            egress_id = egress_info.egress_id
+            logger.info(f"Waiting for egress {egress_id} to complete...")
+
+            while True:
+                try:
+                    egress_list = await self.lk_api.egress.list_egress(
+                        api.ListEgressRequest(egress_id=egress_id)
+                    )
+                except Exception as e:
+                    logger.error(f"Error checking egress status: {e}")
+                    await asyncio.sleep(5)
+                    continue
+
+                if not egress_list.items:
+                    logger.warning("Egress info not found during polling.")
+                    break
+
+                info = egress_list.items[0]
+                if info.status == api.EgressStatus.EGRESS_COMPLETE:
+                    logger.info("Egress completed successfully.")
+                    break
+                elif info.status == api.EgressStatus.EGRESS_FAILED:
+                    raise LiveKitEgressError(f"Egress failed: {info.error}")
+                elif info.status == api.EgressStatus.EGRESS_LIMIT_REACHED:
+                    raise LiveKitEgressError(f"Egress limit reached: {info.error}")
+
+                await asyncio.sleep(5)
+
+            # Download the recording from S3.
+            logger.info(f"Downloading {filename} from S3 bucket {bucket}...")
+            s3 = boto3.client(
+                "s3",
+                aws_access_key_id=access_key,
+                aws_secret_access_key=secret_key,
+                region_name=region,
+            )
+
+            local_dir = "recordings"
+            os.makedirs(local_dir, exist_ok=True)
+            local_path = os.path.join(local_dir, filename)
+
+            try:
+                s3.download_file(bucket, filename, local_path)
+                logger.info(f"Recording downloaded to: {local_path}")
+            except Exception as e:
+                logger.error(f"Failed to download recording: {e}")
+                raise e
+
+        return egress_info.egress_id
+
+    async def kick_participant(self, call_id: str, identity: str) -> None:
+        """Removes a participant from the call.
+
+        Args:
+            call_id (str): The room name.
+            identity (str): The identity of the participant to remove.
+        """
+        logger.info(f"Removing participant '{identity}' from room '{call_id}'")
+        try:
+            await self.lk_api.room.remove_participant(
+                api.RoomParticipantIdentity(room=call_id, identity=identity)
+            )
+            logger.info(f"✓ Participant '{identity}' removed successfully")
+        except Exception as e:
+            logger.error(
+                f"Failed to remove participant '{identity}' from room '{call_id}': {e}",
+                exc_info=True,
+            )
+            raise LiveKitRoomError(f"Failed to remove participant: {e}") from e
+
+    async def mute_participant(
+        self, call_id: str, identity: str, track_sid: str, muted: bool
+    ) -> None:
+        """Mutes or unmutes a participant's track.
+
+        Args:
+            call_id (str): The room name.
+            identity (str): The participant identity.
+            track_sid (str): The SID of the track to mute/unmute.
+            muted (bool): True to mute, False to unmute.
+        """
+        action = "Muting" if muted else "Unmuting"
+        logger.info(
+            f"{action} participant '{identity}' track '{track_sid}' in room '{call_id}'"
+        )
+        try:
+            await self.lk_api.room.mute_published_track(
+                api.MuteRoomTrackRequest(
+                    room=call_id, identity=identity, track_sid=track_sid, muted=muted
+                )
+            )
+            logger.info(
+                f"✓ Participant '{identity}' {'muted' if muted else 'unmuted'} successfully"
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to {'mute' if muted else 'unmute'} participant '{identity}': {e}",
+                exc_info=True,
+            )
+            raise LiveKitRoomError(f"Failed to mute/unmute participant: {e}") from e
+
+    async def send_alert(
+        self, call_id: str, message: str, participant_identity: Optional[str] = None
+    ) -> None:
+        """Sends a data message (alert) to call participants.
+
+        Args:
+            call_id (str): The room name.
+            message (str): The message content.
+            participant_identity (Optional[str]): The identity of a specific
+                participant to send the message to. If None, sends to all.
+        """
+        target = participant_identity if participant_identity else "all participants"
+        logger.info(f"Sending alert to {target} in room '{call_id}'")
+        logger.info(f"  Message: {message}")
+
+        destination_identities = [participant_identity] if participant_identity else []
+        data_packet = json.dumps({"type": "alert", "message": message}).encode("utf-8")
+
+        try:
+            await self.lk_api.room.send_data(
+                api.SendDataRequest(
+                    room=call_id,
+                    data=data_packet,
+                    kind=1,  # 1 = RELIABLE, 0 = LOSSY
+                    destination_identities=destination_identities,
+                )
+            )
+            logger.info(f"✓ Alert sent successfully to {target}")
+        except Exception as e:
+            logger.error(f"Failed to send alert to {target}: {e}", exc_info=True)
+            raise LiveKitError(f"Failed to send alert: {e}") from e
+
+    async def get_participant_identities(self, call_id: str) -> List[Dict[str, Any]]:
+        """Gets a list of all participants in a room with their tracks.
+
+        Args:
+            call_id (str): The room name (call_id).
+
+        Returns:
+            List[Dict[str, Any]]: A list of dictionaries, each containing
+            information about a participant.
+
+            Example:
+                [
+                    {
+                        "identity": "participant-1",
+                        "name": "Participant One",
+                        "tracks": [
+                            {
+                                "sid": "TR_abc123",
+                                "type": "audio",
+                                "muted": False,
+                                "source": "MICROPHONE"
+                            }
+                        ]
+                    }
+                ]
+        """
+        logger.info(f"Fetching participants for room '{call_id}'")
+        try:
+            response = await self.lk_api.room.list_participants(
+                api.ListParticipantsRequest(room=call_id)
+            )
+            participants = []
+            for p in response.participants:
+                tracks = []
+                for track in p.tracks:
+                    tracks.append(
+                        {
+                            "sid": track.sid,
+                            "type": (
+                                "audio"
+                                if track.type == 1
+                                else "video" if track.type == 2 else "unknown"
+                            ),
+                            "muted": track.muted,
+                            "source": (
+                                track.source.name
+                                if hasattr(track.source, "name")
+                                else str(track.source)
+                            ),
+                        }
+                    )
+                participants.append(
+                    {"identity": p.identity, "name": p.name, "tracks": tracks}
+                )
+            logger.info(
+                f"✓ Found {len(participants)} participant(s) in room '{call_id}'"
+            )
+            for p in participants:
+                logger.info(
+                    f"  - {p['identity']} ({p['name']}): {len(p['tracks'])} track(s)"
+                )
+            return participants
+        except Exception as e:
+            logger.error(
+                f"Failed to fetch participants for room '{call_id}': {e}", exc_info=True
+            )
+            raise LiveKitRoomError(f"Failed to fetch participants: {e}") from e

intellema_vdk/providers/livekit/exceptions.py

@@ -0,0 +1,23 @@
+class LiveKitError(Exception):
+    """Base exception for all LiveKit-related errors."""
+    pass
+
+class LiveKitConfigurationError(LiveKitError):
+    """Raised when configuration (URL, API Key, Secret) is missing or invalid."""
+    pass
+
+class LiveKitRoomError(LiveKitError):
+    """Raised when creating, deleting, or managing a room fails."""
+    pass
+
+class LiveKitSIPError(LiveKitError):
+    """Raised when SIP trunking or participant operations fail."""
+    pass
+
+class LiveKitDispatchError(LiveKitError):
+    """Raised when agent dispatch operations fail."""
+    pass
+
+class LiveKitEgressError(LiveKitError):
+    """Raised when starting or managing egress (recording/streaming) fails."""
+    pass

intellema_vdk/providers/protocols.py

@@ -0,0 +1,33 @@
+from typing import List, Optional, Protocol, runtime_checkable
+
+@runtime_checkable
+class VoiceProvider(Protocol):
+    """Protocol defining the interface for voice providers."""
+
+    async def start_outbound_call(self, phone_number: str, prompt_content: str, call_id: Optional[str] = None) -> str:
+        """Initiates an outbound call and returns the call/room ID."""
+        ...
+
+    async def delete_room(self, call_id: str) -> None:
+        """Ends the call/room."""
+        ...
+
+    async def start_stream(self, call_id: str, rtmp_urls: List[str]) -> None:
+        """Starts streaming the call to RTMP URLs."""
+        ...
+
+    async def start_recording(self, call_id: str, output_filepath: Optional[str] = None, upload_to_s3: bool = True, wait_for_completion: bool = True) -> str:
+        """Starts recording the call and returns the recording ID."""
+        ...
+
+    async def kick_participant(self, call_id: str, identity: str) -> None:
+        """Removes a participant from the call."""
+        ...
+
+    async def mute_participant(self, call_id: str, identity: str, track_sid: str, muted: bool) -> None:
+        """Mutes or unmutes a participant's track."""
+        ...
+
+    async def send_alert(self, call_id: str, message: str, participant_identity: Optional[str] = None) -> None:
+        """Sends a data message/alert to the call."""
+        ...

intellema_vdk/providers/retell/__init__.py

@@ -0,0 +1,17 @@
+from .client import RetellManager
+from .exceptions import (
+    RetellError,
+    RetellConfigurationError,
+    RetellAPIError,
+    RetellPhoneNumberError,
+    RetellCallError,
+)
+
+__all__ = [
+    "RetellManager",
+    "RetellError",
+    "RetellConfigurationError",
+    "RetellAPIError",
+    "RetellPhoneNumberError",
+    "RetellCallError",
+]