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

pipecat/processors/aggregators/llm_response.py

@@ -4,8 +4,16 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
+"""LLM response aggregators for handling conversation context and message aggregation.
+
+This module provides aggregators that process and accumulate LLM responses, user inputs,
+and conversation context. These aggregators handle the flow between speech-to-text,
+LLM processing, and text-to-speech components in conversational AI pipelines.
+"""
+
 import asyncio
 import time
+import warnings
 from abc import abstractmethod
 from dataclasses import dataclass
 from typing import Dict, List, Literal, Optional, Set
@@ -13,6 +21,8 @@ from typing import Dict, List, Literal, Optional, Set
 from loguru import logger
 
 from pipecat.audio.interruptions.base_interruption_strategy import BaseInterruptionStrategy
+from pipecat.audio.turn.smart_turn.base_smart_turn import SmartTurnParams
+from pipecat.audio.vad.vad_analyzer import VADParams
 from pipecat.frames.frames import (
     BotInterruptionFrame,
     BotStartedSpeakingFrame,
@@ -37,6 +47,7 @@ from pipecat.frames.frames import (
     LLMSetToolsFrame,
     LLMTextFrame,
     OpenAILLMContextAssistantTimestampFrame,
+    SpeechControlParamsFrame,
     StartFrame,
     StartInterruptionFrame,
     TextFrame,
@@ -55,30 +66,63 @@ from pipecat.utils.time import time_now_iso8601
 
 @dataclass
 class LLMUserAggregatorParams:
+    """Parameters for configuring LLM user aggregation behavior.
+
+    Parameters:
+        aggregation_timeout: Maximum time in seconds to wait for additional
+            transcription content before pushing aggregated result. This
+            timeout is used only when the transcription is slow to arrive.
+        turn_emulated_vad_timeout: Maximum time in seconds to wait for emulated
+            VAD when using turn-based analysis. Applied when transcription is
+            received but VAD didn't detect speech (e.g., whispered utterances).
+        enable_emulated_vad_interruptions: When True, allows emulated VAD events
+            to interrupt the bot when it's speaking. When False, emulated speech
+            is ignored while the bot is speaking.
+    """
+
     aggregation_timeout: float = 0.5
+    turn_emulated_vad_timeout: float = 0.8
+    enable_emulated_vad_interruptions: bool = False
 
 
 @dataclass
 class LLMAssistantAggregatorParams:
+    """Parameters for configuring LLM assistant aggregation behavior.
+
+    Parameters:
+        expect_stripped_words: Whether to expect and handle stripped words
+            in text frames by adding spaces between tokens.
+    """
+
     expect_stripped_words: bool = True
 
 
 class LLMFullResponseAggregator(FrameProcessor):
-    """This is an LLM aggregator that aggregates a full LLM completion. It
-    aggregates LLM text frames (tokens) received between
-    `LLMFullResponseStartFrame` and `LLMFullResponseEndFrame`. Every full
-    completion is returned via the "on_completion" event handler:
-
-       @aggregator.event_handler("on_completion")
-       async def on_completion(
-           aggregator: LLMFullResponseAggregator,
-           completion: str,
-           completed: bool,
-       )
-
+    """Aggregates complete LLM responses between start and end frames.
+
+    This aggregator collects LLM text frames (tokens) received between
+    `LLMFullResponseStartFrame` and `LLMFullResponseEndFrame` and provides
+    the complete response via an event handler.
+
+    The aggregator provides an "on_completion" event that fires when a full
+    completion is available::
+
+        @aggregator.event_handler("on_completion")
+        async def on_completion(
+            aggregator: LLMFullResponseAggregator,
+            completion: str,
+            completed: bool,
+        ):
+            # Handle the completion
+            pass
     """
 
     def __init__(self, **kwargs):
+        """Initialize the LLM full response aggregator.
+
+        Args:
+            **kwargs: Additional arguments passed to parent FrameProcessor.
+        """
         super().__init__(**kwargs)
 
         self._aggregation = ""
@@ -87,6 +131,12 @@ class LLMFullResponseAggregator(FrameProcessor):
         self._register_event_handler("on_completion")
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process incoming frames and aggregate LLM text content.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, StartInterruptionFrame):
@@ -117,83 +167,123 @@ class LLMFullResponseAggregator(FrameProcessor):
 
 
 class BaseLLMResponseAggregator(FrameProcessor):
-    """This is the base class for all LLM response aggregators. These
-    aggregators process incoming frames and aggregate content until they are
-    ready to push the aggregation. In the case of a user, an aggregation might
-    be a full transcription received from the STT service.
+    """Base class for all LLM response aggregators.
 
-    The LLM response aggregators also keep a store (e.g. a message list or an
-    LLM context) of the current conversation, that is, it stores the messages
-    said by the user or by the bot.
+    These aggregators process incoming frames and aggregate content until they are
+    ready to push the aggregation downstream. They maintain conversation state
+    and handle message flow between different components in the pipeline.
 
+    The aggregators keep a store (e.g. message list or LLM context) of the current
+    conversation, storing messages from both users and the bot.
     """
 
     def __init__(self, **kwargs):
+        """Initialize the base LLM response aggregator.
+
+        Args:
+            **kwargs: Additional arguments passed to parent FrameProcessor.
+        """
         super().__init__(**kwargs)
 
     @property
     @abstractmethod
     def messages(self) -> List[dict]:
-        """Returns the messages from the current conversation."""
+        """Get the messages from the current conversation.
+
+        Returns:
+            List of message dictionaries representing the conversation history.
+        """
         pass
 
     @property
     @abstractmethod
     def role(self) -> str:
-        """Returns the role (e.g. user, assistant...) for this aggregator."""
+        """Get the role for this aggregator.
+
+        Returns:
+            The role string (e.g. "user", "assistant") for this aggregator.
+        """
         pass
 
     @abstractmethod
     def add_messages(self, messages):
-        """Add the given messages to the conversation."""
+        """Add the given messages to the conversation.
+
+        Args:
+            messages: Messages to append to the conversation history.
+        """
         pass
 
     @abstractmethod
     def set_messages(self, messages):
-        """Reset the conversation with the given messages."""
+        """Reset the conversation with the given messages.
+
+        Args:
+            messages: Messages to replace the current conversation history.
+        """
         pass
 
     @abstractmethod
     def set_tools(self, tools):
-        """Set LLM tools to be used in the current conversation."""
+        """Set LLM tools to be used in the current conversation.
+
+        Args:
+            tools: List of tool definitions for the LLM to use.
+        """
         pass
 
     @abstractmethod
     def set_tool_choice(self, tool_choice):
-        """Set the tool choice. This should modify the LLM context."""
+        """Set the tool choice for the LLM.
+
+        Args:
+            tool_choice: Tool choice configuration for the LLM context.
+        """
         pass
 
     @abstractmethod
     async def reset(self):
-        """Reset the internals of this aggregator. This should not modify the
-        internal messages.
+        """Reset the internal state of this aggregator.
+
+        This should clear aggregation state but not modify the conversation messages.
         """
         pass
 
     @abstractmethod
     async def handle_aggregation(self, aggregation: str):
-        """Adds the given aggregation to the aggregator. The aggregator can use
-        a simple list of message or a context. It doesn't not push any frames.
+        """Add the given aggregation to the conversation store.
 
+        Args:
+            aggregation: The aggregated text content to add to the conversation.
         """
         pass
 
     @abstractmethod
     async def push_aggregation(self):
-        """Pushes the current aggregation. For example, iN the case of context
-        aggregation this might push a new context frame.
+        """Push the current aggregation downstream.
 
+        The specific frame type pushed depends on the aggregator implementation
+        (e.g. context frame, messages frame).
         """
         pass
 
 
 class LLMContextResponseAggregator(BaseLLMResponseAggregator):
-    """This is a base LLM aggregator that uses an LLM context to store the
-    conversation. It pushes `OpenAILLMContextFrame` as an aggregation frame.
+    """Base LLM aggregator that uses an OpenAI LLM context for conversation storage.
 
+    This aggregator maintains conversation state using an OpenAILLMContext and
+    pushes OpenAILLMContextFrame objects as aggregation frames. It provides
+    common functionality for context-based conversation management.
     """
 
     def __init__(self, *, context: OpenAILLMContext, role: str, **kwargs):
+        """Initialize the context response aggregator.
+
+        Args:
+            context: The OpenAI LLM context to use for conversation storage.
+            role: The role this aggregator represents (e.g. "user", "assistant").
+            **kwargs: Additional arguments passed to parent class.
+        """
         super().__init__(**kwargs)
         self._context = context
         self._role = role
@@ -202,46 +292,99 @@ class LLMContextResponseAggregator(BaseLLMResponseAggregator):
 
     @property
     def messages(self) -> List[dict]:
+        """Get messages from the LLM context.
+
+        Returns:
+            List of message dictionaries from the context.
+        """
         return self._context.get_messages()
 
     @property
     def role(self) -> str:
+        """Get the role for this aggregator.
+
+        Returns:
+            The role string for this aggregator.
+        """
         return self._role
 
     @property
     def context(self):
+        """Get the OpenAI LLM context.
+
+        Returns:
+            The OpenAILLMContext instance used by this aggregator.
+        """
         return self._context
 
     def get_context_frame(self) -> OpenAILLMContextFrame:
+        """Create a context frame with the current context.
+
+        Returns:
+            OpenAILLMContextFrame containing the current context.
+        """
         return OpenAILLMContextFrame(context=self._context)
 
     async def push_context_frame(self, direction: FrameDirection = FrameDirection.DOWNSTREAM):
+        """Push a context frame in the specified direction.
+
+        Args:
+            direction: The direction to push the frame (upstream or downstream).
+        """
         frame = self.get_context_frame()
         await self.push_frame(frame, direction)
 
     def add_messages(self, messages):
+        """Add messages to the context.
+
+        Args:
+            messages: Messages to add to the conversation context.
+        """
         self._context.add_messages(messages)
 
     def set_messages(self, messages):
+        """Set the context messages.
+
+        Args:
+            messages: Messages to replace the current context messages.
+        """
         self._context.set_messages(messages)
 
     def set_tools(self, tools: List):
+        """Set tools in the context.
+
+        Args:
+            tools: List of tool definitions to set in the context.
+        """
         self._context.set_tools(tools)
 
     def set_tool_choice(self, tool_choice: Literal["none", "auto", "required"] | dict):
+        """Set tool choice in the context.
+
+        Args:
+            tool_choice: Tool choice configuration for the context.
+        """
         self._context.set_tool_choice(tool_choice)
 
     async def reset(self):
+        """Reset the aggregation state."""
         self._aggregation = ""
 
 
 class LLMUserContextAggregator(LLMContextResponseAggregator):
-    """This is a user LLM aggregator that uses an LLM context to store the
-    conversation. It aggregates transcriptions from the STT service and it has
-    logic to handle multiple scenarios where transcriptions are received between
-    VAD events (`UserStartedSpeakingFrame` and `UserStoppedSpeakingFrame`) or
-    even outside or no VAD events at all.
+    """User LLM aggregator that processes speech-to-text transcriptions.
+
+    This aggregator handles the complex logic of aggregating user speech transcriptions
+    from STT services. It manages multiple scenarios including:
+
+    - Transcriptions received between VAD events
+    - Transcriptions received outside VAD events
+    - Interim vs final transcriptions
+    - User interruptions during bot speech
+    - Emulated VAD for whispered or short utterances
 
+    The aggregator uses timeouts to handle cases where transcriptions arrive
+    after VAD events or when no VAD is available.
     """
 
     def __init__(
@@ -251,8 +394,18 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         params: Optional[LLMUserAggregatorParams] = None,
         **kwargs,
     ):
+        """Initialize the user context aggregator.
+
+        Args:
+            context: The OpenAI LLM context for conversation storage.
+            params: Configuration parameters for aggregation behavior.
+            **kwargs: Additional arguments. Supports deprecated 'aggregation_timeout'.
+        """
         super().__init__(context=context, role="user", **kwargs)
         self._params = params or LLMUserAggregatorParams()
+        self._vad_params: Optional[VADParams] = None
+        self._turn_params: Optional[SmartTurnParams] = None
+
         if "aggregation_timeout" in kwargs:
             import warnings
 
@@ -280,6 +433,7 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         self._last_aggregation_push_time = 0
 
     async def reset(self):
+        """Reset the aggregation state and interruption strategies."""
         await super().reset()
         self._was_bot_speaking = False
         self._seen_interim_results = False
@@ -287,12 +441,22 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         [await s.reset() for s in self._interruption_strategies]
 
     async def handle_aggregation(self, aggregation: str):
+        """Add the aggregated user text to the context.
+
+        Args:
+            aggregation: The aggregated user text to add as a user message.
+        """
         self._context.add_message({"role": self.role, "content": aggregation})
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames for user speech aggregation and context management.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         if isinstance(frame, StartInterruptionFrame):
             self.logger.debug("Received StartInterruptionFrame")
-
         await super().process_frame(frame, direction)
 
         if isinstance(frame, StartFrame):
@@ -328,9 +492,9 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         elif isinstance(frame, InterimTranscriptionFrame):
             await self._handle_interim_transcription(frame)
         elif isinstance(frame, LLMMessagesAppendFrame):
-            self.add_messages(frame.messages)
+            await self._handle_llm_messages_append(frame)
         elif isinstance(frame, LLMMessagesUpdateFrame):
-            self.set_messages(frame.messages)
+            await self._handle_llm_messages_update(frame)
         elif isinstance(frame, LLMSetToolsFrame):
             self.set_tools(frame.tools)
         elif isinstance(frame, LLMSetToolChoiceFrame):
@@ -338,6 +502,10 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         elif isinstance(frame, LLMFullResponseStartFrame):
             self._last_llm_response_start_time = time.time()
             self._latest_final_transcript = ""
+        elif isinstance(frame, SpeechControlParamsFrame):
+            self._vad_params = frame.vad_params
+            self._turn_params = frame.turn_params
+            await self.push_frame(frame, direction)
         else:
             await self.push_frame(frame, direction)
 
@@ -353,7 +521,7 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
         self._last_aggregation_push_time = time.time()
 
     async def push_aggregation(self, trigger_interruption: bool = False):
-        """Pushes the current aggregation based on interruption strategies and conditions."""
+        """Push the current aggregation based on interruption strategies and conditions."""
         if len(self._aggregation) > 0:
             if self.interruption_strategies and self._bot_speaking:
                 should_interrupt = await self._should_interrupt_based_on_strategies()
@@ -373,7 +541,8 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
                     self.logger.debug(
                         "Triggering interruption - pushing BotInterruptionFrame and aggregation"
                     )
-                    await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM)
+                    # await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM)
+                    await self.push_frame(StartInterruptionFrame(), FrameDirection.DOWNSTREAM)
                     self.logger.debug("Pushed BotInterruptionFrame")
                 # No interruption config - normal behavior (always push aggregation)
                 await self._process_aggregation()
@@ -393,7 +562,11 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
             # await self.push_frame(OpenAILLMContextFrame(self._context))
 
     async def _should_interrupt_based_on_strategies(self) -> bool:
-        """Check if interruption should occur based on configured strategies."""
+        """Check if interruption should occur based on configured strategies.
+
+        Returns:
+            True if any interruption strategy indicates interruption should occur.
+        """
 
         async def should_interrupt(strategy: BaseInterruptionStrategy):
             await strategy.append_text(self._aggregation)
@@ -410,6 +583,16 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
     async def _cancel(self, frame: CancelFrame):
         await self._cancel_aggregation_task()
 
+    async def _handle_llm_messages_append(self, frame: LLMMessagesAppendFrame):
+        self.add_messages(frame.messages)
+        if frame.run_llm:
+            await self.push_context_frame()
+
+    async def _handle_llm_messages_update(self, frame: LLMMessagesUpdateFrame):
+        self.set_messages(frame.messages)
+        if frame.run_llm:
+            await self.push_context_frame()
+
     async def _handle_input_audio(self, frame: InputAudioRawFrame):
         for s in self.interruption_strategies:
             await s.append_audio(frame.audio, frame.sample_rate)
@@ -524,9 +707,40 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
     async def _aggregation_task_handler(self):
         while True:
             try:
-                await asyncio.wait_for(
-                    self._aggregation_event.wait(), self._params.aggregation_timeout
-                )
+                # The _aggregation_task_handler handles two distinct timeout scenarios:
+                #
+                # 1. When emulating_vad=True: Wait for emulated VAD timeout before
+                #    pushing aggregation (simulating VAD behavior when no actual VAD
+                #    detection occurred).
+                #
+                # 2. When emulating_vad=False: Use aggregation_timeout as a buffer
+                #    to wait for potential late-arriving transcription frames after
+                #    a real VAD event.
+                #
+                # For emulated VAD scenarios, the timeout strategy depends on whether
+                # a turn analyzer is configured:
+                #
+                # - WITH turn analyzer: Use turn_emulated_vad_timeout parameter because
+                #   the VAD's stop_secs is set very low (e.g. 0.2s) for rapid speech
+                #   chunking to feed the turn analyzer. This low value is too fast
+                #   for emulated VAD scenarios where we need to allow users time to
+                #   finish speaking (e.g. 0.8s).
+                #
+                # - WITHOUT turn analyzer: Use VAD's stop_secs directly to maintain
+                #   consistent user experience between real VAD detection and
+                #   emulated VAD scenarios.
+                if not self._emulating_vad:
+                    timeout = self._params.aggregation_timeout
+                elif self._turn_params:
+                    timeout = self._params.turn_emulated_vad_timeout
+                else:
+                    # Use VAD stop_secs when no turn analyzer is present, fallback if no VAD params
+                    timeout = (
+                        self._vad_params.stop_secs
+                        if self._vad_params
+                        else self._params.turn_emulated_vad_timeout
+                    )
+                await asyncio.wait_for(self._aggregation_event.wait(), timeout=timeout)
                 await self._maybe_emulate_user_speaking()
             except asyncio.TimeoutError:
                 if not self._user_speaking:
@@ -540,43 +754,47 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
                     )
                     self._emulating_vad = False
             finally:
-                self.reset_watchdog()
                 self._aggregation_event.clear()
 
     async def _maybe_emulate_user_speaking(self):
-        """Emulate user speaking if we got a transcription but it was not
-        detected by VAD. Only do that if the bot is not speaking.
+        """Maybe emulate user speaking based on transcription.
 
+        Emulate user speaking if we got a transcription but it was not
+        detected by VAD. Behavior when bot is speaking depends on the
+        enable_emulated_vad_interruptions parameter.
         """
-        if not self._user_speaking:
-            diff_time = time.time() - self._last_user_speaking_time
-            if diff_time < self._aggregation_timeout:
-                self.logger.debug("Pushing aggregation")
-                await self.push_aggregation()
-        # Commenting the original pipecat code.
         # Check if we received a transcription but VAD was not able to detect
         # voice (e.g. when you whisper a short utterance). In that case, we need
-        # to emulate VAD (i.e. user start/stopped speaking), but we do it only
-        # if the bot is not speaking. If the bot is speaking and we really have
-        # a short utterance we don't really want to interrupt the bot.
-        # if not self._user_speaking and not self._waiting_for_aggregation:
-        #     if self._bot_speaking:
-        #         # If we reached this case and the bot is speaking, let's ignore
-        #         # what the user said.
-        #         logger.debug("Ignoring user speaking emulation, bot is speaking.")
-        #         await self.reset()
-        #     else:
-        #         # The bot is not speaking so, let's trigger user speaking
-        #         # emulation.
-        #         await self.push_frame(EmulateUserStartedSpeakingFrame(), FrameDirection.UPSTREAM)
-        #         self._emulating_vad = True
+        # to emulate VAD (i.e. user start/stopped speaking).
+        if (
+            not self._user_speaking
+            and not self._waiting_for_aggregation
+            and len(self._aggregation) > 0
+        ):
+            if self._bot_speaking and not self._params.enable_emulated_vad_interruptions:
+                # If emulated VAD interruptions are disabled and bot is speaking, ignore
+                logger.debug("Ignoring user speaking emulation, bot is speaking.")
+                await self.reset()
+            else:
+                # Either bot is not speaking, or emulated VAD interruptions are enabled
+                # - trigger user speaking emulation.
+                await self.push_frame(EmulateUserStartedSpeakingFrame(), FrameDirection.UPSTREAM)
+                self._emulating_vad = True
 
 
 class LLMAssistantContextAggregator(LLMContextResponseAggregator):
-    """This is an assistant LLM aggregator that uses an LLM context to store the
-    conversation. It aggregates text frames received between
-    `LLMFullResponseStartFrame` and `LLMFullResponseEndFrame`.
+    """Assistant LLM aggregator that processes bot responses and function calls.
+
+    This aggregator handles the complex logic of processing assistant responses including:
+
+    - Text frame aggregation between response start/end markers
+    - Function call lifecycle management
+    - Context updates with timestamps
+    - Tool execution and result handling
+    - Interruption handling during responses
 
+    The aggregator manages function calls in progress and coordinates between
+    text generation and tool execution phases of LLM responses.
     """
 
     def __init__(
@@ -586,6 +804,13 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
         params: Optional[LLMAssistantAggregatorParams] = None,
         **kwargs,
     ):
+        """Initialize the assistant context aggregator.
+
+        Args:
+            context: The OpenAI LLM context for conversation storage.
+            params: Configuration parameters for aggregation behavior.
+            **kwargs: Additional arguments. Supports deprecated 'expect_stripped_words'.
+        """
         super().__init__(context=context, role="assistant", **kwargs)
         self._params = params or LLMAssistantAggregatorParams()
 
@@ -610,26 +835,57 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
         """Check if there are any function calls currently in progress.
 
         Returns:
-            bool: True if function calls are in progress, False otherwise
+            True if function calls are in progress, False otherwise.
         """
         return bool(self._function_calls_in_progress)
 
     async def handle_aggregation(self, aggregation: str):
+        """Add the aggregated assistant text to the context.
+
+        Args:
+            aggregation: The aggregated assistant text to add as an assistant message.
+        """
         self._context.add_message({"role": "assistant", "content": aggregation})
 
     async def handle_function_call_in_progress(self, frame: FunctionCallInProgressFrame):
+        """Handle a function call that is in progress.
+
+        Args:
+            frame: The function call in progress frame to handle.
+        """
         pass
 
     async def handle_function_call_result(self, frame: FunctionCallResultFrame):
+        """Handle the result of a completed function call.
+
+        Args:
+            frame: The function call result frame to handle.
+        """
         pass
 
     async def handle_function_call_cancel(self, frame: FunctionCallCancelFrame):
+        """Handle cancellation of a function call.
+
+        Args:
+            frame: The function call cancel frame to handle.
+        """
         pass
 
     async def handle_user_image_frame(self, frame: UserImageRawFrame):
+        """Handle a user image frame associated with a function call.
+
+        Args:
+            frame: The user image frame to handle.
+        """
         pass
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
+        """Process frames for assistant response aggregation and function call management.
+
+        Args:
+            frame: The frame to process.
+            direction: The direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, StartInterruptionFrame):
@@ -642,9 +898,9 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
         elif isinstance(frame, TextFrame):
             await self._handle_text(frame)
         elif isinstance(frame, LLMMessagesAppendFrame):
-            self.add_messages(frame.messages)
+            await self._handle_llm_messages_append(frame)
         elif isinstance(frame, LLMMessagesUpdateFrame):
-            self.set_messages(frame.messages)
+            await self._handle_llm_messages_update(frame)
         elif isinstance(frame, LLMSetToolsFrame):
             self.set_tools(frame.tools)
         elif isinstance(frame, LLMSetToolChoiceFrame):
@@ -666,6 +922,7 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
             await self.push_frame(frame, direction)
 
     async def push_aggregation(self):
+        """Push the current assistant aggregation with timestamp."""
         if not self._aggregation:
             return
 
@@ -682,6 +939,16 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
         timestamp_frame = OpenAILLMContextAssistantTimestampFrame(timestamp=time_now_iso8601())
         await self.push_frame(timestamp_frame)
 
+    async def _handle_llm_messages_append(self, frame: LLMMessagesAppendFrame):
+        self.add_messages(frame.messages)
+        if frame.run_llm:
+            await self.push_context_frame(FrameDirection.UPSTREAM)
+
+    async def _handle_llm_messages_update(self, frame: LLMMessagesUpdateFrame):
+        self.set_messages(frame.messages)
+        if frame.run_llm:
+            await self.push_context_frame(FrameDirection.UPSTREAM)
+
     async def _handle_interruptions(self, frame: StartInterruptionFrame):
         await self.push_aggregation()
         self._started = 0
@@ -788,13 +1055,20 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
 
     def _context_updated_task_finished(self, task: asyncio.Task):
         self._context_updated_tasks.discard(task)
-        # The task is finished so this should exit immediately. We need to do
-        # this because otherwise the task manager would report a dangling task
-        # if we don't remove it.
-        asyncio.run_coroutine_threadsafe(self.wait_for_task(task), self.get_event_loop())
 
 
 class LLMUserResponseAggregator(LLMUserContextAggregator):
+    """User response aggregator that outputs LLMMessagesFrame instead of context frames.
+
+    .. deprecated:: 0.0.79
+        This class is deprecated and will be removed in a future version.
+        Use `LLMUserContextAggregator` or another LLM-specific subclass instead.
+
+    This aggregator extends LLMUserContextAggregator but pushes LLMMessagesFrame
+    objects downstream instead of OpenAILLMContextFrame objects. This is useful
+    when you need message-based output rather than context-based output.
+    """
+
     def __init__(
         self,
         messages: Optional[List[dict]] = None,
@@ -802,21 +1076,42 @@ class LLMUserResponseAggregator(LLMUserContextAggregator):
         params: Optional[LLMUserAggregatorParams] = None,
         **kwargs,
     ):
+        """Initialize the user response aggregator.
+
+        Args:
+            messages: Initial messages for the conversation context.
+            params: Configuration parameters for aggregation behavior.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        warnings.warn(
+            "LLMUserResponseAggregator is deprecated and will be removed in a future version. "
+            "Use LLMUserContextAggregator or another LLM-specific subclass instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(context=OpenAILLMContext(messages), params=params, **kwargs)
 
-    async def push_aggregation(self):
-        if len(self._aggregation) > 0:
-            await self.handle_aggregation(self._aggregation)
+    async def _process_aggregation(self):
+        """Process the current aggregation and push it downstream."""
+        aggregation = self._aggregation
+        await self.reset()
+        await self.handle_aggregation(aggregation)
+        frame = LLMMessagesFrame(self._context.messages)
+        await self.push_frame(frame)
 
-            # Reset the aggregation. Reset it before pushing it down, otherwise
-            # if the tasks gets cancelled we won't be able to clear things up.
-            await self.reset()
 
-            frame = LLMMessagesFrame(self._context.messages)
-            await self.push_frame(frame)
+class LLMAssistantResponseAggregator(LLMAssistantContextAggregator):
+    """Assistant response aggregator that outputs LLMMessagesFrame instead of context frames.
 
+    .. deprecated:: 0.0.79
+        This class is deprecated and will be removed in a future version.
+        Use `LLMAssistantContextAggregator` or another LLM-specific subclass instead.
+
+    This aggregator extends LLMAssistantContextAggregator but pushes LLMMessagesFrame
+    objects downstream instead of OpenAILLMContextFrame objects. This is useful
+    when you need message-based output rather than context-based output.
+    """
 
-class LLMAssistantResponseAggregator(LLMAssistantContextAggregator):
     def __init__(
         self,
         messages: Optional[List[dict]] = None,
@@ -824,9 +1119,23 @@ class LLMAssistantResponseAggregator(LLMAssistantContextAggregator):
         params: Optional[LLMAssistantAggregatorParams] = None,
         **kwargs,
     ):
+        """Initialize the assistant response aggregator.
+
+        Args:
+            messages: Initial messages for the conversation context.
+            params: Configuration parameters for aggregation behavior.
+            **kwargs: Additional arguments passed to parent class.
+        """
+        warnings.warn(
+            "LLMAssistantResponseAggregator is deprecated and will be removed in a future version. "
+            "Use LLMAssistantContextAggregator or another LLM-specific subclass instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(context=OpenAILLMContext(messages), params=params, **kwargs)
 
     async def push_aggregation(self):
+        """Push the aggregated assistant response as an LLMMessagesFrame."""
         if len(self._aggregation) > 0:
             await self.handle_aggregation(self._aggregation)