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

intellema_vdk/__init__.py

@@ -1,12 +1,9 @@
 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
+from .speech_lib.stt_client import STTManager
+from .speech_lib.tts_streamer import TTSStreamer
 
 def VoiceClient(provider: str, **kwargs) -> Any:
     """

intellema_vdk/retell_lib/import_phone_number.py

@@ -0,0 +1,73 @@
+import os
+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
+
+def import_twilio_number():
+    """
+    Import your Twilio phone number to Retell.
+    This is required before you can make outbound calls using Retell.
+    """
+    try:
+        manager = RetellManager()
+        
+        print("=== Retell Phone Number Import ===\n")
+        print(f"Phone Number to import: {manager.twilio_number}")
+        print(f"Agent ID to bind: {manager.retell_agent_id}\n")
+        
+        # Ask if user has a Twilio SIP trunk
+        print("Do you have a Twilio Elastic SIP Trunk configured?")
+        print("If you're not sure, you can:")
+        print("  1. Visit: https://console.twilio.com/us1/develop/voice/manage/trunks")
+        print("  2. Or just press Enter to try without it (may not work for some setups)\n")
+        
+        has_trunk = input("Do you have a SIP trunk? (y/n, default: n): ").strip().lower()
+        
+        termination_uri = None
+        sip_username = None
+        sip_password = None
+        
+        if has_trunk == 'y':
+            print("\nEnter your Twilio SIP Trunk Termination URI.")
+            print("Format: yourtrunkname.pstn.twilio.com")
+            print("You can find this in Twilio Console > Elastic SIP Trunking > Your Trunk > Termination")
+            termination_uri = input("Termination URI: ").strip()
+            
+            print("\nDo you use Credential List authentication? (Recommended)")
+            has_creds = input("Use credentials? (y/n, default: y): ").strip().lower() or 'y'
+            
+            if has_creds == 'y':
+                print("Enter the username/password from your Twilio Credential List:")
+                sip_username = input("Username: ").strip()
+                sip_password = input("Password: ").strip()
+        
+        # Optional nickname
+        nickname = input("\nOptional: Enter a nickname for this number (press Enter to skip): ").strip() or None
+        
+        print(f"\n=== Importing Phone Number ===")
+        
+        response = manager.import_phone_number(
+            termination_uri=termination_uri,
+            nickname=nickname,
+            sip_trunk_auth_username=sip_username,
+            sip_trunk_auth_password=sip_password
+        )
+        
+        print(f"\n=== Import Successful! ===")
+        print(f"You can now use this number to make outbound calls via Retell.")
+        
+        return response
+        
+    except Exception as e:
+        print(f"\n✗ Import failed: {e}")
+        print(f"\nTroubleshooting:")
+        print(f"  1. If you don't have a SIP trunk, you may need to purchase the number through Retell")
+        print(f"  2. Visit Retell dashboard: https://app.retellai.com/")
+        print(f"  3. Or create a Twilio Elastic SIP Trunk first")
+        raise
+
+if __name__ == "__main__":
+    import_twilio_number()

intellema_vdk/retell_lib/retell_client.py

@@ -26,64 +26,122 @@ class 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:
+    def import_phone_number(self, termination_uri: str = None, outbound_agent_id: str = None, inbound_agent_id: str = None, nickname: str = None, sip_trunk_auth_username: str = None, sip_trunk_auth_password: str = None):
         """
-        Initiates an outbound call using Twilio.
-        Registers the call with Retell first, then uses TwiML to connect Twilio to Retell's WebSocket.
+        Import/register your Twilio phone number with Retell.
+        This is required before you can make outbound calls using the phone number.
         
         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).
+            termination_uri: Twilio SIP trunk termination URI (e.g., "yourtrunk.pstn.twilio.com").
+                           If not provided, will try to use a default format.
+            outbound_agent_id: Agent ID to use for outbound calls. Defaults to self.retell_agent_id.
+            inbound_agent_id: Agent ID to use for inbound calls. Defaults to None (no inbound).
+            nickname: Optional nickname for the phone number.
+            sip_trunk_auth_username: Username for SIP trunk authentication (if using credential list).
+            sip_trunk_auth_password: Password for SIP trunk authentication (if using credential list).
+        
+        Returns:
+            The phone number registration response from Retell.
         """
-        # 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
-        )
+        # Build the import kwargs
+        import_kwargs = {
+            "phone_number": self.twilio_number,
+        }
+        
+        # Add termination URI if provided
+        if termination_uri:
+            import_kwargs["termination_uri"] = termination_uri
+        
+        # Add SIP credentials if provided
+        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
+        
+        # Set outbound agent (required for outbound calls)
+        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
+        
+        # Set inbound agent if provided
+        if inbound_agent_id:
+            import_kwargs["inbound_agent_id"] = inbound_agent_id
+        
+        # Add nickname if provided
+        if nickname:
+            import_kwargs["nickname"] = nickname
+        
+        try:
+            response = self.retell_client.phone_number.import_(**import_kwargs)
+            print(f"✓ Phone number {self.twilio_number} successfully imported to Retell!")
+            print(f"  Phone Number: {response.phone_number}")
+            print(f"  Type: {response.phone_number_type}")
+            if hasattr(response, 'outbound_agent_id') and response.outbound_agent_id:
+                print(f"  Outbound Agent: {response.outbound_agent_id}")
+            if hasattr(response, 'inbound_agent_id') and response.inbound_agent_id:
+                print(f"  Inbound Agent: {response.inbound_agent_id}")
+            return response
+        except Exception as e:
+            print(f"✗ Error importing phone number: {e}")
+            print(f"\nNote: If you're using Twilio, you may need to:")
+            print(f"  1. Create an Elastic SIP Trunk in Twilio console")
+            print(f"  2. Provide the termination_uri parameter (e.g., 'yourtrunk.pstn.twilio.com')")
+            print(f"  3. Or purchase the number directly through Retell dashboard")
+            raise
 
-        # 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.
-        """
+    def start_outbound_call(self, phone_number: str, prompt_content: str = None, call_id: str = None) -> str:
+        call_kwargs = {
+            "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}
+    
+    # Only set up dynamic variables if we have a custom prompt
+        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"
+            }
+    
+        call_response = self.retell_client.call.create_phone_call(**call_kwargs)
+    
+        print(f"Call created successfully!")
+        print(f"Retell Call ID: {call_response.call_id}")
+        print(f"Call Status: {call_response.call_status}")
+    
+        return call_response.call_id
+
+    def delete_room(self, call_id: str):
         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')
+            call_data = self.retell_client.call.retrieve(call_id)
+            print(f"Current call status: {call_data.call_status}")
+
+            if call_data.call_status in ['registered', 'ongoing', 'dialing']:
+                print(f"Triggering end for Retell call {call_id}...")
+
+                self.retell_client.call.update(
+                    call_id,
+                    override_dynamic_variables={"force_end": "true"}
+                )
+
+                print("✓ force_end override sent to Retell API")
+            else:
+                print(f"Call already ended: {call_data.call_status}")
+
         except Exception as e:
-            print(f"Error ending call {room_name}: {e}")
+            print(f"Error ending call {call_id}: {e}")
+            raise
 
-    def start_stream(self, room_name: str, rtmp_urls: List[str]):
+    def start_stream(self, call_id: 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.
@@ -91,16 +149,16 @@ class RetellManager:
         if not rtmp_urls:
             raise ValueError("No stream URLs provided")
             
-        self.twilio_client.calls(room_name).streams.create(
+        self.twilio_client.calls(call_id).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):
+    def start_recording(self, call_id: 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.
+            call_id: 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.
@@ -110,7 +168,7 @@ class RetellManager:
         """
         
         # Start Twilio recording
-        recording = self.twilio_client.calls(room_name).recordings.create()
+        recording = self.twilio_client.calls(call_id).recordings.create()
         print(f"Recording started: {recording.sid}")
         
         if not wait_for_completion:
@@ -147,7 +205,7 @@ class RetellManager:
         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"
+        filename = output_filepath if output_filepath else f"{call_id}-{uuid.uuid4().hex[:6]}.mp3"
         
         s3 = boto3.client(
             's3',
@@ -170,20 +228,20 @@ class RetellManager:
         
         return recording.sid
 
-    def mute_participant(self, room_name: str, identity: str, track_sid: str, muted: bool):
+    def mute_participant(self, call_id: 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)
+        self.twilio_client.calls(call_id).update(muted=muted)
 
-    def kick_participant(self, room_name: str, identity: str):
+    def kick_participant(self, call_id: str, identity: str):
         """
         Alias for delete_room (hangup).
         """
-        self.delete_room(room_name)
+        self.delete_room(call_id)
 
-    def send_alert(self, room_name: str, message: str, participant_identity: Optional[str] = None):
+    def send_alert(self, call_id: str, message: str, participant_identity: Optional[str] = None):
         """
         Not fully supported in this hybrid model
         """

intellema_vdk/speech_lib/__init__.py

@@ -0,0 +1,2 @@
+from .stt_client import STTManager
+from .tts_streamer import TTSStreamer

intellema_vdk/speech_lib/stt_client.py

@@ -0,0 +1,108 @@
+import os
+import logging
+import httpx
+from dotenv import load_dotenv
+from openai import AsyncOpenAI
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+
+class STTManager:
+    def __init__(self):
+        """
+        Initializes the STTManager.
+        
+        Note:
+            The following must be set in your .env file:
+            - OPENAI_API_KEY
+            - AGENT_API_URL (If not set, posting to agent will be disabled)
+        """
+        self._api_key = os.getenv("OPENAI_API_KEY")
+        if not self._api_key:
+            raise ValueError("OPENAI_API_KEY must be set in your .env file.")
+        
+        self._agent_api_url = os.getenv("AGENT_API_URL")
+        if not self._agent_api_url:
+            logger.warning("AGENT_API_URL is not set in .env. Posting to agent will be disabled.")
+        
+        self._openai_client = AsyncOpenAI(api_key=self._api_key)
+        self._http_client = httpx.AsyncClient()
+
+    async def close(self):
+        """
+        Cleans up resources used by the STTManager.
+        """
+        await self._http_client.aclose()
+        await self._openai_client.close()
+
+    async def transcribe_audio(self, file_path: str, model: str = "whisper-1") -> str:
+        """
+        Transcribes an audio file using OpenAI's whisper model.
+
+        Args:
+            file_path: The path to the audio file to transcribe. 
+                       Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, and webm.
+            model: The name of the whisper model to use.
+                   Note: The OpenAI API currently only supports "whisper-1".
+        Returns:
+            The transcribed text as a string.
+        """
+        logger.info(f"Starting transcription for file: {file_path}")
+        if not os.path.exists(file_path):
+            raise FileNotFoundError(f"Audio file not found at: {file_path}")
+
+        with open(file_path, "rb") as audio_file:
+            transcript = await self._openai_client.audio.transcriptions.create(
+                model=model,
+                file=audio_file
+            )
+        logger.info(f"Successfully transcribed file: {file_path}")
+
+        return transcript.text
+
+    async def transcribe_and_post(self, file_path: str):
+        """
+        Processes an audio file by transcribing it and posting the result to the agent API under a 'message' key.
+
+        Args:
+            file_path: The path to the audio file to process.
+                       Supported formats: mp3, mp4, mpeg, mpga, m4a, wav, and webm.
+        Returns:
+            The transcribed text as a string.
+        """
+        try:
+            # Transcribe the audio file
+            transcript_text = await self.transcribe_audio(file_path)
+
+            # Post the transcribed text to the agent API
+            if self._agent_api_url:
+                await self._post_to_agent(transcript_text)
+            else:
+                logger.info("AGENT_API_URL not set, skipping post to agent.")
+            
+            return transcript_text
+
+        except FileNotFoundError:
+            logger.error(f"Audio file not found at: {file_path}", exc_info=True)
+            raise
+        except Exception as e:
+            logger.error(f"An error occurred during processing of {file_path}: {e}", exc_info=True)
+            raise
+
+    async def _post_to_agent(self, text: str):
+        """
+        Posts the transcribed text to the agent API under a 'message' key.
+        
+        Args:
+            text: The transcribed text to post.
+        """
+        payload = {"message": text}
+        try:
+            logger.info(f"Posting to agent with payload: {payload}")
+            response = await self._http_client.post(self._agent_api_url, json=payload)
+            response.raise_for_status()
+            logger.info(f"Successfully posted to agent. Status: {response.status_code}")
+        except httpx.HTTPError as e:
+            logger.error(f"Failed to post to agent API: {e}", exc_info=True)
+            raise

intellema_vdk/speech_lib/tts_streamer.py

@@ -0,0 +1,188 @@
+import os
+import queue
+import threading
+import time
+import pyaudio
+from together import Together
+
+
+class TTSStreamer:
+    def __init__(self, api_key=None):
+        self.api_key = api_key or os.environ.get("TOGETHER_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "Together API Key is missing. Set TOGETHER_API_KEY env var."
+            )
+
+        self.client = Together(api_key=self.api_key)
+
+        # Audio Config
+        self.p = pyaudio.PyAudio()
+        self.stream = self.p.open(
+            format=pyaudio.paInt16, channels=1, rate=24000, output=True
+        )
+
+        # Queues
+        self.text_queue = queue.Queue()
+        self.audio_queue = queue.Queue()
+
+        # State
+        self.text_buffer = ""
+        self.is_running = True
+        self.playback_finished = threading.Event()
+
+        # Start Threads
+        self.fetcher_thread = threading.Thread(target=self._tts_fetcher, daemon=True)
+        self.player_thread = threading.Thread(target=self._audio_player, daemon=True)
+
+        self.fetcher_thread.start()
+        self.player_thread.start()
+
+    def feed(self, text_chunk):
+        """Feed text tokens from LLM."""
+        if not self.is_running or not text_chunk:
+            return
+
+        self.text_buffer += text_chunk
+        sentence_endings = [".", "!", "?", "\n"]
+
+        for ending in sentence_endings:
+            if ending in self.text_buffer:
+                parts = self.text_buffer.split(ending)
+
+                # Send all complete sentences
+                for sentence in parts[:-1]:
+                    if sentence.strip():
+                        self.text_queue.put(sentence.strip() + ending)
+
+                # Keep the remainder
+                self.text_buffer = parts[-1]
+
+    def flush(self):
+        """
+        Graceful finish: Push remaining text, signal end, and wait for audio to finish playing.
+        """
+        # 1. Push remaining buffer
+        if self.text_buffer.strip():
+            self.text_queue.put(self.text_buffer.strip())
+
+        # 2. Signal Fetcher to stop expecting text
+        self.text_queue.put(None)
+
+        # 3. Wait for the player to signal it's done
+        # We use a timeout to prevent infinite hanging
+        self.playback_finished.wait(timeout=10.0)
+
+    def close(self):
+        """
+        Immediate kill: Stop threads and close audio stream.
+        """
+        if not self.is_running:
+            return
+
+        self.is_running = False
+
+        # Clear queues to unblock threads if they are stuck
+        with self.text_queue.mutex:
+            self.text_queue.queue.clear()
+        with self.audio_queue.mutex:
+            self.audio_queue.queue.clear()
+
+        try:
+            self.stream.stop_stream()
+            self.stream.close()
+            self.p.terminate()
+        except Exception:
+            pass
+
+    def stop(self):
+        """Alias for close"""
+        self.close()
+
+    def _tts_fetcher(self):
+        while self.is_running:
+            try:
+                text = self.text_queue.get(timeout=0.5)
+            except queue.Empty:
+                continue
+
+            if text is None:
+                self.audio_queue.put(None)  # Signal player to finish
+                break
+
+            try:
+                response = self.client.audio.speech.create(
+                    model="canopylabs/orpheus-3b-0.1-ft",
+                    input=text,
+                    voice="tara",
+                    stream=True,
+                    response_format="raw",
+                    response_encoding="pcm_s16le",
+                )
+
+                for chunk in response:
+                    if not self.is_running:
+                        break
+
+                    if isinstance(chunk, tuple):
+                        if len(chunk) > 1:
+                            sub_iterator = chunk[1]
+                            # Check if explicitly bytes (non-iterable in this context intended for iteration)
+                            if isinstance(sub_iterator, bytes):
+                                self._process_audio_bytes(sub_iterator)
+                            else:
+                                try:
+                                    for sub_chunk in sub_iterator:
+                                        if isinstance(sub_chunk, bytes):
+                                            self._process_audio_bytes(sub_chunk)
+                                        elif hasattr(sub_chunk, "content"):
+                                            self._process_audio_bytes(sub_chunk.content)
+                                        elif hasattr(sub_chunk, "data"):
+                                            self._process_audio_bytes(sub_chunk.data)
+                                except TypeError:
+                                    pass
+
+                    elif hasattr(chunk, "content"):
+                        audio_data = chunk.content
+                        if audio_data:
+                            self._process_audio_bytes(audio_data)
+
+                    elif isinstance(chunk, bytes):
+                        self._process_audio_bytes(chunk)
+
+            except Exception as e:
+                print(f"TTS Error: {e}")
+            finally:
+                self.text_queue.task_done()
+
+    def _process_audio_bytes(self, audio_data):
+        """Helper to strip headers and push to queue"""
+        # Strip WAV header if present (RIFF...WAVE)
+        if len(audio_data) >= 44 and audio_data[:4] == b"RIFF":
+            audio_data = audio_data[44:]
+        self.audio_queue.put(audio_data)
+
+    def _audio_player(self):
+        buffer = b""
+        while self.is_running:
+            try:
+                audio_data = self.audio_queue.get(timeout=0.5)
+            except queue.Empty:
+                continue
+
+            if audio_data is None:
+                self.playback_finished.set()
+                break
+
+            buffer += audio_data
+
+            if len(buffer) >= 2:
+                frame_count = len(buffer) // 2
+                bytes_to_play = frame_count * 2
+                play_chunk = buffer[:bytes_to_play]
+                buffer = buffer[bytes_to_play:]
+
+                try:
+                    self.stream.write(play_chunk)
+                except OSError:
+                    break

{intellema_vdk-0.1.0.dist-info → intellema_vdk-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: intellema-vdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: A Voice Development Kit for different Voice Agent Platforms
 Author: Intellema
 License: MIT License
@@ -37,6 +37,12 @@ Requires-Dist: boto3>=1.28.0
 Requires-Dist: twilio
 Requires-Dist: retell-sdk
 Requires-Dist: requests
+Requires-Dist: openai
+Requires-Dist: httpx
+Requires-Dist: pyaudio
+Requires-Dist: together
+Requires-Dist: langchain-openai
+Requires-Dist: langchain-core
 Dynamic: license-file
 
 # Intellema VDK
@@ -100,6 +106,73 @@ from intellema_vdk import start_outbound_call
 await start_outbound_call("livekit", phone_number="+1...")
 ```
 
+## Speech To Text (STT)
+
+The `STTManager` class provides an interface for transcribing audio files using OpenAI's Whisper model and optionally posting the transcribed text to a specified agent API.
+
+### Usage
+
+Here's how to use the `STTManager` to transcribe an audio file and post the result:
+Ensure to set OPENAI_API_KEY and AGENT_API_URL in your `.env` file.
+
+```python
+import asyncio
+from intellema_vdk import STTManager
+
+async def main():
+    # 1- Initialize the STTManager
+    stt_manager = STTManager()
+
+    try:
+        # 2- Transcribe an audio file and post the result to your agent API URL (if provided)
+        # Replace "path/to/your/audio.mp3" with the actual file path
+        transcript = await stt_manager.transcribe_and_post("path/to/your/audio.mp3")
+        print(f"Transcription: {transcript}")
+
+    except FileNotFoundError:
+        print("The audio file was not found.")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+    finally:
+        # 3- Clean up
+        await stt_manager.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+    
+## TTS Streaming 
+
+The `TTSStreamer` class provides low-latency text-to-speech streaming using Together AI's inference engine. It enables real-time voice synthesis from streaming LLM responses.
+
+### Running the Sample implementation
+
+We provide a ready-to-use sample that connects LangChain (OpenAI) with the TTS Streamer.
+
+1.  **Configure Keys**: Ensure `OPENAI_API_KEY` and `TOGETHER_API_KEY` are set in your `.env`.
+2.  **Run the script**:
+    ```bash
+    python sample_implementation.py
+    ```
+
+### Library Usage
+
+You can integrate the streamer into your own loops:
+
+```python
+from intellema_vdk import TTSStreamer
+
+# 1. Initialize per turn
+tts = TTSStreamer()
+
+# 2. Feed text chunks as they are generated
+for chunk in llm_response_stream:
+    tts.feed(chunk)
+
+# 3. Flush and clean up
+tts.flush()
+tts.close()
+```
 
 ## Configuration
 
@@ -115,6 +188,34 @@ TWILIO_AUTH_TOKEN=your-token
 TWILIO_PHONE_NUMBER=your-number
 RETELL_API_KEY=your-retell-key
 RETELL_AGENT_ID=your-agent-id
+TOGETHER_API_KEY=your-together-key
+OPENAI_API_KEY=your-openai-key
+AGENT_API_URL=https://your-agent-api.com/endpoint
 ```
 
+## Retell Setup
+
+**Important:** Before initiating calls with Retell, you must register your Twilio phone number with Retell. This binds your agent to the number and allows Retell to handle the call flow.
+
+You can register your number in two ways:
+
+1.  **Using the Helper Script:**
+    We provide an interactive script to guide you through the process:
+    ```bash
+    python import_phone_number.py
+    ```
+
+2.  **Programmatically:**
+    ```python
+    from intellema_vdk.retell_lib.retell_client import RetellManager
+    
+    manager = RetellManager()
+    # Optional: Pass termination_uri if you have a SIP trunk
+    manager.import_phone_number(nickname="My Twilio Number")
+    ```
+
+## Notes
+
+- **Retell `delete_room` Limitation**: The `delete_room` method for Retell relies on updating dynamic variables during the conversation loop. As a result, it **only works if the user speaks something** which triggers the agent to check the variable and terminate the call.
+
 

intellema_vdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+intellema_vdk/__init__.py,sha256=64pm2TLqhGG225JLddco1kSOpLaD3eGByWvMpaHUUX0,1231
+intellema_vdk/livekit_lib/__init__.py,sha256=9JsOBswDivM8tRw9EF1ql0wwFnHvwjcPWT-umqad98o,68
+intellema_vdk/livekit_lib/client.py,sha256=UxOuT9I-YPtHopx4dXoGKRAJvLXKFgUdtrAcHdR4a-Q,10687
+intellema_vdk/retell_lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+intellema_vdk/retell_lib/import_phone_number.py,sha256=pOt1k6De6-bt2xOPzMMR0nI4Ha6BzLjm19qenyy9RN8,3081
+intellema_vdk/retell_lib/retell_client.py,sha256=qT00NJWi2rJyLWswWTx5fGl5mwPdy6QurQt1Enac0rU,10793
+intellema_vdk/speech_lib/__init__.py,sha256=TXdyAAS6AfQfln_QlIvx_uXU-ksugXzC2N9hrjW1_MQ,73
+intellema_vdk/speech_lib/stt_client.py,sha256=YB8-mJUtQKhqEC4zhipJUb6Y8LqJx0Vv_c4iIxuUjJM,4054
+intellema_vdk/speech_lib/tts_streamer.py,sha256=qs2mzP0vKqv2eKvGJSCTee3mzeJGS9nji0Yy3Y-sOTc,6453
+intellema_vdk-0.2.0.dist-info/licenses/LICENSE,sha256=41qw3yuvY1SpTkwLebZTVYOKk9OIe1Kr6I1S6Y5mp8Y,1087
+intellema_vdk-0.2.0.dist-info/METADATA,sha256=j53oDXr8Xcq7nkP4v6bWeK62z0yR-Pa2yivGaCw-abc,7363
+intellema_vdk-0.2.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+intellema_vdk-0.2.0.dist-info/top_level.txt,sha256=nQ_0rJRkEthHH0bJYoPAVVgQiO6Uw6c_mHnfeROG14U,14
+intellema_vdk-0.2.0.dist-info/RECORD,,

{intellema_vdk-0.1.0.dist-info → intellema_vdk-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

intellema_vdk-0.1.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-intellema_vdk/__init__.py,sha256=L3hrqcxGVpd4xjXMdEXEO8-Rsg4MfJUR_iN3X0hbido,1224
-intellema_vdk/livekit_lib/__init__.py,sha256=9JsOBswDivM8tRw9EF1ql0wwFnHvwjcPWT-umqad98o,68
-intellema_vdk/livekit_lib/client.py,sha256=UxOuT9I-YPtHopx4dXoGKRAJvLXKFgUdtrAcHdR4a-Q,10687
-intellema_vdk/livekit_lib/__pycache__/__init__.cpython-312.pyc,sha256=-LfSHUwq29ExyfKYStSqyiEzVE--LhEkogP2TLI1xPA,224
-intellema_vdk/livekit_lib/__pycache__/client.cpython-312.pyc,sha256=6_zxzDpWZHmBNIuJeKOCWQlYe9XxAhW0npUlcX0Z9sc,14331
-intellema_vdk/retell_lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-intellema_vdk/retell_lib/retell_client.py,sha256=sc6EnDc7J4SEF515-YIre56Tg-KLXDRRzli7Jwf-bSo,8037
-intellema_vdk/retell_lib/__pycache__/__init__.cpython-312.pyc,sha256=raQGnf_MXBHnMWj5H8iXd3B7U53AfOEyXX2aPx9s1cA,147
-intellema_vdk/retell_lib/__pycache__/retell_client.cpython-312.pyc,sha256=eE6z7VLSDglUI5feZnK-qKlB-pOTmoAyDWsgEuraP-s,10060
-intellema_vdk-0.1.0.dist-info/licenses/LICENSE,sha256=41qw3yuvY1SpTkwLebZTVYOKk9OIe1Kr6I1S6Y5mp8Y,1087
-intellema_vdk-0.1.0.dist-info/METADATA,sha256=RqzJZRQZn35QgwEkQu9LZbCIDW7D6b6dSBFfFiLIcTk,4120
-intellema_vdk-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-intellema_vdk-0.1.0.dist-info/top_level.txt,sha256=nQ_0rJRkEthHH0bJYoPAVVgQiO6Uw6c_mHnfeROG14U,14
-intellema_vdk-0.1.0.dist-info/RECORD,,