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

pipecat/utils/text/simple_text_aggregator.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Simple text aggregator for basic sentence-boundary text processing.
+
+This module provides a straightforward text aggregator that accumulates text
+until it finds an end-of-sentence marker, making it suitable for basic TTS
+text processing scenarios.
+"""
+
 from typing import Optional
 
 from pipecat.utils.string import match_endofsentence
@@ -11,19 +18,43 @@ from pipecat.utils.text.base_text_aggregator import BaseTextAggregator
 
 
 class SimpleTextAggregator(BaseTextAggregator):
-    """This is a simple text aggregator. It aggregates text until an end of
-    sentence is found.
+    """Simple text aggregator that accumulates text until sentence boundaries.
 
+    This aggregator provides basic functionality for accumulating text tokens
+    and releasing them when an end-of-sentence marker is detected. It's the
+    most straightforward implementation of text aggregation for TTS processing.
     """
 
     def __init__(self):
+        """Initialize the simple text aggregator.
+
+        Creates an empty text buffer ready to begin accumulating text tokens.
+        """
         self._text = ""
 
     @property
     def text(self) -> str:
+        """Get the currently aggregated text.
+
+        Returns:
+            The text that has been accumulated in the buffer.
+        """
         return self._text
 
     async def aggregate(self, text: str) -> Optional[str]:
+        """Aggregate text and return completed sentences.
+
+        Adds the new text to the buffer and checks for end-of-sentence markers.
+        When a sentence boundary is found, returns the completed sentence and
+        removes it from the buffer.
+
+        Args:
+            text: New text to add to the aggregation buffer.
+
+        Returns:
+            A complete sentence if an end-of-sentence marker is found,
+            or None if more text is needed to complete a sentence.
+        """
         result: Optional[str] = None
 
         self._text += text
@@ -36,7 +67,17 @@ class SimpleTextAggregator(BaseTextAggregator):
         return result
 
     async def handle_interruption(self):
+        """Handle interruptions by clearing the text buffer.
+
+        Called when an interruption occurs in the processing pipeline,
+        discarding any partially accumulated text.
+        """
         self._text = ""
 
     async def reset(self):
+        """Clear the internally aggregated text.
+
+        Resets the aggregator to its initial empty state, discarding
+        any accumulated text content.
+        """
         self._text = ""

pipecat/utils/text/skip_tags_aggregator.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Skip tags aggregator for preventing sentence boundaries within tagged content.
+
+This module provides a text aggregator that prevents end-of-sentence matching
+between specified start/end tag pairs, ensuring that tagged content is processed
+as a unit regardless of internal punctuation.
+"""
+
 from typing import Optional, Sequence
 
 from pipecat.utils.string import StartEndTags, match_endofsentence, parse_start_end_tags
@@ -17,17 +24,18 @@ class SkipTagsAggregator(BaseTextAggregator):
     tag. If a start tag is found the aggregator will keep aggregating text
     unconditionally until the corresponding end tag is found. It's particularly
     useful for processing content with custom delimiters that should prevent
-    text from being considered for end of sentence matching..
+    text from being considered for end of sentence matching.
 
     The aggregator ensures that tags spanning multiple text chunks are correctly
-    identified.
-
+    identified and that content within tags is never split at sentence boundaries.
     """
 
     def __init__(self, tags: Sequence[StartEndTags]):
-        """Initialize the pattern pair aggregator.
+        """Initialize the skip tags aggregator.
 
-        Creates an empty aggregator with no patterns or handlers registered.
+        Args:
+            tags: Sequence of StartEndTags objects defining the tag pairs
+                  that should prevent sentence boundary detection.
         """
         self._text = ""
         self._tags = tags
@@ -39,24 +47,24 @@ class SkipTagsAggregator(BaseTextAggregator):
         """Get the currently buffered text.
 
         Returns:
-            The current text buffer content.
+            The current text buffer content that hasn't been processed yet.
         """
         return self._text
 
     async def aggregate(self, text: str) -> Optional[str]:
-        """Aggregate text and process pattern pairs.
+        """Aggregate text while respecting tag boundaries.
 
-        This method adds the new text to the buffer, processes any complete pattern
-        pairs, and returns processed text up to sentence boundaries if possible.
-        If there are incomplete patterns (start without matching end), it will
-        continue buffering text.
+        This method adds the new text to the buffer, processes any complete
+        pattern pairs, and returns processed text up to sentence boundaries if
+        possible. If there are incomplete patterns (start without matching
+        end), it will continue buffering text.
 
         Args:
             text: New text to add to the buffer.
 
         Returns:
-            Processed text up to a sentence boundary, or None if more
-            text is needed to form a complete sentence or pattern.
+            Processed text up to a sentence boundary (when not within tags),
+            or None if more text is needed to complete a sentence or close tags.
         """
         # Add new text to buffer
         self._text += text

pipecat/utils/time.py

@@ -4,22 +4,58 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Time utilities for the Pipecat framework.
+
+This module provides utility functions for time handling including
+ISO8601 formatting, nanosecond conversions, and human-readable
+time string formatting.
+"""
+
 import datetime
 
 
 def time_now_iso8601() -> str:
+    """Get the current UTC time as an ISO8601 formatted string.
+
+    Returns:
+        The current UTC time in ISO8601 format with millisecond precision.
+    """
     return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="milliseconds")
 
 
 def seconds_to_nanoseconds(seconds: float) -> int:
+    """Convert seconds to nanoseconds.
+
+    Args:
+        seconds: The number of seconds to convert.
+
+    Returns:
+        The equivalent number of nanoseconds as an integer.
+    """
     return int(seconds * 1_000_000_000)
 
 
 def nanoseconds_to_seconds(nanoseconds: int) -> float:
+    """Convert nanoseconds to seconds.
+
+    Args:
+        nanoseconds: The number of nanoseconds to convert.
+
+    Returns:
+        The equivalent number of seconds as a float.
+    """
     return nanoseconds / 1_000_000_000
 
 
 def nanoseconds_to_str(nanoseconds: int) -> str:
+    """Convert nanoseconds to a human-readable time string.
+
+    Args:
+        nanoseconds: The number of nanoseconds to convert.
+
+    Returns:
+        A formatted time string in "H:MM:SS.microseconds" format.
+    """
     total_seconds = nanoseconds_to_seconds(nanoseconds)
     hours = int(total_seconds // 3600)
     minutes = int((total_seconds % 3600) // 60)

pipecat/utils/tracing/class_decorators.py

@@ -33,7 +33,7 @@ C = TypeVar("C", bound=type)
 class AttachmentStrategy(enum.Enum):
     """Controls how spans are attached to the trace hierarchy.
 
-    Attributes:
+    Parameters:
         CHILD: Attached to class span if no parent, otherwise to parent.
         LINK: Attached to class span with link to parent.
         NONE: Always attached to class span regardless of context.
@@ -71,10 +71,10 @@ class Traceable:
 
     @property
     def meter(self):
-        """Returns the OpenTelemetry meter instance.
+        """Get the OpenTelemetry meter instance.
 
         Returns:
-            Meter: The OpenTelemetry meter instance for this object.
+            The OpenTelemetry meter instance for this object.
         """
         return self._meter
 
@@ -83,7 +83,17 @@ class Traceable:
 def __traced_context_manager(
     self: Traceable, func: Callable, name: str | None, attachment_strategy: AttachmentStrategy
 ):
-    """Internal context manager for the traced decorator."""
+    """Internal context manager for the traced decorator.
+
+    Args:
+        self: The Traceable instance.
+        func: The function being traced.
+        name: Custom span name or None to use function name.
+        attachment_strategy: How to attach this span to the trace hierarchy.
+
+    Raises:
+        RuntimeError: If used in a class not inheriting from Traceable.
+    """
     if not isinstance(self, Traceable):
         raise RuntimeError(
             "@traced annotation can only be used in classes inheriting from Traceable"
@@ -124,7 +134,16 @@ def __traced_context_manager(
 
 
 def __traced_decorator(func, name, attachment_strategy: AttachmentStrategy):
-    """Implementation of the traced decorator."""
+    """Implementation of the traced decorator.
+
+    Args:
+        func: The function to trace.
+        name: Custom span name.
+        attachment_strategy: How to attach this span.
+
+    Returns:
+        The wrapped function with tracing capabilities.
+    """
 
     @functools.wraps(func)
     async def coroutine_wrapper(self: Traceable, *args, **kwargs):
@@ -163,7 +182,7 @@ def traced(
     name: Optional[str] = None,
     attachment_strategy: AttachmentStrategy = AttachmentStrategy.CHILD,
 ) -> Callable:
-    """Adds tracing to an async function in a Traceable class.
+    """Add tracing to an async function in a Traceable class.
 
     Args:
         func: The async function to trace.
@@ -193,7 +212,7 @@ def traced(
 
 
 def traceable(cls: C) -> C:
-    """Makes a class traceable for OpenTelemetry.
+    """Make a class traceable for OpenTelemetry.
 
     Creates a new class that inherits from both the original class
     and Traceable, enabling tracing for class methods.
@@ -210,6 +229,12 @@ def traceable(cls: C) -> C:
     @functools.wraps(cls, updated=())
     class TracedClass(cls, Traceable):
         def __init__(self, *args, **kwargs):
+            """Initialize the traced class instance.
+
+            Args:
+                *args: Positional arguments passed to parent classes.
+                **kwargs: Keyword arguments passed to parent classes.
+            """
             cls.__init__(self, *args, **kwargs)
             if hasattr(self, "name"):
                 Traceable.__init__(self, self.name)

pipecat/utils/tracing/conversation_context_provider.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Conversation context provider for OpenTelemetry tracing in Pipecat.
+
+This module provides a singleton context provider that manages the current
+conversation's tracing context, allowing services to create child spans
+that are properly associated with the conversation.
+"""
+
 import uuid
 from typing import TYPE_CHECKING, Optional
 
@@ -32,7 +39,11 @@ class ConversationContextProvider:
 
     @classmethod
     def get_instance(cls):
-        """Get the singleton instance."""
+        """Get the singleton instance.
+
+        Returns:
+            The singleton ConversationContextProvider instance.
+        """
         if cls._instance is None:
             cls._instance = ConversationContextProvider()
         return cls._instance
@@ -83,7 +94,6 @@ class ConversationContextProvider:
         return str(uuid.uuid4())
 
 
-# Create a simple helper function to get the current conversation context
 def get_current_conversation_context() -> Optional["Context"]:
     """Get the OpenTelemetry context for the current conversation.
 

pipecat/utils/tracing/service_attributes.py

@@ -4,7 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-"""Functions for adding attributes to OpenTelemetry spans."""
+"""Functions for adding attributes to OpenTelemetry spans.
+
+This module provides specialized functions for adding service-specific
+attributes to OpenTelemetry spans, following standard semantic conventions
+where applicable and Pipecat-specific conventions for additional context.
+"""
 
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
@@ -26,6 +31,12 @@ def _get_gen_ai_system_from_service_name(service_name: str) -> str:
 
     Uses standard OTel names where possible, with special case mappings for
     service names that don't follow the pattern.
+
+    Args:
+        service_name: The service class name to extract system name from.
+
+    Returns:
+        The standardized gen_ai.system value.
     """
     SPECIAL_CASE_MAPPINGS = {
         # AWS
@@ -66,16 +77,16 @@ def add_tts_span_attributes(
     """Add TTS-specific attributes to a span.
 
     Args:
-        span: The span to add attributes to
-        service_name: Name of the TTS service (e.g., "cartesia")
-        model: Model name/identifier
-        voice_id: Voice identifier
-        text: The text being synthesized
-        settings: Service configuration settings
-        character_count: Number of characters in the text
-        operation_name: Name of the operation (default: "tts")
-        ttfb: Time to first byte in seconds
-        **kwargs: Additional attributes to add
+        span: The span to add attributes to.
+        service_name: Name of the TTS service (e.g., "cartesia").
+        model: Model name/identifier.
+        voice_id: Voice identifier.
+        text: The text being synthesized.
+        settings: Service configuration settings.
+        character_count: Number of characters in the text.
+        operation_name: Name of the operation (default: "tts").
+        ttfb: Time to first byte in seconds.
+        **kwargs: Additional attributes to add.
     """
     # Add standard attributes
     span.set_attribute("gen_ai.system", service_name.replace("TTSService", "").lower())
@@ -114,6 +125,7 @@ def add_stt_span_attributes(
     transcript: Optional[str] = None,
     is_final: Optional[bool] = None,
     language: Optional[str] = None,
+    user_id: Optional[str] = None,
     settings: Optional[Dict[str, Any]] = None,
     vad_enabled: bool = False,
     ttfb: Optional[float] = None,
@@ -122,17 +134,18 @@ def add_stt_span_attributes(
     """Add STT-specific attributes to a span.
 
     Args:
-        span: The span to add attributes to
-        service_name: Name of the STT service (e.g., "deepgram")
-        model: Model name/identifier
-        operation_name: Name of the operation (default: "stt")
-        transcript: The transcribed text
-        is_final: Whether this is a final transcript
-        language: Detected or configured language
-        settings: Service configuration settings
-        vad_enabled: Whether voice activity detection is enabled
-        ttfb: Time to first byte in seconds
-        **kwargs: Additional attributes to add
+        span: The span to add attributes to.
+        service_name: Name of the STT service (e.g., "deepgram").
+        model: Model name/identifier.
+        operation_name: Name of the operation (default: "stt").
+        transcript: The transcribed text.
+        is_final: Whether this is a final transcript.
+        language: Detected or configured language.
+        user_id: User ID associated with the audio being transcribed.
+        settings: Service configuration settings.
+        vad_enabled: Whether voice activity detection is enabled.
+        ttfb: Time to first byte in seconds.
+        **kwargs: Additional attributes to add.
     """
     # Add standard attributes
     span.set_attribute("gen_ai.system", service_name.replace("STTService", "").lower())
@@ -150,6 +163,9 @@ def add_stt_span_attributes(
     if language:
         span.set_attribute("language", language)
 
+    if user_id:
+        span.set_attribute("user_id", user_id)
+
     if ttfb is not None:
         span.set_attribute("metrics.ttfb", ttfb)
 
@@ -184,20 +200,20 @@ def add_llm_span_attributes(
     """Add LLM-specific attributes to a span.
 
     Args:
-        span: The span to add attributes to
-        service_name: Name of the LLM service (e.g., "openai")
-        model: Model name/identifier
-        stream: Whether streaming is enabled
-        messages: JSON-serialized messages
-        output: Aggregated output text from the LLM
-        tools: JSON-serialized tools configuration
-        tool_count: Number of tools available
-        tool_choice: Tool selection configuration
-        system: System message
-        parameters: Service parameters
-        extra_parameters: Additional parameters
-        ttfb: Time to first byte in seconds
-        **kwargs: Additional attributes to add
+        span: The span to add attributes to.
+        service_name: Name of the LLM service (e.g., "openai").
+        model: Model name/identifier.
+        stream: Whether streaming is enabled.
+        messages: JSON-serialized messages.
+        output: Aggregated output text from the LLM.
+        tools: JSON-serialized tools configuration.
+        tool_count: Number of tools available.
+        tool_choice: Tool selection configuration.
+        system: System message.
+        parameters: Service parameters.
+        extra_parameters: Additional parameters.
+        ttfb: Time to first byte in seconds.
+        **kwargs: Additional attributes to add.
     """
     # Add standard attributes
     span.set_attribute("gen_ai.system", _get_gen_ai_system_from_service_name(service_name))
@@ -278,21 +294,21 @@ def add_gemini_live_span_attributes(
     """Add Gemini Live specific attributes to a span.
 
     Args:
-        span: The span to add attributes to
-        service_name: Name of the service
-        model: Model name/identifier
-        operation_name: Name of the operation (setup, model_turn, tool_call, etc.)
-        voice_id: Voice identifier used for output
-        language: Language code for the session
-        modalities: Supported modalities (e.g., "AUDIO", "TEXT")
-        settings: Service configuration settings
-        tools: Available tools/functions list
-        tools_serialized: JSON-serialized tools for detailed inspection
-        transcript: Transcription text
-        is_input: Whether transcript is input (True) or output (False)
-        text_output: Text output from model
-        audio_data_size: Size of audio data in bytes
-        **kwargs: Additional attributes to add
+        span: The span to add attributes to.
+        service_name: Name of the service.
+        model: Model name/identifier.
+        operation_name: Name of the operation (setup, model_turn, tool_call, etc.).
+        voice_id: Voice identifier used for output.
+        language: Language code for the session.
+        modalities: Supported modalities (e.g., "AUDIO", "TEXT").
+        settings: Service configuration settings.
+        tools: Available tools/functions list.
+        tools_serialized: JSON-serialized tools for detailed inspection.
+        transcript: Transcription text.
+        is_input: Whether transcript is input (True) or output (False).
+        text_output: Text output from model.
+        audio_data_size: Size of audio data in bytes.
+        **kwargs: Additional attributes to add.
     """
     # Add standard attributes
     span.set_attribute("gen_ai.system", "gcp.gemini")
@@ -381,19 +397,19 @@ def add_openai_realtime_span_attributes(
     """Add OpenAI Realtime specific attributes to a span.
 
     Args:
-        span: The span to add attributes to
-        service_name: Name of the service
-        model: Model name/identifier
-        operation_name: Name of the operation (setup, transcription, response, etc.)
-        session_properties: Session configuration properties
-        transcript: Transcription text
-        is_input: Whether transcript is input (True) or output (False)
-        context_messages: JSON-serialized context messages
-        function_calls: Function calls being made
-        tools: Available tools/functions list
-        tools_serialized: JSON-serialized tools for detailed inspection
-        audio_data_size: Size of audio data in bytes
-        **kwargs: Additional attributes to add
+        span: The span to add attributes to.
+        service_name: Name of the service.
+        model: Model name/identifier.
+        operation_name: Name of the operation (setup, transcription, response, etc.).
+        session_properties: Session configuration properties.
+        transcript: Transcription text.
+        is_input: Whether transcript is input (True) or output (False).
+        context_messages: JSON-serialized context messages.
+        function_calls: Function calls being made.
+        tools: Available tools/functions list.
+        tools_serialized: JSON-serialized tools for detailed inspection.
+        audio_data_size: Size of audio data in bytes.
+        **kwargs: Additional attributes to add.
     """
     # Add standard attributes
     span.set_attribute("gen_ai.system", "openai")