intellema-vdk 0.1.0__tar.gz

intellema_vdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intellema
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

intellema_vdk-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include requirements.txt
+include LICENSE
+recursive-include intellema_vdk *

intellema_vdk-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: intellema-vdk
+Version: 0.1.0
+Summary: A Voice Development Kit for different Voice Agent Platforms
+Author: Intellema
+License: MIT License
+        
+        Copyright (c) 2026 Intellema
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: livekit-api>=1.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: twilio
+Requires-Dist: retell-sdk
+Requires-Dist: requests
+Dynamic: license-file
+
+# Intellema VDK
+
+Intellema VDK is a unified Voice Development Kit designed to simplify the integration and management of various voice agent platforms. It provides a consistent, factory-based API to interact with providers like LiveKit and Retell AI, enabling developers to build scalable voice applications with ease. Whether you need real-time streaming, outbound calling, or participant management, Intellema VDK abstracts the complexity into a single, intuitive interface.
+
+## Features
+
+- **Room Management**: Create and delete rooms dynamically.
+- **Participant Management**: Generate tokens, kick users, and mute tracks.
+- **SIP Outbound Calling**: Initiate calls to phone numbers via SIP trunks.
+- **Streaming & Recording**: Stream to RTMP destinations and record room sessions directly to AWS S3.
+- **Real-time Alerts**: Send data packets (alerts) to participants.
+
+## Prerequisites
+
+- Python 3.8+
+- A SIP Provider (for outbound calls)
+
+## Installation
+
+```bash
+pip install intellema-vdk
+```
+
+## Usage
+
+### Unified Wrapper (Factory Pattern)
+
+The recommended way to use the library is via the `VoiceClient` factory:
+
+```python
+import asyncio
+from intellema_vdk import VoiceClient
+
+async def main():
+    # 1. Initialize the client
+    client = VoiceClient("livekit") 
+
+    # 2. Use methods directly
+    call_id = await client.start_outbound_call(
+        phone_number="+15551234567",
+        prompt_content="Hello from LiveKit"
+    )
+    
+    # 3. Clean API calls
+    await client.mute_participant(call_id, "user-1", "track-1", True)
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Convenience Function
+
+For quick one-off calls, you can still use the helper:
+
+```python
+from intellema_vdk import start_outbound_call
+
+await start_outbound_call("livekit", phone_number="+1...")
+```
+
+
+## Configuration
+
+Create a `.env` file in the root directory:
+
+```bash
+LIVEKIT_URL=wss://your-livekit-domain.com
+LIVEKIT_API_KEY=your-key
+LIVEKIT_API_SECRET=your-secret
+SIP_OUTBOUND_TRUNK_ID=your-trunk-id
+TWILIO_ACCOUNT_SID=your-sid
+TWILIO_AUTH_TOKEN=your-token
+TWILIO_PHONE_NUMBER=your-number
+RETELL_API_KEY=your-retell-key
+RETELL_AGENT_ID=your-agent-id
+```
+
+

intellema_vdk-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Intellema VDK
+
+Intellema VDK is a unified Voice Development Kit designed to simplify the integration and management of various voice agent platforms. It provides a consistent, factory-based API to interact with providers like LiveKit and Retell AI, enabling developers to build scalable voice applications with ease. Whether you need real-time streaming, outbound calling, or participant management, Intellema VDK abstracts the complexity into a single, intuitive interface.
+
+## Features
+
+- **Room Management**: Create and delete rooms dynamically.
+- **Participant Management**: Generate tokens, kick users, and mute tracks.
+- **SIP Outbound Calling**: Initiate calls to phone numbers via SIP trunks.
+- **Streaming & Recording**: Stream to RTMP destinations and record room sessions directly to AWS S3.
+- **Real-time Alerts**: Send data packets (alerts) to participants.
+
+## Prerequisites
+
+- Python 3.8+
+- A SIP Provider (for outbound calls)
+
+## Installation
+
+```bash
+pip install intellema-vdk
+```
+
+## Usage
+
+### Unified Wrapper (Factory Pattern)
+
+The recommended way to use the library is via the `VoiceClient` factory:
+
+```python
+import asyncio
+from intellema_vdk import VoiceClient
+
+async def main():
+    # 1. Initialize the client
+    client = VoiceClient("livekit") 
+
+    # 2. Use methods directly
+    call_id = await client.start_outbound_call(
+        phone_number="+15551234567",
+        prompt_content="Hello from LiveKit"
+    )
+    
+    # 3. Clean API calls
+    await client.mute_participant(call_id, "user-1", "track-1", True)
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Convenience Function
+
+For quick one-off calls, you can still use the helper:
+
+```python
+from intellema_vdk import start_outbound_call
+
+await start_outbound_call("livekit", phone_number="+1...")
+```
+
+
+## Configuration
+
+Create a `.env` file in the root directory:
+
+```bash
+LIVEKIT_URL=wss://your-livekit-domain.com
+LIVEKIT_API_KEY=your-key
+LIVEKIT_API_SECRET=your-secret
+SIP_OUTBOUND_TRUNK_ID=your-trunk-id
+TWILIO_ACCOUNT_SID=your-sid
+TWILIO_AUTH_TOKEN=your-token
+TWILIO_PHONE_NUMBER=your-number
+RETELL_API_KEY=your-retell-key
+RETELL_AGENT_ID=your-agent-id
+```
+
+

intellema_vdk-0.1.0/intellema_vdk/__init__.py

@@ -0,0 +1,38 @@
+from typing import Optional, List, Any
+import os
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+from .livekit_lib.client import LiveKitManager
+from .retell_lib.retell_client import RetellManager
+
+def VoiceClient(provider: str, **kwargs) -> Any:
+    """
+    Factory function that returns a specific provider client.
+    
+    Args:
+        provider: "livekit" or "retell"
+        **kwargs: Arguments passed to the manager's constructor
+    
+    Returns:
+        An instance of LiveKitManager or RetellManager
+    """
+    if provider == "livekit":
+        return LiveKitManager(**kwargs)
+    elif provider == "retell":
+        return RetellManager(**kwargs)
+    else:
+        raise ValueError(f"Unknown provider: {provider}. Supported providers: 'livekit', 'retell'")
+
+async def start_outbound_call(provider: str, *args, **kwargs):
+    """
+    Convenience wrapper to start an outbound call.
+    """
+    client = VoiceClient(provider)
+    # Check if the method is async (LiveKit) or sync (Retell)
+    if provider == "livekit":
+        return await client.start_outbound_call(*args, **kwargs)
+    else:
+        return client.start_outbound_call(*args, **kwargs)

intellema_vdk-0.1.0/intellema_vdk/livekit_lib/__init__.py

@@ -0,0 +1,3 @@
+from .client import LiveKitManager
+
+__all__ = ["LiveKitManager"]

intellema_vdk-0.1.0/intellema_vdk/livekit_lib/client.py

@@ -0,0 +1,280 @@
+import os
+import json
+import uuid
+import asyncio
+import time
+import boto3
+from typing import List, Optional
+from dotenv import load_dotenv
+from livekit import api
+
+# Load environment variables
+load_dotenv(dotenv_path=".env.local")
+load_dotenv()
+
+class LiveKitManager:
+    def __init__(self):
+        self.url = os.getenv("LIVEKIT_URL")
+        self.api_key = os.getenv("LIVEKIT_API_KEY")
+        self.api_secret = os.getenv("LIVEKIT_API_SECRET")
+        self.sip_trunk_id = os.getenv("SIP_OUTBOUND_TRUNK_ID")
+
+        if not self.url or not self.api_key or not self.api_secret:
+            raise ValueError("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):
+        await self.lk_api.aclose()
+
+    async def start_outbound_call(self, phone_number: str, prompt_content: str, call_id: str = None, timeout: int = 600):
+        if not call_id:
+            call_id = f"outbound_call_{uuid.uuid4().hex[:12]}"
+
+        metadata = json.dumps({
+            "phone_number": phone_number,
+            "prompt_content": prompt_content
+        })
+
+        # 1. Create room with metadata
+        room = await self.lk_api.room.create_room(
+            api.CreateRoomRequest(
+                name=call_id,
+                empty_timeout=timeout,
+                metadata=metadata
+            )
+        )
+
+        # 2. Dispatch agent
+        await self.lk_api.agent_dispatch.create_dispatch(
+            api.CreateAgentDispatchRequest(
+                room=call_id,
+                agent_name="outbound-caller",
+                metadata=metadata
+            )
+        )
+
+        # 3. Initiate Outbound Call (SIP/PSTN)
+        if not self.sip_trunk_id:
+            raise ValueError("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,
+                )
+            )
+        except Exception as e:
+            # Handle SIP Busy/Error 
+            if "Busy Here" in str(e) or "486" in str(e):
+                print(f"Call failed: User is busy ({phone_number})")
+                # We might want to clean up the room if the call failed
+                await self.delete_room(call_id)
+                raise ValueError("User is busy")
+            raise e
+
+        return room
+
+    async def create_token(self, call_id: str, participant_name: str) -> str:
+        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,
+        ))
+        return token.to_jwt()
+
+    async def delete_room(self, call_id: str):
+        await self.lk_api.room.delete_room(api.DeleteRoomRequest(room=call_id))
+
+    async def start_stream(self, call_id: str, rtmp_urls: List[str]):
+        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
+                    )
+                ]
+            )
+        )
+
+    async def start_recording(self, call_id: str, output_filepath: Optional[str] = None, upload_to_s3: bool = True, wait_for_completion: bool = True):
+        """
+        Start recording a room.
+        
+        Args:
+            call_id: Name of the room/call to record.
+            output_filepath: Optional path/filename for the recording.
+            upload_to_s3: If True, uploads to S3 (requires env vars). If False, saves locally on Egress server.
+            wait_for_completion: If True, waits for the recording to finish and downloads it locally (if upload_to_s3 is True).
+        """
+        file_output = None
+        filename = output_filepath if output_filepath else f"{call_id}-{uuid.uuid4().hex[:6]}.mp4"
+
+        if upload_to_s3:
+            access_key = os.getenv("AWS_ACCESS_KEY_ID")
+            secret_key = os.getenv("AWS_SECRET_ACCESS_KEY")
+            bucket = os.getenv("AWS_S3_BUCKET")
+            region = os.getenv("AWS_REGION")
+            
+            if not access_key or not secret_key or not bucket:
+                raise ValueError("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,
+                ),
+            )
+            print(f"Starting recording. File will be saved to S3: s3://{bucket}/{filename}")
+        else:
+            file_output = api.EncodedFileOutput(
+                file_type=api.EncodedFileType.MP4,
+                filepath=filename,
+            )
+            print(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
+            print(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:
+                    print(f"Error checking egress status: {e}")
+                    await asyncio.sleep(5)
+                    continue
+
+                if not egress_list.items:
+                    print("Egress info not found during polling.")
+                    break
+                
+                info = egress_list.items[0]
+                if info.status == api.EgressStatus.EGRESS_COMPLETE:
+                    print("Egress completed successfully.")
+                    break
+                elif info.status == api.EgressStatus.EGRESS_FAILED:
+                    raise RuntimeError(f"Egress failed: {info.error}")
+                elif info.status == api.EgressStatus.EGRESS_LIMIT_REACHED:
+                     raise RuntimeError(f"Egress limit reached: {info.error}")
+                
+                await asyncio.sleep(5)
+
+            # Download from S3
+            print(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)
+                print(f"Recording downloaded to: {local_path}")
+            except Exception as e:
+                print(f"Failed to download recording: {e}")
+                raise e
+
+    async def kick_participant(self, call_id: str, identity: str):
+        await self.lk_api.room.remove_participant(
+            api.RoomParticipantIdentity(
+                room=call_id,
+                identity=identity
+            )
+        )
+
+    async def mute_participant(self, call_id: str, identity: str, track_sid: str, muted: bool):
+        await self.lk_api.room.mute_published_track(
+            api.MuteRoomTrackRequest(
+                room=call_id,
+                identity=identity,
+                track_sid=track_sid,
+                muted=muted
+            )
+        )
+
+    async def send_alert(self, call_id: str, message: str, participant_identity: Optional[str] = None):
+        destination_identities = [participant_identity] if participant_identity else []
+        data_packet = json.dumps({"type": "alert", "message": message}).encode('utf-8')
+
+        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
+            )
+        )
+
+    async def get_participant_identities(self, call_id: str) -> List[dict]:
+        """
+        Get a list of all participants in a room with their identities and tracks.
+        
+        Returns:
+            List of dicts with participant info:
+            [
+                {
+                    "identity": str,
+                    "name": str,
+                    "tracks": [
+                        {"sid": str, "type": str, "muted": bool, "source": str},
+                        ...
+                    ]
+                },
+                ...
+            ]
+        """
+        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
+            })
+        return participants
+
+    

intellema_vdk-0.1.0/intellema_vdk/retell_lib/retell_client.py

@@ -0,0 +1,190 @@
+import os
+from typing import List, Optional
+from dotenv import load_dotenv
+from twilio.rest import Client
+from retell import Retell
+import time
+import uuid
+import requests
+import boto3
+
+# Load environment variables
+load_dotenv(dotenv_path=".env.local")
+load_dotenv()
+
+class RetellManager:
+    def __init__(self):
+        self.twilio_account_sid = os.getenv("TWILIO_ACCOUNT_SID")
+        self.twilio_auth_token = os.getenv("TWILIO_AUTH_TOKEN")
+        self.twilio_number = os.getenv("TWILIO_PHONE_NUMBER")
+        self.retell_api_key = os.getenv("RETELL_API_KEY")
+        self.retell_agent_id = os.getenv("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 ValueError("Missing necessary environment variables for RetellManager")
+
+        self.twilio_client = Client(self.twilio_account_sid, self.twilio_auth_token)
+        self.retell_client = Retell(api_key=self.retell_api_key)
+
+    def start_outbound_call(self, phone_number: str, prompt_content: str = None, call_id: str = None) -> str:
+        """
+        Initiates an outbound call using Twilio.
+        Registers the call with Retell first, then uses TwiML to connect Twilio to Retell's WebSocket.
+        
+        Args:
+            phone_number: The number to call.
+            prompt_content: Content to override the agent's prompt (passed as 'prompt_content' dynamic variable).
+            call_id: Custom ID for metadata (optional).
+        """
+        # 1. Register call with Retell to get the WebSocket URL
+        register_response = self.retell_client.call.register_phone_call(
+            agent_id=self.retell_agent_id,
+            direction="outbound",
+            from_number=self.twilio_number,
+            to_number=phone_number,
+            metadata={"call_id": call_id} if call_id else None,
+            retell_llm_dynamic_variables={"prompt_content": prompt_content} if prompt_content else None
+        )
+
+        # 2. Construct the audio WebSocket URL using the call_id
+        audio_websocket_url = f"wss://api.retellai.com/audio-websocket/{register_response.call_id}"
+
+        # 3. Construct TwiML to connect Twilio to Retell
+        # Note: We construct the XML string manually to avoid extra dependencies like twilio.twiml
+        twiml = f"""<Response>
+            <Connect>
+                <Stream url="{audio_websocket_url}" />
+            </Connect>
+        </Response>"""
+
+        # 3. Create the call with Twilio using the generated TwiML
+        call = self.twilio_client.calls.create(
+            to=phone_number,
+            from_=self.twilio_number,
+            twiml=twiml
+        )
+        return call.sid
+
+    def delete_room(self, room_name: str):
+        """
+        Ends the call. 'room_name' is interpreted as the Twilio Call SID.
+        Ends both the Retell agent and the Twilio call.
+        """
+        try:
+            # Attempt to end Retell call if mapped, but primarily hang up Twilio
+            # Note: Retell SDK end_call requires retell call id, not twilio sid.
+            # If we don't have the mapping, hanging up Twilio is the most effective way to stop everything.
+            try:
+                self.retell_client.call.end_call(call_id=room_name)
+            except Exception:
+                pass # Ignore if Retell call fails (e.g. invalid ID), ensure Twilio hangs up
+            
+            self.twilio_client.calls(room_name).update(status='completed')
+        except Exception as e:
+            print(f"Error ending call {room_name}: {e}")
+
+    def start_stream(self, room_name: str, rtmp_urls: List[str]):
+        """
+        Starts a Twilio Media Stream.
+        Note: Twilio streams are WebSocket-based. If rtmp_urls contains a WSS URL, it will work.
+        """
+        if not rtmp_urls:
+            raise ValueError("No stream URLs provided")
+            
+        self.twilio_client.calls(room_name).streams.create(
+            url=rtmp_urls[0]
+        )
+
+    def start_recording(self, room_name: str, output_filepath: Optional[str] = None, upload_to_s3: bool = True, wait_for_completion: bool = True):
+        """
+        Triggers a recording on the active Twilio call.
+        
+        Args:
+            room_name: The Twilio Call SID.
+            output_filepath: Optional filename for the recording.
+            upload_to_s3: If True, uploads to S3.
+            wait_for_completion: If True, waits for recording to finish and then uploads.
+        
+        Returns:
+            The Twilio Recording SID.
+        """
+        
+        # Start Twilio recording
+        recording = self.twilio_client.calls(room_name).recordings.create()
+        print(f"Recording started: {recording.sid}")
+        
+        if not wait_for_completion:
+            return recording.sid
+        
+        # Poll for recording completion
+        print("Waiting for recording to complete...")
+        while True:
+            rec_status = self.twilio_client.recordings(recording.sid).fetch()
+            if rec_status.status == 'completed':
+                print("Recording completed.")
+                break
+            elif rec_status.status in ['failed', 'absent']:
+                raise RuntimeError(f"Recording failed with status: {rec_status.status}")
+            time.sleep(5)
+        
+        if not upload_to_s3:
+            return recording.sid
+        
+        # Download recording from Twilio
+        media_url = f"https://api.twilio.com/2010-04-01/Accounts/{self.twilio_account_sid}/Recordings/{recording.sid}.mp3"
+        print(f"Downloading recording from: {media_url}")
+        
+        response = requests.get(media_url, auth=(self.twilio_account_sid, self.twilio_auth_token))
+        if response.status_code != 200:
+            raise RuntimeError(f"Failed to download recording: {response.status_code} {response.text}")
+        
+        # Upload to S3
+        access_key = os.getenv("AWS_ACCESS_KEY_ID")
+        secret_key = os.getenv("AWS_SECRET_ACCESS_KEY")
+        bucket = os.getenv("AWS_S3_BUCKET")
+        region = os.getenv("AWS_REGION")
+        
+        if not access_key or not secret_key or not bucket:
+            raise ValueError("AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET) are required for S3 upload.")
+        
+        filename = output_filepath if output_filepath else f"{room_name}-{uuid.uuid4().hex[:6]}.mp3"
+        
+        s3 = boto3.client(
+            's3',
+            aws_access_key_id=access_key,
+            aws_secret_access_key=secret_key,
+            region_name=region
+        )
+        
+        print(f"Uploading to S3: s3://{bucket}/{filename}")
+        s3.put_object(Bucket=bucket, Key=filename, Body=response.content)
+        print(f"Upload complete: s3://{bucket}/{filename}")
+        
+        # Also save locally
+        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)
+        print(f"Recording saved locally: {local_path}")
+        
+        return recording.sid
+
+    def mute_participant(self, room_name: str, identity: str, track_sid: str, muted: bool):
+        """
+        Mutes the participant on the Twilio call.
+        This prevents audio from reaching the Retell AI.
+        """
+        self.twilio_client.calls(room_name).update(muted=muted)
+
+    def kick_participant(self, room_name: str, identity: str):
+        """
+        Alias for delete_room (hangup).
+        """
+        self.delete_room(room_name)
+
+    def send_alert(self, room_name: str, message: str, participant_identity: Optional[str] = None):
+        """
+        Not fully supported in this hybrid model
+        """
+        raise NotImplementedError("send_alert is not currently supported in RetellManager")

intellema_vdk-0.1.0/intellema_vdk.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: intellema-vdk
+Version: 0.1.0
+Summary: A Voice Development Kit for different Voice Agent Platforms
+Author: Intellema
+License: MIT License
+        
+        Copyright (c) 2026 Intellema
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: livekit-api>=1.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: twilio
+Requires-Dist: retell-sdk
+Requires-Dist: requests
+Dynamic: license-file
+
+# Intellema VDK
+
+Intellema VDK is a unified Voice Development Kit designed to simplify the integration and management of various voice agent platforms. It provides a consistent, factory-based API to interact with providers like LiveKit and Retell AI, enabling developers to build scalable voice applications with ease. Whether you need real-time streaming, outbound calling, or participant management, Intellema VDK abstracts the complexity into a single, intuitive interface.
+
+## Features
+
+- **Room Management**: Create and delete rooms dynamically.
+- **Participant Management**: Generate tokens, kick users, and mute tracks.
+- **SIP Outbound Calling**: Initiate calls to phone numbers via SIP trunks.
+- **Streaming & Recording**: Stream to RTMP destinations and record room sessions directly to AWS S3.
+- **Real-time Alerts**: Send data packets (alerts) to participants.
+
+## Prerequisites
+
+- Python 3.8+
+- A SIP Provider (for outbound calls)
+
+## Installation
+
+```bash
+pip install intellema-vdk
+```
+
+## Usage
+
+### Unified Wrapper (Factory Pattern)
+
+The recommended way to use the library is via the `VoiceClient` factory:
+
+```python
+import asyncio
+from intellema_vdk import VoiceClient
+
+async def main():
+    # 1. Initialize the client
+    client = VoiceClient("livekit") 
+
+    # 2. Use methods directly
+    call_id = await client.start_outbound_call(
+        phone_number="+15551234567",
+        prompt_content="Hello from LiveKit"
+    )
+    
+    # 3. Clean API calls
+    await client.mute_participant(call_id, "user-1", "track-1", True)
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Convenience Function
+
+For quick one-off calls, you can still use the helper:
+
+```python
+from intellema_vdk import start_outbound_call
+
+await start_outbound_call("livekit", phone_number="+1...")
+```
+
+
+## Configuration
+
+Create a `.env` file in the root directory:
+
+```bash
+LIVEKIT_URL=wss://your-livekit-domain.com
+LIVEKIT_API_KEY=your-key
+LIVEKIT_API_SECRET=your-secret
+SIP_OUTBOUND_TRUNK_ID=your-trunk-id
+TWILIO_ACCOUNT_SID=your-sid
+TWILIO_AUTH_TOKEN=your-token
+TWILIO_PHONE_NUMBER=your-number
+RETELL_API_KEY=your-retell-key
+RETELL_AGENT_ID=your-agent-id
+```
+
+

intellema_vdk-0.1.0/intellema_vdk.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+intellema_vdk/__init__.py
+intellema_vdk.egg-info/PKG-INFO
+intellema_vdk.egg-info/SOURCES.txt
+intellema_vdk.egg-info/dependency_links.txt
+intellema_vdk.egg-info/requires.txt
+intellema_vdk.egg-info/top_level.txt
+intellema_vdk/livekit_lib/__init__.py
+intellema_vdk/livekit_lib/client.py
+intellema_vdk/livekit_lib/__pycache__/__init__.cpython-312.pyc
+intellema_vdk/livekit_lib/__pycache__/client.cpython-312.pyc
+intellema_vdk/retell_lib/__init__.py
+intellema_vdk/retell_lib/retell_client.py
+intellema_vdk/retell_lib/__pycache__/__init__.cpython-312.pyc
+intellema_vdk/retell_lib/__pycache__/retell_client.cpython-312.pyc
+tests/test_retell_hybrid.py

intellema_vdk-0.1.0/intellema_vdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

intellema_vdk-0.1.0/intellema_vdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+livekit-api>=1.1.0
+python-dotenv>=1.0.0
+boto3>=1.28.0
+twilio
+retell-sdk
+requests

intellema_vdk-0.1.0/intellema_vdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+intellema_vdk

intellema_vdk-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "intellema-vdk"
+version = "0.1.0"
+description = "A Voice Development Kit for different Voice Agent Platforms"
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+authors = [
+  {name = "Intellema"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "livekit-api>=1.1.0",
+    "python-dotenv>=1.0.0",
+    "boto3>=1.28.0",
+    "twilio",
+    "retell-sdk",
+    "requests"
+]
+
+
+
+[tool.setuptools.packages.find]
+include = ["intellema_vdk*"]

intellema_vdk-0.1.0/requirements.txt

@@ -0,0 +1,6 @@
+livekit-api>=1.1.0
+python-dotenv>=1.0.0
+boto3>=1.28.0
+twilio
+retell-sdk
+requests

intellema_vdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

intellema_vdk-0.1.0/tests/test_retell_hybrid.py

@@ -0,0 +1,71 @@
+import unittest
+from unittest.mock import MagicMock, patch
+import os
+import sys
+
+# Add the project root to the python path so we can import retell_lib
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+# Mock environment variables before importing RetellManager
+with patch.dict(os.environ, {
+    "TWILIO_ACCOUNT_SID": "ACmock",
+    "TWILIO_AUTH_TOKEN": "mock_token",
+    "TWILIO_PHONE_NUMBER": "+1234567890",
+    "RETELL_API_KEY": "mock_retell_key",
+    "WEBHOOK_URL": "https://example.com"
+}):
+    from retell_lib.retell_client import RetellManager
+
+class TestRetellManager(unittest.TestCase):
+    @patch.dict(os.environ, {
+        "TWILIO_ACCOUNT_SID": "ACmock",
+        "TWILIO_AUTH_TOKEN": "mock_token",
+        "TWILIO_PHONE_NUMBER": "+1234567890",
+        "RETELL_API_KEY": "mock_retell_key",
+        "RETELL_AGENT_ID": "mock_agent_id"
+    })
+    def setUp(self):
+        self.manager = RetellManager()
+        # Mock the clients
+        self.manager.twilio_client = MagicMock()
+        self.manager.retell_client = MagicMock()
+
+    def test_start_outbound_call(self):
+        # Mock Retell register response
+        mock_register_response = MagicMock()
+        mock_register_response.audio_websocket_url = "wss://api.retellai.com/socket"
+        self.manager.retell_client.call.register.return_value = mock_register_response
+        
+        # Mock Twilio call creation
+        self.manager.twilio_client.calls.create.return_value.sid = "CA123"
+        
+        sid = self.manager.start_outbound_call("+15550000000")
+        
+        # Verify Retell register called
+        self.manager.retell_client.call.register.assert_called_once()
+        
+        # Verify Twilio create called with TwiML
+        self.manager.twilio_client.calls.create.assert_called_once()
+        call_args = self.manager.twilio_client.calls.create.call_args[1]
+        self.assertEqual(call_args['to'], "+15550000000")
+        self.assertIn("<Stream url=\"wss://api.retellai.com/socket\" />", call_args['twiml'])
+        self.assertEqual(sid, "CA123")
+
+    def test_delete_room(self):
+        self.manager.delete_room("CA123")
+        # Retell client end_call should be called
+        self.manager.retell_client.call.end_call.assert_called_with(call_id="CA123")
+        # Twilio client update should be called
+        self.manager.twilio_client.calls.assert_called_with("CA123")
+        self.manager.twilio_client.calls("CA123").update.assert_called_with(status='completed')
+
+    def test_start_recording(self):
+        self.manager.start_recording("CA123")
+        self.manager.twilio_client.calls("CA123").recordings.create.assert_called_once()
+
+    def test_mute_participant(self):
+        self.manager.mute_participant("CA123", "user", "track", True)
+        self.manager.twilio_client.calls("CA123").update.assert_called_with(muted=True)
+
+if __name__ == '__main__':
+    unittest.main()