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

pipecat/processors/aggregators/openai_llm_context.py

@@ -4,6 +4,12 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""OpenAI LLM context management for Pipecat.
+
+This module provides classes for managing OpenAI-specific conversation contexts,
+including message handling, tool management, and image/audio processing capabilities.
+"""
+
 import base64
 import copy
 import io
@@ -29,7 +35,21 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class CustomEncoder(json.JSONEncoder):
+    """Custom JSON encoder for handling special data types in logging.
+
+    Provides specialized encoding for io.BytesIO objects to display
+    readable representations in log output instead of raw binary data.
+    """
+
     def default(self, obj):
+        """Encode special objects for JSON serialization.
+
+        Args:
+            obj: The object to encode.
+
+        Returns:
+            Encoded representation of the object.
+        """
         if isinstance(obj, io.BytesIO):
             # Convert the first 8 bytes to an ASCII hex string
             return f"{obj.getbuffer()[0:8].hex()}..."
@@ -37,63 +57,140 @@ class CustomEncoder(json.JSONEncoder):
 
 
 class OpenAILLMContext:
+    """Manages conversation context for OpenAI LLM interactions.
+
+    Handles message history, tool definitions, tool choices, and multimedia content
+    for OpenAI API conversations. Provides methods for message manipulation,
+    content formatting, and integration with various LLM adapters.
+    """
+
     def __init__(
         self,
         messages: Optional[List[ChatCompletionMessageParam]] = None,
         tools: List[ChatCompletionToolParam] | NotGiven | ToolsSchema = NOT_GIVEN,
         tool_choice: ChatCompletionToolChoiceOptionParam | NotGiven = NOT_GIVEN,
     ):
+        """Initialize the OpenAI LLM context.
+
+        Args:
+            messages: Initial list of conversation messages.
+            tools: Available tools for the LLM to use.
+            tool_choice: Tool selection strategy for the LLM.
+        """
         self._messages: List[ChatCompletionMessageParam] = messages if messages else []
         self._tool_choice: ChatCompletionToolChoiceOptionParam | NotGiven = tool_choice
         self._tools: List[ChatCompletionToolParam] | NotGiven | ToolsSchema = tools
         self._llm_adapter: Optional[BaseLLMAdapter] = None
 
     def get_llm_adapter(self) -> Optional[BaseLLMAdapter]:
+        """Get the current LLM adapter.
+
+        Returns:
+            The currently set LLM adapter, or None if not set.
+        """
         return self._llm_adapter
 
     def set_llm_adapter(self, llm_adapter: BaseLLMAdapter):
+        """Set the LLM adapter for context processing.
+
+        Args:
+            llm_adapter: The LLM adapter to use for tool conversion.
+        """
         self._llm_adapter = llm_adapter
 
     @staticmethod
     def from_messages(messages: List[dict]) -> "OpenAILLMContext":
+        """Create a context from a list of message dictionaries.
+
+        Args:
+            messages: List of message dictionaries to convert to context.
+
+        Returns:
+            New OpenAILLMContext instance with the provided messages.
+        """
         context = OpenAILLMContext()
 
         for message in messages:
-            if "name" not in message:
-                message["name"] = message["role"]
             context.add_message(message)
         return context
 
     @property
     def messages(self) -> List[ChatCompletionMessageParam]:
+        """Get the current messages list.
+
+        Returns:
+            List of conversation messages.
+        """
         return self._messages
 
     @property
     def tools(self) -> List[ChatCompletionToolParam] | NotGiven | List[Any]:
+        """Get the tools list, converting through adapter if available.
+
+        Returns:
+            Tools list, potentially converted by the LLM adapter.
+        """
         if self._llm_adapter:
             return self._llm_adapter.from_standard_tools(self._tools)
         return self._tools
 
     @property
     def tool_choice(self) -> ChatCompletionToolChoiceOptionParam | NotGiven:
+        """Get the current tool choice setting.
+
+        Returns:
+            The tool choice configuration.
+        """
         return self._tool_choice
 
     def add_message(self, message: ChatCompletionMessageParam):
+        """Add a single message to the context.
+
+        Args:
+            message: The message to add to the conversation history.
+        """
         self._messages.append(message)
 
     def add_messages(self, messages: List[ChatCompletionMessageParam]):
+        """Add multiple messages to the context.
+
+        Args:
+            messages: List of messages to add to the conversation history.
+        """
         self._messages.extend(messages)
 
     def set_messages(self, messages: List[ChatCompletionMessageParam]):
+        """Replace all messages in the context.
+
+        Args:
+            messages: New list of messages to replace the current history.
+        """
         self._messages[:] = messages
 
     def get_messages(self) -> List[ChatCompletionMessageParam]:
+        """Get a copy of the current messages list.
+
+        Returns:
+            List of all messages in the conversation history.
+        """
         return self._messages
 
     def get_messages_json(self) -> str:
+        """Get messages as a formatted JSON string.
+
+        Returns:
+            JSON string representation of all messages with custom encoding.
+        """
         return json.dumps(self._messages, cls=CustomEncoder, ensure_ascii=False, indent=2)
 
     def get_messages_for_logging(self) -> str:
+        """Get sanitized messages suitable for logging.
+
+        Removes or truncates sensitive data like image content for safe logging.
+
+        Returns:
+            JSON string with sanitized message content for logging.
+        """
         msgs = []
         for message in self.messages:
             msg = copy.deepcopy(message)
@@ -116,17 +213,18 @@ class OpenAILLMContext:
     def from_standard_message(self, message):
         """Convert from OpenAI message format to OpenAI message format (passthrough).
 
-        OpenAI's format allows both simple string content and structured content:
-        - Simple: {"role": "user", "content": "Hello"}
-        - Structured: {"role": "user", "content": [{"type": "text", "text": "Hello"}]}
+        OpenAI's format allows both simple string content and structured content::
+
+            Simple: {"role": "user", "content": "Hello"}
+            Structured: {"role": "user", "content": [{"type": "text", "text": "Hello"}]}
 
         Since OpenAI is our standard format, this is a passthrough function.
 
         Args:
-            message (dict): Message in OpenAI format
+            message: Message in OpenAI format.
 
         Returns:
-            dict: Same message, unchanged
+            Same message, unchanged.
         """
         return message
 
@@ -138,20 +236,28 @@ class OpenAILLMContext:
         other LLM services that may need to return multiple messages.
 
         Args:
-            obj (dict): Message in OpenAI format with either:
-                - Simple content: {"role": "user", "content": "Hello"}
-                - List content: {"role": "user", "content": [{"type": "text", "text": "Hello"}]}
+            obj: Message in OpenAI format with either simple string content
+                or structured list content.
 
         Returns:
-            list: List containing the original messages, preserving whether
-                the content was in simple string or structured list format
+            List containing the original messages, preserving the content format.
         """
         return [obj]
 
     def get_messages_for_initializing_history(self):
+        """Get messages for initializing conversation history.
+
+        Returns:
+            List of messages suitable for history initialization.
+        """
         return self._messages
 
     def get_messages_for_persistent_storage(self):
+        """Get messages formatted for persistent storage.
+
+        Returns:
+            List of messages converted to standard format for storage.
+        """
         messages = []
         for m in self._messages:
             standard_messages = self.to_standard_messages(m)
@@ -159,9 +265,19 @@ class OpenAILLMContext:
         return messages
 
     def set_tool_choice(self, tool_choice: ChatCompletionToolChoiceOptionParam | NotGiven):
+        """Set the tool choice configuration.
+
+        Args:
+            tool_choice: Tool selection strategy for the LLM.
+        """
         self._tool_choice = tool_choice
 
     def set_tools(self, tools: List[ChatCompletionToolParam] | NotGiven | ToolsSchema = NOT_GIVEN):
+        """Set the available tools for the LLM.
+
+        Args:
+            tools: List of tools available to the LLM, or NOT_GIVEN to disable tools.
+        """
         if tools != NOT_GIVEN and isinstance(tools, list) and len(tools) == 0:
             tools = NOT_GIVEN
         self._tools = tools
@@ -169,6 +285,14 @@ class OpenAILLMContext:
     def add_image_frame_message(
         self, *, format: str, size: tuple[int, int], image: bytes, text: str = None
     ):
+        """Add a message containing an image frame.
+
+        Args:
+            format: Image format (e.g., 'RGB', 'RGBA').
+            size: Image dimensions as (width, height) tuple.
+            image: Raw image bytes.
+            text: Optional text to include with the image.
+        """
         buffer = io.BytesIO()
         Image.frombytes(format, size, image).save(buffer, format="JPEG")
         encoded_image = base64.b64encode(buffer.getvalue()).decode("utf-8")
@@ -182,10 +306,30 @@ class OpenAILLMContext:
         self.add_message({"role": "user", "content": content})
 
     def add_audio_frames_message(self, *, audio_frames: list[AudioRawFrame], text: str = None):
+        """Add a message containing audio frames.
+
+        Args:
+            audio_frames: List of audio frame objects to include.
+            text: Optional text to include with the audio.
+
+        Note:
+            This method is currently a placeholder for future implementation.
+        """
         # todo: implement for OpenAI models and others
         pass
 
     def create_wav_header(self, sample_rate, num_channels, bits_per_sample, data_size):
+        """Create a WAV file header for audio data.
+
+        Args:
+            sample_rate: Audio sample rate in Hz.
+            num_channels: Number of audio channels.
+            bits_per_sample: Bits per audio sample.
+            data_size: Size of audio data in bytes.
+
+        Returns:
+            WAV header as a bytearray.
+        """
         # RIFF chunk descriptor
         header = bytearray()
         header.extend(b"RIFF")  # ChunkID
@@ -211,10 +355,14 @@ class OpenAILLMContext:
 
 @dataclass
 class OpenAILLMContextFrame(Frame):
-    """Like an LLMMessagesFrame, but with extra context specific to the OpenAI
+    """Frame containing OpenAI-specific LLM context.
+
+    Like an LLMMessagesFrame, but with extra context specific to the OpenAI
     API. The context in this message is also mutable, and will be changed by the
     OpenAIContextAggregator frame processor.
 
+    Parameters:
+        context: The OpenAI LLM context containing messages, tools, and configuration.
     """
 
     context: OpenAILLMContext

pipecat/processors/aggregators/sentence.py

@@ -4,35 +4,46 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Text sentence aggregation processor for Pipecat.
+
+This module provides a frame processor that accumulates text frames into
+complete sentences, only outputting when a sentence-ending pattern is detected.
+"""
+
 from pipecat.frames.frames import EndFrame, Frame, InterimTranscriptionFrame, TextFrame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 from pipecat.utils.string import match_endofsentence
 
 
 class SentenceAggregator(FrameProcessor):
-    """This frame processor aggregates text frames into complete sentences.
+    """Aggregates text frames into complete sentences.
+
+    This processor accumulates incoming text frames until a sentence-ending
+    pattern is detected, then outputs the complete sentence as a single frame.
+    Useful for ensuring downstream processors receive coherent, complete sentences
+    rather than fragmented text.
+
+    Frame input/output::
 
-    Frame input/output:
         TextFrame("Hello,") -> None
-        TextFrame(" world.") -> TextFrame("Hello world.")
-
-    Doctest: FIXME to work with asyncio
-    >>> import asyncio
-    >>> async def print_frames(aggregator, frame):
-    ...     async for frame in aggregator.process_frame(frame):
-    ...         print(frame.text)
-
-    >>> aggregator = SentenceAggregator()
-    >>> asyncio.run(print_frames(aggregator, TextFrame("Hello,")))
-    >>> asyncio.run(print_frames(aggregator, TextFrame(" world.")))
-    Hello, world.
+        TextFrame(" world.") -> TextFrame("Hello, world.")
     """
 
     def __init__(self):
+        """Initialize the sentence aggregator.
+
+        Sets up internal state for accumulating text frames into complete sentences.
+        """
         super().__init__()
         self._aggregation = ""
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and aggregate text into complete sentences.
+
+        Args:
+            frame: The incoming frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         # We ignore interim description at this point.

pipecat/processors/aggregators/user_response.py

@@ -4,15 +4,40 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""User response aggregation for text frames.
+
+This module provides an aggregator that collects user responses and outputs
+them as TextFrame objects, useful for capturing and processing user input
+in conversational pipelines.
+"""
+
 from pipecat.frames.frames import TextFrame
-from pipecat.processors.aggregators.llm_response import LLMUserResponseAggregator
+from pipecat.processors.aggregators.llm_response import LLMUserContextAggregator
+from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
+
 
+class UserResponseAggregator(LLMUserContextAggregator):
+    """Aggregates user responses into TextFrame objects.
+
+    This aggregator extends LLMUserContextAggregator to specifically handle
+    user input by collecting text responses and outputting them as TextFrame
+    objects when the aggregation is complete.
+    """
 
-class UserResponseAggregator(LLMUserResponseAggregator):
     def __init__(self, **kwargs):
-        super().__init__(**kwargs)
+        """Initialize the user response aggregator.
+
+        Args:
+            **kwargs: Additional arguments passed to parent LLMUserContextAggregator.
+        """
+        super().__init__(context=OpenAILLMContext(), **kwargs)
 
     async def push_aggregation(self):
+        """Push the aggregated user response as a TextFrame.
+
+        Creates a TextFrame from the current aggregation if it contains content,
+        resets the aggregation state, and pushes the frame downstream.
+        """
         if len(self._aggregation) > 0:
             frame = TextFrame(self._aggregation.strip())
 

pipecat/processors/aggregators/vision_image_frame.py

@@ -4,33 +4,43 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Vision image frame aggregation for Pipecat.
+
+This module provides frame aggregation functionality to combine text and image
+frames into vision frames for multimodal processing.
+"""
+
 from pipecat.frames.frames import Frame, InputImageRawFrame, TextFrame, VisionImageRawFrame
 from pipecat.processors.frame_processor import FrameDirection, FrameProcessor
 
 
 class VisionImageFrameAggregator(FrameProcessor):
-    """This aggregator waits for a consecutive TextFrame and an
-    InputImageRawFrame. After the InputImageRawFrame arrives it will output a
-    VisionImageRawFrame.
-
-    >>> from pipecat.frames.frames import ImageFrame
-
-    >>> async def print_frames(aggregator, frame):
-    ...     async for frame in aggregator.process_frame(frame):
-    ...         print(frame)
-
-    >>> aggregator = VisionImageFrameAggregator()
-    >>> asyncio.run(print_frames(aggregator, TextFrame("What do you see?")))
-    >>> asyncio.run(print_frames(aggregator, ImageFrame(image=bytes([]), size=(0, 0))))
-    VisionImageFrame, text: What do you see?, image size: 0x0, buffer size: 0 B
+    """Aggregates consecutive text and image frames into vision frames.
 
+    This aggregator waits for a consecutive TextFrame and an InputImageRawFrame.
+    After the InputImageRawFrame arrives it will output a VisionImageRawFrame
+    combining both the text and image data for multimodal processing.
     """
 
     def __init__(self):
+        """Initialize the vision image frame aggregator.
+
+        The aggregator starts with no cached text, waiting for the first
+        TextFrame to arrive before it can create vision frames.
+        """
         super().__init__()
         self._describe_text = None
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and aggregate text with images.
+
+        Caches TextFrames and combines them with subsequent InputImageRawFrames
+        to create VisionImageRawFrames. Other frames are passed through unchanged.
+
+        Args:
+            frame: The incoming frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, TextFrame):

pipecat/processors/async_generator.py

@@ -4,6 +4,8 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""Async generator processor for frame serialization and streaming."""
+
 import asyncio
 from typing import Any, AsyncGenerator
 
@@ -17,12 +19,32 @@ from pipecat.serializers.base_serializer import FrameSerializer
 
 
 class AsyncGeneratorProcessor(FrameProcessor):
+    """A frame processor that serializes frames and provides them via async generator.
+
+    This processor passes frames through unchanged while simultaneously serializing
+    them and making the serialized data available through an async generator interface.
+    Useful for streaming frame data to external consumers while maintaining the
+    normal frame processing pipeline.
+    """
+
     def __init__(self, *, serializer: FrameSerializer, **kwargs):
+        """Initialize the async generator processor.
+
+        Args:
+            serializer: The frame serializer to use for converting frames to data.
+            **kwargs: Additional arguments passed to the parent FrameProcessor.
+        """
         super().__init__(**kwargs)
         self._serializer = serializer
         self._data_queue = asyncio.Queue()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames by passing them through and queuing serialized data.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         await self.push_frame(frame, direction)
@@ -35,6 +57,12 @@ class AsyncGeneratorProcessor(FrameProcessor):
                 await self._data_queue.put(data)
 
     async def generator(self) -> AsyncGenerator[Any, None]:
+        """Generate serialized frame data asynchronously.
+
+        Yields:
+            Serialized frame data from the internal queue until a termination
+            signal (None) is received.
+        """
         running = True
         while running:
             data = await self._data_queue.get()