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

pipecat/adapters/services/open_ai_realtime_adapter.py

@@ -3,6 +3,9 @@
 #
 # SPDX-License-Identifier: BSD 2-Clause License
 #
+
+"""OpenAI Realtime LLM adapter for Pipecat."""
+
 from typing import Any, Dict, List, Union
 
 from pipecat.adapters.base_llm_adapter import BaseLLMAdapter
@@ -11,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema
 
 
 class OpenAIRealtimeLLMAdapter(BaseLLMAdapter):
+    """LLM adapter for OpenAI Realtime API function calling.
+
+    Converts Pipecat's tool schemas into the specific format required by
+    OpenAI's Realtime API for function calling capabilities.
+    """
+
     @staticmethod
     def _to_openai_realtime_function_format(function: FunctionSchema) -> Dict[str, Any]:
+        """Convert a function schema to OpenAI Realtime format.
+
+        Args:
+            function: The function schema to convert.
+
+        Returns:
+            Dictionary in OpenAI Realtime function format.
+        """
         return {
             "type": "function",
             "name": function.name,
@@ -25,10 +42,13 @@ class OpenAIRealtimeLLMAdapter(BaseLLMAdapter):
         }
 
     def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]:
-        """Converts function schemas to Openai Realtime function-calling format.
+        """Convert tool schemas to OpenAI Realtime function-calling format.
 
-        :return: Openai Realtime formatted function call definition.
-        """
+        Args:
+            tools_schema: The tools schema containing functions to convert.
 
+        Returns:
+            List of function definitions in OpenAI Realtime format.
+        """
         functions_schema = tools_schema.standard_tools
         return [self._to_openai_realtime_function_format(func) for func in functions_schema]

pipecat/audio/filters/base_audio_filter.py

@@ -4,44 +4,68 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base audio filter interface for input transport audio processing.
+
+This module provides the abstract base class for implementing audio filters
+that process audio data before VAD and downstream processing in input transports.
+"""
+
 from abc import ABC, abstractmethod
 
 from pipecat.frames.frames import FilterControlFrame
 
 
 class BaseAudioFilter(ABC):
-    """This is a base class for input transport audio filters. If an audio
+    """Base class for input transport audio filters.
+
+    This is a base class for input transport audio filters. If an audio
     filter is provided to the input transport it will be used to process audio
     before VAD and before pushing it downstream. There are control frames to
     update filter settings or to enable or disable the filter at runtime.
-
     """
 
     @abstractmethod
     async def start(self, sample_rate: int):
-        """This will be called from the input transport when the transport is
+        """Initialize the filter when the input transport starts.
+
+        This will be called from the input transport when the transport is
         started. It can be used to initialize the filter. The input transport
         sample rate is provided so the filter can adjust to that sample rate.
 
+        Args:
+            sample_rate: The sample rate of the input transport in Hz.
         """
         pass
 
     @abstractmethod
     async def stop(self):
-        """This will be called from the input transport when the transport is
-        stopping.
+        """Clean up the filter when the input transport stops.
 
+        This will be called from the input transport when the transport is
+        stopping.
         """
         pass
 
     @abstractmethod
     async def process_frame(self, frame: FilterControlFrame):
-        """This will be called when the input transport receives a
+        """Process control frames for runtime filter configuration.
+
+        This will be called when the input transport receives a
         FilterControlFrame.
 
+        Args:
+            frame: The control frame containing filter commands or settings.
         """
         pass
 
     @abstractmethod
     async def filter(self, audio: bytes) -> bytes:
+        """Apply the audio filter to the provided audio data.
+
+        Args:
+            audio: Raw audio data as bytes to be filtered.
+
+        Returns:
+            Filtered audio data as bytes.
+        """
         pass

pipecat/audio/filters/koala_filter.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Koala noise suppression audio filter for Pipecat.
+
+This module provides an audio filter implementation using PicoVoice's Koala
+Noise Suppression engine to reduce background noise in audio streams.
+"""
+
 from typing import Sequence
 
 import numpy as np
@@ -21,12 +27,19 @@ except ModuleNotFoundError as e:
 
 
 class KoalaFilter(BaseAudioFilter):
-    """This is an audio filter that uses Koala Noise Suppression (from
-    PicoVoice).
+    """Audio filter using Koala Noise Suppression from PicoVoice.
 
+    Provides real-time noise suppression for audio streams using PicoVoice's
+    Koala engine. The filter buffers audio data to match Koala's required
+    frame length and processes it in chunks.
     """
 
     def __init__(self, *, access_key: str) -> None:
+        """Initialize the Koala noise suppression filter.
+
+        Args:
+            access_key: PicoVoice access key for Koala engine authentication.
+        """
         self._access_key = access_key
 
         self._filtering = True
@@ -36,6 +49,11 @@ class KoalaFilter(BaseAudioFilter):
         self._audio_buffer = bytearray()
 
     async def start(self, sample_rate: int):
+        """Initialize the filter with the transport's sample rate.
+
+        Args:
+            sample_rate: The sample rate of the input transport in Hz.
+        """
         self._sample_rate = sample_rate
         if self._sample_rate != self._koala.sample_rate:
             logger.warning(
@@ -44,13 +62,30 @@ class KoalaFilter(BaseAudioFilter):
             self._koala_ready = False
 
     async def stop(self):
+        """Clean up the Koala engine when stopping."""
         self._koala.reset()
 
     async def process_frame(self, frame: FilterControlFrame):
+        """Process control frames to enable/disable filtering.
+
+        Args:
+            frame: The control frame containing filter commands.
+        """
         if isinstance(frame, FilterEnableFrame):
             self._filtering = frame.enable
 
     async def filter(self, audio: bytes) -> bytes:
+        """Apply Koala noise suppression to audio data.
+
+        Buffers incoming audio and processes it in chunks that match Koala's
+        required frame length. Returns filtered audio data.
+
+        Args:
+            audio: Raw audio data as bytes to be filtered.
+
+        Returns:
+            Noise-suppressed audio data as bytes.
+        """
         if not self._koala_ready or not self._filtering:
             return audio
 

pipecat/audio/filters/krisp_filter.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Krisp noise reduction audio filter for Pipecat.
+
+This module provides an audio filter implementation using Krisp's noise
+reduction technology to suppress background noise in audio streams.
+"""
+
 import os
 
 import numpy as np
@@ -21,14 +27,27 @@ except ModuleNotFoundError as e:
 
 
 class KrispProcessorManager:
-    """
-    Ensures that only one KrispAudioProcessor instance exists for the entire program.
+    """Singleton manager for KrispAudioProcessor instances.
+
+    Ensures that only one KrispAudioProcessor instance exists for the entire
+    program.
     """
 
     _krisp_instance = None
 
     @classmethod
     def get_processor(cls, sample_rate: int, sample_type: str, channels: int, model_path: str):
+        """Get or create a KrispAudioProcessor instance.
+
+        Args:
+            sample_rate: Audio sample rate in Hz.
+            sample_type: Audio sample type (e.g., "PCM_16").
+            channels: Number of audio channels.
+            model_path: Path to the Krisp model file.
+
+        Returns:
+            Shared KrispAudioProcessor instance.
+        """
         if cls._krisp_instance is None:
             cls._krisp_instance = KrispAudioProcessor(
                 sample_rate, sample_type, channels, model_path
@@ -37,14 +56,26 @@ class KrispProcessorManager:
 
 
 class KrispFilter(BaseAudioFilter):
+    """Audio filter using Krisp noise reduction technology.
+
+    Provides real-time noise reduction for audio streams using Krisp's
+    proprietary noise suppression algorithms. Requires a Krisp model file
+    for operation.
+    """
+
     def __init__(
         self, sample_type: str = "PCM_16", channels: int = 1, model_path: str = None
     ) -> None:
-        """Initializes the KrispAudioProcessor with customizable audio processing settings.
+        """Initialize the Krisp noise reduction filter.
 
-        :param sample_type: The type of audio sample, default is 'PCM_16'.
-        :param channels: Number of audio channels, default is 1.
-        :param model_path: Path to the Krisp model; defaults to environment variable KRISP_MODEL_PATH if not provided.
+        Args:
+            sample_type: The audio sample format. Defaults to "PCM_16".
+            channels: Number of audio channels. Defaults to 1.
+            model_path: Path to the Krisp model file. If None, uses KRISP_MODEL_PATH
+                environment variable.
+
+        Raises:
+            ValueError: If model_path is not provided and KRISP_MODEL_PATH is not set.
         """
         super().__init__()
 
@@ -63,19 +94,41 @@ class KrispFilter(BaseAudioFilter):
         self._krisp_processor = None
 
     async def start(self, sample_rate: int):
+        """Initialize the Krisp processor with the transport's sample rate.
+
+        Args:
+            sample_rate: The sample rate of the input transport in Hz.
+        """
         self._sample_rate = sample_rate
         self._krisp_processor = KrispProcessorManager.get_processor(
             self._sample_rate, self._sample_type, self._channels, self._model_path
         )
 
     async def stop(self):
+        """Clean up the Krisp processor when stopping."""
         self._krisp_processor = None
 
     async def process_frame(self, frame: FilterControlFrame):
+        """Process control frames to enable/disable filtering.
+
+        Args:
+            frame: The control frame containing filter commands.
+        """
         if isinstance(frame, FilterEnableFrame):
             self._filtering = frame.enable
 
     async def filter(self, audio: bytes) -> bytes:
+        """Apply Krisp noise reduction to audio data.
+
+        Converts audio to float32, applies Krisp noise reduction processing,
+        and returns the filtered audio clipped to int16 range.
+
+        Args:
+            audio: Raw audio data as bytes to be filtered.
+
+        Returns:
+            Noise-reduced audio data as bytes.
+        """
         if not self._filtering:
             return audio
 

pipecat/audio/filters/noisereduce_filter.py

@@ -4,6 +4,13 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Noisereduce audio filter for Pipecat.
+
+This module provides an audio filter implementation using the noisereduce
+library to reduce background noise in audio streams through spectral
+gating algorithms.
+"""
+
 import numpy as np
 from loguru import logger
 
@@ -21,21 +28,51 @@ except ModuleNotFoundError as e:
 
 
 class NoisereduceFilter(BaseAudioFilter):
+    """Audio filter using the noisereduce library for noise suppression.
+
+    Applies spectral gating noise reduction algorithms to suppress background
+    noise in audio streams. Uses the noisereduce library's default noise
+    reduction parameters.
+    """
+
     def __init__(self) -> None:
+        """Initialize the noisereduce filter."""
         self._filtering = True
         self._sample_rate = 0
 
     async def start(self, sample_rate: int):
+        """Initialize the filter with the transport's sample rate.
+
+        Args:
+            sample_rate: The sample rate of the input transport in Hz.
+        """
         self._sample_rate = sample_rate
 
     async def stop(self):
+        """Clean up the filter when stopping."""
         pass
 
     async def process_frame(self, frame: FilterControlFrame):
+        """Process control frames to enable/disable filtering.
+
+        Args:
+            frame: The control frame containing filter commands.
+        """
         if isinstance(frame, FilterEnableFrame):
             self._filtering = frame.enable
 
     async def filter(self, audio: bytes) -> bytes:
+        """Apply noise reduction to audio data using spectral gating.
+
+        Converts audio to float32, applies noisereduce processing, and returns
+        the filtered audio clipped to int16 range.
+
+        Args:
+            audio: Raw audio data as bytes to be filtered.
+
+        Returns:
+            Noise-reduced audio data as bytes.
+        """
         if not self._filtering:
             return audio
 

pipecat/audio/interruptions/base_interruption_strategy.py

@@ -4,31 +4,51 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base interruption strategy for determining when users can interrupt bot speech."""
+
 from abc import ABC, abstractmethod
 
 
 class BaseInterruptionStrategy(ABC):
-    """This is a base class for interruption strategies. Interruption strategies
+    """Base class for interruption strategies.
+
+    This is a base class for interruption strategies. Interruption strategies
     decide when the user can interrupt the bot while the bot is speaking. For
     example, there could be strategies based on audio volume or strategies based
     on the number of words the user spoke.
-
     """
 
     async def append_audio(self, audio: bytes, sample_rate: int):
-        """Appends audio to the strategy. Not all strategies handle audio."""
+        """Append audio data to the strategy for analysis.
+
+        Not all strategies handle audio. Default implementation does nothing.
+
+        Args:
+            audio: Raw audio bytes to append.
+            sample_rate: Sample rate of the audio data in Hz.
+        """
         pass
 
     async def append_text(self, text: str):
-        """Appends text to the strategy. Not all strategies handle text."""
+        """Append text data to the strategy for analysis.
+
+        Not all strategies handle text. Default implementation does nothing.
+
+        Args:
+            text: Text string to append for analysis.
+        """
         pass
 
     @abstractmethod
     async def should_interrupt(self) -> bool:
-        """This is called when the user stops speaking and it's time to decide
+        """Determine if the user should interrupt the bot.
+
+        This is called when the user stops speaking and it's time to decide
         whether the user should interrupt the bot. The decision will be based on
         the aggregated audio and/or text.
 
+        Returns:
+            True if the user should interrupt the bot, False otherwise.
         """
         pass
 

pipecat/audio/interruptions/min_words_interruption_strategy.py

@@ -4,31 +4,47 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Minimum words interruption strategy for word count-based interruptions."""
+
 from loguru import logger
 
 from pipecat.audio.interruptions.base_interruption_strategy import BaseInterruptionStrategy
 
 
 class MinWordsInterruptionStrategy(BaseInterruptionStrategy):
-    """This is an interruption strategy based on a minimum number of words said
+    """Interruption strategy based on minimum number of words spoken.
+
+    This is an interruption strategy based on a minimum number of words said
     by the user. That is, the strategy will be true if the user has said at
     least that amount of words.
-
     """
 
     def __init__(self, *, min_words: int):
+        """Initialize the minimum words interruption strategy.
+
+        Args:
+            min_words: Minimum number of words required to trigger an interruption.
+        """
         super().__init__()
         self._min_words = min_words
         self._text = ""
 
     async def append_text(self, text: str):
-        """Appends text for later analysis. Not all strategies need to handle
-        text.
+        """Append text for word count analysis.
+
+        Args:
+            text: Text string to append to the accumulated text.
 
+        Note: Not all strategies need to handle text.
         """
         self._text += text
 
     async def should_interrupt(self) -> bool:
+        """Check if the minimum word count has been reached.
+
+        Returns:
+            True if the user has spoken at least the minimum number of words.
+        """
         word_count = len(self._text.split())
         interrupt = word_count >= self._min_words
         logger.debug(
@@ -37,4 +53,5 @@ class MinWordsInterruptionStrategy(BaseInterruptionStrategy):
         return interrupt
 
     async def reset(self):
+        """Reset the accumulated text for the next analysis cycle."""
         self._text = ""

pipecat/audio/mixers/base_audio_mixer.py

@@ -4,50 +4,73 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Base audio mixer for output transport integration.
+
+Provides the abstract base class for audio mixers that can be integrated with
+output transports to mix incoming audio with generated audio from the mixer.
+"""
+
 from abc import ABC, abstractmethod
 
 from pipecat.frames.frames import MixerControlFrame
 
 
 class BaseAudioMixer(ABC):
-    """This is a base class for output transport audio mixers. If an audio mixer
+    """Base class for output transport audio mixers.
+
+    This is a base class for output transport audio mixers. If an audio mixer
     is provided to the output transport it will be used to mix the audio frames
     coming into to the transport with the audio generated from the mixer. There
     are control frames to update mixer settings or to enable or disable the
     mixer at runtime.
-
     """
 
     @abstractmethod
     async def start(self, sample_rate: int):
-        """This will be called from the output transport when the transport is
+        """Initialize the mixer when the output transport starts.
+
+        This will be called from the output transport when the transport is
         started. It can be used to initialize the mixer. The output transport
         sample rate is provided so the mixer can adjust to that sample rate.
 
+        Args:
+            sample_rate: The sample rate of the output transport in Hz.
         """
         pass
 
     @abstractmethod
     async def stop(self):
-        """This will be called from the output transport when the transport is
-        stopping.
+        """Clean up the mixer when the output transport stops.
 
+        This will be called from the output transport when the transport is
+        stopping.
         """
         pass
 
     @abstractmethod
     async def process_frame(self, frame: MixerControlFrame):
-        """This will be called when the output transport receives a
+        """Process mixer control frames from the transport.
+
+        This will be called when the output transport receives a
         MixerControlFrame.
 
+        Args:
+            frame: The mixer control frame to process.
         """
         pass
 
     @abstractmethod
     async def mix(self, audio: bytes) -> bytes:
-        """This is called with the audio that is about to be sent from the
+        """Mix transport audio with mixer-generated audio.
+
+        This is called with the audio that is about to be sent from the
         output transport and that should be mixed with the mixer audio if the
         mixer is enabled.
 
+        Args:
+            audio: Raw audio bytes from the transport to mix.
+
+        Returns:
+            Mixed audio bytes combining transport and mixer audio.
         """
         pass