Merge pull request #3263 from pipecat-ai/pk/deprecate-openai-llm-context

Deprecate `OpenAILLMContext` and associated things

changelog/3263.deprecated.md

@@ -0,0 +1,15 @@
+- `OpenAILLMContext` and its associated things (context aggregators, etc.) are now deprecated in favor of the universal `LLMContext` and its associated things.
+
+  From the developer's point of view, switching to using `LLMContext` machinery will usually be a matter of going from this:
+
+  ```python
+  context = OpenAILLMContext(messages, tools)
+  context_aggregator = llm.create_context_aggregator(context)
+  ```
+
+  To this:
+
+  ```
+  context = LLMContext(messages, tools)
+  context_aggregator = LLMContextAggregatorPair(context)
+  ```

examples/foundational/14e-function-calling-google.py

@@ -104,7 +104,7 @@ async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
         voice_id="71a7ad14-091c-4e8e-a314-022ece01c121",  # British Reading Lady
     )
 
-    llm = GoogleLLMService(api_key=os.getenv("GOOGLE_API_KEY"), model="gemini-2.0-flash-001")
+    llm = GoogleLLMService(api_key=os.getenv("GOOGLE_API_KEY"))
     llm.register_function("get_weather", get_weather)
     llm.register_function("get_image", get_image)
     llm.register_function("get_restaurant_recommendation", fetch_restaurant_recommendation)

src/pipecat/frames/frames.py

@@ -487,12 +487,31 @@ class TranslationFrame(TextFrame):
 class OpenAILLMContextAssistantTimestampFrame(DataFrame):
     """Timestamp information for assistant messages in LLM context.
 
+    .. deprecated:: 0.0.99
+        `OpenAILLMContextAssistantTimestampFrame` is deprecated and will be removed in a future version.
+        Use `LLMContextAssistantTimestampFrame` with the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         timestamp: Timestamp when the assistant message was created.
     """
 
     timestamp: str
 
+    def __post_init__(self):
+        super().__post_init__()
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "OpenAILLMContextAssistantTimestampFrame is deprecated and will be removed in a future version. "
+                "Use LLMContextAssistantTimestampFrame with the universal LLMContext and LLMContextAggregatorPair instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
 
 # A more universal (LLM-agnostic) name for
 # OpenAILLMContextAssistantTimestampFrame, matching LLMContext

src/pipecat/processors/aggregators/llm_context.py

@@ -78,12 +78,29 @@ class LLMContext:
         from OpenAILLMContext to LLMContext. New user code should use
         LLMContext directly.
 
+        .. deprecated:: 0.0.99
+            `from_openai_context()` is deprecated and will be removed in a future version.
+            Directly use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
+
         Args:
             openai_context: The OpenAI LLM context to convert.
 
         Returns:
             New LLMContext instance with converted messages and settings.
         """
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "from_openai_context() (likely invoked by create_context_aggregator()) is deprecated and will be removed in a future version. "
+                "Directly use the universal LLMContext and LLMContextAggregatorPair instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         # Convert tools to ToolsSchema if needed.
         # If the tools are already a ToolsSchema, this is a no-op.
         # Otherwise, we wrap them in a shim ToolsSchema.

src/pipecat/processors/aggregators/llm_response.py

@@ -12,6 +12,7 @@ LLM processing, and text-to-speech components in conversational AI pipelines.
 """
 
 import asyncio
+import warnings
 from abc import abstractmethod
 from dataclasses import dataclass
 from typing import Dict, List, Literal, Optional, Set
@@ -175,6 +176,11 @@ class BaseLLMResponseAggregator(FrameProcessor):
 
     The aggregators keep a store (e.g. message list or LLM context) of the current
     conversation, storing messages from both users and the bot.
+
+    .. deprecated:: 0.0.99
+        `BaseLLMResponseAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(self, **kwargs):
@@ -182,7 +188,21 @@ class BaseLLMResponseAggregator(FrameProcessor):
 
         Args:
             **kwargs: Additional arguments passed to parent FrameProcessor.
+
+        .. deprecated:: 0.0.99
+            `BaseLLMResponseAggregator` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                f"{self.__class__.__name__} (likely created with create_context_aggregator()) is deprecated and will be removed in a future version. "
+                "Use the universal LLMContext and LLMContextAggregatorPair instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         super().__init__(**kwargs)
 
     @property
@@ -274,6 +294,11 @@ class LLMContextResponseAggregator(BaseLLMResponseAggregator):
     This aggregator maintains conversation state using an OpenAILLMContext and
     pushes OpenAILLMContextFrame objects as aggregation frames. It provides
     common functionality for context-based conversation management.
+
+    .. deprecated:: 0.0.99
+        `LLMContextResponseAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(self, *, context: OpenAILLMContext, role: str, **kwargs):
@@ -283,7 +308,13 @@ class LLMContextResponseAggregator(BaseLLMResponseAggregator):
             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.
+
+        .. deprecated:: 0.0.99
+            `LLMContextResponseAggregator` is deprecated and will be removed in a future version.
+            Use the universal `LLMUserAggregator` and `LLMAssistantAggregator` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # Super handles deprecation warning
         super().__init__(**kwargs)
         self._context = context
         self._role = role
@@ -326,8 +357,6 @@ class LLMContextResponseAggregator(BaseLLMResponseAggregator):
         Returns:
             LLMContextFrame containing the current context.
         """
-        import warnings
-
         with warnings.catch_warnings():
             warnings.simplefilter("always")
             warnings.warn(
@@ -400,6 +429,11 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
 
     The aggregator uses timeouts to handle cases where transcriptions arrive
     after VAD events or when no VAD is available.
+
+    .. deprecated:: 0.0.99
+        `LLMUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(
@@ -415,15 +449,19 @@ class LLMUserContextAggregator(LLMContextResponseAggregator):
             context: The OpenAI LLM context for conversation storage.
             params: Configuration parameters for aggregation behavior.
             **kwargs: Additional arguments. Supports deprecated 'aggregation_timeout'.
+
+        .. deprecated:: 0.0.99
+            `LLMUserContextAggregator` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # Super handles deprecation warning
         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
-
             with warnings.catch_warnings():
                 warnings.simplefilter("always")
                 warnings.warn(
@@ -746,6 +784,11 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
 
     The aggregator manages function calls in progress and coordinates between
     text generation and tool execution phases of LLM responses.
+
+    .. deprecated:: 0.0.99
+        `LLMAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(
@@ -761,13 +804,17 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator):
             context: The OpenAI LLM context for conversation storage.
             params: Configuration parameters for aggregation behavior.
             **kwargs: Additional arguments. Supports deprecated 'expect_stripped_words'.
+
+        .. deprecated:: 0.0.99
+            `LLMAssistantContextAggregator` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # Super handles deprecation warning
         super().__init__(context=context, role="assistant", **kwargs)
         self._params = params or LLMAssistantAggregatorParams()
 
         if "expect_stripped_words" in kwargs:
-            import warnings
-
             with warnings.catch_warnings():
                 warnings.simplefilter("always")
                 warnings.warn(
@@ -1039,8 +1086,6 @@ class LLMUserResponseAggregator(LLMUserContextAggregator):
             params: Configuration parameters for aggregation behavior.
             **kwargs: Additional arguments passed to parent class.
         """
-        import warnings
-
         with warnings.catch_warnings():
             warnings.simplefilter("always")
             warnings.warn(
@@ -1086,8 +1131,6 @@ class LLMAssistantResponseAggregator(LLMAssistantContextAggregator):
             params: Configuration parameters for aggregation behavior.
             **kwargs: Additional arguments passed to parent class.
         """
-        import warnings
-
         with warnings.catch_warnings():
             warnings.simplefilter("always")
             warnings.warn(

src/pipecat/processors/aggregators/openai_llm_context.py

@@ -8,12 +8,18 @@
 
 This module provides classes for managing OpenAI-specific conversation contexts,
 including message handling, tool management, and image/audio processing capabilities.
+
+.. deprecated:: 0.0.99
+    This module is deprecated.
+    Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+    See `OpenAILLMContext` docstring for migration guide.
 """
 
 import base64
 import copy
 import io
 import json
+import warnings
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional
 
@@ -62,6 +68,20 @@ class OpenAILLMContext:
     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.
+
+    .. deprecated:: 0.0.99
+        `OpenAILLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+
+        **Before:**
+
+            context = OpenAILLMContext(messages, tools)
+            context_aggregator = llm.create_context_aggregator(context)
+
+        **After:**
+
+            context = LLMContext(messages, tools)
+            context_aggregator = LLMContextAggregatorPair(context)
     """
 
     def __init__(
@@ -76,7 +96,21 @@ class OpenAILLMContext:
             messages: Initial list of conversation messages.
             tools: Available tools for the LLM to use.
             tool_choice: Tool selection strategy for the LLM.
+
+        .. deprecated:: 0.0.99
+            `OpenAILLMContext` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "OpenAILLMContext is deprecated and will be removed in a future version. "
+                "Use the universal LLMContext and LLMContextAggregatorPair instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self._messages: List[ChatCompletionMessageParam] = messages if messages else []
         self._tool_choice: ChatCompletionToolChoiceOptionParam | NotGiven = tool_choice
         self._tools: List[ChatCompletionToolParam] | NotGiven | ToolsSchema = tools
@@ -356,8 +390,25 @@ class OpenAILLMContextFrame(Frame):
     API. The context in this message is also mutable, and will be changed by the
     OpenAIContextAggregator frame processor.
 
+    .. deprecated:: 0.0.99
+        `OpenAILLMContextFrame` is deprecated and will be removed in a future version.
+        Use `LLMContextFrame` with the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         context: The OpenAI LLM context containing messages, tools, and configuration.
     """
 
     context: OpenAILLMContext
+
+    def __post_init__(self):
+        super().__post_init__()
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "OpenAILLMContextFrame is deprecated and will be removed in a future version. "
+                "Use LLMContextFrame with the universal `LLMContext` and `LLMContextAggregatorPair` instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )

src/pipecat/services/anthropic/llm.py

@@ -29,7 +29,6 @@ from pipecat.adapters.services.anthropic_adapter import (
     AnthropicLLMInvocationParams,
 )
 from pipecat.frames.frames import (
-    ErrorFrame,
     Frame,
     FunctionCallCancelFrame,
     FunctionCallInProgressFrame,
@@ -77,11 +76,17 @@ class AnthropicContextAggregatorPair:
     Encapsulates both user and assistant context aggregators
     to manage conversation flow and message formatting.
 
+    .. deprecated:: 0.0.99
+        `AnthropicContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: The user context aggregator.
         _assistant: The assistant context aggregator.
     """
 
+    # Aggregators handle deprecation warnings
     _user: "AnthropicUserContextAggregator"
     _assistant: "AnthropicAssistantContextAggregator"
 
@@ -325,13 +330,21 @@ class AnthropicLLMService(LLMService):
         Returns:
             A pair of context aggregators, one for the user and one for the assistant,
             encapsulated in an AnthropicContextAggregatorPair.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         context.set_llm_adapter(self.get_llm_adapter())
 
         if isinstance(context, OpenAILLMContext):
             context = AnthropicLLMContext.from_openai_context(context)
+
+        # Aggregators handle deprecation warnings
         user = AnthropicUserContextAggregator(context, params=user_params)
         assistant = AnthropicAssistantContextAggregator(context, params=assistant_params)
+
         return AnthropicContextAggregatorPair(_user=user, _assistant=assistant)
 
     def _get_llm_invocation_params(
@@ -602,6 +615,11 @@ class AnthropicLLMContext(OpenAILLMContext):
     Extends OpenAILLMContext to handle Anthropic-specific features like
     system messages, prompt caching, and message format conversions.
     Manages conversation state and message history formatting.
+
+    .. deprecated:: 0.0.99
+        `AnthropicLLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(
@@ -620,6 +638,7 @@ class AnthropicLLMContext(OpenAILLMContext):
             tool_choice: Tool selection preference.
             system: System message content.
         """
+        # Super handles deprecation warning
         super().__init__(messages=messages, tools=tools, tool_choice=tool_choice)
         self.__setup_local()
         self.system = system
@@ -1041,8 +1060,14 @@ class AnthropicUserContextAggregator(LLMUserContextAggregator):
 
     Handles aggregation of user messages for Anthropic LLM services.
     Inherits all functionality from the base LLMUserContextAggregator.
+
+    .. deprecated:: 0.0.99
+        `AnthropicUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
     pass
 
 
@@ -1061,8 +1086,15 @@ class AnthropicAssistantContextAggregator(LLMAssistantContextAggregator):
 
     Handles function call lifecycle management including in-progress tracking,
     result handling, and cancellation for Anthropic's tool use format.
+
+    .. deprecated:: 0.0.99
+        `AnthropicAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def handle_function_call_in_progress(self, frame: FunctionCallInProgressFrame):
         """Handle a function call that is starting.
 

src/pipecat/services/aws/llm.py

@@ -78,11 +78,17 @@ class AWSBedrockContextAggregatorPair:
     Provides convenient access to both user and assistant context aggregators
     for AWS Bedrock LLM operations.
 
+    .. deprecated:: 0.0.99
+        `AWSBedrockContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: The user context aggregator instance.
         _assistant: The assistant context aggregator instance.
     """
 
+    # Aggregators handle deprecation warnings
     _user: "AWSBedrockUserContextAggregator"
     _assistant: "AWSBedrockAssistantContextAggregator"
 
@@ -109,6 +115,11 @@ class AWSBedrockLLMContext(OpenAILLMContext):
     Extends OpenAI LLM context to handle AWS Bedrock's specific message format
     and system message handling. Manages conversion between OpenAI and Bedrock
     message formats.
+
+    .. deprecated:: 0.0.99
+        `AWSBedrockLLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(
@@ -127,6 +138,7 @@ class AWSBedrockLLMContext(OpenAILLMContext):
             tool_choice: Tool selection strategy or specific tool choice.
             system: System message content for AWS Bedrock.
         """
+        # Super handles deprecation warning
         super().__init__(messages=messages, tools=tools, tool_choice=tool_choice)
         self.system = system
 
@@ -589,11 +601,17 @@ class AWSBedrockUserContextAggregator(LLMUserContextAggregator):
     Handles aggregation of user messages and frames for AWS Bedrock format.
     Inherits all functionality from the base LLM user context aggregator.
 
+    .. deprecated:: 0.0.99
+        `AWSBedrockUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Args:
         context: The LLM context to aggregate messages into.
         params: Configuration parameters for the aggregator.
     """
 
+    # Super handles deprecation warning
     pass
 
 
@@ -603,11 +621,18 @@ class AWSBedrockAssistantContextAggregator(LLMAssistantContextAggregator):
     Handles aggregation of assistant responses and function calls for AWS Bedrock
     format, including tool use and tool result handling.
 
+    .. deprecated:: 0.0.99
+        `AWSBedrockAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Args:
         context: The LLM context to aggregate messages into.
         params: Configuration parameters for the aggregator.
     """
 
+    # Super handles deprecation warning
+
     async def handle_function_call_in_progress(self, frame: FunctionCallInProgressFrame):
         """Handle function call in progress frame.
 
@@ -924,14 +949,20 @@ class AWSBedrockLLMService(LLMService):
             the user and one for the assistant, encapsulated in an
             AWSBedrockContextAggregatorPair.
 
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         context.set_llm_adapter(self.get_llm_adapter())
 
         if isinstance(context, OpenAILLMContext):
             context = AWSBedrockLLMContext.from_openai_context(context)
 
+        # Aggregators handle deprecation warnings
         user = AWSBedrockUserContextAggregator(context, params=user_params)
         assistant = AWSBedrockAssistantContextAggregator(context, params=assistant_params)
+
         return AWSBedrockContextAggregatorPair(_user=user, _assistant=assistant)
 
     def _create_no_op_tool(self):

src/pipecat/services/aws/nova_sonic/context.py

@@ -154,6 +154,11 @@ class AWSNovaSonicLLMContext(OpenAILLMContext):
 
     Extends OpenAI context with Nova Sonic-specific message handling,
     conversation history management, and text buffering capabilities.
+
+    .. deprecated:: 0.0.99
+        `AWSNovaSonicLLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(self, messages=None, tools=None, **kwargs):
@@ -164,6 +169,7 @@ class AWSNovaSonicLLMContext(OpenAILLMContext):
             tools: Available tools for the context.
             **kwargs: Additional arguments passed to parent class.
         """
+        # Super handles deprecation warning
         super().__init__(messages=messages, tools=tools, **kwargs)
         self.__setup_local()
 
@@ -334,8 +340,15 @@ class AWSNovaSonicUserContextAggregator(OpenAIUserContextAggregator):
 
     Extends the OpenAI user context aggregator to emit Nova Sonic-specific
     context update frames.
+
+    .. deprecated:: 0.0.99
+        `AWSNovaSonicUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def process_frame(
         self, frame: Frame, direction: FrameDirection = FrameDirection.DOWNSTREAM
     ):
@@ -357,8 +370,15 @@ class AWSNovaSonicAssistantContextAggregator(OpenAIAssistantContextAggregator):
 
     Provides specialized handling for assistant responses and function calls
     in AWS Nova Sonic context, with custom frame processing logic.
+
+    .. deprecated:: 0.0.99
+        `AWSNovaSonicAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def process_frame(self, frame: Frame, direction: FrameDirection):
         """Process frames with Nova Sonic-specific logic.
 
@@ -409,11 +429,17 @@ class AWSNovaSonicAssistantContextAggregator(OpenAIAssistantContextAggregator):
 class AWSNovaSonicContextAggregatorPair:
     """Pair of user and assistant context aggregators for AWS Nova Sonic.
 
+    .. deprecated:: 0.0.99
+        `AWSNovaSonicContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: The user context aggregator.
         _assistant: The assistant context aggregator.
     """
 
+    # Aggregators handle deprecation warnings
     _user: AWSNovaSonicUserContextAggregator
     _assistant: AWSNovaSonicAssistantContextAggregator
 

src/pipecat/services/aws/nova_sonic/llm.py

@@ -1231,7 +1231,13 @@ class AWSNovaSonicLLMService(LLMService):
 
         Returns:
             A pair of user and assistant context aggregators.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # from_openai_context handles deprecation warning
         context = LLMContext.from_openai_context(context)
         return LLMContextAggregatorPair(
             context, user_params=user_params, assistant_params=assistant_params

src/pipecat/services/google/gemini_live/llm.py

@@ -32,7 +32,6 @@ from pipecat.frames.frames import (
     BotStoppedSpeakingFrame,
     CancelFrame,
     EndFrame,
-    ErrorFrame,
     Frame,
     InputAudioRawFrame,
     InputImageRawFrame,
@@ -1772,7 +1771,13 @@ class GeminiLiveLLMService(LLMService):
 
         Returns:
             A pair of user and assistant context aggregators.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # from_openai_context handles deprecation warning
         context = LLMContext.from_openai_context(context)
         assistant_params.expect_stripped_words = False
         return LLMContextAggregatorPair(

src/pipecat/services/google/llm.py

@@ -93,8 +93,15 @@ class GoogleUserContextAggregator(OpenAIUserContextAggregator):
 
     Extends OpenAI user context aggregator to handle Google AI's specific
     Content and Part message format for user messages.
+
+    .. deprecated:: 0.0.99
+        `OpenAIUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def handle_aggregation(self, aggregation: str):
         """Add the aggregated user text to the context as a Google Content message.
 
@@ -109,8 +116,15 @@ class GoogleAssistantContextAggregator(OpenAIAssistantContextAggregator):
 
     Extends OpenAI assistant context aggregator to handle Google AI's specific
     Content and Part message format for assistant responses and function calls.
+
+    .. deprecated:: 0.0.99
+        `GoogleAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def handle_aggregation(self, aggregation: str):
         """Handle aggregated assistant text response.
 
@@ -207,11 +221,17 @@ class GoogleAssistantContextAggregator(OpenAIAssistantContextAggregator):
 class GoogleContextAggregatorPair:
     """Pair of Google context aggregators for user and assistant messages.
 
+    .. deprecated:: 0.0.99
+        `GoogleContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: User context aggregator for handling user messages.
         _assistant: Assistant context aggregator for handling assistant responses.
     """
 
+    # Aggregators handle deprecation warnings
     _user: GoogleUserContextAggregator
     _assistant: GoogleAssistantContextAggregator
 
@@ -237,6 +257,11 @@ class GoogleLLMContext(OpenAILLMContext):
 
     This class handles conversion between OpenAI-style messages and Google AI's
     Content/Part format, including system messages, function calls, and media.
+
+    .. deprecated:: 0.0.99
+        `GoogleLLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(
@@ -252,6 +277,7 @@ class GoogleLLMContext(OpenAILLMContext):
             tools: Available tools/functions for the model.
             tool_choice: Tool choice configuration.
         """
+        # Super handles deprecation warning
         super().__init__(messages=messages, tools=tools, tool_choice=tool_choice)
         self.system_message = None
 
@@ -1225,11 +1251,18 @@ class GoogleLLMService(LLMService):
             the user and one for the assistant, encapsulated in an
             GoogleContextAggregatorPair.
 
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         context.set_llm_adapter(self.get_llm_adapter())
 
         if isinstance(context, OpenAILLMContext):
             context = GoogleLLMContext.upgrade_to_google(context)
+
+        # Aggregators handle deprecation warnings
         user = GoogleUserContextAggregator(context, params=user_params)
         assistant = GoogleAssistantContextAggregator(context, params=assistant_params)
+
         return GoogleContextAggregatorPair(_user=user, _assistant=assistant)

src/pipecat/services/grok/llm.py

@@ -36,11 +36,17 @@ class GrokContextAggregatorPair:
     Provides a convenient container for managing both user and assistant
     context aggregators together for Grok LLM interactions.
 
+    .. deprecated:: 0.0.99
+        `GrokContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: The user context aggregator instance.
         _assistant: The assistant context aggregator instance.
     """
 
+    # Aggregators handle deprecation warnings
     _user: OpenAIUserContextAggregator
     _assistant: OpenAIAssistantContextAggregator
 
@@ -196,9 +202,16 @@ class GrokLLMService(OpenAILLMService):
             GrokContextAggregatorPair: A pair of context aggregators, one for
             the user and one for the assistant, encapsulated in an
             GrokContextAggregatorPair.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         context.set_llm_adapter(self.get_llm_adapter())
 
+        # Aggregators handle deprecation warnings
         user = OpenAIUserContextAggregator(context, params=user_params)
         assistant = OpenAIAssistantContextAggregator(context, params=assistant_params)
+
         return GrokContextAggregatorPair(_user=user, _assistant=assistant)

src/pipecat/services/llm_service.py

@@ -8,13 +8,13 @@
 
 import asyncio
 import inspect
+import warnings
 from dataclasses import dataclass
 from typing import (
     Any,
     Awaitable,
     Callable,
     Dict,
-    List,
     Mapping,
     Optional,
     Protocol,
@@ -243,7 +243,21 @@ class LLMService(AIService):
 
         Returns:
             A context aggregator instance.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            warnings.warn(
+                "create_context_aggregator() is deprecated and will be removed in a future version. "
+                "Use the universal LLMContext and LLMContextAggregatorPair directly instead. "
+                "See OpenAILLMContext docstring for migration guide.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         pass
 
     async def start(self, frame: StartFrame):
@@ -336,8 +350,6 @@ class LLMService(AIService):
         signature = inspect.signature(handler)
         handler_deprecated = len(signature.parameters) > 1
         if handler_deprecated:
-            import warnings
-
             with warnings.catch_warnings():
                 warnings.simplefilter("always")
                 warnings.warn(
@@ -356,8 +368,6 @@ class LLMService(AIService):
 
         # Start callbacks are now deprecated.
         if start_callback:
-            import warnings
-
             with warnings.catch_warnings():
                 warnings.simplefilter("always")
                 warnings.warn(
@@ -500,8 +510,6 @@ class LLMService(AIService):
             timeout: Optional timeout for the requested image to be added to the LLM context.
 
         """
-        import warnings
-
         with warnings.catch_warnings():
             warnings.simplefilter("always")
             warnings.warn(

src/pipecat/services/openai/llm.py

@@ -30,11 +30,17 @@ from pipecat.services.openai.base_llm import BaseOpenAILLMService
 class OpenAIContextAggregatorPair:
     """Pair of OpenAI context aggregators for user and assistant messages.
 
+    .. deprecated:: 0.0.99
+        `OpenAIContextAggregatorPair` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Parameters:
         _user: User context aggregator for processing user messages.
         _assistant: Assistant context aggregator for processing assistant messages.
     """
 
+    # Aggregators handle deprecation warnings
     _user: "OpenAIUserContextAggregator"
     _assistant: "OpenAIAssistantContextAggregator"
 
@@ -101,10 +107,17 @@ class OpenAILLMService(BaseOpenAILLMService):
             the user and one for the assistant, encapsulated in an
             OpenAIContextAggregatorPair.
 
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         context.set_llm_adapter(self.get_llm_adapter())
+
+        # Aggregators handle deprecation warnings
         user = OpenAIUserContextAggregator(context, params=user_params)
         assistant = OpenAIAssistantContextAggregator(context, params=assistant_params)
+
         return OpenAIContextAggregatorPair(_user=user, _assistant=assistant)
 
 
@@ -113,8 +126,14 @@ class OpenAIUserContextAggregator(LLMUserContextAggregator):
 
     Handles aggregation of user messages for OpenAI LLM services.
     Inherits all functionality from the base LLMUserContextAggregator.
+
+    .. deprecated:: 0.0.99
+        `OpenAIUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
     pass
 
 
@@ -124,8 +143,15 @@ class OpenAIAssistantContextAggregator(LLMAssistantContextAggregator):
     Handles aggregation of assistant messages for OpenAI LLM services,
     with specialized support for OpenAI's function calling format,
     tool usage tracking, and image message handling.
+
+    .. deprecated:: 0.0.99
+        `OpenAIAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
+    # Super handles deprecation warning
+
     async def handle_function_call_in_progress(self, frame: FunctionCallInProgressFrame):
         """Handle a function call in progress.
 

src/pipecat/services/openai/realtime/context.py

@@ -113,6 +113,11 @@ class OpenAIRealtimeLLMContext(OpenAILLMContext):
     Extends the standard OpenAI LLM context to support real-time session properties,
     instruction management, and conversion between standard message formats and
     realtime conversation items.
+
+    .. deprecated:: 0.0.99
+        `OpenAIRealtimeLLMContext` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
     """
 
     def __init__(self, messages=None, tools=None, **kwargs):
@@ -123,6 +128,7 @@ class OpenAIRealtimeLLMContext(OpenAILLMContext):
             tools: Available function tools. Defaults to None.
             **kwargs: Additional arguments passed to parent OpenAILLMContext.
         """
+        # Super handles deprecation warning
         super().__init__(messages=messages, tools=tools, **kwargs)
         self.__setup_local()
 
@@ -267,11 +273,18 @@ class OpenAIRealtimeUserContextAggregator(OpenAIUserContextAggregator):
     Handles user input frames and generates appropriate context updates
     for the realtime conversation, including message updates and tool settings.
 
+    .. deprecated:: 0.0.99
+        `OpenAIRealtimeUserContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Args:
         context: The OpenAI realtime LLM context.
         **kwargs: Additional arguments passed to parent aggregator.
     """
 
+    # Super handles deprecation warning
+
     async def process_frame(
         self, frame: Frame, direction: FrameDirection = FrameDirection.DOWNSTREAM
     ):
@@ -311,11 +324,18 @@ class OpenAIRealtimeAssistantContextAggregator(OpenAIAssistantContextAggregator)
     Handles assistant output frames from the realtime service, filtering
     out duplicate text frames and managing function call results.
 
+    .. deprecated:: 0.0.99
+        `OpenAIRealtimeAssistantContextAggregator` is deprecated and will be removed in a future version.
+        Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+        See `OpenAILLMContext` docstring for migration guide.
+
     Args:
         context: The OpenAI realtime LLM context.
         **kwargs: Additional arguments passed to parent aggregator.
     """
 
+    # Super handles deprecation warning
+
     # The LLMAssistantContextAggregator uses TextFrames to aggregate the LLM output,
     # but the OpenAIRealtimeLLMService pushes LLMTextFrames and TTSTextFrames. We
     # need to override this proces_frame for LLMTextFrame, so that only the TTSTextFrames

src/pipecat/services/openai/realtime/llm.py

@@ -882,6 +882,11 @@ class OpenAIRealtimeLLMService(LLMService):
             OpenAIContextAggregatorPair: A pair of context aggregators, one for
             the user and one for the assistant, encapsulated in an
             OpenAIContextAggregatorPair.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
         # Log warning about transcription frame direction change in 0.0.92.
         # We're putting this warning here rather than in the constructor so
@@ -915,7 +920,7 @@ class OpenAIRealtimeLLMService(LLMService):
             "  context = LLMContext(messages, tools)\n"
             "  context_aggregator = LLMContextAggregatorPair(context)\n"
         )
-
+        # from_openai_context handles deprecation warning already
         context = LLMContext.from_openai_context(context)
         assistant_params.expect_stripped_words = False
         return LLMContextAggregatorPair(

src/pipecat/services/ultravox/llm.py

@@ -541,7 +541,13 @@ class UltravoxRealtimeLLMService(LLMService):
 
         Returns:
             A pair of user and assistant context aggregators.
+
+        .. deprecated:: 0.0.99
+            `create_context_aggregator()` is deprecated and will be removed in a future version.
+            Use the universal `LLMContext` and `LLMContextAggregatorPair` instead.
+            See `OpenAILLMContext` docstring for migration guide.
         """
+        # from_openai_context handles deprecation warning
         context = LLMContext.from_openai_context(context)
         assistant_params.expect_stripped_words = False
         return LLMContextAggregatorPair(