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

pipecat/utils/tracing/service_decorators.py

@@ -41,9 +41,15 @@ T = TypeVar("T")
 R = TypeVar("R")
 
 
-# Internal helper functions
 def _noop_decorator(func):
-    """No-op fallback decorator when tracing is unavailable."""
+    """No-op fallback decorator when tracing is unavailable.
+
+    Args:
+        func: The function to pass through unchanged.
+
+    Returns:
+        The original function unchanged.
+    """
     return func
 
 
@@ -53,10 +59,10 @@ def _get_parent_service_context(self):
     This looks for the service span that was created when the service was initialized.
 
     Args:
-        self: The service instance
+        self: The service instance.
 
     Returns:
-        Context or None: The parent service context, or None if unavailable
+        The parent service context, or None if unavailable.
     """
     if not is_tracing_available():
         return None
@@ -73,8 +79,8 @@ def _add_token_usage_to_span(span, token_usage):
     """Add token usage metrics to a span (internal use only).
 
     Args:
-        span: The span to add token metrics to
-        token_usage: Dictionary or object containing token usage information
+        span: The span to add token metrics to.
+        token_usage: Dictionary or object containing token usage information.
     """
     if not is_tracing_available() or not token_usage:
         return
@@ -93,9 +99,10 @@ def _add_token_usage_to_span(span, token_usage):
 
 
 def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable:
-    """Traces TTS service methods with TTS-specific attributes.
+    """Trace TTS service methods with TTS-specific attributes.
 
     Automatically captures and records:
+
     - Service name and model information
     - Voice ID and settings
     - Character count and text content
@@ -118,8 +125,17 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -
 
         @contextlib.asynccontextmanager
         async def tracing_context(self, text):
-            """Async context manager for TTS tracing."""
-            if not is_tracing_available():
+            """Async context manager for TTS tracing.
+
+            Args:
+                self: The TTS service instance.
+                text: The text being synthesized.
+
+            Yields:
+                The active span for the TTS operation.
+            """
+            # Check if tracing is enabled for this service instance
+            if not getattr(self, "_tracing_enabled", False):
                 yield None
                 return
 
@@ -163,7 +179,8 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -
             @functools.wraps(f)
             async def gen_wrapper(self, text, *args, **kwargs):
                 try:
-                    if not is_tracing_available():
+                    # Check if tracing is enabled for this service instance
+                    if not getattr(self, "_tracing_enabled", False):
                         async for item in f(self, text, *args, **kwargs):
                             yield item
                         return
@@ -183,7 +200,8 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -
             @functools.wraps(f)
             async def wrapper(self, text, *args, **kwargs):
                 try:
-                    if not is_tracing_available():
+                    # Check if tracing is enabled for this service instance
+                    if not getattr(self, "_tracing_enabled", False):
                         return await f(self, text, *args, **kwargs)
 
                     async with tracing_context(self, text):
@@ -201,9 +219,10 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -
 
 
 def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable:
-    """Traces STT service methods with transcription attributes.
+    """Trace STT service methods with transcription attributes.
 
     Automatically captures and records:
+
     - Service name and model information
     - Transcription text and final status
     - Language information
@@ -223,7 +242,8 @@ def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) -
         @functools.wraps(f)
         async def wrapper(self, transcript, is_final, language=None):
             try:
-                if not is_tracing_available():
+                # Check if tracing is enabled for this service instance
+                if not getattr(self, "_tracing_enabled", False):
                     return await f(self, transcript, is_final, language)
 
                 service_class_name = self.__class__.__name__
@@ -254,6 +274,7 @@ def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) -
                             transcript=transcript,
                             is_final=is_final,
                             language=str(language) if language else None,
+                            user_id=getattr(self, "_user_id", None),
                             vad_enabled=getattr(self, "vad_enabled", False),
                             settings=settings,
                             ttfb=ttfb,
@@ -278,9 +299,10 @@ def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) -
 
 
 def traced_llm(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable:
-    """Traces LLM service methods with LLM-specific attributes.
+    """Trace LLM service methods with LLM-specific attributes.
 
     Automatically captures and records:
+
     - Service name and model information
     - Context content and messages
     - Tool configurations
@@ -302,7 +324,8 @@ def traced_llm(func: Optional[Callable] = None, *, name: Optional[str] = None) -
         @functools.wraps(f)
         async def wrapper(self, context, *args, **kwargs):
             try:
-                if not is_tracing_available():
+                # Check if tracing is enabled for this service instance
+                if not getattr(self, "_tracing_enabled", False):
                     return await f(self, context, *args, **kwargs)
 
                 service_class_name = self.__class__.__name__
@@ -482,16 +505,17 @@ def traced_llm(func: Optional[Callable] = None, *, name: Optional[str] = None) -
 
 
 def traced_gemini_live(operation: str) -> Callable:
-    """Traces Gemini Live service methods with operation-specific attributes.
+    """Trace Gemini Live service methods with operation-specific attributes.
 
     This decorator automatically captures relevant information based on the operation type:
+
     - llm_setup: Configuration, tools definitions, and system instructions
     - llm_tool_call: Function call information
     - llm_tool_result: Function execution results
     - llm_response: Complete LLM response with usage and output
 
     Args:
-        operation: The operation name (matches the event type being handled)
+        operation: The operation name (matches the event type being handled).
 
     Returns:
         Wrapped method with Gemini Live specific tracing.
@@ -503,7 +527,8 @@ def traced_gemini_live(operation: str) -> Callable:
         @functools.wraps(func)
         async def wrapper(self, *args, **kwargs):
             try:
-                if not is_tracing_available():
+                # Check if tracing is enabled for this service instance
+                if not getattr(self, "_tracing_enabled", False):
                     return await func(self, *args, **kwargs)
 
                 service_class_name = self.__class__.__name__
@@ -786,15 +811,16 @@ def traced_gemini_live(operation: str) -> Callable:
 
 
 def traced_openai_realtime(operation: str) -> Callable:
-    """Traces OpenAI Realtime service methods with operation-specific attributes.
+    """Trace OpenAI Realtime service methods with operation-specific attributes.
 
     This decorator automatically captures relevant information based on the operation type:
+
     - llm_setup: Session configuration and tools
     - llm_request: Context and input messages
     - llm_response: Usage metadata, output, and function calls
 
     Args:
-        operation: The operation name (matches the event type being handled)
+        operation: The operation name (matches the event type being handled).
 
     Returns:
         Wrapped method with OpenAI Realtime specific tracing.
@@ -806,7 +832,8 @@ def traced_openai_realtime(operation: str) -> Callable:
         @functools.wraps(func)
         async def wrapper(self, *args, **kwargs):
             try:
-                if not is_tracing_available():
+                # Check if tracing is enabled for this service instance
+                if not getattr(self, "_tracing_enabled", False):
                     return await func(self, *args, **kwargs)
 
                 service_class_name = self.__class__.__name__

pipecat/utils/tracing/setup.py

@@ -4,7 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-"""Core OpenTelemetry tracing utilities and setup for Pipecat."""
+"""Core OpenTelemetry tracing utilities and setup for Pipecat.
+
+This module provides functions to check availability and configure OpenTelemetry
+tracing for Pipecat applications. It handles the optional nature of OpenTelemetry
+dependencies and provides a safe setup process.
+"""
 
 import os
 
@@ -21,10 +26,10 @@ except ImportError:
 
 
 def is_tracing_available() -> bool:
-    """Returns True if OpenTelemetry tracing is available and configured.
+    """Check if OpenTelemetry tracing is available and configured.
 
     Returns:
-        bool: True if tracing is available, False otherwise.
+        True if tracing is available, False otherwise.
     """
     return OPENTELEMETRY_AVAILABLE
 
@@ -37,15 +42,16 @@ def setup_tracing(
     """Set up OpenTelemetry tracing with a user-provided exporter.
 
     Args:
-        service_name: The name of the service for traces
+        service_name: The name of the service for traces.
         exporter: A pre-configured OpenTelemetry span exporter instance.
                   If None, only console export will be available if enabled.
-        console_export: Whether to also export traces to console (useful for debugging)
+        console_export: Whether to also export traces to console (useful for debugging).
 
     Returns:
-        bool: True if setup was successful, False otherwise
+        True if setup was successful, False otherwise.
+
+    Example::
 
-    Example:
         # With OTLP exporter
         from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
 

pipecat/utils/tracing/turn_context_provider.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Turn context provider for OpenTelemetry tracing in Pipecat.
+
+This module provides a singleton context provider that manages the current
+turn's tracing context, allowing services to create child spans that are
+properly associated with the conversation turn.
+"""
+
 from typing import TYPE_CHECKING, Optional
 
 # Import types for type checking only
@@ -30,7 +37,11 @@ class TurnContextProvider:
 
     @classmethod
     def get_instance(cls):
-        """Get the singleton instance."""
+        """Get the singleton instance.
+
+        Returns:
+            The singleton TurnContextProvider instance.
+        """
         if cls._instance is None:
             cls._instance = TurnContextProvider()
         return cls._instance
@@ -60,7 +71,6 @@ class TurnContextProvider:
         return self._current_turn_context
 
 
-# Create a simple helper function to get the current turn context
 def get_current_turn_context() -> Optional["Context"]:
     """Get the OpenTelemetry context for the current turn.
 

pipecat/utils/tracing/turn_trace_observer.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Turn trace observer for OpenTelemetry tracing in Pipecat.
+
+This module provides an observer that creates trace spans for each conversation
+turn, integrating with the turn tracking system to provide hierarchical tracing
+of conversation flows.
+"""
+
 from typing import TYPE_CHECKING, Dict, Optional
 
 from loguru import logger
@@ -41,6 +48,14 @@ class TurnTraceObserver(BaseObserver):
         additional_span_attributes: Optional[dict] = None,
         **kwargs,
     ):
+        """Initialize the turn trace observer.
+
+        Args:
+            turn_tracker: The turn tracking observer to monitor.
+            conversation_id: Optional conversation ID for grouping turns.
+            additional_span_attributes: Additional attributes to add to spans.
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._turn_tracker = turn_tracker
         self._current_span: Optional["Span"] = None
@@ -68,6 +83,9 @@ class TurnTraceObserver(BaseObserver):
 
         This observer doesn't need to process individual frames as it
         relies on turn start/end events from the turn tracker.
+
+        Args:
+            data: The frame push event data.
         """
         pass
 
@@ -198,6 +216,9 @@ class TurnTraceObserver(BaseObserver):
         """Get the span context for the current turn.
 
         This can be used by services to create child spans.
+
+        Returns:
+            The current turn's span context or None if not available.
         """
         if not is_tracing_available() or not self._current_span:
             return None
@@ -208,6 +229,12 @@ class TurnTraceObserver(BaseObserver):
         """Get the span context for a specific turn.
 
         This can be used by services to create child spans.
+
+        Args:
+            turn_number: The turn number to get context for.
+
+        Returns:
+            The specified turn's span context or None if not available.
         """
         if not is_tracing_available():
             return None

pipecat/utils/utils.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Utility functions for object identification and counting.
+
+This module provides thread-safe utilities for generating unique identifiers
+and maintaining per-class instance counts across the Pipecat framework.
+"""
+
 import collections
 import itertools
 import threading
@@ -17,27 +23,21 @@ _ID_LOCK = threading.Lock()
 def obj_id() -> int:
     """Generate a unique id for an object.
 
-    >>> obj_id()
-    0
-    >>> obj_id()
-    1
-    >>> obj_id()
-    2
+    Returns:
+        A unique integer identifier that increments globally across all objects.
     """
     with _ID_LOCK:
         return next(_ID)
 
 
 def obj_count(obj) -> int:
-    """Generate a unique id for an object.
+    """Generate a unique count for an object based on its class.
 
-    >>> obj_count(object())
-    0
-    >>> obj_count(object())
-    1
-    >>> new_type = type('NewType', (object,), {})
-    >>> obj_count(new_type())
-    0
+    Args:
+        obj: The object instance to count.
+
+    Returns:
+        A unique integer count that increments per class type.
     """
     with _COUNTS_LOCK:
         return next(_COUNTS[obj.__class__.__name__])