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

pipecat/processors/transcript_processor.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Transcript processing utilities for conversation recording and analysis.
+
+This module provides processors that convert speech and text frames into structured
+transcript messages with timestamps, enabling conversation history tracking and analysis.
+"""
+
 from typing import List, Optional
 
 from loguru import logger
@@ -30,7 +36,11 @@ class BaseTranscriptProcessor(FrameProcessor):
     """
 
     def __init__(self, **kwargs):
-        """Initialize processor with empty message store."""
+        """Initialize processor with empty message store.
+
+        Args:
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._processed_messages: List[TranscriptionMessage] = []
         self._register_event_handler("on_transcript_update")
@@ -39,7 +49,7 @@ class BaseTranscriptProcessor(FrameProcessor):
         """Emit transcript updates for new messages.
 
         Args:
-            messages: New messages to emit in update
+            messages: New messages to emit in update.
         """
         if messages:
             self._processed_messages.extend(messages)
@@ -55,8 +65,8 @@ class UserTranscriptProcessor(BaseTranscriptProcessor):
         """Process TranscriptionFrames into user conversation messages.
 
         Args:
-            frame: Input frame to process
-            direction: Frame processing direction
+            frame: Input frame to process.
+            direction: Frame processing direction.
         """
         await super().process_frame(frame, direction)
 
@@ -74,17 +84,18 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor):
 
     This processor aggregates TTS text frames into complete utterances and emits them as
     transcript messages. Utterances are completed when:
+
     - The bot stops speaking (BotStoppedSpeakingFrame)
     - The bot is interrupted (StartInterruptionFrame)
     - The pipeline ends (EndFrame)
-
-    Attributes:
-        _current_text_parts: List of text fragments being aggregated for current utterance
-        _aggregation_start_time: Timestamp when the current utterance began
     """
 
     def __init__(self, **kwargs):
-        """Initialize processor with aggregation state."""
+        """Initialize processor with aggregation state.
+
+        Args:
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._current_text_parts: List[str] = []
         self._aggregation_start_time: Optional[str] = None
@@ -98,42 +109,44 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor):
         TTS services with different formatting patterns.
 
         Examples:
-            Fragments with embedded spacing (concatenated):
-                ```
+            Fragments with embedded spacing (concatenated)::
+
                 TTSTextFrame: ["Hello"]
                 TTSTextFrame: [" there"]  # Leading space
                 TTSTextFrame: ["!"]
                 TTSTextFrame: [" How"]    # Leading space
                 TTSTextFrame: ["'s"]
                 TTSTextFrame: [" it"]     # Leading space
-                ```
+
                 Result: "Hello there! How's it"
 
-            Fragments with trailing spaces (concatenated):
-                ```
+            Fragments with trailing spaces (concatenated)::
+
                 TTSTextFrame: ["Hel"]
                 TTSTextFrame: ["lo "]     # Trailing space
                 TTSTextFrame: ["to "]     # Trailing space
                 TTSTextFrame: ["you"]
-                ```
+
                 Result: "Hello to you"
 
-            Word-by-word fragments without spacing (joined with spaces):
-                ```
+            Word-by-word fragments without spacing (joined with spaces)::
+
                 TTSTextFrame: ["Hello"]
                 TTSTextFrame: ["there"]
                 TTSTextFrame: ["how"]
                 TTSTextFrame: ["are"]
                 TTSTextFrame: ["you"]
-                ```
+
                 Result: "Hello there how are you"
         """
         if self._current_text_parts and self._aggregation_start_time:
+            # Check specifically for space characters, previously isspace() was used
+            # but that includes all whitespace characters (e.g. \n), not just spaces.
             has_leading_spaces = any(
-                part and part[0].isspace() for part in self._current_text_parts[1:]
+                part and part[0] == " " for part in self._current_text_parts[1:]
             )
             has_trailing_spaces = any(
-                part and part[-1].isspace() for part in self._current_text_parts[:-1]
+                part and part[-1] == " " for part in self._current_text_parts[:-1]
             )
 
             # If there are embedded spaces in the fragments, use direct concatenation
@@ -169,6 +182,7 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor):
         """Process frames into assistant conversation messages.
 
         Handles different frame types:
+
         - TTSTextFrame: Aggregates text for current utterance
         - BotStoppedSpeakingFrame: Completes current utterance
         - StartInterruptionFrame: Completes current utterance due to interruption
@@ -176,8 +190,8 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor):
         - CancelFrame: Completes current utterance due to cancellation
 
         Args:
-            frame: Input frame to process
-            direction: Frame processing direction
+            frame: Input frame to process.
+            direction: Frame processing direction.
         """
         await super().process_frame(frame, direction)
 
@@ -211,8 +225,8 @@ class TranscriptProcessor:
     Provides unified access to user and assistant transcript processors
     with shared event handling.
 
-    Example:
-        ```python
+    Example::
+
         transcript = TranscriptProcessor()
 
         pipeline = Pipeline(
@@ -232,7 +246,6 @@ class TranscriptProcessor:
         @transcript.event_handler("on_transcript_update")
         async def handle_update(processor, frame):
             print(f"New messages: {frame.messages}")
-        ```
     """
 
     def __init__(self):
@@ -245,7 +258,10 @@ class TranscriptProcessor:
         """Get the user transcript processor.
 
         Args:
-            **kwargs: Arguments specific to UserTranscriptProcessor
+            **kwargs: Arguments specific to UserTranscriptProcessor.
+
+        Returns:
+            The user transcript processor instance.
         """
         if self._user_processor is None:
             self._user_processor = UserTranscriptProcessor(**kwargs)
@@ -262,7 +278,10 @@ class TranscriptProcessor:
         """Get the assistant transcript processor.
 
         Args:
-            **kwargs: Arguments specific to AssistantTranscriptProcessor
+            **kwargs: Arguments specific to AssistantTranscriptProcessor.
+
+        Returns:
+            The assistant transcript processor instance.
         """
         if self._assistant_processor is None:
             self._assistant_processor = AssistantTranscriptProcessor(**kwargs)
@@ -279,10 +298,10 @@ class TranscriptProcessor:
         """Register event handler for both processors.
 
         Args:
-            event_name: Name of event to handle
+            event_name: Name of event to handle.
 
         Returns:
-            Decorator function that registers handler with both processors
+            Decorator function that registers handler with both processors.
         """
 
         def decorator(handler):

pipecat/processors/user_idle_processor.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""User idle detection and timeout handling for Pipecat."""
+
 import asyncio
 import inspect
 from typing import Awaitable, Callable, Union
@@ -21,6 +23,9 @@ from pipecat.frames.frames import (
     InputDTMFFrame,
     StartUserIdleProcessorFrame,
     StopUserIdleProcessorFrame,
+    FunctionCallInProgressFrame,
+    FunctionCallResultFrame,
+    StartFrame,
     UserStartedSpeakingFrame,
     UserStoppedSpeakingFrame,
 )
@@ -30,19 +35,12 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 class UserIdleProcessor(FrameProcessor):
     """Monitors user inactivity and triggers callbacks after timeout periods.
 
-    Starts monitoring only after the first conversation activity (UserStartedSpeaking
-    or BotSpeaking).
+    This processor tracks user activity and triggers configurable callbacks when
+    users become idle. It starts monitoring only after the first conversation
+    activity and supports both basic and retry-based callback patterns.
 
-    Args:
-        callback: Function to call when user is idle. Can be either:
-            - Basic callback(processor) -> None
-            - Retry callback(processor, retry_count) -> bool
-              Return True to continue monitoring for idle events,
-              Return False to stop the idle monitoring task
-        timeout: Seconds to wait before considering user idle
-        **kwargs: Additional arguments passed to FrameProcessor
+    Example::
 
-    Example:
         # Retry callback:
         async def handle_idle(processor: "UserIdleProcessor", retry_count: int) -> bool:
             if retry_count < 3:
@@ -70,6 +68,16 @@ class UserIdleProcessor(FrameProcessor):
         timeout: float,
         **kwargs,
     ):
+        """Initialize the user idle processor.
+
+        Args:
+            callback: Function to call when user is idle. Can be either a basic
+                callback taking only the processor, or a retry callback taking
+                the processor and retry count. Retry callbacks should return
+                True to continue monitoring or False to stop.
+            timeout: Seconds to wait before considering user idle.
+            **kwargs: Additional arguments passed to FrameProcessor.
+        """
         super().__init__(**kwargs)
         self._callback = self._wrap_callback(callback)
         self._timeout = timeout
@@ -78,7 +86,6 @@ class UserIdleProcessor(FrameProcessor):
         self._conversation_started = False
         self._idle_task = None
         self._idle_event = asyncio.Event()
-        self._function_call_in_progress = False
 
     def _wrap_callback(
         self,
@@ -116,7 +123,11 @@ class UserIdleProcessor(FrameProcessor):
 
     @property
     def retry_count(self) -> int:
-        """Returns the current retry count."""
+        """Get the current retry count.
+
+        Returns:
+            The number of times the idle callback has been triggered.
+        """
         return self._retry_count
 
     async def _stop(self) -> None:
@@ -131,8 +142,8 @@ class UserIdleProcessor(FrameProcessor):
         """Processes incoming frames and manages idle monitoring state.
 
         Args:
-            frame: The frame to process
-            direction: Direction of the frame flow
+            frame: The frame to process.
+            direction: Direction of the frame flow.
         """
         await super().process_frame(frame, direction)
 
@@ -168,12 +179,11 @@ class UserIdleProcessor(FrameProcessor):
             elif isinstance(frame, InputDTMFFrame):
                 self._idle_event.set()
             elif isinstance(frame, FunctionCallInProgressFrame):
-                self._function_call_in_progress = True
-                self.logger.debug("Function call in progress")
+                # Function calls can take longer than the timeout, so we want to prevent idle callbacks
+                self._interrupted = True
                 self._idle_event.set()
-            elif isinstance(frame, (FunctionCallResultFrame, FunctionCallCancelFrame)):
-                self._function_call_in_progress = False
-                self.logger.debug("Got Function call result")
+            elif isinstance(frame, FunctionCallResultFrame):
+                self._interrupted = False
                 self._idle_event.set()
             elif isinstance(frame, StartUserIdleProcessorFrame):
                 if not self._idle_task:
@@ -200,7 +210,7 @@ class UserIdleProcessor(FrameProcessor):
             try:
                 await asyncio.wait_for(self._idle_event.wait(), timeout=self._timeout)
             except asyncio.TimeoutError:
-                if not self._interrupted and not self._function_call_in_progress:
+                if not self._interrupted:
                     self._retry_count += 1
                     should_continue = await self._callback(self, self._retry_count)
                     if not should_continue:

pipecat/runner/__init__.py

@@ -0,0 +1 @@
+"""Pipecat runner package for local and cloud bot execution."""

pipecat/runner/daily.py

@@ -0,0 +1,132 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Daily room and token configuration utilities.
+
+This module provides helper functions for creating and configuring Daily rooms
+and authentication tokens. It automatically creates temporary rooms for
+development or uses existing rooms specified via environment variables.
+
+Environment variables:
+
+- DAILY_API_KEY - Daily API key for room/token creation (required)
+- DAILY_SAMPLE_ROOM_URL (optional) - Existing room URL to use. If not provided,
+  a temporary room will be created automatically.
+
+Example::
+
+    import aiohttp
+    from pipecat.runner.daily import configure
+
+    async with aiohttp.ClientSession() as session:
+        room_url, token = await configure(session)
+        # Use room_url and token with DailyTransport
+"""
+
+import os
+import time
+import uuid
+from typing import Tuple
+
+import aiohttp
+
+from pipecat.transports.services.helpers.daily_rest import (
+    DailyRESTHelper,
+    DailyRoomParams,
+    DailyRoomProperties,
+)
+
+
+async def configure(aiohttp_session: aiohttp.ClientSession) -> Tuple[str, str]:
+    """Configure Daily room URL and token from environment variables.
+
+    This function will either:
+    1. Use an existing room URL from DAILY_SAMPLE_ROOM_URL environment variable
+    2. Create a new temporary room automatically if no URL is provided
+
+    Args:
+        aiohttp_session: HTTP session for making API requests.
+
+    Returns:
+        Tuple containing the room URL and authentication token.
+
+    Raises:
+        Exception: If DAILY_API_KEY is not provided in environment variables.
+    """
+    # Check for required API key
+    api_key = os.getenv("DAILY_API_KEY")
+    if not api_key:
+        raise Exception(
+            "DAILY_API_KEY environment variable is required. "
+            "Get your API key from https://dashboard.daily.co/developers"
+        )
+
+    # Check for existing room URL
+    existing_room_url = os.getenv("DAILY_SAMPLE_ROOM_URL")
+
+    daily_rest_helper = DailyRESTHelper(
+        daily_api_key=api_key,
+        daily_api_url=os.getenv("DAILY_API_URL", "https://api.daily.co/v1"),
+        aiohttp_session=aiohttp_session,
+    )
+
+    if existing_room_url:
+        # Use existing room
+        print(f"Using existing Daily room: {existing_room_url}")
+        room_url = existing_room_url
+    else:
+        # Create a new temporary room
+        room_name = f"pipecat-{uuid.uuid4().hex[:8]}"
+        print(f"Creating new Daily room: {room_name}")
+
+        # Calculate expiration time: current time + 2 hours
+        expiration_time = time.time() + (2 * 60 * 60)  # 2 hours from now
+
+        # Create room properties with absolute timestamp
+        room_properties = DailyRoomProperties(
+            exp=expiration_time,  # Absolute Unix timestamp
+            eject_at_room_exp=True,
+        )
+
+        # Create room parameters
+        room_params = DailyRoomParams(name=room_name, properties=room_properties)
+
+        room_response = await daily_rest_helper.create_room(room_params)
+        room_url = room_response.url
+        print(f"Created Daily room: {room_url}")
+
+    # Create a meeting token for the room with an expiration 2 hours in the future
+    expiry_time: float = 2 * 60 * 60
+    token = await daily_rest_helper.get_token(room_url, expiry_time)
+
+    return (room_url, token)
+
+
+# Keep this for backwards compatibility, but mark as deprecated
+async def configure_with_args(aiohttp_session: aiohttp.ClientSession, parser=None):
+    """Configure Daily room with command-line argument parsing.
+
+    .. deprecated:: 0.0.78
+        This function is deprecated. Use configure() instead which uses
+        environment variables only.
+
+    Args:
+        aiohttp_session: HTTP session for making API requests.
+        parser: Ignored. Kept for backwards compatibility.
+
+    Returns:
+        Tuple containing room URL, authentication token, and None (for args).
+    """
+    import warnings
+
+    warnings.warn(
+        "configure_with_args is deprecated. Use configure() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    room_url, token = await configure(aiohttp_session)
+    return (room_url, token, None)

pipecat/runner/livekit.py

@@ -0,0 +1,148 @@
+#
+# Copyright (c) 2024–2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""LiveKit room and token configuration utilities.
+
+This module provides helper functions for creating and configuring LiveKit
+rooms and authentication tokens. It handles JWT token generation with
+appropriate grants for both regular participants and AI agents.
+
+The module supports creating tokens for development and testing, with
+automatic agent detection for proper room permissions.
+
+Required environment variables:
+
+- LIVEKIT_API_KEY - LiveKit API key
+- LIVEKIT_API_SECRET - LiveKit API secret
+- LIVEKIT_URL - LiveKit server URL
+- LIVEKIT_ROOM_NAME - Room name to join
+
+Example::
+
+    from pipecat.runner.livekit import configure
+
+    url, token, room_name = await configure()
+    # Use with LiveKitTransport
+"""
+
+import argparse
+import os
+from typing import Optional
+
+from livekit import api
+from loguru import logger
+
+
+def generate_token(room_name: str, participant_name: str, api_key: str, api_secret: str) -> str:
+    """Generate a LiveKit access token for a participant.
+
+    Args:
+        room_name: Name of the LiveKit room.
+        participant_name: Name of the participant.
+        api_key: LiveKit API key.
+        api_secret: LiveKit API secret.
+
+    Returns:
+        JWT token string for room access.
+    """
+    token = api.AccessToken(api_key, api_secret)
+    token.with_identity(participant_name).with_name(participant_name).with_grants(
+        api.VideoGrants(
+            room_join=True,
+            room=room_name,
+        )
+    )
+
+    return token.to_jwt()
+
+
+def generate_token_with_agent(
+    room_name: str, participant_name: str, api_key: str, api_secret: str
+) -> str:
+    """Generate a LiveKit access token for an agent participant.
+
+    Args:
+        room_name: Name of the LiveKit room.
+        participant_name: Name of the participant.
+        api_key: LiveKit API key.
+        api_secret: LiveKit API secret.
+
+    Returns:
+        JWT token string for agent room access.
+    """
+    token = api.AccessToken(api_key, api_secret)
+    token.with_identity(participant_name).with_name(participant_name).with_grants(
+        api.VideoGrants(
+            room_join=True,
+            room=room_name,
+            agent=True,  # This makes LiveKit client know agent has joined
+        )
+    )
+
+    return token.to_jwt()
+
+
+async def configure():
+    """Configure LiveKit room URL and token from arguments or environment.
+
+    Returns:
+        Tuple containing the server URL, authentication token, and room name.
+
+    Raises:
+        Exception: If required LiveKit configuration is not provided.
+    """
+    (url, token, room_name, _) = await configure_with_args()
+    return (url, token, room_name)
+
+
+async def configure_with_args(parser: Optional[argparse.ArgumentParser] = None):
+    """Configure LiveKit room with command-line argument parsing.
+
+    Args:
+        parser: Optional argument parser. If None, creates a default one.
+
+    Returns:
+        Tuple containing server URL, authentication token, room name, and parsed arguments.
+
+    Raises:
+        Exception: If required LiveKit configuration is not provided via arguments or environment.
+    """
+    if not parser:
+        parser = argparse.ArgumentParser(description="LiveKit AI SDK Bot Sample")
+    parser.add_argument(
+        "-r", "--room", type=str, required=False, help="Name of the LiveKit room to join"
+    )
+    parser.add_argument("-u", "--url", type=str, required=False, help="URL of the LiveKit server")
+
+    args, unknown = parser.parse_known_args()
+
+    room_name = args.room or os.getenv("LIVEKIT_ROOM_NAME")
+    url = args.url or os.getenv("LIVEKIT_URL")
+    api_key = os.getenv("LIVEKIT_API_KEY")
+    api_secret = os.getenv("LIVEKIT_API_SECRET")
+
+    if not room_name:
+        raise Exception(
+            "No LiveKit room specified. Use the -r/--room option from the command line, or set LIVEKIT_ROOM_NAME in your environment."
+        )
+
+    if not url:
+        raise Exception(
+            "No LiveKit server URL specified. Use the -u/--url option from the command line, or set LIVEKIT_URL in your environment."
+        )
+
+    if not api_key or not api_secret:
+        raise Exception(
+            "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set in environment variables."
+        )
+
+    token = generate_token_with_agent(room_name, "Pipecat Agent", api_key, api_secret)
+
+    # Generate user token for testing/debugging
+    user_token = generate_token(room_name, "User", api_key, api_secret)
+    logger.info(f"User token: {user_token}")
+
+    return (url, token, room_name, args)