From 9d5f5844b87c6a428429dd1637dc4297b85980d2 Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Thu, 26 Jun 2025 13:14:45 -0700 Subject: [PATCH 01/84] clean mcp schema for gemini models, update http mcp example to use gemini --- examples/foundational/39c-mcp-run-http.py | 5 ++++- src/pipecat/services/mcp_service.py | 8 +++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/examples/foundational/39c-mcp-run-http.py b/examples/foundational/39c-mcp-run-http.py index 1c51894b1..df17869bb 100644 --- a/examples/foundational/39c-mcp-run-http.py +++ b/examples/foundational/39c-mcp-run-http.py @@ -16,6 +16,7 @@ from pipecat.pipeline.pipeline import Pipeline from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineParams, PipelineTask from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.services.google.llm import GoogleLLMService from pipecat.services.cartesia.tts import CartesiaTTSService from pipecat.services.deepgram.stt import DeepgramSTTService from pipecat.services.mcp_service import MCPClient @@ -58,7 +59,9 @@ async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_si voice_id="71a7ad14-091c-4e8e-a314-022ece01c121", # British Reading Lady ) - llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"), model="gpt-4o-mini") + llm = GoogleLLMService( + api_key=os.getenv("GOOGLE_API_KEY"), model="gemini-2.0-flash" + ) try: # Github MCP docs: https://github.com/github/github-mcp-server diff --git a/src/pipecat/services/mcp_service.py b/src/pipecat/services/mcp_service.py index 48202e8f9..13d58ed0c 100644 --- a/src/pipecat/services/mcp_service.py +++ b/src/pipecat/services/mcp_service.py @@ -82,13 +82,14 @@ class MCPClient(BaseObject): return tools_schema def _convert_mcp_schema_to_pipecat( - self, tool_name: str, tool_schema: Dict[str, Any] + self, tool_name: str, tool_schema: Dict[str, Any], llm=None ) -> FunctionSchema: """Convert an mcp tool schema to Pipecat's FunctionSchema format. Args: tool_name: The name of the tool tool_schema: The mcp tool schema + llm: The LLM service instance (used to determine if we need Gemini compatibility) Returns: A FunctionSchema instance """ @@ -97,6 +98,11 @@ class MCPClient(BaseObject): properties = tool_schema["input_schema"].get("properties", {}) required = tool_schema["input_schema"].get("required", []) + + # Only clean properties for Google/Gemini LLM services + if llm and self._is_google_llm(llm): + logger.debug(f"Detected Google LLM service, cleaning schema for Gemini compatibility") + properties = self._clean_schema_for_gemini(properties) schema = FunctionSchema( name=tool_name, From 92df8dc43cca1dc51327bbff154c295b9fc44fd2 Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Thu, 26 Jun 2025 13:15:58 -0700 Subject: [PATCH 02/84] fix formatting --- examples/foundational/39c-mcp-run-http.py | 4 +--- src/pipecat/services/mcp_service.py | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/examples/foundational/39c-mcp-run-http.py b/examples/foundational/39c-mcp-run-http.py index df17869bb..e39349f37 100644 --- a/examples/foundational/39c-mcp-run-http.py +++ b/examples/foundational/39c-mcp-run-http.py @@ -59,9 +59,7 @@ async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_si voice_id="71a7ad14-091c-4e8e-a314-022ece01c121", # British Reading Lady ) - llm = GoogleLLMService( - api_key=os.getenv("GOOGLE_API_KEY"), model="gemini-2.0-flash" - ) + llm = GoogleLLMService(api_key=os.getenv("GOOGLE_API_KEY"), model="gemini-2.0-flash") try: # Github MCP docs: https://github.com/github/github-mcp-server diff --git a/src/pipecat/services/mcp_service.py b/src/pipecat/services/mcp_service.py index 13d58ed0c..c51a9bd9c 100644 --- a/src/pipecat/services/mcp_service.py +++ b/src/pipecat/services/mcp_service.py @@ -98,7 +98,7 @@ class MCPClient(BaseObject): properties = tool_schema["input_schema"].get("properties", {}) required = tool_schema["input_schema"].get("required", []) - + # Only clean properties for Google/Gemini LLM services if llm and self._is_google_llm(llm): logger.debug(f"Detected Google LLM service, cleaning schema for Gemini compatibility") From 0c2066800849f6d4f3044942a1f2cad0c3a75f5a Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Thu, 26 Jun 2025 13:21:44 -0700 Subject: [PATCH 03/84] fixed linter errors --- examples/foundational/39c-mcp-run-http.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/foundational/39c-mcp-run-http.py b/examples/foundational/39c-mcp-run-http.py index e39349f37..bdcaa78a5 100644 --- a/examples/foundational/39c-mcp-run-http.py +++ b/examples/foundational/39c-mcp-run-http.py @@ -16,9 +16,9 @@ from pipecat.pipeline.pipeline import Pipeline from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineParams, PipelineTask from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext -from pipecat.services.google.llm import GoogleLLMService from pipecat.services.cartesia.tts import CartesiaTTSService from pipecat.services.deepgram.stt import DeepgramSTTService +from pipecat.services.google.llm import GoogleLLMService from pipecat.services.mcp_service import MCPClient from pipecat.services.openai.llm import OpenAILLMService from pipecat.transports.base_transport import BaseTransport, TransportParams From 86c26fd64c69f481312d84796ba9fa3a7370c6ab Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Thu, 26 Jun 2025 19:57:58 -0700 Subject: [PATCH 04/84] moved needs_mcp_clean_schema to LLMService --- .../services/gemini_multimodal_live/gemini.py | 11 ++++ src/pipecat/services/google/llm.py | 11 ++++ src/pipecat/services/llm_service.py | 11 ++++ src/pipecat/services/mcp_service.py | 54 ++++++++++++++++--- 4 files changed, 80 insertions(+), 7 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index afaf966dc..f9584df9d 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -524,6 +524,17 @@ class GeminiMultimodalLiveLLMService(LLMService): """ return True + def needs_mcp_clean_schema(self) -> bool: + """Check if this LLM service requires MCP schema cleaning. + + Google/Gemini has stricter JSON schema validation and requires + certain properties to be removed or modified for compatibility. + + Returns: + True for Google/Gemini services. + """ + return True + def set_audio_input_paused(self, paused: bool): """Set the audio input pause state. diff --git a/src/pipecat/services/google/llm.py b/src/pipecat/services/google/llm.py index 6b8f51f33..e36c6591e 100644 --- a/src/pipecat/services/google/llm.py +++ b/src/pipecat/services/google/llm.py @@ -631,6 +631,17 @@ class GoogleLLMService(LLMService): """ return True + def needs_mcp_clean_schema(self) -> bool: + """Check if this LLM service requires MCP schema cleaning. + + Google/Gemini has stricter JSON schema validation and requires + certain properties to be removed or modified for compatibility. + + Returns: + True for Google/Gemini services. + """ + return True + def _create_client(self, api_key: str): self._client = genai.Client(api_key=api_key) diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index f7779df98..24ed932d8 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -307,6 +307,17 @@ class LLMService(AIService): return True return function_name in self._functions.keys() + def needs_mcp_clean_schema(self) -> bool: + """Check if this LLM service requires MCP schema cleaning. + + Some LLM services have stricter JSON schema validation and require + certain properties to be removed or modified for compatibility. + + Returns: + True if MCP schemas should be cleaned for this service, False otherwise. + """ + return False + async def run_function_calls(self, function_calls: Sequence[FunctionCallFromLLM]): """Execute a sequence of function calls from the LLM. diff --git a/src/pipecat/services/mcp_service.py b/src/pipecat/services/mcp_service.py index c51a9bd9c..3d757e32e 100644 --- a/src/pipecat/services/mcp_service.py +++ b/src/pipecat/services/mcp_service.py @@ -51,6 +51,7 @@ class MCPClient(BaseObject): super().__init__(**kwargs) self._server_params = server_params self._session = ClientSession + self._needs_schema_cleaning = False if isinstance(server_params, StdioServerParameters): self._client = stdio_client @@ -78,18 +79,56 @@ class MCPClient(BaseObject): Returns: A ToolsSchema containing all successfully registered tools. """ + # Check once if the LLM needs schema cleaning + self._needs_schema_cleaning = llm and llm.needs_mcp_clean_schema() tools_schema = await self._register_tools(llm) return tools_schema + def _clean_schema_for_strict_validation(self, schema: Dict[str, Any]) -> Dict[str, Any]: + """Clean a JSON schema to be compatible with LLMs that have strict validation. + + Some LLMs have stricter validation and don't allow certain schema properties + that are valid in standard JSON Schema. + + Args: + schema: The JSON schema to clean + + Returns: + A cleaned schema compatible with strict validation + """ + if not isinstance(schema, dict): + return schema + + cleaned = {} + + for key, value in schema.items(): + # Skip additionalProperties as some LLMs don't like additionalProperties: false + if key == "additionalProperties": + continue + + # Recursively clean nested objects + if isinstance(value, dict): + cleaned[key] = self._clean_schema_for_strict_validation(value) + elif isinstance(value, list): + cleaned[key] = [ + self._clean_schema_for_strict_validation(item) + if isinstance(item, dict) + else item + for item in value + ] + else: + cleaned[key] = value + + return cleaned + def _convert_mcp_schema_to_pipecat( - self, tool_name: str, tool_schema: Dict[str, Any], llm=None + self, tool_name: str, tool_schema: Dict[str, Any] ) -> FunctionSchema: """Convert an mcp tool schema to Pipecat's FunctionSchema format. Args: tool_name: The name of the tool tool_schema: The mcp tool schema - llm: The LLM service instance (used to determine if we need Gemini compatibility) Returns: A FunctionSchema instance """ @@ -99,10 +138,10 @@ class MCPClient(BaseObject): properties = tool_schema["input_schema"].get("properties", {}) required = tool_schema["input_schema"].get("required", []) - # Only clean properties for Google/Gemini LLM services - if llm and self._is_google_llm(llm): - logger.debug(f"Detected Google LLM service, cleaning schema for Gemini compatibility") - properties = self._clean_schema_for_gemini(properties) + # Only clean properties for LLMs that need strict schema validation + if self._needs_schema_cleaning: + logger.debug("Cleaning schema for strict validation") + properties = self._clean_schema_for_strict_validation(properties) schema = FunctionSchema( name=tool_name, @@ -283,7 +322,8 @@ class MCPClient(BaseObject): try: # Convert the schema function_schema = self._convert_mcp_schema_to_pipecat( - tool_name, {"description": tool.description, "input_schema": tool.inputSchema} + tool_name, + {"description": tool.description, "input_schema": tool.inputSchema}, ) # Register the wrapped function From cafbda1668825d02920c8236356f60c447884593 Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Thu, 26 Jun 2025 20:21:07 -0700 Subject: [PATCH 05/84] remove openai from mcp run http example --- examples/foundational/39c-mcp-run-http.py | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/foundational/39c-mcp-run-http.py b/examples/foundational/39c-mcp-run-http.py index bdcaa78a5..6c39da75c 100644 --- a/examples/foundational/39c-mcp-run-http.py +++ b/examples/foundational/39c-mcp-run-http.py @@ -20,7 +20,6 @@ from pipecat.services.cartesia.tts import CartesiaTTSService from pipecat.services.deepgram.stt import DeepgramSTTService from pipecat.services.google.llm import GoogleLLMService from pipecat.services.mcp_service import MCPClient -from pipecat.services.openai.llm import OpenAILLMService from pipecat.transports.base_transport import BaseTransport, TransportParams from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams from pipecat.transports.services.daily import DailyParams From 15b9a5faf69cbd8348d097c870a013b84f254627 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Mon, 23 Jun 2025 16:02:13 -0400 Subject: [PATCH 06/84] Implement "direct functions", which allow you to bypass specifying a function configuration (as a `FunctionSchema` or in a provider-specific format) and use the Python function directly. Metadata is gathered automatically from the function signature and docstring. --- .../14s-function-calling-direct.py | 147 +++++++++++ pyproject.toml | 3 +- .../adapters/schemas/direct_function.py | 227 +++++++++++++++++ src/pipecat/adapters/schemas/tools_schema.py | 18 +- src/pipecat/services/llm_service.py | 112 ++++++--- tests/test_direct_functions.py | 237 ++++++++++++++++++ 6 files changed, 712 insertions(+), 32 deletions(-) create mode 100644 examples/foundational/14s-function-calling-direct.py create mode 100644 src/pipecat/adapters/schemas/direct_function.py create mode 100644 tests/test_direct_functions.py diff --git a/examples/foundational/14s-function-calling-direct.py b/examples/foundational/14s-function-calling-direct.py new file mode 100644 index 000000000..8c91a369e --- /dev/null +++ b/examples/foundational/14s-function-calling-direct.py @@ -0,0 +1,147 @@ +# +# Copyright (c) 2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +import argparse +import os + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.adapters.schemas.function_schema import FunctionSchema +from pipecat.adapters.schemas.tools_schema import ToolsSchema +from pipecat.audio.vad.silero import SileroVADAnalyzer +from pipecat.frames.frames import TTSSpeakFrame +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineParams, PipelineTask +from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.services.cartesia.tts import CartesiaTTSService +from pipecat.services.deepgram.stt import DeepgramSTTService +from pipecat.services.llm_service import FunctionCallParams +from pipecat.services.openai.llm import OpenAILLMService +from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams +from pipecat.transports.services.daily import DailyParams + +load_dotenv(override=True) + + +async def get_current_weather(params: FunctionCallParams, location: str, format: str): + """ + Get the current weather. + + Args: + location (str): The city and state, e.g. "San Francisco, CA". + format (str): The temperature unit to use. Must be either "celsius" or "fahrenheit". Infer this from the user's location. + """ + await params.result_callback({"conditions": "nice", "temperature": "75"}) + + +async def get_restaurant_recommendation(params: FunctionCallParams, location: str): + """ + Get a restaurant recommendation. + + Args: + location (str): The city and state, e.g. "San Francisco, CA". + """ + await params.result_callback({"name": "The Golden Dragon"}) + + +# We store functions so objects (e.g. SileroVADAnalyzer) don't get +# instantiated. The function will be called when the desired transport gets +# selected. +transport_params = { + "daily": lambda: DailyParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), + "twilio": lambda: FastAPIWebsocketParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), + "webrtc": lambda: TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), +} + + +async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): + logger.info(f"Starting bot") + + stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY")) + + tts = CartesiaTTSService( + api_key=os.getenv("CARTESIA_API_KEY"), + voice_id="71a7ad14-091c-4e8e-a314-022ece01c121", # British Reading Lady + ) + + llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY")) + + # You can also register a function_name of None to get all functions + # sent to the same callback with an additional function_name parameter. + llm.register_direct_function(get_current_weather) + llm.register_direct_function(get_restaurant_recommendation) + + @llm.event_handler("on_function_calls_started") + async def on_function_calls_started(service, function_calls): + await tts.queue_frame(TTSSpeakFrame("Let me check on that.")) + + tools = ToolsSchema(standard_tools=[get_current_weather, get_restaurant_recommendation]) + + messages = [ + { + "role": "system", + "content": "You are a helpful LLM in a WebRTC call. Your goal is to demonstrate your capabilities in a succinct way. Your output will be converted to audio so don't include special characters in your answers. Respond to what the user said in a creative and helpful way.", + }, + ] + + context = OpenAILLMContext(messages, tools) + context_aggregator = llm.create_context_aggregator(context) + + pipeline = Pipeline( + [ + transport.input(), + stt, + context_aggregator.user(), + llm, + tts, + transport.output(), + context_aggregator.assistant(), + ] + ) + + task = PipelineTask( + pipeline, + params=PipelineParams( + enable_metrics=True, + enable_usage_metrics=True, + ), + ) + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + logger.info(f"Client connected") + # Kick off the conversation. + await task.queue_frames([context_aggregator.user().get_context_frame()]) + + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + await task.cancel() + + runner = PipelineRunner(handle_sigint=handle_sigint) + + await runner.run(task) + + +if __name__ == "__main__": + from pipecat.examples.run import main + + main(run_example, transport_params=transport_params) diff --git a/pyproject.toml b/pyproject.toml index f402ddfd1..82669cb0a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,7 +31,8 @@ dependencies = [ "pyloudnorm~=0.1.1", "resampy~=0.4.3", "soxr~=0.5.0", - "openai~=1.70.0" + "openai~=1.70.0", + "docstring_parser~=0.16" ] [project.urls] diff --git a/src/pipecat/adapters/schemas/direct_function.py b/src/pipecat/adapters/schemas/direct_function.py new file mode 100644 index 000000000..377a8ea3e --- /dev/null +++ b/src/pipecat/adapters/schemas/direct_function.py @@ -0,0 +1,227 @@ +import inspect +import types +from typing import ( + Any, + Callable, + Dict, + List, + Mapping, + Protocol, + Set, + Tuple, + Union, + get_args, + get_origin, + get_type_hints, +) + +import docstring_parser + +from pipecat.adapters.schemas.function_schema import FunctionSchema + + +class DirectFunction(Protocol): + """Protocol for a "direct" function that handles LLM function calls. + + "Direct" functions' metadata is automatically extracted from their function signature and + docstrings, allowing them to be used without accompanying function configurations (as + `FunctionSchema`s or in provider-specific formats). + """ + + async def __call__(self, params: "FunctionCallParams", **kwargs: Any) -> None: ... + + +class BaseDirectFunctionWrapper: + """ + Base class for a wrapper around a DirectFunction that: + - extracts metadata from the function signature and docstring + - using that metadata, generates a corresponding FunctionSchema + """ + + @classmethod + def special_first_param_name(cls) -> str: + """The name of the "special" first function parameter that is ignored by the metadata + extraction, as it's not relevant to the LLM. + """ + raise NotImplementedError("Subclasses must define the special first parameter name.") + + def __init__(self, function: Callable): + self.__class__.validate_function(function) + self.function = function + self._initialize_metadata() + + @classmethod + def validate_function(cls, function: Callable) -> None: + if not inspect.iscoroutinefunction(function): + raise Exception(f"Direct function {function.__name__} must be async") + params = list(inspect.signature(function).parameters.items()) + special_first_param_name = cls.special_first_param_name() + if len(params) == 0: + raise Exception( + f"Direct function {function.__name__} must have at least one parameter ({special_first_param_name})" + ) + first_param_name = params[0][0] + if first_param_name != special_first_param_name: + raise Exception( + f"Direct function {function.__name__} first parameter must be named '{special_first_param_name}'" + ) + + def to_function_schema(self) -> FunctionSchema: + return FunctionSchema( + name=self.name, + description=self.description, + properties=self.properties, + required=self.required, + ) + + def _initialize_metadata(self): + # Get function name + self.name = self.function.__name__ + + # Parse docstring for description and parameters + docstring = docstring_parser.parse(inspect.getdoc(self.function)) + + # Get function description + self.description = (docstring.description or "").strip() + + # Get function parameters as JSON schemas, and the list of required parameters + self.properties, self.required = self._get_parameters_as_jsonschema( + self.function, docstring.params + ) + + # TODO: maybe to better support things like enums, check if each type is a pydantic type and use its convert-to-jsonschema function + def _get_parameters_as_jsonschema( + self, func: Callable, docstring_params: List[docstring_parser.DocstringParam] + ) -> Tuple[Dict[str, Any], List[str]]: + """ + Get function parameters as a dictionary of JSON schemas and a list of required parameters. + Ignore the first parameter, as it's expected to be the "special" one. + + Args: + func: Function to get parameters from + docstring_params: List of parameters extracted from the function's docstring + + Returns: + A tuple containing: + - A dictionary mapping each function parameter to its JSON schema + - A list of required parameter names + """ + + sig = inspect.signature(func) + hints = get_type_hints(func) + properties = {} + required = [] + + for name, param in sig.parameters.items(): + # Ignore 'self' parameter + if name == "self": + continue + + # Ignore the first parameter, which is expected to be the "special" one + # (We have already validated that this is the case in validate_function()) + is_first_param = name == next(iter(sig.parameters)) + if is_first_param: + continue + + type_hint = hints.get(name) + + # Convert type hint to JSON schema + properties[name] = self._typehint_to_jsonschema(type_hint) + + # Add whether the parameter is required + # If the parameter has no default value, it's required + if param.default is inspect.Parameter.empty: + required.append(name) + + # Add parameter description from docstring + for doc_param in docstring_params: + if doc_param.arg_name == name: + properties[name]["description"] = doc_param.description or "" + + return properties, required + + def _typehint_to_jsonschema(self, type_hint: Any) -> Dict[str, Any]: + """ + Convert a Python type hint to a JSON Schema. + + Args: + type_hint: A Python type hint + + Returns: + A dictionary representing the JSON Schema + """ + if type_hint is None: + return {} + + # Handle basic types + if type_hint is type(None): + return {"type": "null"} + if type_hint is str: + return {"type": "string"} + elif type_hint is int: + return {"type": "integer"} + elif type_hint is float: + return {"type": "number"} + elif type_hint is bool: + return {"type": "boolean"} + elif type_hint is dict or type_hint is Dict: + return {"type": "object"} + elif type_hint is list or type_hint is List: + return {"type": "array"} + + # Get origin and arguments for complex types + origin = get_origin(type_hint) + args = get_args(type_hint) + + # Handle Optional/Union types + if origin is Union or origin is types.UnionType: + return {"anyOf": [self._typehint_to_jsonschema(arg) for arg in args]} + + # Handle List, Tuple, Set with specific item types + if origin in (list, List, tuple, Tuple, set, Set) and args: + return {"type": "array", "items": self._typehint_to_jsonschema(args[0])} + + # Handle Dict with specific key/value types + if origin in (dict, Dict) and len(args) == 2: + # For JSON Schema, keys must be strings + return {"type": "object", "additionalProperties": self._typehint_to_jsonschema(args[1])} + + # Handle TypedDict + if hasattr(type_hint, "__annotations__"): + properties = {} + required = [] + + # NOTE: this does not yet support some fields being required and others not, which could happen when: + # - the base class is a TypedDict with required fields (total=True or not specified) and the derived class has optional fields (total=False) + # - Python 3.11+ NotRequired is used + all_fields_required = getattr(type_hint, "__total__", True) + + for field_name, field_type in get_type_hints(type_hint).items(): + properties[field_name] = self._typehint_to_jsonschema(field_type) + if all_fields_required: + required.append(field_name) + + schema = {"type": "object", "properties": properties} + + if required: + schema["required"] = required + + return schema + + # Default to any type if we can't determine the specific schema + return {} + + +class DirectFunctionWrapper(BaseDirectFunctionWrapper): + """ + Wrapper around a DirectFunction that: + - extracts metadata from the function signature and docstring + - generates a corresponding FunctionSchema + """ + + @classmethod + def special_first_param_name(cls) -> str: + return "params" + + async def invoke(self, args: Mapping[str, Any], params: "FunctionCallParams"): + return await self.function(params=params, **args) diff --git a/src/pipecat/adapters/schemas/tools_schema.py b/src/pipecat/adapters/schemas/tools_schema.py index 2489e0b4d..de0fdd878 100644 --- a/src/pipecat/adapters/schemas/tools_schema.py +++ b/src/pipecat/adapters/schemas/tools_schema.py @@ -7,6 +7,7 @@ from enum import Enum from typing import Any, Dict, List, Optional +from pipecat.adapters.schemas.direct_function import DirectFunction, DirectFunctionWrapper from pipecat.adapters.schemas.function_schema import FunctionSchema @@ -17,7 +18,7 @@ class AdapterType(Enum): class ToolsSchema: def __init__( self, - standard_tools: List[FunctionSchema], + standard_tools: List[FunctionSchema | DirectFunction], custom_tools: Optional[Dict[AdapterType, List[Dict[str, Any]]]] = None, ) -> None: """ @@ -27,7 +28,20 @@ class ToolsSchema: :param standard_tools: List of tools following FunctionSchema. :param custom_tools: List of tools in a custom format (e.g., search_tool). """ - self._standard_tools = standard_tools + + def _map_standard_tools(tools): + schemas = [] + for tool in tools: + if isinstance(tool, FunctionSchema): + schemas.append(tool) + elif callable(tool): + wrapper = DirectFunctionWrapper(tool) + schemas.append(wrapper.to_function_schema()) + else: + raise TypeError(f"Unsupported tool type: {type(tool)}") + return schemas + + self._standard_tools = _map_standard_tools(standard_tools) self._custom_tools = custom_tools @property diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index 6ef85951a..c87a659ea 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -8,12 +8,33 @@ import asyncio import inspect +import types from dataclasses import dataclass -from typing import Any, Awaitable, Callable, Dict, Mapping, Optional, Protocol, Sequence, Type +from typing import ( + Any, + Awaitable, + Callable, + Dict, + List, + Mapping, + Optional, + Protocol, + Sequence, + Set, + Tuple, + Type, + Union, + get_args, + get_origin, + get_type_hints, +) +import docstring_parser from loguru import logger from pipecat.adapters.base_llm_adapter import BaseLLMAdapter +from pipecat.adapters.schemas.direct_function import DirectFunction, DirectFunctionWrapper +from pipecat.adapters.schemas.function_schema import FunctionSchema from pipecat.adapters.services.open_ai_adapter import OpenAILLMAdapter from pipecat.frames.frames import ( CancelFrame, @@ -94,7 +115,7 @@ class FunctionCallRegistryItem: """ function_name: Optional[str] - handler: FunctionCallHandler + handler: FunctionCallHandler | "DirectFunctionWrapper" cancel_on_interruption: bool @@ -285,6 +306,19 @@ class LLMService(AIService): self._start_callbacks[function_name] = start_callback + def register_direct_function( + self, + handler: DirectFunction, + *, + cancel_on_interruption: bool = True, + ): + wrapper = DirectFunctionWrapper(handler) + self._functions[wrapper.name] = FunctionCallRegistryItem( + function_name=wrapper.name, + handler=wrapper, + cancel_on_interruption=cancel_on_interruption, + ) + def unregister_function(self, function_name: Optional[str]): """Remove a registered function handler. @@ -295,6 +329,11 @@ class LLMService(AIService): if self._start_callbacks[function_name]: del self._start_callbacks[function_name] + def unregister_direct_function(self, handler: Any): + wrapper = DirectFunctionWrapper(handler) + del self._functions[wrapper.name] + # Note: no need to remove start callback here, as direct functions don't support start callbacks. + def has_function(self, function_name: str): """Check if a function handler is registered. @@ -474,35 +513,50 @@ class LLMService(AIService): await self.push_frame(result_frame_downstream, FrameDirection.DOWNSTREAM) await self.push_frame(result_frame_upstream, FrameDirection.UPSTREAM) - signature = inspect.signature(item.handler) - if len(signature.parameters) > 1: - import warnings - - with warnings.catch_warnings(): - warnings.simplefilter("always") - warnings.warn( - "Function calls with parameters `(function_name, tool_call_id, arguments, llm, context, result_callback)` are deprecated, use a single `FunctionCallParams` parameter instead.", - DeprecationWarning, - ) - - await item.handler( - runner_item.function_name, - runner_item.tool_call_id, - runner_item.arguments, - self, - runner_item.context, - function_call_result_callback, + if isinstance(item.handler, DirectFunctionWrapper): + # Handler is a DirectFunctionWrapper + await item.handler.invoke( + args=runner_item.arguments, + params=FunctionCallParams( + function_name=runner_item.function_name, + tool_call_id=runner_item.tool_call_id, + arguments=runner_item.arguments, + llm=self, + context=runner_item.context, + result_callback=function_call_result_callback, + ), ) else: - params = FunctionCallParams( - function_name=runner_item.function_name, - tool_call_id=runner_item.tool_call_id, - arguments=runner_item.arguments, - llm=self, - context=runner_item.context, - result_callback=function_call_result_callback, - ) - await item.handler(params) + # Handler is a FunctionCallHandler + signature = inspect.signature(item.handler) + if len(signature.parameters) > 1: + import warnings + + with warnings.catch_warnings(): + warnings.simplefilter("always") + warnings.warn( + "Function calls with parameters `(function_name, tool_call_id, arguments, llm, context, result_callback)` are deprecated, use a single `FunctionCallParams` parameter instead.", + DeprecationWarning, + ) + + await item.handler( + runner_item.function_name, + runner_item.tool_call_id, + runner_item.arguments, + self, + runner_item.context, + function_call_result_callback, + ) + else: + params = FunctionCallParams( + function_name=runner_item.function_name, + tool_call_id=runner_item.tool_call_id, + arguments=runner_item.arguments, + llm=self, + context=runner_item.context, + result_callback=function_call_result_callback, + ) + await item.handler(params) async def _cancel_function_call(self, function_name: Optional[str]): cancelled_tasks = set() diff --git a/tests/test_direct_functions.py b/tests/test_direct_functions.py new file mode 100644 index 000000000..89967fa03 --- /dev/null +++ b/tests/test_direct_functions.py @@ -0,0 +1,237 @@ +import asyncio +import unittest +from typing import Optional, TypedDict, Union + +from pipecat.adapters.schemas.direct_function import DirectFunctionWrapper +from pipecat.services.llm_service import FunctionCallParams + +# Copyright (c) 2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +class TestDirectFunction(unittest.TestCase): + def test_name_is_set_from_function(self): + async def my_function(params: FunctionCallParams): + return {"status": "success"}, None + + func = DirectFunctionWrapper(function=my_function) + self.assertEqual(func.name, "my_function") + + def test_description_is_set_from_function(self): + async def my_function_short_description(params: FunctionCallParams): + """This is a test function.""" + return {"status": "success"}, None + + func = DirectFunctionWrapper(function=my_function_short_description) + self.assertEqual(func.description, "This is a test function.") + + async def my_function_long_description(params: FunctionCallParams): + """ + This is a test function. + + It does some really cool stuff. + + Trust me, you'll want to use it. + """ + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_long_description)) + func = DirectFunctionWrapper(function=my_function_long_description) + self.assertEqual( + func.description, + "This is a test function.\n\nIt does some really cool stuff.\n\nTrust me, you'll want to use it.", + ) + + def test_properties_are_set_from_function(self): + async def my_function_no_params(params: FunctionCallParams): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_no_params)) + func = DirectFunctionWrapper(function=my_function_no_params) + self.assertEqual(func.properties, {}) + + async def my_function_simple_params( + params: FunctionCallParams, name: str, age: int, height: Union[float, None] + ): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_simple_params)) + func = DirectFunctionWrapper(function=my_function_simple_params) + self.assertEqual( + func.properties, + { + "name": {"type": "string"}, + "age": {"type": "integer"}, + "height": {"anyOf": [{"type": "number"}, {"type": "null"}]}, + }, + ) + + async def my_function_complex_params( + params: FunctionCallParams, + address_lines: list[str], + nickname: str | int | float, + extra: Optional[dict[str, str]], + ): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_params)) + func = DirectFunctionWrapper(function=my_function_complex_params) + self.assertEqual( + func.properties, + { + "address_lines": {"type": "array", "items": {"type": "string"}}, + "nickname": { + "anyOf": [{"type": "string"}, {"type": "integer"}, {"type": "number"}] + }, + "extra": { + "anyOf": [ + {"type": "object", "additionalProperties": {"type": "string"}}, + {"type": "null"}, + ] + }, + }, + ) + + class MyInfo1(TypedDict): + name: str + age: int + + class MyInfo2(TypedDict, total=False): + name: str + age: int + + async def my_function_complex_type_params( + params: FunctionCallParams, info1: MyInfo1, info2: MyInfo2 + ): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_type_params)) + func = DirectFunctionWrapper(function=my_function_complex_type_params) + self.assertEqual( + func.properties, + { + "info1": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "integer"}, + }, + "required": ["name", "age"], + }, + "info2": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "integer"}, + }, + }, + }, + ) + + def test_required_is_set_from_function(self): + async def my_function_no_params(params: FunctionCallParams): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_no_params)) + func = DirectFunctionWrapper(function=my_function_no_params) + self.assertEqual(func.required, []) + + async def my_function_simple_params( + params: FunctionCallParams, name: str, age: int, height: Union[float, None] = None + ): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_simple_params)) + func = DirectFunctionWrapper(function=my_function_simple_params) + self.assertEqual(func.required, ["name", "age"]) + + async def my_function_complex_params( + params: FunctionCallParams, + address_lines: Optional[list[str]], + nickname: str | int = "Bud", + extra: Optional[dict[str, str]] = None, + ): + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_params)) + func = DirectFunctionWrapper(function=my_function_complex_params) + self.assertEqual(func.required, ["address_lines"]) + + def test_property_descriptions_are_set_from_function(self): + async def my_function( + params: FunctionCallParams, name: str, age: int, height: Union[float, None] + ): + """ + This is a test function. + + Args: + name (str): The name of the person. + age (int): The age of the person. + height (float | None): The height of the person in meters. Defaults to None. + """ + return {"status": "success"}, None + + self.assertIsNone(DirectFunctionWrapper.validate_function(my_function)) + func = DirectFunctionWrapper(function=my_function) + + # Validate that the function description is still set correctly even with the longer docstring + self.assertEqual(func.description, "This is a test function.") + + # Validate that the property descriptions are set correctly + self.assertEqual( + func.properties, + { + "name": {"type": "string", "description": "The name of the person."}, + "age": {"type": "integer", "description": "The age of the person."}, + "height": { + "anyOf": [{"type": "number"}, {"type": "null"}], + "description": "The height of the person in meters. Defaults to None.", + }, + }, + ) + + def test_invalid_functions_fail_validation(self): + def my_function_non_async(params: FunctionCallParams): + return {"status": "success"}, None + + with self.assertRaises(InvalidFunctionError): + DirectFunctionWrapper.validate_function(my_function_non_async) + + async def my_function_missing_flow_manager(): + return {"status": "success"}, None + + with self.assertRaises(InvalidFunctionError): + DirectFunctionWrapper.validate_function(my_function_missing_flow_manager) + + async def my_function_misplaced_flow_manager(foo: str, params: FunctionCallParams): + return {"status": "success"}, None + + with self.assertRaises(InvalidFunctionError): + DirectFunctionWrapper.validate_function(my_function_misplaced_flow_manager) + + def test_invoke_calls_function_with_args_and_flow_manager(self): + called = {} + + class DummyFlowManager: + pass + + async def my_function(flow_manager: DummyFlowManager, name: str, age: int): + called["flow_manager"] = flow_manager + called["name"] = name + called["age"] = age + return {"status": "success"}, None + + func = DirectFunctionWrapper(function=my_function) + flow_manager = DummyFlowManager() + args = {"name": "Alice", "age": 30} + + result = asyncio.run(func.invoke(args=args, flow_manager=flow_manager)) + self.assertEqual(result, ({"status": "success"}, None)) + self.assertIs(called["flow_manager"], flow_manager) + self.assertEqual(called["name"], "Alice") + self.assertEqual(called["age"], 30) + + +if __name__ == "__main__": + unittest.main() From ce3ca418c26b469a629c3c4139266431b466d15b Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Tue, 24 Jun 2025 10:26:46 -0400 Subject: [PATCH 07/84] Unit tests for "direct" functions --- tests/test_direct_functions.py | 40 ++++++++++++++-------------------- 1 file changed, 16 insertions(+), 24 deletions(-) diff --git a/tests/test_direct_functions.py b/tests/test_direct_functions.py index 89967fa03..4200d86ac 100644 --- a/tests/test_direct_functions.py +++ b/tests/test_direct_functions.py @@ -10,6 +10,7 @@ from pipecat.services.llm_service import FunctionCallParams # SPDX-License-Identifier: BSD 2-Clause License # + class TestDirectFunction(unittest.TestCase): def test_name_is_set_from_function(self): async def my_function(params: FunctionCallParams): @@ -36,7 +37,6 @@ class TestDirectFunction(unittest.TestCase): """ return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_long_description)) func = DirectFunctionWrapper(function=my_function_long_description) self.assertEqual( func.description, @@ -47,7 +47,6 @@ class TestDirectFunction(unittest.TestCase): async def my_function_no_params(params: FunctionCallParams): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_no_params)) func = DirectFunctionWrapper(function=my_function_no_params) self.assertEqual(func.properties, {}) @@ -56,7 +55,6 @@ class TestDirectFunction(unittest.TestCase): ): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_simple_params)) func = DirectFunctionWrapper(function=my_function_simple_params) self.assertEqual( func.properties, @@ -75,7 +73,6 @@ class TestDirectFunction(unittest.TestCase): ): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_params)) func = DirectFunctionWrapper(function=my_function_complex_params) self.assertEqual( func.properties, @@ -106,7 +103,6 @@ class TestDirectFunction(unittest.TestCase): ): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_type_params)) func = DirectFunctionWrapper(function=my_function_complex_type_params) self.assertEqual( func.properties, @@ -133,7 +129,6 @@ class TestDirectFunction(unittest.TestCase): async def my_function_no_params(params: FunctionCallParams): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_no_params)) func = DirectFunctionWrapper(function=my_function_no_params) self.assertEqual(func.required, []) @@ -142,7 +137,6 @@ class TestDirectFunction(unittest.TestCase): ): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_simple_params)) func = DirectFunctionWrapper(function=my_function_simple_params) self.assertEqual(func.required, ["name", "age"]) @@ -154,7 +148,6 @@ class TestDirectFunction(unittest.TestCase): ): return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function_complex_params)) func = DirectFunctionWrapper(function=my_function_complex_params) self.assertEqual(func.required, ["address_lines"]) @@ -172,7 +165,6 @@ class TestDirectFunction(unittest.TestCase): """ return {"status": "success"}, None - self.assertIsNone(DirectFunctionWrapper.validate_function(my_function)) func = DirectFunctionWrapper(function=my_function) # Validate that the function description is still set correctly even with the longer docstring @@ -195,40 +187,40 @@ class TestDirectFunction(unittest.TestCase): def my_function_non_async(params: FunctionCallParams): return {"status": "success"}, None - with self.assertRaises(InvalidFunctionError): - DirectFunctionWrapper.validate_function(my_function_non_async) + with self.assertRaises(Exception): + DirectFunctionWrapper(function=my_function_non_async) - async def my_function_missing_flow_manager(): + async def my_function_missing_params(): return {"status": "success"}, None - with self.assertRaises(InvalidFunctionError): - DirectFunctionWrapper.validate_function(my_function_missing_flow_manager) + with self.assertRaises(Exception): + DirectFunctionWrapper(my_function_missing_params) - async def my_function_misplaced_flow_manager(foo: str, params: FunctionCallParams): + async def my_function_misplaced_params(foo: str, params: FunctionCallParams): return {"status": "success"}, None - with self.assertRaises(InvalidFunctionError): - DirectFunctionWrapper.validate_function(my_function_misplaced_flow_manager) + with self.assertRaises(Exception): + DirectFunctionWrapper(my_function_misplaced_params) - def test_invoke_calls_function_with_args_and_flow_manager(self): + def test_invoke_calls_function_with_args_and_params_object(self): called = {} - class DummyFlowManager: + class DummyParams: pass - async def my_function(flow_manager: DummyFlowManager, name: str, age: int): - called["flow_manager"] = flow_manager + async def my_function(params: DummyParams, name: str, age: int): + called["params"] = params called["name"] = name called["age"] = age return {"status": "success"}, None func = DirectFunctionWrapper(function=my_function) - flow_manager = DummyFlowManager() + params = DummyParams() args = {"name": "Alice", "age": 30} - result = asyncio.run(func.invoke(args=args, flow_manager=flow_manager)) + result = asyncio.run(func.invoke(args=args, params=params)) self.assertEqual(result, ({"status": "success"}, None)) - self.assertIs(called["flow_manager"], flow_manager) + self.assertIs(called["params"], params) self.assertEqual(called["name"], "Alice") self.assertEqual(called["age"], 30) From e01c20be84bfdb8ea24ce5088a3847e38ff324fa Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Tue, 24 Jun 2025 11:05:52 -0400 Subject: [PATCH 08/84] Remove unused import and tweak a comment --- examples/foundational/14s-function-calling-direct.py | 1 - src/pipecat/adapters/schemas/direct_function.py | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/foundational/14s-function-calling-direct.py b/examples/foundational/14s-function-calling-direct.py index 8c91a369e..7778461f6 100644 --- a/examples/foundational/14s-function-calling-direct.py +++ b/examples/foundational/14s-function-calling-direct.py @@ -10,7 +10,6 @@ import os from dotenv import load_dotenv from loguru import logger -from pipecat.adapters.schemas.function_schema import FunctionSchema from pipecat.adapters.schemas.tools_schema import ToolsSchema from pipecat.audio.vad.silero import SileroVADAnalyzer from pipecat.frames.frames import TTSSpeakFrame diff --git a/src/pipecat/adapters/schemas/direct_function.py b/src/pipecat/adapters/schemas/direct_function.py index 377a8ea3e..54763c3d8 100644 --- a/src/pipecat/adapters/schemas/direct_function.py +++ b/src/pipecat/adapters/schemas/direct_function.py @@ -217,6 +217,7 @@ class DirectFunctionWrapper(BaseDirectFunctionWrapper): Wrapper around a DirectFunction that: - extracts metadata from the function signature and docstring - generates a corresponding FunctionSchema + - helps with function invocation """ @classmethod From a3e540eb322fefd2f0a342cbea83b9320d5b8f82 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Mon, 30 Jun 2025 10:44:55 -0400 Subject: [PATCH 09/84] Rename examples/foundational/14s-function-calling-direct.py to examples/foundational/14t-function-calling-direct.py, since a new "14s" example was added --- ...-function-calling-direct.py => 14t-function-calling-direct.py} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename examples/foundational/{14s-function-calling-direct.py => 14t-function-calling-direct.py} (100%) diff --git a/examples/foundational/14s-function-calling-direct.py b/examples/foundational/14t-function-calling-direct.py similarity index 100% rename from examples/foundational/14s-function-calling-direct.py rename to examples/foundational/14t-function-calling-direct.py From d7a2078e0b4d923d3d68a19db330c2db5ac1940b Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Mon, 30 Jun 2025 10:59:36 -0400 Subject: [PATCH 10/84] Added CHANGELOG entry describing "direct" functions --- CHANGELOG.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d6236f7d..d200d58b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added support for providing "direct" functions, which don't need an + accompanying `FlowsFunctionSchema` or function definition dict. Instead, + metadata (i.e. `name`, `description`, `properties`, and `required`) are + automatically extracted from a combination of the function signature and + docstring. + + Usage: + + ```python + # "Direct" function + # `params` must be the first parameter + async def do_something(params: FunctionCallParams, foo: int, bar: str = ""): + """ + Do something interesting. + + Args: + foo (int): The foo to do something interesting with. + bar (string): The bar to do something interesting with. + """ + + result = await process(foo, bar) + await params.result_callback({"result": result}) + + # ... + + llm.register_direct_function(do_something) + + # ... + + tools = ToolsSchema(standard_tools=[do_something]) + ``` + - Added `watchdog_coroutine()`. This is a watchdog helper for couroutines. So, if you have a coroutine that is waiting for a result and that takes a long time, you will need to wrap it with `watchdog_coroutine()` so the watchdog From b713527da01dd08c8d7cffbeccaecdbf69ff5647 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Mon, 30 Jun 2025 12:53:40 -0700 Subject: [PATCH 11/84] examples: add --esp32 for SDP munging if host name specified --- src/pipecat/examples/run.py | 47 +++++++++++++++++++++++++++++++------ 1 file changed, 40 insertions(+), 7 deletions(-) diff --git a/src/pipecat/examples/run.py b/src/pipecat/examples/run.py index 24f673e06..05b9557fa 100644 --- a/src/pipecat/examples/run.py +++ b/src/pipecat/examples/run.py @@ -8,6 +8,7 @@ import argparse import asyncio import json import os +import re import sys from contextlib import asynccontextmanager from typing import Any, Callable, Dict, Mapping, Optional @@ -61,6 +62,33 @@ async def maybe_capture_participant_screen( ) +def smallwebrtc_sdp_cleanup_ice_candidates(text: str, pattern: str) -> str: + result = [] + lines = text.splitlines() + for line in lines: + if re.search("a=candidate", line): + if re.search(pattern, line) and not re.search("raddr", line): + result.append(line) + else: + result.append(line) + return "\r\n".join(result) + + +def smallwebrtc_sdp_cleanup_fingerprints(text: str) -> str: + result = [] + lines = text.splitlines() + for line in lines: + if not re.search("sha-384", line) and not re.search("sha-512", line): + result.append(line) + return "\r\n".join(result) + + +def smallwebrtc_sdp_munging(sdp: str, host: str) -> str: + sdp = smallwebrtc_sdp_cleanup_fingerprints(sdp) + sdp = smallwebrtc_sdp_cleanup_ice_candidates(sdp, host) + return sdp + + def run_example_daily( run_example: Callable, args: argparse.Namespace, @@ -96,12 +124,6 @@ def run_example_webrtc( # Store connections by pc_id pcs_map: Dict[str, SmallWebRTCConnection] = {} - ice_servers = [ - IceServer( - urls="stun:stun.l.google.com:19302", - ) - ] - # Mount the frontend at / app.mount("/client", SmallWebRTCPrebuiltUI) @@ -122,7 +144,7 @@ def run_example_webrtc( restart_pc=request.get("restart_pc", False), ) else: - pipecat_connection = SmallWebRTCConnection(ice_servers) + pipecat_connection = SmallWebRTCConnection() await pipecat_connection.initialize(sdp=request["sdp"], type=request["type"]) @pipecat_connection.event_handler("closed") @@ -136,6 +158,10 @@ def run_example_webrtc( background_tasks.add_task(run_example, transport, args, False) answer = pipecat_connection.get_answer() + + if args.esp32 and args.host: + answer["sdp"] = smallwebrtc_sdp_munging(answer["sdp"], args.host) + # Updating the peer connection inside the map pcs_map[answer["pc_id"]] = pipecat_connection @@ -254,9 +280,16 @@ def main( parser.add_argument( "--proxy", "-x", help="A public proxy host name (no protocol, e.g. proxy.example.com)" ) + parser.add_argument( + "--esp32", action="store_true", default=False, help="Perform SDP munging for the ESP32" + ) parser.add_argument("--verbose", "-v", action="count", default=0) args = parser.parse_args() + if args.esp32 and args.host == "localhost": + logger.error("For ESP32, you need to specify `--host IP` so we can do SDP munging.") + return + # Log level logger.remove(0) logger.add(sys.stderr, level="TRACE" if args.verbose else "DEBUG") From 5ed2d7ac2bd05ecc398cfaa100f7f64d5de4a688 Mon Sep 17 00:00:00 2001 From: Paul Shippy Date: Mon, 30 Jun 2025 17:31:31 -0700 Subject: [PATCH 12/84] Add session token option for AWS --- src/pipecat/services/aws_nova_sonic/aws.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/pipecat/services/aws_nova_sonic/aws.py b/src/pipecat/services/aws_nova_sonic/aws.py index 77e9575b5..a7832669e 100644 --- a/src/pipecat/services/aws_nova_sonic/aws.py +++ b/src/pipecat/services/aws_nova_sonic/aws.py @@ -194,6 +194,7 @@ class AWSNovaSonicLLMService(LLMService): *, secret_access_key: str, access_key_id: str, + session_token: Optional[str] = None, region: str, model: str = "amazon.nova-sonic-v1:0", voice_id: str = "matthew", # matthew, tiffany, amy @@ -208,6 +209,7 @@ class AWSNovaSonicLLMService(LLMService): Args: secret_access_key: AWS secret access key for authentication. access_key_id: AWS access key ID for authentication. + session_token: AWS session token for authentication. region: AWS region where the service is hosted. model: Model identifier. Defaults to "amazon.nova-sonic-v1:0". voice_id: Voice ID for speech synthesis. Options: matthew, tiffany, amy. @@ -220,6 +222,7 @@ class AWSNovaSonicLLMService(LLMService): super().__init__(**kwargs) self._secret_access_key = secret_access_key self._access_key_id = access_key_id + self._session_token = session_token self._region = region self._model = model self._client: Optional[BedrockRuntimeClient] = None @@ -523,7 +526,9 @@ class AWSNovaSonicLLMService(LLMService): region=self._region, aws_credentials_identity_resolver=StaticCredentialsResolver( credentials=AWSCredentialsIdentity( - access_key_id=self._access_key_id, secret_access_key=self._secret_access_key + access_key_id=self._access_key_id, + secret_access_key=self._secret_access_key, + session_token=self._session_token, ) ), http_auth_scheme_resolver=HTTPAuthSchemeResolver(), From f891140a744f377fb770632bdfb5858018153e18 Mon Sep 17 00:00:00 2001 From: Paul Shippy Date: Mon, 30 Jun 2025 17:35:50 -0700 Subject: [PATCH 13/84] Update sample to take in session token --- examples/foundational/40-aws-nova-sonic.py | 1 + 1 file changed, 1 insertion(+) diff --git a/examples/foundational/40-aws-nova-sonic.py b/examples/foundational/40-aws-nova-sonic.py index ef01f7a47..ecfc4c1fb 100644 --- a/examples/foundational/40-aws-nova-sonic.py +++ b/examples/foundational/40-aws-nova-sonic.py @@ -102,6 +102,7 @@ async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_si secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"), access_key_id=os.getenv("AWS_ACCESS_KEY_ID"), region=os.getenv("AWS_REGION"), # as of 2025-05-06, us-east-1 is the only supported region + session_token=os.getenv("AWS_SESSION_TOKEN"), voice_id="tiffany", # matthew, tiffany, amy # you could choose to pass instruction here rather than via context # system_instruction=system_instruction From 68ea5ee570a40f471fda8918f0aca27c40b95c1f Mon Sep 17 00:00:00 2001 From: Paul Shippy Date: Mon, 30 Jun 2025 17:39:42 -0700 Subject: [PATCH 14/84] Add to change log --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d6236f7d..57c5c9395 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 time, you will need to wrap it with `watchdog_coroutine()` so the watchdog timers are reset regularly. +- Added `session_token` parameter to `AWSNovaSonicLLMService`. + ### Fixed - Fixed a `AWSNovaSonicLLMService` issue introduced in 0.0.72. From fd570b0377e6e1035805d0fae77797f58415666e Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 1 Jul 2025 00:37:04 -0400 Subject: [PATCH 15/84] Update the remaining docstrings, update pre-commit hook, add docstring formatting CI, update CONTRIBUTING with formatting guidance (#2089) --- .github/workflows/format.yaml | 6 +- CONTRIBUTING.md | 49 ++ docs/api/conf.py | 159 ++-- docs/api/index.rst | 63 +- pyproject.toml | 12 + scripts/pre-commit.sh | 28 +- src/pipecat/adapters/base_llm_adapter.py | 37 +- .../adapters/schemas/function_schema.py | 21 +- src/pipecat/adapters/schemas/tools_schema.py | 44 +- .../adapters/services/anthropic_adapter.py | 25 +- .../services/aws_nova_sonic_adapter.py | 26 +- .../adapters/services/bedrock_adapter.py | 25 +- .../adapters/services/gemini_adapter.py | 19 +- .../adapters/services/open_ai_adapter.py | 21 +- .../services/open_ai_realtime_adapter.py | 26 +- .../audio/filters/base_audio_filter.py | 36 +- src/pipecat/audio/filters/koala_filter.py | 39 +- src/pipecat/audio/filters/krisp_filter.py | 65 +- .../audio/filters/noisereduce_filter.py | 37 + .../base_interruption_strategy.py | 30 +- .../min_words_interruption_strategy.py | 25 +- src/pipecat/audio/mixers/base_audio_mixer.py | 37 +- src/pipecat/audio/mixers/soundfile_mixer.py | 59 +- .../audio/resamplers/base_audio_resampler.py | 26 +- .../audio/resamplers/resampy_resampler.py | 27 +- .../audio/resamplers/soxr_resampler.py | 28 +- src/pipecat/audio/turn/base_turn_analyzer.py | 19 + .../audio/turn/smart_turn/base_smart_turn.py | 64 +- .../audio/turn/smart_turn/fal_smart_turn.py | 24 + .../audio/turn/smart_turn/http_smart_turn.py | 23 + .../smart_turn/local_coreml_smart_turn.py | 23 + .../audio/turn/smart_turn/local_smart_turn.py | 20 + src/pipecat/audio/utils.py | 121 +++ src/pipecat/audio/vad/silero.py | 61 ++ src/pipecat/audio/vad/vad_analyzer.py | 88 +++ src/pipecat/clocks/base_clock.py | 19 + src/pipecat/clocks/system_clock.py | 25 + src/pipecat/examples/daily_runner.py | 25 + src/pipecat/examples/run.py | 95 +++ src/pipecat/frames/frames.py | 657 ++++++++++++---- src/pipecat/metrics/metrics.py | 64 +- src/pipecat/observers/base_observer.py | 41 +- .../observers/loggers/debug_log_observer.py | 113 ++- .../observers/loggers/llm_log_observer.py | 9 +- .../loggers/transcription_log_observer.py | 26 +- .../loggers/user_bot_latency_log_observer.py | 19 +- .../observers/turn_tracking_observer.py | 27 +- src/pipecat/pipeline/base_pipeline.py | 17 + src/pipecat/pipeline/base_task.py | 61 +- src/pipecat/pipeline/parallel_pipeline.py | 93 +++ src/pipecat/pipeline/pipeline.py | 78 ++ src/pipecat/pipeline/runner.py | 33 + .../pipeline/sync_parallel_pipeline.py | 89 ++- src/pipecat/pipeline/task.py | 264 ++++--- src/pipecat/pipeline/task_observer.py | 52 +- .../pipeline/to_be_updated/merge_pipeline.py | 34 +- .../processors/aggregators/dtmf_aggregator.py | 1 + .../processors/aggregators/llm_response.py | 4 +- .../aggregators/openai_llm_context.py | 7 +- .../audio/audio_buffer_processor.py | 20 +- .../processors/transcript_processor.py | 25 +- src/pipecat/processors/user_idle_processor.py | 14 +- src/pipecat/serializers/base_serializer.py | 42 + src/pipecat/serializers/exotel.py | 7 +- src/pipecat/serializers/livekit.py | 33 + src/pipecat/serializers/plivo.py | 14 +- src/pipecat/serializers/protobuf.py | 38 +- src/pipecat/serializers/telnyx.py | 14 +- src/pipecat/serializers/twilio.py | 14 +- src/pipecat/services/anthropic/llm.py | 81 +- src/pipecat/services/aws/llm.py | 82 +- src/pipecat/services/aws/utils.py | 13 +- src/pipecat/services/elevenlabs/tts.py | 22 +- src/pipecat/services/google/google.py | 2 + src/pipecat/services/google/llm.py | 128 +++- src/pipecat/services/google/tts.py | 5 +- src/pipecat/services/llm_service.py | 14 +- .../services/openai_realtime_beta/openai.py | 1 + src/pipecat/services/sarvam/tts.py | 5 +- src/pipecat/services/tavus/video.py | 1 + src/pipecat/services/tts_service.py | 10 +- src/pipecat/sync/base_notifier.py | 19 + src/pipecat/sync/event_notifier.py | 24 + src/pipecat/tests/utils.py | 74 +- src/pipecat/transports/base_input.py | 103 ++- src/pipecat/transports/base_output.py | 206 ++++- src/pipecat/transports/base_transport.py | 69 ++ src/pipecat/transports/local/audio.py | 76 ++ src/pipecat/transports/local/tk.py | 84 ++ .../transports/network/fastapi_websocket.py | 172 +++++ .../transports/network/small_webrtc.py | 267 ++++++- .../transports/network/webrtc_connection.py | 156 +++- .../transports/network/websocket_client.py | 169 +++++ .../transports/network/websocket_server.py | 144 +++- src/pipecat/transports/services/daily.py | 718 ++++++++++++++++-- .../transports/services/helpers/daily_rest.py | 228 +++--- src/pipecat/transports/services/livekit.py | 330 ++++++++ src/pipecat/transports/services/tavus.py | 304 +++++++- src/pipecat/utils/asyncio/task_manager.py | 183 +++-- .../utils/asyncio/watchdog_async_iterator.py | 34 +- .../utils/asyncio/watchdog_coroutine.py | 32 +- src/pipecat/utils/asyncio/watchdog_event.py | 24 +- .../utils/asyncio/watchdog_priority_queue.py | 29 +- src/pipecat/utils/asyncio/watchdog_queue.py | 29 +- src/pipecat/utils/base_object.py | 81 ++ src/pipecat/utils/network.py | 2 + src/pipecat/utils/string.py | 50 +- .../utils/text/base_text_aggregator.py | 57 +- src/pipecat/utils/text/base_text_filter.py | 46 ++ .../utils/text/markdown_text_filter.py | 84 +- .../utils/text/pattern_pair_aggregator.py | 32 +- .../utils/text/simple_text_aggregator.py | 45 +- .../utils/text/skip_tags_aggregator.py | 34 +- src/pipecat/utils/time.py | 36 + src/pipecat/utils/tracing/class_decorators.py | 39 +- .../tracing/conversation_context_provider.py | 14 +- .../utils/tracing/service_attributes.py | 139 ++-- .../utils/tracing/service_decorators.py | 47 +- src/pipecat/utils/tracing/setup.py | 20 +- .../utils/tracing/turn_context_provider.py | 14 +- .../utils/tracing/turn_trace_observer.py | 27 + src/pipecat/utils/utils.py | 47 +- 122 files changed, 6858 insertions(+), 1281 deletions(-) diff --git a/.github/workflows/format.yaml b/.github/workflows/format.yaml index 444e24338..7d1219411 100644 --- a/.github/workflows/format.yaml +++ b/.github/workflows/format.yaml @@ -17,7 +17,7 @@ concurrency: jobs: ruff-format: - name: "Formatting checker" + name: "Code quality checks" runs-on: ubuntu-latest steps: - name: Checkout repo @@ -39,8 +39,8 @@ jobs: run: | source .venv/bin/activate ruff format --diff - - name: Ruff import linter + - name: Ruff linter (all rules) id: ruff-check run: | source .venv/bin/activate - ruff check --select I + ruff check diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e0594d64..bee07b8e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -71,6 +71,21 @@ We follow Google-style docstrings with these specific conventions: - Use `Parameters:` section to document each enum value and its meaning - No `__init__` docstring (Enums don't have custom constructors) +**Code Examples in Docstrings:** + +- Use `Examples:` as a section header for multiple examples +- Use descriptive text followed by double colons (`::`) for each example +- **Always include a blank line after the `::"`** +- Indent all code consistently within each block +- Separate multiple examples with blank lines for readability + +**Lists and Bullets in Docstrings:** + +- Use dashes (`-`) for bullet points, not asterisks (`*`) +- **Add a blank line before bullet lists** when they follow a colon +- Use section headers like "Supported features:" or "Behavior:" before lists +- For complex nested information, consider using paragraph format instead + #### Examples: ```python @@ -80,6 +95,12 @@ class MyService(BaseService): Provides detailed explanation of the service's functionality, key features, and usage patterns. + + Supported features: + + - Feature one with detailed explanation + - Feature two with additional context + - Feature three for advanced use cases """ def __init__(self, param1: str, param2: bool = True, **kwargs): @@ -127,6 +148,34 @@ class ConfigParams: port: int = 8080 timeout: float = 30.0 +# Dataclass with code examples +@dataclass +class MessageFrame: + """Frame containing messages in OpenAI format. + + Supports both simple and content list message formats. + + Examples: + Simple format:: + + [ + {"role": "user", "content": "Hello"}, + {"role": "assistant", "content": "Hi there!"} + ] + + Content list format:: + + [ + {"role": "user", "content": [{"type": "text", "text": "Hello"}]}, + {"role": "assistant", "content": [{"type": "text", "text": "Hi there!"}]} + ] + + Parameters: + messages: List of messages in OpenAI format. + """ + + messages: List[dict] + # Enum class class Status(Enum): """Status codes for processing operations. diff --git a/docs/api/conf.py b/docs/api/conf.py index b69c62bbb..31c9fac25 100644 --- a/docs/api/conf.py +++ b/docs/api/conf.py @@ -26,6 +26,10 @@ extensions = [ "sphinx.ext.intersphinx", ] +suppress_warnings = [ + "autodoc.mocked_object", +] + # Napoleon settings napoleon_google_docstring = True napoleon_include_init_with_doc = True @@ -71,7 +75,6 @@ autodoc_mock_imports = [ "langchain", "lmnt", "noisereduce", - "openai", "openpipe", "simli", "soundfile", @@ -81,10 +84,6 @@ autodoc_mock_imports = [ "tkinter", "daily", "daily_python", - "pydantic.BaseModel", - "pydantic.Field", - "pydantic._internal._model_construction", - "pydantic._internal._fields", # Moondream dependencies "torch", "transformers", @@ -167,6 +166,19 @@ autodoc_mock_imports = [ "mcp.client.stdio", "mcp.ClientSession", "mcp.StdioServerParameters", + # gstreamer + "gi", + "gi.require_version", + "gi.repository", + # Protobuf mocks + "pipecat.frames.protobufs.frames_pb2", + "pipecat.serializers.protobuf", + "google.protobuf", + "google.protobuf.descriptor", + "google.protobuf.descriptor_pool", + "google.protobuf.runtime_version", + "google.protobuf.symbol_database", + "google.protobuf.internal.builder", ] # HTML output settings @@ -176,76 +188,32 @@ autodoc_typehints = "signature" # Show type hints in the signature only, not in html_show_sphinx = False -def verify_modules(): - """Verify that required modules are available.""" - required_modules = { - "services": [ - "assemblyai", - "aws", - "cartesia", - "deepgram", - "google", - "lmnt", - "riva", - "simli", - ], - "serializers": ["livekit"], - "vad": ["silero", "vad_analyzer"], - "transports": { - "services": ["daily", "livekit"], - "local": ["audio", "tk"], - "network": ["fastapi_websocket", "websocket_server"], - }, - } +def import_core_modules(): + """Import core pipecat modules for autodoc to discover.""" + core_modules = [ + "pipecat", + "pipecat.frames", + "pipecat.pipeline", + "pipecat.processors", + "pipecat.services", + "pipecat.transports", + "pipecat.audio", + "pipecat.adapters", + "pipecat.clocks", + "pipecat.metrics", + "pipecat.observers", + "pipecat.serializers", + "pipecat.sync", + "pipecat.transcriptions", + "pipecat.utils", + ] - # Skip importing modules that are in autodoc_mock_imports - skipped_modules = set(autodoc_mock_imports) - - missing = [] - for category, modules in required_modules.items(): - if isinstance(modules, dict): - # Handle nested structure - for subcategory, submodules in modules.items(): - for module in submodules: - # Check if module is in autodoc_mock_imports - if ( - f"pipecat.{category}.{subcategory}.{module}" in skipped_modules - or module in skipped_modules - ): - logger.info( - f"Skipping import of mocked module: pipecat.{category}.{subcategory}.{module}" - ) - continue - - try: - __import__(f"pipecat.{category}.{subcategory}.{module}") - logger.info( - f"Successfully imported pipecat.{category}.{subcategory}.{module}" - ) - except (ImportError, TypeError, NameError) as e: - missing.append(f"pipecat.{category}.{subcategory}.{module}") - logger.warning( - f"Optional module not available: pipecat.{category}.{subcategory}.{module} - {str(e)}" - ) - else: - # Handle flat structure - for module in modules: - # Check if module is in autodoc_mock_imports - if f"pipecat.{category}.{module}" in skipped_modules or module in skipped_modules: - logger.info(f"Skipping import of mocked module: pipecat.{category}.{module}") - continue - - try: - __import__(f"pipecat.{category}.{module}") - logger.info(f"Successfully imported pipecat.{category}.{module}") - except (ImportError, TypeError, NameError) as e: - missing.append(f"pipecat.{category}.{module}") - logger.warning( - f"Optional module not available: pipecat.{category}.{module} - {str(e)}" - ) - - if missing: - logger.warning(f"Some optional modules are not available: {missing}") + for module_name in core_modules: + try: + __import__(module_name) + logger.info(f"Successfully imported {module_name}") + except ImportError as e: + logger.warning(f"Failed to import {module_name}: {e}") def clean_title(title: str) -> str: @@ -257,40 +225,7 @@ def clean_title(title: str) -> str: parts = title.split(".") title = parts[-1] - # Special cases for service names and common acronyms - special_cases = { - "ai": "AI", - "aws": "AWS", - "api": "API", - "vad": "VAD", - "assemblyai": "AssemblyAI", - "deepgram": "Deepgram", - "elevenlabs": "ElevenLabs", - "openai": "OpenAI", - "openpipe": "OpenPipe", - "playht": "PlayHT", - "xtts": "XTTS", - "lmnt": "LMNT", - "stt": "STT", - "tts": "TTS", - "llm": "LLM", - "rtvi": "RTVI", - } - - # Check if the entire title is a special case - if title.lower() in special_cases: - return special_cases[title.lower()] - - # Otherwise, capitalize each word - words = title.split("_") - cleaned_words = [] - for word in words: - if word.lower() in special_cases: - cleaned_words.append(special_cases[word.lower()]) - else: - cleaned_words.append(word.capitalize()) - - return " ".join(cleaned_words) + return title def setup(app): @@ -315,9 +250,8 @@ def setup(app): excludes = [ str(project_root / "src/pipecat/pipeline/to_be_updated"), - str(project_root / "src/pipecat/processors/gstreamer"), - str(project_root / "src/pipecat/services/to_be_updated"), - str(project_root / "src/pipecat/vad"), # deprecated + str(project_root / "src/pipecat/examples"), + str(project_root / "src/pipecat/tests"), "**/test_*.py", "**/tests/*.py", ] @@ -358,5 +292,4 @@ def setup(app): logger.error(f"Error generating API documentation: {e}", exc_info=True) -# Run module verification -verify_modules() +import_core_modules() diff --git a/docs/api/index.rst b/docs/api/index.rst index 199aed1dd..344cf3ec6 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,57 +1,17 @@ -Pipecat API Reference Docs -========================== +Pipecat API Reference +===================== -Welcome to Pipecat's API reference documentation! +Welcome to the Pipecat API reference. -Pipecat is an open source framework for building voice and multimodal assistants. -It provides a flexible pipeline architecture for connecting various AI services, -audio processing, and transport layers. +Use the navigation on the left to browse modules, or search using the search box. + +**New to Pipecat?** Check out the `main documentation `_ for tutorials, guides, and client SDK information. Quick Links ----------- * `GitHub Repository `_ -* `Website `_ - -API Reference -------------- - -Core Components -~~~~~~~~~~~~~~~ - -* :mod:`Frames ` -* :mod:`Processors ` -* :mod:`Pipeline ` - -Audio Processing -~~~~~~~~~~~~~~~~ - -* :mod:`Audio ` - -Services -~~~~~~~~ - -* :mod:`Services ` - -Transport & Serialization -~~~~~~~~~~~~~~~~~~~~~~~~~ - -* :mod:`Transports ` - * :mod:`Local ` - * :mod:`Network ` - * :mod:`Services ` -* :mod:`Serializers ` - -Utilities -~~~~~~~~~ - -* :mod:`Adapters ` -* :mod:`Clocks ` -* :mod:`Metrics ` -* :mod:`Observers ` -* :mod:`Sync ` -* :mod:`Transcriptions ` -* :mod:`Utils ` +* `Join our Community `_ .. toctree:: :maxdepth: 3 @@ -71,11 +31,4 @@ Utilities Sync Transcriptions Transports - Utils - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` \ No newline at end of file + Utils \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index f402ddfd1..9dfd84ec6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -123,9 +123,21 @@ select = [ "D", # Docstring rules "I", # Import rules ] +ignore = [ + "D105", # Missing docstring in magic methods (__str__, __repr__, etc.) +] [tool.ruff.lint.per-file-ignores] +# Skip docstring checks for non-source code +"examples/**/*.py" = ["D"] +"tests/**/*.py" = ["D"] +"scripts/**/*.py" = ["D"] +"docs/**/*.py" = ["D"] +# Skip D104 (missing docstring in public package) for __init__.py files "**/__init__.py" = ["D104"] +# Skip specific rules for generated protobuf files +"**/*_pb2.py" = ["D"] +"src/pipecat/services/__init__.py" = ["D"] [tool.ruff.lint.pydocstyle] convention = "google" diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh index 22f00313d..1341a8575 100755 --- a/scripts/pre-commit.sh +++ b/scripts/pre-commit.sh @@ -1,3 +1,27 @@ -#!/bin/sh +#!/bin/bash -NO_COLOR=1 ruff format --diff +# Color codes for output +RED='\033[0;31m' +GREEN='\033[0;32m' +NC='\033[0m' # No Color + +echo "🔍 Running pre-commit checks..." + +# Change to project root (one level up from scripts/) +cd "$(dirname "$0")/.." + +# Format check +echo "📝 Checking code formatting..." +if ! NO_COLOR=1 ruff format --diff --check; then + echo -e "${RED}❌ Code formatting issues found. Run 'ruff format' to fix.${NC}" + exit 1 +fi + +# Lint check +echo "🔍 Running linter..." +if ! ruff check; then + echo -e "${RED}❌ Linting issues found.${NC}" + exit 1 +fi + +echo -e "${GREEN}✅ All pre-commit checks passed!${NC}" \ No newline at end of file diff --git a/src/pipecat/adapters/base_llm_adapter.py b/src/pipecat/adapters/base_llm_adapter.py index c26722604..6a957c267 100644 --- a/src/pipecat/adapters/base_llm_adapter.py +++ b/src/pipecat/adapters/base_llm_adapter.py @@ -1,3 +1,15 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Base adapter for LLM provider integration. + +This module provides the abstract base class for implementing LLM provider-specific +adapters that handle tool format conversion and standardization. +""" + from abc import ABC, abstractmethod from typing import Any, List, Union, cast @@ -7,12 +19,35 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class BaseLLMAdapter(ABC): + """Abstract base class for LLM provider adapters. + + Provides a standard interface for converting between Pipecat's standardized + tool schemas and provider-specific tool formats. Subclasses must implement + provider-specific conversion logic. + """ + @abstractmethod def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Any]: - """Converts tools to the provider's format.""" + """Convert tools schema to the provider's specific format. + + Args: + tools_schema: The standardized tools schema to convert. + + Returns: + List of tools in the provider's expected format. + """ pass def from_standard_tools(self, tools: Any) -> List[Any]: + """Convert tools from standard format to provider format. + + Args: + tools: Tools in standard format or provider-specific format. + + Returns: + List of tools converted to provider format, or original tools + if not in standard format. + """ if isinstance(tools, ToolsSchema): logger.debug(f"Retrieving the tools using the adapter: {type(self)}") return self.to_provider_tools_format(tools) diff --git a/src/pipecat/adapters/schemas/function_schema.py b/src/pipecat/adapters/schemas/function_schema.py index 55a070cf9..2b8753e58 100644 --- a/src/pipecat/adapters/schemas/function_schema.py +++ b/src/pipecat/adapters/schemas/function_schema.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Function schema utilities for AI tool definitions. + +This module provides standardized function schema representation for defining +tools and functions used with AI models, ensuring consistent formatting +across different AI service providers. +""" + from typing import Any, Dict, List @@ -13,17 +20,19 @@ class FunctionSchema: Provides a structured way to define function tools used with AI models like OpenAI. This schema defines the function's name, description, parameter properties, and required parameters, following specifications required by AI service providers. - - Args: - name: Name of the function to be called. - description: Description of what the function does. - properties: Dictionary defining parameter types, descriptions, and constraints. - required: List of property names that are required parameters. """ def __init__( self, name: str, description: str, properties: Dict[str, Any], required: List[str] ) -> None: + """Initialize the function schema. + + Args: + name: Name of the function to be called. + description: Description of what the function does. + properties: Dictionary defining parameter types, descriptions, and constraints. + required: List of property names that are required parameters. + """ self._name = name self._description = description self._properties = properties diff --git a/src/pipecat/adapters/schemas/tools_schema.py b/src/pipecat/adapters/schemas/tools_schema.py index 2489e0b4d..7ef582f7e 100644 --- a/src/pipecat/adapters/schemas/tools_schema.py +++ b/src/pipecat/adapters/schemas/tools_schema.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Tools schema definitions for function calling adapters. + +This module provides schemas for managing both standardized function tools +and custom adapter-specific tools in the Pipecat framework. +""" + from enum import Enum from typing import Any, Dict, List, Optional @@ -11,33 +17,61 @@ from pipecat.adapters.schemas.function_schema import FunctionSchema class AdapterType(Enum): + """Supported adapter types for custom tools. + + Parameters: + GEMINI: Google Gemini adapter - currently the only service supporting custom tools. + """ + GEMINI = "gemini" # that is the only service where we are able to add custom tools for now class ToolsSchema: + """Schema for managing both standard and custom function calling tools. + + This class provides a unified interface for handling standardized function + schemas alongside custom tools that may not follow the standard format, + such as adapter-specific search tools. + """ + def __init__( self, standard_tools: List[FunctionSchema], custom_tools: Optional[Dict[AdapterType, List[Dict[str, Any]]]] = None, ) -> None: - """ - A schema for tools that includes both standardized function schemas - and custom tools that do not follow the FunctionSchema format. + """Initialize the tools schema. - :param standard_tools: List of tools following FunctionSchema. - :param custom_tools: List of tools in a custom format (e.g., search_tool). + Args: + standard_tools: List of tools following the standardized FunctionSchema format. + custom_tools: Dictionary mapping adapter types to their custom tool definitions. + These tools may not follow the FunctionSchema format (e.g., search_tool). """ self._standard_tools = standard_tools self._custom_tools = custom_tools @property def standard_tools(self) -> List[FunctionSchema]: + """Get the list of standard function schema tools. + + Returns: + List of tools following the FunctionSchema format. + """ return self._standard_tools @property def custom_tools(self) -> Dict[AdapterType, List[Dict[str, Any]]]: + """Get the custom tools dictionary. + + Returns: + Dictionary mapping adapter types to their custom tool definitions. + """ return self._custom_tools @custom_tools.setter def custom_tools(self, value: Dict[AdapterType, List[Dict[str, Any]]]) -> None: + """Set the custom tools dictionary. + + Args: + value: Dictionary mapping adapter types to their custom tool definitions. + """ self._custom_tools = value diff --git a/src/pipecat/adapters/services/anthropic_adapter.py b/src/pipecat/adapters/services/anthropic_adapter.py index 23197d3a8..fb5abe108 100644 --- a/src/pipecat/adapters/services/anthropic_adapter.py +++ b/src/pipecat/adapters/services/anthropic_adapter.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Anthropic LLM adapter for Pipecat.""" + from typing import Any, Dict, List from pipecat.adapters.base_llm_adapter import BaseLLMAdapter @@ -12,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class AnthropicLLMAdapter(BaseLLMAdapter): + """Adapter for converting tool schemas to Anthropic's function-calling format. + + This adapter handles the conversion of Pipecat's standard function schemas + to the specific format required by Anthropic's Claude models for function calling. + """ + @staticmethod def _to_anthropic_function_format(function: FunctionSchema) -> Dict[str, Any]: + """Convert a single function schema to Anthropic's format. + + Args: + function: The function schema to convert. + + Returns: + Dictionary containing the function definition in Anthropic's format. + """ return { "name": function.name, "description": function.description, @@ -25,10 +41,13 @@ class AnthropicLLMAdapter(BaseLLMAdapter): } def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]: - """Converts function schemas to Anthropic's function-calling format. + """Convert function schemas to Anthropic's function-calling format. - :return: Anthropic formatted function call definition. + Args: + tools_schema: The tools schema containing functions to convert. + + Returns: + List of function definitions formatted for Anthropic's API. """ - functions_schema = tools_schema.standard_tools return [self._to_anthropic_function_format(func) for func in functions_schema] diff --git a/src/pipecat/adapters/services/aws_nova_sonic_adapter.py b/src/pipecat/adapters/services/aws_nova_sonic_adapter.py index dc7eef92d..2875f8272 100644 --- a/src/pipecat/adapters/services/aws_nova_sonic_adapter.py +++ b/src/pipecat/adapters/services/aws_nova_sonic_adapter.py @@ -3,6 +3,9 @@ # # SPDX-License-Identifier: BSD 2-Clause License # + +"""AWS Nova Sonic LLM adapter for Pipecat.""" + import json from typing import Any, Dict, List @@ -12,8 +15,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class AWSNovaSonicLLMAdapter(BaseLLMAdapter): + """Adapter for AWS Nova Sonic language models. + + Converts Pipecat's standard function schemas into AWS Nova Sonic's + specific function-calling format, enabling tool use with Nova Sonic models. + """ + @staticmethod def _to_aws_nova_sonic_function_format(function: FunctionSchema) -> Dict[str, Any]: + """Convert a function schema to AWS Nova Sonic format. + + Args: + function: The function schema to convert. + + Returns: + Dictionary in AWS Nova Sonic function format with toolSpec structure. + """ return { "toolSpec": { "name": function.name, @@ -31,10 +48,13 @@ class AWSNovaSonicLLMAdapter(BaseLLMAdapter): } def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]: - """Converts function schemas to AWS Nova Sonic function-calling format. + """Convert tools schema to AWS Nova Sonic function-calling format. - :return: AWS Nova Sonic formatted function call definition. + Args: + tools_schema: The tools schema containing function definitions to convert. + + Returns: + List of dictionaries in AWS Nova Sonic function format. """ - functions_schema = tools_schema.standard_tools return [self._to_aws_nova_sonic_function_format(func) for func in functions_schema] diff --git a/src/pipecat/adapters/services/bedrock_adapter.py b/src/pipecat/adapters/services/bedrock_adapter.py index 113a6938d..364ad87d2 100644 --- a/src/pipecat/adapters/services/bedrock_adapter.py +++ b/src/pipecat/adapters/services/bedrock_adapter.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""AWS Bedrock LLM adapter for Pipecat.""" + from typing import Any, Dict, List from pipecat.adapters.base_llm_adapter import BaseLLMAdapter @@ -12,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class AWSBedrockLLMAdapter(BaseLLMAdapter): + """Adapter for AWS Bedrock LLM integration with Pipecat. + + Provides conversion utilities for transforming Pipecat function schemas + into AWS Bedrock's expected tool format for function calling capabilities. + """ + @staticmethod def _to_bedrock_function_format(function: FunctionSchema) -> Dict[str, Any]: + """Convert a function schema to Bedrock's tool format. + + Args: + function: The function schema to convert. + + Returns: + Dictionary formatted for Bedrock's tool specification. + """ return { "toolSpec": { "name": function.name, @@ -29,10 +45,13 @@ class AWSBedrockLLMAdapter(BaseLLMAdapter): } def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]: - """Converts function schemas to Bedrock's function-calling format. + """Convert function schemas to Bedrock's function-calling format. - :return: Bedrock formatted function call definition. + Args: + tools_schema: The tools schema containing functions to convert. + + Returns: + List of Bedrock formatted function call definitions. """ - functions_schema = tools_schema.standard_tools return [self._to_bedrock_function_format(func) for func in functions_schema] diff --git a/src/pipecat/adapters/services/gemini_adapter.py b/src/pipecat/adapters/services/gemini_adapter.py index 8efca5189..2139e0057 100644 --- a/src/pipecat/adapters/services/gemini_adapter.py +++ b/src/pipecat/adapters/services/gemini_adapter.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Gemini LLM adapter for Pipecat.""" + from typing import Any, Dict, List, Union from pipecat.adapters.base_llm_adapter import BaseLLMAdapter @@ -11,12 +13,23 @@ from pipecat.adapters.schemas.tools_schema import AdapterType, ToolsSchema class GeminiLLMAdapter(BaseLLMAdapter): + """LLM adapter for Google's Gemini service. + + Provides tool schema conversion functionality to transform standard tool + definitions into Gemini's specific function-calling format for use with + Gemini LLM models. + """ + def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]: - """Converts function schemas to Gemini's function-calling format. + """Convert tool schemas to Gemini's function-calling format. - :return: Gemini formatted function call definition. + Args: + tools_schema: The tools schema containing standard and custom tool definitions. + + Returns: + List of tool definitions formatted for Gemini's function-calling API. + Includes both converted standard tools and any custom Gemini-specific tools. """ - functions_schema = tools_schema.standard_tools formatted_standard_tools = [ {"function_declarations": [func.to_default_dict() for func in functions_schema]} diff --git a/src/pipecat/adapters/services/open_ai_adapter.py b/src/pipecat/adapters/services/open_ai_adapter.py index 909e5103a..59d70aa1e 100644 --- a/src/pipecat/adapters/services/open_ai_adapter.py +++ b/src/pipecat/adapters/services/open_ai_adapter.py @@ -3,6 +3,9 @@ # # SPDX-License-Identifier: BSD 2-Clause License # + +"""OpenAI LLM adapter for Pipecat.""" + from typing import List from openai.types.chat import ChatCompletionToolParam @@ -12,10 +15,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class OpenAILLMAdapter(BaseLLMAdapter): - def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[ChatCompletionToolParam]: - """Converts function schemas to OpenAI's function-calling format. + """Adapter for converting tool schemas to OpenAI's format. - :return: OpenAI formatted function call definition. + Provides conversion utilities for transforming Pipecat's standard tool + schemas into the format expected by OpenAI's ChatCompletion API for + function calling capabilities. + """ + + def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[ChatCompletionToolParam]: + """Convert function schemas to OpenAI's function-calling format. + + Args: + tools_schema: The Pipecat tools schema to convert. + + Returns: + List of OpenAI formatted function call definitions ready for use + with ChatCompletion API. """ functions_schema = tools_schema.standard_tools return [ diff --git a/src/pipecat/adapters/services/open_ai_realtime_adapter.py b/src/pipecat/adapters/services/open_ai_realtime_adapter.py index b7eafaa81..58aea5a9a 100644 --- a/src/pipecat/adapters/services/open_ai_realtime_adapter.py +++ b/src/pipecat/adapters/services/open_ai_realtime_adapter.py @@ -3,6 +3,9 @@ # # SPDX-License-Identifier: BSD 2-Clause License # + +"""OpenAI Realtime LLM adapter for Pipecat.""" + from typing import Any, Dict, List, Union from pipecat.adapters.base_llm_adapter import BaseLLMAdapter @@ -11,8 +14,22 @@ from pipecat.adapters.schemas.tools_schema import ToolsSchema class OpenAIRealtimeLLMAdapter(BaseLLMAdapter): + """LLM adapter for OpenAI Realtime API function calling. + + Converts Pipecat's tool schemas into the specific format required by + OpenAI's Realtime API for function calling capabilities. + """ + @staticmethod def _to_openai_realtime_function_format(function: FunctionSchema) -> Dict[str, Any]: + """Convert a function schema to OpenAI Realtime format. + + Args: + function: The function schema to convert. + + Returns: + Dictionary in OpenAI Realtime function format. + """ return { "type": "function", "name": function.name, @@ -25,10 +42,13 @@ class OpenAIRealtimeLLMAdapter(BaseLLMAdapter): } def to_provider_tools_format(self, tools_schema: ToolsSchema) -> List[Dict[str, Any]]: - """Converts function schemas to Openai Realtime function-calling format. + """Convert tool schemas to OpenAI Realtime function-calling format. - :return: Openai Realtime formatted function call definition. + Args: + tools_schema: The tools schema containing functions to convert. + + Returns: + List of function definitions in OpenAI Realtime format. """ - functions_schema = tools_schema.standard_tools return [self._to_openai_realtime_function_format(func) for func in functions_schema] diff --git a/src/pipecat/audio/filters/base_audio_filter.py b/src/pipecat/audio/filters/base_audio_filter.py index c956ffe16..1724fd859 100644 --- a/src/pipecat/audio/filters/base_audio_filter.py +++ b/src/pipecat/audio/filters/base_audio_filter.py @@ -4,44 +4,68 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base audio filter interface for input transport audio processing. + +This module provides the abstract base class for implementing audio filters +that process audio data before VAD and downstream processing in input transports. +""" + from abc import ABC, abstractmethod from pipecat.frames.frames import FilterControlFrame class BaseAudioFilter(ABC): - """This is a base class for input transport audio filters. If an audio + """Base class for input transport audio filters. + + This is a base class for input transport audio filters. If an audio filter is provided to the input transport it will be used to process audio before VAD and before pushing it downstream. There are control frames to update filter settings or to enable or disable the filter at runtime. - """ @abstractmethod async def start(self, sample_rate: int): - """This will be called from the input transport when the transport is + """Initialize the filter when the input transport starts. + + This will be called from the input transport when the transport is started. It can be used to initialize the filter. The input transport sample rate is provided so the filter can adjust to that sample rate. + Args: + sample_rate: The sample rate of the input transport in Hz. """ pass @abstractmethod async def stop(self): - """This will be called from the input transport when the transport is - stopping. + """Clean up the filter when the input transport stops. + This will be called from the input transport when the transport is + stopping. """ pass @abstractmethod async def process_frame(self, frame: FilterControlFrame): - """This will be called when the input transport receives a + """Process control frames for runtime filter configuration. + + This will be called when the input transport receives a FilterControlFrame. + Args: + frame: The control frame containing filter commands or settings. """ pass @abstractmethod async def filter(self, audio: bytes) -> bytes: + """Apply the audio filter to the provided audio data. + + Args: + audio: Raw audio data as bytes to be filtered. + + Returns: + Filtered audio data as bytes. + """ pass diff --git a/src/pipecat/audio/filters/koala_filter.py b/src/pipecat/audio/filters/koala_filter.py index c1e539e37..64314428a 100644 --- a/src/pipecat/audio/filters/koala_filter.py +++ b/src/pipecat/audio/filters/koala_filter.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Koala noise suppression audio filter for Pipecat. + +This module provides an audio filter implementation using PicoVoice's Koala +Noise Suppression engine to reduce background noise in audio streams. +""" + from typing import Sequence import numpy as np @@ -21,12 +27,19 @@ except ModuleNotFoundError as e: class KoalaFilter(BaseAudioFilter): - """This is an audio filter that uses Koala Noise Suppression (from - PicoVoice). + """Audio filter using Koala Noise Suppression from PicoVoice. + Provides real-time noise suppression for audio streams using PicoVoice's + Koala engine. The filter buffers audio data to match Koala's required + frame length and processes it in chunks. """ def __init__(self, *, access_key: str) -> None: + """Initialize the Koala noise suppression filter. + + Args: + access_key: PicoVoice access key for Koala engine authentication. + """ self._access_key = access_key self._filtering = True @@ -36,6 +49,11 @@ class KoalaFilter(BaseAudioFilter): self._audio_buffer = bytearray() async def start(self, sample_rate: int): + """Initialize the filter with the transport's sample rate. + + Args: + sample_rate: The sample rate of the input transport in Hz. + """ self._sample_rate = sample_rate if self._sample_rate != self._koala.sample_rate: logger.warning( @@ -44,13 +62,30 @@ class KoalaFilter(BaseAudioFilter): self._koala_ready = False async def stop(self): + """Clean up the Koala engine when stopping.""" self._koala.reset() async def process_frame(self, frame: FilterControlFrame): + """Process control frames to enable/disable filtering. + + Args: + frame: The control frame containing filter commands. + """ if isinstance(frame, FilterEnableFrame): self._filtering = frame.enable async def filter(self, audio: bytes) -> bytes: + """Apply Koala noise suppression to audio data. + + Buffers incoming audio and processes it in chunks that match Koala's + required frame length. Returns filtered audio data. + + Args: + audio: Raw audio data as bytes to be filtered. + + Returns: + Noise-suppressed audio data as bytes. + """ if not self._koala_ready or not self._filtering: return audio diff --git a/src/pipecat/audio/filters/krisp_filter.py b/src/pipecat/audio/filters/krisp_filter.py index b23a46b65..267d2f2ea 100644 --- a/src/pipecat/audio/filters/krisp_filter.py +++ b/src/pipecat/audio/filters/krisp_filter.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Krisp noise reduction audio filter for Pipecat. + +This module provides an audio filter implementation using Krisp's noise +reduction technology to suppress background noise in audio streams. +""" + import os import numpy as np @@ -21,14 +27,27 @@ except ModuleNotFoundError as e: class KrispProcessorManager: - """ - Ensures that only one KrispAudioProcessor instance exists for the entire program. + """Singleton manager for KrispAudioProcessor instances. + + Ensures that only one KrispAudioProcessor instance exists for the entire + program. """ _krisp_instance = None @classmethod def get_processor(cls, sample_rate: int, sample_type: str, channels: int, model_path: str): + """Get or create a KrispAudioProcessor instance. + + Args: + sample_rate: Audio sample rate in Hz. + sample_type: Audio sample type (e.g., "PCM_16"). + channels: Number of audio channels. + model_path: Path to the Krisp model file. + + Returns: + Shared KrispAudioProcessor instance. + """ if cls._krisp_instance is None: cls._krisp_instance = KrispAudioProcessor( sample_rate, sample_type, channels, model_path @@ -37,14 +56,26 @@ class KrispProcessorManager: class KrispFilter(BaseAudioFilter): + """Audio filter using Krisp noise reduction technology. + + Provides real-time noise reduction for audio streams using Krisp's + proprietary noise suppression algorithms. Requires a Krisp model file + for operation. + """ + def __init__( self, sample_type: str = "PCM_16", channels: int = 1, model_path: str = None ) -> None: - """Initializes the KrispAudioProcessor with customizable audio processing settings. + """Initialize the Krisp noise reduction filter. - :param sample_type: The type of audio sample, default is 'PCM_16'. - :param channels: Number of audio channels, default is 1. - :param model_path: Path to the Krisp model; defaults to environment variable KRISP_MODEL_PATH if not provided. + Args: + sample_type: The audio sample format. Defaults to "PCM_16". + channels: Number of audio channels. Defaults to 1. + model_path: Path to the Krisp model file. If None, uses KRISP_MODEL_PATH + environment variable. + + Raises: + ValueError: If model_path is not provided and KRISP_MODEL_PATH is not set. """ super().__init__() @@ -63,19 +94,41 @@ class KrispFilter(BaseAudioFilter): self._krisp_processor = None async def start(self, sample_rate: int): + """Initialize the Krisp processor with the transport's sample rate. + + Args: + sample_rate: The sample rate of the input transport in Hz. + """ self._sample_rate = sample_rate self._krisp_processor = KrispProcessorManager.get_processor( self._sample_rate, self._sample_type, self._channels, self._model_path ) async def stop(self): + """Clean up the Krisp processor when stopping.""" self._krisp_processor = None async def process_frame(self, frame: FilterControlFrame): + """Process control frames to enable/disable filtering. + + Args: + frame: The control frame containing filter commands. + """ if isinstance(frame, FilterEnableFrame): self._filtering = frame.enable async def filter(self, audio: bytes) -> bytes: + """Apply Krisp noise reduction to audio data. + + Converts audio to float32, applies Krisp noise reduction processing, + and returns the filtered audio clipped to int16 range. + + Args: + audio: Raw audio data as bytes to be filtered. + + Returns: + Noise-reduced audio data as bytes. + """ if not self._filtering: return audio diff --git a/src/pipecat/audio/filters/noisereduce_filter.py b/src/pipecat/audio/filters/noisereduce_filter.py index 7a4b18395..550153b56 100644 --- a/src/pipecat/audio/filters/noisereduce_filter.py +++ b/src/pipecat/audio/filters/noisereduce_filter.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Noisereduce audio filter for Pipecat. + +This module provides an audio filter implementation using the noisereduce +library to reduce background noise in audio streams through spectral +gating algorithms. +""" + import numpy as np from loguru import logger @@ -21,21 +28,51 @@ except ModuleNotFoundError as e: class NoisereduceFilter(BaseAudioFilter): + """Audio filter using the noisereduce library for noise suppression. + + Applies spectral gating noise reduction algorithms to suppress background + noise in audio streams. Uses the noisereduce library's default noise + reduction parameters. + """ + def __init__(self) -> None: + """Initialize the noisereduce filter.""" self._filtering = True self._sample_rate = 0 async def start(self, sample_rate: int): + """Initialize the filter with the transport's sample rate. + + Args: + sample_rate: The sample rate of the input transport in Hz. + """ self._sample_rate = sample_rate async def stop(self): + """Clean up the filter when stopping.""" pass async def process_frame(self, frame: FilterControlFrame): + """Process control frames to enable/disable filtering. + + Args: + frame: The control frame containing filter commands. + """ if isinstance(frame, FilterEnableFrame): self._filtering = frame.enable async def filter(self, audio: bytes) -> bytes: + """Apply noise reduction to audio data using spectral gating. + + Converts audio to float32, applies noisereduce processing, and returns + the filtered audio clipped to int16 range. + + Args: + audio: Raw audio data as bytes to be filtered. + + Returns: + Noise-reduced audio data as bytes. + """ if not self._filtering: return audio diff --git a/src/pipecat/audio/interruptions/base_interruption_strategy.py b/src/pipecat/audio/interruptions/base_interruption_strategy.py index 7811e8418..83b2ff280 100644 --- a/src/pipecat/audio/interruptions/base_interruption_strategy.py +++ b/src/pipecat/audio/interruptions/base_interruption_strategy.py @@ -4,31 +4,51 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base interruption strategy for determining when users can interrupt bot speech.""" + from abc import ABC, abstractmethod class BaseInterruptionStrategy(ABC): - """This is a base class for interruption strategies. Interruption strategies + """Base class for interruption strategies. + + This is a base class for interruption strategies. Interruption strategies decide when the user can interrupt the bot while the bot is speaking. For example, there could be strategies based on audio volume or strategies based on the number of words the user spoke. - """ async def append_audio(self, audio: bytes, sample_rate: int): - """Appends audio to the strategy. Not all strategies handle audio.""" + """Append audio data to the strategy for analysis. + + Not all strategies handle audio. Default implementation does nothing. + + Args: + audio: Raw audio bytes to append. + sample_rate: Sample rate of the audio data in Hz. + """ pass async def append_text(self, text: str): - """Appends text to the strategy. Not all strategies handle text.""" + """Append text data to the strategy for analysis. + + Not all strategies handle text. Default implementation does nothing. + + Args: + text: Text string to append for analysis. + """ pass @abstractmethod async def should_interrupt(self) -> bool: - """This is called when the user stops speaking and it's time to decide + """Determine if the user should interrupt the bot. + + This is called when the user stops speaking and it's time to decide whether the user should interrupt the bot. The decision will be based on the aggregated audio and/or text. + Returns: + True if the user should interrupt the bot, False otherwise. """ pass diff --git a/src/pipecat/audio/interruptions/min_words_interruption_strategy.py b/src/pipecat/audio/interruptions/min_words_interruption_strategy.py index f9f7595ab..3f2dd5825 100644 --- a/src/pipecat/audio/interruptions/min_words_interruption_strategy.py +++ b/src/pipecat/audio/interruptions/min_words_interruption_strategy.py @@ -4,31 +4,47 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Minimum words interruption strategy for word count-based interruptions.""" + from loguru import logger from pipecat.audio.interruptions.base_interruption_strategy import BaseInterruptionStrategy class MinWordsInterruptionStrategy(BaseInterruptionStrategy): - """This is an interruption strategy based on a minimum number of words said + """Interruption strategy based on minimum number of words spoken. + + This is an interruption strategy based on a minimum number of words said by the user. That is, the strategy will be true if the user has said at least that amount of words. - """ def __init__(self, *, min_words: int): + """Initialize the minimum words interruption strategy. + + Args: + min_words: Minimum number of words required to trigger an interruption. + """ super().__init__() self._min_words = min_words self._text = "" async def append_text(self, text: str): - """Appends text for later analysis. Not all strategies need to handle - text. + """Append text for word count analysis. + Args: + text: Text string to append to the accumulated text. + + Note: Not all strategies need to handle text. """ self._text += text async def should_interrupt(self) -> bool: + """Check if the minimum word count has been reached. + + Returns: + True if the user has spoken at least the minimum number of words. + """ word_count = len(self._text.split()) interrupt = word_count >= self._min_words logger.debug( @@ -37,4 +53,5 @@ class MinWordsInterruptionStrategy(BaseInterruptionStrategy): return interrupt async def reset(self): + """Reset the accumulated text for the next analysis cycle.""" self._text = "" diff --git a/src/pipecat/audio/mixers/base_audio_mixer.py b/src/pipecat/audio/mixers/base_audio_mixer.py index 9b7b12163..4ba5938d2 100644 --- a/src/pipecat/audio/mixers/base_audio_mixer.py +++ b/src/pipecat/audio/mixers/base_audio_mixer.py @@ -4,50 +4,73 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base audio mixer for output transport integration. + +Provides the abstract base class for audio mixers that can be integrated with +output transports to mix incoming audio with generated audio from the mixer. +""" + from abc import ABC, abstractmethod from pipecat.frames.frames import MixerControlFrame class BaseAudioMixer(ABC): - """This is a base class for output transport audio mixers. If an audio mixer + """Base class for output transport audio mixers. + + This is a base class for output transport audio mixers. If an audio mixer is provided to the output transport it will be used to mix the audio frames coming into to the transport with the audio generated from the mixer. There are control frames to update mixer settings or to enable or disable the mixer at runtime. - """ @abstractmethod async def start(self, sample_rate: int): - """This will be called from the output transport when the transport is + """Initialize the mixer when the output transport starts. + + This will be called from the output transport when the transport is started. It can be used to initialize the mixer. The output transport sample rate is provided so the mixer can adjust to that sample rate. + Args: + sample_rate: The sample rate of the output transport in Hz. """ pass @abstractmethod async def stop(self): - """This will be called from the output transport when the transport is - stopping. + """Clean up the mixer when the output transport stops. + This will be called from the output transport when the transport is + stopping. """ pass @abstractmethod async def process_frame(self, frame: MixerControlFrame): - """This will be called when the output transport receives a + """Process mixer control frames from the transport. + + This will be called when the output transport receives a MixerControlFrame. + Args: + frame: The mixer control frame to process. """ pass @abstractmethod async def mix(self, audio: bytes) -> bytes: - """This is called with the audio that is about to be sent from the + """Mix transport audio with mixer-generated audio. + + This is called with the audio that is about to be sent from the output transport and that should be mixed with the mixer audio if the mixer is enabled. + Args: + audio: Raw audio bytes from the transport to mix. + + Returns: + Mixed audio bytes combining transport and mixer audio. """ pass diff --git a/src/pipecat/audio/mixers/soundfile_mixer.py b/src/pipecat/audio/mixers/soundfile_mixer.py index 1628c4d8a..c3664012c 100644 --- a/src/pipecat/audio/mixers/soundfile_mixer.py +++ b/src/pipecat/audio/mixers/soundfile_mixer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Soundfile-based audio mixer for file playback integration. + +Provides an audio mixer that combines incoming audio with audio loaded from +files using the soundfile library. Supports multiple audio formats and +runtime configuration changes. +""" + import asyncio from typing import Any, Dict, Mapping @@ -24,7 +31,9 @@ except ModuleNotFoundError as e: class SoundfileMixer(BaseAudioMixer): - """This is an audio mixer that mixes incoming audio with audio from a + """Audio mixer that combines incoming audio with file-based audio. + + This is an audio mixer that mixes incoming audio with audio from a file. It uses the soundfile library to load files so it supports multiple formats. The audio files need to only have one channel (mono) and it needs to match the sample rate of the output transport. @@ -33,7 +42,6 @@ class SoundfileMixer(BaseAudioMixer): `MixerUpdateSettingsFrame` has the following settings available: `sound` (str) and `volume` (float) to be able to update to a different sound file or to change the volume at runtime. - """ def __init__( @@ -46,6 +54,16 @@ class SoundfileMixer(BaseAudioMixer): loop: bool = True, **kwargs, ): + """Initialize the soundfile mixer. + + Args: + sound_files: Mapping of sound names to file paths for loading. + default_sound: Name of the default sound to play initially. + volume: Mixing volume level (0.0 to 1.0). Defaults to 0.4. + mixing: Whether mixing is initially enabled. Defaults to True. + loop: Whether to loop audio files when they end. Defaults to True. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(**kwargs) self._sound_files = sound_files self._volume = volume @@ -58,14 +76,28 @@ class SoundfileMixer(BaseAudioMixer): self._loop = loop async def start(self, sample_rate: int): + """Initialize the mixer and load all sound files. + + Args: + sample_rate: The sample rate of the output transport in Hz. + """ self._sample_rate = sample_rate for sound_name, file_name in self._sound_files.items(): await asyncio.to_thread(self._load_sound_file, sound_name, file_name) async def stop(self): + """Clean up mixer resources. + + Currently performs no cleanup as sound data is managed by garbage collection. + """ pass async def process_frame(self, frame: MixerControlFrame): + """Process mixer control frames to update settings or enable/disable mixing. + + Args: + frame: The mixer control frame to process. + """ if isinstance(frame, MixerUpdateSettingsFrame): await self._update_settings(frame) elif isinstance(frame, MixerEnableFrame): @@ -73,12 +105,22 @@ class SoundfileMixer(BaseAudioMixer): pass async def mix(self, audio: bytes) -> bytes: + """Mix transport audio with the current sound file. + + Args: + audio: Raw audio bytes from the transport to mix. + + Returns: + Mixed audio bytes combining transport and file audio. + """ return self._mix_with_sound(audio) async def _enable_mixing(self, enable: bool): + """Enable or disable audio mixing.""" self._mixing = enable async def _update_settings(self, frame: MixerUpdateSettingsFrame): + """Update mixer settings from a control frame.""" for setting, value in frame.settings.items(): match setting: case "sound": @@ -89,6 +131,11 @@ class SoundfileMixer(BaseAudioMixer): await self._update_loop(value) async def _change_sound(self, sound: str): + """Change the currently playing sound file. + + Args: + sound: Name of the sound file to switch to. + """ if sound in self._sound_files: self._current_sound = sound self._sound_pos = 0 @@ -96,12 +143,15 @@ class SoundfileMixer(BaseAudioMixer): logger.error(f"Sound {sound} is not available") async def _update_volume(self, volume: float): + """Update the mixing volume level.""" self._volume = volume async def _update_loop(self, loop: bool): + """Update the looping behavior.""" self._loop = loop def _load_sound_file(self, sound_name: str, file_name: str): + """Load an audio file into memory for mixing.""" try: logger.debug(f"Loading mixer sound from {file_name}") sound, sample_rate = sf.read(file_name, dtype="int16") @@ -118,10 +168,7 @@ class SoundfileMixer(BaseAudioMixer): logger.error(f"Unable to open file {file_name}: {e}") def _mix_with_sound(self, audio: bytes): - """Mixes raw audio frames with chunks of the same length from the sound - file. - - """ + """Mix raw audio frames with chunks of the same length from the sound file.""" if not self._mixing or not self._current_sound in self._sounds: return audio diff --git a/src/pipecat/audio/resamplers/base_audio_resampler.py b/src/pipecat/audio/resamplers/base_audio_resampler.py index 6afbbcbfe..42854cd2c 100644 --- a/src/pipecat/audio/resamplers/base_audio_resampler.py +++ b/src/pipecat/audio/resamplers/base_audio_resampler.py @@ -4,27 +4,35 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base audio resampler interface for Pipecat. + +This module defines the abstract base class for audio resampling implementations, +providing a common interface for converting audio between different sample rates. +""" + from abc import ABC, abstractmethod class BaseAudioResampler(ABC): - """Abstract base class for audio resampling. This class defines an - interface for audio resampling implementations. + """Abstract base class for audio resampling implementations. + + This class defines the interface that all audio resampling implementations + must follow, providing a standardized way to convert audio data between + different sample rates. """ @abstractmethod async def resample(self, audio: bytes, in_rate: int, out_rate: int) -> bytes: - """ - Resamples the given audio data to a different sample rate. + """Resamples the given audio data to a different sample rate. This is an abstract method that must be implemented in subclasses. - Parameters: - audio (bytes): The audio data to be resampled, represented as a byte string. - in_rate (int): The original sample rate of the audio data (in Hz). - out_rate (int): The desired sample rate for the resampled audio data (in Hz). + Args: + audio: The audio data to be resampled, as raw bytes. + in_rate: The original sample rate of the audio data in Hz. + out_rate: The desired sample rate for the output audio in Hz. Returns: - bytes: The resampled audio data as a byte string. + The resampled audio data as raw bytes. """ pass diff --git a/src/pipecat/audio/resamplers/resampy_resampler.py b/src/pipecat/audio/resamplers/resampy_resampler.py index 8c053fc3b..b427bd3e8 100644 --- a/src/pipecat/audio/resamplers/resampy_resampler.py +++ b/src/pipecat/audio/resamplers/resampy_resampler.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Resampy-based audio resampler implementation. + +This module provides an audio resampler that uses the resampy library +for high-quality audio sample rate conversion. +""" + import numpy as np import resampy @@ -11,12 +17,31 @@ from pipecat.audio.resamplers.base_audio_resampler import BaseAudioResampler class ResampyResampler(BaseAudioResampler): - """Audio resampler implementation using the resampy library.""" + """Audio resampler implementation using the resampy library. + + This resampler uses the resampy library's Kaiser windowing filter + for high-quality audio resampling with good performance characteristics. + """ def __init__(self, **kwargs): + """Initialize the resampy resampler. + + Args: + **kwargs: Additional keyword arguments (currently unused). + """ pass async def resample(self, audio: bytes, in_rate: int, out_rate: int) -> bytes: + """Resample audio data using resampy library. + + Args: + audio: Input audio data as raw bytes (16-bit signed integers). + in_rate: Original sample rate in Hz. + out_rate: Target sample rate in Hz. + + Returns: + Resampled audio data as raw bytes (16-bit signed integers). + """ if in_rate == out_rate: return audio audio_data = np.frombuffer(audio, dtype=np.int16) diff --git a/src/pipecat/audio/resamplers/soxr_resampler.py b/src/pipecat/audio/resamplers/soxr_resampler.py index 88edb84eb..9f285069f 100644 --- a/src/pipecat/audio/resamplers/soxr_resampler.py +++ b/src/pipecat/audio/resamplers/soxr_resampler.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""SoX-based audio resampler implementation. + +This module provides an audio resampler that uses the SoX resampler library +for very high quality audio sample rate conversion. +""" + import numpy as np import soxr @@ -11,12 +17,32 @@ from pipecat.audio.resamplers.base_audio_resampler import BaseAudioResampler class SOXRAudioResampler(BaseAudioResampler): - """Audio resampler implementation using the SoX resampler library.""" + """Audio resampler implementation using the SoX resampler library. + + This resampler uses the SoX resampler library configured for very high + quality (VHQ) resampling, providing excellent audio quality at the cost + of additional computational overhead. + """ def __init__(self, **kwargs): + """Initialize the SoX audio resampler. + + Args: + **kwargs: Additional keyword arguments (currently unused). + """ pass async def resample(self, audio: bytes, in_rate: int, out_rate: int) -> bytes: + """Resample audio data using SoX resampler library. + + Args: + audio: Input audio data as raw bytes (16-bit signed integers). + in_rate: Original sample rate in Hz. + out_rate: Target sample rate in Hz. + + Returns: + Resampled audio data as raw bytes (16-bit signed integers). + """ if in_rate == out_rate: return audio audio_data = np.frombuffer(audio, dtype=np.int16) diff --git a/src/pipecat/audio/turn/base_turn_analyzer.py b/src/pipecat/audio/turn/base_turn_analyzer.py index 301dbf7bf..642173852 100644 --- a/src/pipecat/audio/turn/base_turn_analyzer.py +++ b/src/pipecat/audio/turn/base_turn_analyzer.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base turn analyzer for determining end-of-turn in audio conversations. + +This module provides the abstract base class and enumeration for analyzing +when a user has finished speaking in a conversation. +""" + from abc import ABC, abstractmethod from enum import Enum from typing import Optional, Tuple @@ -12,6 +18,13 @@ from pipecat.metrics.metrics import MetricsData class EndOfTurnState(Enum): + """State enumeration for end-of-turn analysis results. + + Parameters: + COMPLETE: The user has finished their turn and stopped speaking. + INCOMPLETE: The user is still speaking or may continue speaking. + """ + COMPLETE = 1 INCOMPLETE = 2 @@ -24,6 +37,12 @@ class BaseTurnAnalyzer(ABC): """ def __init__(self, *, sample_rate: Optional[int] = None): + """Initialize the turn analyzer. + + Args: + sample_rate: Optional initial sample rate for audio processing. + If provided, this will be used as the fixed sample rate. + """ self._init_sample_rate = sample_rate self._sample_rate = 0 diff --git a/src/pipecat/audio/turn/smart_turn/base_smart_turn.py b/src/pipecat/audio/turn/smart_turn/base_smart_turn.py index 0b577028b..38b5410ec 100644 --- a/src/pipecat/audio/turn/smart_turn/base_smart_turn.py +++ b/src/pipecat/audio/turn/smart_turn/base_smart_turn.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Smart turn analyzer base class using ML models for end-of-turn detection. + +This module provides the base implementation for smart turn analyzers that use +machine learning models to determine when a user has finished speaking, going +beyond simple silence-based detection. +""" + import time from abc import abstractmethod from typing import Any, Dict, Optional, Tuple @@ -23,6 +30,14 @@ USE_ONLY_LAST_VAD_SEGMENT = True class SmartTurnParams(BaseModel): + """Configuration parameters for smart turn analysis. + + Parameters: + stop_secs: Maximum silence duration in seconds before ending turn. + pre_speech_ms: Milliseconds of audio to include before speech starts. + max_duration_secs: Maximum duration in seconds for audio segments. + """ + stop_secs: float = STOP_SECS pre_speech_ms: float = PRE_SPEECH_MS max_duration_secs: float = MAX_DURATION_SECONDS @@ -31,13 +46,28 @@ class SmartTurnParams(BaseModel): class SmartTurnTimeoutException(Exception): + """Exception raised when smart turn analysis times out.""" + pass class BaseSmartTurn(BaseTurnAnalyzer): + """Base class for smart turn analyzers using ML models. + + Provides common functionality for smart turn detection including audio + buffering, speech tracking, and ML model integration. Subclasses must + implement the specific model prediction logic. + """ + def __init__( self, *, sample_rate: Optional[int] = None, params: Optional[SmartTurnParams] = None ): + """Initialize the smart turn analyzer. + + Args: + sample_rate: Optional sample rate for audio processing. + params: Configuration parameters for turn analysis behavior. + """ super().__init__(sample_rate=sample_rate) self._params = params or SmartTurnParams() # Configuration @@ -50,9 +80,23 @@ class BaseSmartTurn(BaseTurnAnalyzer): @property def speech_triggered(self) -> bool: + """Check if speech has been detected and triggered analysis. + + Returns: + True if speech has been detected and turn analysis is active. + """ return self._speech_triggered def append_audio(self, buffer: bytes, is_speech: bool) -> EndOfTurnState: + """Append audio data for turn analysis. + + Args: + buffer: Raw audio data bytes to append for analysis. + is_speech: Whether the audio buffer contains detected speech. + + Returns: + Current end-of-turn state after processing the audio. + """ # Convert raw audio to float32 format and append to the buffer audio_int16 = np.frombuffer(buffer, dtype=np.int16) audio_float32 = np.frombuffer(audio_int16, dtype=np.int16).astype(np.float32) / 32768.0 @@ -92,6 +136,12 @@ class BaseSmartTurn(BaseTurnAnalyzer): return state async def analyze_end_of_turn(self) -> Tuple[EndOfTurnState, Optional[MetricsData]]: + """Analyze the current audio state to determine if turn has ended. + + Returns: + Tuple containing the end-of-turn state and optional metrics data + from the ML model analysis. + """ state, result = await self._process_speech_segment(self._audio_buffer) if state == EndOfTurnState.COMPLETE or USE_ONLY_LAST_VAD_SEGMENT: self._clear(state) @@ -99,9 +149,11 @@ class BaseSmartTurn(BaseTurnAnalyzer): return state, result def clear(self): + """Reset the turn analyzer to its initial state.""" self._clear(EndOfTurnState.COMPLETE) def _clear(self, turn_state: EndOfTurnState): + """Clear internal state based on turn completion status.""" # If the state is still incomplete, keep the _speech_triggered as True self._speech_triggered = turn_state == EndOfTurnState.INCOMPLETE self._audio_buffer = [] @@ -111,6 +163,7 @@ class BaseSmartTurn(BaseTurnAnalyzer): async def _process_speech_segment( self, audio_buffer ) -> Tuple[EndOfTurnState, Optional[MetricsData]]: + """Process accumulated audio segment using ML model.""" state = EndOfTurnState.INCOMPLETE if not audio_buffer: @@ -188,14 +241,5 @@ class BaseSmartTurn(BaseTurnAnalyzer): @abstractmethod async def _predict_endpoint(self, audio_array: np.ndarray) -> Dict[str, Any]: - """Abstract method to predict if a turn has ended based on audio. - - Args: - audio_array: Float32 numpy array of audio samples at 16kHz. - - Returns: - Dictionary with: - - prediction: 1 if turn is complete, else 0 - - probability: Confidence of the prediction - """ + """Predict end-of-turn using ML model from audio data.""" pass diff --git a/src/pipecat/audio/turn/smart_turn/fal_smart_turn.py b/src/pipecat/audio/turn/smart_turn/fal_smart_turn.py index 9e3a85b56..d627eca72 100644 --- a/src/pipecat/audio/turn/smart_turn/fal_smart_turn.py +++ b/src/pipecat/audio/turn/smart_turn/fal_smart_turn.py @@ -4,6 +4,16 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Fal.ai smart turn analyzer implementation. + +This module provides a smart turn analyzer that uses Fal.ai's hosted smart-turn model +for end-of-turn detection in conversations. + +Note: To learn more about the smart-turn model, visit: + - https://fal.ai/models/fal-ai/smart-turn/playground + - https://github.com/pipecat-ai/smart-turn +""" + from typing import Optional import aiohttp @@ -12,6 +22,12 @@ from pipecat.audio.turn.smart_turn.http_smart_turn import HttpSmartTurnAnalyzer class FalSmartTurnAnalyzer(HttpSmartTurnAnalyzer): + """Smart turn analyzer using Fal.ai's hosted smart-turn model. + + Extends HttpSmartTurnAnalyzer to provide integration with Fal.ai's + smart turn detection API endpoint with proper authentication. + """ + def __init__( self, *, @@ -20,6 +36,14 @@ class FalSmartTurnAnalyzer(HttpSmartTurnAnalyzer): api_key: Optional[str] = None, **kwargs, ): + """Initialize the Fal.ai smart turn analyzer. + + Args: + aiohttp_session: HTTP client session for making API requests. + url: Fal.ai API endpoint URL for smart turn detection. + api_key: API key for authenticating with Fal.ai service. + **kwargs: Additional arguments passed to parent HttpSmartTurnAnalyzer. + """ headers = {} if api_key: headers = {"Authorization": f"Key {api_key}"} diff --git a/src/pipecat/audio/turn/smart_turn/http_smart_turn.py b/src/pipecat/audio/turn/smart_turn/http_smart_turn.py index bf9f086a3..c28727f78 100644 --- a/src/pipecat/audio/turn/smart_turn/http_smart_turn.py +++ b/src/pipecat/audio/turn/smart_turn/http_smart_turn.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""HTTP-based smart turn analyzer for remote ML inference. + +This module provides a smart turn analyzer that sends audio data to remote +HTTP endpoints for ML-based end-of-turn detection. +""" + import asyncio import io from typing import Any, Dict, Optional @@ -16,6 +22,12 @@ from pipecat.audio.turn.smart_turn.base_smart_turn import BaseSmartTurn, SmartTu class HttpSmartTurnAnalyzer(BaseSmartTurn): + """Smart turn analyzer using HTTP-based ML inference. + + Sends audio data to remote HTTP endpoints for ML-based end-of-turn + prediction. Handles serialization, HTTP communication, and error recovery. + """ + def __init__( self, *, @@ -24,12 +36,21 @@ class HttpSmartTurnAnalyzer(BaseSmartTurn): headers: Optional[Dict[str, str]] = None, **kwargs, ): + """Initialize the HTTP smart turn analyzer. + + Args: + url: HTTP endpoint URL for the smart turn ML service. + aiohttp_session: HTTP client session for making requests. + headers: Optional HTTP headers to include in requests. + **kwargs: Additional arguments passed to BaseSmartTurn. + """ super().__init__(**kwargs) self._url = url self._headers = headers or {} self._aiohttp_session = aiohttp_session def _serialize_array(self, audio_array: np.ndarray) -> bytes: + """Serialize NumPy audio array to bytes for HTTP transmission.""" logger.trace("Serializing NumPy array to bytes...") buffer = io.BytesIO() np.save(buffer, audio_array) @@ -38,6 +59,7 @@ class HttpSmartTurnAnalyzer(BaseSmartTurn): return serialized_bytes async def _send_raw_request(self, data_bytes: bytes) -> Dict[str, Any]: + """Send raw audio data to the HTTP endpoint for prediction.""" headers = {"Content-Type": "application/octet-stream"} headers.update(self._headers) @@ -83,6 +105,7 @@ class HttpSmartTurnAnalyzer(BaseSmartTurn): raise Exception("Failed to send raw request to Daily Smart Turn.") async def _predict_endpoint(self, audio_array: np.ndarray) -> Dict[str, Any]: + """Predict end-of-turn using remote HTTP ML service.""" try: serialized_array = self._serialize_array(audio_array) return await self._send_raw_request(serialized_array) diff --git a/src/pipecat/audio/turn/smart_turn/local_coreml_smart_turn.py b/src/pipecat/audio/turn/smart_turn/local_coreml_smart_turn.py index 88d6530bd..dd35449de 100644 --- a/src/pipecat/audio/turn/smart_turn/local_coreml_smart_turn.py +++ b/src/pipecat/audio/turn/smart_turn/local_coreml_smart_turn.py @@ -4,6 +4,11 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Local CoreML smart turn analyzer for on-device ML inference. + +This module provides a smart turn analyzer that uses CoreML models for +local end-of-turn detection without requiring network connectivity. +""" from typing import Any, Dict @@ -25,7 +30,24 @@ except ModuleNotFoundError as e: class LocalCoreMLSmartTurnAnalyzer(BaseSmartTurn): + """Local smart turn analyzer using CoreML models. + + Provides end-of-turn detection using locally-stored CoreML models, + enabling offline operation without network dependencies. Optimized + for Apple Silicon and other CoreML-compatible hardware. + """ + def __init__(self, *, smart_turn_model_path: str, **kwargs): + """Initialize the local CoreML smart turn analyzer. + + Args: + smart_turn_model_path: Path to directory containing the CoreML model + and feature extractor files. + **kwargs: Additional arguments passed to BaseSmartTurn. + + Raises: + Exception: If smart_turn_model_path is not provided or model loading fails. + """ super().__init__(**kwargs) if not smart_turn_model_path: @@ -41,6 +63,7 @@ class LocalCoreMLSmartTurnAnalyzer(BaseSmartTurn): logger.debug("Loaded Local Smart Turn") async def _predict_endpoint(self, audio_array: np.ndarray) -> Dict[str, Any]: + """Predict end-of-turn using local CoreML model.""" inputs = self._turn_processor( audio_array, sampling_rate=16000, diff --git a/src/pipecat/audio/turn/smart_turn/local_smart_turn.py b/src/pipecat/audio/turn/smart_turn/local_smart_turn.py index a3ee7ebf9..ed67dad12 100644 --- a/src/pipecat/audio/turn/smart_turn/local_smart_turn.py +++ b/src/pipecat/audio/turn/smart_turn/local_smart_turn.py @@ -4,6 +4,11 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Local PyTorch smart turn analyzer for on-device ML inference. + +This module provides a smart turn analyzer that uses PyTorch models for +local end-of-turn detection without requiring network connectivity. +""" from typing import Any, Dict @@ -24,7 +29,21 @@ except ModuleNotFoundError as e: class LocalSmartTurnAnalyzer(BaseSmartTurn): + """Local smart turn analyzer using PyTorch models. + + Provides end-of-turn detection using locally-stored PyTorch models, + enabling offline operation without network dependencies. Uses + Wav2Vec2-BERT architecture for audio sequence classification. + """ + def __init__(self, *, smart_turn_model_path: str, **kwargs): + """Initialize the local PyTorch smart turn analyzer. + + Args: + smart_turn_model_path: Path to directory containing the PyTorch model + and feature extractor files. If empty, uses default HuggingFace model. + **kwargs: Additional arguments passed to BaseSmartTurn. + """ super().__init__(**kwargs) if not smart_turn_model_path: @@ -46,6 +65,7 @@ class LocalSmartTurnAnalyzer(BaseSmartTurn): logger.debug("Loaded Local Smart Turn") async def _predict_endpoint(self, audio_array: np.ndarray) -> Dict[str, Any]: + """Predict end-of-turn using local PyTorch model.""" inputs = self._turn_processor( audio_array, sampling_rate=16000, diff --git a/src/pipecat/audio/utils.py b/src/pipecat/audio/utils.py index 1f7db648f..7b72be1a9 100644 --- a/src/pipecat/audio/utils.py +++ b/src/pipecat/audio/utils.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Audio utility functions for Pipecat. + +This module provides common audio processing utilities including mixing, +format conversion, volume calculation, and codec transformations for +various audio formats used in Pipecat pipelines. +""" + import audioop import numpy as np @@ -15,10 +22,31 @@ from pipecat.audio.resamplers.soxr_resampler import SOXRAudioResampler def create_default_resampler(**kwargs) -> BaseAudioResampler: + """Create a default audio resampler instance. + + Args: + **kwargs: Additional keyword arguments passed to the resampler constructor. + + Returns: + A configured SOXRAudioResampler instance. + """ return SOXRAudioResampler(**kwargs) def mix_audio(audio1: bytes, audio2: bytes) -> bytes: + """Mix two audio streams together by adding their samples. + + Both audio streams are assumed to be 16-bit signed integer PCM data. + If the streams have different lengths, the shorter one is zero-padded + to match the longer stream. + + Args: + audio1: First audio stream as raw bytes (16-bit signed integers). + audio2: Second audio stream as raw bytes (16-bit signed integers). + + Returns: + Mixed audio data as raw bytes with samples clipped to 16-bit range. + """ data1 = np.frombuffer(audio1, dtype=np.int16) data2 = np.frombuffer(audio2, dtype=np.int16) @@ -37,6 +65,19 @@ def mix_audio(audio1: bytes, audio2: bytes) -> bytes: def interleave_stereo_audio(left_audio: bytes, right_audio: bytes) -> bytes: + """Interleave left and right mono audio channels into stereo audio. + + Takes two mono audio streams and combines them into a single stereo + stream by interleaving the samples (L, R, L, R, ...). If the channels + have different lengths, both are truncated to the shorter length. + + Args: + left_audio: Left channel audio as raw bytes (16-bit signed integers). + right_audio: Right channel audio as raw bytes (16-bit signed integers). + + Returns: + Interleaved stereo audio data as raw bytes. + """ left = np.frombuffer(left_audio, dtype=np.int16) right = np.frombuffer(right_audio, dtype=np.int16) @@ -50,12 +91,34 @@ def interleave_stereo_audio(left_audio: bytes, right_audio: bytes) -> bytes: def normalize_value(value, min_value, max_value): + """Normalize a value to the range [0, 1] and clamp it to bounds. + + Args: + value: The value to normalize. + min_value: The minimum value of the input range. + max_value: The maximum value of the input range. + + Returns: + Normalized value clamped to the range [0, 1]. + """ normalized = (value - min_value) / (max_value - min_value) normalized_clamped = max(0, min(1, normalized)) return normalized_clamped def calculate_audio_volume(audio: bytes, sample_rate: int) -> float: + """Calculate the loudness level of audio data using EBU R128 standard. + + Uses the pyloudnorm library to calculate integrated loudness according + to the EBU R128 recommendation, then normalizes the result to [0, 1]. + + Args: + audio: Audio data as raw bytes (16-bit signed integers). + sample_rate: Sample rate of the audio in Hz. + + Returns: + Normalized loudness value between 0 (quiet) and 1 (loud). + """ audio_np = np.frombuffer(audio, dtype=np.int16) audio_float = audio_np.astype(np.float64) @@ -71,12 +134,37 @@ def calculate_audio_volume(audio: bytes, sample_rate: int) -> float: def exp_smoothing(value: float, prev_value: float, factor: float) -> float: + """Apply exponential smoothing to a value. + + Exponential smoothing is used to reduce noise in time-series data by + giving more weight to recent values while still considering historical data. + + Args: + value: The new value to incorporate. + prev_value: The previous smoothed value. + factor: Smoothing factor between 0 and 1. Higher values give more + weight to the new value. + + Returns: + The exponentially smoothed value. + """ return prev_value + factor * (value - prev_value) async def ulaw_to_pcm( ulaw_bytes: bytes, in_rate: int, out_rate: int, resampler: BaseAudioResampler ): + """Convert μ-law encoded audio to PCM and optionally resample. + + Args: + ulaw_bytes: μ-law encoded audio data as raw bytes. + in_rate: Original sample rate of the μ-law audio in Hz. + out_rate: Desired output sample rate in Hz. + resampler: Audio resampler instance for rate conversion. + + Returns: + PCM audio data as raw bytes at the specified output rate. + """ # Convert μ-law to PCM in_pcm_bytes = audioop.ulaw2lin(ulaw_bytes, 2) @@ -87,6 +175,17 @@ async def ulaw_to_pcm( async def pcm_to_ulaw(pcm_bytes: bytes, in_rate: int, out_rate: int, resampler: BaseAudioResampler): + """Convert PCM audio to μ-law encoding and optionally resample. + + Args: + pcm_bytes: PCM audio data as raw bytes (16-bit signed integers). + in_rate: Original sample rate of the PCM audio in Hz. + out_rate: Desired output sample rate in Hz. + resampler: Audio resampler instance for rate conversion. + + Returns: + μ-law encoded audio data as raw bytes at the specified output rate. + """ # Resample in_pcm_bytes = await resampler.resample(pcm_bytes, in_rate, out_rate) @@ -99,6 +198,17 @@ async def pcm_to_ulaw(pcm_bytes: bytes, in_rate: int, out_rate: int, resampler: async def alaw_to_pcm( alaw_bytes: bytes, in_rate: int, out_rate: int, resampler: BaseAudioResampler ) -> bytes: + """Convert A-law encoded audio to PCM and optionally resample. + + Args: + alaw_bytes: A-law encoded audio data as raw bytes. + in_rate: Original sample rate of the A-law audio in Hz. + out_rate: Desired output sample rate in Hz. + resampler: Audio resampler instance for rate conversion. + + Returns: + PCM audio data as raw bytes at the specified output rate. + """ # Convert a-law to PCM in_pcm_bytes = audioop.alaw2lin(alaw_bytes, 2) @@ -109,6 +219,17 @@ async def alaw_to_pcm( async def pcm_to_alaw(pcm_bytes: bytes, in_rate: int, out_rate: int, resampler: BaseAudioResampler): + """Convert PCM audio to A-law encoding and optionally resample. + + Args: + pcm_bytes: PCM audio data as raw bytes (16-bit signed integers). + in_rate: Original sample rate of the PCM audio in Hz. + out_rate: Desired output sample rate in Hz. + resampler: Audio resampler instance for rate conversion. + + Returns: + A-law encoded audio data as raw bytes at the specified output rate. + """ # Resample in_pcm_bytes = await resampler.resample(pcm_bytes, in_rate, out_rate) diff --git a/src/pipecat/audio/vad/silero.py b/src/pipecat/audio/vad/silero.py index cb1dc7631..d97e9b1df 100644 --- a/src/pipecat/audio/vad/silero.py +++ b/src/pipecat/audio/vad/silero.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Silero Voice Activity Detection (VAD) implementation for Pipecat. + +This module provides a VAD analyzer based on the Silero VAD ONNX model, +which can detect voice activity in audio streams with high accuracy. +Supports 8kHz and 16kHz sample rates. +""" + import time from typing import Optional @@ -25,7 +32,20 @@ except ModuleNotFoundError as e: class SileroOnnxModel: + """ONNX runtime wrapper for the Silero VAD model. + + Provides voice activity detection using the pre-trained Silero VAD model + with ONNX runtime for efficient inference. Handles model state management + and input validation for audio processing. + """ + def __init__(self, path, force_onnx_cpu=True): + """Initialize the Silero ONNX model. + + Args: + path: Path to the ONNX model file. + force_onnx_cpu: Whether to force CPU execution provider. + """ import numpy as np global np @@ -45,6 +65,7 @@ class SileroOnnxModel: self.sample_rates = [8000, 16000] def _validate_input(self, x, sr: int): + """Validate and preprocess input audio data.""" if np.ndim(x) == 1: x = np.expand_dims(x, 0) if np.ndim(x) > 2: @@ -60,12 +81,18 @@ class SileroOnnxModel: return x, sr def reset_states(self, batch_size=1): + """Reset the internal model states. + + Args: + batch_size: Batch size for state initialization. Defaults to 1. + """ self._state = np.zeros((2, batch_size, 128), dtype="float32") self._context = np.zeros((batch_size, 0), dtype="float32") self._last_sr = 0 self._last_batch_size = 0 def __call__(self, x, sr: int): + """Process audio input through the VAD model.""" x, sr = self._validate_input(x, sr) num_samples = 512 if sr == 16000 else 256 @@ -105,7 +132,20 @@ class SileroOnnxModel: class SileroVADAnalyzer(VADAnalyzer): + """Voice Activity Detection analyzer using the Silero VAD model. + + Implements VAD analysis using the pre-trained Silero ONNX model for + accurate voice activity detection. Supports 8kHz and 16kHz sample rates + with automatic model state management and periodic resets. + """ + def __init__(self, *, sample_rate: Optional[int] = None, params: Optional[VADParams] = None): + """Initialize the Silero VAD analyzer. + + Args: + sample_rate: Audio sample rate (8000 or 16000 Hz). If None, will be set later. + params: VAD parameters for detection thresholds and timing. + """ super().__init__(sample_rate=sample_rate, params=params) logger.debug("Loading Silero VAD model...") @@ -137,6 +177,14 @@ class SileroVADAnalyzer(VADAnalyzer): # def set_sample_rate(self, sample_rate: int): + """Set the sample rate for audio processing. + + Args: + sample_rate: Audio sample rate (must be 8000 or 16000 Hz). + + Raises: + ValueError: If sample rate is not 8000 or 16000 Hz. + """ if sample_rate != 16000 and sample_rate != 8000: raise ValueError( f"Silero VAD sample rate needs to be 16000 or 8000 (sample rate: {sample_rate})" @@ -145,9 +193,22 @@ class SileroVADAnalyzer(VADAnalyzer): super().set_sample_rate(sample_rate) def num_frames_required(self) -> int: + """Get the number of audio frames required for VAD analysis. + + Returns: + Number of frames required (512 for 16kHz, 256 for 8kHz). + """ return 512 if self.sample_rate == 16000 else 256 def voice_confidence(self, buffer) -> float: + """Calculate voice activity confidence for the given audio buffer. + + Args: + buffer: Audio buffer to analyze. + + Returns: + Voice confidence score between 0.0 and 1.0. + """ try: audio_int16 = np.frombuffer(buffer, np.int16) # Divide by 32768 because we have signed 16-bit data. diff --git a/src/pipecat/audio/vad/vad_analyzer.py b/src/pipecat/audio/vad/vad_analyzer.py index 073e61712..5c92d390c 100644 --- a/src/pipecat/audio/vad/vad_analyzer.py +++ b/src/pipecat/audio/vad/vad_analyzer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Voice Activity Detection (VAD) analyzer base classes and utilities. + +This module provides the abstract base class for VAD analyzers and associated +data structures for voice activity detection in audio streams. Includes state +management, parameter configuration, and audio analysis framework. +""" + from abc import ABC, abstractmethod from enum import Enum from typing import Optional @@ -20,6 +27,15 @@ VAD_MIN_VOLUME = 0.6 class VADState(Enum): + """Voice Activity Detection states. + + Parameters: + QUIET: No voice activity detected. + STARTING: Voice activity beginning, transitioning from quiet. + SPEAKING: Active voice detected and confirmed. + STOPPING: Voice activity ending, transitioning to quiet. + """ + QUIET = 1 STARTING = 2 SPEAKING = 3 @@ -27,6 +43,15 @@ class VADState(Enum): class VADParams(BaseModel): + """Configuration parameters for Voice Activity Detection. + + Parameters: + confidence: Minimum confidence threshold for voice detection. + start_secs: Duration to wait before confirming voice start. + stop_secs: Duration to wait before confirming voice stop. + min_volume: Minimum audio volume threshold for voice detection. + """ + confidence: float = VAD_CONFIDENCE start_secs: float = VAD_START_SECS stop_secs: float = VAD_STOP_SECS @@ -34,7 +59,20 @@ class VADParams(BaseModel): class VADAnalyzer(ABC): + """Abstract base class for Voice Activity Detection analyzers. + + Provides the framework for implementing VAD analysis with configurable + parameters, state management, and audio processing capabilities. + Subclasses must implement the core voice confidence calculation. + """ + def __init__(self, *, sample_rate: Optional[int] = None, params: Optional[VADParams] = None): + """Initialize the VAD analyzer. + + Args: + sample_rate: Audio sample rate in Hz. If None, will be set later. + params: VAD parameters for detection configuration. + """ self._init_sample_rate = sample_rate self._sample_rate = 0 self._params = params or VADParams() @@ -48,29 +86,67 @@ class VADAnalyzer(ABC): @property def sample_rate(self) -> int: + """Get the current sample rate. + + Returns: + Current audio sample rate in Hz. + """ return self._sample_rate @property def num_channels(self) -> int: + """Get the number of audio channels. + + Returns: + Number of audio channels (always 1 for mono). + """ return self._num_channels @property def params(self) -> VADParams: + """Get the current VAD parameters. + + Returns: + Current VAD configuration parameters. + """ return self._params @abstractmethod def num_frames_required(self) -> int: + """Get the number of audio frames required for analysis. + + Returns: + Number of frames needed for VAD processing. + """ pass @abstractmethod def voice_confidence(self, buffer) -> float: + """Calculate voice activity confidence for the given audio buffer. + + Args: + buffer: Audio buffer to analyze. + + Returns: + Voice confidence score between 0.0 and 1.0. + """ pass def set_sample_rate(self, sample_rate: int): + """Set the sample rate for audio processing. + + Args: + sample_rate: Audio sample rate in Hz. + """ self._sample_rate = self._init_sample_rate or sample_rate self.set_params(self._params) def set_params(self, params: VADParams): + """Set VAD parameters and recalculate internal values. + + Args: + params: VAD parameters for detection configuration. + """ logger.debug(f"Setting VAD params to: {params}") self._params = params self._vad_frames = self.num_frames_required() @@ -85,10 +161,22 @@ class VADAnalyzer(ABC): self._vad_state: VADState = VADState.QUIET def _get_smoothed_volume(self, audio: bytes) -> float: + """Calculate smoothed audio volume using exponential smoothing.""" volume = calculate_audio_volume(audio, self.sample_rate) return exp_smoothing(volume, self._prev_volume, self._smoothing_factor) def analyze_audio(self, buffer) -> VADState: + """Analyze audio buffer and return current VAD state. + + Processes incoming audio data, maintains internal state, and determines + voice activity status based on confidence and volume thresholds. + + Args: + buffer: Audio buffer to analyze. + + Returns: + Current VAD state after processing the buffer. + """ self._vad_buffer += buffer num_required_bytes = self._vad_frames_num_bytes diff --git a/src/pipecat/clocks/base_clock.py b/src/pipecat/clocks/base_clock.py index 184c82f00..7efe3c457 100644 --- a/src/pipecat/clocks/base_clock.py +++ b/src/pipecat/clocks/base_clock.py @@ -4,14 +4,33 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base clock interface for Pipecat timing operations.""" + from abc import ABC, abstractmethod class BaseClock(ABC): + """Abstract base class for clock implementations. + + Provides a common interface for timing operations used in Pipecat + for synchronization, scheduling, and time-based processing. + """ + @abstractmethod def get_time(self) -> int: + """Get the current time value. + + Returns: + The current time as an integer value. The specific unit and + reference point depend on the concrete implementation. + """ pass @abstractmethod def start(self): + """Start or initialize the clock. + + Performs any necessary initialization or starts the timing mechanism. + This method should be called before using get_time(). + """ pass diff --git a/src/pipecat/clocks/system_clock.py b/src/pipecat/clocks/system_clock.py index ed6e81ad7..87f2a722b 100644 --- a/src/pipecat/clocks/system_clock.py +++ b/src/pipecat/clocks/system_clock.py @@ -4,17 +4,42 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""System clock implementation for Pipecat.""" + import time from pipecat.clocks.base_clock import BaseClock class SystemClock(BaseClock): + """A monotonic clock implementation using system time. + + Provides high-precision timing using the system's monotonic clock, + which is not affected by system clock adjustments and is suitable + for measuring elapsed time in real-time applications. + """ + def __init__(self): + """Initialize the system clock. + + The clock starts in an uninitialized state and must be started + explicitly using the start() method before time measurement begins. + """ self._time = 0 def get_time(self) -> int: + """Get the elapsed time since the clock was started. + + Returns: + The elapsed time in nanoseconds since start() was called. + Returns 0 if the clock has not been started yet. + """ return time.monotonic_ns() - self._time if self._time > 0 else 0 def start(self): + """Start the clock and begin time measurement. + + Records the current monotonic time as the reference point + for all subsequent get_time() calls. + """ self._time = time.monotonic_ns() diff --git a/src/pipecat/examples/daily_runner.py b/src/pipecat/examples/daily_runner.py index 04157d549..d8d6acd81 100644 --- a/src/pipecat/examples/daily_runner.py +++ b/src/pipecat/examples/daily_runner.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Daily.co room configuration utilities for Pipecat examples.""" + import argparse import os from typing import Optional @@ -14,6 +16,17 @@ from pipecat.transports.services.helpers.daily_rest import DailyRESTHelper async def configure(aiohttp_session: aiohttp.ClientSession): + """Configure Daily.co room URL and token from arguments or environment. + + Args: + aiohttp_session: HTTP session for making API requests. + + Returns: + Tuple containing the room URL and authentication token. + + Raises: + Exception: If room URL or API key are not provided. + """ (url, token, _) = await configure_with_args(aiohttp_session) return (url, token) @@ -21,6 +34,18 @@ async def configure(aiohttp_session: aiohttp.ClientSession): async def configure_with_args( aiohttp_session: aiohttp.ClientSession, parser: Optional[argparse.ArgumentParser] = None ): + """Configure Daily.co room with command-line argument parsing. + + Args: + aiohttp_session: HTTP session for making API requests. + parser: Optional argument parser. If None, creates a default one. + + Returns: + Tuple containing room URL, authentication token, and parsed arguments. + + Raises: + Exception: If room URL or API key are not provided via arguments or environment. + """ if not parser: parser = argparse.ArgumentParser(description="Daily AI SDK Bot Sample") parser.add_argument( diff --git a/src/pipecat/examples/run.py b/src/pipecat/examples/run.py index 24f673e06..edc8ba058 100644 --- a/src/pipecat/examples/run.py +++ b/src/pipecat/examples/run.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Pipecat example runner with support for multiple transport types. + +This module provides a unified interface for running Pipecat examples across +different transport types including Daily.co, WebRTC, and Twilio. It handles +setup, configuration, and lifecycle management for each transport type. +""" + import argparse import asyncio import json @@ -35,6 +42,15 @@ load_dotenv(override=True) def get_transport_client_id(transport: BaseTransport, client: Any) -> str: + """Get client identifier from transport-specific client object. + + Args: + transport: The transport instance. + client: Transport-specific client object. + + Returns: + Client identifier string, empty if transport not supported. + """ if isinstance(transport, SmallWebRTCTransport): return client.pc_id elif isinstance(transport, DailyTransport): @@ -46,6 +62,13 @@ def get_transport_client_id(transport: BaseTransport, client: Any) -> str: async def maybe_capture_participant_camera( transport: BaseTransport, client: Any, framerate: int = 0 ): + """Capture participant camera video if transport supports it. + + Args: + transport: The transport instance. + client: Transport-specific client object. + framerate: Video capture framerate. Defaults to 0 (auto). + """ if isinstance(transport, DailyTransport): await transport.capture_participant_video( client["id"], framerate=framerate, video_source="camera" @@ -55,6 +78,13 @@ async def maybe_capture_participant_camera( async def maybe_capture_participant_screen( transport: BaseTransport, client: Any, framerate: int = 0 ): + """Capture participant screen video if transport supports it. + + Args: + transport: The transport instance. + client: Transport-specific client object. + framerate: Video capture framerate. Defaults to 0 (auto). + """ if isinstance(transport, DailyTransport): await transport.capture_participant_video( client["id"], framerate=framerate, video_source="screenVideo" @@ -66,6 +96,13 @@ def run_example_daily( args: argparse.Namespace, transport_params: Mapping[str, Callable] = {}, ): + """Run example using Daily.co transport. + + Args: + run_example: The example function to run. + args: Parsed command-line arguments. + transport_params: Mapping of transport names to parameter factory functions. + """ logger.info("Running example with DailyTransport...") from pipecat.examples.daily_runner import configure @@ -87,6 +124,13 @@ def run_example_webrtc( args: argparse.Namespace, transport_params: Mapping[str, Callable] = {}, ): + """Run example using WebRTC transport with FastAPI server. + + Args: + run_example: The example function to run. + args: Parsed command-line arguments. + transport_params: Mapping of transport names to parameter factory functions. + """ logger.info("Running example with SmallWebRTCTransport...") from pipecat_ai_small_webrtc_prebuilt.frontend import SmallWebRTCPrebuiltUI @@ -107,10 +151,20 @@ def run_example_webrtc( @app.get("/", include_in_schema=False) async def root_redirect(): + """Redirect root requests to client interface.""" return RedirectResponse(url="/client/") @app.post("/api/offer") async def offer(request: dict, background_tasks: BackgroundTasks): + """Handle WebRTC offer requests and manage peer connections. + + Args: + request: WebRTC offer request containing SDP and connection details. + background_tasks: FastAPI background tasks for running examples. + + Returns: + WebRTC answer with connection details. + """ pc_id = request.get("pc_id") if pc_id and pc_id in pcs_map: @@ -127,6 +181,11 @@ def run_example_webrtc( @pipecat_connection.event_handler("closed") async def handle_disconnected(webrtc_connection: SmallWebRTCConnection): + """Handle WebRTC connection closure and cleanup. + + Args: + webrtc_connection: The closed WebRTC connection. + """ logger.info(f"Discarding peer connection for pc_id: {webrtc_connection.pc_id}") pcs_map.pop(webrtc_connection.pc_id, None) @@ -143,6 +202,11 @@ def run_example_webrtc( @asynccontextmanager async def lifespan(app: FastAPI): + """Manage FastAPI application lifecycle and cleanup connections. + + Args: + app: The FastAPI application instance. + """ yield # Run app coros = [pc.disconnect() for pc in pcs_map.values()] await asyncio.gather(*coros) @@ -156,6 +220,13 @@ def run_example_twilio( args: argparse.Namespace, transport_params: Mapping[str, Callable] = {}, ): + """Run example using Twilio transport with FastAPI WebSocket server. + + Args: + run_example: The example function to run. + args: Parsed command-line arguments. + transport_params: Mapping of transport names to parameter factory functions. + """ logger.info("Running example with FastAPIWebsocketTransport (Twilio)...") app = FastAPI() @@ -170,6 +241,11 @@ def run_example_twilio( @app.post("/") async def start_call(): + """Handle Twilio webhook and return TwiML response. + + Returns: + TwiML XML response directing call to WebSocket stream. + """ logger.debug("POST TwiML") xml_content = f""" @@ -184,6 +260,11 @@ def run_example_twilio( @app.websocket("/ws") async def websocket_endpoint(websocket: WebSocket): + """Handle Twilio WebSocket connections for voice streaming. + + Args: + websocket: The WebSocket connection from Twilio. + """ await websocket.accept() logger.debug("WebSocket connection accepted") @@ -216,6 +297,13 @@ def run_main( args: argparse.Namespace, transport_params: Mapping[str, Callable] = {}, ): + """Run the example with the specified transport type. + + Args: + run_example: The example function to run. + args: Parsed command-line arguments. + transport_params: Mapping of transport names to parameter factory functions. + """ if args.transport not in transport_params: logger.error(f"Transport '{args.transport}' not supported by this example") return @@ -235,6 +323,13 @@ def main( parser: Optional[argparse.ArgumentParser] = None, transport_params: Mapping[str, Callable] = {}, ): + """Main entry point for running Pipecat examples with transport selection. + + Args: + run_example: The example function to run. + parser: Optional argument parser. If None, creates a default one. + transport_params: Mapping of transport names to parameter factory functions. + """ if not parser: parser = argparse.ArgumentParser(description="Pipecat Bot Runner") parser.add_argument( diff --git a/src/pipecat/frames/frames.py b/src/pipecat/frames/frames.py index 3a602a3e2..59e862818 100644 --- a/src/pipecat/frames/frames.py +++ b/src/pipecat/frames/frames.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Core frame definitions for the Pipecat AI framework. + +This module contains all frame types used throughout the Pipecat pipeline system, +including data frames, system frames, and control frames for audio, video, text, +and LLM processing. +""" + from dataclasses import dataclass, field from enum import Enum from typing import ( @@ -32,7 +39,22 @@ if TYPE_CHECKING: class KeypadEntry(str, Enum): - """DTMF entries.""" + """DTMF keypad entries for phone system integration. + + Parameters: + ONE: Number key 1. + TWO: Number key 2. + THREE: Number key 3. + FOUR: Number key 4. + FIVE: Number key 5. + SIX: Number key 6. + SEVEN: Number key 7. + EIGHT: Number key 8. + NINE: Number key 9. + ZERO: Number key 0. + POUND: Pound/hash key (#). + STAR: Star/asterisk key (*). + """ ONE = "1" TWO = "2" @@ -49,12 +71,31 @@ class KeypadEntry(str, Enum): def format_pts(pts: Optional[int]): + """Format presentation timestamp (PTS) in nanoseconds to a human-readable string. + + Converts a PTS value in nanoseconds to a string representation. + + Args: + pts: Presentation timestamp in nanoseconds, or None if not set. + """ return nanoseconds_to_str(pts) if pts else None @dataclass class Frame: - """Base frame class.""" + """Base frame class for all frames in the Pipecat pipeline. + + All frames inherit from this base class and automatically receive + unique identifiers, names, and metadata support. + + Parameters: + id: Unique identifier for the frame instance. + name: Human-readable name combining class name and instance count. + pts: Presentation timestamp in nanoseconds. + metadata: Dictionary for arbitrary frame metadata. + transport_source: Name of the transport source that created this frame. + transport_destination: Name of the transport destination for this frame. + """ id: int = field(init=False) name: str = field(init=False) @@ -77,9 +118,10 @@ class Frame: @dataclass class SystemFrame(Frame): - """System frames are frames that are not internally queued by any of the - frame processors and should be processed immediately. + """System frame class for immediate processing. + System frames are frames that are not internally queued by any of the + frame processors and should be processed immediately. """ pass @@ -87,9 +129,10 @@ class SystemFrame(Frame): @dataclass class DataFrame(Frame): - """Data frames are frames that will be processed in order and usually - contain data such as LLM context, text, audio or images. + """Data frame class for processing data in order. + Data frames are frames that will be processed in order and usually + contain data such as LLM context, text, audio or images. """ pass @@ -97,10 +140,11 @@ class DataFrame(Frame): @dataclass class ControlFrame(Frame): - """Control frames are frames that, similar to data frames, will be processed + """Control frame class for processing control information in order. + + Control frames are frames that, similar to data frames, will be processed in order and usually contain control information such as frames to update settings or to end the pipeline. - """ pass @@ -113,7 +157,14 @@ class ControlFrame(Frame): @dataclass class AudioRawFrame: - """A chunk of audio.""" + """A frame containing a chunk of raw audio. + + Parameters: + audio: Raw audio bytes in PCM format. + sample_rate: Audio sample rate in Hz. + num_channels: Number of audio channels. + num_frames: Number of audio frames (calculated automatically). + """ audio: bytes sample_rate: int @@ -126,7 +177,13 @@ class AudioRawFrame: @dataclass class ImageRawFrame: - """A raw image.""" + """A frame containing a raw image. + + Parameters: + image: Raw image bytes. + size: Image dimensions as (width, height) tuple. + format: Image format (e.g., 'JPEG', 'PNG'). + """ image: bytes size: Tuple[int, int] @@ -140,10 +197,11 @@ class ImageRawFrame: @dataclass class OutputAudioRawFrame(DataFrame, AudioRawFrame): - """A chunk of audio. Will be played by the output transport. If the - transport supports multiple audio destinations (e.g. multiple audio tracks) the - destination name can be specified. + """Audio data frame for output to transport. + A chunk of raw audio that will be played by the output transport. If the + transport supports multiple audio destinations (e.g. multiple audio tracks) + the destination name can be specified in transport_destination. """ def __post_init__(self): @@ -157,10 +215,11 @@ class OutputAudioRawFrame(DataFrame, AudioRawFrame): @dataclass class OutputImageRawFrame(DataFrame, ImageRawFrame): - """An image that will be shown by the transport. If the transport supports - multiple video destinations (e.g. multiple video tracks) the destination - name can be specified. + """Image data frame for output to transport. + An image that will be shown by the transport. If the transport supports + multiple video destinations (e.g. multiple video tracks) the destination + name can be specified in transport_destination. """ def __str__(self): @@ -170,16 +229,23 @@ class OutputImageRawFrame(DataFrame, ImageRawFrame): @dataclass class TTSAudioRawFrame(OutputAudioRawFrame): - """A chunk of output audio generated by a TTS service.""" + """Audio data frame generated by Text-to-Speech services. + + A chunk of output audio generated by a TTS service, ready for playback. + """ pass @dataclass class URLImageRawFrame(OutputImageRawFrame): - """An output image with an associated URL. These images are usually + """Image frame with an associated URL. + + An output image with an associated URL. These images are usually generated by third-party services that provide a URL to download the image. + Parameters: + url: URL where the image can be downloaded from. """ url: Optional[str] = None @@ -191,10 +257,14 @@ class URLImageRawFrame(OutputImageRawFrame): @dataclass class SpriteFrame(DataFrame): - """An animated sprite. Will be shown by the transport if the transport's + """Animated sprite frame containing multiple images. + + An animated sprite that will be shown by the transport if the transport's camera is enabled. Will play at the framerate specified in the transport's `camera_out_framerate` constructor parameter. + Parameters: + images: List of image frames that make up the sprite animation. """ images: List[OutputImageRawFrame] @@ -206,9 +276,14 @@ class SpriteFrame(DataFrame): @dataclass class TextFrame(DataFrame): - """A chunk of text. Emitted by LLM services, consumed by TTS services, can - be used to send text through processors. + """Text data frame for passing text through the pipeline. + A chunk of text. Emitted by LLM services, consumed by context + aggregators, TTS services and more. Can be used to send text + through processors. + + Parameters: + text: The text content. """ text: str @@ -220,23 +295,30 @@ class TextFrame(DataFrame): @dataclass class LLMTextFrame(TextFrame): - """A text frame generated by LLM services.""" + """Text frame generated by LLM services.""" pass @dataclass class TTSTextFrame(TextFrame): - """A text frame generated by TTS services.""" + """Text frame generated by Text-to-Speech services.""" pass @dataclass class TranscriptionFrame(TextFrame): - """A text frame with transcription-specific data. The `result` field + """Text frame containing speech transcription data. + + A text frame with transcription-specific data. The `result` field contains the result from the STT service if available. + Parameters: + user_id: Identifier for the user who spoke. + timestamp: When the transcription occurred. + language: Detected or specified language of the speech. + result: Raw result from the STT service. """ user_id: str @@ -250,9 +332,17 @@ class TranscriptionFrame(TextFrame): @dataclass class InterimTranscriptionFrame(TextFrame): - """A text frame with interim transcription-specific data. The `result` field + """Text frame containing partial/interim transcription data. + + A text frame with interim transcription-specific data that represents + partial results before final transcription. The `result` field contains the result from the STT service if available. + Parameters: + user_id: Identifier for the user who spoke. + timestamp: When the interim transcription occurred. + language: Detected or specified language of the speech. + result: Raw result from the STT service. """ text: str @@ -267,10 +357,15 @@ class InterimTranscriptionFrame(TextFrame): @dataclass class TranslationFrame(TextFrame): - """A text frame with translated transcription data. + """Text frame containing translated transcription data. - Will be placed in the transport's receive queue when a participant speaks. + A text frame with translated transcription data that will be placed + in the transport's receive queue when a participant speaks. + Parameters: + user_id: Identifier for the user who spoke. + timestamp: When the translation occurred. + language: Target language of the translation. """ user_id: str @@ -283,16 +378,27 @@ class TranslationFrame(TextFrame): @dataclass class OpenAILLMContextAssistantTimestampFrame(DataFrame): - """Timestamp information for assistant message in LLM context.""" + """Timestamp information for assistant messages in LLM context. + + Parameters: + timestamp: Timestamp when the assistant message was created. + """ timestamp: str @dataclass class TranscriptionMessage: - """A message in a conversation transcript containing the role and content. + """A message in a conversation transcript. + A message in a conversation transcript containing the role and content. Messages are in standard format with roles normalized to user/assistant. + + Parameters: + role: The role of the message sender (user or assistant). + content: The message content/text. + user_id: Optional identifier for the user. + timestamp: Optional timestamp when the message was created. """ role: Literal["user", "assistant"] @@ -303,39 +409,46 @@ class TranscriptionMessage: @dataclass class TranscriptionUpdateFrame(DataFrame): - """A frame containing new messages added to the conversation transcript. + """Frame containing new messages added to conversation transcript. + A frame containing new messages added to the conversation transcript. This frame is emitted when new messages are added to the conversation history, containing only the newly added messages rather than the full transcript. Messages have normalized roles (user/assistant) regardless of the LLM service used. Messages are always in the OpenAI standard message format, which supports both: - Simple format: - [ - { - "role": "user", - "content": "Hi, how are you?" - }, - { - "role": "assistant", - "content": "Great! And you?" - } - ] + Examples: + Simple format:: - Content list format: - [ - { - "role": "user", - "content": [{"type": "text", "text": "Hi, how are you?"}] - }, - { - "role": "assistant", - "content": [{"type": "text", "text": "Great! And you?"}] - } - ] + [ + { + "role": "user", + "content": "Hi, how are you?" + }, + { + "role": "assistant", + "content": "Great! And you?" + } + ] + + Content list format:: + + [ + { + "role": "user", + "content": [{"type": "text", "text": "Hi, how are you?"}] + }, + { + "role": "assistant", + "content": [{"type": "text", "text": "Great! And you?"}] + } + ] OpenAI supports both formats. Anthropic and Google messages are converted to the content list format. + + Parameters: + messages: List of new transcript messages that were added. """ messages: List[TranscriptionMessage] @@ -347,12 +460,16 @@ class TranscriptionUpdateFrame(DataFrame): @dataclass class LLMMessagesFrame(DataFrame): - """A frame containing a list of LLM messages. Used to signal that an LLM + """Frame containing LLM messages for chat completion. + + A frame containing a list of LLM messages. Used to signal that an LLM service should run a chat completion and emit an LLMFullResponseStartFrame, TextFrames and an LLMFullResponseEndFrame. Note that the `messages` - property in this class is mutable, and will be be updated by various + property in this class is mutable, and will be updated by various aggregators. + Parameters: + messages: List of message dictionaries in LLM format. """ messages: List[dict] @@ -360,9 +477,13 @@ class LLMMessagesFrame(DataFrame): @dataclass class LLMMessagesAppendFrame(DataFrame): - """A frame containing a list of LLM messages that need to be added to the + """Frame containing LLM messages to append to current context. + + A frame containing a list of LLM messages that need to be added to the current context. + Parameters: + messages: List of message dictionaries to append. """ messages: List[dict] @@ -370,10 +491,14 @@ class LLMMessagesAppendFrame(DataFrame): @dataclass class LLMMessagesUpdateFrame(DataFrame): - """A frame containing a list of new LLM messages. These messages will + """Frame containing LLM messages to replace current context. + + A frame containing a list of new LLM messages. These messages will replace the current context LLM messages and should generate a new LLMMessagesFrame. + Parameters: + messages: List of message dictionaries to replace current context. """ messages: List[dict] @@ -381,9 +506,14 @@ class LLMMessagesUpdateFrame(DataFrame): @dataclass class LLMSetToolsFrame(DataFrame): - """A frame containing a list of tools for an LLM to use for function calling. + """Frame containing tools for LLM function calling. + + A frame containing a list of tools for an LLM to use for function calling. The specific format depends on the LLM being used, but it should typically contain JSON Schema objects. + + Parameters: + tools: List of tool/function definitions for the LLM. """ tools: List[dict] @@ -391,23 +521,35 @@ class LLMSetToolsFrame(DataFrame): @dataclass class LLMSetToolChoiceFrame(DataFrame): - """A frame containing a tool choice for an LLM to use for function calling.""" + """Frame containing tool choice configuration for LLM function calling. + + Parameters: + tool_choice: Tool choice setting - 'none', 'auto', 'required', or specific tool dict. + """ tool_choice: Literal["none", "auto", "required"] | dict @dataclass class LLMEnablePromptCachingFrame(DataFrame): - """A frame to enable/disable prompt caching in certain LLMs.""" + """Frame to enable/disable prompt caching in LLMs. + + Parameters: + enable: Whether to enable prompt caching. + """ enable: bool @dataclass class TTSSpeakFrame(DataFrame): - """A frame that contains a text that should be spoken by the TTS in the - pipeline (if any). + """Frame containing text that should be spoken by TTS. + A frame that contains text that should be spoken by the TTS service + in the pipeline (if any). + + Parameters: + text: The text to be spoken. """ text: str @@ -415,6 +557,12 @@ class TTSSpeakFrame(DataFrame): @dataclass class TransportMessageFrame(DataFrame): + """Frame containing transport-specific message data. + + Parameters: + message: The transport message payload. + """ + message: Any def __str__(self): @@ -423,17 +571,22 @@ class TransportMessageFrame(DataFrame): @dataclass class DTMFFrame: - """A DTMF button frame""" + """Base class for DTMF (Dual-Tone Multi-Frequency) keypad frames. + + Parameters: + button: The DTMF keypad entry that was pressed. + """ button: KeypadEntry @dataclass class OutputDTMFFrame(DTMFFrame, DataFrame): - """A DTMF keypress output that will be queued. If your transport supports + """DTMF keypress output frame for transport queuing. + + A DTMF keypress output that will be queued. If your transport supports multiple dial-out destinations, use the `transport_destination` field to specify where the DTMF keypress should be sent. - """ pass @@ -446,7 +599,20 @@ class OutputDTMFFrame(DTMFFrame, DataFrame): @dataclass class StartFrame(SystemFrame): - """This is the first frame that should be pushed down a pipeline.""" + """Initial frame to start pipeline processing. + + This is the first frame that should be pushed down a pipeline to + initialize all processors with their configuration parameters. + + Parameters: + audio_in_sample_rate: Input audio sample rate in Hz. + audio_out_sample_rate: Output audio sample rate in Hz. + allow_interruptions: Whether to allow user interruptions. + enable_metrics: Whether to enable performance metrics collection. + enable_usage_metrics: Whether to enable usage metrics collection. + interruption_strategies: List of interruption handling strategies. + report_only_initial_ttfb: Whether to report only initial time-to-first-byte. + """ audio_in_sample_rate: int = 16000 audio_out_sample_rate: int = 24000 @@ -459,17 +625,26 @@ class StartFrame(SystemFrame): @dataclass class CancelFrame(SystemFrame): - """Indicates that a pipeline needs to stop right away.""" + """Frame indicating pipeline should stop immediately. + + Indicates that a pipeline needs to stop right away without + processing remaining queued frames. + """ pass @dataclass class ErrorFrame(SystemFrame): - """This is used notify upstream that an error has occurred downstream the - pipeline. A fatal error indicates the error is unrecoverable and that the + """Frame notifying of errors in the pipeline. + + This is used to notify upstream that an error has occurred downstream in + the pipeline. A fatal error indicates the error is unrecoverable and that the bot should exit. + Parameters: + error: Description of the error that occurred. + fatal: Whether the error is fatal and requires bot shutdown. """ error: str @@ -481,9 +656,13 @@ class ErrorFrame(SystemFrame): @dataclass class FatalErrorFrame(ErrorFrame): - """This is used notify upstream that an unrecoverable error has occurred and - that the bot should exit. + """Frame notifying of unrecoverable errors requiring bot shutdown. + This is used to notify upstream that an unrecoverable error has occurred and + that the bot should exit immediately. + + Parameters: + fatal: Always True for fatal errors. """ fatal: bool = field(default=True, init=False) @@ -491,10 +670,11 @@ class FatalErrorFrame(ErrorFrame): @dataclass class EndTaskFrame(SystemFrame): - """This is used to notify the pipeline task that the pipeline should be - closed nicely (flushing all the queued frames) by pushing an EndFrame - downstream. + """Frame to request graceful pipeline task closure. + This is used to notify the pipeline task that the pipeline should be + closed nicely (flushing all the queued frames) by pushing an EndFrame + downstream. This frame should be pushed upstream. """ pass @@ -502,9 +682,11 @@ class EndTaskFrame(SystemFrame): @dataclass class CancelTaskFrame(SystemFrame): - """This is used to notify the pipeline task that the pipeline should be - stopped immediately by pushing a CancelFrame downstream. + """Frame to request immediate pipeline task cancellation. + This is used to notify the pipeline task that the pipeline should be + stopped immediately by pushing a CancelFrame downstream. This frame + should be pushed upstream. """ pass @@ -512,10 +694,12 @@ class CancelTaskFrame(SystemFrame): @dataclass class StopTaskFrame(SystemFrame): - """This is used to notify the pipeline task that it should be stopped as - soon as possible (flushing all the queued frames) but that the pipeline - processors should be kept in a running state. + """Frame to request pipeline task stop while keeping processors running. + This is used to notify the pipeline task that it should be stopped as + soon as possible (flushing all the queued frames) but that the pipeline + processors should be kept in a running state. This frame should be pushed + upstream. """ pass @@ -523,11 +707,15 @@ class StopTaskFrame(SystemFrame): @dataclass class FrameProcessorPauseUrgentFrame(SystemFrame): - """This frame is used to pause frame processing for the given processor as + """Frame to pause frame processing immediately. + + This frame is used to pause frame processing for the given processor as fast as possible. Pausing frame processing will keep frames in the internal queue which will then be processed when frame processing is resumed with `FrameProcessorResumeFrame`. + Parameters: + processor: The frame processor to pause. """ processor: "FrameProcessor" @@ -535,10 +723,14 @@ class FrameProcessorPauseUrgentFrame(SystemFrame): @dataclass class FrameProcessorResumeUrgentFrame(SystemFrame): - """This frame is used to resume frame processing for the given processor + """Frame to resume frame processing immediately. + + This frame is used to resume frame processing for the given processor if it was previously paused as fast as possible. After resuming frame processing all queued frames will be processed in the order received. + Parameters: + processor: The frame processor to resume. """ processor: "FrameProcessor" @@ -546,11 +738,12 @@ class FrameProcessorResumeUrgentFrame(SystemFrame): @dataclass class StartInterruptionFrame(SystemFrame): - """Emitted by VAD to indicate that a user has started speaking (i.e. is - interruption). This is similar to UserStartedSpeakingFrame except that it - should be pushed concurrently with other frames (so the order is not - guaranteed). + """Frame indicating user started speaking (interruption detected). + Emitted by the BaseInputTransport to indicate that a user has started + speaking (i.e. is interrupting). This is similar to + UserStartedSpeakingFrame except that it should be pushed concurrently + with other frames (so the order is not guaranteed). """ pass @@ -558,11 +751,12 @@ class StartInterruptionFrame(SystemFrame): @dataclass class StopInterruptionFrame(SystemFrame): - """Emitted by VAD to indicate that a user has stopped speaking (i.e. no more - interruptions). This is similar to UserStoppedSpeakingFrame except that it - should be pushed concurrently with other frames (so the order is not - guaranteed). + """Frame indicating user stopped speaking (interruption ended). + Emitted by the BaseInputTransport to indicate that a user has stopped + speaking (i.e. no more interruptions). This is similar to + UserStoppedSpeakingFrame except that it should be pushed concurrently + with other frames (so the order is not guaranteed). """ pass @@ -570,11 +764,15 @@ class StopInterruptionFrame(SystemFrame): @dataclass class UserStartedSpeakingFrame(SystemFrame): - """Emitted by VAD to indicate that a user has started speaking. This can be + """Frame indicating user has started speaking. + + Emitted by VAD to indicate that a user has started speaking. This can be used for interruptions or other times when detecting that someone is speaking is more important than knowing what they're saying (as you will - with a TranscriptionFrame) + get with a TranscriptionFrame). + Parameters: + emulated: Whether this event was emulated rather than detected by VAD. """ emulated: bool = False @@ -582,14 +780,22 @@ class UserStartedSpeakingFrame(SystemFrame): @dataclass class UserStoppedSpeakingFrame(SystemFrame): - """Emitted by the VAD to indicate that a user stopped speaking.""" + """Frame indicating user has stopped speaking. + + Emitted by the VAD to indicate that a user stopped speaking. + + Parameters: + emulated: Whether this event was emulated rather than detected by VAD. + """ emulated: bool = False @dataclass class EmulateUserStartedSpeakingFrame(SystemFrame): - """Emitted by internal processors upstream to emulate VAD behavior when a + """Frame to emulate user started speaking behavior. + + Emitted by internal processors upstream to emulate VAD behavior when a user starts speaking. """ @@ -598,7 +804,9 @@ class EmulateUserStartedSpeakingFrame(SystemFrame): @dataclass class EmulateUserStoppedSpeakingFrame(SystemFrame): - """Emitted by internal processors upstream to emulate VAD behavior when a + """Frame to emulate user stopped speaking behavior. + + Emitted by internal processors upstream to emulate VAD behavior when a user stops speaking. """ @@ -607,24 +815,27 @@ class EmulateUserStoppedSpeakingFrame(SystemFrame): @dataclass class VADUserStartedSpeakingFrame(SystemFrame): - """Frame emitted when VAD detects the user has definitively started speaking.""" + """Frame emitted when VAD definitively detects user started speaking.""" pass @dataclass class VADUserStoppedSpeakingFrame(SystemFrame): - """Frame emitted when VAD detects the user has definitively stopped speaking.""" + """Frame emitted when VAD definitively detects user stopped speaking.""" pass @dataclass class BotInterruptionFrame(SystemFrame): - """Emitted by when the bot should be interrupted. This will mainly cause the + """Frame indicating the bot should be interrupted. + + Emitted when the bot should be interrupted. This will mainly cause the same actions as if the user interrupted except that the UserStartedSpeakingFrame and UserStoppedSpeakingFrame won't be generated. - + This frame should be pushed upstreams. It results in the BaseInputTransport + starting an interruption by pushing a StartInterruptionFrame downstream. """ pass @@ -632,25 +843,34 @@ class BotInterruptionFrame(SystemFrame): @dataclass class BotStartedSpeakingFrame(SystemFrame): - """Emitted upstream by transport outputs to indicate the bot started speaking.""" + """Frame indicating the bot started speaking. + + Emitted upstream and downstream by the BaseTransportOutput to indicate the + bot started speaking. + """ pass @dataclass class BotStoppedSpeakingFrame(SystemFrame): - """Emitted upstream by transport outputs to indicate the bot stopped speaking.""" + """Frame indicating the bot stopped speaking. + + Emitted upstream and downstream by the BaseTransportOutput to indicate the + bot stopped speaking. + """ pass @dataclass class BotSpeakingFrame(SystemFrame): - """Emitted upstream by transport outputs while the bot is still - speaking. This can be used, for example, to detect when a user is idle. That - is, while the bot is speaking we don't want to trigger any user idle timeout - since the user might be listening. + """Frame indicating the bot is currently speaking. + Emitted upstream and downstream by the BaseOutputTransport while the bot is + still speaking. This can be used, for example, to detect when a user is + idle. That is, while the bot is speaking we don't want to trigger any user + idle timeout since the user might be listening. """ pass @@ -658,21 +878,28 @@ class BotSpeakingFrame(SystemFrame): @dataclass class MetricsFrame(SystemFrame): - """Emitted by processor that can compute metrics like latencies.""" + """Frame containing performance metrics data. + + Emitted by processors that can compute metrics like latencies. + + Parameters: + data: List of metrics data collected by the processor. + """ data: List[MetricsData] @dataclass class FunctionCallFromLLM: - """Represents a function call returned by the LLM to be registered for execution. + """Represents a function call returned by the LLM. - Attributes: - function_name (str): The name of the function. - tool_call_id (str): A unique identifier for the function call. - arguments (Mapping[str, Any]): The arguments for the function. - context (OpenAILLMContext): The LLM context. + Represents a function call returned by the LLM to be registered for execution. + Parameters: + function_name: The name of the function to call. + tool_call_id: A unique identifier for the function call. + arguments: The arguments to pass to the function. + context: The LLM context when the function call was made. """ function_name: str @@ -683,15 +910,28 @@ class FunctionCallFromLLM: @dataclass class FunctionCallsStartedFrame(SystemFrame): - """A frame signaling that one or more function call execution is going to - start.""" + """Frame signaling that function call execution is starting. + + A frame signaling that one or more function call execution is going to + start. + + Parameters: + function_calls: Sequence of function calls that will be executed. + """ function_calls: Sequence[FunctionCallFromLLM] @dataclass class FunctionCallInProgressFrame(SystemFrame): - """A frame signaling that a function call is in progress.""" + """Frame signaling that a function call is currently executing. + + Parameters: + function_name: Name of the function being executed. + tool_call_id: Unique identifier for this function call. + arguments: Arguments passed to the function. + cancel_on_interruption: Whether to cancel this call if interrupted. + """ function_name: str tool_call_id: str @@ -701,7 +941,12 @@ class FunctionCallInProgressFrame(SystemFrame): @dataclass class FunctionCallCancelFrame(SystemFrame): - """A frame to signal a function call has been cancelled.""" + """Frame signaling that a function call has been cancelled. + + Parameters: + function_name: Name of the function that was cancelled. + tool_call_id: Unique identifier for the cancelled function call. + """ function_name: str tool_call_id: str @@ -709,7 +954,12 @@ class FunctionCallCancelFrame(SystemFrame): @dataclass class FunctionCallResultProperties: - """Properties for a function call result frame.""" + """Properties for configuring function call result behavior. + + Parameters: + run_llm: Whether to run the LLM after receiving this result. + on_context_updated: Callback to execute when context is updated. + """ run_llm: Optional[bool] = None on_context_updated: Optional[Callable[[], Awaitable[None]]] = None @@ -717,7 +967,16 @@ class FunctionCallResultProperties: @dataclass class FunctionCallResultFrame(SystemFrame): - """A frame containing the result of an LLM function (tool) call.""" + """Frame containing the result of an LLM function call. + + Parameters: + function_name: Name of the function that was executed. + tool_call_id: Unique identifier for the function call. + arguments: Arguments that were passed to the function. + result: The result returned by the function. + run_llm: Whether to run the LLM after this result. + properties: Additional properties for result handling. + """ function_name: str tool_call_id: str @@ -729,13 +988,23 @@ class FunctionCallResultFrame(SystemFrame): @dataclass class STTMuteFrame(SystemFrame): - """System frame to mute/unmute the STT service.""" + """Frame to mute/unmute the Speech-to-Text service. + + Parameters: + mute: Whether to mute (True) or unmute (False) the STT service. + """ mute: bool @dataclass class TransportMessageUrgentFrame(SystemFrame): + """Frame for urgent transport messages that need immediate processing. + + Parameters: + message: The urgent transport message payload. + """ + message: Any def __str__(self): @@ -744,10 +1013,18 @@ class TransportMessageUrgentFrame(SystemFrame): @dataclass class UserImageRequestFrame(SystemFrame): - """A frame to request an image from the given user. The frame might be + """Frame requesting an image from a specific user. + + A frame to request an image from the given user. The frame might be generated by a function call in which case the corresponding fields will be properly set. + Parameters: + user_id: Identifier of the user to request image from. + context: Optional context for the image request. + function_name: Name of function that generated this request (if any). + tool_call_id: Tool call ID if generated by function call. + video_source: Specific video source to capture from. """ user_id: str @@ -762,10 +1039,11 @@ class UserImageRequestFrame(SystemFrame): @dataclass class InputAudioRawFrame(SystemFrame, AudioRawFrame): - """A chunk of audio usually coming from an input transport. If the transport - supports multiple audio sources (e.g. multiple audio tracks) the source name - will be specified. + """Raw audio input frame from transport. + A chunk of audio usually coming from an input transport. If the transport + supports multiple audio sources (e.g. multiple audio tracks) the source name + will be specified in transport_source. """ def __post_init__(self): @@ -779,10 +1057,11 @@ class InputAudioRawFrame(SystemFrame, AudioRawFrame): @dataclass class InputImageRawFrame(SystemFrame, ImageRawFrame): - """An image usually coming from an input transport. If the transport - supports multiple video sources (e.g. multiple video tracks) the source name - will be specified. + """Raw image input frame from transport. + An image usually coming from an input transport. If the transport + supports multiple video sources (e.g. multiple video tracks) the source name + will be specified in transport_source. """ def __str__(self): @@ -792,7 +1071,13 @@ class InputImageRawFrame(SystemFrame, ImageRawFrame): @dataclass class UserAudioRawFrame(InputAudioRawFrame): - """A chunk of audio, usually coming from an input transport, associated to a user.""" + """Raw audio input frame associated with a specific user. + + A chunk of audio, usually coming from an input transport, associated to a user. + + Parameters: + user_id: Identifier of the user who provided this audio. + """ user_id: str = "" @@ -803,7 +1088,14 @@ class UserAudioRawFrame(InputAudioRawFrame): @dataclass class UserImageRawFrame(InputImageRawFrame): - """An image associated to a user.""" + """Raw image input frame associated with a specific user. + + An image associated to a user, potentially in response to an image request. + + Parameters: + user_id: Identifier of the user who provided this image. + request: The original image request frame if this is a response. + """ user_id: str = "" request: Optional[UserImageRequestFrame] = None @@ -815,7 +1107,13 @@ class UserImageRawFrame(InputImageRawFrame): @dataclass class VisionImageRawFrame(InputImageRawFrame): - """An image with an associated text to ask for a description of it.""" + """Image frame for vision/image analysis with associated text prompt. + + An image with an associated text to ask for a description of it. + + Parameters: + text: Optional text prompt describing what to analyze in the image. + """ text: Optional[str] = None @@ -826,17 +1124,18 @@ class VisionImageRawFrame(InputImageRawFrame): @dataclass class InputDTMFFrame(DTMFFrame, SystemFrame): - """A DTMF keypress input.""" + """DTMF keypress input frame from transport.""" pass @dataclass class OutputDTMFUrgentFrame(DTMFFrame, SystemFrame): - """A DTMF keypress output that will be sent right away. If your transport + """DTMF keypress output frame for immediate sending. + + A DTMF keypress output that will be sent right away. If your transport supports multiple dial-out destinations, use the `transport_destination` field to specify where the DTMF keypress should be sent. - """ pass @@ -849,12 +1148,13 @@ class OutputDTMFUrgentFrame(DTMFFrame, SystemFrame): @dataclass class EndFrame(ControlFrame): - """Indicates that a pipeline has ended and frame processors and pipelines + """Frame indicating pipeline has ended and should shut down. + + Indicates that a pipeline has ended and frame processors and pipelines should be shut down. If the transport receives this frame, it will stop sending frames to its output channel(s) and close all its threads. Note, - that this is a control frame, which means it will received in the order it - was sent (unline system frames). - + that this is a control frame, which means it will be received in the order it + was sent (unlike system frames). """ pass @@ -862,10 +1162,11 @@ class EndFrame(ControlFrame): @dataclass class StopFrame(ControlFrame): - """Indicates that a pipeline should be stopped but that the pipeline + """Frame indicating pipeline should stop but keep processors running. + + Indicates that a pipeline should be stopped but that the pipeline processors should be kept in a running state. This is normally queued from the pipeline task. - """ pass @@ -873,9 +1174,13 @@ class StopFrame(ControlFrame): @dataclass class HeartbeatFrame(ControlFrame): - """This frame is used by the pipeline task as a mechanism to know if the + """Frame used by pipeline task to monitor pipeline health. + + This frame is used by the pipeline task as a mechanism to know if the pipeline is running properly. + Parameters: + timestamp: Timestamp when the heartbeat was generated. """ timestamp: int @@ -883,11 +1188,15 @@ class HeartbeatFrame(ControlFrame): @dataclass class FrameProcessorPauseFrame(ControlFrame): - """This frame is used to pause frame processing for the given + """Frame to pause frame processing for a specific processor. + + This frame is used to pause frame processing for the given processor. Pausing frame processing will keep frames in the internal queue which will then be processed when frame processing is resumed with `FrameProcessorResumeFrame`. + Parameters: + processor: The frame processor to pause. """ processor: "FrameProcessor" @@ -895,10 +1204,14 @@ class FrameProcessorPauseFrame(ControlFrame): @dataclass class FrameProcessorResumeFrame(ControlFrame): - """This frame is used to resume frame processing for the given processor if + """Frame to resume frame processing for a specific processor. + + This frame is used to resume frame processing for the given processor if it was previously paused. After resuming frame processing all queued frames will be processed in the order received. + Parameters: + processor: The frame processor to resume. """ processor: "FrameProcessor" @@ -906,8 +1219,10 @@ class FrameProcessorResumeFrame(ControlFrame): @dataclass class LLMFullResponseStartFrame(ControlFrame): - """Used to indicate the beginning of an LLM response. Following by one or - more TextFrame and a final LLMFullResponseEndFrame. + """Frame indicating the beginning of an LLM response. + + Used to indicate the beginning of an LLM response. Followed by one or + more TextFrames and a final LLMFullResponseEndFrame. """ pass @@ -915,19 +1230,20 @@ class LLMFullResponseStartFrame(ControlFrame): @dataclass class LLMFullResponseEndFrame(ControlFrame): - """Indicates the end of an LLM response.""" + """Frame indicating the end of an LLM response.""" pass @dataclass class TTSStartedFrame(ControlFrame): - """Used to indicate the beginning of a TTS response. Following - TTSAudioRawFrames are part of the TTS response until an + """Frame indicating the beginning of a TTS response. + + Used to indicate the beginning of a TTS response. Following + TTSAudioRawFrames are part of the TTS response until a TTSStoppedFrame. These frames can be used for aggregating audio frames in a transport to optimize the size of frames sent to the session, without needing to control this in the TTS service. - """ pass @@ -935,37 +1251,54 @@ class TTSStartedFrame(ControlFrame): @dataclass class TTSStoppedFrame(ControlFrame): - """Indicates the end of a TTS response.""" + """Frame indicating the end of a TTS response.""" pass @dataclass class ServiceUpdateSettingsFrame(ControlFrame): - """A control frame containing a request to update service settings.""" + """Base frame for updating service settings. + + A control frame containing a request to update service settings. + + Parameters: + settings: Dictionary of setting name to value mappings. + """ settings: Mapping[str, Any] @dataclass class LLMUpdateSettingsFrame(ServiceUpdateSettingsFrame): + """Frame for updating LLM service settings.""" + pass @dataclass class TTSUpdateSettingsFrame(ServiceUpdateSettingsFrame): + """Frame for updating TTS service settings.""" + pass @dataclass class STTUpdateSettingsFrame(ServiceUpdateSettingsFrame): + """Frame for updating STT service settings.""" + pass @dataclass class VADParamsUpdateFrame(ControlFrame): - """A control frame containing a request to update VAD params. Intended + """Frame for updating VAD parameters. + + A control frame containing a request to update VAD params. Intended to be pushed upstream from RTVI processor. + + Parameters: + params: New VAD parameters to apply. """ params: VADParams @@ -973,41 +1306,57 @@ class VADParamsUpdateFrame(ControlFrame): @dataclass class FilterControlFrame(ControlFrame): - """Base control frame for other audio filter frames.""" + """Base control frame for audio filter operations.""" pass @dataclass class FilterUpdateSettingsFrame(FilterControlFrame): - """Control frame to update filter settings.""" + """Frame for updating audio filter settings. + + Parameters: + settings: Dictionary of filter setting name to value mappings. + """ settings: Mapping[str, Any] @dataclass class FilterEnableFrame(FilterControlFrame): - """Control frame to enable or disable the filter at runtime.""" + """Frame for enabling/disabling audio filters at runtime. + + Parameters: + enable: Whether to enable (True) or disable (False) the filter. + """ enable: bool @dataclass class MixerControlFrame(ControlFrame): - """Base control frame for other audio mixer frames.""" + """Base control frame for audio mixer operations.""" pass @dataclass class MixerUpdateSettingsFrame(MixerControlFrame): - """Control frame to update mixer settings.""" + """Frame for updating audio mixer settings. + + Parameters: + settings: Dictionary of mixer setting name to value mappings. + """ settings: Mapping[str, Any] @dataclass class MixerEnableFrame(MixerControlFrame): - """Control frame to enable or disable the mixer at runtime.""" + """Frame for enabling/disabling audio mixer at runtime. + + Parameters: + enable: Whether to enable (True) or disable (False) the mixer. + """ enable: bool diff --git a/src/pipecat/metrics/metrics.py b/src/pipecat/metrics/metrics.py index fbd5f9c8c..4884d14f6 100644 --- a/src/pipecat/metrics/metrics.py +++ b/src/pipecat/metrics/metrics.py @@ -1,22 +1,64 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Metrics data models for Pipecat framework. + +This module defines Pydantic models for various types of metrics data +collected throughout the pipeline, including timing, token usage, and +processing statistics. +""" + from typing import Optional from pydantic import BaseModel class MetricsData(BaseModel): + """Base class for all metrics data. + + Parameters: + processor: Name of the processor generating the metrics. + model: Optional model name associated with the metrics. + """ + processor: str model: Optional[str] = None class TTFBMetricsData(MetricsData): + """Time To First Byte (TTFB) metrics data. + + Parameters: + value: TTFB measurement in seconds. + """ + value: float class ProcessingMetricsData(MetricsData): + """General processing time metrics data. + + Parameters: + value: Processing time measurement in seconds. + """ + value: float class LLMTokenUsage(BaseModel): + """Token usage statistics for LLM operations. + + Parameters: + prompt_tokens: Number of tokens in the input prompt. + completion_tokens: Number of tokens in the generated completion. + total_tokens: Total number of tokens used (prompt + completion). + cache_read_input_tokens: Number of tokens read from cache, if applicable. + cache_creation_input_tokens: Number of tokens used to create cache entries, if applicable. + """ + prompt_tokens: int completion_tokens: int total_tokens: int @@ -26,15 +68,35 @@ class LLMTokenUsage(BaseModel): class LLMUsageMetricsData(MetricsData): + """LLM token usage metrics data. + + Parameters: + value: Token usage statistics for the LLM operation. + """ + value: LLMTokenUsage class TTSUsageMetricsData(MetricsData): + """Text-to-Speech usage metrics data. + + Parameters: + value: Number of characters processed by TTS. + """ + value: int class SmartTurnMetricsData(MetricsData): - """Metrics data for smart turn predictions.""" + """Metrics data for smart turn predictions. + + Parameters: + is_complete: Whether the turn is predicted to be complete. + probability: Confidence probability of the turn completion prediction. + inference_time_ms: Time taken for inference in milliseconds. + server_total_time_ms: Total server processing time in milliseconds. + e2e_processing_time_ms: End-to-end processing time in milliseconds. + """ is_complete: bool probability: float diff --git a/src/pipecat/observers/base_observer.py b/src/pipecat/observers/base_observer.py index 077f6986b..d8a67a373 100644 --- a/src/pipecat/observers/base_observer.py +++ b/src/pipecat/observers/base_observer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base observer classes for monitoring frame flow in the Pipecat pipeline. + +This module provides the foundation for observing frame transfers between +processors without modifying the pipeline structure. Observers can be used +for logging, debugging, analytics, and monitoring pipeline behavior. +""" + from abc import abstractmethod from dataclasses import dataclass @@ -18,19 +25,19 @@ if TYPE_CHECKING: @dataclass class FramePushed: - """Represents an event where a frame is pushed from one processor to another - within the pipeline. + """Event data for frame transfers between processors in the pipeline. - This data structure is typically used by observers to track the flow of - frames through the pipeline for logging, debugging, or analytics purposes. - - Attributes: - source (FrameProcessor): The processor sending the frame. - destination (FrameProcessor): The processor receiving the frame. - frame (Frame): The frame being transferred. - direction (FrameDirection): The direction of the transfer (e.g., downstream or upstream). - timestamp (int): The time when the frame was pushed, based on the pipeline clock. + Represents an event where a frame is pushed from one processor to another + within the pipeline. This data structure is typically used by observers + to track the flow of frames through the pipeline for logging, debugging, + or analytics purposes. + Parameters: + source: The processor sending the frame. + destination: The processor receiving the frame. + frame: The frame being transferred. + direction: The direction of the transfer (e.g., downstream or upstream). + timestamp: The time when the frame was pushed, based on the pipeline clock. """ source: "FrameProcessor" @@ -41,11 +48,12 @@ class FramePushed: class BaseObserver(BaseObject): - """This is the base class for pipeline frame observers. Observers can view - all the frames that go through the pipeline without the need to inject - processors in the pipeline. This can be useful, for example, to implement - frame loggers or debuggers among other things. + """Base class for pipeline frame observers. + Observers can view all frames that flow through the pipeline without + needing to inject processors into the pipeline structure. This enables + non-intrusive monitoring capabilities such as frame logging, debugging, + performance analysis, and analytics collection. """ @abstractmethod @@ -57,7 +65,6 @@ class BaseObserver(BaseObject): transferred through the pipeline. Args: - data (FramePushed): The event data containing details about the frame transfer. - + data: The event data containing details about the frame transfer. """ pass diff --git a/src/pipecat/observers/loggers/debug_log_observer.py b/src/pipecat/observers/loggers/debug_log_observer.py index 1b75a3f7a..a8cf7d2d3 100644 --- a/src/pipecat/observers/loggers/debug_log_observer.py +++ b/src/pipecat/observers/loggers/debug_log_observer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Debug logging observer for frame activity monitoring. + +This module provides a debug observer that logs detailed frame activity +to the console, making it useful for debugging pipeline behavior and +understanding frame flow between processors. +""" + from dataclasses import fields, is_dataclass from enum import Enum, auto from typing import Dict, Optional, Set, Tuple, Type, Union @@ -16,7 +23,12 @@ from pipecat.processors.frame_processor import FrameDirection class FrameEndpoint(Enum): - """Specifies which endpoint (source or destination) to filter on.""" + """Specifies which endpoint (source or destination) to filter on. + + Parameters: + SOURCE: Filter on the source component that is pushing the frame. + DESTINATION: Filter on the destination component receiving the frame. + """ SOURCE = auto() DESTINATION = auto() @@ -28,44 +40,36 @@ class DebugLogObserver(BaseObserver): Automatically extracts and formats data from any frame type, making it useful for debugging pipeline behavior without needing frame-specific observers. - Args: - frame_types: Optional tuple of frame types to log, or a dict with frame type - filters. If None, logs all frame types. - exclude_fields: Optional set of field names to exclude from logging. - Examples: - Log all frames from all services: - ```python - observers = DebugLogObserver() - ``` + Log all frames from all services:: - Log specific frame types from any source/destination: - ```python - from pipecat.frames.frames import TranscriptionFrame, InterimTranscriptionFrame - observers=[ - DebugLogObserver(frame_types=(LLMTextFrame,TranscriptionFrame,)), - ], - ``` + observers = DebugLogObserver() - Log frames with specific source/destination filters: - ```python - from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame - from pipecat.transports.base_output_transport import BaseOutputTransport - from pipecat.services.stt_service import STTService + Log specific frame types from any source/destination:: - observers=[ - DebugLogObserver( - frame_types={ - # Only log StartInterruptionFrame when source is BaseOutputTransport - StartInterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE), - # Only log UserStartedSpeakingFrame when destination is STTService - UserStartedSpeakingFrame: (STTService, FrameEndpoint.DESTINATION), - # Log LLMTextFrame regardless of source or destination type - LLMTextFrame: None, - } - ), - ], - ``` + from pipecat.frames.frames import TranscriptionFrame, InterimTranscriptionFrame + observers=[ + DebugLogObserver(frame_types=(LLMTextFrame,TranscriptionFrame,)), + ] + + Log frames with specific source/destination filters:: + + from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame + from pipecat.transports.base_output_transport import BaseOutputTransport + from pipecat.services.stt_service import STTService + + observers=[ + DebugLogObserver( + frame_types={ + # Only log StartInterruptionFrame when source is BaseOutputTransport + StartInterruptionFrame: (BaseOutputTransport, FrameEndpoint.SOURCE), + # Only log UserStartedSpeakingFrame when destination is STTService + UserStartedSpeakingFrame: (STTService, FrameEndpoint.DESTINATION), + # Log LLMTextFrame regardless of source or destination type + LLMTextFrame: None, + } + ), + ] """ def __init__( @@ -79,14 +83,17 @@ class DebugLogObserver(BaseObserver): """Initialize the debug log observer. Args: - frame_types: Tuple of frame types to log, or a dict mapping frame types to - filter configurations. Filter configs can be: - - None to log all instances of the frame type - - A tuple of (service_type, endpoint) to filter on a specific service - and endpoint (SOURCE or DESTINATION) - If None is provided instead of a tuple/dict, log all frames. - exclude_fields: Set of field names to exclude from logging. If None, only binary - data fields are excluded. + frame_types: Frame types to log. Can be: + + - Tuple of frame types to log all instances + - Dict mapping frame types to filter configurations + - None to log all frames + + Filter configurations can be None (log all instances) or a tuple + of (service_type, endpoint) to filter on specific services. + exclude_fields: Field names to exclude from logging. Defaults to + excluding binary data fields like 'audio', 'image', 'images'. + **kwargs: Additional arguments passed to parent class. """ super().__init__(**kwargs) @@ -113,14 +120,7 @@ class DebugLogObserver(BaseObserver): ) def _format_value(self, value): - """Format a value for logging. - - Args: - value: The value to format. - - Returns: - str: A string representation of the value suitable for logging. - """ + """Format a value for logging.""" if value is None: return "None" elif isinstance(value, str): @@ -143,16 +143,7 @@ class DebugLogObserver(BaseObserver): return str(value) def _should_log_frame(self, frame, src, dst): - """Determine if a frame should be logged based on filters. - - Args: - frame: The frame being processed - src: The source component - dst: The destination component - - Returns: - bool: True if the frame should be logged, False otherwise - """ + """Determine if a frame should be logged based on filters.""" # If no filters, log all frames if not self.frame_filters: return True diff --git a/src/pipecat/observers/loggers/llm_log_observer.py b/src/pipecat/observers/loggers/llm_log_observer.py index a6675b5c0..53a0ac484 100644 --- a/src/pipecat/observers/loggers/llm_log_observer.py +++ b/src/pipecat/observers/loggers/llm_log_observer.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""LLM logging observer for Pipecat.""" + from loguru import logger from pipecat.frames.frames import ( @@ -34,10 +36,15 @@ class LLMLogObserver(BaseObserver): This allows you to track when the LLM starts responding, what it generates, and when it finishes. - """ async def on_push_frame(self, data: FramePushed): + """Handle frame push events and log LLM-related activities. + + Args: + data: The frame push event data containing source, destination, + frame, direction, and timestamp information. + """ src = data.source dst = data.destination frame = data.frame diff --git a/src/pipecat/observers/loggers/transcription_log_observer.py b/src/pipecat/observers/loggers/transcription_log_observer.py index 8ca1d9c9b..1f1a74388 100644 --- a/src/pipecat/observers/loggers/transcription_log_observer.py +++ b/src/pipecat/observers/loggers/transcription_log_observer.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Transcription logging observer for Pipecat. + +This module provides an observer that logs transcription frames to the console, +allowing developers to monitor speech-to-text activity in real-time. +""" + from loguru import logger from pipecat.frames.frames import ( @@ -17,17 +23,23 @@ from pipecat.services.stt_service import STTService class TranscriptionLogObserver(BaseObserver): """Observer to log transcription activity to the console. - Logs all frame instances (only from STT service) of: - - - TranscriptionFrame - - InterimTranscriptionFrame - - This allows you to track when the LLM starts responding, what it generates, - and when it finishes. + Monitors and logs all transcription frames from STT services, including + both final transcriptions and interim results. This allows developers + to track speech recognition activity and debug transcription issues. + Only processes frames from STTService instances to avoid logging + unrelated transcription frames from other sources. """ async def on_push_frame(self, data: FramePushed): + """Handle frame push events and log transcription frames. + + Logs TranscriptionFrame and InterimTranscriptionFrame instances + with timestamps and user information for debugging purposes. + + Args: + data: Frame push event data containing source, frame, and timestamp. + """ src = data.source frame = data.frame timestamp = data.timestamp diff --git a/src/pipecat/observers/loggers/user_bot_latency_log_observer.py b/src/pipecat/observers/loggers/user_bot_latency_log_observer.py index f601a9e9e..eb699f2bb 100644 --- a/src/pipecat/observers/loggers/user_bot_latency_log_observer.py +++ b/src/pipecat/observers/loggers/user_bot_latency_log_observer.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Observer for measuring user-to-bot response latency.""" + import time from loguru import logger @@ -18,19 +20,28 @@ from pipecat.processors.frame_processor import FrameDirection class UserBotLatencyLogObserver(BaseObserver): - """Observer that logs the latency between when the user stops speaking and - when the bot starts speaking. - - This helps measure how quickly the AI services respond. + """Observer that measures time between user stopping speech and bot starting speech. + This helps measure how quickly the AI services respond by tracking + conversation turn timing and logging latency metrics. """ def __init__(self): + """Initialize the latency observer. + + Sets up tracking for processed frames and user speech timing + to calculate response latencies. + """ super().__init__() self._processed_frames = set() self._user_stopped_time = 0 async def on_push_frame(self, data: FramePushed): + """Process frames to track speech timing and calculate latency. + + Args: + data: Frame push event containing the frame and direction information. + """ # Only process downstream frames if data.direction != FrameDirection.DOWNSTREAM: return diff --git a/src/pipecat/observers/turn_tracking_observer.py b/src/pipecat/observers/turn_tracking_observer.py index 04b5ad92b..525101f57 100644 --- a/src/pipecat/observers/turn_tracking_observer.py +++ b/src/pipecat/observers/turn_tracking_observer.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Turn tracking observer for conversation flow monitoring. + +This module provides an observer that monitors conversation turns in a pipeline, +tracking when turns start and end based on user and bot speech patterns. +""" + import asyncio from collections import deque @@ -23,15 +29,30 @@ from pipecat.observers.base_observer import BaseObserver, FramePushed class TurnTrackingObserver(BaseObserver): """Observer that tracks conversation turns in a pipeline. + This observer monitors the flow of conversation by tracking when turns + start and end based on user and bot speaking patterns. It handles + interruptions, timeouts, and maintains turn state throughout the pipeline. + Turn tracking logic: + - The first turn starts immediately when the pipeline starts (StartFrame) - Subsequent turns start when the user starts speaking - A turn ends when the bot stops speaking and either: + - The user starts speaking again - A timeout period elapses with no more bot speech """ def __init__(self, max_frames=100, turn_end_timeout_secs=2.5, **kwargs): + """Initialize the turn tracking observer. + + Args: + max_frames: Maximum number of frame IDs to keep in history for + duplicate detection. Defaults to 100. + turn_end_timeout_secs: Timeout in seconds after bot stops speaking + before automatically ending the turn. Defaults to 2.5. + **kwargs: Additional arguments passed to the parent observer. + """ super().__init__(**kwargs) self._turn_count = 0 self._is_turn_active = False @@ -49,7 +70,11 @@ class TurnTrackingObserver(BaseObserver): self._register_event_handler("on_turn_ended") async def on_push_frame(self, data: FramePushed): - """Process frame events for turn tracking.""" + """Process frame events for turn tracking. + + Args: + data: Frame push event data containing the frame and metadata. + """ # Skip already processed frames if data.frame.id in self._processed_frames: return diff --git a/src/pipecat/pipeline/base_pipeline.py b/src/pipecat/pipeline/base_pipeline.py index b0a08da80..a3b1e0b3e 100644 --- a/src/pipecat/pipeline/base_pipeline.py +++ b/src/pipecat/pipeline/base_pipeline.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base pipeline implementation for frame processing.""" + from abc import abstractmethod from typing import List @@ -11,9 +13,24 @@ from pipecat.processors.frame_processor import FrameProcessor class BasePipeline(FrameProcessor): + """Base class for all pipeline implementations. + + Provides the foundation for pipeline processors that need to support + metrics collection from their contained processors. + """ + def __init__(self): + """Initialize the base pipeline.""" super().__init__() @abstractmethod def processors_with_metrics(self) -> List[FrameProcessor]: + """Return processors that can generate metrics. + + Implementing classes should collect and return all processors within + their pipeline that support metrics generation. + + Returns: + List of frame processors that support metrics collection. + """ pass diff --git a/src/pipecat/pipeline/base_task.py b/src/pipecat/pipeline/base_task.py index 6cdd88c9b..2751f2b7b 100644 --- a/src/pipecat/pipeline/base_task.py +++ b/src/pipecat/pipeline/base_task.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base pipeline task implementation for managing pipeline execution. + +This module provides the abstract base class and configuration for pipeline +tasks that manage the lifecycle and execution of frame processing pipelines. +""" + import asyncio from abc import abstractmethod from dataclasses import dataclass @@ -15,44 +21,81 @@ from pipecat.utils.base_object import BaseObject @dataclass class PipelineTaskParams: - """Specific configuration for the pipeline task.""" + """Configuration parameters for pipeline task execution. + + Parameters: + loop: The asyncio event loop to use for task execution. + """ loop: asyncio.AbstractEventLoop class BasePipelineTask(BaseObject): + """Abstract base class for pipeline task implementations. + + Defines the interface for managing pipeline execution lifecycle, + including starting, stopping, and frame queuing operations. + """ + @abstractmethod def has_finished(self) -> bool: - """Indicates whether the tasks has finished. That is, all processors - have stopped. + """Check if the pipeline task has finished execution. + Returns: + True if all processors have stopped and the task is complete. """ pass @abstractmethod async def stop_when_done(self): - """This is a helper function that sends an EndFrame to the pipeline in - order to stop the task after everything in it has been processed. + """Schedule the pipeline to stop after processing all queued frames. + Implementing classes should send an EndFrame or equivalent signal to + gracefully terminate the pipeline once all current processing is complete. """ pass @abstractmethod async def cancel(self): - """Stops the running pipeline immediately.""" + """Immediately stop the running pipeline. + + Implementing classes should cancel all running tasks and stop frame + processing without waiting for completion. + """ pass @abstractmethod async def run(self, params: PipelineTaskParams): - """Starts running the given pipeline.""" + """Start and run the pipeline with the given parameters. + + Implementing classes should initialize and execute the pipeline using + the provided configuration parameters. + + Args: + params: Configuration parameters for pipeline execution. + """ pass @abstractmethod async def queue_frame(self, frame: Frame): - """Queue a frame to be pushed down the pipeline.""" + """Queue a single frame for processing by the pipeline. + + Implementing classes should add the frame to their processing queue + for downstream handling. + + Args: + frame: The frame to be processed. + """ pass @abstractmethod async def queue_frames(self, frames: Iterable[Frame] | AsyncIterable[Frame]): - """Queues multiple frames to be pushed down the pipeline.""" + """Queue multiple frames for processing by the pipeline. + + Implementing classes should process the iterable/async iterable and + add all frames to their processing queue. + + Args: + frames: An iterable or async iterable of frames to be processed. + """ pass diff --git a/src/pipecat/pipeline/parallel_pipeline.py b/src/pipecat/pipeline/parallel_pipeline.py index 300492cc5..57b3a82c3 100644 --- a/src/pipecat/pipeline/parallel_pipeline.py +++ b/src/pipecat/pipeline/parallel_pipeline.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Parallel pipeline implementation for concurrent frame processing. + +This module provides a parallel pipeline that processes frames through multiple +sub-pipelines concurrently, with coordination for system frames and proper +handling of pipeline lifecycle events. +""" + import asyncio from itertools import chain from typing import Awaitable, Callable, Dict, List @@ -25,16 +32,34 @@ from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue class ParallelPipelineSource(FrameProcessor): + """Source processor for parallel pipeline branches. + + Handles frame routing for parallel pipeline inputs, directing system frames + to the parent push function and other upstream frames to a queue for processing. + """ + def __init__( self, upstream_queue: asyncio.Queue, push_frame_func: Callable[[Frame, FrameDirection], Awaitable[None]], ): + """Initialize the parallel pipeline source. + + Args: + upstream_queue: Queue for collecting upstream frames from this branch. + push_frame_func: Function to push frames to the parent parallel pipeline. + """ super().__init__() self._up_queue = upstream_queue self._push_frame_func = push_frame_func async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames with special handling for system frames. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -48,16 +73,34 @@ class ParallelPipelineSource(FrameProcessor): class ParallelPipelineSink(FrameProcessor): + """Sink processor for parallel pipeline branches. + + Handles frame routing for parallel pipeline outputs, directing system frames + to the parent push function and other downstream frames to a queue for coordination. + """ + def __init__( self, downstream_queue: asyncio.Queue, push_frame_func: Callable[[Frame, FrameDirection], Awaitable[None]], ): + """Initialize the parallel pipeline sink. + + Args: + downstream_queue: Queue for collecting downstream frames from this branch. + push_frame_func: Function to push frames to the parent parallel pipeline. + """ super().__init__() self._down_queue = downstream_queue self._push_frame_func = push_frame_func async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames with special handling for system frames. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -71,7 +114,24 @@ class ParallelPipelineSink(FrameProcessor): class ParallelPipeline(BasePipeline): + """Pipeline that processes frames through multiple sub-pipelines concurrently. + + Creates multiple parallel processing branches from the provided processor lists, + coordinating frame flow and ensuring proper synchronization of lifecycle events + like EndFrames. Each branch runs independently while system frames are handled + specially to maintain pipeline coordination. + """ + def __init__(self, *args): + """Initialize the parallel pipeline with processor lists. + + Args: + *args: Variable number of processor lists, each becoming a parallel branch. + + Raises: + Exception: If no processor lists are provided. + TypeError: If any argument is not a list of processors. + """ super().__init__() if len(args) == 0: @@ -93,6 +153,11 @@ class ParallelPipeline(BasePipeline): # def processors_with_metrics(self) -> List[FrameProcessor]: + """Collect processors that can generate metrics from all parallel branches. + + Returns: + List of frame processors that support metrics collection from all branches. + """ return list(chain.from_iterable(p.processors_with_metrics() for p in self._pipelines)) # @@ -100,6 +165,14 @@ class ParallelPipeline(BasePipeline): # async def setup(self, setup: FrameProcessorSetup): + """Set up the parallel pipeline and all its branches. + + Args: + setup: Configuration for frame processor setup. + + Raises: + TypeError: If any processor list argument is not actually a list. + """ await super().setup(setup) self._up_queue = WatchdogQueue(setup.task_manager) @@ -129,12 +202,19 @@ class ParallelPipeline(BasePipeline): await asyncio.gather(*[s.setup(setup) for s in self._sinks]) async def cleanup(self): + """Clean up the parallel pipeline and all its branches.""" await super().cleanup() await asyncio.gather(*[s.cleanup() for s in self._sources]) await asyncio.gather(*[p.cleanup() for p in self._pipelines]) await asyncio.gather(*[s.cleanup() for s in self._sinks]) async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames through all parallel branches with lifecycle coordination. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) if isinstance(frame, StartFrame): @@ -159,9 +239,11 @@ class ParallelPipeline(BasePipeline): await self._stop() async def _start(self, frame: StartFrame): + """Start the parallel pipeline processing tasks.""" await self._create_tasks() async def _stop(self): + """Stop all parallel pipeline processing tasks.""" if self._up_task: # The up task doesn't receive an EndFrame, so we just cancel it. await self.cancel_task(self._up_task) @@ -174,6 +256,7 @@ class ParallelPipeline(BasePipeline): self._down_task = None async def _cancel(self): + """Cancel all parallel pipeline processing tasks.""" if self._up_task: await self.cancel_task(self._up_task) self._up_task = None @@ -182,34 +265,44 @@ class ParallelPipeline(BasePipeline): self._down_task = None async def _create_tasks(self): + """Create upstream and downstream processing tasks if not already running.""" if not self._up_task: self._up_task = self.create_task(self._process_up_queue()) if not self._down_task: self._down_task = self.create_task(self._process_down_queue()) async def _drain_queues(self): + """Drain all frames from upstream and downstream queues.""" while not self._up_queue.empty: await self._up_queue.get() while not self._down_queue.empty: await self._down_queue.get() async def _handle_interruption(self): + """Handle interruption by cancelling tasks, draining queues, and restarting.""" await self._cancel() await self._drain_queues() await self._create_tasks() async def _parallel_push_frame(self, frame: Frame, direction: FrameDirection): + """Push frames while avoiding duplicates using frame ID tracking.""" if frame.id not in self._seen_ids: self._seen_ids.add(frame.id) await self.push_frame(frame, direction) async def _process_up_queue(self): + """Process upstream frames from all parallel branches.""" while True: frame = await self._up_queue.get() await self._parallel_push_frame(frame, FrameDirection.UPSTREAM) self._up_queue.task_done() async def _process_down_queue(self): + """Process downstream frames with EndFrame coordination. + + Coordinates EndFrames to ensure they are only pushed upstream once + all parallel branches have completed processing them. + """ running = True while running: frame = await self._down_queue.get() diff --git a/src/pipecat/pipeline/pipeline.py b/src/pipecat/pipeline/pipeline.py index c10a32e0a..ee96dd7fc 100644 --- a/src/pipecat/pipeline/pipeline.py +++ b/src/pipecat/pipeline/pipeline.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Pipeline implementation for connecting and managing frame processors. + +This module provides the main Pipeline class that connects frame processors +in sequence and manages frame flow between them, along with helper classes +for pipeline source and sink operations. +""" + from typing import Callable, Coroutine, List from pipecat.frames.frames import Frame @@ -12,11 +19,29 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor, F class PipelineSource(FrameProcessor): + """Source processor that forwards frames to an upstream handler. + + This processor acts as the entry point for a pipeline, forwarding + downstream frames to the next processor and upstream frames to a + provided upstream handler function. + """ + def __init__(self, upstream_push_frame: Callable[[Frame, FrameDirection], Coroutine]): + """Initialize the pipeline source. + + Args: + upstream_push_frame: Coroutine function to handle upstream frames. + """ super().__init__() self._upstream_push_frame = upstream_push_frame async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them based on direction. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -27,11 +52,29 @@ class PipelineSource(FrameProcessor): class PipelineSink(FrameProcessor): + """Sink processor that forwards frames to a downstream handler. + + This processor acts as the exit point for a pipeline, forwarding + upstream frames to the previous processor and downstream frames to a + provided downstream handler function. + """ + def __init__(self, downstream_push_frame: Callable[[Frame, FrameDirection], Coroutine]): + """Initialize the pipeline sink. + + Args: + downstream_push_frame: Coroutine function to handle downstream frames. + """ super().__init__() self._downstream_push_frame = downstream_push_frame async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them based on direction. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -42,7 +85,19 @@ class PipelineSink(FrameProcessor): class Pipeline(BasePipeline): + """Main pipeline implementation that connects frame processors in sequence. + + Creates a linear chain of frame processors with automatic source and sink + processors for external frame handling. Manages processor lifecycle and + provides metrics collection from contained processors. + """ + def __init__(self, processors: List[FrameProcessor]): + """Initialize the pipeline with a list of processors. + + Args: + processors: List of frame processors to connect in sequence. + """ super().__init__() # Add a source and a sink queue so we can forward frames upstream and @@ -58,6 +113,14 @@ class Pipeline(BasePipeline): # def processors_with_metrics(self): + """Return processors that can generate metrics. + + Recursively collects all processors that support metrics generation, + including those from nested pipelines. + + Returns: + List of frame processors that can generate metrics. + """ services = [] for p in self._processors: if isinstance(p, BasePipeline): @@ -71,14 +134,26 @@ class Pipeline(BasePipeline): # async def setup(self, setup: FrameProcessorSetup): + """Set up the pipeline and all contained processors. + + Args: + setup: Configuration for frame processor setup. + """ await super().setup(setup) await self._setup_processors(setup) async def cleanup(self): + """Clean up the pipeline and all contained processors.""" await super().cleanup() await self._cleanup_processors() async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames by routing them through the pipeline. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) if direction == FrameDirection.DOWNSTREAM: @@ -87,14 +162,17 @@ class Pipeline(BasePipeline): await self._sink.queue_frame(frame, FrameDirection.UPSTREAM) async def _setup_processors(self, setup: FrameProcessorSetup): + """Set up all processors in the pipeline.""" for p in self._processors: await p.setup(setup) async def _cleanup_processors(self): + """Clean up all processors in the pipeline.""" for p in self._processors: await p.cleanup() def _link_processors(self): + """Link all processors in sequence and set their parent.""" prev = self._processors[0] for curr in self._processors[1:]: prev.set_parent(self) diff --git a/src/pipecat/pipeline/runner.py b/src/pipecat/pipeline/runner.py index b789fc7ba..d64bf9495 100644 --- a/src/pipecat/pipeline/runner.py +++ b/src/pipecat/pipeline/runner.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Pipeline runner for managing pipeline task execution. + +This module provides the PipelineRunner class that handles the execution +of pipeline tasks with signal handling, garbage collection, and lifecycle +management. +""" + import asyncio import gc import signal @@ -17,6 +24,13 @@ from pipecat.utils.base_object import BaseObject class PipelineRunner(BaseObject): + """Manages the execution of pipeline tasks with lifecycle and signal handling. + + Provides a high-level interface for running pipeline tasks with automatic + signal handling (SIGINT/SIGTERM), optional garbage collection, and proper + cleanup of resources. + """ + def __init__( self, *, @@ -25,6 +39,14 @@ class PipelineRunner(BaseObject): force_gc: bool = False, loop: Optional[asyncio.AbstractEventLoop] = None, ): + """Initialize the pipeline runner. + + Args: + name: Optional name for the runner instance. + handle_sigint: Whether to automatically handle SIGINT/SIGTERM signals. + force_gc: Whether to force garbage collection after task completion. + loop: Event loop to use. If None, uses the current running loop. + """ super().__init__(name=name) self._tasks = {} @@ -36,6 +58,11 @@ class PipelineRunner(BaseObject): self._setup_sigint() async def run(self, task: PipelineTask): + """Run a pipeline task to completion. + + Args: + task: The pipeline task to execute. + """ logger.debug(f"Runner {self} started running {task}") self._tasks[task.name] = task params = PipelineTaskParams(loop=self._loop) @@ -56,27 +83,33 @@ class PipelineRunner(BaseObject): logger.debug(f"Runner {self} finished running {task}") async def stop_when_done(self): + """Schedule all running tasks to stop when their current processing is complete.""" logger.debug(f"Runner {self} scheduled to stop when all tasks are done") await asyncio.gather(*[t.stop_when_done() for t in self._tasks.values()]) async def cancel(self): + """Cancel all running tasks immediately.""" logger.debug(f"Cancelling runner {self}") await asyncio.gather(*[t.cancel() for t in self._tasks.values()]) def _setup_sigint(self): + """Set up signal handlers for graceful shutdown.""" loop = asyncio.get_running_loop() loop.add_signal_handler(signal.SIGINT, lambda *args: self._sig_handler()) loop.add_signal_handler(signal.SIGTERM, lambda *args: self._sig_handler()) def _sig_handler(self): + """Handle interrupt signals by cancelling all tasks.""" if not self._sig_task: self._sig_task = asyncio.create_task(self._sig_cancel()) async def _sig_cancel(self): + """Cancel all running tasks due to signal interruption.""" logger.warning(f"Interruption detected. Cancelling runner {self}") await self.cancel() def _gc_collect(self): + """Force garbage collection and log results.""" collected = gc.collect() logger.debug(f"Garbage collector: collected {collected} objects.") logger.debug(f"Garbage collector: uncollectable objects {gc.garbage}") diff --git a/src/pipecat/pipeline/sync_parallel_pipeline.py b/src/pipecat/pipeline/sync_parallel_pipeline.py index 006290710..6454c3929 100644 --- a/src/pipecat/pipeline/sync_parallel_pipeline.py +++ b/src/pipecat/pipeline/sync_parallel_pipeline.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Synchronous parallel pipeline implementation for concurrent frame processing. + +This module provides a pipeline that processes frames through multiple parallel +pipelines simultaneously, synchronizing their output to maintain frame ordering +and prevent duplicate processing. +""" + import asyncio from dataclasses import dataclass from itertools import chain @@ -20,17 +27,38 @@ from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue @dataclass class SyncFrame(ControlFrame): - """This frame is used to know when the internal pipelines have finished.""" + """Control frame used to synchronize parallel pipeline processing. + + This frame is sent through parallel pipelines to determine when the + internal pipelines have finished processing a batch of frames. + """ pass class SyncParallelPipelineSource(FrameProcessor): + """Source processor for synchronous parallel pipeline processing. + + Routes frames to parallel pipelines and collects upstream responses + for synchronization purposes. + """ + def __init__(self, upstream_queue: asyncio.Queue): + """Initialize the sync parallel pipeline source. + + Args: + upstream_queue: Queue for collecting upstream frames from the pipeline. + """ super().__init__() self._up_queue = upstream_queue async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them based on direction. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -41,11 +69,28 @@ class SyncParallelPipelineSource(FrameProcessor): class SyncParallelPipelineSink(FrameProcessor): + """Sink processor for synchronous parallel pipeline processing. + + Collects downstream frames from parallel pipelines and routes + upstream frames back through the pipeline. + """ + def __init__(self, downstream_queue: asyncio.Queue): + """Initialize the sync parallel pipeline sink. + + Args: + downstream_queue: Queue for collecting downstream frames from the pipeline. + """ super().__init__() self._down_queue = downstream_queue async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them based on direction. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -56,7 +101,28 @@ class SyncParallelPipelineSink(FrameProcessor): class SyncParallelPipeline(BasePipeline): + """Pipeline that processes frames through multiple parallel pipelines synchronously. + + Creates multiple parallel processing paths that all receive the same input frames + and produces synchronized output. Each parallel path is a separate pipeline that + processes frames independently, with synchronization points to ensure consistent + ordering and prevent duplicate frame processing. + + The pipeline uses SyncFrame control frames to coordinate between parallel paths + and ensure all paths have completed processing before moving to the next frame. + """ + def __init__(self, *args): + """Initialize the synchronous parallel pipeline. + + Args: + *args: Variable number of processor lists, each representing a parallel pipeline path. + Each argument should be a list of FrameProcessor instances. + + Raises: + Exception: If no arguments are provided. + TypeError: If any argument is not a list of processors. + """ super().__init__() if len(args) == 0: @@ -72,6 +138,11 @@ class SyncParallelPipeline(BasePipeline): # def processors_with_metrics(self) -> List[FrameProcessor]: + """Collect processors that can generate metrics from all parallel pipelines. + + Returns: + List of frame processors that support metrics collection from all parallel paths. + """ return list(chain.from_iterable(p.processors_with_metrics() for p in self._pipelines)) # @@ -79,6 +150,11 @@ class SyncParallelPipeline(BasePipeline): # async def setup(self, setup: FrameProcessorSetup): + """Set up the parallel pipeline and all contained processors. + + Args: + setup: Configuration for frame processor setup. + """ await super().setup(setup) self._up_queue = WatchdogQueue(setup.task_manager) @@ -113,12 +189,23 @@ class SyncParallelPipeline(BasePipeline): await asyncio.gather(*[s["processor"].setup(setup) for s in self._sinks]) async def cleanup(self): + """Clean up the parallel pipeline and all contained processors.""" await super().cleanup() await asyncio.gather(*[s["processor"].cleanup() for s in self._sources]) await asyncio.gather(*[p.cleanup() for p in self._pipelines]) await asyncio.gather(*[s["processor"].cleanup() for s in self._sinks]) async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames through all parallel pipelines with synchronization. + + Distributes frames to all parallel pipelines and synchronizes their output + to maintain proper ordering and prevent duplicate processing. Uses SyncFrame + control frames to coordinate between parallel paths. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) # The last processor of each pipeline needs to be synchronous otherwise diff --git a/src/pipecat/pipeline/task.py b/src/pipecat/pipeline/task.py index 0cf294b05..a8b55e77c 100644 --- a/src/pipecat/pipeline/task.py +++ b/src/pipecat/pipeline/task.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Pipeline task implementation for managing frame processing pipelines. + +This module provides the main PipelineTask class that orchestrates pipeline +execution, frame routing, lifecycle management, and monitoring capabilities +including heartbeats, idle detection, and observer integration. +""" + import asyncio import time from collections import deque @@ -53,12 +60,13 @@ HEARTBEAT_MONITOR_SECONDS = HEARTBEAT_SECONDS * 10 class PipelineParams(BaseModel): - """Configuration parameters for pipeline execution. These parameters are - usually passed to all frame processors using through `StartFrame`. For other - generic pipeline task parameters use `PipelineTask` constructor arguments - instead. + """Configuration parameters for pipeline execution. - Attributes: + These parameters are usually passed to all frame processors through + StartFrame. For other generic pipeline task parameters use PipelineTask + constructor arguments instead. + + Parameters: allow_interruptions: Whether to allow pipeline interruptions. audio_in_sample_rate: Input audio sample rate in Hz. audio_out_sample_rate: Output audio sample rate in Hz. @@ -66,12 +74,11 @@ class PipelineParams(BaseModel): enable_metrics: Whether to enable metrics collection. enable_usage_metrics: Whether to enable usage metrics. heartbeats_period_secs: Period between heartbeats in seconds. + interruption_strategies: Strategies for bot interruption behavior. observers: [deprecated] Use `observers` arg in `PipelineTask` class. report_only_initial_ttfb: Whether to report only initial time to first byte. send_initial_empty_metrics: Whether to send initial empty metrics. start_metadata: Additional metadata for pipeline start. - interruption_strategies: Strategies for bot interruption behavior. - """ model_config = ConfigDict(arbitrary_types_allowed=True) @@ -97,17 +104,25 @@ class PipelineTaskSource(FrameProcessor): pipeline given to the pipeline task. It allows us to easily push frames downstream to the pipeline and also receive upstream frames coming from the pipeline. - - Args: - up_queue: Queue for upstream frame processing. - """ def __init__(self, up_queue: asyncio.Queue, **kwargs): + """Initialize the pipeline task source. + + Args: + up_queue: Queue for upstream frame processing. + **kwargs: Additional arguments passed to the parent class. + """ super().__init__(**kwargs) self._up_queue = up_queue async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them based on direction. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) match direction: @@ -123,16 +138,25 @@ class PipelineTaskSink(FrameProcessor): This is the sink processor that is linked at the end of the pipeline given to the pipeline task. It allows us to receive downstream frames and act on them, for example, waiting to receive an EndFrame. - - Args: - down_queue: Queue for downstream frame processing. """ def __init__(self, down_queue: asyncio.Queue, **kwargs): + """Initialize the pipeline task sink. + + Args: + down_queue: Queue for downstream frame processing. + **kwargs: Additional arguments passed to the parent class. + """ super().__init__(**kwargs) self._down_queue = down_queue async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and route them to the downstream queue. + + Args: + frame: The frame to process. + direction: The direction of frame flow. + """ await super().process_frame(frame, direction) await self._down_queue.put(frame) @@ -140,69 +164,30 @@ class PipelineTaskSink(FrameProcessor): class PipelineTask(BasePipelineTask): """Manages the execution of a pipeline, handling frame processing and task lifecycle. - It has a couple of event handlers `on_frame_reached_upstream` and - `on_frame_reached_downstream` that are called when upstream frames or - downstream frames reach both ends of pipeline. By default, the events - handlers will not be called unless some filters are set using - `set_reached_upstream_filter` and `set_reached_downstream_filter`. + This class orchestrates pipeline execution with comprehensive monitoring, + event handling, and lifecycle management. It provides event handlers for + various pipeline states and frame types, idle detection, heartbeat monitoring, + and observer integration. - @task.event_handler("on_frame_reached_upstream") - async def on_frame_reached_upstream(task, frame): - ... + Event handlers available: - @task.event_handler("on_frame_reached_downstream") - async def on_frame_reached_downstream(task, frame): - ... + - on_frame_reached_upstream: Called when upstream frames reach the source + - on_frame_reached_downstream: Called when downstream frames reach the sink + - on_idle_timeout: Called when pipeline is idle beyond timeout threshold + - on_pipeline_started: Called when pipeline starts with StartFrame + - on_pipeline_stopped: Called when pipeline stops with StopFrame + - on_pipeline_ended: Called when pipeline ends with EndFrame + - on_pipeline_cancelled: Called when pipeline is cancelled - It also has an event handler that detects when the pipeline is idle. By - default, a pipeline is idle if no `BotSpeakingFrame` or - `LLMFullResponseEndFrame` are received within `idle_timeout_secs`. + Example:: - @task.event_handler("on_idle_timeout") - async def on_pipeline_idle_timeout(task): - ... + @task.event_handler("on_frame_reached_upstream") + async def on_frame_reached_upstream(task, frame): + ... - There are also events to know if a pipeline has been started, stopped, ended - or cancelled. - - @task.event_handler("on_pipeline_started") - async def on_pipeline_started(task, frame: StartFrame): - ... - - @task.event_handler("on_pipeline_stopped") - async def on_pipeline_stopped(task, frame: StopFrame): - ... - - @task.event_handler("on_pipeline_ended") - async def on_pipeline_ended(task, frame: EndFrame): - ... - - @task.event_handler("on_pipeline_cancelled") - async def on_pipeline_cancelled(task, frame: CancelFrame): - ... - - Args: - pipeline: The pipeline to execute. - params: Configuration parameters for the pipeline. - additional_span_attributes: Optional dictionary of attributes to propagate as - OpenTelemetry conversation span attributes. - cancel_on_idle_timeout: Whether the pipeline task should be cancelled if - the idle timeout is reached. - check_dangling_tasks: Whether to check for processors' tasks finishing properly. - clock: Clock implementation for timing operations. - conversation_id: Optional custom ID for the conversation. - enable_tracing: Whether to enable tracing. - enable_turn_tracking: Whether to enable turn tracking. - enable_watchdog_logging: Whether to print task processing times. - enable_watchdog_timers: Whether to enable task watchdog timers. - idle_timeout_frames: A tuple with the frames that should trigger an idle - timeout if not received withing `idle_timeout_seconds`. - idle_timeout_secs: Timeout (in seconds) to consider pipeline idle or - None. If a pipeline is idle the pipeline task will be cancelled - automatically. - observers: List of observers for monitoring pipeline execution. - watchdog_timeout_secs: Watchdog timer timeout (in seconds). A warning - will be logged if the watchdog timer is not reset before this timeout. + @task.event_handler("on_idle_timeout") + async def on_pipeline_idle_timeout(task): + ... """ def __init__( @@ -228,6 +213,32 @@ class PipelineTask(BasePipelineTask): task_manager: Optional[BaseTaskManager] = None, watchdog_timeout_secs: float = WATCHDOG_TIMEOUT, ): + """Initialize the PipelineTask. + + Args: + pipeline: The pipeline to execute. + params: Configuration parameters for the pipeline. + additional_span_attributes: Optional dictionary of attributes to propagate as + OpenTelemetry conversation span attributes. + cancel_on_idle_timeout: Whether the pipeline task should be cancelled if + the idle timeout is reached. + check_dangling_tasks: Whether to check for processors' tasks finishing properly. + clock: Clock implementation for timing operations. + conversation_id: Optional custom ID for the conversation. + enable_tracing: Whether to enable tracing. + enable_turn_tracking: Whether to enable turn tracking. + enable_watchdog_logging: Whether to print task processing times. + enable_watchdog_timers: Whether to enable task watchdog timers. + idle_timeout_frames: A tuple with the frames that should trigger an idle + timeout if not received within `idle_timeout_seconds`. + idle_timeout_secs: Timeout (in seconds) to consider pipeline idle or + None. If a pipeline is idle the pipeline task will be cancelled + automatically. + observers: List of observers for monitoring pipeline execution. + task_manager: Optional task manager for handling asyncio tasks. + watchdog_timeout_secs: Watchdog timer timeout (in seconds). A warning + will be logged if the watchdog timer is not reset before this timeout. + """ super().__init__() self._pipeline = pipeline self._params = params or PipelineParams() @@ -331,60 +342,97 @@ class PipelineTask(BasePipelineTask): @property def params(self) -> PipelineParams: - """Returns the pipeline parameters of this task.""" + """Get the pipeline parameters for this task. + + Returns: + The pipeline parameters configuration. + """ return self._params @property def turn_tracking_observer(self) -> Optional[TurnTrackingObserver]: - """Return the turn tracking observer if enabled.""" + """Get the turn tracking observer if enabled. + + Returns: + The turn tracking observer instance or None if not enabled. + """ return self._turn_tracking_observer @property def turn_trace_observer(self) -> Optional[TurnTraceObserver]: - """Return the turn trace observer if enabled.""" + """Get the turn trace observer if enabled. + + Returns: + The turn trace observer instance or None if not enabled. + """ return self._turn_trace_observer def add_observer(self, observer: BaseObserver): + """Add an observer to monitor pipeline execution. + + Args: + observer: The observer to add to the pipeline monitoring. + """ self._observer.add_observer(observer) async def remove_observer(self, observer: BaseObserver): + """Remove an observer from pipeline monitoring. + + Args: + observer: The observer to remove from pipeline monitoring. + """ await self._observer.remove_observer(observer) def set_reached_upstream_filter(self, types: Tuple[Type[Frame], ...]): - """Sets which frames will be checked before calling the - on_frame_reached_upstream event handler. + """Set which frame types trigger the on_frame_reached_upstream event. + Args: + types: Tuple of frame types to monitor for upstream events. """ self._reached_upstream_types = types def set_reached_downstream_filter(self, types: Tuple[Type[Frame], ...]): - """Sets which frames will be checked before calling the - on_frame_reached_downstream event handler. + """Set which frame types trigger the on_frame_reached_downstream event. + Args: + types: Tuple of frame types to monitor for downstream events. """ self._reached_downstream_types = types def has_finished(self) -> bool: - """Indicates whether the tasks has finished. That is, all processors + """Check if the pipeline task has finished execution. + + This indicates whether the tasks has finished, meaninig all processors have stopped. + Returns: + True if all processors have stopped and the task is complete. """ return self._finished async def stop_when_done(self): - """This is a helper function that sends an EndFrame to the pipeline in - order to stop the task after everything in it has been processed. + """Schedule the pipeline to stop after processing all queued frames. + Sends an EndFrame to gracefully terminate the pipeline once all + current processing is complete. """ logger.debug(f"Task {self} scheduled to stop when done") await self.queue_frame(EndFrame()) async def cancel(self): - """Stops the running pipeline immediately.""" + """Immediately stop the running pipeline. + + Cancels all running tasks and stops frame processing without + waiting for completion. + """ await self._cancel() async def run(self, params: PipelineTaskParams): - """Starts and manages the pipeline execution until completion or cancellation.""" + """Start and manage the pipeline execution until completion or cancellation. + + Args: + params: Configuration parameters for pipeline execution. + """ if self.has_finished(): return cleanup_pipeline = True @@ -440,6 +488,7 @@ class PipelineTask(BasePipelineTask): await self.queue_frame(frame) async def _cancel(self): + """Internal cancellation logic for the pipeline task.""" if not self._cancelled: logger.debug(f"Canceling pipeline task {self}") self._cancelled = True @@ -453,6 +502,7 @@ class PipelineTask(BasePipelineTask): self._process_push_task = None async def _create_tasks(self): + """Create and start all pipeline processing tasks.""" self._process_up_task = self._task_manager.create_task( self._process_up_queue(), f"{self}::_process_up_queue" ) @@ -468,6 +518,7 @@ class PipelineTask(BasePipelineTask): return self._process_push_task def _maybe_start_heartbeat_tasks(self): + """Start heartbeat tasks if heartbeats are enabled and not already running.""" if self._params.enable_heartbeats and self._heartbeat_push_task is None: self._heartbeat_push_task = self._task_manager.create_task( self._heartbeat_push_handler(), f"{self}::_heartbeat_push_handler" @@ -477,12 +528,14 @@ class PipelineTask(BasePipelineTask): ) def _maybe_start_idle_task(self): + """Start idle monitoring task if idle timeout is configured.""" if self._idle_timeout_secs: self._idle_monitor_task = self._task_manager.create_task( self._idle_monitor_handler(), f"{self}::_idle_monitor_handler" ) async def _cancel_tasks(self): + """Cancel all running pipeline tasks.""" await self._observer.stop() if self._process_up_task: @@ -497,6 +550,7 @@ class PipelineTask(BasePipelineTask): await self._maybe_cancel_idle_task() async def _maybe_cancel_heartbeat_tasks(self): + """Cancel heartbeat tasks if they are running.""" if not self._params.enable_heartbeats: return @@ -509,11 +563,13 @@ class PipelineTask(BasePipelineTask): self._heartbeat_monitor_task = None async def _maybe_cancel_idle_task(self): + """Cancel idle monitoring task if it is running.""" if self._idle_timeout_secs and self._idle_monitor_task: await self._task_manager.cancel_task(self._idle_monitor_task) self._idle_monitor_task = None def _initial_metrics_frame(self) -> MetricsFrame: + """Create an initial metrics frame with zero values for all processors.""" processors = self._pipeline.processors_with_metrics() data = [] for p in processors: @@ -522,10 +578,12 @@ class PipelineTask(BasePipelineTask): return MetricsFrame(data=data) async def _wait_for_pipeline_end(self): + """Wait for the pipeline to signal completion.""" await self._pipeline_end_event.wait() self._pipeline_end_event.clear() async def _setup(self, params: PipelineTaskParams): + """Set up the pipeline task and all processors.""" mgr_params = TaskManagerParams( loop=params.loop, enable_watchdog_logging=self._enable_watchdog_logging, @@ -545,6 +603,7 @@ class PipelineTask(BasePipelineTask): await self._sink.setup(setup) async def _cleanup(self, cleanup_pipeline: bool): + """Clean up the pipeline task and processors.""" # Cleanup base object. await self.cleanup() @@ -559,10 +618,11 @@ class PipelineTask(BasePipelineTask): await self._sink.cleanup() async def _process_push_queue(self): - """This is the task that runs the pipeline for the first time by sending + """Process frames from the push queue and send them through the pipeline. + + This is the task that runs the pipeline for the first time by sending a StartFrame and by pushing any other frames queued by the user. It runs until the tasks is cancelled or stopped (e.g. with an EndFrame). - """ self._clock.start() @@ -596,11 +656,12 @@ class PipelineTask(BasePipelineTask): await self._cleanup(cleanup_pipeline) async def _process_up_queue(self): - """This is the task that processes frames coming upstream from the + """Process frames coming upstream from the pipeline. + + This is the task that processes frames coming upstream from the pipeline. These frames might indicate, for example, that we want the pipeline to be stopped (e.g. EndTaskFrame) in which case we would send an EndFrame down the pipeline. - """ while True: frame = await self._up_queue.get() @@ -629,11 +690,12 @@ class PipelineTask(BasePipelineTask): self._up_queue.task_done() async def _process_down_queue(self): - """This tasks process frames coming downstream from the pipeline. For + """Process frames coming downstream from the pipeline. + + This tasks process frames coming downstream from the pipeline. For example, heartbeat frames or an EndFrame which would indicate all processors have handled the EndFrame and therefore we can exit the task cleanly. - """ while True: frame = await self._down_queue.get() @@ -664,7 +726,7 @@ class PipelineTask(BasePipelineTask): self._down_queue.task_done() async def _heartbeat_push_handler(self): - """This tasks pushes a heartbeat frame every heartbeat period.""" + """Push heartbeat frames at regular intervals.""" while True: # Don't use `queue_frame()` because if an EndFrame is queued the # task will just stop waiting for the pipeline to finish not @@ -673,11 +735,12 @@ class PipelineTask(BasePipelineTask): await asyncio.sleep(self._params.heartbeats_period_secs) async def _heartbeat_monitor_handler(self): - """This tasks monitors heartbeat frames. If a heartbeat frame has not + """Monitor heartbeat frames for processing time and timeout detection. + + This task monitors heartbeat frames. If a heartbeat frame has not been received for a long period a warning will be logged. It also logs the time that a heartbeat frame takes to processes, that is how long it takes for the heartbeat frame to traverse all the pipeline. - """ wait_time = HEARTBEAT_MONITOR_SECONDS while True: @@ -692,9 +755,12 @@ class PipelineTask(BasePipelineTask): ) async def _idle_monitor_handler(self): - """This tasks monitors activity in the pipeline. If no frames are - received (heartbeats don't count) the pipeline is considered idle. + """Monitor pipeline activity and detect idle conditions. + Tracks frame activity and triggers idle timeout events when the + pipeline hasn't received relevant frames within the timeout period. + + Note: Heartbeats are excluded from idle detection. """ running = True last_frame_time = 0 @@ -732,10 +798,13 @@ class PipelineTask(BasePipelineTask): running = await self._idle_timeout_detected(frame_buffer) async def _idle_timeout_detected(self, last_frames: Deque[Frame]) -> bool: - """Logic for when the pipeline is idle. + """Handle idle timeout detection and optional cancellation. + + Args: + last_frames: Recent frames received before timeout for debugging. Returns: - bool: Whther the pipeline task is being cancelled or not. + Whether the pipeline task should continue running. """ logger.warning("Idle timeout detected. Last 10 frames received:") for i, frame in enumerate(last_frames, 1): @@ -749,6 +818,7 @@ class PipelineTask(BasePipelineTask): return True def _print_dangling_tasks(self): + """Log any dangling tasks that haven't been properly cleaned up.""" tasks = [t.get_name() for t in self._task_manager.current_tasks()] if tasks: logger.warning(f"Dangling tasks detected: {tasks}") diff --git a/src/pipecat/pipeline/task_observer.py b/src/pipecat/pipeline/task_observer.py index 40f4c953c..cd46f85ef 100644 --- a/src/pipecat/pipeline/task_observer.py +++ b/src/pipecat/pipeline/task_observer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Task observer for managing pipeline frame observers. + +This module provides a proxy observer system that manages multiple observers +for pipeline frame events, ensuring that observer processing doesn't block +the main pipeline execution. +""" + import asyncio import inspect from typing import Dict, List, Optional @@ -17,9 +24,15 @@ from pipecat.utils.asyncio.watchdog_queue import WatchdogQueue @dataclass class Proxy: - """This is the data we receive from the main observer and that we put into - a queue for later processing. + """Proxy data for managing observer tasks and queues. + This represents is the data received from the main observer that + is queued for later processing. + + Parameters: + queue: Queue for frame data awaiting observer processing. + task: Asyncio task running the observer's frame processing loop. + observer: The actual observer instance being proxied. """ queue: asyncio.Queue @@ -28,7 +41,9 @@ class Proxy: class TaskObserver(BaseObserver): - """This is a pipeline frame observer that is meant to be used as a proxy to + """Proxy observer that manages multiple observers without blocking the pipeline. + + This is a pipeline frame observer that is meant to be used as a proxy to the user provided observers. That is, this is the observer that should be passed to the frame processors. Then, every time a frame is pushed this observer will call all the observers registered to the pipeline task. @@ -37,7 +52,6 @@ class TaskObserver(BaseObserver): pipeline by creating a queue and a task for each user observer. When a frame is received, it will be put in a queue for efficiency and later processed by each task. - """ def __init__( @@ -47,6 +61,13 @@ class TaskObserver(BaseObserver): task_manager: BaseTaskManager, **kwargs, ): + """Initialize the TaskObserver. + + Args: + observers: List of observers to manage. Defaults to empty list. + task_manager: Task manager for creating and managing observer tasks. + **kwargs: Additional arguments passed to the base observer. + """ super().__init__(**kwargs) self._observers = observers or [] self._task_manager = task_manager @@ -55,6 +76,11 @@ class TaskObserver(BaseObserver): ) def add_observer(self, observer: BaseObserver): + """Add a new observer to the managed list. + + Args: + observer: The observer to add. + """ # Add the observer to the list. self._observers.append(observer) @@ -65,6 +91,11 @@ class TaskObserver(BaseObserver): self._proxies[observer] = proxy async def remove_observer(self, observer: BaseObserver): + """Remove an observer and clean up its resources. + + Args: + observer: The observer to remove. + """ # If the observer has a proxy, remove it. if observer in self._proxies: proxy = self._proxies[observer] @@ -78,11 +109,11 @@ class TaskObserver(BaseObserver): self._observers.remove(observer) async def start(self): - """Starts all proxy observer tasks.""" + """Start all proxy observer tasks.""" self._proxies = self._create_proxies(self._observers) async def stop(self): - """Stops all proxy observer tasks.""" + """Stop all proxy observer tasks.""" if not self._proxies: return @@ -90,13 +121,20 @@ class TaskObserver(BaseObserver): await self._task_manager.cancel_task(proxy.task) async def on_push_frame(self, data: FramePushed): + """Queue frame data for all managed observers. + + Args: + data: The frame push event data to distribute to observers. + """ for proxy in self._proxies.values(): await proxy.queue.put(data) def _started(self) -> bool: + """Check if the task observer has been started.""" return self._proxies is not None def _create_proxy(self, observer: BaseObserver) -> Proxy: + """Create a proxy for a single observer.""" queue = WatchdogQueue(self._task_manager) task = self._task_manager.create_task( self._proxy_task_handler(queue, observer), @@ -106,6 +144,7 @@ class TaskObserver(BaseObserver): return proxy def _create_proxies(self, observers: List[BaseObserver]) -> Dict[BaseObserver, Proxy]: + """Create proxies for all observers.""" proxies = {} for observer in observers: proxy = self._create_proxy(observer) @@ -113,6 +152,7 @@ class TaskObserver(BaseObserver): return proxies async def _proxy_task_handler(self, queue: asyncio.Queue, observer: BaseObserver): + """Handle frame processing for a single observer.""" warning_reported = False while True: data = await queue.get() diff --git a/src/pipecat/pipeline/to_be_updated/merge_pipeline.py b/src/pipecat/pipeline/to_be_updated/merge_pipeline.py index 27a52894b..4cd825a97 100644 --- a/src/pipecat/pipeline/to_be_updated/merge_pipeline.py +++ b/src/pipecat/pipeline/to_be_updated/merge_pipeline.py @@ -1,3 +1,16 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Sequential pipeline merging for Pipecat. + +This module provides a pipeline implementation that sequentially merges +the output from multiple pipelines, processing them one after another +in a specified order. +""" + from typing import List from pipecat.frames.frames import EndFrame, EndPipeFrame @@ -5,14 +18,31 @@ from pipecat.pipeline.pipeline import Pipeline class SequentialMergePipeline(Pipeline): - """This class merges the sink queues from a list of pipelines. Frames from - each pipeline's sink are merged in the order of pipelines in the list.""" + """Pipeline that sequentially merges output from multiple pipelines. + + This pipeline merges the sink queues from a list of pipelines by processing + frames from each pipeline's sink sequentially in the order specified. Each + pipeline runs to completion before the next one begins processing. + """ def __init__(self, pipelines: List[Pipeline]): + """Initialize the sequential merge pipeline. + + Args: + pipelines: List of pipelines to merge sequentially. Pipelines will + be processed in the order they appear in this list. + """ super().__init__([]) self.pipelines = pipelines async def run_pipeline(self): + """Run all pipelines sequentially and merge their output. + + Processes each pipeline in order, consuming all frames from each + pipeline's sink until an EndFrame or EndPipeFrame is encountered, + then moves to the next pipeline. After all pipelines complete, + sends a final EndFrame to signal completion. + """ for idx, pipeline in enumerate(self.pipelines): while True: frame = await pipeline.sink.get() diff --git a/src/pipecat/processors/aggregators/dtmf_aggregator.py b/src/pipecat/processors/aggregators/dtmf_aggregator.py index 006a7c181..f3485245c 100644 --- a/src/pipecat/processors/aggregators/dtmf_aggregator.py +++ b/src/pipecat/processors/aggregators/dtmf_aggregator.py @@ -33,6 +33,7 @@ class DTMFAggregator(FrameProcessor): The aggregator accumulates digits from InputDTMFFrame instances and flushes when: + - Timeout occurs (configurable idle period) - Termination digit is received (default: '#') - EndFrame or CancelFrame is received diff --git a/src/pipecat/processors/aggregators/llm_response.py b/src/pipecat/processors/aggregators/llm_response.py index 6d27d1ddf..85c4a3b06 100644 --- a/src/pipecat/processors/aggregators/llm_response.py +++ b/src/pipecat/processors/aggregators/llm_response.py @@ -92,7 +92,7 @@ class LLMFullResponseAggregator(FrameProcessor): the complete response via an event handler. The aggregator provides an "on_completion" event that fires when a full - completion is available: + completion is available:: @aggregator.event_handler("on_completion") async def on_completion( @@ -363,6 +363,7 @@ class LLMUserContextAggregator(LLMContextResponseAggregator): 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 @@ -654,6 +655,7 @@ class LLMAssistantContextAggregator(LLMContextResponseAggregator): """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 diff --git a/src/pipecat/processors/aggregators/openai_llm_context.py b/src/pipecat/processors/aggregators/openai_llm_context.py index a8520546a..82edcadb0 100644 --- a/src/pipecat/processors/aggregators/openai_llm_context.py +++ b/src/pipecat/processors/aggregators/openai_llm_context.py @@ -210,9 +210,10 @@ 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. diff --git a/src/pipecat/processors/audio/audio_buffer_processor.py b/src/pipecat/processors/audio/audio_buffer_processor.py index f48d2d6a8..78561b2f9 100644 --- a/src/pipecat/processors/audio/audio_buffer_processor.py +++ b/src/pipecat/processors/audio/audio_buffer_processor.py @@ -39,17 +39,19 @@ class AudioBufferProcessor(FrameProcessor): including sample rate conversion and mono/stereo output. Events: - on_audio_data: Triggered when buffer_size is reached, providing merged audio - on_track_audio_data: Triggered when buffer_size is reached, providing separate tracks - on_user_turn_audio_data: Triggered when user turn has ended, providing that user turn's audio - on_bot_turn_audio_data: Triggered when bot turn has ended, providing that bot turn's audio + + - on_audio_data: Triggered when buffer_size is reached, providing merged audio + - on_track_audio_data: Triggered when buffer_size is reached, providing separate tracks + - on_user_turn_audio_data: Triggered when user turn has ended, providing that user turn's audio + - on_bot_turn_audio_data: Triggered when bot turn has ended, providing that bot turn's audio Audio handling: - - Mono output (num_channels=1): User and bot audio are mixed - - Stereo output (num_channels=2): User audio on left, bot audio on right - - Automatic resampling of incoming audio to match desired sample_rate - - Silence insertion for non-continuous audio streams - - Buffer synchronization between user and bot audio + + - Mono output (num_channels=1): User and bot audio are mixed + - Stereo output (num_channels=2): User audio on left, bot audio on right + - Automatic resampling of incoming audio to match desired sample_rate + - Silence insertion for non-continuous audio streams + - Buffer synchronization between user and bot audio """ def __init__( diff --git a/src/pipecat/processors/transcript_processor.py b/src/pipecat/processors/transcript_processor.py index 856311392..df6dd469b 100644 --- a/src/pipecat/processors/transcript_processor.py +++ b/src/pipecat/processors/transcript_processor.py @@ -84,6 +84,7 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor): This processor aggregates TTS text frames into complete utterances and emits them as transcript messages. Utterances are completed when: + - The bot stops speaking (BotStoppedSpeakingFrame) - The bot is interrupted (StartInterruptionFrame) - The pipeline ends (EndFrame) @@ -108,34 +109,34 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor): TTS services with different formatting patterns. Examples: - Fragments with embedded spacing (concatenated): - ``` + Fragments with embedded spacing (concatenated):: + TTSTextFrame: ["Hello"] TTSTextFrame: [" there"] # Leading space TTSTextFrame: ["!"] TTSTextFrame: [" How"] # Leading space TTSTextFrame: ["'s"] TTSTextFrame: [" it"] # Leading space - ``` + Result: "Hello there! How's it" - Fragments with trailing spaces (concatenated): - ``` + Fragments with trailing spaces (concatenated):: + TTSTextFrame: ["Hel"] TTSTextFrame: ["lo "] # Trailing space TTSTextFrame: ["to "] # Trailing space TTSTextFrame: ["you"] - ``` + Result: "Hello to you" - Word-by-word fragments without spacing (joined with spaces): - ``` + Word-by-word fragments without spacing (joined with spaces):: + TTSTextFrame: ["Hello"] TTSTextFrame: ["there"] TTSTextFrame: ["how"] TTSTextFrame: ["are"] TTSTextFrame: ["you"] - ``` + Result: "Hello there how are you" """ if self._current_text_parts and self._aggregation_start_time: @@ -179,6 +180,7 @@ class AssistantTranscriptProcessor(BaseTranscriptProcessor): """Process frames into assistant conversation messages. Handles different frame types: + - TTSTextFrame: Aggregates text for current utterance - BotStoppedSpeakingFrame: Completes current utterance - StartInterruptionFrame: Completes current utterance due to interruption @@ -221,8 +223,8 @@ class TranscriptProcessor: Provides unified access to user and assistant transcript processors with shared event handling. - Example: - ```python + Example:: + transcript = TranscriptProcessor() pipeline = Pipeline( @@ -242,7 +244,6 @@ class TranscriptProcessor: @transcript.event_handler("on_transcript_update") async def handle_update(processor, frame): print(f"New messages: {frame.messages}") - ``` """ def __init__(self): diff --git a/src/pipecat/processors/user_idle_processor.py b/src/pipecat/processors/user_idle_processor.py index c692642cc..1a442fd8a 100644 --- a/src/pipecat/processors/user_idle_processor.py +++ b/src/pipecat/processors/user_idle_processor.py @@ -28,8 +28,8 @@ class UserIdleProcessor(FrameProcessor): users become idle. It starts monitoring only after the first conversation activity and supports both basic and retry-based callback patterns. - Example: - ``` + Example:: + # Retry callback: async def handle_idle(processor: "UserIdleProcessor", retry_count: int) -> bool: if retry_count < 3: @@ -45,7 +45,6 @@ class UserIdleProcessor(FrameProcessor): callback=handle_idle, timeout=5.0 ) - ``` """ def __init__( @@ -61,11 +60,10 @@ class UserIdleProcessor(FrameProcessor): """Initialize the user idle processor. Args: - callback: Function to call when user is idle. Can be either: - - Basic callback(processor) -> None - - Retry callback(processor, retry_count) -> bool - Return True to continue monitoring for idle events, - Return False to stop the idle monitoring task + callback: Function to call when user is idle. Can be either a basic + callback taking only the processor, or a retry callback taking + the processor and retry count. Retry callbacks should return + True to continue monitoring or False to stop. timeout: Seconds to wait before considering user idle. **kwargs: Additional arguments passed to FrameProcessor. """ diff --git a/src/pipecat/serializers/base_serializer.py b/src/pipecat/serializers/base_serializer.py index c70b1408e..f57165034 100644 --- a/src/pipecat/serializers/base_serializer.py +++ b/src/pipecat/serializers/base_serializer.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Frame serialization interfaces for Pipecat.""" + from abc import ABC, abstractmethod from enum import Enum @@ -11,23 +13,63 @@ from pipecat.frames.frames import Frame, StartFrame class FrameSerializerType(Enum): + """Enumeration of supported frame serialization formats. + + Parameters: + BINARY: Binary serialization format for compact representation. + TEXT: Text-based serialization format for human-readable output. + """ + BINARY = "binary" TEXT = "text" class FrameSerializer(ABC): + """Abstract base class for frame serialization implementations. + + Defines the interface for converting frames to/from serialized formats + for transmission or storage. Subclasses must implement serialization + type detection and the core serialize/deserialize methods. + """ + @property @abstractmethod def type(self) -> FrameSerializerType: + """Get the serialization type supported by this serializer. + + Returns: + The FrameSerializerType indicating binary or text format. + """ pass async def setup(self, frame: StartFrame): + """Initialize the serializer with startup configuration. + + Args: + frame: StartFrame containing initialization parameters. + """ pass @abstractmethod async def serialize(self, frame: Frame) -> str | bytes | None: + """Convert a frame to its serialized representation. + + Args: + frame: The frame to serialize. + + Returns: + Serialized frame data as string, bytes, or None if serialization fails. + """ pass @abstractmethod async def deserialize(self, data: str | bytes) -> Frame | None: + """Convert serialized data back to a frame object. + + Args: + data: Serialized frame data as string or bytes. + + Returns: + Reconstructed Frame object, or None if deserialization fails. + """ pass diff --git a/src/pipecat/serializers/exotel.py b/src/pipecat/serializers/exotel.py index 4e546e442..960cbe74a 100644 --- a/src/pipecat/serializers/exotel.py +++ b/src/pipecat/serializers/exotel.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Exotel Media Streams serializer for Pipecat.""" + import base64 import json from typing import Optional @@ -33,13 +35,14 @@ class ExotelFrameSerializer(FrameSerializer): media streams protocol. It supports audio conversion, DTMF events, and automatic call termination. - Ref Doc for events - https://support.exotel.com/support/solutions/articles/3000108630-working-with-the-stream-and-voicebot-applet + Note: Ref docs for events: + https://support.exotel.com/support/solutions/articles/3000108630-working-with-the-stream-and-voicebot-applet """ class InputParams(BaseModel): """Configuration parameters for ExotelFrameSerializer. - Attributes: + Parameters: exotel_sample_rate: Sample rate used by Exotel, defaults to 8000 Hz. sample_rate: Optional override for pipeline input sample rate. """ diff --git a/src/pipecat/serializers/livekit.py b/src/pipecat/serializers/livekit.py index d856a7a56..3d4188960 100644 --- a/src/pipecat/serializers/livekit.py +++ b/src/pipecat/serializers/livekit.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""LiveKit frame serializer for Pipecat.""" + import ctypes import pickle @@ -21,11 +23,33 @@ except ModuleNotFoundError as e: class LivekitFrameSerializer(FrameSerializer): + """Serializer for converting between Pipecat frames and LiveKit audio frames. + + This serializer handles the conversion of Pipecat's OutputAudioRawFrame objects + to LiveKit AudioFrame objects for transmission, and the reverse conversion + for received audio data. + """ + @property def type(self) -> FrameSerializerType: + """Get the serializer type. + + Returns: + The serializer type indicating binary serialization. + """ return FrameSerializerType.BINARY async def serialize(self, frame: Frame) -> str | bytes | None: + """Serialize a Pipecat frame to LiveKit AudioFrame format. + + Args: + frame: The Pipecat frame to serialize. Only OutputAudioRawFrame + instances are supported. + + Returns: + Pickled LiveKit AudioFrame bytes if frame is OutputAudioRawFrame, + None otherwise. + """ if not isinstance(frame, OutputAudioRawFrame): return None audio_frame = AudioFrame( @@ -37,6 +61,15 @@ class LivekitFrameSerializer(FrameSerializer): return pickle.dumps(audio_frame) async def deserialize(self, data: str | bytes) -> Frame | None: + """Deserialize LiveKit AudioFrame data to a Pipecat frame. + + Args: + data: Pickled data containing a LiveKit AudioFrame. + + Returns: + InputAudioRawFrame containing the deserialized audio data, + or None if deserialization fails. + """ audio_frame: AudioFrame = pickle.loads(data)["frame"] return InputAudioRawFrame( audio=bytes(audio_frame.data), diff --git a/src/pipecat/serializers/plivo.py b/src/pipecat/serializers/plivo.py index 7fcd951d4..d0c19be0a 100644 --- a/src/pipecat/serializers/plivo.py +++ b/src/pipecat/serializers/plivo.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Plivo WebSocket frame serializer for audio streaming.""" + import base64 import json from typing import Optional @@ -38,22 +40,12 @@ class PlivoFrameSerializer(FrameSerializer): When auto_hang_up is enabled (default), the serializer will automatically terminate the Plivo call when an EndFrame or CancelFrame is processed, but requires Plivo credentials to be provided. - - Attributes: - _stream_id: The Plivo Stream ID. - _call_id: The associated Plivo Call ID. - _auth_id: Plivo auth ID for API access. - _auth_token: Plivo authentication token for API access. - _params: Configuration parameters. - _plivo_sample_rate: Sample rate used by Plivo (typically 8kHz). - _sample_rate: Input sample rate for the pipeline. - _resampler: Audio resampler for format conversion. """ class InputParams(BaseModel): """Configuration parameters for PlivoFrameSerializer. - Attributes: + Parameters: plivo_sample_rate: Sample rate used by Plivo, defaults to 8000 Hz. sample_rate: Optional override for pipeline input sample rate. auto_hang_up: Whether to automatically terminate call on EndFrame. diff --git a/src/pipecat/serializers/protobuf.py b/src/pipecat/serializers/protobuf.py index c91c6661e..867fa0674 100644 --- a/src/pipecat/serializers/protobuf.py +++ b/src/pipecat/serializers/protobuf.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Protobuf frame serialization for Pipecat.""" + import dataclasses import json @@ -22,13 +24,25 @@ from pipecat.frames.frames import ( from pipecat.serializers.base_serializer import FrameSerializer, FrameSerializerType -# Data class for converting transport messages into Protobuf format. @dataclasses.dataclass class MessageFrame: + """Data class for converting transport messages into Protobuf format. + + Parameters: + data: JSON-encoded message data for transport. + """ + data: str class ProtobufFrameSerializer(FrameSerializer): + """Serializer for converting Pipecat frames to/from Protocol Buffer format. + + Provides efficient binary serialization for frame transport over network + connections. Supports text, audio, transcription, and message frames with + automatic conversion between transport message types. + """ + SERIALIZABLE_TYPES = { TextFrame: "text", OutputAudioRawFrame: "audio", @@ -46,13 +60,27 @@ class ProtobufFrameSerializer(FrameSerializer): DESERIALIZABLE_FIELDS = {v: k for k, v in DESERIALIZABLE_TYPES.items()} def __init__(self): + """Initialize the Protobuf frame serializer.""" pass @property def type(self) -> FrameSerializerType: + """Get the serializer type. + + Returns: + FrameSerializerType.BINARY indicating binary serialization format. + """ return FrameSerializerType.BINARY async def serialize(self, frame: Frame) -> str | bytes | None: + """Serialize a frame to Protocol Buffer binary format. + + Args: + frame: The frame to serialize. + + Returns: + Serialized frame as bytes, or None if frame type is not serializable. + """ # Wrapping this messages as a JSONFrame to send if isinstance(frame, (TransportMessageFrame, TransportMessageUrgentFrame)): frame = MessageFrame( @@ -75,6 +103,14 @@ class ProtobufFrameSerializer(FrameSerializer): return proto_frame.SerializeToString() async def deserialize(self, data: str | bytes) -> Frame | None: + """Deserialize Protocol Buffer binary data to a frame. + + Args: + data: Binary protobuf data to deserialize. + + Returns: + Deserialized frame instance, or None if deserialization fails. + """ proto = frame_protos.Frame.FromString(data) which = proto.WhichOneof("frame") if which not in self.DESERIALIZABLE_FIELDS: diff --git a/src/pipecat/serializers/telnyx.py b/src/pipecat/serializers/telnyx.py index 5f8a09252..adc235555 100644 --- a/src/pipecat/serializers/telnyx.py +++ b/src/pipecat/serializers/telnyx.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Telnyx WebSocket frame serializer for Pipecat.""" + import base64 import json from typing import Optional @@ -43,22 +45,12 @@ class TelnyxFrameSerializer(FrameSerializer): When auto_hang_up is enabled (default), the serializer will automatically terminate the Telnyx call when an EndFrame or CancelFrame is processed, but requires Telnyx credentials to be provided. - - Attributes: - _stream_id: The Telnyx Stream ID. - _call_control_id: The associated Telnyx Call Control ID. - _api_key: Telnyx API key for API access. - _params: Configuration parameters. - _telnyx_sample_rate: Sample rate used by Telnyx (typically 8kHz). - _sample_rate: Input sample rate for the pipeline. - _resampler: Audio resampler for format conversion. - _hangup_attempted: Flag to track if hang-up has been attempted. """ class InputParams(BaseModel): """Configuration parameters for TelnyxFrameSerializer. - Attributes: + Parameters: telnyx_sample_rate: Sample rate used by Telnyx, defaults to 8000 Hz. sample_rate: Optional override for pipeline input sample rate. inbound_encoding: Audio encoding for data sent to Telnyx (e.g., "PCMU"). diff --git a/src/pipecat/serializers/twilio.py b/src/pipecat/serializers/twilio.py index 26a3fea5e..ae4d54e4d 100644 --- a/src/pipecat/serializers/twilio.py +++ b/src/pipecat/serializers/twilio.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Twilio Media Streams WebSocket protocol serializer for Pipecat.""" + import base64 import json from typing import Optional @@ -38,22 +40,12 @@ class TwilioFrameSerializer(FrameSerializer): When auto_hang_up is enabled (default), the serializer will automatically terminate the Twilio call when an EndFrame or CancelFrame is processed, but requires Twilio credentials to be provided. - - Attributes: - _stream_sid: The Twilio Media Stream SID. - _call_sid: The associated Twilio Call SID. - _account_sid: Twilio account SID for API access. - _auth_token: Twilio authentication token for API access. - _params: Configuration parameters. - _twilio_sample_rate: Sample rate used by Twilio (typically 8kHz). - _sample_rate: Input sample rate for the pipeline. - _resampler: Audio resampler for format conversion. """ class InputParams(BaseModel): """Configuration parameters for TwilioFrameSerializer. - Attributes: + Parameters: twilio_sample_rate: Sample rate used by Twilio, defaults to 8000 Hz. sample_rate: Optional override for pipeline input sample rate. auto_hang_up: Whether to automatically terminate call on EndFrame. diff --git a/src/pipecat/services/anthropic/llm.py b/src/pipecat/services/anthropic/llm.py index 33b9c9e30..d7c703ebb 100644 --- a/src/pipecat/services/anthropic/llm.py +++ b/src/pipecat/services/anthropic/llm.py @@ -538,20 +538,37 @@ class AnthropicLLMContext(OpenAILLMContext): Handles text content and function calls for both user and assistant messages. Args: - obj: Message in Anthropic format: - { - "role": "user/assistant", - "content": str | [{"type": "text/tool_use/tool_result", ...}] - } + obj: Message in Anthropic format. Returns: - List of messages in standard format: - [ + List of messages in standard format. + + Examples: + Input Anthropic format:: + { - "role": "user/assistant/tool", - "content": [{"type": "text", "text": str}] + "role": "assistant", + "content": [ + {"type": "text", "text": "Hello"}, + {"type": "tool_use", "id": "123", "name": "search", "input": {"q": "test"}} + ] } - ] + + Output standard format:: + + [ + {"role": "assistant", "content": [{"type": "text", "text": "Hello"}]}, + { + "role": "assistant", + "tool_calls": [ + { + "type": "function", + "id": "123", + "function": {"name": "search", "arguments": '{"q": "test"}'} + } + ] + } + ] """ # todo: image format (?) # tool_use @@ -613,23 +630,37 @@ class AnthropicLLMContext(OpenAILLMContext): Empty text content is converted to "(empty)". Args: - message: Message in standard format: - { - "role": "user/assistant/tool", - "content": str | [{"type": "text", ...}], - "tool_calls": [{"id": str, "function": {"name": str, "arguments": str}}] - } + message: Message in standard format. Returns: - Message in Anthropic format: - { - "role": "user/assistant", - "content": str | [ - {"type": "text", "text": str} | - {"type": "tool_use", "id": str, "name": str, "input": dict} | - {"type": "tool_result", "tool_use_id": str, "content": str} - ] - } + Message in Anthropic format. + + Examples: + Input standard format:: + + { + "role": "assistant", + "tool_calls": [ + { + "id": "123", + "function": {"name": "search", "arguments": '{"q": "test"}'} + } + ] + } + + Output Anthropic format:: + + { + "role": "assistant", + "content": [ + { + "type": "tool_use", + "id": "123", + "name": "search", + "input": {"q": "test"} + } + ] + } """ # todo: image messages (?) if message["role"] == "tool": diff --git a/src/pipecat/services/aws/llm.py b/src/pipecat/services/aws/llm.py index 283cea601..43015b2bd 100644 --- a/src/pipecat/services/aws/llm.py +++ b/src/pipecat/services/aws/llm.py @@ -207,20 +207,37 @@ class AWSBedrockLLMContext(OpenAILLMContext): Handles text content and function calls for both user and assistant messages. Args: - obj: Message in AWS Bedrock format: - { - "role": "user/assistant", - "content": [{"text": str} | {"toolUse": {...}} | {"toolResult": {...}}] - } + obj: Message in AWS Bedrock format. Returns: - List of messages in standard format: - [ + List of messages in standard format. + + Examples: + AWS Bedrock format input:: + { - "role": "user/assistant/tool", - "content": [{"type": "text", "text": str}] + "role": "assistant", + "content": [ + {"text": "Hello"}, + {"toolUse": {"toolUseId": "123", "name": "search", "input": {"q": "test"}}} + ] } - ] + + Standard format output:: + + [ + {"role": "assistant", "content": [{"type": "text", "text": "Hello"}]}, + { + "role": "assistant", + "tool_calls": [ + { + "type": "function", + "id": "123", + "function": {"name": "search", "arguments": '{"q": "test"}'} + } + ] + } + ] """ role = obj.get("role") content = obj.get("content") @@ -294,23 +311,38 @@ class AWSBedrockLLMContext(OpenAILLMContext): Empty text content is converted to "(empty)". Args: - message: Message in standard format: - { - "role": "user/assistant/tool", - "content": str | [{"type": "text", ...}], - "tool_calls": [{"id": str, "function": {"name": str, "arguments": str}}] - } + message: Message in standard format. Returns: - Message in AWS Bedrock format: - { - "role": "user/assistant", - "content": [ - {"text": str} | - {"toolUse": {"toolUseId": str, "name": str, "input": dict}} | - {"toolResult": {"toolUseId": str, "content": [...], "status": str}} - ] - } + Message in AWS Bedrock format. + + Examples: + Standard format input:: + + { + "role": "assistant", + "tool_calls": [ + { + "id": "123", + "function": {"name": "search", "arguments": '{"q": "test"}'} + } + ] + } + + AWS Bedrock format output:: + + { + "role": "assistant", + "content": [ + { + "toolUse": { + "toolUseId": "123", + "name": "search", + "input": {"q": "test"} + } + } + ] + } """ if message["role"] == "tool": # Try to parse the content as JSON if it looks like JSON diff --git a/src/pipecat/services/aws/utils.py b/src/pipecat/services/aws/utils.py index cfd36b417..a2559d8bc 100644 --- a/src/pipecat/services/aws/utils.py +++ b/src/pipecat/services/aws/utils.py @@ -39,10 +39,8 @@ def get_presigned_url( Args: region: AWS region for the service. - credentials: Dictionary containing AWS credentials with keys: - - access_key: AWS access key ID - - secret_key: AWS secret access key - - session_token: AWS session token (optional) + credentials: Dictionary containing AWS credentials. Must include + 'access_key' and 'secret_key', with optional 'session_token'. language_code: Language code for transcription (e.g., "en-US"). media_encoding: Audio encoding format. Defaults to "pcm". sample_rate: Audio sample rate in Hz. Defaults to 16000. @@ -325,9 +323,10 @@ def decode_event(message): message: Raw event stream message bytes received from AWS. Returns: - Tuple containing: - - Dictionary of parsed headers - - Dictionary of parsed JSON payload + A tuple of (headers, payload) where: + + - headers: Dictionary of parsed headers + - payload: Dictionary of parsed JSON payload Raises: AssertionError: If CRC checksum verification fails. diff --git a/src/pipecat/services/elevenlabs/tts.py b/src/pipecat/services/elevenlabs/tts.py index 7153c39c5..13cb08255 100644 --- a/src/pipecat/services/elevenlabs/tts.py +++ b/src/pipecat/services/elevenlabs/tts.py @@ -764,21 +764,23 @@ class ElevenLabsHttpTTSService(WordTTSService): def calculate_word_times(self, alignment_info: Mapping[str, Any]) -> List[Tuple[str, float]]: """Calculate word timing from character alignment data. - Example input data: - { - "characters": [" ", "H", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d"], - "character_start_times_seconds": [0.0, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9], - "character_end_times_seconds": [0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] - } - - Would produce word times (with cumulative_time=0): - [("Hello", 0.1), ("world", 0.5)] - Args: alignment_info: Character timing data from ElevenLabs. Returns: List of (word, timestamp) pairs. + + Example input data:: + + { + "characters": [" ", "H", "e", "l", "l", "o", " ", "w", "o", "r", "l", "d"], + "character_start_times_seconds": [0.0, 0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9], + "character_end_times_seconds": [0.1, 0.15, 0.2, 0.25, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0] + } + + Would produce word times (with cumulative_time=0):: + + [("Hello", 0.1), ("world", 0.5)] """ chars = alignment_info.get("characters", []) char_start_times = alignment_info.get("character_start_times_seconds", []) diff --git a/src/pipecat/services/google/google.py b/src/pipecat/services/google/google.py index ec187000f..3b4f03a86 100644 --- a/src/pipecat/services/google/google.py +++ b/src/pipecat/services/google/google.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Google services module for Pipecat.""" + import sys from pipecat.services import DeprecatedModuleProxy diff --git a/src/pipecat/services/google/llm.py b/src/pipecat/services/google/llm.py index 86ed4dd88..b4ddb3c00 100644 --- a/src/pipecat/services/google/llm.py +++ b/src/pipecat/services/google/llm.py @@ -380,18 +380,48 @@ class GoogleLLMContext(OpenAILLMContext): System messages are stored separately and return None. Args: - message: Message in standard format: - { - "role": "user/assistant/system/tool", - "content": str | [{"type": "text/image_url", ...}] | None, - "tool_calls": [{"function": {"name": str, "arguments": str}}] - } + message: Message in standard format. Returns: - Content object with: - - role: "user" or "model" (converted from "assistant") - - parts: List[Part] containing text, inline_data, or function calls - Returns None for system messages. + Content object with role and parts, or None for system messages. + + Examples: + Standard text message:: + + { + "role": "user", + "content": "Hello there" + } + + Converts to Google Content with:: + + Content( + role="user", + parts=[Part(text="Hello there")] + ) + + Standard function call message:: + + { + "role": "assistant", + "tool_calls": [ + { + "function": { + "name": "search", + "arguments": '{"query": "test"}' + } + } + ] + } + + Converts to Google Content with:: + + Content( + role="model", + parts=[Part(function_call=FunctionCall(name="search", args={"query": "test"}))] + ) + + System message returns None and stores content in self.system_message. """ role = message["role"] content = message.get("content", []) @@ -447,21 +477,73 @@ class GoogleLLMContext(OpenAILLMContext): Handles text, images, and function calls from Google's Content/Part objects. Args: - obj: Google Content object with: - - role: "model" (converted to "assistant") or "user" - - parts: List[Part] containing text, inline_data, or function calls + obj: Google Content object with role and parts. Returns: - List of messages in standard format: - [ - { - "role": "user/assistant/tool", - "content": [ - {"type": "text", "text": str} | - {"type": "image_url", "image_url": {"url": str}} - ] - } - ] + List containing a single message in standard format. + + Examples: + Google Content with text:: + + Content( + role="user", + parts=[Part(text="Hello")] + ) + + Converts to:: + + [ + { + "role": "user", + "content": [{"type": "text", "text": "Hello"}] + } + ] + + Google Content with function call:: + + Content( + role="model", + parts=[Part(function_call=FunctionCall(name="search", args={"q": "test"}))] + ) + + Converts to:: + + [ + { + "role": "assistant", + "tool_calls": [ + { + "id": "search", + "type": "function", + "function": { + "name": "search", + "arguments": '{"q": "test"}' + } + } + ] + } + ] + + Google Content with image:: + + Content( + role="user", + parts=[Part(inline_data=Blob(mime_type="image/jpeg", data=bytes_data))] + ) + + Converts to:: + + [ + { + "role": "user", + "content": [ + { + "type": "image_url", + "image_url": {"url": "data:image/jpeg;base64,"} + } + ] + } + ] """ msg = {"role": obj.role, "content": []} if msg["role"] == "model": diff --git a/src/pipecat/services/google/tts.py b/src/pipecat/services/google/tts.py index 40de8afff..0bd201c4b 100644 --- a/src/pipecat/services/google/tts.py +++ b/src/pipecat/services/google/tts.py @@ -471,8 +471,8 @@ class GoogleTTSService(TTSService): default application credentials (GOOGLE_APPLICATION_CREDENTIALS env var). Only Chirp 3 HD and Journey voices are supported. Use GoogleHttpTTSService for other voices. - Example: - ```python + Example:: + tts = GoogleTTSService( credentials_path="/path/to/service-account.json", voice_id="en-US-Chirp3-HD-Charon", @@ -480,7 +480,6 @@ class GoogleTTSService(TTSService): language=Language.EN_US, ) ) - ``` """ class InputParams(BaseModel): diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index 6ef85951a..68a74335b 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -128,13 +128,14 @@ class LLMService(AIService): parallel and sequential execution modes. Provides event handlers for completion timeouts and function call lifecycle events. - Event handlers: - on_completion_timeout: Called when an LLM completion timeout occurs. - on_function_calls_started: Called when function calls are received and - execution is about to start. + The service supports the following event handlers: + + - on_completion_timeout: Called when an LLM completion timeout occurs + - on_function_calls_started: Called when function calls are received and + execution is about to start + + Example:: - Example: - ```python @task.event_handler("on_completion_timeout") async def on_completion_timeout(service): logger.warning("LLM completion timed out") @@ -142,7 +143,6 @@ class LLMService(AIService): @task.event_handler("on_function_calls_started") async def on_function_calls_started(service, function_calls): logger.info(f"Starting {len(function_calls)} function calls") - ``` """ # OpenAILLMAdapter is used as the default adapter since it aligns with most LLM implementations. diff --git a/src/pipecat/services/openai_realtime_beta/openai.py b/src/pipecat/services/openai_realtime_beta/openai.py index ce21e33ad..eb8925760 100644 --- a/src/pipecat/services/openai_realtime_beta/openai.py +++ b/src/pipecat/services/openai_realtime_beta/openai.py @@ -639,6 +639,7 @@ class OpenAIRealtimeBetaLLMService(LLMService): """Maybe handle an error event related to retrieving a conversation item. If the given error event is an error retrieving a conversation item: + - set an exception on the future that retrieve_conversation_item() is waiting on - return true Otherwise: diff --git a/src/pipecat/services/sarvam/tts.py b/src/pipecat/services/sarvam/tts.py index eee4048cb..51fd4f07b 100644 --- a/src/pipecat/services/sarvam/tts.py +++ b/src/pipecat/services/sarvam/tts.py @@ -59,8 +59,8 @@ class SarvamTTSService(TTSService): Indian languages. Provides control over voice characteristics like pitch, pace, and loudness. - Example: - ```python + Example:: + tts = SarvamTTSService( api_key="your-api-key", voice_id="anushka", @@ -72,7 +72,6 @@ class SarvamTTSService(TTSService): pace=1.2 ) ) - ``` """ class InputParams(BaseModel): diff --git a/src/pipecat/services/tavus/video.py b/src/pipecat/services/tavus/video.py index 999d712d0..9f40b709d 100644 --- a/src/pipecat/services/tavus/video.py +++ b/src/pipecat/services/tavus/video.py @@ -42,6 +42,7 @@ class TavusVideoService(AIService): are routed through Pipecat's media pipeline. In use cases with DailyTransport, this creates two distinct virtual rooms: + - Tavus room: Contains the Tavus Avatar and the Pipecat Bot - User room: Contains the Pipecat Bot and the user """ diff --git a/src/pipecat/services/tts_service.py b/src/pipecat/services/tts_service.py index 183ef1f19..1d97045fe 100644 --- a/src/pipecat/services/tts_service.py +++ b/src/pipecat/services/tts_service.py @@ -549,12 +549,11 @@ class WebsocketTTSService(TTSService, WebsocketService): Event handlers: on_connection_error: Called when a websocket connection error occurs. - Example: - ```python + Example:: + @tts.event_handler("on_connection_error") async def on_connection_error(tts: TTSService, error: str): logger.error(f"TTS connection error: {error}") - ``` """ def __init__(self, *, reconnect_on_error: bool = True, **kwargs): @@ -622,12 +621,11 @@ class WebsocketWordTTSService(WordTTSService, WebsocketService): Event handlers: on_connection_error: Called when a websocket connection error occurs. - Example: - ```python + Example:: + @tts.event_handler("on_connection_error") async def on_connection_error(tts: TTSService, error: str): logger.error(f"TTS connection error: {error}") - ``` """ def __init__(self, *, reconnect_on_error: bool = True, **kwargs): diff --git a/src/pipecat/sync/base_notifier.py b/src/pipecat/sync/base_notifier.py index 69a27b445..60321e282 100644 --- a/src/pipecat/sync/base_notifier.py +++ b/src/pipecat/sync/base_notifier.py @@ -4,14 +4,33 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base notifier interface for Pipecat.""" + from abc import ABC, abstractmethod class BaseNotifier(ABC): + """Abstract base class for notification mechanisms. + + Provides a standard interface for implementing notification and waiting + patterns used for event coordination and signaling between components + in the Pipecat framework. + """ + @abstractmethod async def notify(self): + """Send a notification signal. + + Implementations should trigger any waiting coroutines or processes + that are blocked on this notifier. + """ pass @abstractmethod async def wait(self): + """Wait for a notification signal. + + Implementations should block until a notification is received + from the corresponding notify() call. + """ pass diff --git a/src/pipecat/sync/event_notifier.py b/src/pipecat/sync/event_notifier.py index f62ba4f6f..6708c2404 100644 --- a/src/pipecat/sync/event_notifier.py +++ b/src/pipecat/sync/event_notifier.py @@ -4,18 +4,42 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Event-based notifier implementation using asyncio Event primitives.""" + import asyncio from pipecat.sync.base_notifier import BaseNotifier class EventNotifier(BaseNotifier): + """Event-based notifier using asyncio.Event for task synchronization. + + Provides a simple notification mechanism where one task can signal + an event and other tasks can wait for that event to occur. The event + is automatically cleared after each wait operation. + """ + def __init__(self): + """Initialize the event notifier. + + Creates an internal asyncio.Event for managing notifications. + """ self._event = asyncio.Event() async def notify(self): + """Signal the event to notify waiting tasks. + + Sets the internal event, causing any tasks waiting on this + notifier to be awakened. + """ self._event.set() async def wait(self): + """Wait for the event to be signaled. + + Blocks until another task calls notify(). Automatically clears + the event after being awakened so subsequent calls will wait + for the next notification. + """ await self._event.wait() self._event.clear() diff --git a/src/pipecat/tests/utils.py b/src/pipecat/tests/utils.py index 3ea52bf26..2c0f65b2d 100644 --- a/src/pipecat/tests/utils.py +++ b/src/pipecat/tests/utils.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Testing utilities for Pipecat pipeline components.""" + import asyncio from dataclasses import dataclass from typing import Any, Awaitable, Callable, Dict, List, Optional, Sequence, Tuple @@ -24,15 +26,27 @@ from pipecat.processors.frame_processor import FrameDirection, FrameProcessor @dataclass class SleepFrame(SystemFrame): - """This frame is used by test framework to introduce some sleep time before - the next frame is pushed. This is useful to control system frames vs data or - control frames. + """A system frame that introduces a sleep delay in the test pipeline. + + This frame is used by the test framework to control timing between + frame processing, allowing tests to separate system frames from + data or control frames. + + Parameters: + sleep: Duration to sleep in seconds before processing the next frame. """ sleep: float = 0.1 class HeartbeatsObserver(BaseObserver): + """Observer that monitors heartbeat frames from a specific processor. + + This observer watches for HeartbeatFrames from a target processor and + invokes a callback when they are detected, useful for testing timing + and lifecycle events. + """ + def __init__( self, *, @@ -40,11 +54,23 @@ class HeartbeatsObserver(BaseObserver): heartbeat_callback: Callable[[FrameProcessor, HeartbeatFrame], Awaitable[None]], **kwargs, ): + """Initialize the heartbeats observer. + + Args: + target: The frame processor to monitor for heartbeat frames. + heartbeat_callback: Async callback function to invoke when heartbeats are detected. + **kwargs: Additional arguments passed to the parent observer. + """ super().__init__(**kwargs) self._target = target self._callback = heartbeat_callback async def on_push_frame(self, data: FramePushed): + """Handle frame push events and detect heartbeats from target processor. + + Args: + data: The frame push event data containing source and frame information. + """ src = data.source frame = data.frame @@ -53,6 +79,13 @@ class HeartbeatsObserver(BaseObserver): class QueuedFrameProcessor(FrameProcessor): + """A processor that captures frames in a queue for testing purposes. + + This processor intercepts frames flowing in a specific direction and + stores them in a queue for later inspection during testing, while + still allowing the frames to continue through the pipeline. + """ + def __init__( self, *, @@ -60,12 +93,25 @@ class QueuedFrameProcessor(FrameProcessor): queue_direction: FrameDirection, ignore_start: bool = True, ): + """Initialize the queued frame processor. + + Args: + queue: The asyncio queue to store captured frames. + queue_direction: The direction of frames to capture (UPSTREAM or DOWNSTREAM). + ignore_start: Whether to ignore StartFrames when capturing. + """ super().__init__() self._queue = queue self._queue_direction = queue_direction self._ignore_start = ignore_start async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and capture them in the queue if they match the direction. + + Args: + frame: The frame to process. + direction: The direction the frame is flowing. + """ await super().process_frame(frame, direction) if direction == self._queue_direction: @@ -85,6 +131,28 @@ async def run_test( start_metadata: Optional[Dict[str, Any]] = None, send_end_frame: bool = True, ) -> Tuple[Sequence[Frame], Sequence[Frame]]: + """Run a test pipeline with the specified processor and validate frame flow. + + This function creates a test pipeline with the given processor, sends the + specified frames through it, and validates that the expected frames are + received in both upstream and downstream directions. + + Args: + processor: The frame processor to test. + frames_to_send: Sequence of frames to send through the processor. + expected_down_frames: Expected frame types flowing downstream (optional). + expected_up_frames: Expected frame types flowing upstream (optional). + ignore_start: Whether to ignore StartFrames in frame validation. + observers: Optional list of observers to attach to the pipeline. + start_metadata: Optional metadata to include with the StartFrame. + send_end_frame: Whether to send an EndFrame at the end of the test. + + Returns: + Tuple containing (downstream_frames, upstream_frames) that were received. + + Raises: + AssertionError: If the received frames don't match the expected frame types. + """ observers = observers or [] start_metadata = start_metadata or {} diff --git a/src/pipecat/transports/base_input.py b/src/pipecat/transports/base_input.py index 93cd90825..5b71ba69c 100644 --- a/src/pipecat/transports/base_input.py +++ b/src/pipecat/transports/base_input.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base input transport implementation for Pipecat. + +This module provides the BaseInputTransport class which handles audio and video +input processing, including VAD, turn analysis, and interruption management. +""" + import asyncio from concurrent.futures import ThreadPoolExecutor from typing import Optional @@ -47,7 +53,20 @@ AUDIO_INPUT_TIMEOUT_SECS = 0.5 class BaseInputTransport(FrameProcessor): + """Base class for input transport implementations. + + Handles audio and video input processing including Voice Activity Detection, + turn analysis, audio filtering, and user interaction management. Supports + interruption handling and provides hooks for transport-specific implementations. + """ + def __init__(self, params: TransportParams, **kwargs): + """Initialize the base input transport. + + Args: + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(**kwargs) self._params = params @@ -115,25 +134,54 @@ class BaseInputTransport(FrameProcessor): self._params.video_out_color_format = self._params.camera_out_color_format def enable_audio_in_stream_on_start(self, enabled: bool) -> None: + """Enable or disable audio streaming on transport start. + + Args: + enabled: Whether to start audio streaming immediately on transport start. + """ logger.debug(f"Enabling audio on start. {enabled}") self._params.audio_in_stream_on_start = enabled async def start_audio_in_streaming(self): + """Start audio input streaming. + + Override in subclasses to implement transport-specific audio streaming. + """ pass @property def sample_rate(self) -> int: + """Get the current audio sample rate. + + Returns: + The sample rate in Hz. + """ return self._sample_rate @property def vad_analyzer(self) -> Optional[VADAnalyzer]: + """Get the Voice Activity Detection analyzer. + + Returns: + The VAD analyzer instance if configured, None otherwise. + """ return self._params.vad_analyzer @property def turn_analyzer(self) -> Optional[BaseTurnAnalyzer]: + """Get the turn-taking analyzer. + + Returns: + The turn analyzer instance if configured, None otherwise. + """ return self._params.turn_analyzer async def start(self, frame: StartFrame): + """Start the input transport and initialize components. + + Args: + frame: The start frame containing initialization parameters. + """ self._paused = False self._user_speaking = False @@ -152,6 +200,11 @@ class BaseInputTransport(FrameProcessor): await self._params.audio_in_filter.start(self._sample_rate) async def stop(self, frame: EndFrame): + """Stop the input transport and cleanup resources. + + Args: + frame: The end frame signaling transport shutdown. + """ # Cancel and wait for the audio input task to finish. await self._cancel_audio_task() # Stop audio filter. @@ -159,6 +212,11 @@ class BaseInputTransport(FrameProcessor): await self._params.audio_in_filter.stop() async def pause(self, frame: StopFrame): + """Pause the input transport temporarily. + + Args: + frame: The stop frame signaling transport pause. + """ self._paused = True # Cancel task so we clear the queue await self._cancel_audio_task() @@ -166,19 +224,38 @@ class BaseInputTransport(FrameProcessor): self._create_audio_task() async def cancel(self, frame: CancelFrame): + """Cancel the input transport and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ # Cancel and wait for the audio input task to finish. await self._cancel_audio_task() async def set_transport_ready(self, frame: StartFrame): - """To be called when the transport is ready to stream.""" + """Called when the transport is ready to stream. + + Args: + frame: The start frame containing initialization parameters. + """ # Create audio input queue and task if needed. self._create_audio_task() async def push_video_frame(self, frame: InputImageRawFrame): + """Push a video frame downstream if video input is enabled. + + Args: + frame: The input video frame to process. + """ if self._params.video_in_enabled and not self._paused: await self.push_frame(frame) async def push_audio_frame(self, frame: InputAudioRawFrame): + """Push an audio frame to the processing queue if audio input is enabled. + + Args: + frame: The input audio frame to process. + """ if self._params.audio_in_enabled and not self._paused: await self._audio_in_queue.put(frame) @@ -187,6 +264,12 @@ class BaseInputTransport(FrameProcessor): # async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process incoming frames and handle transport-specific logic. + + Args: + frame: The frame to process. + direction: The direction of frame flow in the pipeline. + """ await super().process_frame(frame, direction) # Specific system frames @@ -238,12 +321,14 @@ class BaseInputTransport(FrameProcessor): # async def _handle_bot_interruption(self, frame: BotInterruptionFrame): + """Handle bot interruption frames.""" logger.debug("Bot interruption") if self.interruptions_allowed: await self._start_interruption() await self.push_frame(StartInterruptionFrame()) async def _handle_user_interruption(self, frame: Frame): + """Handle user interruption events based on speaking state.""" if isinstance(frame, UserStartedSpeakingFrame): logger.debug("User started speaking") self._user_speaking = True @@ -281,9 +366,11 @@ class BaseInputTransport(FrameProcessor): # async def _handle_bot_started_speaking(self, frame: BotStartedSpeakingFrame): + """Update bot speaking state when bot starts speaking.""" self._bot_speaking = True async def _handle_bot_stopped_speaking(self, frame: BotStoppedSpeakingFrame): + """Update bot speaking state when bot stops speaking.""" self._bot_speaking = False # @@ -291,16 +378,19 @@ class BaseInputTransport(FrameProcessor): # def _create_audio_task(self): + """Create the audio processing task if audio input is enabled.""" if not self._audio_task and self._params.audio_in_enabled: self._audio_in_queue = asyncio.Queue() self._audio_task = self.create_task(self._audio_task_handler()) async def _cancel_audio_task(self): + """Cancel and cleanup the audio processing task.""" if self._audio_task: await self.cancel_task(self._audio_task) self._audio_task = None async def _vad_analyze(self, audio_frame: InputAudioRawFrame) -> VADState: + """Analyze audio frame for voice activity.""" state = VADState.QUIET if self.vad_analyzer: state = await self.get_event_loop().run_in_executor( @@ -309,6 +399,7 @@ class BaseInputTransport(FrameProcessor): return state async def _handle_vad(self, audio_frame: InputAudioRawFrame, vad_state: VADState): + """Handle Voice Activity Detection results and generate appropriate frames.""" new_vad_state = await self._vad_analyze(audio_frame) if ( new_vad_state != vad_state @@ -339,18 +430,21 @@ class BaseInputTransport(FrameProcessor): return vad_state async def _handle_end_of_turn(self): + """Handle end-of-turn analysis and generate prediction results.""" if self.turn_analyzer: state, prediction = await self.turn_analyzer.analyze_end_of_turn() await self._handle_prediction_result(prediction) await self._handle_end_of_turn_complete(state) async def _handle_end_of_turn_complete(self, state: EndOfTurnState): + """Handle completion of end-of-turn analysis.""" if state == EndOfTurnState.COMPLETE: await self._handle_user_interruption(UserStoppedSpeakingFrame()) async def _run_turn_analyzer( self, frame: InputAudioRawFrame, vad_state: VADState, previous_vad_state: VADState ): + """Run turn analysis on audio frame and handle results.""" is_speech = vad_state == VADState.SPEAKING or vad_state == VADState.STARTING # If silence exceeds threshold, we are going to receive EndOfTurnState.COMPLETE end_of_turn_state = self._params.turn_analyzer.append_audio(frame.audio, is_speech) @@ -361,6 +455,7 @@ class BaseInputTransport(FrameProcessor): await self._handle_end_of_turn() async def _audio_task_handler(self): + """Main audio processing task handler for VAD and turn analysis.""" vad_state: VADState = VADState.QUIET while True: try: @@ -399,9 +494,5 @@ class BaseInputTransport(FrameProcessor): self.reset_watchdog() async def _handle_prediction_result(self, result: MetricsData): - """Handle a prediction result event from the turn analyzer. - - Args: - result: The prediction result MetricsData. - """ + """Handle a prediction result event from the turn analyzer.""" await self.push_frame(MetricsFrame(data=[result])) diff --git a/src/pipecat/transports/base_output.py b/src/pipecat/transports/base_output.py index 36d0536d7..f90b4c553 100644 --- a/src/pipecat/transports/base_output.py +++ b/src/pipecat/transports/base_output.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base output transport implementation for Pipecat. + +This module provides the BaseOutputTransport class which handles audio and video +output processing, including frame buffering, mixing, timing, and media streaming. +""" + import asyncio import itertools import sys @@ -46,7 +52,20 @@ BOT_VAD_STOP_SECS = 0.35 class BaseOutputTransport(FrameProcessor): + """Base class for output transport implementations. + + Handles audio and video output processing including frame buffering, audio mixing, + timing coordination, and media streaming. Supports multiple output destinations + and provides interruption handling for real-time communication. + """ + def __init__(self, params: TransportParams, **kwargs): + """Initialize the base output transport. + + Args: + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(**kwargs) self._params = params @@ -67,13 +86,28 @@ class BaseOutputTransport(FrameProcessor): @property def sample_rate(self) -> int: + """Get the current audio sample rate. + + Returns: + The sample rate in Hz. + """ return self._sample_rate @property def audio_chunk_size(self) -> int: + """Get the audio chunk size for output processing. + + Returns: + The size of audio chunks in bytes. + """ return self._audio_chunk_size async def start(self, frame: StartFrame): + """Start the output transport and initialize components. + + Args: + frame: The start frame containing initialization parameters. + """ self._sample_rate = self._params.audio_out_sample_rate or frame.audio_out_sample_rate # We will write 10ms*CHUNKS of audio at a time (where CHUNKS is the @@ -83,15 +117,29 @@ class BaseOutputTransport(FrameProcessor): self._audio_chunk_size = audio_bytes_10ms * self._params.audio_out_10ms_chunks async def stop(self, frame: EndFrame): + """Stop the output transport and cleanup resources. + + Args: + frame: The end frame signaling transport shutdown. + """ for _, sender in self._media_senders.items(): await sender.stop(frame) async def cancel(self, frame: CancelFrame): + """Cancel the output transport and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ for _, sender in self._media_senders.items(): await sender.cancel(frame) async def set_transport_ready(self, frame: StartFrame): - """To be called when the transport is ready to stream.""" + """Called when the transport is ready to stream. + + Args: + frame: The start frame containing initialization parameters. + """ # Register destinations. for destination in self._params.audio_out_destinations: await self.register_audio_destination(destination) @@ -127,27 +175,67 @@ class BaseOutputTransport(FrameProcessor): await self._media_senders[destination].start(frame) async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message. + + Args: + frame: The transport message frame to send. + """ pass async def register_video_destination(self, destination: str): + """Register a video output destination. + + Args: + destination: The destination identifier to register. + """ pass async def register_audio_destination(self, destination: str): + """Register an audio output destination. + + Args: + destination: The destination identifier to register. + """ pass async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the transport. + + Args: + frame: The output video frame to write. + """ pass async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the transport. + + Args: + frame: The output audio frame to write. + """ pass async def write_dtmf(self, frame: OutputDTMFFrame | OutputDTMFUrgentFrame): + """Write a DTMF tone to the transport. + + Args: + frame: The DTMF frame to write. + """ pass async def send_audio(self, frame: OutputAudioRawFrame): + """Send an audio frame downstream. + + Args: + frame: The audio frame to send. + """ await self.queue_frame(frame, FrameDirection.DOWNSTREAM) async def send_image(self, frame: OutputImageRawFrame | SpriteFrame): + """Send an image frame downstream. + + Args: + frame: The image frame to send. + """ await self.queue_frame(frame, FrameDirection.DOWNSTREAM) # @@ -155,6 +243,12 @@ class BaseOutputTransport(FrameProcessor): # async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process incoming frames and handle transport-specific logic. + + Args: + frame: The frame to process. + direction: The direction of frame flow in the pipeline. + """ await super().process_frame(frame, direction) # @@ -200,6 +294,7 @@ class BaseOutputTransport(FrameProcessor): await self._handle_frame(frame) async def _handle_frame(self, frame: Frame): + """Handle frames by routing them to appropriate media senders.""" if frame.transport_destination not in self._media_senders: logger.warning( f"{self} destination [{frame.transport_destination}] not registered for frame {frame}" @@ -226,6 +321,12 @@ class BaseOutputTransport(FrameProcessor): # class MediaSender: + """Handles media streaming for a specific destination. + + Manages audio and video output processing including buffering, timing, + mixing, and frame delivery for a single output destination. + """ + def __init__( self, transport: "BaseOutputTransport", @@ -235,6 +336,15 @@ class BaseOutputTransport(FrameProcessor): audio_chunk_size: int, params: TransportParams, ): + """Initialize the media sender. + + Args: + transport: The parent transport instance. + destination: The destination identifier for this sender. + sample_rate: The audio sample rate in Hz. + audio_chunk_size: The size of audio chunks in bytes. + params: Transport configuration parameters. + """ self._transport = transport self._destination = destination self._sample_rate = sample_rate @@ -266,13 +376,28 @@ class BaseOutputTransport(FrameProcessor): @property def sample_rate(self) -> int: + """Get the audio sample rate. + + Returns: + The sample rate in Hz. + """ return self._sample_rate @property def audio_chunk_size(self) -> int: + """Get the audio chunk size. + + Returns: + The size of audio chunks in bytes. + """ return self._audio_chunk_size async def start(self, frame: StartFrame): + """Start the media sender and initialize components. + + Args: + frame: The start frame containing initialization parameters. + """ self._audio_buffer = bytearray() # Create all tasks. @@ -293,6 +418,11 @@ class BaseOutputTransport(FrameProcessor): await self._mixer.start(self._sample_rate) async def stop(self, frame: EndFrame): + """Stop the media sender and cleanup resources. + + Args: + frame: The end frame signaling sender shutdown. + """ # Let the sink tasks process the queue until they reach this EndFrame. await self._clock_queue.put((sys.maxsize, frame.id, frame)) await self._audio_queue.put(frame) @@ -314,12 +444,22 @@ class BaseOutputTransport(FrameProcessor): await self._cancel_video_task() async def cancel(self, frame: CancelFrame): + """Cancel the media sender and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ # Since we are cancelling everything it doesn't matter what task we cancel first. await self._cancel_audio_task() await self._cancel_clock_task() await self._cancel_video_task() async def handle_interruptions(self, _: StartInterruptionFrame): + """Handle interruption events by restarting tasks and clearing buffers. + + Args: + _: The start interruption frame (unused). + """ if not self._transport.interruptions_allowed: return @@ -335,6 +475,11 @@ class BaseOutputTransport(FrameProcessor): await self._bot_stopped_speaking() async def handle_audio_frame(self, frame: OutputAudioRawFrame): + """Handle incoming audio frames by buffering and chunking. + + Args: + frame: The output audio frame to handle. + """ if not self._params.audio_out_enabled: return @@ -357,6 +502,11 @@ class BaseOutputTransport(FrameProcessor): self._audio_buffer = self._audio_buffer[self._audio_chunk_size :] async def handle_image_frame(self, frame: OutputImageRawFrame | SpriteFrame): + """Handle incoming image frames for video output. + + Args: + frame: The output image or sprite frame to handle. + """ if not self._params.video_out_enabled: return @@ -368,12 +518,27 @@ class BaseOutputTransport(FrameProcessor): await self._set_video_images(frame.images) async def handle_timed_frame(self, frame: Frame): + """Handle frames with presentation timestamps. + + Args: + frame: The frame with timing information to handle. + """ await self._clock_queue.put((frame.pts, frame.id, frame)) async def handle_sync_frame(self, frame: Frame): + """Handle frames that need synchronized processing. + + Args: + frame: The frame to handle synchronously. + """ await self._audio_queue.put(frame) async def handle_mixer_control_frame(self, frame: MixerControlFrame): + """Handle audio mixer control frames. + + Args: + frame: The mixer control frame to handle. + """ if self._mixer: await self._mixer.process_frame(frame) @@ -382,16 +547,19 @@ class BaseOutputTransport(FrameProcessor): # def _create_audio_task(self): + """Create the audio processing task.""" if not self._audio_task: self._audio_queue = asyncio.Queue() self._audio_task = self._transport.create_task(self._audio_task_handler()) async def _cancel_audio_task(self): + """Cancel and cleanup the audio processing task.""" if self._audio_task: await self._transport.cancel_task(self._audio_task) self._audio_task = None async def _bot_started_speaking(self): + """Handle bot started speaking event.""" if not self._bot_speaking: logger.debug( f"Bot{f' [{self._destination}]' if self._destination else ''} started speaking" @@ -407,6 +575,7 @@ class BaseOutputTransport(FrameProcessor): self._bot_speaking = True async def _bot_stopped_speaking(self): + """Handle bot stopped speaking event.""" if self._bot_speaking: logger.debug( f"Bot{f' [{self._destination}]' if self._destination else ''} stopped speaking" @@ -426,6 +595,11 @@ class BaseOutputTransport(FrameProcessor): self._audio_buffer = bytearray() async def _handle_frame(self, frame: Frame): + """Handle various frame types with appropriate processing. + + Args: + frame: The frame to handle. + """ if isinstance(frame, OutputImageRawFrame): await self._set_video_image(frame) elif isinstance(frame, SpriteFrame): @@ -436,6 +610,12 @@ class BaseOutputTransport(FrameProcessor): await self._transport.write_dtmf(frame) def _next_frame(self) -> AsyncGenerator[Frame, None]: + """Generate the next frame for audio processing. + + Returns: + An async generator yielding frames for processing. + """ + async def without_mixer(vad_stop_secs: float) -> AsyncGenerator[Frame, None]: while True: try: @@ -480,6 +660,7 @@ class BaseOutputTransport(FrameProcessor): return without_mixer(BOT_VAD_STOP_SECS) async def _audio_task_handler(self): + """Main audio processing task handler.""" # Push a BotSpeakingFrame every 200ms, we don't really need to push it # at every audio chunk. If the audio chunk is bigger than 200ms, push at # every audio chunk. @@ -518,23 +699,36 @@ class BaseOutputTransport(FrameProcessor): # def _create_video_task(self): + """Create the video processing task if video output is enabled.""" if not self._video_task and self._params.video_out_enabled: self._video_queue = asyncio.Queue() self._video_task = self._transport.create_task(self._video_task_handler()) async def _cancel_video_task(self): + """Cancel and cleanup the video processing task.""" # Stop video output task. if self._video_task: await self._transport.cancel_task(self._video_task) self._video_task = None async def _set_video_image(self, image: OutputImageRawFrame): + """Set a single video image for cycling output. + + Args: + image: The image frame to cycle for video output. + """ self._video_images = itertools.cycle([image]) async def _set_video_images(self, images: List[OutputImageRawFrame]): + """Set multiple video images for cycling output. + + Args: + images: The list of image frames to cycle for video output. + """ self._video_images = itertools.cycle(images) async def _video_task_handler(self): + """Main video processing task handler.""" self._video_start_time = None self._video_frame_index = 0 self._video_frame_duration = 1 / self._params.video_out_framerate @@ -550,6 +744,7 @@ class BaseOutputTransport(FrameProcessor): await asyncio.sleep(self._video_frame_duration) async def _video_is_live_handler(self): + """Handle live video streaming with frame timing.""" image = await self._video_queue.get() # We get the start time as soon as we get the first image. @@ -575,6 +770,12 @@ class BaseOutputTransport(FrameProcessor): self._video_queue.task_done() async def _draw_image(self, frame: OutputImageRawFrame): + """Draw/render an image frame with resizing if needed. + + Args: + frame: The image frame to draw. + """ + def resize_frame(frame: OutputImageRawFrame) -> OutputImageRawFrame: desired_size = (self._params.video_out_width, self._params.video_out_height) @@ -601,16 +802,19 @@ class BaseOutputTransport(FrameProcessor): # def _create_clock_task(self): + """Create the clock/timing processing task.""" if not self._clock_task: self._clock_queue = WatchdogPriorityQueue(self._transport.task_manager) self._clock_task = self._transport.create_task(self._clock_task_handler()) async def _cancel_clock_task(self): + """Cancel and cleanup the clock processing task.""" if self._clock_task: await self._transport.cancel_task(self._clock_task) self._clock_task = None async def _clock_task_handler(self): + """Main clock/timing task handler for timed frame delivery.""" running = True while running: timestamp, _, frame = await self._clock_queue.get() diff --git a/src/pipecat/transports/base_transport.py b/src/pipecat/transports/base_transport.py index c634babb8..8e722127f 100644 --- a/src/pipecat/transports/base_transport.py +++ b/src/pipecat/transports/base_transport.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base transport classes for Pipecat. + +This module provides the foundation for transport implementations including +parameter configuration and abstract base classes for input/output transport +functionality. +""" + from abc import abstractmethod from typing import List, Mapping, Optional @@ -18,6 +25,45 @@ from pipecat.utils.base_object import BaseObject class TransportParams(BaseModel): + """Configuration parameters for transport implementations. + + Parameters: + camera_in_enabled: Enable camera input (deprecated, use video_in_enabled). + camera_out_enabled: Enable camera output (deprecated, use video_out_enabled). + camera_out_is_live: Enable real-time camera output (deprecated). + camera_out_width: Camera output width in pixels (deprecated). + camera_out_height: Camera output height in pixels (deprecated). + camera_out_bitrate: Camera output bitrate in bits per second (deprecated). + camera_out_framerate: Camera output frame rate in FPS (deprecated). + camera_out_color_format: Camera output color format string (deprecated). + audio_out_enabled: Enable audio output streaming. + audio_out_sample_rate: Output audio sample rate in Hz. + audio_out_channels: Number of output audio channels. + audio_out_bitrate: Output audio bitrate in bits per second. + audio_out_10ms_chunks: Number of 10ms chunks to buffer for output. + audio_out_mixer: Audio mixer instance or destination mapping. + audio_out_destinations: List of audio output destination identifiers. + audio_in_enabled: Enable audio input streaming. + audio_in_sample_rate: Input audio sample rate in Hz. + audio_in_channels: Number of input audio channels. + audio_in_filter: Audio filter to apply to input audio. + audio_in_stream_on_start: Start audio streaming immediately on transport start. + audio_in_passthrough: Pass through input audio frames downstream. + video_in_enabled: Enable video input streaming. + video_out_enabled: Enable video output streaming. + video_out_is_live: Enable real-time video output streaming. + video_out_width: Video output width in pixels. + video_out_height: Video output height in pixels. + video_out_bitrate: Video output bitrate in bits per second. + video_out_framerate: Video output frame rate in FPS. + video_out_color_format: Video output color format string. + video_out_destinations: List of video output destination identifiers. + vad_enabled: Enable Voice Activity Detection (deprecated). + vad_audio_passthrough: Enable VAD audio passthrough (deprecated). + vad_analyzer: Voice Activity Detection analyzer instance. + turn_analyzer: Turn-taking analyzer instance for conversation management. + """ + model_config = ConfigDict(arbitrary_types_allowed=True) camera_in_enabled: bool = False @@ -57,6 +103,12 @@ class TransportParams(BaseModel): class BaseTransport(BaseObject): + """Base class for transport implementations. + + Provides the foundation for transport classes that handle media streaming, + including input and output frame processors for audio and video data. + """ + def __init__( self, *, @@ -64,14 +116,31 @@ class BaseTransport(BaseObject): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the base transport. + + Args: + name: Optional name for the transport instance. + input_name: Optional name for the input processor. + output_name: Optional name for the output processor. + """ super().__init__(name=name) self._input_name = input_name self._output_name = output_name @abstractmethod def input(self) -> FrameProcessor: + """Get the input frame processor for this transport. + + Returns: + The frame processor that handles incoming frames. + """ pass @abstractmethod def output(self) -> FrameProcessor: + """Get the output frame processor for this transport. + + Returns: + The frame processor that handles outgoing frames. + """ pass diff --git a/src/pipecat/transports/local/audio.py b/src/pipecat/transports/local/audio.py index 1d5e80158..b38d1dd8e 100644 --- a/src/pipecat/transports/local/audio.py +++ b/src/pipecat/transports/local/audio.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Local audio transport implementation for Pipecat. + +This module provides a local audio transport that uses PyAudio for real-time +audio input and output through the system's default audio devices. +""" + import asyncio from concurrent.futures import ThreadPoolExecutor from typing import Optional @@ -27,14 +33,33 @@ except ModuleNotFoundError as e: class LocalAudioTransportParams(TransportParams): + """Configuration parameters for local audio transport. + + Parameters: + input_device_index: PyAudio device index for audio input. If None, uses default. + output_device_index: PyAudio device index for audio output. If None, uses default. + """ + input_device_index: Optional[int] = None output_device_index: Optional[int] = None class LocalAudioInputTransport(BaseInputTransport): + """Local audio input transport using PyAudio. + + Captures audio from the system's audio input device and converts it to + InputAudioRawFrame objects for processing in the pipeline. + """ + _params: LocalAudioTransportParams def __init__(self, py_audio: pyaudio.PyAudio, params: LocalAudioTransportParams): + """Initialize the local audio input transport. + + Args: + py_audio: PyAudio instance for audio device management. + params: Transport configuration parameters. + """ super().__init__(params) self._py_audio = py_audio @@ -42,6 +67,11 @@ class LocalAudioInputTransport(BaseInputTransport): self._sample_rate = 0 async def start(self, frame: StartFrame): + """Start the audio input stream. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._in_stream: @@ -64,6 +94,7 @@ class LocalAudioInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def cleanup(self): + """Stop and cleanup the audio input stream.""" await super().cleanup() if self._in_stream: self._in_stream.stop_stream() @@ -71,6 +102,7 @@ class LocalAudioInputTransport(BaseInputTransport): self._in_stream = None def _audio_in_callback(self, in_data, frame_count, time_info, status): + """Callback function for PyAudio input stream.""" frame = InputAudioRawFrame( audio=in_data, sample_rate=self._sample_rate, @@ -83,9 +115,21 @@ class LocalAudioInputTransport(BaseInputTransport): class LocalAudioOutputTransport(BaseOutputTransport): + """Local audio output transport using PyAudio. + + Plays audio frames through the system's audio output device by converting + OutputAudioRawFrame objects to playable audio data. + """ + _params: LocalAudioTransportParams def __init__(self, py_audio: pyaudio.PyAudio, params: LocalAudioTransportParams): + """Initialize the local audio output transport. + + Args: + py_audio: PyAudio instance for audio device management. + params: Transport configuration parameters. + """ super().__init__(params) self._py_audio = py_audio @@ -97,6 +141,11 @@ class LocalAudioOutputTransport(BaseOutputTransport): self._executor = ThreadPoolExecutor(max_workers=1) async def start(self, frame: StartFrame): + """Start the audio output stream. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._out_stream: @@ -116,6 +165,7 @@ class LocalAudioOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def cleanup(self): + """Stop and cleanup the audio output stream.""" await super().cleanup() if self._out_stream: self._out_stream.stop_stream() @@ -123,6 +173,11 @@ class LocalAudioOutputTransport(BaseOutputTransport): self._out_stream = None async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the output stream. + + Args: + frame: The audio frame to write to the output device. + """ if self._out_stream: await self.get_event_loop().run_in_executor( self._executor, self._out_stream.write, frame.audio @@ -130,7 +185,18 @@ class LocalAudioOutputTransport(BaseOutputTransport): class LocalAudioTransport(BaseTransport): + """Complete local audio transport with input and output capabilities. + + Provides a unified interface for local audio I/O using PyAudio, supporting + both audio capture and playback through the system's audio devices. + """ + def __init__(self, params: LocalAudioTransportParams): + """Initialize the local audio transport. + + Args: + params: Transport configuration parameters. + """ super().__init__() self._params = params self._pyaudio = pyaudio.PyAudio() @@ -143,11 +209,21 @@ class LocalAudioTransport(BaseTransport): # def input(self) -> FrameProcessor: + """Get the input frame processor for this transport. + + Returns: + The audio input transport processor. + """ if not self._input: self._input = LocalAudioInputTransport(self._pyaudio, self._params) return self._input def output(self) -> FrameProcessor: + """Get the output frame processor for this transport. + + Returns: + The audio output transport processor. + """ if not self._output: self._output = LocalAudioOutputTransport(self._pyaudio, self._params) return self._output diff --git a/src/pipecat/transports/local/tk.py b/src/pipecat/transports/local/tk.py index 73c17853a..c687370ce 100644 --- a/src/pipecat/transports/local/tk.py +++ b/src/pipecat/transports/local/tk.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Tkinter-based local transport implementation for Pipecat. + +This module provides a local transport using Tkinter for video display and +PyAudio for audio I/O, suitable for desktop applications and testing. +""" + import asyncio import tkinter as tk from concurrent.futures import ThreadPoolExecutor @@ -40,20 +46,44 @@ except ModuleNotFoundError as e: class TkTransportParams(TransportParams): + """Configuration parameters for Tkinter transport. + + Parameters: + audio_input_device_index: PyAudio device index for audio input. If None, uses default. + audio_output_device_index: PyAudio device index for audio output. If None, uses default. + """ + audio_input_device_index: Optional[int] = None audio_output_device_index: Optional[int] = None class TkInputTransport(BaseInputTransport): + """Tkinter-based audio input transport. + + Captures audio from the system's audio input device using PyAudio and + converts it to InputAudioRawFrame objects for pipeline processing. + """ + _params: TkTransportParams def __init__(self, py_audio: pyaudio.PyAudio, params: TkTransportParams): + """Initialize the Tkinter input transport. + + Args: + py_audio: PyAudio instance for audio device management. + params: Transport configuration parameters. + """ super().__init__(params) self._py_audio = py_audio self._in_stream = None self._sample_rate = 0 async def start(self, frame: StartFrame): + """Start the audio input stream. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._in_stream: @@ -76,6 +106,7 @@ class TkInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def cleanup(self): + """Stop and cleanup the audio input stream.""" await super().cleanup() if self._in_stream: self._in_stream.stop_stream() @@ -83,6 +114,7 @@ class TkInputTransport(BaseInputTransport): self._in_stream = None def _audio_in_callback(self, in_data, frame_count, time_info, status): + """Callback function for PyAudio input stream.""" frame = InputAudioRawFrame( audio=in_data, sample_rate=self._sample_rate, @@ -95,9 +127,22 @@ class TkInputTransport(BaseInputTransport): class TkOutputTransport(BaseOutputTransport): + """Tkinter-based audio and video output transport. + + Plays audio through PyAudio and displays video frames in a Tkinter window, + providing a complete multimedia output solution for desktop applications. + """ + _params: TkTransportParams def __init__(self, tk_root: tk.Tk, py_audio: pyaudio.PyAudio, params: TkTransportParams): + """Initialize the Tkinter output transport. + + Args: + tk_root: The root Tkinter window for video display. + py_audio: PyAudio instance for audio device management. + params: Transport configuration parameters. + """ super().__init__(params) self._py_audio = py_audio self._out_stream = None @@ -115,6 +160,11 @@ class TkOutputTransport(BaseOutputTransport): self._image_label.pack() async def start(self, frame: StartFrame): + """Start the audio output stream. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._out_stream: @@ -134,6 +184,7 @@ class TkOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def cleanup(self): + """Stop and cleanup the audio output stream.""" await super().cleanup() if self._out_stream: self._out_stream.stop_stream() @@ -141,15 +192,26 @@ class TkOutputTransport(BaseOutputTransport): self._out_stream = None async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the output stream. + + Args: + frame: The audio frame to write to the output device. + """ if self._out_stream: await self.get_event_loop().run_in_executor( self._executor, self._out_stream.write, frame.audio ) async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the Tkinter display. + + Args: + frame: The video frame to display in the Tkinter window. + """ self.get_event_loop().call_soon(self._write_frame_to_tk, frame) def _write_frame_to_tk(self, frame: OutputImageRawFrame): + """Write frame data to the Tkinter image label.""" width = frame.size[0] height = frame.size[1] data = f"P6 {width} {height} 255 ".encode() + frame.image @@ -162,7 +224,19 @@ class TkOutputTransport(BaseOutputTransport): class TkLocalTransport(BaseTransport): + """Complete Tkinter-based local transport with audio and video capabilities. + + Provides a unified interface for local multimedia I/O using Tkinter for video + display and PyAudio for audio, suitable for desktop applications and testing. + """ + def __init__(self, tk_root: tk.Tk, params: TkTransportParams): + """Initialize the Tkinter local transport. + + Args: + tk_root: The root Tkinter window for video display. + params: Transport configuration parameters. + """ super().__init__() self._tk_root = tk_root self._params = params @@ -176,11 +250,21 @@ class TkLocalTransport(BaseTransport): # def input(self) -> TkInputTransport: + """Get the input frame processor for this transport. + + Returns: + The Tkinter input transport processor. + """ if not self._input: self._input = TkInputTransport(self._pyaudio, self._params) return self._input def output(self) -> TkOutputTransport: + """Get the output frame processor for this transport. + + Returns: + The Tkinter output transport processor. + """ if not self._output: self._output = TkOutputTransport(self._tk_root, self._pyaudio, self._params) return self._output diff --git a/src/pipecat/transports/network/fastapi_websocket.py b/src/pipecat/transports/network/fastapi_websocket.py index 5ddaacff7..c3f3a933b 100644 --- a/src/pipecat/transports/network/fastapi_websocket.py +++ b/src/pipecat/transports/network/fastapi_websocket.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""FastAPI WebSocket transport implementation for Pipecat. + +This module provides WebSocket-based transport for real-time audio/video streaming +using FastAPI and WebSocket connections. Supports binary and text serialization +with configurable session timeouts and WAV header generation. +""" import asyncio import io @@ -45,19 +51,48 @@ except ModuleNotFoundError as e: class FastAPIWebsocketParams(TransportParams): + """Configuration parameters for FastAPI WebSocket transport. + + Parameters: + add_wav_header: Whether to add WAV headers to audio frames. + serializer: Frame serializer for encoding/decoding messages. + session_timeout: Session timeout in seconds, None for no timeout. + """ + add_wav_header: bool = False serializer: Optional[FrameSerializer] = None session_timeout: Optional[int] = None class FastAPIWebsocketCallbacks(BaseModel): + """Callback functions for WebSocket events. + + Parameters: + on_client_connected: Called when a client connects to the WebSocket. + on_client_disconnected: Called when a client disconnects from the WebSocket. + on_session_timeout: Called when a session timeout occurs. + """ + on_client_connected: Callable[[WebSocket], Awaitable[None]] on_client_disconnected: Callable[[WebSocket], Awaitable[None]] on_session_timeout: Callable[[WebSocket], Awaitable[None]] class FastAPIWebsocketClient: + """WebSocket client wrapper for handling connections and message passing. + + Manages WebSocket state, message sending/receiving, and connection lifecycle + with support for both binary and text message types. + """ + def __init__(self, websocket: WebSocket, is_binary: bool, callbacks: FastAPIWebsocketCallbacks): + """Initialize the WebSocket client. + + Args: + websocket: The FastAPI WebSocket connection. + is_binary: Whether to use binary message format. + callbacks: Event callback functions. + """ self._websocket = websocket self._closing = False self._is_binary = is_binary @@ -65,12 +100,27 @@ class FastAPIWebsocketClient: self._leave_counter = 0 async def setup(self, _: StartFrame): + """Set up the WebSocket client. + + Args: + _: The start frame (unused). + """ self._leave_counter += 1 def receive(self) -> typing.AsyncIterator[bytes | str]: + """Get an async iterator for receiving WebSocket messages. + + Returns: + An async iterator yielding bytes or strings based on message type. + """ return self._websocket.iter_bytes() if self._is_binary else self._websocket.iter_text() async def send(self, data: str | bytes): + """Send data through the WebSocket connection. + + Args: + data: The data to send (string or bytes). + """ try: if self._can_send(): if self._is_binary: @@ -89,6 +139,7 @@ class FastAPIWebsocketClient: await self.trigger_client_disconnected() async def disconnect(self): + """Disconnect the WebSocket client.""" self._leave_counter -= 1 if self._leave_counter > 0: return @@ -99,27 +150,47 @@ class FastAPIWebsocketClient: await self.trigger_client_disconnected() async def trigger_client_disconnected(self): + """Trigger the client disconnected callback.""" await self._callbacks.on_client_disconnected(self._websocket) async def trigger_client_connected(self): + """Trigger the client connected callback.""" await self._callbacks.on_client_connected(self._websocket) async def trigger_client_timeout(self): + """Trigger the client timeout callback.""" await self._callbacks.on_session_timeout(self._websocket) def _can_send(self): + """Check if data can be sent through the WebSocket.""" return self.is_connected and not self.is_closing @property def is_connected(self) -> bool: + """Check if the WebSocket is currently connected. + + Returns: + True if the WebSocket is in connected state. + """ return self._websocket.client_state == WebSocketState.CONNECTED @property def is_closing(self) -> bool: + """Check if the WebSocket is currently closing. + + Returns: + True if the WebSocket is in the process of closing. + """ return self._closing class FastAPIWebsocketInputTransport(BaseInputTransport): + """Input transport for FastAPI WebSocket connections. + + Handles incoming WebSocket messages, deserializes frames, and manages + connection monitoring with optional session timeouts. + """ + def __init__( self, transport: BaseTransport, @@ -127,6 +198,14 @@ class FastAPIWebsocketInputTransport(BaseInputTransport): params: FastAPIWebsocketParams, **kwargs, ): + """Initialize the WebSocket input transport. + + Args: + transport: The parent transport instance. + client: The WebSocket client wrapper. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport self._client = client @@ -138,6 +217,11 @@ class FastAPIWebsocketInputTransport(BaseInputTransport): self._initialized = False async def start(self, frame: StartFrame): + """Start the input transport and begin message processing. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -156,6 +240,7 @@ class FastAPIWebsocketInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def _stop_tasks(self): + """Stop all running tasks.""" if self._monitor_websocket_task: await self.cancel_task(self._monitor_websocket_task) self._monitor_websocket_task = None @@ -164,20 +249,32 @@ class FastAPIWebsocketInputTransport(BaseInputTransport): self._receive_task = None async def stop(self, frame: EndFrame): + """Stop the input transport and cleanup resources. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._stop_tasks() await self._client.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the input transport and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._stop_tasks() await self._client.disconnect() async def cleanup(self): + """Clean up transport resources.""" await super().cleanup() await self._transport.cleanup() async def _receive_messages(self): + """Main message receiving loop for WebSocket messages.""" try: async for message in WatchdogAsyncIterator( self._client.receive(), manager=self.task_manager @@ -206,6 +303,12 @@ class FastAPIWebsocketInputTransport(BaseInputTransport): class FastAPIWebsocketOutputTransport(BaseOutputTransport): + """Output transport for FastAPI WebSocket connections. + + Handles outgoing frame serialization, audio streaming with timing simulation, + and WebSocket message transmission with optional WAV header generation. + """ + def __init__( self, transport: BaseTransport, @@ -213,6 +316,14 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): params: FastAPIWebsocketParams, **kwargs, ): + """Initialize the WebSocket output transport. + + Args: + transport: The parent transport instance. + client: The WebSocket client wrapper. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport @@ -231,6 +342,11 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): self._initialized = False async def start(self, frame: StartFrame): + """Start the output transport and initialize timing. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -245,20 +361,37 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport and cleanup resources. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._write_frame(frame) await self._client.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the output transport and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._write_frame(frame) await self._client.disconnect() async def cleanup(self): + """Clean up transport resources.""" await super().cleanup() await self._transport.cleanup() async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process outgoing frames with special handling for interruptions. + + 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): @@ -266,9 +399,19 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): self._next_send_time = 0 async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message frame. + + Args: + frame: The transport message frame to send. + """ await self._write_frame(frame) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the WebSocket with timing simulation. + + Args: + frame: The output audio frame to write. + """ if self._client.is_closing: return @@ -303,6 +446,7 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): await self._write_audio_sleep() async def _write_frame(self, frame: Frame): + """Serialize and send a frame through the WebSocket.""" if not self._params.serializer: return @@ -314,6 +458,7 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): logger.error(f"{self} exception sending data: {e.__class__.__name__} ({e})") async def _write_audio_sleep(self): + """Simulate audio playback timing with appropriate delays.""" # Simulate a clock. current_time = time.monotonic() sleep_duration = max(0, self._next_send_time - current_time) @@ -325,6 +470,12 @@ class FastAPIWebsocketOutputTransport(BaseOutputTransport): class FastAPIWebsocketTransport(BaseTransport): + """FastAPI WebSocket transport for real-time audio/video streaming. + + Provides bidirectional WebSocket communication with frame serialization, + session management, and event handling for client connections and timeouts. + """ + def __init__( self, websocket: WebSocket, @@ -332,6 +483,14 @@ class FastAPIWebsocketTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the FastAPI WebSocket transport. + + Args: + websocket: The FastAPI WebSocket connection. + params: Transport configuration parameters. + input_name: Optional name for the input processor. + output_name: Optional name for the output processor. + """ super().__init__(input_name=input_name, output_name=output_name) self._params = params @@ -361,16 +520,29 @@ class FastAPIWebsocketTransport(BaseTransport): self._register_event_handler("on_session_timeout") def input(self) -> FastAPIWebsocketInputTransport: + """Get the input transport processor. + + Returns: + The WebSocket input transport instance. + """ return self._input def output(self) -> FastAPIWebsocketOutputTransport: + """Get the output transport processor. + + Returns: + The WebSocket output transport instance. + """ return self._output async def _on_client_connected(self, websocket): + """Handle client connected event.""" await self._call_event_handler("on_client_connected", websocket) async def _on_client_disconnected(self, websocket): + """Handle client disconnected event.""" await self._call_event_handler("on_client_disconnected", websocket) async def _on_session_timeout(self, websocket): + """Handle session timeout event.""" await self._call_event_handler("on_session_timeout", websocket) diff --git a/src/pipecat/transports/network/small_webrtc.py b/src/pipecat/transports/network/small_webrtc.py index 9eedd7d95..140a7b537 100644 --- a/src/pipecat/transports/network/small_webrtc.py +++ b/src/pipecat/transports/network/small_webrtc.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Small WebRTC transport implementation for Pipecat. + +This module provides a WebRTC transport implementation using aiortc for +real-time audio and video communication. It supports bidirectional media +streaming, application messaging, and client connection management. +""" + import asyncio import fractions import time @@ -47,13 +54,32 @@ except ModuleNotFoundError as e: class SmallWebRTCCallbacks(BaseModel): + """Callback handlers for SmallWebRTC events. + + Parameters: + on_app_message: Called when an application message is received. + on_client_connected: Called when a client establishes connection. + on_client_disconnected: Called when a client disconnects. + """ + on_app_message: Callable[[Any], Awaitable[None]] on_client_connected: Callable[[SmallWebRTCConnection], Awaitable[None]] on_client_disconnected: Callable[[SmallWebRTCConnection], Awaitable[None]] class RawAudioTrack(AudioStreamTrack): + """Custom audio stream track for WebRTC output. + + Handles audio frame generation and timing for WebRTC transmission, + supporting queued audio data with proper synchronization. + """ + def __init__(self, sample_rate): + """Initialize the raw audio track. + + Args: + sample_rate: The audio sample rate in Hz. + """ super().__init__() self._sample_rate = sample_rate self._samples_per_10ms = sample_rate * 10 // 1000 @@ -64,7 +90,17 @@ class RawAudioTrack(AudioStreamTrack): self._chunk_queue = deque() def add_audio_bytes(self, audio_bytes: bytes): - """Adds bytes to the audio buffer and returns a Future that completes when the data is processed.""" + """Add audio bytes to the buffer for transmission. + + Args: + audio_bytes: Raw audio data to queue for transmission. + + Returns: + A Future that completes when the data is processed. + + Raises: + ValueError: If audio bytes are not a multiple of 10ms size. + """ if len(audio_bytes) % self._bytes_per_10ms != 0: raise ValueError("Audio bytes must be a multiple of 10ms size.") future = asyncio.get_running_loop().create_future() @@ -79,7 +115,11 @@ class RawAudioTrack(AudioStreamTrack): return future async def recv(self): - """Returns the next audio frame, generating silence if needed.""" + """Return the next audio frame for WebRTC transmission. + + Returns: + An AudioFrame containing the next audio data or silence. + """ # Compute required wait time for synchronization if self._timestamp > 0: wait = self._start + (self._timestamp / self._sample_rate) - time.time() @@ -106,18 +146,37 @@ class RawAudioTrack(AudioStreamTrack): class RawVideoTrack(VideoStreamTrack): + """Custom video stream track for WebRTC output. + + Handles video frame queuing and conversion for WebRTC transmission. + """ + def __init__(self, width, height): + """Initialize the raw video track. + + Args: + width: Video frame width in pixels. + height: Video frame height in pixels. + """ super().__init__() self._width = width self._height = height self._video_buffer = asyncio.Queue() def add_video_frame(self, frame): - """Adds a raw video frame to the buffer.""" + """Add a video frame to the transmission buffer. + + Args: + frame: The video frame to queue for transmission. + """ self._video_buffer.put_nowait(frame) async def recv(self): - """Returns the next video frame, waiting if the buffer is empty.""" + """Return the next video frame for WebRTC transmission. + + Returns: + A VideoFrame ready for WebRTC transmission. + """ raw_frame = await self._video_buffer.get() # Convert bytes to NumPy array @@ -134,6 +193,12 @@ class RawVideoTrack(VideoStreamTrack): class SmallWebRTCClient: + """WebRTC client implementation for handling connections and media streams. + + Manages WebRTC peer connections, audio/video streaming, and application + messaging through the SmallWebRTCConnection interface. + """ + FORMAT_CONVERSIONS = { "yuv420p": cv2.COLOR_YUV2RGB_I420, "yuvj420p": cv2.COLOR_YUV2RGB_I420, # OpenCV treats both the same @@ -142,6 +207,12 @@ class SmallWebRTCClient: } def __init__(self, webrtc_connection: SmallWebRTCConnection, callbacks: SmallWebRTCCallbacks): + """Initialize the WebRTC client. + + Args: + webrtc_connection: The underlying WebRTC connection handler. + callbacks: Event callbacks for connection and message handling. + """ self._webrtc_connection = webrtc_connection self._closing = False self._callbacks = callbacks @@ -180,14 +251,14 @@ class SmallWebRTCClient: await self._handle_app_message(message) def _convert_frame(self, frame_array: np.ndarray, format_name: str) -> np.ndarray: - """Convert a given frame to RGB format based on the input format. + """Convert a video frame to RGB format based on the input format. Args: - frame_array (np.ndarray): The input frame. - format_name (str): The format of the input frame. + frame_array: The input frame as a NumPy array. + format_name: The format of the input frame. Returns: - np.ndarray: The converted RGB frame. + The converted RGB frame as a NumPy array. Raises: ValueError: If the format is unsupported. @@ -203,8 +274,13 @@ class SmallWebRTCClient: return cv2.cvtColor(frame_array, conversion_code) async def read_video_frame(self): - """Reads a video frame from the given MediaStreamTrack, converts it to RGB, + """Read video frames from the WebRTC connection. + + Reads a video frame from the given MediaStreamTrack, converts it to RGB, and creates an InputImageRawFrame. + + Yields: + UserImageRawFrame objects containing video data from the peer. """ while True: if self._video_input_track is None: @@ -242,7 +318,13 @@ class SmallWebRTCClient: yield image_frame async def read_audio_frame(self): - """Reads 20ms of audio from the given MediaStreamTrack and creates an InputAudioRawFrame.""" + """Read audio frames from the WebRTC connection. + + Reads 20ms of audio from the given MediaStreamTrack and creates an InputAudioRawFrame. + + Yields: + InputAudioRawFrame objects containing audio data from the peer. + """ while True: if self._audio_input_track is None: await asyncio.sleep(0.01) @@ -285,20 +367,37 @@ class SmallWebRTCClient: yield audio_frame async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the WebRTC connection. + + Args: + frame: The audio frame to transmit. + """ if self._can_send() and self._audio_output_track: await self._audio_output_track.add_audio_bytes(frame.audio) async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the WebRTC connection. + + Args: + frame: The video frame to transmit. + """ if self._can_send() and self._video_output_track: self._video_output_track.add_video_frame(frame) async def setup(self, _params: TransportParams, frame): + """Set up the client with transport parameters. + + Args: + _params: Transport configuration parameters. + frame: The initialization frame containing setup data. + """ self._audio_in_channels = _params.audio_in_channels self._in_sample_rate = _params.audio_in_sample_rate or frame.audio_in_sample_rate self._out_sample_rate = _params.audio_out_sample_rate or frame.audio_out_sample_rate self._params = _params async def connect(self): + """Establish the WebRTC connection.""" if self._webrtc_connection.is_connected(): # already initialized return @@ -307,6 +406,7 @@ class SmallWebRTCClient: await self._webrtc_connection.connect() async def disconnect(self): + """Disconnect from the WebRTC peer.""" if self.is_connected and not self.is_closing: logger.info(f"Disconnecting to Small WebRTC") self._closing = True @@ -314,10 +414,16 @@ class SmallWebRTCClient: await self._handle_peer_disconnected() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send an application message through the WebRTC connection. + + Args: + frame: The message frame to send. + """ if self._can_send(): self._webrtc_connection.send_app_message(frame.message) async def _handle_client_connected(self): + """Handle client connection establishment.""" # There is nothing to do here yet, the pipeline is still not ready if not self._params: return @@ -337,12 +443,14 @@ class SmallWebRTCClient: await self._callbacks.on_client_connected(self._webrtc_connection) async def _handle_peer_disconnected(self): + """Handle peer disconnection cleanup.""" self._audio_input_track = None self._video_input_track = None self._audio_output_track = None self._video_output_track = None async def _handle_client_closed(self): + """Handle client connection closure.""" self._audio_input_track = None self._video_input_track = None self._audio_output_track = None @@ -350,27 +458,52 @@ class SmallWebRTCClient: await self._callbacks.on_client_disconnected(self._webrtc_connection) async def _handle_app_message(self, message: Any): + """Handle incoming application messages.""" await self._callbacks.on_app_message(message) def _can_send(self): + """Check if the connection is ready for sending data.""" return self.is_connected and not self.is_closing @property def is_connected(self) -> bool: + """Check if the WebRTC connection is established. + + Returns: + True if connected to the peer. + """ return self._webrtc_connection.is_connected() @property def is_closing(self) -> bool: + """Check if the connection is in the process of closing. + + Returns: + True if the connection is closing. + """ return self._closing class SmallWebRTCInputTransport(BaseInputTransport): + """Input transport implementation for SmallWebRTC. + + Handles incoming audio and video streams from WebRTC peers, + including user image requests and application message handling. + """ + def __init__( self, client: SmallWebRTCClient, params: TransportParams, **kwargs, ): + """Initialize the WebRTC input transport. + + Args: + client: The WebRTC client instance. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._client = client self._params = params @@ -382,12 +515,23 @@ class SmallWebRTCInputTransport(BaseInputTransport): self._initialized = False async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process incoming frames including user image requests. + + Args: + frame: The frame to process. + direction: The direction of frame flow in the pipeline. + """ await super().process_frame(frame, direction) if isinstance(frame, UserImageRequestFrame): await self.request_participant_image(frame) async def start(self, frame: StartFrame): + """Start the input transport and establish WebRTC connection. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -404,6 +548,7 @@ class SmallWebRTCInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def _stop_tasks(self): + """Stop all background tasks.""" if self._receive_audio_task: await self.cancel_task(self._receive_audio_task) self._receive_audio_task = None @@ -412,16 +557,27 @@ class SmallWebRTCInputTransport(BaseInputTransport): self._receive_video_task = None async def stop(self, frame: EndFrame): + """Stop the input transport and disconnect from WebRTC. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._stop_tasks() await self._client.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the input transport and disconnect immediately. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._stop_tasks() await self._client.disconnect() async def _receive_audio(self): + """Background task for receiving audio frames from WebRTC.""" try: audio_iterator = self._client.read_audio_frame() async for audio_frame in WatchdogAsyncIterator( @@ -434,6 +590,7 @@ class SmallWebRTCInputTransport(BaseInputTransport): logger.error(f"{self} exception receiving data: {e.__class__.__name__} ({e})") async def _receive_video(self): + """Background task for receiving video frames from WebRTC.""" try: video_iterator = self._client.read_video_frame() async for video_frame in WatchdogAsyncIterator( @@ -462,16 +619,24 @@ class SmallWebRTCInputTransport(BaseInputTransport): logger.error(f"{self} exception receiving data: {e.__class__.__name__} ({e})") async def push_app_message(self, message: Any): + """Push an application message into the pipeline. + + Args: + message: The application message to process. + """ logger.debug(f"Received app message inside SmallWebRTCInputTransport {message}") frame = TransportMessageUrgentFrame(message=message) await self.push_frame(frame) # Add this method similar to DailyInputTransport.request_participant_image async def request_participant_image(self, frame: UserImageRequestFrame): - """Requests an image frame from the participant's video stream. + """Request an image frame from the participant's video stream. When a UserImageRequestFrame is received, this method will store the request and the next video frame received will be converted to a UserImageRawFrame. + + Args: + frame: The user image request frame. """ logger.debug(f"Requesting image from participant: {frame.user_id}") @@ -486,12 +651,25 @@ class SmallWebRTCInputTransport(BaseInputTransport): class SmallWebRTCOutputTransport(BaseOutputTransport): + """Output transport implementation for SmallWebRTC. + + Handles outgoing audio and video streams to WebRTC peers, + including transport message sending. + """ + def __init__( self, client: SmallWebRTCClient, params: TransportParams, **kwargs, ): + """Initialize the WebRTC output transport. + + Args: + client: The WebRTC client instance. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._client = client self._params = params @@ -500,6 +678,11 @@ class SmallWebRTCOutputTransport(BaseOutputTransport): self._initialized = False async def start(self, frame: StartFrame): + """Start the output transport and establish WebRTC connection. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -512,24 +695,55 @@ class SmallWebRTCOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport and disconnect from WebRTC. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._client.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the output transport and disconnect immediately. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._client.disconnect() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message through the WebRTC connection. + + Args: + frame: The transport message frame to send. + """ await self._client.send_message(frame) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the WebRTC connection. + + Args: + frame: The output audio frame to transmit. + """ await self._client.write_audio_frame(frame) async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the WebRTC connection. + + Args: + frame: The output video frame to transmit. + """ await self._client.write_video_frame(frame) class SmallWebRTCTransport(BaseTransport): + """WebRTC transport implementation for real-time communication. + + Provides bidirectional audio and video streaming over WebRTC connections + with support for application messaging and connection event handling. + """ + def __init__( self, webrtc_connection: SmallWebRTCConnection, @@ -537,6 +751,14 @@ class SmallWebRTCTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the WebRTC transport. + + Args: + webrtc_connection: The underlying WebRTC connection handler. + params: Transport configuration parameters. + input_name: Optional name for the input processor. + output_name: Optional name for the output processor. + """ super().__init__(input_name=input_name, output_name=output_name) self._params = params @@ -558,6 +780,11 @@ class SmallWebRTCTransport(BaseTransport): self._register_event_handler("on_client_disconnected") def input(self) -> SmallWebRTCInputTransport: + """Get the input transport processor. + + Returns: + The input transport for handling incoming media streams. + """ if not self._input: self._input = SmallWebRTCInputTransport( self._client, self._params, name=self._input_name @@ -565,6 +792,11 @@ class SmallWebRTCTransport(BaseTransport): return self._input def output(self) -> SmallWebRTCOutputTransport: + """Get the output transport processor. + + Returns: + The output transport for handling outgoing media streams. + """ if not self._output: self._output = SmallWebRTCOutputTransport( self._client, self._params, name=self._input_name @@ -572,20 +804,33 @@ class SmallWebRTCTransport(BaseTransport): return self._output async def send_image(self, frame: OutputImageRawFrame | SpriteFrame): + """Send an image frame through the transport. + + Args: + frame: The image frame to send. + """ if self._output: await self._output.queue_frame(frame, FrameDirection.DOWNSTREAM) async def send_audio(self, frame: OutputAudioRawFrame): + """Send an audio frame through the transport. + + Args: + frame: The audio frame to send. + """ if self._output: await self._output.queue_frame(frame, FrameDirection.DOWNSTREAM) async def _on_app_message(self, message: Any): + """Handle incoming application messages.""" if self._input: await self._input.push_app_message(message) await self._call_event_handler("on_app_message", message) async def _on_client_connected(self, webrtc_connection): + """Handle client connection events.""" await self._call_event_handler("on_client_connected", webrtc_connection) async def _on_client_disconnected(self, webrtc_connection): + """Handle client disconnection events.""" await self._call_event_handler("on_client_disconnected", webrtc_connection) diff --git a/src/pipecat/transports/network/webrtc_connection.py b/src/pipecat/transports/network/webrtc_connection.py index 49aa2b1da..e08d678e5 100644 --- a/src/pipecat/transports/network/webrtc_connection.py +++ b/src/pipecat/transports/network/webrtc_connection.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Small WebRTC connection implementation for Pipecat. + +This module provides a WebRTC connection implementation using aiortc, +with support for audio/video tracks, data channels, and signaling +for real-time communication applications. +""" + import asyncio import json import time @@ -35,36 +42,85 @@ VIDEO_TRANSCEIVER_INDEX = 1 class TrackStatusMessage(BaseModel): + """Message for updating track enabled/disabled status. + + Parameters: + type: Message type identifier. + receiver_index: Index of the track receiver to update. + enabled: Whether the track should be enabled or disabled. + """ + type: Literal["trackStatus"] receiver_index: int enabled: bool class RenegotiateMessage(BaseModel): + """Message requesting WebRTC renegotiation. + + Parameters: + type: Message type identifier for renegotiation requests. + """ + type: Literal["renegotiate"] = "renegotiate" class PeerLeftMessage(BaseModel): + """Message indicating a peer has left the connection. + + Parameters: + type: Message type identifier for peer departure. + """ + type: Literal["peerLeft"] = "peerLeft" class SignallingMessage: + """Union types for signaling message handling. + + Parameters: + Inbound: Types of messages that can be received from peers. + outbound: Types of messages that can be sent to peers. + """ + Inbound = Union[TrackStatusMessage] # in case we need to add new messages in the future outbound = Union[RenegotiateMessage] class SmallWebRTCTrack: + """Wrapper for WebRTC media tracks with enabled/disabled state management. + + Provides additional functionality on top of aiortc MediaStreamTrack including + enable/disable control and frame discarding for audio and video streams. + """ + def __init__(self, track: MediaStreamTrack): + """Initialize the WebRTC track wrapper. + + Args: + track: The underlying MediaStreamTrack to wrap. + """ self._track = track self._enabled = True def set_enabled(self, enabled: bool) -> None: + """Enable or disable the track. + + Args: + enabled: Whether the track should be enabled for receiving frames. + """ self._enabled = enabled def is_enabled(self) -> bool: + """Check if the track is currently enabled. + + Returns: + True if the track is enabled for receiving frames. + """ return self._enabled async def discard_old_frames(self): + """Discard old frames from the track queue to reduce latency.""" remote_track = self._track if isinstance(remote_track, RemoteStreamTrack): if not hasattr(remote_track, "_queue") or not isinstance( @@ -78,11 +134,24 @@ class SmallWebRTCTrack: remote_track._queue.task_done() async def recv(self) -> Optional[Frame]: + """Receive the next frame from the track. + + Returns: + The next frame if the track is enabled, None otherwise. + """ if not self._enabled: return None return await self._track.recv() def __getattr__(self, name): + """Forward attribute access to the underlying track. + + Args: + name: The attribute name to access. + + Returns: + The attribute value from the underlying track. + """ # Forward other attribute/method calls to the underlying track return getattr(self._track, name) @@ -92,7 +161,22 @@ IceServer = RTCIceServer class SmallWebRTCConnection(BaseObject): + """WebRTC connection implementation using aiortc. + + Provides WebRTC peer connection functionality including ICE server configuration, + track management, data channel communication, and connection state handling + for real-time audio/video communication. + """ + def __init__(self, ice_servers: Optional[Union[List[str], List[IceServer]]] = None): + """Initialize the WebRTC connection. + + Args: + ice_servers: List of ICE servers as URLs or IceServer objects. + + Raises: + TypeError: If ice_servers contains mixed types or unsupported types. + """ super().__init__() if not ice_servers: self.ice_servers: List[IceServer] = [] @@ -126,13 +210,24 @@ class SmallWebRTCConnection(BaseObject): @property def pc(self) -> RTCPeerConnection: + """Get the underlying RTCPeerConnection. + + Returns: + The aiortc RTCPeerConnection instance. + """ return self._pc @property def pc_id(self) -> str: + """Get the peer connection identifier. + + Returns: + The unique identifier for this peer connection. + """ return self._pc_id def _initialize(self): + """Initialize the peer connection and associated components.""" logger.debug("Initializing new peer connection") rtc_config = RTCConfiguration(iceServers=self.ice_servers) @@ -147,6 +242,8 @@ class SmallWebRTCConnection(BaseObject): self._pending_app_messages = [] def _setup_listeners(self): + """Set up event listeners for the peer connection.""" + @self._pc.on("datachannel") def on_datachannel(channel): self._data_channel = channel @@ -208,6 +305,7 @@ class SmallWebRTCConnection(BaseObject): await self._call_event_handler("track-ended", track) async def _create_answer(self, sdp: str, type: str): + """Create an SDP answer for the given offer.""" offer = RTCSessionDescription(sdp=sdp, type=type) await self._pc.setRemoteDescription(offer) @@ -223,9 +321,16 @@ class SmallWebRTCConnection(BaseObject): self._answer = self._pc.localDescription async def initialize(self, sdp: str, type: str): + """Initialize the connection with an SDP offer. + + Args: + sdp: The SDP offer string. + type: The SDP type (usually "offer"). + """ await self._create_answer(sdp, type) async def connect(self): + """Connect the WebRTC peer connection and handle initial setup.""" self._connect_invoked = True # If we already connected, trigger again the connected event if self.is_connected(): @@ -241,6 +346,13 @@ class SmallWebRTCConnection(BaseObject): self.ask_to_renegotiate() async def renegotiate(self, sdp: str, type: str, restart_pc: bool = False): + """Renegotiate the WebRTC connection with new parameters. + + Args: + sdp: The new SDP offer string. + type: The SDP type (usually "offer"). + restart_pc: Whether to restart the peer connection entirely. + """ logger.debug(f"Renegotiating {self._pc_id}") if restart_pc: @@ -264,6 +376,7 @@ class SmallWebRTCConnection(BaseObject): asyncio.create_task(delayed_task()) def force_transceivers_to_send_recv(self): + """Force all transceivers to bidirectional send/receive mode.""" for transceiver in self._pc.getTransceivers(): transceiver.direction = "sendrecv" # logger.debug( @@ -272,6 +385,11 @@ class SmallWebRTCConnection(BaseObject): # logger.debug(f"Sender track: {transceiver.sender.track}") def replace_audio_track(self, track): + """Replace the audio track in the first transceiver. + + Args: + track: The new audio track to use for sending. + """ logger.debug(f"Replacing audio track {track.kind}") # Transceivers always appear in creation-order for both peers # For now we are only considering that we are going to have 02 transceivers, @@ -283,6 +401,11 @@ class SmallWebRTCConnection(BaseObject): logger.warning("Audio transceiver not found. Cannot replace audio track.") def replace_video_track(self, track): + """Replace the video track in the second transceiver. + + Args: + track: The new video track to use for sending. + """ logger.debug(f"Replacing video track {track.kind}") # Transceivers always appear in creation-order for both peers # For now we are only considering that we are going to have 02 transceivers, @@ -294,10 +417,12 @@ class SmallWebRTCConnection(BaseObject): logger.warning("Video transceiver not found. Cannot replace video track.") async def disconnect(self): + """Disconnect from the WebRTC peer connection.""" self.send_app_message({"type": SIGNALLING_TYPE, "message": PeerLeftMessage().model_dump()}) await self._close() async def _close(self): + """Close the peer connection and cleanup resources.""" if self._pc: await self._pc.close() self._message_queue.clear() @@ -305,6 +430,12 @@ class SmallWebRTCConnection(BaseObject): self._track_map = {} def get_answer(self): + """Get the SDP answer for the current connection. + + Returns: + Dictionary containing SDP answer, type, and peer connection ID, + or None if no answer is available. + """ if not self._answer: return None @@ -315,6 +446,7 @@ class SmallWebRTCConnection(BaseObject): } async def _handle_new_connection_state(self): + """Handle changes in the peer connection state.""" state = self._pc.connectionState if state == "connected" and not self._connect_invoked: # We are going to wait until the pipeline is ready before triggering the event @@ -328,7 +460,12 @@ class SmallWebRTCConnection(BaseObject): # Despite the fact that aiortc provides this listener, they don't have a status for "disconnected" # So, there is no advantage in looking at self._pc.connectionState # That is why we are trying to keep our own state - def is_connected(self): + def is_connected(self) -> bool: + """Check if the WebRTC connection is currently active. + + Returns: + True if the connection is active and receiving data. + """ # If the small webrtc transport has never invoked to connect # we are acting like if we are not connected if not self._connect_invoked: @@ -342,6 +479,11 @@ class SmallWebRTCConnection(BaseObject): return (time.time() - self._last_received_time) < 3 def audio_input_track(self): + """Get the audio input track wrapper. + + Returns: + SmallWebRTCTrack wrapper for the audio track, or None if unavailable. + """ if self._track_map.get(AUDIO_TRANSCEIVER_INDEX): return self._track_map[AUDIO_TRANSCEIVER_INDEX] @@ -359,6 +501,11 @@ class SmallWebRTCConnection(BaseObject): return audio_track def video_input_track(self): + """Get the video input track wrapper. + + Returns: + SmallWebRTCTrack wrapper for the video track, or None if unavailable. + """ if self._track_map.get(VIDEO_TRANSCEIVER_INDEX): return self._track_map[VIDEO_TRANSCEIVER_INDEX] @@ -376,6 +523,11 @@ class SmallWebRTCConnection(BaseObject): return video_track def send_app_message(self, message: Any): + """Send an application message through the data channel. + + Args: + message: The message to send (will be JSON serialized). + """ json_message = json.dumps(message) if self._data_channel and self._data_channel.readyState == "open": self._data_channel.send(json_message) @@ -384,6 +536,7 @@ class SmallWebRTCConnection(BaseObject): self._message_queue.append(json_message) def ask_to_renegotiate(self): + """Request renegotiation of the WebRTC connection.""" if self._renegotiation_in_progress: return @@ -393,6 +546,7 @@ class SmallWebRTCConnection(BaseObject): ) def _handle_signalling_message(self, message): + """Handle incoming signaling messages.""" logger.debug(f"Signalling message received: {message}") inbound_adapter = TypeAdapter(SignallingMessage.Inbound) signalling_message = inbound_adapter.validate_python(message) diff --git a/src/pipecat/transports/network/websocket_client.py b/src/pipecat/transports/network/websocket_client.py index 98c7f9e2d..f0746a589 100644 --- a/src/pipecat/transports/network/websocket_client.py +++ b/src/pipecat/transports/network/websocket_client.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""WebSocket client transport implementation for Pipecat. + +This module provides a WebSocket client transport that enables bidirectional +communication over WebSocket connections, with support for audio streaming, +frame serialization, and connection management. +""" + import asyncio import io import time @@ -34,17 +41,38 @@ from pipecat.utils.asyncio.task_manager import BaseTaskManager class WebsocketClientParams(TransportParams): + """Configuration parameters for WebSocket client transport. + + Parameters: + add_wav_header: Whether to add WAV headers to audio frames. + serializer: Frame serializer for encoding/decoding messages. + """ + add_wav_header: bool = True serializer: Optional[FrameSerializer] = None class WebsocketClientCallbacks(BaseModel): + """Callback functions for WebSocket client events. + + Parameters: + on_connected: Called when WebSocket connection is established. + on_disconnected: Called when WebSocket connection is closed. + on_message: Called when a message is received from the WebSocket. + """ + on_connected: Callable[[websockets.WebSocketClientProtocol], Awaitable[None]] on_disconnected: Callable[[websockets.WebSocketClientProtocol], Awaitable[None]] on_message: Callable[[websockets.WebSocketClientProtocol, websockets.Data], Awaitable[None]] class WebsocketClientSession: + """Manages a WebSocket client connection session. + + Handles connection lifecycle, message sending/receiving, and provides + callback mechanisms for connection events. + """ + def __init__( self, uri: str, @@ -52,6 +80,14 @@ class WebsocketClientSession: callbacks: WebsocketClientCallbacks, transport_name: str, ): + """Initialize the WebSocket client session. + + Args: + uri: The WebSocket URI to connect to. + params: Configuration parameters for the session. + callbacks: Callback functions for session events. + transport_name: Name of the parent transport for logging. + """ self._uri = uri self._params = params self._callbacks = callbacks @@ -63,6 +99,14 @@ class WebsocketClientSession: @property def task_manager(self) -> BaseTaskManager: + """Get the task manager for this session. + + Returns: + The task manager instance. + + Raises: + Exception: If task manager is not initialized. + """ if not self._task_manager: raise Exception( f"{self._transport_name}::WebsocketClientSession: TaskManager not initialized (pipeline not started?)" @@ -70,11 +114,17 @@ class WebsocketClientSession: return self._task_manager async def setup(self, task_manager: BaseTaskManager): + """Set up the session with a task manager. + + Args: + task_manager: The task manager to use for session tasks. + """ self._leave_counter += 1 if not self._task_manager: self._task_manager = task_manager async def connect(self): + """Connect to the WebSocket server.""" if self._websocket: return @@ -89,6 +139,7 @@ class WebsocketClientSession: logger.error(f"Timeout connecting to {self._uri}") async def disconnect(self): + """Disconnect from the WebSocket server.""" self._leave_counter -= 1 if not self._websocket or self._leave_counter > 0: return @@ -99,6 +150,11 @@ class WebsocketClientSession: self._websocket = None async def send(self, message: websockets.Data): + """Send a message through the WebSocket connection. + + Args: + message: The message data to send. + """ try: if self._websocket: await self._websocket.send(message) @@ -106,6 +162,7 @@ class WebsocketClientSession: logger.error(f"{self} exception sending data: {e.__class__.__name__} ({e})") async def _client_task_handler(self): + """Handle incoming messages from the WebSocket connection.""" try: # Handle incoming messages async for message in self._websocket: @@ -116,16 +173,30 @@ class WebsocketClientSession: await self._callbacks.on_disconnected(self._websocket) def __str__(self): + """String representation of the WebSocket client session.""" return f"{self._transport_name}::WebsocketClientSession" class WebsocketClientInputTransport(BaseInputTransport): + """WebSocket client input transport for receiving frames. + + Handles incoming WebSocket messages, deserializes them to frames, + and pushes them downstream in the processing pipeline. + """ + def __init__( self, transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams, ): + """Initialize the WebSocket client input transport. + + Args: + transport: The parent transport instance. + session: The WebSocket session to use for communication. + params: Configuration parameters for the transport. + """ super().__init__(params) self._transport = transport @@ -136,10 +207,20 @@ class WebsocketClientInputTransport(BaseInputTransport): self._initialized = False async def setup(self, setup: FrameProcessorSetup): + """Set up the input transport with the frame processor setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._session.setup(setup.task_manager) async def start(self, frame: StartFrame): + """Start the input transport and initialize the WebSocket connection. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -153,18 +234,35 @@ class WebsocketClientInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the input transport and disconnect from WebSocket. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._session.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the input transport and disconnect from WebSocket. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._session.disconnect() async def cleanup(self): + """Clean up the input transport resources.""" await super().cleanup() await self._transport.cleanup() async def on_message(self, websocket, message): + """Handle incoming WebSocket messages. + + Args: + websocket: The WebSocket connection that received the message. + message: The received message data. + """ if not self._params.serializer: return frame = await self._params.serializer.deserialize(message) @@ -177,12 +275,25 @@ class WebsocketClientInputTransport(BaseInputTransport): class WebsocketClientOutputTransport(BaseOutputTransport): + """WebSocket client output transport for sending frames. + + Handles outgoing frames, serializes them for WebSocket transmission, + and manages audio streaming with proper timing simulation. + """ + def __init__( self, transport: BaseTransport, session: WebsocketClientSession, params: WebsocketClientParams, ): + """Initialize the WebSocket client output transport. + + Args: + transport: The parent transport instance. + session: The WebSocket session to use for communication. + params: Configuration parameters for the transport. + """ super().__init__(params) self._transport = transport @@ -201,10 +312,20 @@ class WebsocketClientOutputTransport(BaseOutputTransport): self._initialized = False async def setup(self, setup: FrameProcessorSetup): + """Set up the output transport with the frame processor setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._session.setup(setup.task_manager) async def start(self, frame: StartFrame): + """Start the output transport and initialize the WebSocket connection. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -219,21 +340,42 @@ class WebsocketClientOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport and disconnect from WebSocket. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._session.disconnect() async def cancel(self, frame: CancelFrame): + """Cancel the output transport and disconnect from WebSocket. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._session.disconnect() async def cleanup(self): + """Clean up the output transport resources.""" await super().cleanup() await self._transport.cleanup() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message through the WebSocket. + + Args: + frame: The transport message frame to send. + """ await self._write_frame(frame) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the WebSocket with optional WAV header. + + Args: + frame: The output audio frame to write. + """ frame = OutputAudioRawFrame( audio=frame.audio, sample_rate=self.sample_rate, @@ -260,6 +402,7 @@ class WebsocketClientOutputTransport(BaseOutputTransport): await self._write_audio_sleep() async def _write_frame(self, frame: Frame): + """Write a frame to the WebSocket after serialization.""" if not self._params.serializer: return payload = await self._params.serializer.serialize(frame) @@ -267,6 +410,7 @@ class WebsocketClientOutputTransport(BaseOutputTransport): await self._session.send(payload) async def _write_audio_sleep(self): + """Simulate audio playback timing with sleep delays.""" # Simulate a clock. current_time = time.monotonic() sleep_duration = max(0, self._next_send_time - current_time) @@ -278,11 +422,23 @@ class WebsocketClientOutputTransport(BaseOutputTransport): class WebsocketClientTransport(BaseTransport): + """WebSocket client transport for bidirectional communication. + + Provides a complete WebSocket client transport implementation with + input and output capabilities, connection management, and event handling. + """ + def __init__( self, uri: str, params: Optional[WebsocketClientParams] = None, ): + """Initialize the WebSocket client transport. + + Args: + uri: The WebSocket URI to connect to. + params: Optional configuration parameters for the transport. + """ super().__init__() self._params = params or WebsocketClientParams() @@ -304,21 +460,34 @@ class WebsocketClientTransport(BaseTransport): self._register_event_handler("on_disconnected") def input(self) -> WebsocketClientInputTransport: + """Get the input transport for receiving frames. + + Returns: + The WebSocket client input transport instance. + """ if not self._input: self._input = WebsocketClientInputTransport(self, self._session, self._params) return self._input def output(self) -> WebsocketClientOutputTransport: + """Get the output transport for sending frames. + + Returns: + The WebSocket client output transport instance. + """ if not self._output: self._output = WebsocketClientOutputTransport(self, self._session, self._params) return self._output async def _on_connected(self, websocket): + """Handle WebSocket connection established event.""" await self._call_event_handler("on_connected", websocket) async def _on_disconnected(self, websocket): + """Handle WebSocket connection closed event.""" await self._call_event_handler("on_disconnected", websocket) async def _on_message(self, websocket, message): + """Handle incoming WebSocket message.""" if self._input: await self._input.on_message(websocket, message) diff --git a/src/pipecat/transports/network/websocket_server.py b/src/pipecat/transports/network/websocket_server.py index 1fe33f4a6..dbe418d3b 100644 --- a/src/pipecat/transports/network/websocket_server.py +++ b/src/pipecat/transports/network/websocket_server.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""WebSocket server transport implementation for Pipecat. + +This module provides WebSocket server transport functionality for real-time +audio and data streaming, including client connection management, session +handling, and frame serialization. +""" + import asyncio import io import time @@ -39,12 +46,29 @@ except ModuleNotFoundError as e: class WebsocketServerParams(TransportParams): + """Configuration parameters for WebSocket server transport. + + Parameters: + add_wav_header: Whether to add WAV headers to audio frames. + serializer: Frame serializer for message encoding/decoding. + session_timeout: Timeout in seconds for client sessions. + """ + add_wav_header: bool = False serializer: Optional[FrameSerializer] = None session_timeout: Optional[int] = None class WebsocketServerCallbacks(BaseModel): + """Callback functions for WebSocket server events. + + Parameters: + on_client_connected: Called when a client connects to the server. + on_client_disconnected: Called when a client disconnects from the server. + on_session_timeout: Called when a client session times out. + on_websocket_ready: Called when the WebSocket server is ready to accept connections. + """ + on_client_connected: Callable[[websockets.WebSocketServerProtocol], Awaitable[None]] on_client_disconnected: Callable[[websockets.WebSocketServerProtocol], Awaitable[None]] on_session_timeout: Callable[[websockets.WebSocketServerProtocol], Awaitable[None]] @@ -52,6 +76,12 @@ class WebsocketServerCallbacks(BaseModel): class WebsocketServerInputTransport(BaseInputTransport): + """WebSocket server input transport for receiving client data. + + Handles incoming WebSocket connections, message processing, and client + session management including timeout monitoring and connection lifecycle. + """ + def __init__( self, transport: BaseTransport, @@ -61,6 +91,16 @@ class WebsocketServerInputTransport(BaseInputTransport): callbacks: WebsocketServerCallbacks, **kwargs, ): + """Initialize the WebSocket server input transport. + + Args: + transport: The parent transport instance. + host: Host address to bind the WebSocket server to. + port: Port number to bind the WebSocket server to. + params: WebSocket server configuration parameters. + callbacks: Callback functions for WebSocket events. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport @@ -82,6 +122,11 @@ class WebsocketServerInputTransport(BaseInputTransport): self._initialized = False async def start(self, frame: StartFrame): + """Start the WebSocket server and initialize components. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -96,6 +141,11 @@ class WebsocketServerInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the WebSocket server and cleanup resources. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) self._stop_server_event.set() if self._monitor_task: @@ -106,6 +156,11 @@ class WebsocketServerInputTransport(BaseInputTransport): self._server_task = None async def cancel(self, frame: CancelFrame): + """Cancel the WebSocket server and stop all processing. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) if self._monitor_task: await self.cancel_task(self._monitor_task) @@ -115,16 +170,19 @@ class WebsocketServerInputTransport(BaseInputTransport): self._server_task = None async def cleanup(self): + """Cleanup resources and parent transport.""" await super().cleanup() await self._transport.cleanup() async def _server_task_handler(self): + """Handle WebSocket server startup and client connections.""" logger.info(f"Starting websocket server on {self._host}:{self._port}") async with websockets.serve(self._client_handler, self._host, self._port) as server: await self._callbacks.on_websocket_ready() await self._stop_server_event.wait() async def _client_handler(self, websocket: websockets.WebSocketServerProtocol, path): + """Handle individual client connections and message processing.""" logger.info(f"New client connection from {websocket.remote_address}") if self._websocket: await self._websocket.close() @@ -170,9 +228,7 @@ class WebsocketServerInputTransport(BaseInputTransport): async def _monitor_websocket( self, websocket: websockets.WebSocketServerProtocol, session_timeout: int ): - """Wait for session_timeout seconds, if the websocket is still open, - trigger timeout event. - """ + """Monitor WebSocket connection for session timeout.""" try: await asyncio.sleep(session_timeout) if not websocket.closed: @@ -183,7 +239,20 @@ class WebsocketServerInputTransport(BaseInputTransport): class WebsocketServerOutputTransport(BaseOutputTransport): + """WebSocket server output transport for sending data to clients. + + Handles outgoing frame serialization, audio streaming with timing control, + and client connection management for WebSocket communication. + """ + def __init__(self, transport: BaseTransport, params: WebsocketServerParams, **kwargs): + """Initialize the WebSocket server output transport. + + Args: + transport: The parent transport instance. + params: WebSocket server configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport @@ -203,12 +272,22 @@ class WebsocketServerOutputTransport(BaseOutputTransport): self._initialized = False async def set_client_connection(self, websocket: Optional[websockets.WebSocketServerProtocol]): + """Set the active client WebSocket connection. + + Args: + websocket: The WebSocket connection to set as active, or None to clear. + """ if self._websocket: await self._websocket.close() logger.warning("Only one client allowed, using new connection") self._websocket = websocket async def start(self, frame: StartFrame): + """Start the output transport and initialize components. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -222,18 +301,35 @@ class WebsocketServerOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport and send final frame. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._write_frame(frame) async def cancel(self, frame: CancelFrame): + """Cancel the output transport and send cancellation frame. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._write_frame(frame) async def cleanup(self): + """Cleanup resources and parent transport.""" await super().cleanup() await self._transport.cleanup() async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and handle interruption timing. + + 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): @@ -241,9 +337,19 @@ class WebsocketServerOutputTransport(BaseOutputTransport): self._next_send_time = 0 async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message frame to the client. + + Args: + frame: The transport message frame to send. + """ await self._write_frame(frame) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the WebSocket client with timing control. + + Args: + frame: The output audio frame to write. + """ if not self._websocket: # Simulate audio playback with a sleep. await self._write_audio_sleep() @@ -275,6 +381,7 @@ class WebsocketServerOutputTransport(BaseOutputTransport): await self._write_audio_sleep() async def _write_frame(self, frame: Frame): + """Serialize and send a frame to the WebSocket client.""" if not self._params.serializer: return @@ -286,6 +393,7 @@ class WebsocketServerOutputTransport(BaseOutputTransport): logger.error(f"{self} exception sending data: {e.__class__.__name__} ({e})") async def _write_audio_sleep(self): + """Simulate audio device timing by sleeping between audio chunks.""" # Simulate a clock. current_time = time.monotonic() sleep_duration = max(0, self._next_send_time - current_time) @@ -297,6 +405,13 @@ class WebsocketServerOutputTransport(BaseOutputTransport): class WebsocketServerTransport(BaseTransport): + """WebSocket server transport for bidirectional real-time communication. + + Provides a complete WebSocket server implementation with separate input and + output transports, client connection management, and event handling for + real-time audio and data streaming applications. + """ + def __init__( self, params: WebsocketServerParams, @@ -305,6 +420,15 @@ class WebsocketServerTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the WebSocket server transport. + + Args: + params: WebSocket server configuration parameters. + host: Host address to bind the server to. Defaults to "localhost". + port: Port number to bind the server to. Defaults to 8765. + input_name: Optional name for the input processor. + output_name: Optional name for the output processor. + """ super().__init__(input_name=input_name, output_name=output_name) self._host = host self._port = port @@ -328,6 +452,11 @@ class WebsocketServerTransport(BaseTransport): self._register_event_handler("on_websocket_ready") def input(self) -> WebsocketServerInputTransport: + """Get the input transport for receiving client data. + + Returns: + The WebSocket server input transport instance. + """ if not self._input: self._input = WebsocketServerInputTransport( self, self._host, self._port, self._params, self._callbacks, name=self._input_name @@ -335,6 +464,11 @@ class WebsocketServerTransport(BaseTransport): return self._input def output(self) -> WebsocketServerOutputTransport: + """Get the output transport for sending data to clients. + + Returns: + The WebSocket server output transport instance. + """ if not self._output: self._output = WebsocketServerOutputTransport( self, self._params, name=self._output_name @@ -342,6 +476,7 @@ class WebsocketServerTransport(BaseTransport): return self._output async def _on_client_connected(self, websocket): + """Handle client connection events.""" if self._output: await self._output.set_client_connection(websocket) await self._call_event_handler("on_client_connected", websocket) @@ -349,6 +484,7 @@ class WebsocketServerTransport(BaseTransport): logger.error("A WebsocketServerTransport output is missing in the pipeline") async def _on_client_disconnected(self, websocket): + """Handle client disconnection events.""" if self._output: await self._output.set_client_connection(None) await self._call_event_handler("on_client_disconnected", websocket) @@ -356,7 +492,9 @@ class WebsocketServerTransport(BaseTransport): logger.error("A WebsocketServerTransport output is missing in the pipeline") async def _on_session_timeout(self, websocket): + """Handle client session timeout events.""" await self._call_event_handler("on_session_timeout", websocket) async def _on_websocket_ready(self): + """Handle WebSocket server ready events.""" await self._call_event_handler("on_websocket_ready") diff --git a/src/pipecat/transports/services/daily.py b/src/pipecat/transports/services/daily.py index 4c00fa44c..b62aa4b6e 100644 --- a/src/pipecat/transports/services/daily.py +++ b/src/pipecat/transports/services/daily.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Daily transport implementation for Pipecat. + +This module provides comprehensive Daily video conferencing integration including +audio/video streaming, transcription, recording, dial-in/out functionality, and +real-time communication features. +""" + import asyncio import time from concurrent.futures import ThreadPoolExecutor @@ -67,7 +74,7 @@ VAD_RESET_PERIOD_MS = 2000 class DailyTransportMessageFrame(TransportMessageFrame): """Frame for transport messages in Daily calls. - Attributes: + Parameters: participant_id: Optional ID of the participant this message is for/from. """ @@ -78,7 +85,7 @@ class DailyTransportMessageFrame(TransportMessageFrame): class DailyTransportMessageUrgentFrame(TransportMessageUrgentFrame): """Frame for urgent transport messages in Daily calls. - Attributes: + Parameters: participant_id: Optional ID of the participant this message is for/from. """ @@ -89,13 +96,15 @@ class WebRTCVADAnalyzer(VADAnalyzer): """Voice Activity Detection analyzer using WebRTC. Implements voice activity detection using Daily's native WebRTC VAD. - - Args: - sample_rate: Audio sample rate in Hz. - params: VAD configuration parameters (VADParams). """ def __init__(self, *, sample_rate: Optional[int] = None, params: Optional[VADParams] = None): + """Initialize the WebRTC VAD analyzer. + + Args: + sample_rate: Audio sample rate in Hz. + params: VAD configuration parameters. + """ super().__init__(sample_rate=sample_rate, params=params) self._webrtc_vad = Daily.create_native_vad( @@ -104,9 +113,22 @@ class WebRTCVADAnalyzer(VADAnalyzer): logger.debug("Loaded native WebRTC VAD") def num_frames_required(self) -> int: + """Get the number of audio frames required for VAD analysis. + + Returns: + The number of frames needed (equivalent to 10ms of audio). + """ return int(self.sample_rate / 100.0) def voice_confidence(self, buffer) -> float: + """Analyze audio buffer and return voice confidence score. + + Args: + buffer: Audio buffer to analyze. + + Returns: + Voice confidence score between 0.0 and 1.0. + """ confidence = 0 if len(buffer) > 0: confidence = self._webrtc_vad.analyze_frames(buffer) @@ -116,7 +138,7 @@ class WebRTCVADAnalyzer(VADAnalyzer): class DailyDialinSettings(BaseModel): """Settings for Daily's dial-in functionality. - Attributes: + Parameters: call_id: CallId is represented by UUID and represents the sessionId in the SIP Network. call_domain: Call Domain is represented by UUID and represents your Daily Domain on the SIP Network. """ @@ -128,7 +150,7 @@ class DailyDialinSettings(BaseModel): class DailyTranscriptionSettings(BaseModel): """Configuration settings for Daily's transcription service. - Attributes: + Parameters: language: ISO language code for transcription (e.g. "en"). model: Transcription model to use (e.g. "nova-2-general"). profanity_filter: Whether to filter profanity from transcripts. @@ -152,14 +174,14 @@ class DailyTranscriptionSettings(BaseModel): class DailyParams(TransportParams): """Configuration parameters for Daily transport. - Args: - api_url: Daily API base URL - api_key: Daily API authentication key - dialin_settings: Optional settings for dial-in functionality - camera_out_enabled: Whether to enable the main camera output track. If enabled, it still needs `video_out_enabled=True` - microphone_out_enabled: Whether to enable the main microphone track. If enabled, it still needs `audio_out_enabled=True` - transcription_enabled: Whether to enable speech transcription - transcription_settings: Configuration for transcription service + Parameters: + api_url: Daily API base URL. + api_key: Daily API authentication key. + dialin_settings: Optional settings for dial-in functionality. + camera_out_enabled: Whether to enable the main camera output track. + microphone_out_enabled: Whether to enable the main microphone track. + transcription_enabled: Whether to enable speech transcription. + transcription_settings: Configuration for transcription service. """ api_url: str = "https://api.daily.co/v1" @@ -174,7 +196,7 @@ class DailyParams(TransportParams): class DailyCallbacks(BaseModel): """Callback handlers for Daily events. - Attributes: + Parameters: on_active_speaker_changed: Called when the active speaker of the call has changed. on_joined: Called when bot successfully joined a room. on_left: Called when bot left a room. @@ -230,6 +252,15 @@ class DailyCallbacks(BaseModel): def completion_callback(future): + """Create a completion callback for Daily API calls. + + Args: + future: The asyncio Future to set the result on. + + Returns: + A callback function that sets the future result. + """ + def _callback(*args): def set_result(future, *args): try: @@ -247,6 +278,13 @@ def completion_callback(future): @dataclass class DailyAudioTrack: + """Container for Daily audio track components. + + Parameters: + source: The custom audio source for the track. + track: The custom audio track instance. + """ + source: CustomAudioSource track: CustomAudioTrack @@ -254,21 +292,14 @@ class DailyAudioTrack: class DailyTransportClient(EventHandler): """Core client for interacting with Daily's API. - Manages the connection to Daily rooms and handles all low-level API interactions. - - Args: - room_url: URL of the Daily room to connect to. - token: Optional authentication token for the room. - bot_name: Display name for the bot in the call. - params: Configuration parameters (DailyParams). - callbacks: Event callback handlers (DailyCallbacks). - transport_name: Name identifier for the transport. + Manages the connection to Daily rooms and handles all low-level API interactions + including room management, media streaming, transcription, and event handling. """ _daily_initialized: bool = False - # This is necessary to override EventHandler's __new__ method. def __new__(cls, *args, **kwargs): + """Override EventHandler's __new__ method to ensure Daily is initialized only once.""" return super().__new__(cls) def __init__( @@ -280,6 +311,16 @@ class DailyTransportClient(EventHandler): callbacks: DailyCallbacks, transport_name: str, ): + """Initialize the Daily transport client. + + Args: + room_url: URL of the Daily room to connect to. + token: Optional authentication token for the room. + bot_name: Display name for the bot in the call. + params: Configuration parameters for the transport. + callbacks: Event callback handlers. + transport_name: Name identifier for the transport. + """ super().__init__() if not DailyTransportClient._daily_initialized: @@ -335,25 +376,51 @@ class DailyTransportClient(EventHandler): self._custom_audio_tracks: Dict[str, DailyAudioTrack] = {} def _camera_name(self): + """Generate a unique camera name for this client instance.""" return f"camera-{self}" @property def room_url(self) -> str: + """Get the Daily room URL. + + Returns: + The room URL this client is connected to. + """ return self._room_url @property def participant_id(self) -> str: + """Get the participant ID for this client. + + Returns: + The participant ID assigned by Daily. + """ return self._participant_id @property def in_sample_rate(self) -> int: + """Get the input audio sample rate. + + Returns: + The input sample rate in Hz. + """ return self._in_sample_rate @property def out_sample_rate(self) -> int: + """Get the output audio sample rate. + + Returns: + The output sample rate in Hz. + """ return self._out_sample_rate async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send an application message to participants. + + Args: + frame: The message frame to send. + """ if not self._joined: return @@ -368,10 +435,20 @@ class DailyTransportClient(EventHandler): await future async def register_audio_destination(self, destination: str): + """Register a custom audio destination for multi-track output. + + Args: + destination: The destination identifier to register. + """ self._custom_audio_tracks[destination] = await self.add_custom_audio_track(destination) self._client.update_publishing({"customAudio": {destination: True}}) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the appropriate audio track. + + Args: + frame: The audio frame to write. + """ future = self._get_event_loop().create_future() destination = frame.transport_destination @@ -391,10 +468,20 @@ class DailyTransportClient(EventHandler): await future async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the camera device. + + Args: + frame: The image frame to write. + """ if not frame.transport_destination and self._camera: self._camera.write_frame(frame.image) async def setup(self, setup: FrameProcessorSetup): + """Setup the client with task manager and event queues. + + Args: + setup: The frame processor setup configuration. + """ if self._task_manager: return @@ -408,6 +495,7 @@ class DailyTransportClient(EventHandler): ) async def cleanup(self): + """Cleanup client resources and cancel tasks.""" if self._event_task and self._task_manager: await self._task_manager.cancel_task(self._event_task) self._event_task = None @@ -422,6 +510,11 @@ class DailyTransportClient(EventHandler): await self._get_event_loop().run_in_executor(self._executor, self._cleanup) async def start(self, frame: StartFrame): + """Start the client and initialize audio/video components. + + Args: + frame: The start frame containing initialization parameters. + """ self._in_sample_rate = self._params.audio_in_sample_rate or frame.audio_in_sample_rate self._out_sample_rate = self._params.audio_out_sample_rate or frame.audio_out_sample_rate @@ -452,6 +545,7 @@ class DailyTransportClient(EventHandler): self._microphone_track = DailyAudioTrack(source=audio_source, track=audio_track) async def join(self): + """Join the Daily room with configured settings.""" # Transport already joined or joining, ignore. if self._joined or self._joining: # Increment leave counter if we already joined. @@ -497,6 +591,7 @@ class DailyTransportClient(EventHandler): await self._callbacks.on_error(error_msg) async def _join(self): + """Execute the actual room join operation.""" future = self._get_event_loop().create_future() camera_enabled = self._params.video_out_enabled and self._params.camera_out_enabled @@ -552,6 +647,7 @@ class DailyTransportClient(EventHandler): return await asyncio.wait_for(future, timeout=10) async def leave(self): + """Leave the Daily room and cleanup resources.""" # Decrement leave counter when leaving. self._leave_counter -= 1 @@ -586,22 +682,39 @@ class DailyTransportClient(EventHandler): await self._callbacks.on_error(error_msg) async def _leave(self): + """Execute the actual room leave operation.""" future = self._get_event_loop().create_future() self._client.leave(completion=completion_callback(future)) return await asyncio.wait_for(future, timeout=10) def _cleanup(self): + """Cleanup the Daily client instance.""" if self._client: self._client.release() self._client = None def participants(self): + """Get current participants in the room. + + Returns: + Dictionary of participants keyed by participant ID. + """ return self._client.participants() def participant_counts(self): + """Get participant count information. + + Returns: + Dictionary with participant count details. + """ return self._client.participant_counts() async def start_dialout(self, settings): + """Start a dial-out call to a phone number. + + Args: + settings: Dial-out configuration settings. + """ logger.debug(f"Starting dialout: settings={settings}") future = self._get_event_loop().create_future() @@ -611,6 +724,11 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to start dialout: {error}") async def stop_dialout(self, participant_id): + """Stop a dial-out call for a specific participant. + + Args: + participant_id: ID of the participant to stop dial-out for. + """ logger.debug(f"Stopping dialout: participant_id={participant_id}") future = self._get_event_loop().create_future() @@ -620,21 +738,43 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to stop dialout: {error}") async def send_dtmf(self, settings): + """Send DTMF tones during a call. + + Args: + settings: DTMF settings including tones and target session. + """ future = self._get_event_loop().create_future() self._client.send_dtmf(settings, completion=completion_callback(future)) await future async def sip_call_transfer(self, settings): + """Transfer a SIP call to another destination. + + Args: + settings: SIP call transfer settings. + """ future = self._get_event_loop().create_future() self._client.sip_call_transfer(settings, completion=completion_callback(future)) await future async def sip_refer(self, settings): + """Send a SIP REFER request. + + Args: + settings: SIP REFER settings. + """ future = self._get_event_loop().create_future() self._client.sip_refer(settings, completion=completion_callback(future)) await future async def start_recording(self, streaming_settings, stream_id, force_new): + """Start recording the call. + + Args: + streaming_settings: Recording configuration settings. + stream_id: Unique identifier for the recording stream. + force_new: Whether to force a new recording session. + """ logger.debug( f"Starting recording: stream_id={stream_id} force_new={force_new} settings={streaming_settings}" ) @@ -648,6 +788,11 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to start recording: {error}") async def stop_recording(self, stream_id): + """Stop recording the call. + + Args: + stream_id: Unique identifier for the recording stream to stop. + """ logger.debug(f"Stopping recording: stream_id={stream_id}") future = self._get_event_loop().create_future() @@ -657,6 +802,11 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to stop recording: {error}") async def start_transcription(self, settings): + """Start transcription for the call. + + Args: + settings: Transcription configuration settings. + """ if not self._token: logger.warning("Transcription can't be started without a room token") return @@ -673,6 +823,7 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to start transcription: {error}") async def stop_transcription(self): + """Stop transcription for the call.""" if not self._token: return @@ -685,6 +836,12 @@ class DailyTransportClient(EventHandler): logger.error(f"Unable to stop transcription: {error}") async def send_prebuilt_chat_message(self, message: str, user_name: Optional[str] = None): + """Send a chat message to Daily's Prebuilt main room. + + Args: + message: The chat message to send. + user_name: Optional user name that will appear as sender of the message. + """ if not self._joined: return @@ -695,6 +852,11 @@ class DailyTransportClient(EventHandler): await future async def capture_participant_transcription(self, participant_id: str): + """Enable transcription capture for a specific participant. + + Args: + participant_id: ID of the participant to capture transcription for. + """ if not self._params.transcription_enabled: return @@ -710,6 +872,15 @@ class DailyTransportClient(EventHandler): sample_rate: int = 16000, callback_interval_ms: int = 20, ): + """Capture audio from a specific participant. + + Args: + participant_id: ID of the participant to capture audio from. + callback: Callback function to handle audio data. + audio_source: Audio source to capture (microphone, screenAudio, or custom). + sample_rate: Desired sample rate for audio capture. + callback_interval_ms: Interval between audio callbacks in milliseconds. + """ # Only enable the desired audio source subscription on this participant. if audio_source in ("microphone", "screenAudio"): media = {"media": {audio_source: "subscribed"}} @@ -740,6 +911,15 @@ class DailyTransportClient(EventHandler): video_source: str = "camera", color_format: str = "RGB", ): + """Capture video from a specific participant. + + Args: + participant_id: ID of the participant to capture video from. + callback: Callback function to handle video frames. + framerate: Desired framerate for video capture. + video_source: Video source to capture (camera, screenVideo, or custom). + color_format: Color format for video frames. + """ # Only enable the desired audio source subscription on this participant. if video_source in ("camera", "screenVideo"): media = {"media": {video_source: "subscribed"}} @@ -762,6 +942,14 @@ class DailyTransportClient(EventHandler): ) async def add_custom_audio_track(self, track_name: str) -> DailyAudioTrack: + """Add a custom audio track for multi-stream output. + + Args: + track_name: Name for the custom audio track. + + Returns: + The created DailyAudioTrack instance. + """ future = self._get_event_loop().create_future() audio_source = CustomAudioSource(self._out_sample_rate, 1) @@ -782,6 +970,11 @@ class DailyTransportClient(EventHandler): return track async def remove_custom_audio_track(self, track_name: str): + """Remove a custom audio track. + + Args: + track_name: Name of the custom audio track to remove. + """ future = self._get_event_loop().create_future() self._client.remove_custom_audio_track( track_name=track_name, @@ -790,6 +983,12 @@ class DailyTransportClient(EventHandler): await future async def update_transcription(self, participants=None, instance_id=None): + """Update transcription settings for specific participants. + + Args: + participants: List of participant IDs to enable transcription for. + instance_id: Optional transcription instance ID. + """ future = self._get_event_loop().create_future() self._client.update_transcription( participants, instance_id, completion=completion_callback(future) @@ -797,6 +996,12 @@ class DailyTransportClient(EventHandler): await future async def update_subscriptions(self, participant_settings=None, profile_settings=None): + """Update media subscription settings. + + Args: + participant_settings: Per-participant subscription settings. + profile_settings: Global subscription profile settings. + """ future = self._get_event_loop().create_future() self._client.update_subscriptions( participant_settings=participant_settings, @@ -806,6 +1011,11 @@ class DailyTransportClient(EventHandler): await future async def update_publishing(self, publishing_settings: Mapping[str, Any]): + """Update media publishing settings. + + Args: + publishing_settings: Publishing configuration settings. + """ future = self._get_event_loop().create_future() self._client.update_publishing( publishing_settings=publishing_settings, @@ -814,6 +1024,11 @@ class DailyTransportClient(EventHandler): await future async def update_remote_participants(self, remote_participants: Mapping[str, Any]): + """Update settings for remote participants. + + Args: + remote_participants: Remote participant configuration settings. + """ future = self._get_event_loop().create_future() self._client.update_remote_participants( remote_participants=remote_participants, completion=completion_callback(future) @@ -826,76 +1041,195 @@ class DailyTransportClient(EventHandler): # def on_active_speaker_changed(self, participant): + """Handle active speaker change events. + + Args: + participant: The new active speaker participant info. + """ self._call_event_callback(self._callbacks.on_active_speaker_changed, participant) def on_app_message(self, message: Any, sender: str): + """Handle application message events. + + Args: + message: The received message data. + sender: ID of the message sender. + """ self._call_event_callback(self._callbacks.on_app_message, message, sender) def on_call_state_updated(self, state: str): + """Handle call state update events. + + Args: + state: The new call state. + """ self._call_event_callback(self._callbacks.on_call_state_updated, state) def on_dialin_connected(self, data: Any): + """Handle dial-in connected events. + + Args: + data: Dial-in connection data. + """ self._call_event_callback(self._callbacks.on_dialin_connected, data) def on_dialin_ready(self, sip_endpoint: str): + """Handle dial-in ready events. + + Args: + sip_endpoint: The SIP endpoint for dial-in. + """ self._call_event_callback(self._callbacks.on_dialin_ready, sip_endpoint) def on_dialin_stopped(self, data: Any): + """Handle dial-in stopped events. + + Args: + data: Dial-in stop data. + """ self._call_event_callback(self._callbacks.on_dialin_stopped, data) def on_dialin_error(self, data: Any): + """Handle dial-in error events. + + Args: + data: Dial-in error data. + """ self._call_event_callback(self._callbacks.on_dialin_error, data) def on_dialin_warning(self, data: Any): + """Handle dial-in warning events. + + Args: + data: Dial-in warning data. + """ self._call_event_callback(self._callbacks.on_dialin_warning, data) def on_dialout_answered(self, data: Any): + """Handle dial-out answered events. + + Args: + data: Dial-out answered data. + """ self._call_event_callback(self._callbacks.on_dialout_answered, data) def on_dialout_connected(self, data: Any): + """Handle dial-out connected events. + + Args: + data: Dial-out connection data. + """ self._call_event_callback(self._callbacks.on_dialout_connected, data) def on_dialout_stopped(self, data: Any): + """Handle dial-out stopped events. + + Args: + data: Dial-out stop data. + """ self._call_event_callback(self._callbacks.on_dialout_stopped, data) def on_dialout_error(self, data: Any): + """Handle dial-out error events. + + Args: + data: Dial-out error data. + """ self._call_event_callback(self._callbacks.on_dialout_error, data) def on_dialout_warning(self, data: Any): + """Handle dial-out warning events. + + Args: + data: Dial-out warning data. + """ self._call_event_callback(self._callbacks.on_dialout_warning, data) def on_participant_joined(self, participant): + """Handle participant joined events. + + Args: + participant: The participant that joined. + """ self._call_event_callback(self._callbacks.on_participant_joined, participant) def on_participant_left(self, participant, reason): + """Handle participant left events. + + Args: + participant: The participant that left. + reason: Reason for leaving. + """ self._call_event_callback(self._callbacks.on_participant_left, participant, reason) def on_participant_updated(self, participant): + """Handle participant updated events. + + Args: + participant: The updated participant info. + """ self._call_event_callback(self._callbacks.on_participant_updated, participant) def on_transcription_started(self, status): + """Handle transcription started events. + + Args: + status: Transcription start status. + """ logger.debug(f"Transcription started: {status}") self._transcription_status = status self._call_event_callback(self.update_transcription, self._transcription_ids) def on_transcription_stopped(self, stopped_by, stopped_by_error): + """Handle transcription stopped events. + + Args: + stopped_by: Who stopped the transcription. + stopped_by_error: Whether stopped due to error. + """ logger.debug("Transcription stopped") def on_transcription_error(self, message): + """Handle transcription error events. + + Args: + message: Error message. + """ logger.error(f"Transcription error: {message}") def on_transcription_message(self, message): + """Handle transcription message events. + + Args: + message: The transcription message data. + """ self._call_event_callback(self._callbacks.on_transcription_message, message) def on_recording_started(self, status): + """Handle recording started events. + + Args: + status: Recording start status. + """ logger.debug(f"Recording started: {status}") self._call_event_callback(self._callbacks.on_recording_started, status) def on_recording_stopped(self, stream_id): + """Handle recording stopped events. + + Args: + stream_id: ID of the stopped recording stream. + """ logger.debug(f"Recording stopped: {stream_id}") self._call_event_callback(self._callbacks.on_recording_stopped, stream_id) def on_recording_error(self, stream_id, message): + """Handle recording error events. + + Args: + stream_id: ID of the recording stream with error. + message: Error message. + """ logger.error(f"Recording error for {stream_id}: {message}") self._call_event_callback(self._callbacks.on_recording_error, stream_id, message) @@ -904,12 +1238,14 @@ class DailyTransportClient(EventHandler): # def _audio_data_received(self, participant_id: str, audio_data: AudioData, audio_source: str): + """Handle received audio data from participants.""" callback = self._audio_renderers[participant_id][audio_source] self._call_audio_callback(callback, participant_id, audio_data, audio_source) def _video_frame_received( self, participant_id: str, video_frame: VideoFrame, video_source: str ): + """Handle received video frames from participants.""" callback = self._video_renderers[participant_id][video_source] self._call_video_callback(callback, participant_id, video_frame, video_source) @@ -918,21 +1254,26 @@ class DailyTransportClient(EventHandler): # def _call_audio_callback(self, callback, *args): + """Queue an audio callback for async execution.""" self._call_async_callback(self._audio_queue, callback, *args) def _call_video_callback(self, callback, *args): + """Queue a video callback for async execution.""" self._call_async_callback(self._video_queue, callback, *args) def _call_event_callback(self, callback, *args): + """Queue an event callback for async execution.""" self._call_async_callback(self._event_queue, callback, *args) def _call_async_callback(self, queue: asyncio.Queue, callback, *args): + """Queue a callback for async execution on the event loop.""" future = asyncio.run_coroutine_threadsafe( queue.put((callback, *args)), self._get_event_loop() ) future.result() async def _callback_task_handler(self, queue: asyncio.Queue): + """Handle queued callbacks from the specified queue.""" while True: # Wait to process any callback until we are joined. await self._joined_event.wait() @@ -941,22 +1282,21 @@ class DailyTransportClient(EventHandler): queue.task_done() def _get_event_loop(self) -> asyncio.AbstractEventLoop: + """Get the event loop from the task manager.""" if not self._task_manager: raise Exception(f"{self}: missing task manager (pipeline not started?)") return self._task_manager.get_event_loop() def __str__(self): + """String representation of the DailyTransportClient.""" return f"{self._transport_name}::DailyTransportClient" class DailyInputTransport(BaseInputTransport): """Handles incoming media streams and events from Daily calls. - Processes incoming audio, video, transcriptions and other events from Daily. - - Args: - client: DailyTransportClient instance. - params: Configuration parameters. + Processes incoming audio, video, transcriptions and other events from Daily + room participants, including participant media capture and event forwarding. """ def __init__( @@ -966,6 +1306,14 @@ class DailyInputTransport(BaseInputTransport): params: DailyParams, **kwargs, ): + """Initialize the Daily input transport. + + Args: + transport: The parent transport instance. + client: DailyTransportClient instance. + params: Configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport @@ -988,9 +1336,15 @@ class DailyInputTransport(BaseInputTransport): @property def vad_analyzer(self) -> Optional[VADAnalyzer]: + """Get the Voice Activity Detection analyzer. + + Returns: + The VAD analyzer instance if configured. + """ return self._vad_analyzer async def start_audio_in_streaming(self): + """Start receiving audio from participants.""" if not self._params.audio_in_enabled: return @@ -1003,15 +1357,26 @@ class DailyInputTransport(BaseInputTransport): self._streaming_started = True async def setup(self, setup: FrameProcessorSetup): + """Setup the input transport with shared client setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup input transport and shared resources.""" await super().cleanup() await self._client.cleanup() await self._transport.cleanup() async def start(self, frame: StartFrame): + """Start the input transport and join the Daily room. + + Args: + frame: The start frame containing initialization parameters. + """ # Parent start. await super().start(frame) @@ -1033,12 +1398,22 @@ class DailyInputTransport(BaseInputTransport): await self.start_audio_in_streaming() async def stop(self, frame: EndFrame): + """Stop the input transport and leave the Daily room. + + Args: + frame: The end frame signaling transport shutdown. + """ # Parent stop. await super().stop(frame) # Leave the room. await self._client.leave() async def cancel(self, frame: CancelFrame): + """Cancel the input transport and leave the Daily room. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ # Parent stop. await super().cancel(frame) # Leave the room. @@ -1049,6 +1424,12 @@ class DailyInputTransport(BaseInputTransport): # async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process incoming frames, including user image requests. + + Args: + frame: The frame to process. + direction: The direction of frame flow in the pipeline. + """ await super().process_frame(frame, direction) if isinstance(frame, UserImageRequestFrame): @@ -1059,9 +1440,20 @@ class DailyInputTransport(BaseInputTransport): # async def push_transcription_frame(self, frame: TranscriptionFrame | InterimTranscriptionFrame): + """Push a transcription frame downstream. + + Args: + frame: The transcription frame to push. + """ await self.push_frame(frame) async def push_app_message(self, message: Any, sender: str): + """Push an application message as an urgent transport frame. + + Args: + message: The message data to send. + sender: ID of the message sender. + """ frame = DailyTransportMessageUrgentFrame(message=message, participant_id=sender) await self.push_frame(frame) @@ -1075,6 +1467,13 @@ class DailyInputTransport(BaseInputTransport): audio_source: str = "microphone", sample_rate: int = 16000, ): + """Capture audio from a specific participant. + + Args: + participant_id: ID of the participant to capture audio from. + audio_source: Audio source to capture from. + sample_rate: Desired sample rate for audio capture. + """ if self._streaming_started: await self._client.capture_participant_audio( participant_id, self._on_participant_audio_data, audio_source, sample_rate @@ -1085,6 +1484,7 @@ class DailyInputTransport(BaseInputTransport): async def _on_participant_audio_data( self, participant_id: str, audio: AudioData, audio_source: str ): + """Handle received participant audio data.""" frame = UserAudioRawFrame( user_id=participant_id, audio=audio.audio_frames, @@ -1105,6 +1505,14 @@ class DailyInputTransport(BaseInputTransport): video_source: str = "camera", color_format: str = "RGB", ): + """Capture video from a specific participant. + + Args: + participant_id: ID of the participant to capture video from. + framerate: Desired framerate for video capture. + video_source: Video source to capture from. + color_format: Color format for video frames. + """ if participant_id not in self._video_renderers: self._video_renderers[participant_id] = {} @@ -1119,6 +1527,11 @@ class DailyInputTransport(BaseInputTransport): ) async def request_participant_image(self, frame: UserImageRequestFrame): + """Request a video frame from a specific participant. + + Args: + frame: The user image request frame. + """ if frame.user_id in self._video_renderers: video_source = frame.video_source if frame.video_source else "camera" self._video_renderers[frame.user_id][video_source]["render_next_frame"].append(frame) @@ -1126,6 +1539,7 @@ class DailyInputTransport(BaseInputTransport): async def _on_participant_video_frame( self, participant_id: str, video_frame: VideoFrame, video_source: str ): + """Handle received participant video frames.""" render_frame = False curr_time = time.time() @@ -1161,16 +1575,21 @@ class DailyInputTransport(BaseInputTransport): class DailyOutputTransport(BaseOutputTransport): """Handles outgoing media streams and events to Daily calls. - Manages sending audio, video and other data to Daily calls. - - Args: - client: DailyTransportClient instance. - params: Configuration parameters. + Manages sending audio, video, DTMF tones, and other data to Daily calls, + including audio destination registration and message transmission. """ def __init__( self, transport: BaseTransport, client: DailyTransportClient, params: DailyParams, **kwargs ): + """Initialize the Daily output transport. + + Args: + transport: The parent transport instance. + client: DailyTransportClient instance. + params: Configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport @@ -1180,15 +1599,26 @@ class DailyOutputTransport(BaseOutputTransport): self._initialized = False async def setup(self, setup: FrameProcessorSetup): + """Setup the output transport with shared client setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup output transport and shared resources.""" await super().cleanup() await self._client.cleanup() await self._transport.cleanup() async def start(self, frame: StartFrame): + """Start the output transport and join the Daily room. + + Args: + frame: The start frame containing initialization parameters. + """ # Parent start. await super().start(frame) @@ -1207,27 +1637,57 @@ class DailyOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport and leave the Daily room. + + Args: + frame: The end frame signaling transport shutdown. + """ # Parent stop. await super().stop(frame) # Leave the room. await self._client.leave() async def cancel(self, frame: CancelFrame): + """Cancel the output transport and leave the Daily room. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ # Parent stop. await super().cancel(frame) # Leave the room. await self._client.leave() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message to participants. + + Args: + frame: The transport message frame to send. + """ await self._client.send_message(frame) async def register_video_destination(self, destination: str): + """Register a video output destination. + + Args: + destination: The destination identifier to register. + """ logger.warning(f"{self} registering video destinations is not supported yet") async def register_audio_destination(self, destination: str): + """Register an audio output destination. + + Args: + destination: The destination identifier to register. + """ await self._client.register_audio_destination(destination) async def write_dtmf(self, frame: OutputDTMFFrame | OutputDTMFUrgentFrame): + """Write DTMF tones to the call. + + Args: + frame: The DTMF frame containing tone information. + """ await self._client.send_dtmf( { "sessionId": frame.transport_destination, @@ -1236,25 +1696,28 @@ class DailyOutputTransport(BaseOutputTransport): ) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the Daily call. + + Args: + frame: The audio frame to write. + """ await self._client.write_audio_frame(frame) async def write_video_frame(self, frame: OutputImageRawFrame): + """Write a video frame to the Daily call. + + Args: + frame: The video frame to write. + """ await self._client.write_video_frame(frame) class DailyTransport(BaseTransport): """Transport implementation for Daily audio and video calls. - Handles audio/video streaming, transcription, recordings, dial-in, - dial-out, and call management through Daily's API. - - Args: - room_url: URL of the Daily room to connect to. - token: Optional authentication token for the room. - bot_name: Display name for the bot in the call. - params: Configuration parameters (DailyParams) for the transport. - input_name: Optional name for the input transport. - output_name: Optional name for the output transport. + Provides comprehensive Daily integration including audio/video streaming, + transcription, recording, dial-in/out functionality, and real-time communication + features for conversational AI applications. """ def __init__( @@ -1266,6 +1729,16 @@ class DailyTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the Daily transport. + + Args: + room_url: URL of the Daily room to connect to. + token: Optional authentication token for the room. + bot_name: Display name for the bot in the call. + params: Configuration parameters for the transport. + input_name: Optional name for the input transport. + output_name: Optional name for the output transport. + """ super().__init__(input_name=input_name, output_name=output_name) callbacks = DailyCallbacks( @@ -1339,6 +1812,11 @@ class DailyTransport(BaseTransport): # def input(self) -> DailyInputTransport: + """Get the input transport for receiving media and events. + + Returns: + The Daily input transport instance. + """ if not self._input: self._input = DailyInputTransport( self, self._client, self._params, name=self._input_name @@ -1346,6 +1824,11 @@ class DailyTransport(BaseTransport): return self._input def output(self) -> DailyOutputTransport: + """Get the output transport for sending media and events. + + Returns: + The Daily output transport instance. + """ if not self._output: self._output = DailyOutputTransport( self, self._client, self._params, name=self._output_name @@ -1358,33 +1841,78 @@ class DailyTransport(BaseTransport): @property def room_url(self) -> str: + """Get the Daily room URL. + + Returns: + The room URL this transport is connected to. + """ return self._client.room_url @property def participant_id(self) -> str: + """Get the participant ID for this transport. + + Returns: + The participant ID assigned by Daily. + """ return self._client.participant_id async def send_image(self, frame: OutputImageRawFrame | SpriteFrame): + """Send an image frame to the Daily call. + + Args: + frame: The image frame to send. + """ if self._output: await self._output.queue_frame(frame, FrameDirection.DOWNSTREAM) async def send_audio(self, frame: OutputAudioRawFrame): + """Send an audio frame to the Daily call. + + Args: + frame: The audio frame to send. + """ if self._output: await self._output.queue_frame(frame, FrameDirection.DOWNSTREAM) def participants(self): + """Get current participants in the room. + + Returns: + Dictionary of participants keyed by participant ID. + """ return self._client.participants() def participant_counts(self): + """Get participant count information. + + Returns: + Dictionary with participant count details. + """ return self._client.participant_counts() async def start_dialout(self, settings=None): + """Start a dial-out call to a phone number. + + Args: + settings: Dial-out configuration settings. + """ await self._client.start_dialout(settings) async def stop_dialout(self, participant_id): + """Stop a dial-out call for a specific participant. + + Args: + participant_id: ID of the participant to stop dial-out for. + """ await self._client.stop_dialout(participant_id) async def send_dtmf(self, settings): + """Send DTMF tones during a call (deprecated). + + Args: + settings: DTMF settings including tones and target session. + """ import warnings with warnings.catch_warnings(): @@ -1396,33 +1924,66 @@ class DailyTransport(BaseTransport): await self._client.send_dtmf(settings) async def sip_call_transfer(self, settings): + """Transfer a SIP call to another destination. + + Args: + settings: SIP call transfer settings. + """ await self._client.sip_call_transfer(settings) async def sip_refer(self, settings): + """Send a SIP REFER request. + + Args: + settings: SIP REFER settings. + """ await self._client.sip_refer(settings) async def start_recording(self, streaming_settings=None, stream_id=None, force_new=None): + """Start recording the call. + + Args: + streaming_settings: Recording configuration settings. + stream_id: Unique identifier for the recording stream. + force_new: Whether to force a new recording session. + """ await self._client.start_recording(streaming_settings, stream_id, force_new) async def stop_recording(self, stream_id=None): + """Stop recording the call. + + Args: + stream_id: Unique identifier for the recording stream to stop. + """ await self._client.stop_recording(stream_id) async def start_transcription(self, settings=None): + """Start transcription for the call. + + Args: + settings: Transcription configuration settings. + """ await self._client.start_transcription(settings) async def stop_transcription(self): + """Stop transcription for the call.""" await self._client.stop_transcription() async def send_prebuilt_chat_message(self, message: str, user_name: Optional[str] = None): - """Sends a chat message to Daily's Prebuilt main room. + """Send a chat message to Daily's Prebuilt main room. Args: - message: The chat message to send - user_name: Optional user name that will appear as sender of the message + message: The chat message to send. + user_name: Optional user name that will appear as sender of the message. """ await self._client.send_prebuilt_chat_message(message, user_name) async def capture_participant_transcription(self, participant_id: str): + """Enable transcription capture for a specific participant. + + Args: + participant_id: ID of the participant to capture transcription for. + """ await self._client.capture_participant_transcription(participant_id) async def capture_participant_audio( @@ -1431,6 +1992,13 @@ class DailyTransport(BaseTransport): audio_source: str = "microphone", sample_rate: int = 16000, ): + """Capture audio from a specific participant. + + Args: + participant_id: ID of the participant to capture audio from. + audio_source: Audio source to capture from. + sample_rate: Desired sample rate for audio capture. + """ if self._input: await self._input.capture_participant_audio(participant_id, audio_source, sample_rate) @@ -1441,32 +2009,60 @@ class DailyTransport(BaseTransport): video_source: str = "camera", color_format: str = "RGB", ): + """Capture video from a specific participant. + + Args: + participant_id: ID of the participant to capture video from. + framerate: Desired framerate for video capture. + video_source: Video source to capture from. + color_format: Color format for video frames. + """ if self._input: await self._input.capture_participant_video( participant_id, framerate, video_source, color_format ) async def update_publishing(self, publishing_settings: Mapping[str, Any]): + """Update media publishing settings. + + Args: + publishing_settings: Publishing configuration settings. + """ await self._client.update_publishing(publishing_settings=publishing_settings) async def update_subscriptions(self, participant_settings=None, profile_settings=None): + """Update media subscription settings. + + Args: + participant_settings: Per-participant subscription settings. + profile_settings: Global subscription profile settings. + """ await self._client.update_subscriptions( participant_settings=participant_settings, profile_settings=profile_settings ) async def update_remote_participants(self, remote_participants: Mapping[str, Any]): + """Update settings for remote participants. + + Args: + remote_participants: Remote participant configuration settings. + """ await self._client.update_remote_participants(remote_participants=remote_participants) async def _on_active_speaker_changed(self, participant: Any): + """Handle active speaker change events.""" await self._call_event_handler("on_active_speaker_changed", participant) async def _on_joined(self, data): + """Handle room joined events.""" await self._call_event_handler("on_joined", data) async def _on_left(self): + """Handle room left events.""" await self._call_event_handler("on_left") async def _on_error(self, error): + """Handle error events and push error frames.""" await self._call_event_handler("on_error", error) # Push error frame to notify the pipeline error_frame = ErrorFrame(error) @@ -1480,20 +2076,25 @@ class DailyTransport(BaseTransport): raise Exception("No valid input or output channel to push error") async def _on_app_message(self, message: Any, sender: str): + """Handle application message events.""" if self._input: await self._input.push_app_message(message, sender) await self._call_event_handler("on_app_message", message, sender) async def _on_call_state_updated(self, state: str): + """Handle call state update events.""" await self._call_event_handler("on_call_state_updated", state) async def _on_client_connected(self, participant: Any): + """Handle client connected events.""" await self._call_event_handler("on_client_connected", participant) async def _on_client_disconnected(self, participant: Any): + """Handle client disconnected events.""" await self._call_event_handler("on_client_disconnected", participant) async def _handle_dialin_ready(self, sip_endpoint: str): + """Handle dial-in ready events by updating SIP configuration.""" if not self._params.dialin_settings: return @@ -1528,38 +2129,49 @@ class DailyTransport(BaseTransport): logger.exception(f"Error handling dialin-ready event ({url}): {e}") async def _on_dialin_connected(self, data): + """Handle dial-in connected events.""" await self._call_event_handler("on_dialin_connected", data) async def _on_dialin_ready(self, sip_endpoint): + """Handle dial-in ready events.""" if self._params.dialin_settings: await self._handle_dialin_ready(sip_endpoint) await self._call_event_handler("on_dialin_ready", sip_endpoint) async def _on_dialin_stopped(self, data): + """Handle dial-in stopped events.""" await self._call_event_handler("on_dialin_stopped", data) async def _on_dialin_error(self, data): + """Handle dial-in error events.""" await self._call_event_handler("on_dialin_error", data) async def _on_dialin_warning(self, data): + """Handle dial-in warning events.""" await self._call_event_handler("on_dialin_warning", data) async def _on_dialout_answered(self, data): + """Handle dial-out answered events.""" await self._call_event_handler("on_dialout_answered", data) async def _on_dialout_connected(self, data): + """Handle dial-out connected events.""" await self._call_event_handler("on_dialout_connected", data) async def _on_dialout_stopped(self, data): + """Handle dial-out stopped events.""" await self._call_event_handler("on_dialout_stopped", data) async def _on_dialout_error(self, data): + """Handle dial-out error events.""" await self._call_event_handler("on_dialout_error", data) async def _on_dialout_warning(self, data): + """Handle dial-out warning events.""" await self._call_event_handler("on_dialout_warning", data) async def _on_participant_joined(self, participant): + """Handle participant joined events.""" id = participant["id"] logger.info(f"Participant joined {id}") @@ -1577,6 +2189,7 @@ class DailyTransport(BaseTransport): await self._call_event_handler("on_client_connected", participant) async def _on_participant_left(self, participant, reason): + """Handle participant left events.""" id = participant["id"] logger.info(f"Participant left {id}") await self._call_event_handler("on_participant_left", participant, reason) @@ -1584,9 +2197,11 @@ class DailyTransport(BaseTransport): await self._call_event_handler("on_client_disconnected", participant) async def _on_participant_updated(self, participant): + """Handle participant updated events.""" await self._call_event_handler("on_participant_updated", participant) async def _on_transcription_message(self, message): + """Handle transcription message events.""" await self._call_event_handler("on_transcription_message", message) participant_id = "" @@ -1619,10 +2234,13 @@ class DailyTransport(BaseTransport): await self._input.push_transcription_frame(frame) async def _on_recording_started(self, status): + """Handle recording started events.""" await self._call_event_handler("on_recording_started", status) async def _on_recording_stopped(self, stream_id): + """Handle recording stopped events.""" await self._call_event_handler("on_recording_stopped", stream_id) async def _on_recording_error(self, stream_id, message): + """Handle recording error events.""" await self._call_event_handler("on_recording_error", stream_id, message) diff --git a/src/pipecat/transports/services/helpers/daily_rest.py b/src/pipecat/transports/services/helpers/daily_rest.py index 796022920..a283b4dfc 100644 --- a/src/pipecat/transports/services/helpers/daily_rest.py +++ b/src/pipecat/transports/services/helpers/daily_rest.py @@ -20,11 +20,11 @@ from pydantic import BaseModel, Field, ValidationError class DailyRoomSipParams(BaseModel): """SIP configuration parameters for Daily rooms. - Attributes: - display_name: Name shown for the SIP endpoint - video: Whether video is enabled for SIP - sip_mode: SIP connection mode, typically 'dial-in' - num_endpoints: Number of allowed SIP endpoints + Parameters: + display_name: Name shown for the SIP endpoint. + video: Whether video is enabled for SIP. + sip_mode: SIP connection mode, typically 'dial-in'. + num_endpoints: Number of allowed SIP endpoints. """ display_name: str = "sw-sip-dialin" @@ -38,6 +38,12 @@ class RecordingsBucketConfig(BaseModel): Refer to the Daily API documentation for more information: https://docs.daily.co/guides/products/live-streaming-recording/storing-recordings-in-a-custom-s3-bucket + + Parameters: + bucket_name: Name of the S3 bucket for storing recordings. + bucket_region: AWS region where the S3 bucket is located. + assume_role_arn: ARN of the IAM role to assume for S3 access. + allow_api_access: Whether to allow API access to the recordings. """ bucket_name: str @@ -49,21 +55,22 @@ class RecordingsBucketConfig(BaseModel): class DailyRoomProperties(BaseModel, extra="allow"): """Properties for configuring a Daily room. - Attributes: - exp: Optional Unix epoch timestamp for room expiration (e.g., time.time() + 300 for 5 minutes) - enable_chat: Whether chat is enabled in the room - enable_prejoin_ui: Whether the pre-join UI is enabled - enable_emoji_reactions: Whether emoji reactions are enabled - eject_at_room_exp: Whether to remove participants when room expires - enable_dialout: Whether SIP dial-out is enabled - enable_recording: Recording settings ('cloud', 'local', 'raw-tracks') - geo: Geographic region for room - max_participants: Maximum number of participants allowed in the room - sip: SIP configuration parameters - sip_uri: SIP URI information returned by Daily - start_video_off: Whether video is off by default - Reference: https://docs.daily.co/reference/rest-api/rooms/create-room#properties + + Parameters: + exp: Optional Unix epoch timestamp for room expiration (e.g., time.time() + 300 for 5 minutes). + enable_chat: Whether chat is enabled in the room. + enable_prejoin_ui: Whether the pre-join UI is enabled. + enable_emoji_reactions: Whether emoji reactions are enabled. + eject_at_room_exp: Whether to remove participants when room expires. + enable_dialout: Whether SIP dial-out is enabled. + enable_recording: Recording settings ('cloud', 'local', 'raw-tracks'). + geo: Geographic region for room. + max_participants: Maximum number of participants allowed in the room. + recordings_bucket: Configuration for custom S3 bucket recordings. + sip: SIP configuration parameters. + sip_uri: SIP URI information returned by Daily. + start_video_off: Whether video is off by default. """ exp: Optional[float] = None @@ -85,7 +92,7 @@ class DailyRoomProperties(BaseModel, extra="allow"): """Get the SIP endpoint URI if available. Returns: - str: SIP endpoint URI or empty string if not available + SIP endpoint URI or empty string if not available. """ if not self.sip_uri: return "" @@ -96,10 +103,10 @@ class DailyRoomProperties(BaseModel, extra="allow"): class DailyRoomParams(BaseModel): """Parameters for creating a Daily room. - Attributes: - name: Optional custom name for the room - privacy: Room privacy setting ('private' or 'public') - properties: Room configuration properties + Parameters: + name: Optional custom name for the room. + privacy: Room privacy setting ('private' or 'public'). + properties: Room configuration properties. """ name: Optional[str] = None @@ -110,14 +117,14 @@ class DailyRoomParams(BaseModel): class DailyRoomObject(BaseModel): """Represents a Daily room returned by the API. - Attributes: - id: Unique room identifier - name: Room name - api_created: Whether room was created via API - privacy: Room privacy setting ('private' or 'public') - url: Full URL for joining the room + Parameters: + id: Unique room identifier. + name: Room name. + api_created: Whether room was created via API. + privacy: Room privacy setting ('private' or 'public'). + url: Full URL for joining the room. created_at: Timestamp of room creation in ISO 8601 format (e.g., "2019-01-26T09:01:22.000Z"). - config: Room configuration properties + config: Room configuration properties. """ id: str @@ -134,71 +141,40 @@ class DailyMeetingTokenProperties(BaseModel): Refer to the Daily API documentation for more information: https://docs.daily.co/reference/rest-api/meeting-tokens/create-meeting-token#properties + + Parameters: + room_name: The room for which this token is valid. If not set, the token is valid for all rooms in your domain. + eject_at_token_exp: If True, the user will be ejected from the room when the token expires. + eject_after_elapsed: The number of seconds after which the user will be ejected from the room. + nbf: Not before timestamp - users cannot join with this token before this time. + exp: Expiration time (unix timestamp in seconds). Strongly recommended for security. + is_owner: If True, the token will grant owner privileges in the room. + user_name: The name of the user. This will be added to the token payload. + user_id: A unique identifier for the user. This will be added to the token payload. + enable_screenshare: If True, the user will be able to share their screen. + start_video_off: If True, the user's video will be turned off when they join the room. + start_audio_off: If True, the user's audio will be turned off when they join the room. + enable_recording: Recording settings for the token. Must be one of 'cloud', 'local' or 'raw-tracks'. + enable_prejoin_ui: If True, the user will see the prejoin UI before joining the room. + start_cloud_recording: Start cloud recording when the user joins the room. + permissions: Specifies the initial default permissions for a non-meeting-owner participant. """ - room_name: Optional[str] = Field( - default=None, - description="The room for which this token is valid. If not set, the token is valid for all rooms in your domain. You should always set room_name if using this token to control meeting access.", - ) - - eject_at_token_exp: Optional[bool] = Field( - default=None, - description="If `true`, the user will be ejected from the room when the token expires. Defaults to `false`.", - ) - eject_after_elapsed: Optional[int] = Field( - default=None, - description="The number of seconds after which the user will be ejected from the room. If not provided, the user will not be ejected based on elapsed time.", - ) - - nbf: Optional[int] = Field( - default=None, - description="Not before. This is a unix timestamp (seconds since the epoch.) Users cannot join a meeting in with this token before this time.", - ) - - exp: Optional[int] = Field( - default=None, - description="Expiration time (unix timestamp in seconds). We strongly recommend setting this value for security. If not set, the token will not expire. Refer docs for more info.", - ) - is_owner: Optional[bool] = Field( - default=None, - description="If `true`, the token will grant owner privileges in the room. Defaults to `false`.", - ) - user_name: Optional[str] = Field( - default=None, - description="The name of the user. This will be added to the token payload.", - ) - user_id: Optional[str] = Field( - default=None, - description="A unique identifier for the user. This will be added to the token payload.", - ) - enable_screenshare: Optional[bool] = Field( - default=None, - description="If `true`, the user will be able to share their screen. Defaults to `true`.", - ) - start_video_off: Optional[bool] = Field( - default=None, - description="If `true`, the user's video will be turned off when they join the room. Defaults to `false`.", - ) - start_audio_off: Optional[bool] = Field( - default=None, - description="If `true`, the user's audio will be turned off when they join the room. Defaults to `false`.", - ) - enable_recording: Optional[Literal["cloud", "local", "raw-tracks"]] = Field( - default=None, - description="Recording settings for the token. Must be one of `cloud`, `local` or `raw-tracks`.", - ) - enable_prejoin_ui: Optional[bool] = Field( - default=None, - description="If `true`, the user will see the prejoin UI before joining the room.", - ) - start_cloud_recording: Optional[bool] = Field( - default=None, - description="Start cloud recording when the user joins the room. This can be used to always record and archive meetings, for example in a customer support context.", - ) - permissions: Optional[dict] = Field( - default=None, - description="Specifies the initial default permissions for a non-meeting-owner participant joining a call.", - ) + room_name: Optional[str] = None + eject_at_token_exp: Optional[bool] = None + eject_after_elapsed: Optional[int] = None + nbf: Optional[int] = None + exp: Optional[int] = None + is_owner: Optional[bool] = None + user_name: Optional[str] = None + user_id: Optional[str] = None + enable_screenshare: Optional[bool] = None + start_video_off: Optional[bool] = None + start_audio_off: Optional[bool] = None + enable_recording: Optional[Literal["cloud", "local", "raw-tracks"]] = None + enable_prejoin_ui: Optional[bool] = None + start_cloud_recording: Optional[bool] = None + permissions: Optional[dict] = None class DailyMeetingTokenParams(BaseModel): @@ -206,6 +182,9 @@ class DailyMeetingTokenParams(BaseModel): Refer to the Daily API documentation for more information: https://docs.daily.co/reference/rest-api/meeting-tokens/create-meeting-token#body-params + + Parameters: + properties: Meeting token configuration properties. """ properties: DailyMeetingTokenProperties = Field(default_factory=DailyMeetingTokenProperties) @@ -215,11 +194,6 @@ class DailyRESTHelper: """Helper class for interacting with Daily's REST API. Provides methods for creating, managing, and accessing Daily rooms. - - Args: - daily_api_key: Your Daily API key - daily_api_url: Daily API base URL (e.g. "https://api.daily.co/v1") - aiohttp_session: Async HTTP session for making requests """ def __init__( @@ -229,7 +203,13 @@ class DailyRESTHelper: daily_api_url: str = "https://api.daily.co/v1", aiohttp_session: aiohttp.ClientSession, ): - """Initialize the Daily REST helper.""" + """Initialize the Daily REST helper. + + Args: + daily_api_key: Your Daily API key. + daily_api_url: Daily API base URL (e.g. "https://api.daily.co/v1"). + aiohttp_session: Async HTTP session for making requests. + """ self.daily_api_key = daily_api_key self.daily_api_url = daily_api_url self.aiohttp_session = aiohttp_session @@ -238,10 +218,10 @@ class DailyRESTHelper: """Extract room name from a Daily room URL. Args: - room_url: Full Daily room URL + room_url: Full Daily room URL. Returns: - str: Room name portion of the URL + Room name portion of the URL. """ return urlparse(room_url).path[1:] @@ -249,10 +229,10 @@ class DailyRESTHelper: """Get room details from a Daily room URL. Args: - room_url: Full Daily room URL + room_url: Full Daily room URL. Returns: - DailyRoomObject: DailyRoomObject instance for the room + DailyRoomObject instance for the room. """ room_name = self.get_name_from_url(room_url) return await self._get_room_from_name(room_name) @@ -261,13 +241,13 @@ class DailyRESTHelper: """Create a new Daily room. Args: - params: Room configuration parameters + params: Room configuration parameters. Returns: - DailyRoomObject: DailyRoomObject instance for the created room + DailyRoomObject instance for the created room. Raises: - Exception: If room creation fails or response is invalid + Exception: If room creation fails or response is invalid. """ headers = {"Authorization": f"Bearer {self.daily_api_key}"} json = params.model_dump(exclude_none=True) @@ -298,19 +278,19 @@ class DailyRESTHelper: """Generate a meeting token for user to join a Daily room. Args: - room_url: Daily room URL - expiry_time: Token validity duration in seconds (default: 1 hour) - eject_at_token_exp: Whether to eject user when token expires - owner: Whether token has owner privileges + room_url: Daily room URL. + expiry_time: Token validity duration in seconds (default: 1 hour). + eject_at_token_exp: Whether to eject user when token expires. + owner: Whether token has owner privileges. params: Optional additional token properties. Note that room_name, exp, and is_owner will be set based on the other function parameters regardless of values in params. Returns: - str: Meeting token + Meeting token. Raises: - Exception: If token generation fails or room URL is missing + Exception: If token generation fails or room URL is missing. """ if not room_url: raise Exception( @@ -355,10 +335,10 @@ class DailyRESTHelper: """Delete a room using its URL. Args: - room_url: Daily room URL + room_url: Daily room URL. Returns: - bool: True if deletion was successful + True if deletion was successful. """ room_name = self.get_name_from_url(room_url) return await self.delete_room_by_name(room_name) @@ -367,13 +347,13 @@ class DailyRESTHelper: """Delete a room using its name. Args: - room_name: Name of the room to delete + room_name: Name of the room to delete. Returns: - bool: True if deletion was successful + True if deletion was successful. Raises: - Exception: If deletion fails (excluding 404 Not Found) + Exception: If deletion fails (excluding 404 Not Found). """ headers = {"Authorization": f"Bearer {self.daily_api_key}"} async with self.aiohttp_session.delete( @@ -386,17 +366,7 @@ class DailyRESTHelper: return True async def _get_room_from_name(self, room_name: str) -> DailyRoomObject: - """Internal method to get room details by name. - - Args: - room_name: Name of the room - - Returns: - DailyRoomObject: DailyRoomObject instance for the room - - Raises: - Exception: If room is not found or response is invalid - """ + """Internal method to get room details by name.""" headers = {"Authorization": f"Bearer {self.daily_api_key}"} async with self.aiohttp_session.get( f"{self.daily_api_url}/rooms/{room_name}", headers=headers diff --git a/src/pipecat/transports/services/livekit.py b/src/pipecat/transports/services/livekit.py index 53dd091ef..d7363b9e7 100644 --- a/src/pipecat/transports/services/livekit.py +++ b/src/pipecat/transports/services/livekit.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""LiveKit transport implementation for Pipecat. + +This module provides comprehensive LiveKit real-time communication integration +including audio streaming, data messaging, participant management, and room +event handling for conversational AI applications. +""" + import asyncio from dataclasses import dataclass from typing import Any, Awaitable, Callable, List, Optional @@ -41,19 +48,49 @@ except ModuleNotFoundError as e: @dataclass class LiveKitTransportMessageFrame(TransportMessageFrame): + """Frame for transport messages in LiveKit rooms. + + Parameters: + participant_id: Optional ID of the participant this message is for/from. + """ + participant_id: Optional[str] = None @dataclass class LiveKitTransportMessageUrgentFrame(TransportMessageUrgentFrame): + """Frame for urgent transport messages in LiveKit rooms. + + Parameters: + participant_id: Optional ID of the participant this message is for/from. + """ + participant_id: Optional[str] = None class LiveKitParams(TransportParams): + """Configuration parameters for LiveKit transport. + + Inherits all parameters from TransportParams without additional configuration. + """ + pass class LiveKitCallbacks(BaseModel): + """Callback handlers for LiveKit events. + + Parameters: + on_connected: Called when connected to the LiveKit room. + on_disconnected: Called when disconnected from the LiveKit room. + on_participant_connected: Called when a participant joins the room. + on_participant_disconnected: Called when a participant leaves the room. + on_audio_track_subscribed: Called when an audio track is subscribed. + on_audio_track_unsubscribed: Called when an audio track is unsubscribed. + on_data_received: Called when data is received from a participant. + on_first_participant_joined: Called when the first participant joins. + """ + on_connected: Callable[[], Awaitable[None]] on_disconnected: Callable[[], Awaitable[None]] on_participant_connected: Callable[[str], Awaitable[None]] @@ -65,6 +102,12 @@ class LiveKitCallbacks(BaseModel): class LiveKitTransportClient: + """Core client for interacting with LiveKit rooms. + + Manages the connection to LiveKit rooms and handles all low-level API interactions + including room management, audio streaming, data messaging, and event handling. + """ + def __init__( self, url: str, @@ -74,6 +117,16 @@ class LiveKitTransportClient: callbacks: LiveKitCallbacks, transport_name: str, ): + """Initialize the LiveKit transport client. + + Args: + url: LiveKit server URL to connect to. + token: Authentication token for the room. + room_name: Name of the LiveKit room to join. + params: Configuration parameters for the transport. + callbacks: Event callback handlers. + transport_name: Name identifier for the transport. + """ self._url = url self._token = token self._room_name = room_name @@ -93,15 +146,33 @@ class LiveKitTransportClient: @property def participant_id(self) -> str: + """Get the participant ID for this client. + + Returns: + The participant ID assigned by LiveKit. + """ return self._participant_id @property def room(self) -> rtc.Room: + """Get the LiveKit room instance. + + Returns: + The LiveKit room object. + + Raises: + Exception: If room object is not available. + """ if not self._room: raise Exception(f"{self}: missing room object (pipeline not started?)") return self._room async def setup(self, setup: FrameProcessorSetup): + """Setup the client with task manager and room initialization. + + Args: + setup: The frame processor setup configuration. + """ if self._task_manager: return @@ -118,13 +189,20 @@ class LiveKitTransportClient: self.room.on("disconnected")(self._on_disconnected_wrapper) async def cleanup(self): + """Cleanup client resources.""" await self.disconnect() async def start(self, frame: StartFrame): + """Start the client and initialize audio components. + + Args: + frame: The start frame containing initialization parameters. + """ self._out_sample_rate = self._params.audio_out_sample_rate or frame.audio_out_sample_rate @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) async def connect(self): + """Connect to the LiveKit room with retry logic.""" if self._connected: # Increment disconnect counter if already connected. self._disconnect_counter += 1 @@ -168,6 +246,7 @@ class LiveKitTransportClient: raise async def disconnect(self): + """Disconnect from the LiveKit room.""" # Decrement leave counter when leaving. self._disconnect_counter -= 1 @@ -181,6 +260,12 @@ class LiveKitTransportClient: await self._callbacks.on_disconnected() async def send_data(self, data: bytes, participant_id: Optional[str] = None): + """Send data to participants in the room. + + Args: + data: The data bytes to send. + participant_id: Optional specific participant to send to. + """ if not self._connected: return @@ -195,6 +280,11 @@ class LiveKitTransportClient: logger.error(f"Error sending data: {e}") async def publish_audio(self, audio_frame: rtc.AudioFrame): + """Publish an audio frame to the room. + + Args: + audio_frame: The LiveKit audio frame to publish. + """ if not self._connected or not self._audio_source: return @@ -204,9 +294,22 @@ class LiveKitTransportClient: logger.error(f"Error publishing audio: {e}") def get_participants(self) -> List[str]: + """Get list of participant IDs in the room. + + Returns: + List of participant IDs. + """ return [p.sid for p in self.room.remote_participants.values()] async def get_participant_metadata(self, participant_id: str) -> dict: + """Get metadata for a specific participant. + + Args: + participant_id: ID of the participant to get metadata for. + + Returns: + Dictionary containing participant metadata. + """ participant = self.room.remote_participants.get(participant_id) if participant: return { @@ -218,9 +321,19 @@ class LiveKitTransportClient: return {} async def set_participant_metadata(self, metadata: str): + """Set metadata for the local participant. + + Args: + metadata: Metadata string to set. + """ await self.room.local_participant.set_metadata(metadata) async def mute_participant(self, participant_id: str): + """Mute a specific participant's audio tracks. + + Args: + participant_id: ID of the participant to mute. + """ participant = self.room.remote_participants.get(participant_id) if participant: for track in participant.tracks.values(): @@ -228,6 +341,11 @@ class LiveKitTransportClient: await track.set_enabled(False) async def unmute_participant(self, participant_id: str): + """Unmute a specific participant's audio tracks. + + Args: + participant_id: ID of the participant to unmute. + """ participant = self.room.remote_participants.get(participant_id) if participant: for track in participant.tracks.values(): @@ -236,12 +354,14 @@ class LiveKitTransportClient: # Wrapper methods for event handlers def _on_participant_connected_wrapper(self, participant: rtc.RemoteParticipant): + """Wrapper for participant connected events.""" self._task_manager.create_task( self._async_on_participant_connected(participant), f"{self}::_async_on_participant_connected", ) def _on_participant_disconnected_wrapper(self, participant: rtc.RemoteParticipant): + """Wrapper for participant disconnected events.""" self._task_manager.create_task( self._async_on_participant_disconnected(participant), f"{self}::_async_on_participant_disconnected", @@ -253,6 +373,7 @@ class LiveKitTransportClient: publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant, ): + """Wrapper for track subscribed events.""" self._task_manager.create_task( self._async_on_track_subscribed(track, publication, participant), f"{self}::_async_on_track_subscribed", @@ -264,27 +385,32 @@ class LiveKitTransportClient: publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant, ): + """Wrapper for track unsubscribed events.""" self._task_manager.create_task( self._async_on_track_unsubscribed(track, publication, participant), f"{self}::_async_on_track_unsubscribed", ) def _on_data_received_wrapper(self, data: rtc.DataPacket): + """Wrapper for data received events.""" self._task_manager.create_task( self._async_on_data_received(data), f"{self}::_async_on_data_received", ) def _on_connected_wrapper(self): + """Wrapper for connected events.""" self._task_manager.create_task(self._async_on_connected(), f"{self}::_async_on_connected") def _on_disconnected_wrapper(self): + """Wrapper for disconnected events.""" self._task_manager.create_task( self._async_on_disconnected(), f"{self}::_async_on_disconnected" ) # Async methods for event handling async def _async_on_participant_connected(self, participant: rtc.RemoteParticipant): + """Handle participant connected events.""" logger.info(f"Participant connected: {participant.identity}") await self._callbacks.on_participant_connected(participant.sid) if not self._other_participant_has_joined: @@ -292,6 +418,7 @@ class LiveKitTransportClient: await self._callbacks.on_first_participant_joined(participant.sid) async def _async_on_participant_disconnected(self, participant: rtc.RemoteParticipant): + """Handle participant disconnected events.""" logger.info(f"Participant disconnected: {participant.identity}") await self._callbacks.on_participant_disconnected(participant.sid) if len(self.get_participants()) == 0: @@ -303,6 +430,7 @@ class LiveKitTransportClient: publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant, ): + """Handle track subscribed events.""" if track.kind == rtc.TrackKind.KIND_AUDIO: logger.info(f"Audio track subscribed: {track.sid} from participant {participant.sid}") self._audio_tracks[participant.sid] = track @@ -318,22 +446,27 @@ class LiveKitTransportClient: publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant, ): + """Handle track unsubscribed events.""" logger.info(f"Track unsubscribed: {publication.sid} from {participant.identity}") if track.kind == rtc.TrackKind.KIND_AUDIO: await self._callbacks.on_audio_track_unsubscribed(participant.sid) async def _async_on_data_received(self, data: rtc.DataPacket): + """Handle data received events.""" await self._callbacks.on_data_received(data.data, data.participant.sid) async def _async_on_connected(self): + """Handle connected events.""" await self._callbacks.on_connected() async def _async_on_disconnected(self, reason=None): + """Handle disconnected events.""" self._connected = False logger.info(f"Disconnected from {self._room_name}. Reason: {reason}") await self._callbacks.on_disconnected() async def _process_audio_stream(self, audio_stream: rtc.AudioStream, participant_id: str): + """Process incoming audio stream from a participant.""" logger.info(f"Started processing audio stream for participant {participant_id}") async for event in audio_stream: if isinstance(event, rtc.AudioFrameEvent): @@ -342,15 +475,23 @@ class LiveKitTransportClient: logger.warning(f"Received unexpected event type: {type(event)}") async def get_next_audio_frame(self): + """Get the next audio frame from the queue.""" while True: frame, participant_id = await self._audio_queue.get() yield frame, participant_id def __str__(self): + """String representation of the LiveKit transport client.""" return f"{self._transport_name}::LiveKitTransportClient" class LiveKitInputTransport(BaseInputTransport): + """Handles incoming media streams and events from LiveKit rooms. + + Processes incoming audio streams from room participants and forwards them + as Pipecat frames, including audio resampling and VAD integration. + """ + def __init__( self, transport: BaseTransport, @@ -358,6 +499,14 @@ class LiveKitInputTransport(BaseInputTransport): params: LiveKitParams, **kwargs, ): + """Initialize the LiveKit input transport. + + Args: + transport: The parent transport instance. + client: LiveKitTransportClient instance. + params: Configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport self._client = client @@ -371,9 +520,19 @@ class LiveKitInputTransport(BaseInputTransport): @property def vad_analyzer(self) -> Optional[VADAnalyzer]: + """Get the Voice Activity Detection analyzer. + + Returns: + The VAD analyzer instance if configured. + """ return self._vad_analyzer async def start(self, frame: StartFrame): + """Start the input transport and connect to LiveKit room. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -389,6 +548,11 @@ class LiveKitInputTransport(BaseInputTransport): logger.info("LiveKitInputTransport started") async def stop(self, frame: EndFrame): + """Stop the input transport and disconnect from LiveKit room. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._client.disconnect() if self._audio_in_task: @@ -396,24 +560,42 @@ class LiveKitInputTransport(BaseInputTransport): logger.info("LiveKitInputTransport stopped") async def cancel(self, frame: CancelFrame): + """Cancel the input transport and disconnect from LiveKit room. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._client.disconnect() if self._audio_in_task and self._params.audio_in_enabled: await self.cancel_task(self._audio_in_task) async def setup(self, setup: FrameProcessorSetup): + """Setup the input transport with shared client setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup input transport and shared resources.""" await super().cleanup() await self._transport.cleanup() async def push_app_message(self, message: Any, sender: str): + """Push an application message as an urgent transport frame. + + Args: + message: The message data to send. + sender: ID of the message sender. + """ frame = LiveKitTransportMessageUrgentFrame(message=message, participant_id=sender) await self.push_frame(frame) async def _audio_in_task_handler(self): + """Handle incoming audio frames from participants.""" logger.info("Audio input task started") audio_iterator = self._client.get_next_audio_frame() async for audio_data in WatchdogAsyncIterator(audio_iterator, manager=self.task_manager): @@ -433,6 +615,7 @@ class LiveKitInputTransport(BaseInputTransport): async def _convert_livekit_audio_to_pipecat( self, audio_frame_event: rtc.AudioFrameEvent ) -> AudioRawFrame: + """Convert LiveKit audio frame to Pipecat audio frame.""" audio_frame = audio_frame_event.frame audio_data = await self._resampler.resample( @@ -447,6 +630,12 @@ class LiveKitInputTransport(BaseInputTransport): class LiveKitOutputTransport(BaseOutputTransport): + """Handles outgoing media streams and events to LiveKit rooms. + + Manages sending audio frames and data messages to LiveKit room participants, + including audio format conversion for LiveKit compatibility. + """ + def __init__( self, transport: BaseTransport, @@ -454,6 +643,14 @@ class LiveKitOutputTransport(BaseOutputTransport): params: LiveKitParams, **kwargs, ): + """Initialize the LiveKit output transport. + + Args: + transport: The parent transport instance. + client: LiveKitTransportClient instance. + params: Configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._transport = transport self._client = client @@ -462,6 +659,11 @@ class LiveKitOutputTransport(BaseOutputTransport): self._initialized = False async def start(self, frame: StartFrame): + """Start the output transport and connect to LiveKit room. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -475,33 +677,60 @@ class LiveKitOutputTransport(BaseOutputTransport): logger.info("LiveKitOutputTransport started") async def stop(self, frame: EndFrame): + """Stop the output transport and disconnect from LiveKit room. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._client.disconnect() logger.info("LiveKitOutputTransport stopped") async def cancel(self, frame: CancelFrame): + """Cancel the output transport and disconnect from LiveKit room. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._client.disconnect() async def setup(self, setup: FrameProcessorSetup): + """Setup the output transport with shared client setup. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup output transport and shared resources.""" await super().cleanup() await self._transport.cleanup() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a transport message to participants. + + Args: + frame: The transport message frame to send. + """ if isinstance(frame, (LiveKitTransportMessageFrame, LiveKitTransportMessageUrgentFrame)): await self._client.send_data(frame.message.encode(), frame.participant_id) else: await self._client.send_data(frame.message.encode()) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the LiveKit room. + + Args: + frame: The audio frame to write. + """ livekit_audio = self._convert_pipecat_audio_to_livekit(frame.audio) await self._client.publish_audio(livekit_audio) def _convert_pipecat_audio_to_livekit(self, pipecat_audio: bytes) -> rtc.AudioFrame: + """Convert Pipecat audio data to LiveKit audio frame.""" bytes_per_sample = 2 # Assuming 16-bit audio total_samples = len(pipecat_audio) // bytes_per_sample samples_per_channel = total_samples // self._params.audio_out_channels @@ -515,6 +744,13 @@ class LiveKitOutputTransport(BaseOutputTransport): class LiveKitTransport(BaseTransport): + """Transport implementation for LiveKit real-time communication. + + Provides comprehensive LiveKit integration including audio streaming, data + messaging, participant management, and room event handling for conversational + AI applications. + """ + def __init__( self, url: str, @@ -524,6 +760,16 @@ class LiveKitTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the LiveKit transport. + + Args: + url: LiveKit server URL to connect to. + token: Authentication token for the room. + room_name: Name of the LiveKit room to join. + params: Configuration parameters for the transport. + input_name: Optional name for the input transport. + output_name: Optional name for the output transport. + """ super().__init__(input_name=input_name, output_name=output_name) callbacks = LiveKitCallbacks( @@ -556,6 +802,11 @@ class LiveKitTransport(BaseTransport): self._register_event_handler("on_call_state_updated") def input(self) -> LiveKitInputTransport: + """Get the input transport for receiving media and events. + + Returns: + The LiveKit input transport instance. + """ if not self._input: self._input = LiveKitInputTransport( self, self._client, self._params, name=self._input_name @@ -563,6 +814,11 @@ class LiveKitTransport(BaseTransport): return self._input def output(self) -> LiveKitOutputTransport: + """Get the output transport for sending media and events. + + Returns: + The LiveKit output transport instance. + """ if not self._output: self._output = LiveKitOutputTransport( self, self._client, self._params, name=self._output_name @@ -571,41 +827,84 @@ class LiveKitTransport(BaseTransport): @property def participant_id(self) -> str: + """Get the participant ID for this transport. + + Returns: + The participant ID assigned by LiveKit. + """ return self._client.participant_id async def send_audio(self, frame: OutputAudioRawFrame): + """Send an audio frame to the LiveKit room. + + Args: + frame: The audio frame to send. + """ if self._output: await self._output.queue_frame(frame, FrameDirection.DOWNSTREAM) def get_participants(self) -> List[str]: + """Get list of participant IDs in the room. + + Returns: + List of participant IDs. + """ return self._client.get_participants() async def get_participant_metadata(self, participant_id: str) -> dict: + """Get metadata for a specific participant. + + Args: + participant_id: ID of the participant to get metadata for. + + Returns: + Dictionary containing participant metadata. + """ return await self._client.get_participant_metadata(participant_id) async def set_metadata(self, metadata: str): + """Set metadata for the local participant. + + Args: + metadata: Metadata string to set. + """ await self._client.set_participant_metadata(metadata) async def mute_participant(self, participant_id: str): + """Mute a specific participant's audio tracks. + + Args: + participant_id: ID of the participant to mute. + """ await self._client.mute_participant(participant_id) async def unmute_participant(self, participant_id: str): + """Unmute a specific participant's audio tracks. + + Args: + participant_id: ID of the participant to unmute. + """ await self._client.unmute_participant(participant_id) async def _on_connected(self): + """Handle room connected events.""" await self._call_event_handler("on_connected") async def _on_disconnected(self): + """Handle room disconnected events.""" await self._call_event_handler("on_disconnected") async def _on_participant_connected(self, participant_id: str): + """Handle participant connected events.""" await self._call_event_handler("on_participant_connected", participant_id) async def _on_participant_disconnected(self, participant_id: str): + """Handle participant disconnected events.""" await self._call_event_handler("on_participant_disconnected", participant_id) await self._call_event_handler("on_participant_left", participant_id, "disconnected") async def _on_audio_track_subscribed(self, participant_id: str): + """Handle audio track subscribed events.""" await self._call_event_handler("on_audio_track_subscribed", participant_id) participant = self._client.room.remote_participants.get(participant_id) if participant: @@ -615,19 +914,33 @@ class LiveKitTransport(BaseTransport): ) async def _on_audio_track_unsubscribed(self, participant_id: str): + """Handle audio track unsubscribed events.""" await self._call_event_handler("on_audio_track_unsubscribed", participant_id) async def _on_data_received(self, data: bytes, participant_id: str): + """Handle data received events.""" if self._input: await self._input.push_app_message(data.decode(), participant_id) await self._call_event_handler("on_data_received", data, participant_id) async def send_message(self, message: str, participant_id: Optional[str] = None): + """Send a message to participants in the room. + + Args: + message: The message string to send. + participant_id: Optional specific participant to send to. + """ if self._output: frame = LiveKitTransportMessageFrame(message=message, participant_id=participant_id) await self._output.send_message(frame) async def send_message_urgent(self, message: str, participant_id: Optional[str] = None): + """Send an urgent message to participants in the room. + + Args: + message: The urgent message string to send. + participant_id: Optional specific participant to send to. + """ if self._output: frame = LiveKitTransportMessageUrgentFrame( message=message, participant_id=participant_id @@ -635,19 +948,36 @@ class LiveKitTransport(BaseTransport): await self._output.send_message(frame) async def on_room_event(self, event): + """Handle room events. + + Args: + event: The room event to handle. + """ # Handle room events pass async def on_participant_event(self, event): + """Handle participant events. + + Args: + event: The participant event to handle. + """ # Handle participant events pass async def on_track_event(self, event): + """Handle track events. + + Args: + event: The track event to handle. + """ # Handle track events pass async def _on_call_state_updated(self, state: str): + """Handle call state update events.""" await self._call_event_handler("on_call_state_updated", self, state) async def _on_first_participant_joined(self, participant_id: str): + """Handle first participant joined events.""" await self._call_event_handler("on_first_participant_joined", participant_id) diff --git a/src/pipecat/transports/services/tavus.py b/src/pipecat/transports/services/tavus.py index ff70416d2..e83dc6a20 100644 --- a/src/pipecat/transports/services/tavus.py +++ b/src/pipecat/transports/services/tavus.py @@ -1,3 +1,16 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Tavus transport implementation for Pipecat. + +This module provides integration with the Tavus platform for creating conversational +AI applications with avatars. It manages conversation sessions and provides real-time +audio/video streaming capabilities through the Tavus API. +""" + import os from functools import partial from typing import Any, Awaitable, Callable, Mapping, Optional @@ -31,8 +44,10 @@ from pipecat.transports.services.daily import ( class TavusApi: - """ - A helper class for interacting with the Tavus API (v2). + """Helper class for interacting with the Tavus API (v2). + + Provides methods for creating and managing conversations with Tavus avatars, + including conversation lifecycle management and persona information retrieval. """ BASE_URL = "https://tavusapi.com/v2" @@ -40,12 +55,11 @@ class TavusApi: MOCK_PERSONA_NAME = "TestTavusTransport" def __init__(self, api_key: str, session: aiohttp.ClientSession): - """ - Initialize the TavusApi client. + """Initialize the TavusApi client. Args: - api_key (str): Tavus API key. - session (aiohttp.ClientSession): An aiohttp session for making HTTP requests. + api_key: Tavus API key for authentication. + session: An aiohttp session for making HTTP requests. """ self._api_key = api_key self._session = session @@ -54,6 +68,15 @@ class TavusApi: self._dev_room_url = os.getenv("TAVUS_SAMPLE_ROOM_URL") async def create_conversation(self, replica_id: str, persona_id: str) -> dict: + """Create a new conversation with the specified replica and persona. + + Args: + replica_id: ID of the replica to use in the conversation. + persona_id: ID of the persona to use in the conversation. + + Returns: + Dictionary containing conversation_id and conversation_url. + """ if self._dev_room_url: return { "conversation_id": self.MOCK_CONVERSATION_ID, @@ -73,6 +96,11 @@ class TavusApi: return response async def end_conversation(self, conversation_id: str): + """End an existing conversation. + + Args: + conversation_id: ID of the conversation to end. + """ if conversation_id is None or conversation_id == self.MOCK_CONVERSATION_ID: return @@ -82,6 +110,14 @@ class TavusApi: logger.debug(f"Ended Tavus conversation {conversation_id}") async def get_persona_name(self, persona_id: str) -> str: + """Get the name of a persona by ID. + + Args: + persona_id: ID of the persona to retrieve. + + Returns: + The name of the persona. + """ if self._dev_room_url is not None: return self.MOCK_PERSONA_NAME @@ -94,11 +130,11 @@ class TavusApi: class TavusCallbacks(BaseModel): - """Callback handlers for the Tavus events. + """Callback handlers for Tavus events. - Attributes: - on_participant_joined: Called when a participant joins. - on_participant_left: Called when a participant leaves. + Parameters: + on_participant_joined: Called when a participant joins the conversation. + on_participant_left: Called when a participant leaves the conversation. """ on_participant_joined: Callable[[Mapping[str, Any]], Awaitable[None]] @@ -106,7 +142,13 @@ class TavusCallbacks(BaseModel): class TavusParams(DailyParams): - """Configuration parameters for the Tavus transport.""" + """Configuration parameters for the Tavus transport. + + Parameters: + audio_in_enabled: Whether to enable audio input from participants. + audio_out_enabled: Whether to enable audio output to participants. + microphone_out_enabled: Whether to enable microphone output track. + """ audio_in_enabled: bool = True audio_out_enabled: bool = True @@ -114,24 +156,14 @@ class TavusParams(DailyParams): class TavusTransportClient: - """ + """Transport client that integrates Pipecat with the Tavus platform. + A transport client that integrates a Pipecat Bot with the Tavus platform by managing conversation sessions using the Tavus API. This client uses `TavusApi` to interact with the Tavus backend services. When a conversation is started via `TavusApi`, Tavus provides a `roomURL` that can be used to connect the Pipecat Bot into the same virtual room where the TavusBot is operating. - - Args: - bot_name (str): The name of the Pipecat bot instance. - params (TavusParams): Optional parameters for Tavus operation. Defaults to `TavusParams()`. - callbacks (TavusCallbacks): Callback handlers for Tavus-related events. - api_key (str): API key for authenticating with Tavus API. - replica_id (str): ID of the replica to use in the Tavus conversation. - persona_id (str): ID of the Tavus persona. Defaults to "pipecat-stream", which signals Tavus to use - the TTS voice of the Pipecat bot instead of a Tavus persona voice. - session (aiohttp.ClientSession): The aiohttp session for making async HTTP requests. - sample_rate: Audio sample rate to be used by the client. """ def __init__( @@ -145,6 +177,19 @@ class TavusTransportClient: persona_id: str = "pipecat-stream", session: aiohttp.ClientSession, ) -> None: + """Initialize the Tavus transport client. + + Args: + bot_name: The name of the Pipecat bot instance. + params: Optional parameters for Tavus operation. + callbacks: Callback handlers for Tavus-related events. + api_key: API key for authenticating with Tavus API. + replica_id: ID of the replica to use in the Tavus conversation. + persona_id: ID of the Tavus persona. Defaults to "pipecat-stream", + which signals Tavus to use the TTS voice of the Pipecat bot + instead of a Tavus persona voice. + session: The aiohttp session for making async HTTP requests. + """ self._bot_name = bot_name self._api = TavusApi(api_key, session) self._replica_id = replica_id @@ -155,11 +200,17 @@ class TavusTransportClient: self._params = params async def _initialize(self) -> str: + """Initialize the conversation and return the room URL.""" response = await self._api.create_conversation(self._replica_id, self._persona_id) self._conversation_id = response["conversation_id"] return response["conversation_url"] async def setup(self, setup: FrameProcessorSetup): + """Setup the client and initialize the conversation. + + Args: + setup: The frame processor setup configuration. + """ if self._conversation_id is not None: logger.debug(f"Conversation ID already defined: {self._conversation_id}") return @@ -206,29 +257,44 @@ class TavusTransportClient: self._conversation_id = None async def cleanup(self): + """Cleanup client resources.""" try: await self._client.cleanup() except Exception as e: logger.exception(f"Exception during cleanup: {e}") async def _on_joined(self, data): + """Handle joined event.""" logger.debug("TavusTransportClient joined!") async def _on_left(self): + """Handle left event.""" logger.debug("TavusTransportClient left!") async def _on_handle_callback(self, event_name, *args, **kwargs): + """Handle generic callback events.""" logger.trace(f"[Callback] {event_name} called with args={args}, kwargs={kwargs}") async def get_persona_name(self) -> str: + """Get the persona name from the API. + + Returns: + The name of the current persona. + """ return await self._api.get_persona_name(self._persona_id) async def start(self, frame: StartFrame): + """Start the client and join the room. + + Args: + frame: The start frame containing initialization parameters. + """ logger.debug("TavusTransportClient start invoked!") await self._client.start(frame) await self._client.join() async def stop(self): + """Stop the client and end the conversation.""" await self._client.leave() await self._api.end_conversation(self._conversation_id) self._conversation_id = None @@ -241,6 +307,15 @@ class TavusTransportClient: video_source: str = "camera", color_format: str = "RGB", ): + """Capture video from a participant. + + Args: + participant_id: ID of the participant to capture video from. + callback: Callback function to handle video frames. + framerate: Desired framerate for video capture. + video_source: Video source to capture from. + color_format: Color format for video frames. + """ await self._client.capture_participant_video( participant_id, callback, framerate, video_source, color_format ) @@ -253,22 +328,47 @@ class TavusTransportClient: sample_rate: int = 16000, callback_interval_ms: int = 20, ): + """Capture audio from a participant. + + Args: + participant_id: ID of the participant to capture audio from. + callback: Callback function to handle audio data. + audio_source: Audio source to capture from. + sample_rate: Desired sample rate for audio capture. + callback_interval_ms: Interval between audio callbacks in milliseconds. + """ await self._client.capture_participant_audio( participant_id, callback, audio_source, sample_rate, callback_interval_ms ) async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a message to participants. + + Args: + frame: The message frame to send. + """ await self._client.send_message(frame) @property def out_sample_rate(self) -> int: + """Get the output sample rate. + + Returns: + The output sample rate in Hz. + """ return self._client.out_sample_rate @property def in_sample_rate(self) -> int: + """Get the input sample rate. + + Returns: + The input sample rate in Hz. + """ return self._client.in_sample_rate async def send_interrupt_message(self) -> None: + """Send an interrupt message to the conversation.""" transport_frame = TransportMessageUrgentFrame( message={ "message_type": "conversation", @@ -279,6 +379,12 @@ class TavusTransportClient: await self.send_message(transport_frame) async def update_subscriptions(self, participant_settings=None, profile_settings=None): + """Update subscription settings for participants. + + Args: + participant_settings: Per-participant subscription settings. + profile_settings: Global subscription profile settings. + """ if not self._client: return @@ -287,11 +393,21 @@ class TavusTransportClient: ) async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the transport. + + Args: + frame: The audio frame to write. + """ if not self._client: return await self._client.write_audio_frame(frame) async def register_audio_destination(self, destination: str): + """Register an audio destination for output. + + Args: + destination: The destination identifier to register. + """ if not self._client: return @@ -299,12 +415,25 @@ class TavusTransportClient: class TavusInputTransport(BaseInputTransport): + """Input transport for receiving audio and events from Tavus conversations. + + Handles incoming audio streams from participants and manages audio capture + from the Daily room connected to the Tavus conversation. + """ + def __init__( self, client: TavusTransportClient, params: TransportParams, **kwargs, ): + """Initialize the Tavus input transport. + + Args: + client: The Tavus transport client instance. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._client = client self._params = params @@ -314,14 +443,25 @@ class TavusInputTransport(BaseInputTransport): self._initialized = False async def setup(self, setup: FrameProcessorSetup): + """Setup the input transport. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup input transport resources.""" await super().cleanup() await self._client.cleanup() async def start(self, frame: StartFrame): + """Start the input transport. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -333,14 +473,29 @@ class TavusInputTransport(BaseInputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the input transport. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._client.stop() async def cancel(self, frame: CancelFrame): + """Cancel the input transport. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._client.stop() async def start_capturing_audio(self, participant): + """Start capturing audio from a participant. + + Args: + participant: The participant to capture audio from. + """ if self._params.audio_in_enabled: logger.info( f"TavusTransportClient start capturing audio for participant {participant['id']}" @@ -354,6 +509,7 @@ class TavusInputTransport(BaseInputTransport): async def _on_participant_audio_data( self, participant_id: str, audio: AudioData, audio_source: str ): + """Handle received participant audio data.""" frame = InputAudioRawFrame( audio=audio.audio_frames, sample_rate=audio.audio_frames, @@ -364,12 +520,25 @@ class TavusInputTransport(BaseInputTransport): class TavusOutputTransport(BaseOutputTransport): + """Output transport for sending audio and events to Tavus conversations. + + Handles outgoing audio streams to participants and manages the custom + audio track expected by the Tavus platform. + """ + def __init__( self, client: TavusTransportClient, params: TransportParams, **kwargs, ): + """Initialize the Tavus output transport. + + Args: + client: The Tavus transport client instance. + params: Transport configuration parameters. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(params, **kwargs) self._client = client self._params = params @@ -380,14 +549,25 @@ class TavusOutputTransport(BaseOutputTransport): self._transport_destination: Optional[str] = "stream" async def setup(self, setup: FrameProcessorSetup): + """Setup the output transport. + + Args: + setup: The frame processor setup configuration. + """ await super().setup(setup) await self._client.setup(setup) async def cleanup(self): + """Cleanup output transport resources.""" await super().cleanup() await self._client.cleanup() async def start(self, frame: StartFrame): + """Start the output transport. + + Args: + frame: The start frame containing initialization parameters. + """ await super().start(frame) if self._initialized: @@ -403,51 +583,72 @@ class TavusOutputTransport(BaseOutputTransport): await self.set_transport_ready(frame) async def stop(self, frame: EndFrame): + """Stop the output transport. + + Args: + frame: The end frame signaling transport shutdown. + """ await super().stop(frame) await self._client.stop() async def cancel(self, frame: CancelFrame): + """Cancel the output transport. + + Args: + frame: The cancel frame signaling immediate cancellation. + """ await super().cancel(frame) await self._client.stop() async def send_message(self, frame: TransportMessageFrame | TransportMessageUrgentFrame): + """Send a message to participants. + + Args: + frame: The message frame to send. + """ logger.info(f"TavusOutputTransport sending message {frame}") await self._client.send_message(frame) async def process_frame(self, frame: Frame, direction: FrameDirection): + """Process frames and handle interruptions. + + 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): await self._handle_interruptions() async def _handle_interruptions(self): + """Handle interruption events by sending interrupt message.""" await self._client.send_interrupt_message() async def write_audio_frame(self, frame: OutputAudioRawFrame): + """Write an audio frame to the Tavus transport. + + Args: + frame: The audio frame to write. + """ # This is the custom track destination expected by Tavus frame.transport_destination = self._transport_destination await self._client.write_audio_frame(frame) async def register_audio_destination(self, destination: str): + """Register an audio destination. + + Args: + destination: The destination identifier to register. + """ await self._client.register_audio_destination(destination) class TavusTransport(BaseTransport): - """ - Transport implementation for Tavus video calls. + """Transport implementation for Tavus video calls. When used, the Pipecat bot joins the same virtual room as the Tavus Avatar and the user. This is achieved by using `TavusTransportClient`, which initiates the conversation via `TavusApi` and obtains a room URL that all participants connect to. - - Args: - bot_name (str): The name of the Pipecat bot. - session (aiohttp.ClientSession): aiohttp session used for async HTTP requests. - api_key (str): Tavus API key for authentication. - replica_id (str): ID of the replica model used for voice generation. - persona_id (str): ID of the Tavus persona. Defaults to "pipecat-stream" to use the Pipecat TTS voice. - params (TavusParams): Optional Tavus-specific configuration parameters. - input_name (Optional[str]): Optional name for the input transport. - output_name (Optional[str]): Optional name for the output transport. """ def __init__( @@ -461,6 +662,19 @@ class TavusTransport(BaseTransport): input_name: Optional[str] = None, output_name: Optional[str] = None, ): + """Initialize the Tavus transport. + + Args: + bot_name: The name of the Pipecat bot. + session: aiohttp session used for async HTTP requests. + api_key: Tavus API key for authentication. + replica_id: ID of the replica model used for voice generation. + persona_id: ID of the Tavus persona. Defaults to "pipecat-stream" + to use the Pipecat TTS voice. + params: Optional Tavus-specific configuration parameters. + input_name: Optional name for the input transport. + output_name: Optional name for the output transport. + """ super().__init__(input_name=input_name, output_name=output_name) self._params = params @@ -487,11 +701,13 @@ class TavusTransport(BaseTransport): self._register_event_handler("on_client_disconnected") async def _on_participant_left(self, participant, reason): + """Handle participant left events.""" persona_name = await self._client.get_persona_name() if participant.get("info", {}).get("userName", "") != persona_name: await self._on_client_disconnected(participant) async def _on_participant_joined(self, participant): + """Handle participant joined events.""" # get persona, look up persona_name, set this as the bot name to ignore persona_name = await self._client.get_persona_name() @@ -513,23 +729,41 @@ class TavusTransport(BaseTransport): await self._input.start_capturing_audio(participant) async def update_subscriptions(self, participant_settings=None, profile_settings=None): + """Update subscription settings for participants. + + Args: + participant_settings: Per-participant subscription settings. + profile_settings: Global subscription profile settings. + """ await self._client.update_subscriptions( participant_settings=participant_settings, profile_settings=profile_settings, ) def input(self) -> FrameProcessor: + """Get the input transport for receiving media and events. + + Returns: + The Tavus input transport instance. + """ if not self._input: self._input = TavusInputTransport(client=self._client, params=self._params) return self._input def output(self) -> FrameProcessor: + """Get the output transport for sending media and events. + + Returns: + The Tavus output transport instance. + """ if not self._output: self._output = TavusOutputTransport(client=self._client, params=self._params) return self._output async def _on_client_connected(self, participant: Any): + """Handle client connected events.""" await self._call_event_handler("on_client_connected", participant) async def _on_client_disconnected(self, participant: Any): + """Handle client disconnected events.""" await self._call_event_handler("on_client_disconnected", participant) diff --git a/src/pipecat/utils/asyncio/task_manager.py b/src/pipecat/utils/asyncio/task_manager.py index 844536186..aaa340399 100644 --- a/src/pipecat/utils/asyncio/task_manager.py +++ b/src/pipecat/utils/asyncio/task_manager.py @@ -4,6 +4,14 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Asyncio task management with watchdog monitoring capabilities. + +This module provides task management functionality with optional watchdog timers +to monitor task execution and prevent hanging operations. Includes both abstract +base classes and concrete implementations for managing asyncio tasks with +comprehensive monitoring and cleanup capabilities. +""" + import asyncio import time from abc import ABC, abstractmethod @@ -17,6 +25,15 @@ WATCHDOG_TIMEOUT = 5.0 @dataclass class TaskManagerParams: + """Configuration parameters for task manager initialization. + + Parameters: + loop: The asyncio event loop to use for task management. + enable_watchdog_timers: Whether to enable watchdog timers for tasks. + enable_watchdog_logging: Whether to log watchdog timing information. + watchdog_timeout: Default timeout in seconds for watchdog timers. + """ + loop: asyncio.AbstractEventLoop enable_watchdog_timers: bool = False enable_watchdog_logging: bool = False @@ -24,12 +41,28 @@ class TaskManagerParams: class BaseTaskManager(ABC): + """Abstract base class for asyncio task management with watchdog support. + + Provides the interface for creating, monitoring, and managing asyncio tasks + with optional watchdog timer functionality to detect stalled operations. + """ + @abstractmethod def setup(self, params: TaskManagerParams): + """Initialize the task manager with configuration parameters. + + Args: + params: Configuration parameters for task management. + """ pass @abstractmethod def get_event_loop(self) -> asyncio.AbstractEventLoop: + """Get the event loop used by this task manager. + + Returns: + The asyncio event loop instance. + """ pass @abstractmethod @@ -42,21 +75,19 @@ class BaseTaskManager(ABC): enable_watchdog_timers: Optional[bool] = None, watchdog_timeout: Optional[float] = None, ) -> asyncio.Task: - """ - Creates and schedules a new asyncio Task that runs the given coroutine. + """Creates and schedules a new asyncio Task that runs the given coroutine. The task is added to a global set of created tasks. Args: - loop (asyncio.AbstractEventLoop): The event loop to use for creating the task. - coroutine (Coroutine): The coroutine to be executed within the task. - name (str): The name to assign to the task for identification. - enable_watchdog_logging(bool): whether this task should log watchdog processing times. - enable_watchdog_timers(bool): whether this task should have a watchdog timer. - watchdog_timeout(float): watchdog timer timeout for this task. + coroutine: The coroutine to be executed within the task. + name: The name to assign to the task for identification. + enable_watchdog_logging: Whether this task should log watchdog processing times. + enable_watchdog_timers: Whether this task should have a watchdog timer. + watchdog_timeout: Watchdog timer timeout for this task. Returns: - asyncio.Task: The created task object. + The created task object. """ pass @@ -69,50 +100,67 @@ class BaseTaskManager(ABC): is removed from the set of registered tasks upon completion or failure. Args: - task (asyncio.Task): The asyncio Task to wait for. - timeout (Optional[float], optional): The maximum number of seconds - to wait for the task to complete. If None, waits indefinitely. - Defaults to None. + task: The asyncio Task to wait for. + timeout: The maximum number of seconds to wait for the task to complete. + If None, waits indefinitely. """ pass @abstractmethod async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None): - """Cancels the given asyncio Task and awaits its completion with an - optional timeout. + """Cancels the given asyncio Task and awaits its completion with an optional timeout. This function removes the task from the set of registered tasks upon completion or failure. Args: - task (asyncio.Task): The task to be cancelled. - timeout (Optional[float]): The optional timeout in seconds to wait for the task to cancel. - + task: The task to be cancelled. + timeout: The optional timeout in seconds to wait for the task to cancel. """ pass @abstractmethod def current_tasks(self) -> Sequence[asyncio.Task]: - """Returns the list of currently created/registered tasks.""" + """Returns the list of currently created/registered tasks. + + Returns: + Sequence of currently managed asyncio tasks. + """ pass @abstractmethod def task_reset_watchdog(self): - """Resets the running task watchdog timer. If not reset, a warning will - be logged indicating the task is stalling. + """Task reset watchdog timer. + Resets the running task watchdog timer. If not reset, a warning will + be logged indicating the task is stalling. """ pass @property @abstractmethod def task_watchdog_enabled(self) -> bool: - """Whether the current running task has a watchdog timer enabled.""" + """Whether the current running task has a watchdog timer enabled. + + Returns: + True if the current task has watchdog monitoring active. + """ pass @dataclass class TaskData: + """Internal data structure for tracking task metadata and watchdog state. + + Parameters: + task: The asyncio Task being managed. + watchdog_timer: Event used to reset the watchdog timer. + enable_watchdog_logging: Whether to log watchdog timing information. + enable_watchdog_timers: Whether watchdog timers are enabled for this task. + watchdog_timeout: Timeout in seconds for watchdog warnings. + watchdog_task: Optional background task monitoring the watchdog timer. + """ + task: asyncio.Task watchdog_timer: asyncio.Event enable_watchdog_logging: bool @@ -122,15 +170,36 @@ class TaskData: class TaskManager(BaseTaskManager): + """Concrete implementation of BaseTaskManager with full watchdog support. + + Manages asyncio tasks with optional watchdog monitoring to detect stalled + operations. Provides comprehensive task lifecycle management including + creation, monitoring, cancellation, and cleanup. + """ + def __init__(self) -> None: + """Initialize the task manager with empty task registry.""" self._tasks: Dict[str, TaskData] = {} self._params: Optional[TaskManagerParams] = None def setup(self, params: TaskManagerParams): + """Initialize the task manager with configuration parameters. + + Args: + params: Configuration parameters for task management. + """ if not self._params: self._params = params def get_event_loop(self) -> asyncio.AbstractEventLoop: + """Get the event loop used by this task manager. + + Returns: + The asyncio event loop instance. + + Raises: + Exception: If the task manager is not properly set up. + """ if not self._params: raise Exception("TaskManager is not setup: unable to get event loop") return self._params.loop @@ -144,21 +213,22 @@ class TaskManager(BaseTaskManager): enable_watchdog_timers: Optional[bool] = None, watchdog_timeout: Optional[float] = None, ) -> asyncio.Task: - """ - Creates and schedules a new asyncio Task that runs the given coroutine. + """Creates and schedules a new asyncio Task that runs the given coroutine. The task is added to a global set of created tasks. Args: - loop (asyncio.AbstractEventLoop): The event loop to use for creating the task. - coroutine (Coroutine): The coroutine to be executed within the task. - name (str): The name to assign to the task for identification. - enable_watchdog_logging(bool): whether this task should log watchdog processing time. - enable_watchdog_timers(bool): whether this task should have a watchdog timer. - watchdog_timeout(float): watchdog timer timeout for this task. + coroutine: The coroutine to be executed within the task. + name: The name to assign to the task for identification. + enable_watchdog_logging: Whether this task should log watchdog processing time. + enable_watchdog_timers: Whether this task should have a watchdog timer. + watchdog_timeout: Watchdog timer timeout for this task. Returns: - asyncio.Task: The created task object. + The created task object. + + Raises: + Exception: If the task manager is not properly set up. """ async def run_coroutine(): @@ -208,10 +278,9 @@ class TaskManager(BaseTaskManager): is removed from the set of registered tasks upon completion or failure. Args: - task (asyncio.Task): The asyncio Task to wait for. - timeout (Optional[float], optional): The maximum number of seconds - to wait for the task to complete. If None, waits indefinitely. - Defaults to None. + task: The asyncio Task to wait for. + timeout: The maximum number of seconds to wait for the task to complete. + If None, waits indefinitely. """ name = task.get_name() try: @@ -228,16 +297,14 @@ class TaskManager(BaseTaskManager): logger.exception(f"{name}: unexpected exception while stopping task: {e}") async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None): - """Cancels the given asyncio Task and awaits its completion with an - optional timeout. + """Cancels the given asyncio Task and awaits its completion with an optional timeout. This function removes the task from the set of registered tasks upon completion or failure. Args: - task (asyncio.Task): The task to be cancelled. - timeout (Optional[float]): The optional timeout in seconds to wait for the task to cancel. - + task: The task to be cancelled. + timeout: The optional timeout in seconds to wait for the task to cancel. """ name = task.get_name() task.cancel() @@ -260,18 +327,28 @@ class TaskManager(BaseTaskManager): raise def reset_watchdog(self, task: asyncio.Task): + """Reset the watchdog timer for a specific task. + + Args: + task: The task whose watchdog timer should be reset. + """ name = task.get_name() if name in self._tasks and self._tasks[name].enable_watchdog_timers: self._tasks[name].watchdog_timer.set() def current_tasks(self) -> Sequence[asyncio.Task]: - """Returns the list of currently created/registered tasks.""" + """Returns the list of currently created/registered tasks. + + Returns: + Sequence of currently managed asyncio tasks. + """ return [data.task for data in self._tasks.values()] def task_reset_watchdog(self): - """Resets the running task watchdog timer. If not reset on time, a warning - will be logged indicating the task is stalling. + """Task reset watchdog timer. + Resets the running task watchdog timer. If not reset on time, a warning + will be logged indicating the task is stalling. """ task = asyncio.current_task() if task: @@ -279,6 +356,11 @@ class TaskManager(BaseTaskManager): @property def task_watchdog_enabled(self) -> bool: + """Whether the current running task has a watchdog timer enabled. + + Returns: + True if the current task has watchdog monitoring active. + """ task = asyncio.current_task() if not task: return False @@ -286,6 +368,11 @@ class TaskManager(BaseTaskManager): return name in self._tasks and self._tasks[name].enable_watchdog_timers def _add_task(self, task_data: TaskData): + """Add a task to the internal registry and start watchdog if enabled. + + Args: + task_data: The task data containing task and watchdog configuration. + """ name = task_data.task.get_name() self._tasks[name] = task_data if self._params and task_data.enable_watchdog_timers: @@ -295,6 +382,11 @@ class TaskManager(BaseTaskManager): task_data.watchdog_task = watchdog_task async def _watchdog_task_handler(self, task_data: TaskData): + """Background task that monitors watchdog timer for a specific task. + + Args: + task_data: The task data containing watchdog configuration. + """ name = task_data.task.get_name() timer = task_data.watchdog_timer enable_watchdog_logging = task_data.enable_watchdog_logging @@ -315,6 +407,11 @@ class TaskManager(BaseTaskManager): timer.clear() def _task_done_handler(self, task: asyncio.Task): + """Handle task completion by cleaning up watchdog and removing from registry. + + Args: + task: The completed asyncio task. + """ name = task.get_name() try: task_data = self._tasks[name] diff --git a/src/pipecat/utils/asyncio/watchdog_async_iterator.py b/src/pipecat/utils/asyncio/watchdog_async_iterator.py index d9d3e2f79..c9db0ba7e 100644 --- a/src/pipecat/utils/asyncio/watchdog_async_iterator.py +++ b/src/pipecat/utils/asyncio/watchdog_async_iterator.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Watchdog-enabled async iterator wrapper for task monitoring. + +This module provides an async iterator wrapper that automatically resets +watchdog timers while waiting for iterator items, preventing false positive +watchdog timeouts during legitimate waiting periods. +""" + import asyncio from typing import AsyncIterator, Optional @@ -11,10 +18,11 @@ from pipecat.utils.asyncio.task_manager import BaseTaskManager class WatchdogAsyncIterator: - """An asynchronous iterator that monitors activity and resets the current + """Watchdog async iterator wrapper. + + An asynchronous iterator that monitors activity and resets the current task watchdog timer. This is necessary to avoid task watchdog timers to expire while we are waiting to get an item from the iterator. - """ def __init__( @@ -24,6 +32,13 @@ class WatchdogAsyncIterator: manager: BaseTaskManager, timeout: float = 2.0, ): + """Initialize the watchdog async iterator. + + Args: + async_iterable: The async iterable to wrap with watchdog monitoring. + manager: The task manager for watchdog timer control. + timeout: Timeout in seconds between watchdog resets while waiting. + """ self._async_iterable = async_iterable self._manager = manager self._timeout = timeout @@ -31,9 +46,22 @@ class WatchdogAsyncIterator: self._current_anext_task: Optional[asyncio.Task] = None def __aiter__(self): + """Return self as the async iterator. + + Returns: + This iterator instance. + """ return self async def __anext__(self): + """Get the next item from the iterator with watchdog monitoring. + + Returns: + The next item from the wrapped async iterator. + + Raises: + StopAsyncIteration: When the iterator is exhausted. + """ if not self._iter: self._iter = await self._ensure_async_iterator(self._async_iterable) @@ -43,6 +71,7 @@ class WatchdogAsyncIterator: return await self._iter.__anext__() async def _watchdog_anext(self): + """Get next item while periodically resetting watchdog timer.""" while True: try: if not self._current_anext_task: @@ -67,6 +96,7 @@ class WatchdogAsyncIterator: raise async def _ensure_async_iterator(self, obj) -> AsyncIterator: + """Ensure the object is an async iterator, awaiting if necessary.""" aiter = obj.__aiter__() if asyncio.iscoroutine(aiter): aiter = await aiter diff --git a/src/pipecat/utils/asyncio/watchdog_coroutine.py b/src/pipecat/utils/asyncio/watchdog_coroutine.py index 84855c3e6..234776548 100644 --- a/src/pipecat/utils/asyncio/watchdog_coroutine.py +++ b/src/pipecat/utils/asyncio/watchdog_coroutine.py @@ -4,17 +4,26 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Watchdog-enabled coroutine wrapper for task monitoring. + +This module provides a coroutine wrapper that automatically resets watchdog +timers while waiting for coroutine completion, preventing false positive +watchdog timeouts during legitimate operations. +""" + import asyncio from typing import Optional +from pipecat.pipeline import task from pipecat.utils.asyncio.task_manager import BaseTaskManager class WatchdogCoroutine: - """An asynchronous iterator that monitors activity and resets the current + """Watchdog-enabled coroutine wrapper. + + An asynchronous iterator that monitors activity and resets the current task watchdog timer. This is necessary to avoid task watchdog timers to expire while we are waiting to get an item from the iterator. - """ def __init__( @@ -24,18 +33,27 @@ class WatchdogCoroutine: manager: BaseTaskManager, timeout: float = 2.0, ): + """Initialize the watchdog coroutine wrapper. + + Args: + coroutine: The coroutine to wrap with watchdog monitoring. + manager: The task manager for watchdog timer control. + timeout: Timeout in seconds between watchdog resets while waiting. + """ self._coroutine = coroutine self._manager = manager self._timeout = timeout self._current_coro_task: Optional[asyncio.Task] = None async def __call__(self): + """Execute the wrapped coroutine with watchdog monitoring.""" if self._manager.task_watchdog_enabled: return await self._watchdog_call() else: return await self._coroutine async def _watchdog_call(self): + """Execute coroutine while periodically resetting watchdog timer.""" while True: try: if not self._current_coro_task: @@ -57,5 +75,15 @@ class WatchdogCoroutine: async def watchdog_coroutine(coroutine, *, manager: BaseTaskManager, timeout: float = 2.0): + """Execute a coroutine with watchdog monitoring support. + + Args: + coroutine: The coroutine to execute with watchdog monitoring. + manager: The task manager for watchdog timer control. + timeout: Timeout in seconds between watchdog resets while waiting. + + Returns: + The result of the coroutine execution. + """ watchdog_coro = WatchdogCoroutine(coroutine, manager=manager, timeout=timeout) return await watchdog_coro() diff --git a/src/pipecat/utils/asyncio/watchdog_event.py b/src/pipecat/utils/asyncio/watchdog_event.py index 65453f6ec..b2b306618 100644 --- a/src/pipecat/utils/asyncio/watchdog_event.py +++ b/src/pipecat/utils/asyncio/watchdog_event.py @@ -4,16 +4,24 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Watchdog-enabled asyncio Event for task monitoring. + +This module provides an asyncio Event subclass that automatically resets +watchdog timers while waiting for the event, preventing false positive +watchdog timeouts during legitimate waiting periods. +""" + import asyncio from pipecat.utils.asyncio.task_manager import BaseTaskManager class WatchdogEvent(asyncio.Event): - """An asynchronous event that resets the current task watchdog timer. This + """Watchdog-enabled asyncio Event. + + An asynchronous event that resets the current task watchdog timer. This is necessary to avoid task watchdog timers to expire while we are waiting on the event. - """ def __init__( @@ -22,17 +30,29 @@ class WatchdogEvent(asyncio.Event): *, timeout: float = 2.0, ) -> None: + """Initialize the watchdog event. + + Args: + manager: The task manager for watchdog timer control. + timeout: Timeout in seconds between watchdog resets while waiting. + """ super().__init__() self._manager = manager self._timeout = timeout async def wait(self): + """Wait for the event to be set with watchdog monitoring. + + Returns: + True when the event is set. + """ if self._manager.task_watchdog_enabled: return await self._watchdog_wait() else: return await super().wait() async def _watchdog_wait(self): + """Wait for event while periodically resetting watchdog timer.""" while True: try: await asyncio.wait_for(super().wait(), timeout=self._timeout) diff --git a/src/pipecat/utils/asyncio/watchdog_priority_queue.py b/src/pipecat/utils/asyncio/watchdog_priority_queue.py index 31d358fc7..46c6adf3d 100644 --- a/src/pipecat/utils/asyncio/watchdog_priority_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_priority_queue.py @@ -4,16 +4,24 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Watchdog-enabled asyncio PriorityQueue for task monitoring. + +This module provides an asyncio PriorityQueue subclass that automatically resets +watchdog timers while waiting for items, preventing false positive watchdog +timeouts during legitimate queue operations. +""" + import asyncio from pipecat.utils.asyncio.task_manager import BaseTaskManager class WatchdogPriorityQueue(asyncio.PriorityQueue): - """An asynchronous priority queue that resets the current task watchdog + """Watchdog-enabled asyncio PriorityQueue. + + An asynchronous priority queue that resets the current task watchdog timer. This is necessary to avoid task watchdog timers to expire while we are waiting to get an item from the queue. - """ def __init__( @@ -23,22 +31,39 @@ class WatchdogPriorityQueue(asyncio.PriorityQueue): maxsize: int = 0, timeout: float = 2.0, ) -> None: + """Initialize the watchdog priority queue. + + Args: + manager: The task manager for watchdog timer control. + maxsize: Maximum queue size. 0 means unlimited. + timeout: Timeout in seconds between watchdog resets while waiting. + """ super().__init__(maxsize) self._manager = manager self._timeout = timeout async def get(self): + """Get an item from the queue with watchdog monitoring. + + Returns: + The next item from the priority queue. + """ if self._manager.task_watchdog_enabled: return await self._watchdog_get() else: return await super().get() def task_done(self): + """Mark a task as done and reset watchdog if enabled. + + Should be called after processing each item retrieved from the queue. + """ if self._manager.task_watchdog_enabled: self._manager.task_reset_watchdog() super().task_done() async def _watchdog_get(self): + """Get item from queue while periodically resetting watchdog timer.""" while True: try: item = await asyncio.wait_for(super().get(), timeout=self._timeout) diff --git a/src/pipecat/utils/asyncio/watchdog_queue.py b/src/pipecat/utils/asyncio/watchdog_queue.py index 961324b7b..4a92497f4 100644 --- a/src/pipecat/utils/asyncio/watchdog_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_queue.py @@ -4,16 +4,24 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Watchdog-enabled asyncio Queue for task monitoring. + +This module provides an asyncio Queue subclass that automatically resets +watchdog timers while waiting for items, preventing false positive watchdog +timeouts during legitimate queue operations. +""" + import asyncio from pipecat.utils.asyncio.task_manager import BaseTaskManager class WatchdogQueue(asyncio.Queue): - """An asynchronous queue that resets the current task watchdog timer. This + """Watchdog-enabled asyncio Queue. + + An asynchronous queue that resets the current task watchdog timer. This is necessary to avoid task watchdog timers to expire while we are waiting to get an item from the queue. - """ def __init__( @@ -23,22 +31,39 @@ class WatchdogQueue(asyncio.Queue): maxsize: int = 0, timeout: float = 2.0, ) -> None: + """Initialize the watchdog queue. + + Args: + manager: The task manager for watchdog timer control. + maxsize: Maximum queue size. 0 means unlimited. + timeout: Timeout in seconds between watchdog resets while waiting. + """ super().__init__(maxsize) self._manager = manager self._timeout = timeout async def get(self): + """Get an item from the queue with watchdog monitoring. + + Returns: + The next item from the queue. + """ if self._manager.task_watchdog_enabled: return await self._watchdog_get() else: return await super().get() def task_done(self): + """Mark a task as done and reset watchdog if enabled. + + Should be called after processing each item retrieved from the queue. + """ if self._manager.task_watchdog_enabled: self._manager.task_reset_watchdog() super().task_done() async def _watchdog_get(self): + """Get item from queue while periodically resetting watchdog timer.""" while True: try: item = await asyncio.wait_for(super().get(), timeout=self._timeout) diff --git a/src/pipecat/utils/base_object.py b/src/pipecat/utils/base_object.py index 03b42ade0..51eb1195b 100644 --- a/src/pipecat/utils/base_object.py +++ b/src/pipecat/utils/base_object.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base object class providing event handling and lifecycle management. + +This module provides the foundational BaseObject class that offers common +functionality including unique identification, naming, event handling, +and async cleanup for all Pipecat components. +""" + import asyncio import inspect from abc import ABC @@ -15,7 +22,20 @@ from pipecat.utils.utils import obj_count, obj_id class BaseObject(ABC): + """Abstract base class providing common functionality for Pipecat objects. + + Provides unique identification, naming, event handling capabilities, + and async lifecycle management for all Pipecat components. All major + classes in the framework should inherit from this base class. + """ + def __init__(self, *, name: Optional[str] = None): + """Initialize the base object. + + Args: + name: Optional custom name for the object. If not provided, + generates a name using the class name and instance count. + """ self._id: int = obj_id() self._name = name or f"{self.__class__.__name__}#{obj_count(self)}" @@ -29,19 +49,44 @@ class BaseObject(ABC): @property def id(self) -> int: + """Get the unique identifier for this object. + + Returns: + The unique integer ID assigned to this object instance. + """ return self._id @property def name(self) -> str: + """Get the name of this object. + + Returns: + The object's name, either custom-provided or auto-generated. + """ return self._name async def cleanup(self): + """Clean up resources and wait for running event handlers to complete. + + This method should be called when the object is no longer needed. + It waits for all currently executing event handler tasks to finish + before returning. + """ if self._event_tasks: event_names, tasks = zip(*self._event_tasks) logger.debug(f"{self} waiting on event handlers to finish {list(event_names)}...") await asyncio.wait(tasks) def event_handler(self, event_name: str): + """Decorator for registering event handlers. + + Args: + event_name: The name of the event to handle. + + Returns: + The decorator function that registers the handler. + """ + def decorator(handler): self.add_event_handler(event_name, handler) return handler @@ -49,18 +94,37 @@ class BaseObject(ABC): return decorator def add_event_handler(self, event_name: str, handler): + """Add an event handler for the specified event. + + Args: + event_name: The name of the event to handle. + handler: The function to call when the event occurs. + Can be sync or async. + """ if event_name in self._event_handlers: self._event_handlers[event_name].append(handler) else: logger.warning(f"Event handler {event_name} not registered") def _register_event_handler(self, event_name: str): + """Register an event handler type. + + Args: + event_name: The name of the event type to register. + """ if event_name not in self._event_handlers: self._event_handlers[event_name] = [] else: logger.warning(f"Event handler {event_name} not registered") async def _call_event_handler(self, event_name: str, *args, **kwargs): + """Call all registered handlers for the specified event. + + Args: + event_name: The name of the event to trigger. + *args: Positional arguments to pass to event handlers. + **kwargs: Keyword arguments to pass to event handlers. + """ # If we haven't registered an event handler, we don't need to do # anything. if not self._event_handlers.get(event_name): @@ -76,6 +140,13 @@ class BaseObject(ABC): task.add_done_callback(self._event_task_finished) async def _run_task(self, event_name: str, *args, **kwargs): + """Execute all handlers for an event. + + Args: + event_name: The name of the event being handled. + *args: Positional arguments to pass to handlers. + **kwargs: Keyword arguments to pass to handlers. + """ try: for handler in self._event_handlers[event_name]: if inspect.iscoroutinefunction(handler): @@ -86,9 +157,19 @@ class BaseObject(ABC): logger.exception(f"Exception in event handler {event_name}: {e}") def _event_task_finished(self, task: asyncio.Task): + """Clean up completed event handler tasks. + + Args: + task: The completed asyncio Task to remove from tracking. + """ tuple_to_remove = next((t for t in self._event_tasks if t[1] == task), None) if tuple_to_remove: self._event_tasks.discard(tuple_to_remove) def __str__(self): + """Return the string representation of this object. + + Returns: + The object's name as its string representation. + """ return self.name diff --git a/src/pipecat/utils/network.py b/src/pipecat/utils/network.py index 27bec990c..3aef43988 100644 --- a/src/pipecat/utils/network.py +++ b/src/pipecat/utils/network.py @@ -4,6 +4,8 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base class for network utilities, providing exponential backoff time calculation.""" + def exponential_backoff_time( attempt: int, min_wait: float = 4, max_wait: float = 10, multiplier: float = 1 diff --git a/src/pipecat/utils/string.py b/src/pipecat/utils/string.py index 69036a665..21449a3ab 100644 --- a/src/pipecat/utils/string.py +++ b/src/pipecat/utils/string.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Text processing utilities for sentence boundary detection and tag parsing. + +This module provides utilities for natural language text processing including +sentence boundary detection, email and number pattern handling, and XML-style +tag parsing for structured text content. +""" + import re from typing import Optional, Sequence, Tuple @@ -30,18 +37,16 @@ StartEndTags = Tuple[str, str] def replace_match(text: str, match: re.Match, old: str, new: str) -> str: - """Replace occurrences of a substring within a matched section of a given - text. + """Replace occurrences of a substring within a matched section of text. Args: - text (str): The input text in which replacements will be made. - match (re.Match): A regex match object representing the section of text to modify. - old (str): The substring to be replaced. - new (str): The substring to replace `old` with. + text: The input text in which replacements will be made. + match: A regex match object representing the section of text to modify. + old: The substring to be replaced. + new: The substring to replace `old` with. Returns: - str: The modified text with the specified replacements made within the matched section. - + The modified text with the specified replacements made within the matched section. """ start = match.start() end = match.end() @@ -51,7 +56,7 @@ def replace_match(text: str, match: re.Match, old: str, new: str) -> str: def match_endofsentence(text: str) -> int: - """Finds the position of the end of a sentence in the provided text string. + """Find the position of the end of a sentence in the provided text. This function processes the input text by replacing periods in email addresses and numbers with ampersands to prevent them from being @@ -59,11 +64,10 @@ def match_endofsentence(text: str) -> int: sentence using a specified regex pattern. Args: - text (str): The input text in which to find the end of the sentence. + text: The input text in which to find the end of the sentence. Returns: - int: The position of the end of the sentence if found, otherwise 0. - + The position of the end of the sentence if found, otherwise 0. """ text = text.rstrip() @@ -90,24 +94,22 @@ def parse_start_end_tags( current_tag: Optional[StartEndTags], current_tag_index: int, ) -> Tuple[Optional[StartEndTags], int]: - """Parses the given text to identify a pair of start/end tags. + """Parse text to identify start and end tag pairs. - If a start tag was previously found (i.e. current_tags is valid), wait for - the corresponding end tag. Otherwise, wait for a start tag. + If a start tag was previously found (i.e., current_tag is valid), wait for + the corresponding end tag. Otherwise, wait for a start tag. - This function will return the index in the text that we should start parsing + This function returns the index in the text where parsing should continue in the next call and the current or new tags. - Parameters: - - text (str): The text to be parsed. - - tags (Sequence[StartEndTags]): List of tuples containing start and end tags. - - current_tags (Optional[StartEndTags]): The currently active tags, if any. - - current_tags_index (int): The current index in the text. + Args: + text: The text to be parsed. + tags: List of tuples containing start and end tags. + current_tag: The currently active tags, if any. + current_tag_index: The current index in the text. Returns: - Tuple[Optional[StartEndTags], int]: A tuple containing None or the current - tag and the index of the text. - + A tuple containing None or the current tag and the index of the text. """ # If we are already inside a tag, check if the end tag is in the text. if current_tag: diff --git a/src/pipecat/utils/text/base_text_aggregator.py b/src/pipecat/utils/text/base_text_aggregator.py index 01fd2ba9e..27e50fff5 100644 --- a/src/pipecat/utils/text/base_text_aggregator.py +++ b/src/pipecat/utils/text/base_text_aggregator.py @@ -4,54 +4,85 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base text aggregator interface for Pipecat text processing. + +This module defines the abstract base class for text aggregators that accumulate +and process text tokens, typically used by TTS services to determine when +aggregated text should be sent for speech synthesis. +""" + from abc import ABC, abstractmethod from typing import Optional class BaseTextAggregator(ABC): - """This is the base class for text aggregators. Text aggregators are usually - used by the TTS service to aggregate LLM tokens and decide when the - aggregated text should be pushed to the TTS service. + """Base class for text aggregators in the Pipecat framework. + + Text aggregators are usually used by the TTS service to aggregate LLM tokens + and decide when the aggregated text should be pushed to the TTS service. Text aggregators can also be used to manipulate text while it's being aggregated (e.g. reasoning blocks can be removed). + Subclasses must implement all abstract methods to define specific aggregation + logic, text manipulation behavior, and state management for interruptions. """ @property @abstractmethod def text(self) -> str: - """Returns the currently aggregated text.""" + """Get the currently aggregated text. + + Subclasses must implement this property to return the text that has + been accumulated so far in their internal buffer or storage. + + Returns: + The text that has been accumulated so far. + """ pass @abstractmethod async def aggregate(self, text: str) -> Optional[str]: - """Aggregates the specified text with the currently accumulated text. + """Aggregate the specified text with the currently accumulated text. This method should be implemented to define how the new text contributes to the aggregation process. It returns the updated aggregated text if it's ready to be processed, or None otherwise. + Subclasses should implement their specific logic for: + + - How to combine new text with existing accumulated text + - When to consider the aggregated text ready for processing + - What criteria determine text completion (e.g., sentence boundaries) + Args: - text (str): The text to be aggregated. + text: The text to be aggregated. Returns: - Optional[str]: The updated aggregated text or None if aggregated - text is not ready. - + The updated aggregated text if ready for processing, or None if more + text is needed before the aggregated content is ready. """ pass @abstractmethod async def handle_interruption(self): - """Handles interruptions. When an interruption occurs it is possible - that we might want to discard the aggregated text or do some internal - modifications to the aggregated text. + """Handle interruptions in the text aggregation process. + When an interruption occurs it is possible that we might want to discard + the aggregated text or do some internal modifications to the aggregated text. + + Subclasses should implement this method to define how they respond to + interruptions, such as clearing buffers, resetting state, or preserving + partial content. """ pass @abstractmethod async def reset(self): - """Clears the internally aggregated text.""" + """Clear the internally aggregated text and reset to initial state. + + Subclasses should implement this method to return the aggregator to its + initial state, discarding any previously accumulated text content and + resetting any internal tracking variables. + """ pass diff --git a/src/pipecat/utils/text/base_text_filter.py b/src/pipecat/utils/text/base_text_filter.py index 787a1a9da..1a18a38a6 100644 --- a/src/pipecat/utils/text/base_text_filter.py +++ b/src/pipecat/utils/text/base_text_filter.py @@ -4,23 +4,69 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Base text filter interface for Pipecat text processing. + +This module defines the abstract base class for text filters that can modify +text content in the processing pipeline, including support for settings updates +and interruption handling. +""" + from abc import ABC, abstractmethod from typing import Any, Mapping class BaseTextFilter(ABC): + """Abstract base class for text filters in the Pipecat framework. + + Text filters are responsible for modifying text content as it flows through + the processing pipeline. They support dynamic settings updates and can handle + interruptions to reset their internal state. + + Subclasses must implement all abstract methods to define specific filtering + behavior, settings management, and interruption handling logic. + """ + @abstractmethod async def update_settings(self, settings: Mapping[str, Any]): + """Update the filter's configuration settings. + + Subclasses should implement this method to handle dynamic configuration + updates during runtime, updating internal state as needed. + + Args: + settings: Dictionary of setting names to values for configuration. + """ pass @abstractmethod async def filter(self, text: str) -> str: + """Apply filtering transformations to the input text. + + Subclasses must implement this method to define the specific text + transformations that should be applied to the input. + + Args: + text: The input text to be filtered. + + Returns: + The filtered text after applying transformations. + """ pass @abstractmethod async def handle_interruption(self): + """Handle interruption events in the processing pipeline. + + Subclasses should implement this method to reset internal state, + clear buffers, or perform other cleanup when an interruption occurs. + """ pass @abstractmethod async def reset_interruption(self): + """Reset the filter state after an interruption has been handled. + + Subclasses should implement this method to restore the filter to normal + operation after an interruption has been processed and resolved. + """ pass diff --git a/src/pipecat/utils/text/markdown_text_filter.py b/src/pipecat/utils/text/markdown_text_filter.py index 5ec960ad2..49b56b47a 100644 --- a/src/pipecat/utils/text/markdown_text_filter.py +++ b/src/pipecat/utils/text/markdown_text_filter.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Markdown text filter for removing Markdown formatting from text. + +This module provides a text filter that converts Markdown content to plain text +while preserving structure and handling special cases like code blocks and tables. +""" + import re from typing import Any, Mapping, Optional @@ -14,19 +20,34 @@ from pipecat.utils.text.base_text_filter import BaseTextFilter class MarkdownTextFilter(BaseTextFilter): - """Removes Markdown formatting from text in TextFrames. + """Text filter that removes Markdown formatting from text content. Converts Markdown to plain text while preserving the overall structure, including leading and trailing spaces. Handles special cases like - asterisks and table formatting. + asterisks and table formatting. Supports selective filtering of code + blocks and tables based on configuration. """ class InputParams(BaseModel): + """Configuration parameters for Markdown text filtering. + + Parameters: + enable_text_filter: Whether to apply Markdown filtering. Defaults to True. + filter_code: Whether to remove code blocks from the text. Defaults to False. + filter_tables: Whether to remove table content from the text. Defaults to False. + """ + enable_text_filter: Optional[bool] = True filter_code: Optional[bool] = False filter_tables: Optional[bool] = False def __init__(self, params: Optional[InputParams] = None, **kwargs): + """Initialize the Markdown text filter. + + Args: + params: Configuration parameters for filtering behavior. + **kwargs: Additional keyword arguments passed to parent class. + """ super().__init__(**kwargs) self._settings = params or MarkdownTextFilter.InputParams() self._in_code_block = False @@ -34,11 +55,24 @@ class MarkdownTextFilter(BaseTextFilter): self._interrupted = False async def update_settings(self, settings: Mapping[str, Any]): + """Update the filter's configuration settings. + + Args: + settings: Dictionary of setting names to values for configuration. + """ for key, value in settings.items(): if hasattr(self._settings, key): setattr(self._settings, key, value) async def filter(self, text: str) -> str: + """Apply Markdown filtering transformations to the input text. + + Args: + text: The input text containing Markdown formatting to be filtered. + + Returns: + The filtered text with Markdown formatting removed or converted. + """ if self._settings.enable_text_filter: # Remove newlines and replace with a space only when there's no text before or after filtered_text = re.sub(r"^\s*\n", " ", text, flags=re.MULTILINE) @@ -108,11 +142,20 @@ class MarkdownTextFilter(BaseTextFilter): return text async def handle_interruption(self): + """Handle interruption events in the processing pipeline. + + Resets the filter state and clears any tracking variables for + code blocks and tables. + """ self._interrupted = True self._in_code_block = False self._in_table = False async def reset_interruption(self): + """Reset the filter state after an interruption has been handled. + + Clears the interrupted flag to restore normal operation. + """ self._interrupted = False # @@ -120,8 +163,10 @@ class MarkdownTextFilter(BaseTextFilter): # def _remove_code_blocks(self, text: str) -> str: - """Main method to remove code blocks from the input text. - Handles interruptions and delegates to specific methods based on the current state. + """Remove code blocks from the input text. + + Handles interruptions and delegates to specific methods based on the + current state. """ if self._interrupted: self._in_code_block = False @@ -137,8 +182,10 @@ class MarkdownTextFilter(BaseTextFilter): return self._handle_not_in_code_block(match, text, code_block_pattern) def _handle_in_code_block(self, match, text): - """Handle text when we're currently inside a code block. - If we find the end of the block, return text after it. Otherwise, skip the content. + """Handle text when not currently inside a code block. + + If we find the end of the block, return text after it. Otherwise, skip + the content. """ if match: self._in_code_block = False @@ -147,9 +194,7 @@ class MarkdownTextFilter(BaseTextFilter): return "" # Skip content inside code block def _handle_not_in_code_block(self, match, text, code_block_pattern): - """Handle text when we're not currently inside a code block. - Delegate to specific methods based on whether we find a code block delimiter. - """ + """Handle text when not currently inside a code block.""" if not match: return text # No code block found, return original text @@ -159,14 +204,17 @@ class MarkdownTextFilter(BaseTextFilter): return self._handle_code_block_within_text(text, code_block_pattern) def _handle_start_of_code_block(self, text, start_index): - """Handle the case where we find the start of a code block. - Return any text before the code block and set the state to inside a code block. + """Handle the case where a code block starts. + + Return any text before the code block and set the state to inside a + code block. """ self._in_code_block = True return text[:start_index].strip() def _handle_code_block_within_text(self, text, code_block_pattern): - """Handle the case where we find a code block within the text. + """Handle code blocks found within text content. + If it's a complete code block, remove it and return surrounding text. If it's the start of a code block, return text before it and set state. """ @@ -180,8 +228,16 @@ class MarkdownTextFilter(BaseTextFilter): # Filter tables # def remove_tables(self, text: str) -> str: - """Remove tables from the input text, handling cases where - both start and end tags are in the same input. + """Remove HTML tables from the input text. + + Handles cases where both start and end tags are in the same input, + as well as tables that span multiple text chunks. + + Args: + text: The text containing HTML tables to remove. + + Returns: + The text with tables removed. """ if self._interrupted: self._in_table = False diff --git a/src/pipecat/utils/text/pattern_pair_aggregator.py b/src/pipecat/utils/text/pattern_pair_aggregator.py index dbc985774..ac074f2de 100644 --- a/src/pipecat/utils/text/pattern_pair_aggregator.py +++ b/src/pipecat/utils/text/pattern_pair_aggregator.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Pattern pair aggregator for processing structured content in streaming text. + +This module provides an aggregator that identifies and processes content between +pattern pairs (like XML tags or custom delimiters) in streaming text, with +support for custom handlers and configurable pattern removal. +""" + import re from typing import Awaitable, Callable, Optional, Tuple @@ -20,20 +27,15 @@ class PatternMatch: in the text. It contains information about which pattern was matched, the full matched text (including start and end patterns), and the content between the patterns. - - Attributes: - pattern_id: The identifier of the matched pattern pair. - full_match: The complete text including start and end patterns. - content: The text content between the start and end patterns. """ def __init__(self, pattern_id: str, full_match: str, content: str): """Initialize a pattern match. Args: - pattern_id: ID of the pattern pair. - full_match: Complete matched text including start and end patterns. - content: Content between the start and end patterns. + pattern_id: The identifier of the matched pattern pair. + full_match: The complete text including start and end patterns. + content: The text content between the start and end patterns. """ self.pattern_id = pattern_id self.full_match = full_match @@ -43,7 +45,7 @@ class PatternMatch: """Return a string representation of the pattern match. Returns: - A string describing the pattern match. + A descriptive string showing the pattern ID and content. """ return f"PatternMatch(id={self.pattern_id}, content={self.content})" @@ -66,6 +68,7 @@ class PatternPairAggregator(BaseTextAggregator): """Initialize the pattern pair aggregator. Creates an empty aggregator with no patterns or handlers registered. + Text buffering and pattern detection will begin when text is aggregated. """ self._text = "" self._patterns = {} @@ -76,7 +79,7 @@ class PatternPairAggregator(BaseTextAggregator): """Get the currently buffered text. Returns: - The current text buffer content. + The current text buffer content that hasn't been processed yet. """ return self._text @@ -115,7 +118,7 @@ class PatternPairAggregator(BaseTextAggregator): Args: pattern_id: ID of the pattern pair to match. - handler: Function to call when pattern is matched. + handler: Async function to call when pattern is matched. The function should accept a PatternMatch object. Returns: @@ -131,10 +134,11 @@ class PatternPairAggregator(BaseTextAggregator): appropriate handlers, and optionally removes the matches. Args: - text: The text to process. + text: The text to process for pattern matches. Returns: Tuple of (processed_text, was_modified) where: + - processed_text is the text after processing patterns - was_modified indicates whether any changes were made """ @@ -185,7 +189,7 @@ class PatternPairAggregator(BaseTextAggregator): matching end patterns, which would indicate incomplete content. Args: - text: The text to check. + text: The text to check for incomplete patterns. Returns: True if there are incomplete patterns, False otherwise. @@ -257,6 +261,6 @@ class PatternPairAggregator(BaseTextAggregator): """Clear the internally aggregated text. Resets the aggregator to its initial state, discarding any - buffered text. + buffered text and clearing pattern tracking state. """ self._text = "" diff --git a/src/pipecat/utils/text/simple_text_aggregator.py b/src/pipecat/utils/text/simple_text_aggregator.py index 791844f73..f9eb7d83a 100644 --- a/src/pipecat/utils/text/simple_text_aggregator.py +++ b/src/pipecat/utils/text/simple_text_aggregator.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Simple text aggregator for basic sentence-boundary text processing. + +This module provides a straightforward text aggregator that accumulates text +until it finds an end-of-sentence marker, making it suitable for basic TTS +text processing scenarios. +""" + from typing import Optional from pipecat.utils.string import match_endofsentence @@ -11,19 +18,43 @@ from pipecat.utils.text.base_text_aggregator import BaseTextAggregator class SimpleTextAggregator(BaseTextAggregator): - """This is a simple text aggregator. It aggregates text until an end of - sentence is found. + """Simple text aggregator that accumulates text until sentence boundaries. + This aggregator provides basic functionality for accumulating text tokens + and releasing them when an end-of-sentence marker is detected. It's the + most straightforward implementation of text aggregation for TTS processing. """ def __init__(self): + """Initialize the simple text aggregator. + + Creates an empty text buffer ready to begin accumulating text tokens. + """ self._text = "" @property def text(self) -> str: + """Get the currently aggregated text. + + Returns: + The text that has been accumulated in the buffer. + """ return self._text async def aggregate(self, text: str) -> Optional[str]: + """Aggregate text and return completed sentences. + + Adds the new text to the buffer and checks for end-of-sentence markers. + When a sentence boundary is found, returns the completed sentence and + removes it from the buffer. + + Args: + text: New text to add to the aggregation buffer. + + Returns: + A complete sentence if an end-of-sentence marker is found, + or None if more text is needed to complete a sentence. + """ result: Optional[str] = None self._text += text @@ -36,7 +67,17 @@ class SimpleTextAggregator(BaseTextAggregator): return result async def handle_interruption(self): + """Handle interruptions by clearing the text buffer. + + Called when an interruption occurs in the processing pipeline, + discarding any partially accumulated text. + """ self._text = "" async def reset(self): + """Clear the internally aggregated text. + + Resets the aggregator to its initial empty state, discarding + any accumulated text content. + """ self._text = "" diff --git a/src/pipecat/utils/text/skip_tags_aggregator.py b/src/pipecat/utils/text/skip_tags_aggregator.py index 81bbb9a96..6f6f8455c 100644 --- a/src/pipecat/utils/text/skip_tags_aggregator.py +++ b/src/pipecat/utils/text/skip_tags_aggregator.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Skip tags aggregator for preventing sentence boundaries within tagged content. + +This module provides a text aggregator that prevents end-of-sentence matching +between specified start/end tag pairs, ensuring that tagged content is processed +as a unit regardless of internal punctuation. +""" + from typing import Optional, Sequence from pipecat.utils.string import StartEndTags, match_endofsentence, parse_start_end_tags @@ -17,17 +24,18 @@ class SkipTagsAggregator(BaseTextAggregator): tag. If a start tag is found the aggregator will keep aggregating text unconditionally until the corresponding end tag is found. It's particularly useful for processing content with custom delimiters that should prevent - text from being considered for end of sentence matching.. + text from being considered for end of sentence matching. The aggregator ensures that tags spanning multiple text chunks are correctly - identified. - + identified and that content within tags is never split at sentence boundaries. """ def __init__(self, tags: Sequence[StartEndTags]): - """Initialize the pattern pair aggregator. + """Initialize the skip tags aggregator. - Creates an empty aggregator with no patterns or handlers registered. + Args: + tags: Sequence of StartEndTags objects defining the tag pairs + that should prevent sentence boundary detection. """ self._text = "" self._tags = tags @@ -39,24 +47,24 @@ class SkipTagsAggregator(BaseTextAggregator): """Get the currently buffered text. Returns: - The current text buffer content. + The current text buffer content that hasn't been processed yet. """ return self._text async def aggregate(self, text: str) -> Optional[str]: - """Aggregate text and process pattern pairs. + """Aggregate text while respecting tag boundaries. - This method adds the new text to the buffer, processes any complete pattern - pairs, and returns processed text up to sentence boundaries if possible. - If there are incomplete patterns (start without matching end), it will - continue buffering text. + This method adds the new text to the buffer, processes any complete + pattern pairs, and returns processed text up to sentence boundaries if + possible. If there are incomplete patterns (start without matching + end), it will continue buffering text. Args: text: New text to add to the buffer. Returns: - Processed text up to a sentence boundary, or None if more - text is needed to form a complete sentence or pattern. + Processed text up to a sentence boundary (when not within tags), + or None if more text is needed to complete a sentence or close tags. """ # Add new text to buffer self._text += text diff --git a/src/pipecat/utils/time.py b/src/pipecat/utils/time.py index b1e95f895..36156b1ca 100644 --- a/src/pipecat/utils/time.py +++ b/src/pipecat/utils/time.py @@ -4,22 +4,58 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Time utilities for the Pipecat framework. + +This module provides utility functions for time handling including +ISO8601 formatting, nanosecond conversions, and human-readable +time string formatting. +""" + import datetime def time_now_iso8601() -> str: + """Get the current UTC time as an ISO8601 formatted string. + + Returns: + The current UTC time in ISO8601 format with millisecond precision. + """ return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="milliseconds") def seconds_to_nanoseconds(seconds: float) -> int: + """Convert seconds to nanoseconds. + + Args: + seconds: The number of seconds to convert. + + Returns: + The equivalent number of nanoseconds as an integer. + """ return int(seconds * 1_000_000_000) def nanoseconds_to_seconds(nanoseconds: int) -> float: + """Convert nanoseconds to seconds. + + Args: + nanoseconds: The number of nanoseconds to convert. + + Returns: + The equivalent number of seconds as a float. + """ return nanoseconds / 1_000_000_000 def nanoseconds_to_str(nanoseconds: int) -> str: + """Convert nanoseconds to a human-readable time string. + + Args: + nanoseconds: The number of nanoseconds to convert. + + Returns: + A formatted time string in "H:MM:SS.microseconds" format. + """ total_seconds = nanoseconds_to_seconds(nanoseconds) hours = int(total_seconds // 3600) minutes = int((total_seconds % 3600) // 60) diff --git a/src/pipecat/utils/tracing/class_decorators.py b/src/pipecat/utils/tracing/class_decorators.py index 98da7211e..ba997b275 100644 --- a/src/pipecat/utils/tracing/class_decorators.py +++ b/src/pipecat/utils/tracing/class_decorators.py @@ -33,7 +33,7 @@ C = TypeVar("C", bound=type) class AttachmentStrategy(enum.Enum): """Controls how spans are attached to the trace hierarchy. - Attributes: + Parameters: CHILD: Attached to class span if no parent, otherwise to parent. LINK: Attached to class span with link to parent. NONE: Always attached to class span regardless of context. @@ -71,10 +71,10 @@ class Traceable: @property def meter(self): - """Returns the OpenTelemetry meter instance. + """Get the OpenTelemetry meter instance. Returns: - Meter: The OpenTelemetry meter instance for this object. + The OpenTelemetry meter instance for this object. """ return self._meter @@ -83,7 +83,17 @@ class Traceable: def __traced_context_manager( self: Traceable, func: Callable, name: str | None, attachment_strategy: AttachmentStrategy ): - """Internal context manager for the traced decorator.""" + """Internal context manager for the traced decorator. + + Args: + self: The Traceable instance. + func: The function being traced. + name: Custom span name or None to use function name. + attachment_strategy: How to attach this span to the trace hierarchy. + + Raises: + RuntimeError: If used in a class not inheriting from Traceable. + """ if not isinstance(self, Traceable): raise RuntimeError( "@traced annotation can only be used in classes inheriting from Traceable" @@ -124,7 +134,16 @@ def __traced_context_manager( def __traced_decorator(func, name, attachment_strategy: AttachmentStrategy): - """Implementation of the traced decorator.""" + """Implementation of the traced decorator. + + Args: + func: The function to trace. + name: Custom span name. + attachment_strategy: How to attach this span. + + Returns: + The wrapped function with tracing capabilities. + """ @functools.wraps(func) async def coroutine_wrapper(self: Traceable, *args, **kwargs): @@ -163,7 +182,7 @@ def traced( name: Optional[str] = None, attachment_strategy: AttachmentStrategy = AttachmentStrategy.CHILD, ) -> Callable: - """Adds tracing to an async function in a Traceable class. + """Add tracing to an async function in a Traceable class. Args: func: The async function to trace. @@ -193,7 +212,7 @@ def traced( def traceable(cls: C) -> C: - """Makes a class traceable for OpenTelemetry. + """Make a class traceable for OpenTelemetry. Creates a new class that inherits from both the original class and Traceable, enabling tracing for class methods. @@ -210,6 +229,12 @@ def traceable(cls: C) -> C: @functools.wraps(cls, updated=()) class TracedClass(cls, Traceable): def __init__(self, *args, **kwargs): + """Initialize the traced class instance. + + Args: + *args: Positional arguments passed to parent classes. + **kwargs: Keyword arguments passed to parent classes. + """ cls.__init__(self, *args, **kwargs) if hasattr(self, "name"): Traceable.__init__(self, self.name) diff --git a/src/pipecat/utils/tracing/conversation_context_provider.py b/src/pipecat/utils/tracing/conversation_context_provider.py index 611e59650..995776ff5 100644 --- a/src/pipecat/utils/tracing/conversation_context_provider.py +++ b/src/pipecat/utils/tracing/conversation_context_provider.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Conversation context provider for OpenTelemetry tracing in Pipecat. + +This module provides a singleton context provider that manages the current +conversation's tracing context, allowing services to create child spans +that are properly associated with the conversation. +""" + import uuid from typing import TYPE_CHECKING, Optional @@ -32,7 +39,11 @@ class ConversationContextProvider: @classmethod def get_instance(cls): - """Get the singleton instance.""" + """Get the singleton instance. + + Returns: + The singleton ConversationContextProvider instance. + """ if cls._instance is None: cls._instance = ConversationContextProvider() return cls._instance @@ -83,7 +94,6 @@ class ConversationContextProvider: return str(uuid.uuid4()) -# Create a simple helper function to get the current conversation context def get_current_conversation_context() -> Optional["Context"]: """Get the OpenTelemetry context for the current conversation. diff --git a/src/pipecat/utils/tracing/service_attributes.py b/src/pipecat/utils/tracing/service_attributes.py index 8f90ad3be..3896bd028 100644 --- a/src/pipecat/utils/tracing/service_attributes.py +++ b/src/pipecat/utils/tracing/service_attributes.py @@ -4,7 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # -"""Functions for adding attributes to OpenTelemetry spans.""" +"""Functions for adding attributes to OpenTelemetry spans. + +This module provides specialized functions for adding service-specific +attributes to OpenTelemetry spans, following standard semantic conventions +where applicable and Pipecat-specific conventions for additional context. +""" from typing import TYPE_CHECKING, Any, Dict, List, Optional @@ -26,6 +31,12 @@ def _get_gen_ai_system_from_service_name(service_name: str) -> str: Uses standard OTel names where possible, with special case mappings for service names that don't follow the pattern. + + Args: + service_name: The service class name to extract system name from. + + Returns: + The standardized gen_ai.system value. """ SPECIAL_CASE_MAPPINGS = { # AWS @@ -66,16 +77,16 @@ def add_tts_span_attributes( """Add TTS-specific attributes to a span. Args: - span: The span to add attributes to - service_name: Name of the TTS service (e.g., "cartesia") - model: Model name/identifier - voice_id: Voice identifier - text: The text being synthesized - settings: Service configuration settings - character_count: Number of characters in the text - operation_name: Name of the operation (default: "tts") - ttfb: Time to first byte in seconds - **kwargs: Additional attributes to add + span: The span to add attributes to. + service_name: Name of the TTS service (e.g., "cartesia"). + model: Model name/identifier. + voice_id: Voice identifier. + text: The text being synthesized. + settings: Service configuration settings. + character_count: Number of characters in the text. + operation_name: Name of the operation (default: "tts"). + ttfb: Time to first byte in seconds. + **kwargs: Additional attributes to add. """ # Add standard attributes span.set_attribute("gen_ai.system", service_name.replace("TTSService", "").lower()) @@ -122,17 +133,17 @@ def add_stt_span_attributes( """Add STT-specific attributes to a span. Args: - span: The span to add attributes to - service_name: Name of the STT service (e.g., "deepgram") - model: Model name/identifier - operation_name: Name of the operation (default: "stt") - transcript: The transcribed text - is_final: Whether this is a final transcript - language: Detected or configured language - settings: Service configuration settings - vad_enabled: Whether voice activity detection is enabled - ttfb: Time to first byte in seconds - **kwargs: Additional attributes to add + span: The span to add attributes to. + service_name: Name of the STT service (e.g., "deepgram"). + model: Model name/identifier. + operation_name: Name of the operation (default: "stt"). + transcript: The transcribed text. + is_final: Whether this is a final transcript. + language: Detected or configured language. + settings: Service configuration settings. + vad_enabled: Whether voice activity detection is enabled. + ttfb: Time to first byte in seconds. + **kwargs: Additional attributes to add. """ # Add standard attributes span.set_attribute("gen_ai.system", service_name.replace("STTService", "").lower()) @@ -184,20 +195,20 @@ def add_llm_span_attributes( """Add LLM-specific attributes to a span. Args: - span: The span to add attributes to - service_name: Name of the LLM service (e.g., "openai") - model: Model name/identifier - stream: Whether streaming is enabled - messages: JSON-serialized messages - output: Aggregated output text from the LLM - tools: JSON-serialized tools configuration - tool_count: Number of tools available - tool_choice: Tool selection configuration - system: System message - parameters: Service parameters - extra_parameters: Additional parameters - ttfb: Time to first byte in seconds - **kwargs: Additional attributes to add + span: The span to add attributes to. + service_name: Name of the LLM service (e.g., "openai"). + model: Model name/identifier. + stream: Whether streaming is enabled. + messages: JSON-serialized messages. + output: Aggregated output text from the LLM. + tools: JSON-serialized tools configuration. + tool_count: Number of tools available. + tool_choice: Tool selection configuration. + system: System message. + parameters: Service parameters. + extra_parameters: Additional parameters. + ttfb: Time to first byte in seconds. + **kwargs: Additional attributes to add. """ # Add standard attributes span.set_attribute("gen_ai.system", _get_gen_ai_system_from_service_name(service_name)) @@ -278,21 +289,21 @@ def add_gemini_live_span_attributes( """Add Gemini Live specific attributes to a span. Args: - span: The span to add attributes to - service_name: Name of the service - model: Model name/identifier - operation_name: Name of the operation (setup, model_turn, tool_call, etc.) - voice_id: Voice identifier used for output - language: Language code for the session - modalities: Supported modalities (e.g., "AUDIO", "TEXT") - settings: Service configuration settings - tools: Available tools/functions list - tools_serialized: JSON-serialized tools for detailed inspection - transcript: Transcription text - is_input: Whether transcript is input (True) or output (False) - text_output: Text output from model - audio_data_size: Size of audio data in bytes - **kwargs: Additional attributes to add + span: The span to add attributes to. + service_name: Name of the service. + model: Model name/identifier. + operation_name: Name of the operation (setup, model_turn, tool_call, etc.). + voice_id: Voice identifier used for output. + language: Language code for the session. + modalities: Supported modalities (e.g., "AUDIO", "TEXT"). + settings: Service configuration settings. + tools: Available tools/functions list. + tools_serialized: JSON-serialized tools for detailed inspection. + transcript: Transcription text. + is_input: Whether transcript is input (True) or output (False). + text_output: Text output from model. + audio_data_size: Size of audio data in bytes. + **kwargs: Additional attributes to add. """ # Add standard attributes span.set_attribute("gen_ai.system", "gcp.gemini") @@ -381,19 +392,19 @@ def add_openai_realtime_span_attributes( """Add OpenAI Realtime specific attributes to a span. Args: - span: The span to add attributes to - service_name: Name of the service - model: Model name/identifier - operation_name: Name of the operation (setup, transcription, response, etc.) - session_properties: Session configuration properties - transcript: Transcription text - is_input: Whether transcript is input (True) or output (False) - context_messages: JSON-serialized context messages - function_calls: Function calls being made - tools: Available tools/functions list - tools_serialized: JSON-serialized tools for detailed inspection - audio_data_size: Size of audio data in bytes - **kwargs: Additional attributes to add + span: The span to add attributes to. + service_name: Name of the service. + model: Model name/identifier. + operation_name: Name of the operation (setup, transcription, response, etc.). + session_properties: Session configuration properties. + transcript: Transcription text. + is_input: Whether transcript is input (True) or output (False). + context_messages: JSON-serialized context messages. + function_calls: Function calls being made. + tools: Available tools/functions list. + tools_serialized: JSON-serialized tools for detailed inspection. + audio_data_size: Size of audio data in bytes. + **kwargs: Additional attributes to add. """ # Add standard attributes span.set_attribute("gen_ai.system", "openai") diff --git a/src/pipecat/utils/tracing/service_decorators.py b/src/pipecat/utils/tracing/service_decorators.py index c016827d6..9078bba15 100644 --- a/src/pipecat/utils/tracing/service_decorators.py +++ b/src/pipecat/utils/tracing/service_decorators.py @@ -41,9 +41,15 @@ T = TypeVar("T") R = TypeVar("R") -# Internal helper functions def _noop_decorator(func): - """No-op fallback decorator when tracing is unavailable.""" + """No-op fallback decorator when tracing is unavailable. + + Args: + func: The function to pass through unchanged. + + Returns: + The original function unchanged. + """ return func @@ -53,10 +59,10 @@ def _get_parent_service_context(self): This looks for the service span that was created when the service was initialized. Args: - self: The service instance + self: The service instance. Returns: - Context or None: The parent service context, or None if unavailable + The parent service context, or None if unavailable. """ if not is_tracing_available(): return None @@ -73,8 +79,8 @@ def _add_token_usage_to_span(span, token_usage): """Add token usage metrics to a span (internal use only). Args: - span: The span to add token metrics to - token_usage: Dictionary or object containing token usage information + span: The span to add token metrics to. + token_usage: Dictionary or object containing token usage information. """ if not is_tracing_available() or not token_usage: return @@ -93,9 +99,10 @@ def _add_token_usage_to_span(span, token_usage): def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable: - """Traces TTS service methods with TTS-specific attributes. + """Trace TTS service methods with TTS-specific attributes. Automatically captures and records: + - Service name and model information - Voice ID and settings - Character count and text content @@ -118,7 +125,15 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) - @contextlib.asynccontextmanager async def tracing_context(self, text): - """Async context manager for TTS tracing.""" + """Async context manager for TTS tracing. + + Args: + self: The TTS service instance. + text: The text being synthesized. + + Yields: + The active span for the TTS operation. + """ if not is_tracing_available(): yield None return @@ -201,9 +216,10 @@ def traced_tts(func: Optional[Callable] = None, *, name: Optional[str] = None) - def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable: - """Traces STT service methods with transcription attributes. + """Trace STT service methods with transcription attributes. Automatically captures and records: + - Service name and model information - Transcription text and final status - Language information @@ -278,9 +294,10 @@ def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) - def traced_llm(func: Optional[Callable] = None, *, name: Optional[str] = None) -> Callable: - """Traces LLM service methods with LLM-specific attributes. + """Trace LLM service methods with LLM-specific attributes. Automatically captures and records: + - Service name and model information - Context content and messages - Tool configurations @@ -482,16 +499,17 @@ def traced_llm(func: Optional[Callable] = None, *, name: Optional[str] = None) - def traced_gemini_live(operation: str) -> Callable: - """Traces Gemini Live service methods with operation-specific attributes. + """Trace Gemini Live service methods with operation-specific attributes. This decorator automatically captures relevant information based on the operation type: + - llm_setup: Configuration, tools definitions, and system instructions - llm_tool_call: Function call information - llm_tool_result: Function execution results - llm_response: Complete LLM response with usage and output Args: - operation: The operation name (matches the event type being handled) + operation: The operation name (matches the event type being handled). Returns: Wrapped method with Gemini Live specific tracing. @@ -786,15 +804,16 @@ def traced_gemini_live(operation: str) -> Callable: def traced_openai_realtime(operation: str) -> Callable: - """Traces OpenAI Realtime service methods with operation-specific attributes. + """Trace OpenAI Realtime service methods with operation-specific attributes. This decorator automatically captures relevant information based on the operation type: + - llm_setup: Session configuration and tools - llm_request: Context and input messages - llm_response: Usage metadata, output, and function calls Args: - operation: The operation name (matches the event type being handled) + operation: The operation name (matches the event type being handled). Returns: Wrapped method with OpenAI Realtime specific tracing. diff --git a/src/pipecat/utils/tracing/setup.py b/src/pipecat/utils/tracing/setup.py index ab74530cb..f2dfa0c88 100644 --- a/src/pipecat/utils/tracing/setup.py +++ b/src/pipecat/utils/tracing/setup.py @@ -4,7 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # -"""Core OpenTelemetry tracing utilities and setup for Pipecat.""" +"""Core OpenTelemetry tracing utilities and setup for Pipecat. + +This module provides functions to check availability and configure OpenTelemetry +tracing for Pipecat applications. It handles the optional nature of OpenTelemetry +dependencies and provides a safe setup process. +""" import os @@ -21,10 +26,10 @@ except ImportError: def is_tracing_available() -> bool: - """Returns True if OpenTelemetry tracing is available and configured. + """Check if OpenTelemetry tracing is available and configured. Returns: - bool: True if tracing is available, False otherwise. + True if tracing is available, False otherwise. """ return OPENTELEMETRY_AVAILABLE @@ -37,15 +42,16 @@ def setup_tracing( """Set up OpenTelemetry tracing with a user-provided exporter. Args: - service_name: The name of the service for traces + service_name: The name of the service for traces. exporter: A pre-configured OpenTelemetry span exporter instance. If None, only console export will be available if enabled. - console_export: Whether to also export traces to console (useful for debugging) + console_export: Whether to also export traces to console (useful for debugging). Returns: - bool: True if setup was successful, False otherwise + True if setup was successful, False otherwise. + + Example:: - Example: # With OTLP exporter from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter diff --git a/src/pipecat/utils/tracing/turn_context_provider.py b/src/pipecat/utils/tracing/turn_context_provider.py index 7af3d694a..f02d92d45 100644 --- a/src/pipecat/utils/tracing/turn_context_provider.py +++ b/src/pipecat/utils/tracing/turn_context_provider.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Turn context provider for OpenTelemetry tracing in Pipecat. + +This module provides a singleton context provider that manages the current +turn's tracing context, allowing services to create child spans that are +properly associated with the conversation turn. +""" + from typing import TYPE_CHECKING, Optional # Import types for type checking only @@ -30,7 +37,11 @@ class TurnContextProvider: @classmethod def get_instance(cls): - """Get the singleton instance.""" + """Get the singleton instance. + + Returns: + The singleton TurnContextProvider instance. + """ if cls._instance is None: cls._instance = TurnContextProvider() return cls._instance @@ -60,7 +71,6 @@ class TurnContextProvider: return self._current_turn_context -# Create a simple helper function to get the current turn context def get_current_turn_context() -> Optional["Context"]: """Get the OpenTelemetry context for the current turn. diff --git a/src/pipecat/utils/tracing/turn_trace_observer.py b/src/pipecat/utils/tracing/turn_trace_observer.py index f67ca3b28..31b4d0130 100644 --- a/src/pipecat/utils/tracing/turn_trace_observer.py +++ b/src/pipecat/utils/tracing/turn_trace_observer.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Turn trace observer for OpenTelemetry tracing in Pipecat. + +This module provides an observer that creates trace spans for each conversation +turn, integrating with the turn tracking system to provide hierarchical tracing +of conversation flows. +""" + from typing import TYPE_CHECKING, Dict, Optional from loguru import logger @@ -41,6 +48,14 @@ class TurnTraceObserver(BaseObserver): additional_span_attributes: Optional[dict] = None, **kwargs, ): + """Initialize the turn trace observer. + + Args: + turn_tracker: The turn tracking observer to monitor. + conversation_id: Optional conversation ID for grouping turns. + additional_span_attributes: Additional attributes to add to spans. + **kwargs: Additional arguments passed to parent class. + """ super().__init__(**kwargs) self._turn_tracker = turn_tracker self._current_span: Optional["Span"] = None @@ -68,6 +83,9 @@ class TurnTraceObserver(BaseObserver): This observer doesn't need to process individual frames as it relies on turn start/end events from the turn tracker. + + Args: + data: The frame push event data. """ pass @@ -198,6 +216,9 @@ class TurnTraceObserver(BaseObserver): """Get the span context for the current turn. This can be used by services to create child spans. + + Returns: + The current turn's span context or None if not available. """ if not is_tracing_available() or not self._current_span: return None @@ -208,6 +229,12 @@ class TurnTraceObserver(BaseObserver): """Get the span context for a specific turn. This can be used by services to create child spans. + + Args: + turn_number: The turn number to get context for. + + Returns: + The specified turn's span context or None if not available. """ if not is_tracing_available(): return None diff --git a/src/pipecat/utils/utils.py b/src/pipecat/utils/utils.py index 0f4801f35..f741bc05b 100644 --- a/src/pipecat/utils/utils.py +++ b/src/pipecat/utils/utils.py @@ -4,6 +4,12 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Utility functions for object identification and counting. + +This module provides thread-safe utilities for generating unique identifiers +and maintaining per-class instance counts across the Pipecat framework. +""" + import collections import itertools import threading @@ -17,27 +23,40 @@ _ID_LOCK = threading.Lock() def obj_id() -> int: """Generate a unique id for an object. - >>> obj_id() - 0 - >>> obj_id() - 1 - >>> obj_id() - 2 + Returns: + A unique integer identifier that increments globally across all objects. + + Examples:: + + >>> obj_id() + 0 + >>> obj_id() + 1 + >>> obj_id() + 2 """ with _ID_LOCK: return next(_ID) def obj_count(obj) -> int: - """Generate a unique id for an object. + """Generate a unique count for an object based on its class. - >>> obj_count(object()) - 0 - >>> obj_count(object()) - 1 - >>> new_type = type('NewType', (object,), {}) - >>> obj_count(new_type()) - 0 + Args: + obj: The object instance to count. + + Returns: + A unique integer count that increments per class type. + + Examples:: + + >>> obj_count(object()) + 0 + >>> obj_count(object()) + 1 + >>> new_type = type('NewType', (object,), {}) + >>> obj_count(new_type()) + 0 """ with _COUNTS_LOCK: return next(_COUNTS[obj.__class__.__name__]) From 0968f36d3ebfea43f5f1958a54d3de65c0579507 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 1 Jul 2025 09:51:02 -0400 Subject: [PATCH 16/84] fix: remove javascript directory from the websocket README --- examples/websocket/client/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/websocket/client/README.md b/examples/websocket/client/README.md index 753c6d563..f18fce022 100644 --- a/examples/websocket/client/README.md +++ b/examples/websocket/client/README.md @@ -6,10 +6,10 @@ Basic implementation using the [Pipecat JavaScript SDK](https://docs.pipecat.ai/ 1. Run the bot server. See the [server README](../README). -2. Navigate to the `client/javascript` directory: +2. Navigate to the `client` directory: ```bash -cd client/javascript +cd client ``` 3. Install dependencies: From d50e6db3126b339be2bd7187acdb12796b304c20 Mon Sep 17 00:00:00 2001 From: Paul Kompfner Date: Tue, 1 Jul 2025 14:24:27 -0400 Subject: [PATCH 17/84] =?UTF-8?q?Whoops=E2=80=94fix=20mistake=20in=20CHANG?= =?UTF-8?q?ELOG=20(`FlowsFunctionSchema`=20->=20`FunctionSchema`)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d200d58b8..834faaa94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,10 +10,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Added support for providing "direct" functions, which don't need an - accompanying `FlowsFunctionSchema` or function definition dict. Instead, - metadata (i.e. `name`, `description`, `properties`, and `required`) are - automatically extracted from a combination of the function signature and - docstring. + accompanying `FunctionSchema` or function definition dict. Instead, metadata + (i.e. `name`, `description`, `properties`, and `required`) are automatically + extracted from a combination of the function signature and docstring. Usage: From 58675f4d5a042de7bb26561c58fcddda4027a30e Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Tue, 1 Jul 2025 11:50:12 -0700 Subject: [PATCH 18/84] renamed clean schema to alternate schema --- .../services/gemini_multimodal_live/gemini.py | 4 +-- src/pipecat/services/google/llm.py | 4 +-- src/pipecat/services/llm_service.py | 4 +-- src/pipecat/services/mcp_service.py | 36 +++++++++---------- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index f9584df9d..ec33eb7b4 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -524,8 +524,8 @@ class GeminiMultimodalLiveLLMService(LLMService): """ return True - def needs_mcp_clean_schema(self) -> bool: - """Check if this LLM service requires MCP schema cleaning. + def needs_mcp_alternate_schema(self) -> bool: + """Check if this LLM service requires alternate MCP schema. Google/Gemini has stricter JSON schema validation and requires certain properties to be removed or modified for compatibility. diff --git a/src/pipecat/services/google/llm.py b/src/pipecat/services/google/llm.py index e36c6591e..ed4939bfb 100644 --- a/src/pipecat/services/google/llm.py +++ b/src/pipecat/services/google/llm.py @@ -631,8 +631,8 @@ class GoogleLLMService(LLMService): """ return True - def needs_mcp_clean_schema(self) -> bool: - """Check if this LLM service requires MCP schema cleaning. + def needs_mcp_alternate_schema(self) -> bool: + """Check if this LLM service requires alternate MCP schema. Google/Gemini has stricter JSON schema validation and requires certain properties to be removed or modified for compatibility. diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index 24ed932d8..ec4ee9eec 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -307,8 +307,8 @@ class LLMService(AIService): return True return function_name in self._functions.keys() - def needs_mcp_clean_schema(self) -> bool: - """Check if this LLM service requires MCP schema cleaning. + def needs_mcp_alternate_schema(self) -> bool: + """Check if this LLM service requires alternate MCP schema. Some LLM services have stricter JSON schema validation and require certain properties to be removed or modified for compatibility. diff --git a/src/pipecat/services/mcp_service.py b/src/pipecat/services/mcp_service.py index 3d757e32e..c165b96fa 100644 --- a/src/pipecat/services/mcp_service.py +++ b/src/pipecat/services/mcp_service.py @@ -51,7 +51,7 @@ class MCPClient(BaseObject): super().__init__(**kwargs) self._server_params = server_params self._session = ClientSession - self._needs_schema_cleaning = False + self._needs_alternate_schema = False if isinstance(server_params, StdioServerParameters): self._client = stdio_client @@ -79,47 +79,47 @@ class MCPClient(BaseObject): Returns: A ToolsSchema containing all successfully registered tools. """ - # Check once if the LLM needs schema cleaning - self._needs_schema_cleaning = llm and llm.needs_mcp_clean_schema() + # Check once if the LLM needs alternate strict schema + self._needs_alternate_schema = llm and llm.needs_mcp_alternate_schema() tools_schema = await self._register_tools(llm) return tools_schema - def _clean_schema_for_strict_validation(self, schema: Dict[str, Any]) -> Dict[str, Any]: - """Clean a JSON schema to be compatible with LLMs that have strict validation. + def _get_alternate_schema_for_strict_validation(self, schema: Dict[str, Any]) -> Dict[str, Any]: + """Get an alternate JSON schema to be compatible with LLMs that have strict validation. Some LLMs have stricter validation and don't allow certain schema properties that are valid in standard JSON Schema. Args: - schema: The JSON schema to clean + schema: The JSON schema to get an alternate schema for Returns: - A cleaned schema compatible with strict validation + An alternate schema compatible with strict validation """ if not isinstance(schema, dict): return schema - cleaned = {} + alternate_schema = {} for key, value in schema.items(): # Skip additionalProperties as some LLMs don't like additionalProperties: false if key == "additionalProperties": continue - # Recursively clean nested objects + # Recursively get alternate schema for nested objects if isinstance(value, dict): - cleaned[key] = self._clean_schema_for_strict_validation(value) + alternate_schema[key] = self._get_alternate_schema_for_strict_validation(value) elif isinstance(value, list): - cleaned[key] = [ - self._clean_schema_for_strict_validation(item) + alternate_schema[key] = [ + self._get_alternate_schema_for_strict_validation(item) if isinstance(item, dict) else item for item in value ] else: - cleaned[key] = value + alternate_schema[key] = value - return cleaned + return alternate_schema def _convert_mcp_schema_to_pipecat( self, tool_name: str, tool_schema: Dict[str, Any] @@ -138,10 +138,10 @@ class MCPClient(BaseObject): properties = tool_schema["input_schema"].get("properties", {}) required = tool_schema["input_schema"].get("required", []) - # Only clean properties for LLMs that need strict schema validation - if self._needs_schema_cleaning: - logger.debug("Cleaning schema for strict validation") - properties = self._clean_schema_for_strict_validation(properties) + # Only get alternate schema for LLMs that need strict schema validation + if self._needs_alternate_schema: + logger.debug("Getting alternate schema for strict validation") + properties = self._get_alternate_schema_for_strict_validation(properties) schema = FunctionSchema( name=tool_name, From cc637f4dea1b73f3020d3cc97bfa36e02469f683 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 1 Jul 2025 15:22:30 -0400 Subject: [PATCH 19/84] Clean up docstrings after DirectFunction merge (#2105) * Add missing import for FunctionCallParams * Update docstrings in direct_function * Docstring fixes for run.py * Remove unused imports in llm_service * Add missing docstrings to llm_service * Remove FunctionCallParams import * Wording improvements * Type checking for FunctionCallParams --- .../adapters/schemas/direct_function.py | 120 ++++++++++++++---- src/pipecat/examples/run.py | 29 +++++ src/pipecat/services/llm_service.py | 25 ++-- 3 files changed, 139 insertions(+), 35 deletions(-) diff --git a/src/pipecat/adapters/schemas/direct_function.py b/src/pipecat/adapters/schemas/direct_function.py index 54763c3d8..e300eff81 100644 --- a/src/pipecat/adapters/schemas/direct_function.py +++ b/src/pipecat/adapters/schemas/direct_function.py @@ -1,6 +1,22 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Direct function wrapper utilities for LLM function calling. + +This module provides utilities for wrapping "direct" functions that handle LLM +function calls. Direct functions have their metadata automatically extracted +from function signatures and docstrings, allowing them to be used without +accompanying configurations (as FunctionSchemas or in provider-specific +formats). +""" + import inspect import types from typing import ( + TYPE_CHECKING, Any, Callable, Dict, @@ -19,6 +35,9 @@ import docstring_parser from pipecat.adapters.schemas.function_schema import FunctionSchema +if TYPE_CHECKING: + from pipecat.services.llm_service import FunctionCallParams + class DirectFunction(Protocol): """Protocol for a "direct" function that handles LLM function calls. @@ -28,30 +47,58 @@ class DirectFunction(Protocol): `FunctionSchema`s or in provider-specific formats). """ - async def __call__(self, params: "FunctionCallParams", **kwargs: Any) -> None: ... + async def __call__(self, params: "FunctionCallParams", **kwargs: Any) -> None: + """Execute the direct function. + + Args: + params: Function call parameters from the LLM service. + **kwargs: Additional keyword arguments passed to the function. + """ + ... class BaseDirectFunctionWrapper: - """ - Base class for a wrapper around a DirectFunction that: - - extracts metadata from the function signature and docstring - - using that metadata, generates a corresponding FunctionSchema - """ + """Base class for a wrapper around a DirectFunction. - @classmethod - def special_first_param_name(cls) -> str: - """The name of the "special" first function parameter that is ignored by the metadata - extraction, as it's not relevant to the LLM. - """ - raise NotImplementedError("Subclasses must define the special first parameter name.") + Provides functionality to: + + - extract metadata from the function signature and docstring + - use that metadata to generate a corresponding FunctionSchema + """ def __init__(self, function: Callable): + """Initialize the direct function wrapper. + + Args: + function: The function to wrap and extract metadata from. + """ self.__class__.validate_function(function) self.function = function self._initialize_metadata() + @classmethod + def special_first_param_name(cls) -> str: + """Get the name of the special first function parameter. + + The special first parameter is ignored by metadata extraction as it's + not relevant to the LLM (e.g., 'params' for FunctionCallParams). + + Returns: + The name of the special first parameter. + """ + raise NotImplementedError("Subclasses must define the special first parameter name.") + @classmethod def validate_function(cls, function: Callable) -> None: + """Validate that the function meets direct function requirements. + + Args: + function: The function to validate. + + Raises: + Exception: If function doesn't meet requirements (not async, missing + parameters, incorrect first parameter name). + """ if not inspect.iscoroutinefunction(function): raise Exception(f"Direct function {function.__name__} must be async") params = list(inspect.signature(function).parameters.items()) @@ -67,6 +114,11 @@ class BaseDirectFunctionWrapper: ) def to_function_schema(self) -> FunctionSchema: + """Convert the wrapped function to a FunctionSchema. + + Returns: + A FunctionSchema instance with extracted metadata. + """ return FunctionSchema( name=self.name, description=self.description, @@ -75,6 +127,7 @@ class BaseDirectFunctionWrapper: ) def _initialize_metadata(self): + """Initialize metadata from function signature and docstring.""" # Get function name self.name = self.function.__name__ @@ -93,20 +146,20 @@ class BaseDirectFunctionWrapper: def _get_parameters_as_jsonschema( self, func: Callable, docstring_params: List[docstring_parser.DocstringParam] ) -> Tuple[Dict[str, Any], List[str]]: - """ - Get function parameters as a dictionary of JSON schemas and a list of required parameters. + """Get function parameters as a dictionary of JSON schemas and a list of required parameters. + Ignore the first parameter, as it's expected to be the "special" one. Args: - func: Function to get parameters from - docstring_params: List of parameters extracted from the function's docstring + func: Function to get parameters from. + docstring_params: List of parameters extracted from the function's docstring. Returns: A tuple containing: - - A dictionary mapping each function parameter to its JSON schema - - A list of required parameter names - """ + - A dictionary mapping each function parameter to its JSON schema + - A list of required parameter names + """ sig = inspect.signature(func) hints = get_type_hints(func) properties = {} @@ -141,8 +194,7 @@ class BaseDirectFunctionWrapper: return properties, required def _typehint_to_jsonschema(self, type_hint: Any) -> Dict[str, Any]: - """ - Convert a Python type hint to a JSON Schema. + """Convert a Python type hint to a JSON Schema. Args: type_hint: A Python type hint @@ -213,16 +265,32 @@ class BaseDirectFunctionWrapper: class DirectFunctionWrapper(BaseDirectFunctionWrapper): - """ - Wrapper around a DirectFunction that: - - extracts metadata from the function signature and docstring - - generates a corresponding FunctionSchema - - helps with function invocation + """Wrapper around a DirectFunction for LLM function calling. + + This class: + + - Extracts metadata from the function signature and docstring + - Generates a corresponding FunctionSchema + - Helps with function invocation """ @classmethod def special_first_param_name(cls) -> str: + """Get the special first parameter name for direct functions. + + Returns: + The string "params" which is expected as the first parameter. + """ return "params" async def invoke(self, args: Mapping[str, Any], params: "FunctionCallParams"): + """Invoke the wrapped function with the provided arguments. + + Args: + args: Arguments to pass to the function. + params: Function call parameters from the LLM service. + + Returns: + The result of the function call. + """ return await self.function(params=params, **args) diff --git a/src/pipecat/examples/run.py b/src/pipecat/examples/run.py index 60cb3b5c6..be2834a28 100644 --- a/src/pipecat/examples/run.py +++ b/src/pipecat/examples/run.py @@ -93,6 +93,15 @@ async def maybe_capture_participant_screen( def smallwebrtc_sdp_cleanup_ice_candidates(text: str, pattern: str) -> str: + """Clean up ICE candidates in SDP text for SmallWebRTC. + + Args: + text: SDP text to clean up. + pattern: Pattern to match for candidate filtering. + + Returns: + Cleaned SDP text with filtered ICE candidates. + """ result = [] lines = text.splitlines() for line in lines: @@ -105,6 +114,14 @@ def smallwebrtc_sdp_cleanup_ice_candidates(text: str, pattern: str) -> str: def smallwebrtc_sdp_cleanup_fingerprints(text: str) -> str: + """Remove unsupported fingerprint algorithms from SDP text. + + Args: + text: SDP text to clean up. + + Returns: + SDP text with sha-384 and sha-512 fingerprints removed. + """ result = [] lines = text.splitlines() for line in lines: @@ -114,6 +131,15 @@ def smallwebrtc_sdp_cleanup_fingerprints(text: str) -> str: def smallwebrtc_sdp_munging(sdp: str, host: str) -> str: + """Apply SDP modifications for SmallWebRTC compatibility. + + Args: + sdp: Original SDP string. + host: Host address for ICE candidate filtering. + + Returns: + Modified SDP string with fingerprint and ICE candidate cleanup. + """ sdp = smallwebrtc_sdp_cleanup_fingerprints(sdp) sdp = smallwebrtc_sdp_cleanup_ice_candidates(sdp, host) return sdp @@ -232,6 +258,9 @@ def run_example_webrtc( Args: app: The FastAPI application instance. + + Yields: + Control to the FastAPI application runtime. """ yield # Run app coros = [pc.disconnect() for pc in pcs_map.values()] diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index 98c8483fe..51a5688f9 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -8,28 +8,19 @@ import asyncio import inspect -import types from dataclasses import dataclass from typing import ( Any, Awaitable, Callable, Dict, - List, Mapping, Optional, Protocol, Sequence, - Set, - Tuple, Type, - Union, - get_args, - get_origin, - get_type_hints, ) -import docstring_parser from loguru import logger from pipecat.adapters.base_llm_adapter import BaseLLMAdapter @@ -312,6 +303,17 @@ class LLMService(AIService): *, cancel_on_interruption: bool = True, ): + """Register a direct function handler for LLM function calls. + + Direct functions have their metadata automatically extracted from their + signature and docstring, eliminating the need for accompanying + configurations (as FunctionSchemas or in provider-specific formats). + + Args: + handler: The direct function to register. Must follow DirectFunction protocol. + cancel_on_interruption: Whether to cancel this function call when an + interruption occurs. Defaults to True. + """ wrapper = DirectFunctionWrapper(handler) self._functions[wrapper.name] = FunctionCallRegistryItem( function_name=wrapper.name, @@ -330,6 +332,11 @@ class LLMService(AIService): del self._start_callbacks[function_name] def unregister_direct_function(self, handler: Any): + """Remove a registered direct function handler. + + Args: + handler: The direct function handler to remove. + """ wrapper = DirectFunctionWrapper(handler) del self._functions[wrapper.name] # Note: no need to remove start callback here, as direct functions don't support start callbacks. From f6112713e84ce89fab7b90f92882cef4542b3aca Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 1 Jul 2025 10:29:20 -0700 Subject: [PATCH 20/84] Add user_id to TranscriptionFrame and InterimTranscriptionFrame pushed by STTServices --- CHANGELOG.md | 6 ++++++ src/pipecat/services/assemblyai/stt.py | 4 ++-- src/pipecat/services/aws/stt.py | 4 ++-- src/pipecat/services/azure/stt.py | 2 +- src/pipecat/services/cartesia/stt.py | 14 ++++++++++++-- src/pipecat/services/deepgram/stt.py | 4 ++-- src/pipecat/services/fal/stt.py | 2 +- src/pipecat/services/gladia/stt.py | 4 ++-- src/pipecat/services/google/stt.py | 4 ++-- src/pipecat/services/riva/stt.py | 9 ++++++--- src/pipecat/services/stt_service.py | 22 ++++++++++++++++++++++ src/pipecat/services/whisper/base_stt.py | 6 +++++- src/pipecat/services/whisper/stt.py | 14 ++++++++++++-- 13 files changed, 75 insertions(+), 20 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 834faaa94..f3c683b8b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +<<<<<<< HEAD - Added support for providing "direct" functions, which don't need an accompanying `FunctionSchema` or function definition dict. Instead, metadata (i.e. `name`, `description`, `properties`, and `required`) are automatically @@ -39,6 +40,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 tools = ToolsSchema(standard_tools=[do_something]) ``` +======= +- `user_id` is now populated in the `TranscriptionFrame` and + `InterimTranscriptionFrame` when using a service that provides a `user_id`, + like `DailyTransport` or `LiveKitTransport`. +>>>>>>> 5f958226 (Add user_id to TranscriptionFrame and InterimTranscriptionFrame pushed by STTServices) - Added `watchdog_coroutine()`. This is a watchdog helper for couroutines. So, if you have a coroutine that is waiting for a result and that takes a long diff --git a/src/pipecat/services/assemblyai/stt.py b/src/pipecat/services/assemblyai/stt.py index 0e7103885..5d8a596ca 100644 --- a/src/pipecat/services/assemblyai/stt.py +++ b/src/pipecat/services/assemblyai/stt.py @@ -311,7 +311,7 @@ class AssemblyAISTTService(STTService): await self.push_frame( TranscriptionFrame( message.transcript, - "", # participant + self._user_id, time_now_iso8601(), self._language, message, @@ -323,7 +323,7 @@ class AssemblyAISTTService(STTService): await self.push_frame( InterimTranscriptionFrame( message.transcript, - "", # participant + self._user_id, time_now_iso8601(), self._language, message, diff --git a/src/pipecat/services/aws/stt.py b/src/pipecat/services/aws/stt.py index a7f8fea97..22e8c8e63 100644 --- a/src/pipecat/services/aws/stt.py +++ b/src/pipecat/services/aws/stt.py @@ -366,7 +366,7 @@ class AWSTranscribeSTTService(STTService): await self.push_frame( TranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), self._settings["language"], result=result, @@ -382,7 +382,7 @@ class AWSTranscribeSTTService(STTService): await self.push_frame( InterimTranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), self._settings["language"], result=result, diff --git a/src/pipecat/services/azure/stt.py b/src/pipecat/services/azure/stt.py index 415f91550..6965ba188 100644 --- a/src/pipecat/services/azure/stt.py +++ b/src/pipecat/services/azure/stt.py @@ -183,7 +183,7 @@ class AzureSTTService(STTService): language = getattr(event.result, "language", None) or self._settings.get("language") frame = TranscriptionFrame( event.result.text, - "", + self._user_id, time_now_iso8601(), language, result=event, diff --git a/src/pipecat/services/cartesia/stt.py b/src/pipecat/services/cartesia/stt.py index 5ca9cce0f..50d42e467 100644 --- a/src/pipecat/services/cartesia/stt.py +++ b/src/pipecat/services/cartesia/stt.py @@ -289,14 +289,24 @@ class CartesiaSTTService(STTService): await self.stop_ttfb_metrics() if is_final: await self.push_frame( - TranscriptionFrame(transcript, "", time_now_iso8601(), language) + TranscriptionFrame( + transcript, + self._user_id, + time_now_iso8601(), + language, + ) ) await self._handle_transcription(transcript, is_final, language) await self.stop_processing_metrics() else: # For interim transcriptions, just push the frame without tracing await self.push_frame( - InterimTranscriptionFrame(transcript, "", time_now_iso8601(), language) + InterimTranscriptionFrame( + transcript, + self._user_id, + time_now_iso8601(), + language, + ) ) async def _disconnect(self): diff --git a/src/pipecat/services/deepgram/stt.py b/src/pipecat/services/deepgram/stt.py index d897d8c92..d30e4da39 100644 --- a/src/pipecat/services/deepgram/stt.py +++ b/src/pipecat/services/deepgram/stt.py @@ -278,7 +278,7 @@ class DeepgramSTTService(STTService): await self.push_frame( TranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), language, result=result, @@ -291,7 +291,7 @@ class DeepgramSTTService(STTService): await self.push_frame( InterimTranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), language, result=result, diff --git a/src/pipecat/services/fal/stt.py b/src/pipecat/services/fal/stt.py index 3485a7de1..202c03c1b 100644 --- a/src/pipecat/services/fal/stt.py +++ b/src/pipecat/services/fal/stt.py @@ -291,7 +291,7 @@ class FalSTTService(SegmentedSTTService): logger.debug(f"Transcription: [{text}]") yield TranscriptionFrame( text, - "", + self._user_id, time_now_iso8601(), Language(self._settings["language"]), result=response, diff --git a/src/pipecat/services/gladia/stt.py b/src/pipecat/services/gladia/stt.py index c436a7ea9..f931993b3 100644 --- a/src/pipecat/services/gladia/stt.py +++ b/src/pipecat/services/gladia/stt.py @@ -567,7 +567,7 @@ class GladiaSTTService(STTService): await self.push_frame( TranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), language, result=content, @@ -582,7 +582,7 @@ class GladiaSTTService(STTService): await self.push_frame( InterimTranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), language, result=content, diff --git a/src/pipecat/services/google/stt.py b/src/pipecat/services/google/stt.py index e94fbbb12..9cd2ac3ae 100644 --- a/src/pipecat/services/google/stt.py +++ b/src/pipecat/services/google/stt.py @@ -862,7 +862,7 @@ class GoogleSTTService(STTService): await self.push_frame( TranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), primary_language, result=result, @@ -880,7 +880,7 @@ class GoogleSTTService(STTService): await self.push_frame( InterimTranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), primary_language, result=result, diff --git a/src/pipecat/services/riva/stt.py b/src/pipecat/services/riva/stt.py index ba8750f91..a7d114a12 100644 --- a/src/pipecat/services/riva/stt.py +++ b/src/pipecat/services/riva/stt.py @@ -314,7 +314,7 @@ class RivaSTTService(STTService): await self.push_frame( TranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), self._language_code, result=result, @@ -329,7 +329,7 @@ class RivaSTTService(STTService): await self.push_frame( InterimTranscriptionFrame( transcript, - "", + self._user_id, time_now_iso8601(), self._language_code, result=result, @@ -636,7 +636,10 @@ class RivaSegmentedSTTService(SegmentedSTTService): if text: logger.debug(f"Transcription: [{text}]") yield TranscriptionFrame( - text, "", time_now_iso8601(), self._language_enum + text, + self._user_id, + time_now_iso8601(), + self._language_enum, ) transcription_found = True diff --git a/src/pipecat/services/stt_service.py b/src/pipecat/services/stt_service.py index db777c77f..5aebe10f3 100644 --- a/src/pipecat/services/stt_service.py +++ b/src/pipecat/services/stt_service.py @@ -57,6 +57,7 @@ class STTService(AIService): self._sample_rate = 0 self._settings: Dict[str, Any] = {} self._muted: bool = False + self._user_id: str = "" @property def is_muted(self) -> bool: @@ -132,6 +133,11 @@ class STTService(AIService): async def process_audio_frame(self, frame: AudioRawFrame, direction: FrameDirection): """Process an audio frame for speech recognition. + If the service is muted, this method does nothing. Otherwise, it + processes the audio frame and runs speech-to-text on it, yielding + transcription results. If the frame has a user_id, it is stored + for later use in transcription. + Args: frame: The audio frame to process. direction: The direction of frame processing. @@ -139,6 +145,13 @@ class STTService(AIService): if self._muted: return + # UserAudioRawFrame contains a user_id (e.g. Daily, Livekit) + if hasattr(frame, "user_id"): + self._user_id = frame.user_id + # AudioRawFrame does not have a user_id (e.g. SmallWebRTCTransport, websockets) + else: + self._user_id = "" + await self.process_generator(self.run_stt(frame.audio)) async def process_frame(self, frame: Frame, direction: FrameDirection): @@ -241,10 +254,19 @@ class SegmentedSTTService(STTService): Continuously buffers audio, growing the buffer while user is speaking and maintaining a small buffer when not speaking to account for VAD delay. + If the frame has a user_id, it is stored for later use in transcription. + Args: frame: The audio frame to process. direction: The direction of frame processing. """ + # UserAudioRawFrame contains a user_id (e.g. Daily, Livekit) + if hasattr(frame, "user_id"): + self._user_id = frame.user_id + # AudioRawFrame does not have a user_id (e.g. SmallWebRTCTransport, websockets) + else: + self._user_id = "" + # If the user is speaking the audio buffer will keep growing. self._audio_buffer += frame.audio diff --git a/src/pipecat/services/whisper/base_stt.py b/src/pipecat/services/whisper/base_stt.py index 6f8ac26f2..a7dc6244c 100644 --- a/src/pipecat/services/whisper/base_stt.py +++ b/src/pipecat/services/whisper/base_stt.py @@ -219,7 +219,11 @@ class BaseWhisperSTTService(SegmentedSTTService): if text: await self._handle_transcription(text, True, self._language) logger.debug(f"Transcription: [{text}]") - yield TranscriptionFrame(text, "", time_now_iso8601()) + yield TranscriptionFrame( + text, + self._user_id, + time_now_iso8601(), + ) else: logger.warning("Received empty transcription from API") diff --git a/src/pipecat/services/whisper/stt.py b/src/pipecat/services/whisper/stt.py index ace18ab56..559c0a1e1 100644 --- a/src/pipecat/services/whisper/stt.py +++ b/src/pipecat/services/whisper/stt.py @@ -395,7 +395,12 @@ class WhisperSTTService(SegmentedSTTService): if text: await self._handle_transcription(text, True, self._settings["language"]) logger.debug(f"Transcription: [{text}]") - yield TranscriptionFrame(text, "", time_now_iso8601(), self._settings["language"]) + yield TranscriptionFrame( + text, + self._user_id, + time_now_iso8601(), + self._settings["language"], + ) class WhisperSTTServiceMLX(WhisperSTTService): @@ -500,7 +505,12 @@ class WhisperSTTServiceMLX(WhisperSTTService): if text: await self._handle_transcription(text, True, self._settings["language"]) logger.debug(f"Transcription: [{text}]") - yield TranscriptionFrame(text, "", time_now_iso8601(), self._settings["language"]) + yield TranscriptionFrame( + text, + self._user_id, + time_now_iso8601(), + self._settings["language"], + ) except Exception as e: logger.exception(f"MLX Whisper transcription error: {e}") From 8cbce555e423e490753ff790febc3b99b789d63b Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Tue, 1 Jul 2025 11:09:57 -0700 Subject: [PATCH 21/84] Add user_id to stt_traced decorator --- CHANGELOG.md | 10 ++++------ src/pipecat/utils/tracing/service_attributes.py | 5 +++++ src/pipecat/utils/tracing/service_decorators.py | 1 + 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3c683b8b..f1e873569 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -<<<<<<< HEAD - Added support for providing "direct" functions, which don't need an accompanying `FunctionSchema` or function definition dict. Instead, metadata (i.e. `name`, `description`, `properties`, and `required`) are automatically @@ -40,11 +39,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 tools = ToolsSchema(standard_tools=[do_something]) ``` -======= -- `user_id` is now populated in the `TranscriptionFrame` and - `InterimTranscriptionFrame` when using a service that provides a `user_id`, - like `DailyTransport` or `LiveKitTransport`. ->>>>>>> 5f958226 (Add user_id to TranscriptionFrame and InterimTranscriptionFrame pushed by STTServices) + + - `user_id` is now populated in the `TranscriptionFrame` and + `InterimTranscriptionFrame` when using a transport that provides a + `user_id`, like `DailyTransport` or `LiveKitTransport`. - Added `watchdog_coroutine()`. This is a watchdog helper for couroutines. So, if you have a coroutine that is waiting for a result and that takes a long diff --git a/src/pipecat/utils/tracing/service_attributes.py b/src/pipecat/utils/tracing/service_attributes.py index 3896bd028..fa9d21904 100644 --- a/src/pipecat/utils/tracing/service_attributes.py +++ b/src/pipecat/utils/tracing/service_attributes.py @@ -125,6 +125,7 @@ def add_stt_span_attributes( transcript: Optional[str] = None, is_final: Optional[bool] = None, language: Optional[str] = None, + user_id: Optional[str] = None, settings: Optional[Dict[str, Any]] = None, vad_enabled: bool = False, ttfb: Optional[float] = None, @@ -140,6 +141,7 @@ def add_stt_span_attributes( transcript: The transcribed text. is_final: Whether this is a final transcript. language: Detected or configured language. + user_id: User ID associated with the audio being transcribed. settings: Service configuration settings. vad_enabled: Whether voice activity detection is enabled. ttfb: Time to first byte in seconds. @@ -161,6 +163,9 @@ def add_stt_span_attributes( if language: span.set_attribute("language", language) + if user_id: + span.set_attribute("user_id", user_id) + if ttfb is not None: span.set_attribute("metrics.ttfb", ttfb) diff --git a/src/pipecat/utils/tracing/service_decorators.py b/src/pipecat/utils/tracing/service_decorators.py index 9078bba15..c5612d2b2 100644 --- a/src/pipecat/utils/tracing/service_decorators.py +++ b/src/pipecat/utils/tracing/service_decorators.py @@ -270,6 +270,7 @@ def traced_stt(func: Optional[Callable] = None, *, name: Optional[str] = None) - transcript=transcript, is_final=is_final, language=str(language) if language else None, + user_id=getattr(self, "_user_id", None), vad_enabled=getattr(self, "vad_enabled", False), settings=settings, ttfb=ttfb, From 5310d903eca69062932d8ff23954ffc16fbb2799 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Tue, 1 Jul 2025 17:04:27 -0300 Subject: [PATCH 22/84] Adding the requirements and needed variables for the freeze-test example. --- examples/freeze-test/client/src/app.ts | 12 ++++++- examples/freeze-test/env.example | 4 +++ examples/freeze-test/freeze_test_bot.py | 45 ++++++++++++++++++++++--- examples/freeze-test/requirements.txt | 4 +++ 4 files changed, 60 insertions(+), 5 deletions(-) create mode 100644 examples/freeze-test/env.example create mode 100644 examples/freeze-test/requirements.txt diff --git a/examples/freeze-test/client/src/app.ts b/examples/freeze-test/client/src/app.ts index 2e8315539..7b565ea71 100644 --- a/examples/freeze-test/client/src/app.ts +++ b/examples/freeze-test/client/src/app.ts @@ -191,7 +191,17 @@ class WebsocketClientApp { const startTime = Date.now(); this.recordingSerializer = new RecordingSerializer() - const transport = this.ENABLE_RECORDING_MODE ? new WebSocketTransport({serializer: this.recordingSerializer}) : new WebSocketTransport(); + const transport = this.ENABLE_RECORDING_MODE ? + new WebSocketTransport({ + serializer: this.recordingSerializer, + recorderSampleRate: 8000, + playerSampleRate:8000 + }) : + new WebSocketTransport({ + serializer: new ProtobufFrameSerializer(), + recorderSampleRate: 8000, + playerSampleRate:8000 + }); this.websocketTransport = transport const RTVIConfig: RTVIClientOptions = { diff --git a/examples/freeze-test/env.example b/examples/freeze-test/env.example new file mode 100644 index 000000000..7a94b2eee --- /dev/null +++ b/examples/freeze-test/env.example @@ -0,0 +1,4 @@ +SENTRY_DSN= +DEEPGRAM_API_KEY= +CARTESIA_API_KEY= +OPENAI_API_KEY= \ No newline at end of file diff --git a/examples/freeze-test/freeze_test_bot.py b/examples/freeze-test/freeze_test_bot.py index 52ef5fc89..8ce3df17a 100644 --- a/examples/freeze-test/freeze_test_bot.py +++ b/examples/freeze-test/freeze_test_bot.py @@ -18,7 +18,6 @@ from fastapi import FastAPI, Request, WebSocket from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import RedirectResponse from loguru import logger -from pipecat_ai_small_webrtc_prebuilt.frontend import SmallWebRTCPrebuiltUI from pipecat.audio.vad.silero import SileroVADAnalyzer from pipecat.frames.frames import ( @@ -27,11 +26,13 @@ from pipecat.frames.frames import ( Frame, InterimTranscriptionFrame, LLMFullResponseEndFrame, + LLMMessagesFrame, StartFrame, StartInterruptionFrame, StopFrame, StopInterruptionFrame, TranscriptionFrame, + TTSSpeakFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, ) @@ -47,6 +48,7 @@ from pipecat.processors.aggregators.openai_llm_context import ( from pipecat.processors.frame_processor import FrameDirection, FrameProcessor from pipecat.processors.frameworks.rtvi import RTVIConfig, RTVIProcessor from pipecat.processors.metrics.sentry import SentryMetrics +from pipecat.processors.user_idle_processor import UserIdleProcessor from pipecat.serializers.protobuf import ProtobufFrameSerializer from pipecat.services.cartesia.tts import CartesiaTTSService from pipecat.services.deepgram.stt import DeepgramSTTService @@ -78,9 +80,6 @@ app.add_middleware( allow_headers=["*"], ) -# Mount the frontend at / -app.mount("/client", SmallWebRTCPrebuiltUI) - class SimulateFreezeInput(FrameProcessor): def __init__( @@ -188,6 +187,37 @@ async def run_example(websocket_client): stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY")) + async def handle_user_idle(user_idle: UserIdleProcessor, retry_count: int) -> bool: + if retry_count == 1: + # First attempt: Add a gentle prompt to the conversation + messages.append( + { + "role": "system", + "content": "The user has been quiet. Politely and briefly ask if they're still there.", + } + ) + await user_idle.push_frame(LLMMessagesFrame(messages)) + return True + elif retry_count == 2: + # Second attempt: More direct prompt + messages.append( + { + "role": "system", + "content": "The user is still inactive. Ask if they'd like to continue our conversation.", + } + ) + await user_idle.push_frame(LLMMessagesFrame(messages)) + return True + else: + # Third attempt: End the conversation + await user_idle.push_frame( + TTSSpeakFrame("It seems like you're busy right now. Have a nice day!") + ) + await task.queue_frame(EndFrame()) + return False + + user_idle = UserIdleProcessor(callback=handle_user_idle, timeout=10.0) + tts = CartesiaTTSService( api_key=os.getenv("CARTESIA_API_KEY"), voice_id="71a7ad14-091c-4e8e-a314-022ece01c121", # British Reading Lady @@ -222,6 +252,7 @@ async def run_example(websocket_client): stt, ], ), + user_idle, rtvi, context_aggregator.user(), # User responses llm, # LLM @@ -238,6 +269,8 @@ async def run_example(websocket_client): enable_metrics=True, enable_usage_metrics=True, report_only_initial_ttfb=True, + audio_in_sample_rate=8000, + audio_out_sample_rate=8000, ), idle_timeout_secs=120, observers=[ @@ -249,6 +282,10 @@ async def run_example(websocket_client): # LLMTextFrame: None, OpenAILLMContextFrame: None, LLMFullResponseEndFrame: None, + UserStartedSpeakingFrame: None, + UserStoppedSpeakingFrame: None, + StartInterruptionFrame: None, + StopInterruptionFrame: None, }, exclude_fields={ "result", diff --git a/examples/freeze-test/requirements.txt b/examples/freeze-test/requirements.txt new file mode 100644 index 000000000..8e3d7f12f --- /dev/null +++ b/examples/freeze-test/requirements.txt @@ -0,0 +1,4 @@ +python-dotenv +fastapi[all] +uvicorn +pipecat-ai[silero,websocket,openai, deepgram, cartesia, sentry] From fccd48bfff23510e1d87f110ad7dfc844e0d0513 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Tue, 1 Jul 2025 17:05:18 -0300 Subject: [PATCH 23/84] Fixing pipeline freeze when using Python 3.10 --- CHANGELOG.md | 3 ++ src/pipecat/pipeline/parallel_pipeline.py | 2 ++ src/pipecat/processors/consumer_processor.py | 1 + src/pipecat/processors/frame_processor.py | 2 ++ src/pipecat/processors/frameworks/rtvi.py | 2 ++ .../processors/idle_frame_processor.py | 3 +- src/pipecat/processors/user_idle_processor.py | 7 +++- src/pipecat/services/tavus/video.py | 1 + src/pipecat/services/tts_service.py | 1 + src/pipecat/transports/base_output.py | 1 + src/pipecat/utils/asyncio/task_manager.py | 22 ++++++++++++ src/pipecat/utils/asyncio/watchdog_event.py | 5 +++ .../utils/asyncio/watchdog_priority_queue.py | 35 +++++++++++++++++-- src/pipecat/utils/asyncio/watchdog_queue.py | 34 ++++++++++++++++-- 14 files changed, 113 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 834faaa94..9a12496d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- Fixed a race condition that occurs in Python 3.10+ where the task could miss + the `CancelledError` and continue running indefinitely, freezing the pipeline. + - Fixed a `AWSNovaSonicLLMService` issue introduced in 0.0.72. ## [0.0.73] - 2025-06-26 diff --git a/src/pipecat/pipeline/parallel_pipeline.py b/src/pipecat/pipeline/parallel_pipeline.py index 57b3a82c3..250a3e989 100644 --- a/src/pipecat/pipeline/parallel_pipeline.py +++ b/src/pipecat/pipeline/parallel_pipeline.py @@ -258,9 +258,11 @@ class ParallelPipeline(BasePipeline): async def _cancel(self): """Cancel all parallel pipeline processing tasks.""" if self._up_task: + self._up_queue.cancel() await self.cancel_task(self._up_task) self._up_task = None if self._down_task: + self._down_queue.cancel() await self.cancel_task(self._down_task) self._down_task = None diff --git a/src/pipecat/processors/consumer_processor.py b/src/pipecat/processors/consumer_processor.py index 277cef2cd..7812bbbd3 100644 --- a/src/pipecat/processors/consumer_processor.py +++ b/src/pipecat/processors/consumer_processor.py @@ -77,6 +77,7 @@ class ConsumerProcessor(FrameProcessor): async def _cancel(self, _: CancelFrame): """Cancel the consumer task.""" if self._consumer_task: + self._queue.cancel() await self.cancel_task(self._consumer_task) async def _consumer_task_handler(self): diff --git a/src/pipecat/processors/frame_processor.py b/src/pipecat/processors/frame_processor.py index 4105f4179..0d5a6db62 100644 --- a/src/pipecat/processors/frame_processor.py +++ b/src/pipecat/processors/frame_processor.py @@ -651,6 +651,7 @@ class FrameProcessor(BaseObject): async def __cancel_input_task(self): """Cancel the input processing task.""" if self.__input_frame_task: + self.__input_queue.cancel() await self.cancel_task(self.__input_frame_task) self.__input_frame_task = None @@ -686,6 +687,7 @@ class FrameProcessor(BaseObject): async def __cancel_push_task(self): """Cancel the frame pushing task.""" if self.__push_frame_task: + self.__push_queue.cancel() await self.cancel_task(self.__push_frame_task) self.__push_frame_task = None diff --git a/src/pipecat/processors/frameworks/rtvi.py b/src/pipecat/processors/frameworks/rtvi.py index 22d5370f2..7c03561a9 100644 --- a/src/pipecat/processors/frameworks/rtvi.py +++ b/src/pipecat/processors/frameworks/rtvi.py @@ -1086,10 +1086,12 @@ class RTVIProcessor(FrameProcessor): async def _cancel_tasks(self): """Cancel all running tasks.""" if self._action_task: + self._action_queue.cancel() await self.cancel_task(self._action_task) self._action_task = None if self._message_task: + self._message_queue.cancel() await self.cancel_task(self._message_task) self._message_task = None diff --git a/src/pipecat/processors/idle_frame_processor.py b/src/pipecat/processors/idle_frame_processor.py index 672027491..b8839124a 100644 --- a/src/pipecat/processors/idle_frame_processor.py +++ b/src/pipecat/processors/idle_frame_processor.py @@ -11,6 +11,7 @@ from typing import Awaitable, Callable, List, Optional from pipecat.frames.frames import Frame, StartFrame from pipecat.processors.frame_processor import FrameDirection, FrameProcessor +from pipecat.utils.asyncio.watchdog_event import WatchdogEvent class IdleFrameProcessor(FrameProcessor): @@ -77,7 +78,7 @@ class IdleFrameProcessor(FrameProcessor): def _create_idle_task(self): """Create and start the idle monitoring task.""" if not self._idle_task: - self._idle_event = asyncio.Event() + self._idle_event = WatchdogEvent(self.task_manager) self._idle_task = self.create_task(self._idle_task_handler()) async def _idle_task_handler(self): diff --git a/src/pipecat/processors/user_idle_processor.py b/src/pipecat/processors/user_idle_processor.py index 1a442fd8a..e98320b8b 100644 --- a/src/pipecat/processors/user_idle_processor.py +++ b/src/pipecat/processors/user_idle_processor.py @@ -15,10 +15,12 @@ from pipecat.frames.frames import ( CancelFrame, EndFrame, Frame, + StartFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, ) from pipecat.processors.frame_processor import FrameDirection, FrameProcessor +from pipecat.utils.asyncio.watchdog_event import WatchdogEvent class UserIdleProcessor(FrameProcessor): @@ -74,7 +76,7 @@ class UserIdleProcessor(FrameProcessor): self._interrupted = False self._conversation_started = False self._idle_task = None - self._idle_event = asyncio.Event() + self._idle_event = None def _wrap_callback( self, @@ -134,6 +136,9 @@ class UserIdleProcessor(FrameProcessor): """ await super().process_frame(frame, direction) + if isinstance(frame, StartFrame): + self._idle_event = WatchdogEvent(self.task_manager) + # Check for end frames before processing if isinstance(frame, (EndFrame, CancelFrame)): # Stop the idle task, if it exists diff --git a/src/pipecat/services/tavus/video.py b/src/pipecat/services/tavus/video.py index 9f40b709d..d633329bb 100644 --- a/src/pipecat/services/tavus/video.py +++ b/src/pipecat/services/tavus/video.py @@ -244,6 +244,7 @@ class TavusVideoService(AIService): async def _cancel_send_task(self): """Cancel the audio sending task if it exists.""" if self._send_task: + self._queue.cancel() await self.cancel_task(self._send_task) self._send_task = None diff --git a/src/pipecat/services/tts_service.py b/src/pipecat/services/tts_service.py index 1d97045fe..43ab5634f 100644 --- a/src/pipecat/services/tts_service.py +++ b/src/pipecat/services/tts_service.py @@ -805,6 +805,7 @@ class AudioContextWordTTSService(WebsocketWordTTSService): async def _stop_audio_context_task(self): if self._audio_context_task: + self._contexts_queue.cancel() await self.cancel_task(self._audio_context_task) self._audio_context_task = None diff --git a/src/pipecat/transports/base_output.py b/src/pipecat/transports/base_output.py index f90b4c553..93a11f5a3 100644 --- a/src/pipecat/transports/base_output.py +++ b/src/pipecat/transports/base_output.py @@ -810,6 +810,7 @@ class BaseOutputTransport(FrameProcessor): async def _cancel_clock_task(self): """Cancel and cleanup the clock processing task.""" if self._clock_task: + self._clock_queue.cancel() await self._transport.cancel_task(self._clock_task) self._clock_task = None diff --git a/src/pipecat/utils/asyncio/task_manager.py b/src/pipecat/utils/asyncio/task_manager.py index aaa340399..3bc3453ac 100644 --- a/src/pipecat/utils/asyncio/task_manager.py +++ b/src/pipecat/utils/asyncio/task_manager.py @@ -295,6 +295,9 @@ class TaskManager(BaseTaskManager): raise except Exception as e: logger.exception(f"{name}: unexpected exception while stopping task: {e}") + except BaseException as e: + logger.critical(f"{name}: fatal base exception while stopping task: {e}") + raise async def cancel_task(self, task: asyncio.Task, timeout: Optional[float] = None): """Cancels the given asyncio Task and awaits its completion with an optional timeout. @@ -394,6 +397,10 @@ class TaskManager(BaseTaskManager): while True: try: + if task_data.task.done(): + logger.debug(f"{name}: task is already done, cancelling watchdog task.") + break + start_time = time.time() await asyncio.wait_for(timer.wait(), timeout=watchdog_timeout) total_time = time.time() - start_time @@ -417,7 +424,22 @@ class TaskManager(BaseTaskManager): task_data = self._tasks[name] if task_data.watchdog_task: task_data.watchdog_task.cancel() + # In Python 3.10, simply calling task.cancel() looks like is not enough. + # Without this, some tasks appear that are never canceled. + # Python 3.12 handles this more gracefully, but we keep this for compatibility + # and to avoid "Task exception was never retrieved" warnings. + self.get_event_loop().create_task( + self._cleanup_watchdog(name, task_data.watchdog_task) + ) task_data.watchdog_task = None del self._tasks[name] except KeyError as e: logger.trace(f"{name}: unable to remove task data (already removed?): {e}") + + async def _cleanup_watchdog(self, name: str, watchdog_task: asyncio.Task): + try: + await watchdog_task + except asyncio.CancelledError: + pass + except Exception as e: + logger.warning(f"{name}: watchdog task raised exception: {e}") diff --git a/src/pipecat/utils/asyncio/watchdog_event.py b/src/pipecat/utils/asyncio/watchdog_event.py index b2b306618..73a49ad3e 100644 --- a/src/pipecat/utils/asyncio/watchdog_event.py +++ b/src/pipecat/utils/asyncio/watchdog_event.py @@ -60,3 +60,8 @@ class WatchdogEvent(asyncio.Event): return True except asyncio.TimeoutError: self._manager.task_reset_watchdog() + + def clear(self): + if self._manager.task_watchdog_enabled: + self._manager.task_reset_watchdog() + super().clear() diff --git a/src/pipecat/utils/asyncio/watchdog_priority_queue.py b/src/pipecat/utils/asyncio/watchdog_priority_queue.py index 46c6adf3d..2bd630fba 100644 --- a/src/pipecat/utils/asyncio/watchdog_priority_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_priority_queue.py @@ -12,10 +12,19 @@ timeouts during legitimate queue operations. """ import asyncio +from dataclasses import dataclass + +from loguru import logger from pipecat.utils.asyncio.task_manager import BaseTaskManager +@dataclass +class WatchdogPriorityCancelSentinel: + def __lt__(self, other): + return True + + class WatchdogPriorityQueue(asyncio.PriorityQueue): """Watchdog-enabled asyncio PriorityQueue. @@ -49,9 +58,17 @@ class WatchdogPriorityQueue(asyncio.PriorityQueue): The next item from the priority queue. """ if self._manager.task_watchdog_enabled: - return await self._watchdog_get() + get_result = await self._watchdog_get() else: - return await super().get() + get_result = await super().get() + + if isinstance(get_result, WatchdogPriorityCancelSentinel): + logger.debug( + "Received WatchdogPriorityCancelSentinel, throwing CancelledError to force cancelling" + ) + raise asyncio.CancelledError("Cancelling watchdog queue get() call.") + else: + return get_result def task_done(self): """Mark a task as done and reset watchdog if enabled. @@ -62,6 +79,20 @@ class WatchdogPriorityQueue(asyncio.PriorityQueue): self._manager.task_reset_watchdog() super().task_done() + def cancel(self): + """Ensures reliable task cancellation by preventing a common race condition. + + The race condition occurs in Python 3.10+ when: + 1. A value is put in the queue just before task cancellation + 2. queue.get() completes before the cancellation signal is delivered + 3. The task misses the CancelledError and continues running indefinitely + + This method prevents the issue by injecting a special sentinel value that + forces the task to raise CancelledError when consumed, ensuring proper + task termination. + """ + super().put_nowait(WatchdogPriorityCancelSentinel()) + async def _watchdog_get(self): """Get item from queue while periodically resetting watchdog timer.""" while True: diff --git a/src/pipecat/utils/asyncio/watchdog_queue.py b/src/pipecat/utils/asyncio/watchdog_queue.py index 4a92497f4..e3e379f3d 100644 --- a/src/pipecat/utils/asyncio/watchdog_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_queue.py @@ -12,10 +12,18 @@ timeouts during legitimate queue operations. """ import asyncio +from dataclasses import dataclass + +from loguru import logger from pipecat.utils.asyncio.task_manager import BaseTaskManager +@dataclass +class WatchdogQueueCancelSentinel: + pass + + class WatchdogQueue(asyncio.Queue): """Watchdog-enabled asyncio Queue. @@ -49,9 +57,17 @@ class WatchdogQueue(asyncio.Queue): The next item from the queue. """ if self._manager.task_watchdog_enabled: - return await self._watchdog_get() + get_result = await self._watchdog_get() else: - return await super().get() + get_result = await super().get() + + if isinstance(get_result, WatchdogQueueCancelSentinel): + logger.debug( + "Received WatchdogQueueCancelFrame, throwing CancelledError to force cancelling" + ) + raise asyncio.CancelledError("Cancelling watchdog queue get() call.") + else: + return get_result def task_done(self): """Mark a task as done and reset watchdog if enabled. @@ -62,6 +78,20 @@ class WatchdogQueue(asyncio.Queue): self._manager.task_reset_watchdog() super().task_done() + def cancel(self): + """Ensures reliable task cancellation by preventing a common race condition. + + The race condition occurs in Python 3.10+ when: + 1. A value is put in the queue just before task cancellation + 2. queue.get() completes before the cancellation signal is delivered + 3. The task misses the CancelledError and continues running indefinitely + + This method prevents the issue by injecting a special sentinel value that + forces the task to raise CancelledError when consumed, ensuring proper + task termination. + """ + super().put_nowait(WatchdogQueueCancelSentinel()) + async def _watchdog_get(self): """Get item from queue while periodically resetting watchdog timer.""" while True: From 721f662bbefb0b3b54ac02fb12866f2971658526 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Tue, 1 Jul 2025 17:09:05 -0300 Subject: [PATCH 24/84] Making cancel sentinel classes private --- src/pipecat/utils/asyncio/watchdog_priority_queue.py | 6 +++--- src/pipecat/utils/asyncio/watchdog_queue.py | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/pipecat/utils/asyncio/watchdog_priority_queue.py b/src/pipecat/utils/asyncio/watchdog_priority_queue.py index 2bd630fba..98d7f9172 100644 --- a/src/pipecat/utils/asyncio/watchdog_priority_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_priority_queue.py @@ -20,7 +20,7 @@ from pipecat.utils.asyncio.task_manager import BaseTaskManager @dataclass -class WatchdogPriorityCancelSentinel: +class _WatchdogPriorityCancelSentinel: def __lt__(self, other): return True @@ -62,7 +62,7 @@ class WatchdogPriorityQueue(asyncio.PriorityQueue): else: get_result = await super().get() - if isinstance(get_result, WatchdogPriorityCancelSentinel): + if isinstance(get_result, _WatchdogPriorityCancelSentinel): logger.debug( "Received WatchdogPriorityCancelSentinel, throwing CancelledError to force cancelling" ) @@ -91,7 +91,7 @@ class WatchdogPriorityQueue(asyncio.PriorityQueue): forces the task to raise CancelledError when consumed, ensuring proper task termination. """ - super().put_nowait(WatchdogPriorityCancelSentinel()) + super().put_nowait(_WatchdogPriorityCancelSentinel()) async def _watchdog_get(self): """Get item from queue while periodically resetting watchdog timer.""" diff --git a/src/pipecat/utils/asyncio/watchdog_queue.py b/src/pipecat/utils/asyncio/watchdog_queue.py index e3e379f3d..53b04c534 100644 --- a/src/pipecat/utils/asyncio/watchdog_queue.py +++ b/src/pipecat/utils/asyncio/watchdog_queue.py @@ -20,7 +20,7 @@ from pipecat.utils.asyncio.task_manager import BaseTaskManager @dataclass -class WatchdogQueueCancelSentinel: +class _WatchdogQueueCancelSentinel: pass @@ -61,7 +61,7 @@ class WatchdogQueue(asyncio.Queue): else: get_result = await super().get() - if isinstance(get_result, WatchdogQueueCancelSentinel): + if isinstance(get_result, _WatchdogQueueCancelSentinel): logger.debug( "Received WatchdogQueueCancelFrame, throwing CancelledError to force cancelling" ) @@ -90,7 +90,7 @@ class WatchdogQueue(asyncio.Queue): forces the task to raise CancelledError when consumed, ensuring proper task termination. """ - super().put_nowait(WatchdogQueueCancelSentinel()) + super().put_nowait(_WatchdogQueueCancelSentinel()) async def _watchdog_get(self): """Get item from queue while periodically resetting watchdog timer.""" From b87c57c951d42205cc572e3b06d96007b11d96dd Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Tue, 1 Jul 2025 17:12:18 -0300 Subject: [PATCH 25/84] Adding missing docstring to the watchdog event --- src/pipecat/utils/asyncio/watchdog_event.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pipecat/utils/asyncio/watchdog_event.py b/src/pipecat/utils/asyncio/watchdog_event.py index 73a49ad3e..c48356c50 100644 --- a/src/pipecat/utils/asyncio/watchdog_event.py +++ b/src/pipecat/utils/asyncio/watchdog_event.py @@ -62,6 +62,7 @@ class WatchdogEvent(asyncio.Event): self._manager.task_reset_watchdog() def clear(self): + """Clear the event while resetting watchdog timer.""" if self._manager.task_watchdog_enabled: self._manager.task_reset_watchdog() super().clear() From 0cdcfcee8d945bd78b693981c22d2eda2ac2671e Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Sun, 29 Jun 2025 09:58:00 -0400 Subject: [PATCH 26/84] Remove redundant import and global in SileroOnnxModel --- src/pipecat/audio/vad/silero.py | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/pipecat/audio/vad/silero.py b/src/pipecat/audio/vad/silero.py index d97e9b1df..57c302e49 100644 --- a/src/pipecat/audio/vad/silero.py +++ b/src/pipecat/audio/vad/silero.py @@ -46,10 +46,6 @@ class SileroOnnxModel: path: Path to the ONNX model file. force_onnx_cpu: Whether to force CPU execution provider. """ - import numpy as np - - global np - opts = onnxruntime.SessionOptions() opts.inter_op_num_threads = 1 opts.intra_op_num_threads = 1 From d45a07b5e51e2c48192ff4d66a176f9d4f1e121e Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 9 May 2025 10:50:27 -0400 Subject: [PATCH 27/84] add FileAPI to gemini.py --- .../services/gemini_multimodal_live/gemini.py | 103 +++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 3c5ed92dc..cc85799db 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -71,6 +71,8 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events +from .audio_transcriber import AudioTranscriber +from .file_api import GeminiFileAPI try: import websockets @@ -218,6 +220,29 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): system_instruction += str(content) return system_instruction + def add_file_reference(self, file_uri: str, mime_type: str, text: Optional[str] = None): + """Add a file reference to the context. + + This adds a user message with a file reference that will be sent during context initialization. + + Args: + file_uri: URI of the uploaded file + mime_type: MIME type of the file + text: Optional text prompt to accompany the file + """ + # Create parts list with file reference + parts = [] + if text: + parts.append({"type": "text", "text": text}) + + # Add file reference part + parts.append({"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}}) + + # Add to messages + message = {"role": "user", "content": parts} + self.messages.append(message) + logger.info(f"Added file reference to context: {file_uri}") + def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -242,6 +267,14 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): for part in content: if part.get("type") == "text": parts.append({"text": part.get("text")}) + elif part.get("type") == "file_data": + file_data = part.get("file_data", {}) + parts.append({ + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri") + } + }) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -432,6 +465,62 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter + """Gemini Live LLM Service with multimodal capabilities including File API support. + + This service implements the Gemini Multimodal Live API with support for: + - Audio input and output + - Image/video input + - File API (upload, reference, and management) + - Tools/function calling + + Example usage of File API: + ```python + # Initialize the service + gemini_service = GeminiMultimodalLiveLLMService(api_key="YOUR_API_KEY") + + # Upload a file from the client + file_path = "/path/to/user_uploaded_file.pdf" + file_info = await gemini_service.file_api.upload_file(file_path) + + # Get file URI and mime type from response + file_uri = file_info["file"]["uri"] + mime_type = "application/pdf" # Set appropriate MIME type + + # When starting a new bot session: + # 1. Initialize the context + context = GeminiMultimodalLiveContext() + + # 2. Add file reference to context BEFORE starting the conversation + context.add_file_reference( + file_uri=file_uri, + mime_type=mime_type, + text="Please analyze this document" + ) + + # 3. Now set the context to start the conversation with file reference included + await gemini_service.set_context(context) + + # Gemini now has access to the file reference in its context window + # The file URI remains valid for 48 hours before Google deletes it + + # Optional: List all files for this user + files = await gemini_service.file_api.list_files() + + # Optional: Get metadata for a specific file + file_metadata = await gemini_service.file_api.get_file(file_info["file"]["name"]) + + # Optional: Delete a file when no longer needed + await gemini_service.file_api.delete_file(file_info["file"]["name"]) + ``` + + Notes: + - Files are stored for 48 hours on Google's servers + - Maximum file size is 2GB + - Total storage per project is 20GB + - File references should be added to the context BEFORE starting the conversation + - The same file reference can be reused for multiple sessions within the 48-hour window + """ + def __init__( self, *, @@ -445,6 +534,7 @@ class GeminiMultimodalLiveLLMService(LLMService): tools: Optional[Union[List[dict], ToolsSchema]] = None, params: Optional[InputParams] = None, inference_on_context_initialization: bool = True, + file_api_base_url: str = "https://generativelanguage.googleapis.com/v1beta/files", **kwargs, ): """Initialize the Gemini Multimodal Live LLM service. @@ -522,6 +612,9 @@ class GeminiMultimodalLiveLLMService(LLMService): else {}, "extra": params.extra if isinstance(params.extra, dict) else {}, } + + # Initialize the File API client + self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) def can_generate_metrics(self) -> bool: """Check if the service can generate usage metrics. @@ -938,7 +1031,7 @@ class GeminiMultimodalLiveLLMService(LLMService): self._needs_turn_complete_message = True async def _create_single_response(self, messages_list): - # refactor to combine this logic with same logic in GeminiMultimodalLiveContext + # Refactor to combine this logic with same logic in GeminiMultimodalLiveContext messages = [] for item in messages_list: role = item.get("role") @@ -957,6 +1050,14 @@ class GeminiMultimodalLiveLLMService(LLMService): for part in content: if part.get("type") == "text": parts.append({"text": part.get("text")}) + elif part.get("type") == "file_data": + file_data = part.get("file_data", {}) + parts.append({ + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri") + } + }) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: From e02b95fca5d6e23d670aae953b21f602ab6b5c31 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 9 May 2025 10:51:24 -0400 Subject: [PATCH 28/84] Create file_api --- .../services/gemini_multimodal_live/file_api | 179 ++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 src/pipecat/services/gemini_multimodal_live/file_api diff --git a/src/pipecat/services/gemini_multimodal_live/file_api b/src/pipecat/services/gemini_multimodal_live/file_api new file mode 100644 index 000000000..10c8a44db --- /dev/null +++ b/src/pipecat/services/gemini_multimodal_live/file_api @@ -0,0 +1,179 @@ +import aiohttp +import mimetypes +from typing import Dict, Any, Optional + +from loguru import logger + +class GeminiFileAPI: + """Client for the Gemini File API. + + This class provides methods for uploading, fetching, listing, and deleting files + through Google's Gemini File API. + + Files uploaded through this API remain available for 48 hours and can be referenced + in calls to the Gemini generative models. Maximum file size is 2GB, with total + project storage limited to 20GB. + """ + + def __init__(self, api_key: str, base_url: str = "https://generativelanguage.googleapis.com/v1beta/files"): + """Initialize the Gemini File API client. + + Args: + api_key: Google AI API key + base_url: Base URL for the Gemini File API (default is the v1beta endpoint) + """ + self.api_key = api_key + self.base_url = base_url + + async def upload_file(self, file_path: str, display_name: Optional[str] = None) -> Dict[str, Any]: + """Upload a file to the Gemini File API. + + Args: + file_path: Path to the file to upload + display_name: Optional display name for the file + + Returns: + File metadata including uri, name, and display_name + """ + logger.info(f"Uploading file: {file_path}") + + async with aiohttp.ClientSession() as session: + # Determine the file's MIME type + mime_type, _ = mimetypes.guess_type(file_path) + if not mime_type: + mime_type = "application/octet-stream" + + # Read the file + with open(file_path, "rb") as f: + file_data = f.read() + + # First request to initiate the upload + headers = { + "X-Goog-Upload-Protocol": "resumable", + "X-Goog-Upload-Command": "start", + "X-Goog-Upload-Header-Content-Length": str(len(file_data)), + "X-Goog-Upload-Header-Content-Type": mime_type, + "Content-Type": "application/json" + } + + # Create the metadata payload + metadata = {} + if display_name: + metadata = {"file": {"display_name": display_name}} + + # Initial request to get the upload URL + async with session.post( + f"{self.base_url}?key={self.api_key}", + headers=headers, + json=metadata + ) as response: + if response.status != 200: + error_text = await response.text() + logger.error(f"Error initiating file upload: {error_text}") + raise Exception(f"Failed to initiate upload: {response.status}") + + # Get the upload URL from the response header + upload_url = response.headers.get("X-Goog-Upload-URL") + if not upload_url: + raise Exception("No upload URL in response") + + # Upload the actual file + headers = { + "Content-Length": str(len(file_data)), + "X-Goog-Upload-Offset": "0", + "X-Goog-Upload-Command": "upload, finalize" + } + + async with session.post( + upload_url, + headers=headers, + data=file_data + ) as response: + if response.status != 200: + error_text = await response.text() + logger.error(f"Error uploading file: {error_text}") + raise Exception(f"Failed to upload file: {response.status}") + + file_info = await response.json() + logger.info(f"File uploaded successfully: {file_info.get('file', {}).get('name')}") + return file_info + + async def get_file(self, name: str) -> Dict[str, Any]: + """Get metadata for a file. + + Args: + name: File name (or full path) + + Returns: + File metadata + """ + # Extract just the name part if a full path is provided + if '/' in name: + name = name.split('/')[-1] + + async with aiohttp.ClientSession() as session: + async with session.get( + f"{self.base_url}/{name}?key={self.api_key}" + ) as response: + if response.status != 200: + error_text = await response.text() + logger.error(f"Error getting file metadata: {error_text}") + raise Exception(f"Failed to get file metadata: {response.status}") + + file_info = await response.json() + return file_info + + async def list_files(self, page_size: int = 10, page_token: Optional[str] = None) -> Dict[str, Any]: + """List uploaded files. + + Args: + page_size: Number of files to return per page + page_token: Token for pagination + + Returns: + List of files and next page token if available + """ + params = { + "key": self.api_key, + "pageSize": page_size + } + + if page_token: + params["pageToken"] = page_token + + async with aiohttp.ClientSession() as session: + async with session.get( + self.base_url, + params=params + ) as response: + if response.status != 200: + error_text = await response.text() + logger.error(f"Error listing files: {error_text}") + raise Exception(f"Failed to list files: {response.status}") + + result = await response.json() + return result + + async def delete_file(self, name: str) -> bool: + """Delete a file. + + Args: + name: File name (or full path) + + Returns: + True if deleted successfully + """ + # Extract just the name part if a full path is provided + if '/' in name: + name = name.split('/')[-1] + + async with aiohttp.ClientSession() as session: + async with session.delete( + f"{self.base_url}/{name}?key={self.api_key}" + ) as response: + if response.status != 200: + error_text = await response.text() + logger.error(f"Error deleting file: {error_text}") + raise Exception(f"Failed to delete file: {response.status}") + + return True From 9171d4b0408c9c954e55a56f19558f8258d29ecc Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 9 May 2025 10:52:04 -0400 Subject: [PATCH 29/84] add FileData class events.py --- src/pipecat/services/gemini_multimodal_live/events.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/pipecat/services/gemini_multimodal_live/events.py b/src/pipecat/services/gemini_multimodal_live/events.py index 160ff1174..b70e2bf3e 100644 --- a/src/pipecat/services/gemini_multimodal_live/events.py +++ b/src/pipecat/services/gemini_multimodal_live/events.py @@ -44,6 +44,16 @@ class ContentPart(BaseModel): text: Optional[str] = Field(default=None, validate_default=False) inlineData: Optional[MediaChunk] = Field(default=None, validate_default=False) + fileData: Optional['FileData'] = Field(default=None, validate_default=False) + + +class FileData(BaseModel): + """Represents a file reference in the Gemini File API.""" + mimeType: str + fileUri: str + + +ContentPart.model_rebuild() # Rebuild model to resolve forward reference class Turn(BaseModel): From 77c369c3c76f8bb9c1a44d341b97e0133d1d85fd Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 9 May 2025 10:53:31 -0400 Subject: [PATCH 30/84] add file_api __init__.py --- src/pipecat/services/gemini_multimodal_live/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pipecat/services/gemini_multimodal_live/__init__.py b/src/pipecat/services/gemini_multimodal_live/__init__.py index 61bdf58dd..60a226e64 100644 --- a/src/pipecat/services/gemini_multimodal_live/__init__.py +++ b/src/pipecat/services/gemini_multimodal_live/__init__.py @@ -1 +1,2 @@ from .gemini import GeminiMultimodalLiveLLMService +from .file_api import GeminiFileAPI From 1ec1aa76e941a10501edafd4492d7d67e830a6a3 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Tue, 13 May 2025 22:01:02 -0400 Subject: [PATCH 31/84] Rename file_api to file_api.py added proper .py to file name. --- .../services/gemini_multimodal_live/{file_api => file_api.py} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/pipecat/services/gemini_multimodal_live/{file_api => file_api.py} (100%) diff --git a/src/pipecat/services/gemini_multimodal_live/file_api b/src/pipecat/services/gemini_multimodal_live/file_api.py similarity index 100% rename from src/pipecat/services/gemini_multimodal_live/file_api rename to src/pipecat/services/gemini_multimodal_live/file_api.py From bd7ca9419615e88061c4287a29ddf9dea8f3c8b2 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 12:19:40 -0400 Subject: [PATCH 32/84] Update gemini.py --- .../services/gemini_multimodal_live/gemini.py | 56 ------------------- 1 file changed, 56 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index cc85799db..b270f7721 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -464,63 +464,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter - - """Gemini Live LLM Service with multimodal capabilities including File API support. - This service implements the Gemini Multimodal Live API with support for: - - Audio input and output - - Image/video input - - File API (upload, reference, and management) - - Tools/function calling - - Example usage of File API: - ```python - # Initialize the service - gemini_service = GeminiMultimodalLiveLLMService(api_key="YOUR_API_KEY") - - # Upload a file from the client - file_path = "/path/to/user_uploaded_file.pdf" - file_info = await gemini_service.file_api.upload_file(file_path) - - # Get file URI and mime type from response - file_uri = file_info["file"]["uri"] - mime_type = "application/pdf" # Set appropriate MIME type - - # When starting a new bot session: - # 1. Initialize the context - context = GeminiMultimodalLiveContext() - - # 2. Add file reference to context BEFORE starting the conversation - context.add_file_reference( - file_uri=file_uri, - mime_type=mime_type, - text="Please analyze this document" - ) - - # 3. Now set the context to start the conversation with file reference included - await gemini_service.set_context(context) - - # Gemini now has access to the file reference in its context window - # The file URI remains valid for 48 hours before Google deletes it - - # Optional: List all files for this user - files = await gemini_service.file_api.list_files() - - # Optional: Get metadata for a specific file - file_metadata = await gemini_service.file_api.get_file(file_info["file"]["name"]) - - # Optional: Delete a file when no longer needed - await gemini_service.file_api.delete_file(file_info["file"]["name"]) - ``` - - Notes: - - Files are stored for 48 hours on Google's servers - - Maximum file size is 2GB - - Total storage per project is 20GB - - File references should be added to the context BEFORE starting the conversation - - The same file reference can be reused for multiple sessions within the 48-hour window - """ - def __init__( self, *, From 7b1071b30d88e290e446a3fc11ca2a8922a56a8d Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 13:04:52 -0400 Subject: [PATCH 33/84] Create 26f-gemini-multimodal-live-files-api.py This is an example to test usage of the Files API integration. Specifically with the Gemini Multimodal Live Service. --- .../26f-gemini-multimodal-live-files-api.py | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 examples/foundational/26f-gemini-multimodal-live-files-api.py diff --git a/examples/foundational/26f-gemini-multimodal-live-files-api.py b/examples/foundational/26f-gemini-multimodal-live-files-api.py new file mode 100644 index 000000000..413830cf9 --- /dev/null +++ b/examples/foundational/26f-gemini-multimodal-live-files-api.py @@ -0,0 +1,210 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +import argparse +import os +import tempfile + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.audio.vad.silero import SileroVADAnalyzer +from pipecat.audio.vad.vad_analyzer import VADParams +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineParams, PipelineTask +from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.services.gemini_multimodal_live.gemini import ( + GeminiMultimodalLiveLLMService, + GeminiMultimodalLiveContext, +) +from pipecat.transports.base_transport import TransportParams +from pipecat.transports.network.small_webrtc import SmallWebRTCTransport +from pipecat.transports.network.webrtc_connection import SmallWebRTCConnection + +load_dotenv(override=True) + + +async def create_sample_file(): + """Create a sample text file for testing the File API.""" + content = """# Sample Document for Gemini File API Test + +This is a test document to demonstrate the Gemini File API functionality. + +## Key Information: +- This document was created for testing purposes +- It contains information about AI assistants +- The document should be analyzed by Gemini +- The secret phrase for the test is "Pineapple Pizza" + +## AI Assistant Capabilities: +1. Natural language processing +2. File analysis and understanding +3. Context-aware conversations +4. Multi-modal interactions + +## Conclusion: +This document serves as a test case for the Gemini File API integration with Pipecat. +The AI should be able to reference and discuss the contents of this file. +""" + + # Create a temporary file + with tempfile.NamedTemporaryFile(mode='w', suffix='.txt', delete=False) as f: + f.write(content) + return f.name + + +async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespace): + logger.info(f"Starting File API bot") + + # Create a sample file to upload + sample_file_path = await create_sample_file() + logger.info(f"Created sample file: {sample_file_path}") + + # Initialize the SmallWebRTCTransport with the connection + transport = SmallWebRTCTransport( + webrtc_connection=webrtc_connection, + params=TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + video_in_enabled=False, + vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), + ), + ) + + system_instruction = """ + You are a helpful AI assistant with access to a document that has been uploaded for analysis. + + The document contains test information including a secret phrase. You should be able to: + - Reference and discuss the contents of the uploaded document + - Answer questions about what's in the document + - Use the information from the document in our conversation + + Your output will be converted to audio so don't include special characters in your answers. + Be friendly and demonstrate your ability to work with the uploaded file. + """ + + # Initialize Gemini service with File API support + llm = GeminiMultimodalLiveLLMService( + api_key=os.getenv("GOOGLE_API_KEY"), + system_instruction=system_instruction, + voice_id="Charon", # Aoede, Charon, Fenrir, Kore, Puck + transcribe_user_audio=True, + ) + + # Upload the sample file to Gemini File API + logger.info("Uploading file to Gemini File API...") + file_info = None + try: + file_info = await llm.file_api.upload_file( + sample_file_path, + display_name="Sample Test Document" + ) + logger.info(f"File uploaded successfully: {file_info['file']['name']}") + + # Get file URI and mime type + file_uri = file_info["file"]["uri"] + mime_type = "text/plain" + + # Create context with file reference + context = OpenAILLMContext( + [ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Greet the user and let them know you have access to a document they can ask you about. Mention that you can discuss its contents." + }, + { + "type": "file_data", + "file_data": { + "mime_type": mime_type, + "file_uri": file_uri + } + } + ] + } + ] + ) + + logger.info("File reference added to conversation context") + + except Exception as e: + logger.error(f"Error uploading file: {e}") + # Continue with a basic context if file upload fails + context = OpenAILLMContext( + [ + { + "role": "user", + "content": "Greet the user and explain that there was an issue with file upload, but you're ready to help with other tasks." + } + ] + ) + + # Create context aggregator + context_aggregator = llm.create_context_aggregator(context) + + # Build the pipeline + pipeline = Pipeline([ + transport.input(), + context_aggregator.user(), + llm, + transport.output(), + context_aggregator.assistant(), + ]) + + # Configure the pipeline task + task = PipelineTask( + pipeline, + params=PipelineParams( + allow_interruptions=True, + enable_metrics=True, + enable_usage_metrics=True, + ), + ) + + # Handle client connection event + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + logger.info(f"Client connected") + # Kick off the conversation using standard context frame + await task.queue_frames([context_aggregator.user().get_context_frame()]) + + # Handle client disconnection events + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + + @transport.event_handler("on_client_closed") + async def on_client_closed(transport, client): + logger.info(f"Client closed connection") + await task.cancel() + + # Run the pipeline + runner = PipelineRunner(handle_sigint=False) + await runner.run(task) + + # Clean up: delete the uploaded file and temporary file + if file_info: + try: + await llm.file_api.delete_file(file_info["file"]["name"]) + logger.info("Cleaned up uploaded file from Gemini") + except Exception as e: + logger.error(f"Error cleaning up file: {e}") + + # Remove temporary file + try: + os.unlink(sample_file_path) + logger.info("Cleaned up temporary file") + except Exception as e: + logger.error(f"Error removing temporary file: {e}") + + +if __name__ == "__main__": + from run import main + + main() From baccf504179629166e1df7f4c709b35c309de8a3 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 13:41:55 -0400 Subject: [PATCH 34/84] update correct upload endpoint file_api.py --- .../gemini_multimodal_live/file_api.py | 44 ++++++++++++------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/file_api.py b/src/pipecat/services/gemini_multimodal_live/file_api.py index 10c8a44db..39b7d9df9 100644 --- a/src/pipecat/services/gemini_multimodal_live/file_api.py +++ b/src/pipecat/services/gemini_multimodal_live/file_api.py @@ -1,3 +1,9 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + import aiohttp import mimetypes from typing import Dict, Any, Optional @@ -24,9 +30,11 @@ class GeminiFileAPI: """ self.api_key = api_key self.base_url = base_url + # Upload URL uses the /upload/ path + self.upload_base_url = "https://generativelanguage.googleapis.com/upload/v1beta/files" async def upload_file(self, file_path: str, display_name: Optional[str] = None) -> Dict[str, Any]: - """Upload a file to the Gemini File API. + """Upload a file to the Gemini File API using the correct resumable upload protocol. Args: file_path: Path to the file to upload @@ -47,7 +55,12 @@ class GeminiFileAPI: with open(file_path, "rb") as f: file_data = f.read() - # First request to initiate the upload + # Create the metadata payload + metadata = {} + if display_name: + metadata = {"file": {"display_name": display_name}} + + # Step 1: Initial resumable request to get upload URL headers = { "X-Goog-Upload-Protocol": "resumable", "X-Goog-Upload-Command": "start", @@ -56,43 +69,42 @@ class GeminiFileAPI: "Content-Type": "application/json" } - # Create the metadata payload - metadata = {} - if display_name: - metadata = {"file": {"display_name": display_name}} - - # Initial request to get the upload URL + logger.debug(f"Step 1: Getting upload URL from {self.upload_base_url}") async with session.post( - f"{self.base_url}?key={self.api_key}", + f"{self.upload_base_url}?key={self.api_key}", headers=headers, json=metadata ) as response: if response.status != 200: error_text = await response.text() logger.error(f"Error initiating file upload: {error_text}") - raise Exception(f"Failed to initiate upload: {response.status}") + raise Exception(f"Failed to initiate upload: {response.status} - {error_text}") # Get the upload URL from the response header upload_url = response.headers.get("X-Goog-Upload-URL") if not upload_url: - raise Exception("No upload URL in response") + logger.error(f"Response headers: {dict(response.headers)}") + raise Exception("No upload URL in response headers") + + logger.debug(f"Got upload URL: {upload_url}") - # Upload the actual file - headers = { + # Step 2: Upload the actual file data + upload_headers = { "Content-Length": str(len(file_data)), "X-Goog-Upload-Offset": "0", "X-Goog-Upload-Command": "upload, finalize" } + logger.debug(f"Step 2: Uploading file data to {upload_url}") async with session.post( upload_url, - headers=headers, + headers=upload_headers, data=file_data ) as response: if response.status != 200: error_text = await response.text() - logger.error(f"Error uploading file: {error_text}") - raise Exception(f"Failed to upload file: {response.status}") + logger.error(f"Error uploading file data: {error_text}") + raise Exception(f"Failed to upload file: {response.status} - {error_text}") file_info = await response.json() logger.info(f"File uploaded successfully: {file_info.get('file', {}).get('name')}") From 6e6e932370eb74f36a30ddfaeb35e57900a118a8 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 17:36:36 -0400 Subject: [PATCH 35/84] Create 26g-gemini-multimodal-live-groundingMetadata.py --- ...emini-multimodal-live-groundingMetadata.py | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py diff --git a/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py b/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py new file mode 100644 index 000000000..0c6d35ff0 --- /dev/null +++ b/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py @@ -0,0 +1,164 @@ + +import argparse +import os + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.audio.vad.silero import SileroVADAnalyzer +from pipecat.audio.vad.vad_analyzer import VADParams +from pipecat.adapters.schemas.tools_schema import AdapterType, ToolsSchema +from pipecat.frames.frames import Frame +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineParams, PipelineTask +from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.processors.frame_processor import FrameDirection, FrameProcessor +from pipecat.services.gemini_multimodal_live.gemini import GeminiMultimodalLiveLLMService +from pipecat.services.google.frames import LLMSearchResponseFrame +from pipecat.transports.base_transport import TransportParams +from pipecat.transports.network.small_webrtc import SmallWebRTCTransport +from pipecat.transports.network.webrtc_connection import SmallWebRTCConnection + +load_dotenv(override=True) + +SYSTEM_INSTRUCTION = """ +You are a helpful AI assistant that actively uses Google Search to provide up-to-date, accurate information. + +IMPORTANT: For ANY question about current events, news, recent developments, real-time information, or anything that might have changed recently, you MUST use the google_search tool to get the latest information. + +You should use Google Search for: +- Current news and events +- Recent developments in any field +- Today's weather, stock prices, or other real-time data +- Any question that starts with "what's happening", "latest", "recent", "current", "today", etc. +- When you're not certain about recent information + +Always be proactive about using search when the user asks about anything that could benefit from real-time information. + +Your output will be converted to audio so don't include special characters in your answers. + +Respond to what the user said in a creative and helpful way, always using search for current information. +""" + + +class GroundingMetadataProcessor(FrameProcessor): + """Processor to capture and display grounding metadata from Gemini Live API.""" + + def __init__(self): + super().__init__() + self._grounding_count = 0 + + async def process_frame(self, frame: Frame, direction: FrameDirection): + # Always call super().process_frame first + await super().process_frame(frame, direction) + + # Only log important frame types, not every audio frame + if hasattr(frame, '__class__'): + frame_type = frame.__class__.__name__ + if frame_type in ['LLMTextFrame', 'TTSTextFrame', 'LLMFullResponseStartFrame', 'LLMFullResponseEndFrame']: + logger.debug(f"GroundingProcessor received: {frame_type}") + + if isinstance(frame, LLMSearchResponseFrame): + self._grounding_count += 1 + logger.info(f"\n🔍 GROUNDING METADATA RECEIVED #{self._grounding_count}") + logger.info(f"📝 Search Result Text: {frame.search_result[:200]}...") + + if frame.rendered_content: + logger.info(f"🔗 Rendered Content: {frame.rendered_content}") + + if frame.origins: + logger.info(f"📍 Number of Origins: {len(frame.origins)}") + for i, origin in enumerate(frame.origins): + logger.info(f" Origin {i+1}: {origin.site_title} - {origin.site_uri}") + if origin.results: + logger.info(f" Results: {len(origin.results)} items") + + # Always push the frame downstream + await self.push_frame(frame, direction) + + +async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespace): + logger.info(f"Starting Gemini Live Grounding Test Bot") + + # Initialize the SmallWebRTCTransport with the connection + transport = SmallWebRTCTransport( + webrtc_connection=webrtc_connection, + params=TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + video_in_enabled=False, + vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), + ), + ) + + # Create tools using ToolsSchema with custom tools for Gemini + tools = ToolsSchema( + standard_tools=[], # No standard function declarations needed + custom_tools={ + AdapterType.GEMINI: [ + {"google_search": {}}, + {"code_execution": {}} + ] + } + ) + + llm = GeminiMultimodalLiveLLMService( + api_key=os.getenv("GOOGLE_API_KEY"), + system_instruction=SYSTEM_INSTRUCTION, + voice_id="Charon", # Aoede, Charon, Fenrir, Kore, Puck + transcribe_user_audio=True, + tools=tools, + ) + + # Create a processor to capture grounding metadata + grounding_processor = GroundingMetadataProcessor() + + messages = [ + { + "role": "user", + "content": 'Please introduce yourself and let me know that you can help with current information by searching the web. Ask me what current information I\'d like to know about.', + }, + ] + + # Set up conversation context and management + context = OpenAILLMContext(messages) + context_aggregator = llm.create_context_aggregator(context) + + pipeline = Pipeline( + [ + transport.input(), + context_aggregator.user(), + llm, + grounding_processor, # Add our grounding processor here + transport.output(), + context_aggregator.assistant(), + ] + ) + + task = PipelineTask(pipeline) + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + logger.info(f"Client connected") + # Kick off the conversation. + await task.queue_frames([context_aggregator.user().get_context_frame()]) + + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + + @transport.event_handler("on_client_closed") + async def on_client_closed(transport, client): + logger.info(f"Client closed connection") + await task.cancel() + + runner = PipelineRunner(handle_sigint=False) + + await runner.run(task) + + +if __name__ == "__main__": + from run import main + + main() From 44d3bd30fae6a29d115a6cf767f512a4d18c28f0 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 18:01:15 -0400 Subject: [PATCH 36/84] Add groundingMetadata and logging gemini.py --- .../services/gemini_multimodal_live/gemini.py | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index b270f7721..301290b45 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -60,6 +60,8 @@ from pipecat.processors.aggregators.openai_llm_context import ( ) from pipecat.processors.frame_processor import FrameDirection from pipecat.services.llm_service import FunctionCallFromLLM, LLMService +from pipecat.services.google.frames import LLMSearchOrigin, LLMSearchResponseFrame, LLMSearchResult +from pipecat.services.llm_service import LLMService from pipecat.services.openai.llm import ( OpenAIAssistantContextAggregator, OpenAIUserContextAggregator, @@ -560,6 +562,10 @@ class GeminiMultimodalLiveLLMService(LLMService): # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) + # Grounding metadata tracking + self._search_result_buffer = "" + self._accumulated_grounding_metadata = None + def can_generate_metrics(self) -> bool: """Check if the service can generate usage metrics. @@ -909,12 +915,23 @@ class GeminiMultimodalLiveLLMService(LLMService): await self._handle_evt_input_transcription(evt) elif evt.serverContent and evt.serverContent.outputTranscription: await self._handle_evt_output_transcription(evt) + elif evt.serverContent and evt.serverContent.groundingMetadata: + await self._handle_evt_grounding_metadata(evt) elif evt.toolCall: await self._handle_evt_tool_call(evt) elif False: # !!! todo: error events? await self._handle_evt_error(evt) # errors are fatal, so exit the receive loop return + else: + # Log unhandled events that might contain grounding metadata + logger.warning(f"Received unhandled server event type: {evt}") + pass + + async def _transcribe_audio_handler(self): + while True: + audio = await self._transcribe_audio_queue.get() + await self._handle_transcribe_user_audio(audio, self._context) # # @@ -1071,8 +1088,14 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.push_frame(LLMFullResponseStartFrame()) self._bot_text_buffer += text + self._search_result_buffer += text # Also accumulate for grounding await self.push_frame(LLMTextFrame(text=text)) + # Check for grounding metadata in server content + if evt.serverContent and evt.serverContent.groundingMetadata: + self._accumulated_grounding_metadata = evt.serverContent.groundingMetadata + logger.debug("Grounding metadata detected in model turn.") + inline_data = part.inlineData if not inline_data: return @@ -1139,6 +1162,18 @@ class GeminiMultimodalLiveLLMService(LLMService): self._llm_output_buffer = "" # Only push the TTSStoppedFrame if the bot is outputting audio + # Process grounding metadata if we have accumulated any + if self._accumulated_grounding_metadata: + logger.debug("Processing grounding metadata...") + await self._process_grounding_metadata(self._accumulated_grounding_metadata, self._search_result_buffer) + else: + logger.debug("No grounding metadata to process") + + # Reset grounding tracking for next response + self._search_result_buffer = "" + self._accumulated_grounding_metadata = None + + # Only push the TTSStoppedFrame the bot is outputting audio # when text is found, modalities is set to TEXT and no audio # is produced. if not text: @@ -1216,6 +1251,13 @@ class GeminiMultimodalLiveLLMService(LLMService): # Collect text for tracing self._llm_output_buffer += text + # Accumulate text for grounding as well + self._search_result_buffer += text + + # Check for grounding metadata in server content + if evt.serverContent and evt.serverContent.groundingMetadata: + self._accumulated_grounding_metadata = evt.serverContent.groundingMetadata + await self.push_frame(LLMTextFrame(text=text)) await self.push_frame(TTSTextFrame(text=text)) @@ -1238,6 +1280,73 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.start_llm_usage_metrics(tokens) + async def _handle_evt_grounding_metadata(self, evt): + """Handle dedicated grounding metadata events.""" + logger.debug("Received dedicated grounding metadata event.") + + if evt.serverContent and evt.serverContent.groundingMetadata: + grounding_metadata = evt.serverContent.groundingMetadata + logger.debug(f"Grounding data: {len(grounding_metadata.groundingChunks or [])} chunks, {len(grounding_metadata.groundingSupports or [])} supports") + + # Process the grounding metadata immediately + await self._process_grounding_metadata(grounding_metadata, self._search_result_buffer) + + async def _process_grounding_metadata(self, grounding_metadata: events.GroundingMetadata, search_result: str = ""): + """Process grounding metadata and emit LLMSearchResponseFrame.""" + logger.debug(f"Processing grounding metadata. Search result text length: {len(search_result)}") + if not grounding_metadata: + logger.warning("No grounding metadata provided to _process_grounding_metadata") + return + + # logger.debug(f"Processing grounding metadata: {grounding_metadata}") # Too verbose for PR + + # Extract rendered content for search suggestions + rendered_content = None + if grounding_metadata.searchEntryPoint and grounding_metadata.searchEntryPoint.renderedContent: + rendered_content = grounding_metadata.searchEntryPoint.renderedContent + + # Convert grounding chunks and supports to LLMSearchOrigin format + origins = [] + + if grounding_metadata.groundingChunks and grounding_metadata.groundingSupports: + # Create a mapping of chunk indices to origins + chunk_to_origin = {} + + for index, chunk in enumerate(grounding_metadata.groundingChunks): + if chunk.web: + origin = LLMSearchOrigin( + site_uri=chunk.web.uri, + site_title=chunk.web.title, + results=[] + ) + chunk_to_origin[index] = origin + origins.append(origin) + + # Add grounding support results to the appropriate origins + for support in grounding_metadata.groundingSupports: + if support.segment and support.groundingChunkIndices: + text = support.segment.text or "" + confidence_scores = support.confidenceScores or [] + + # Add this result to all origins referenced by this support + for chunk_index in support.groundingChunkIndices: + if chunk_index in chunk_to_origin: + result = LLMSearchResult( + text=text, + confidence=confidence_scores + ) + chunk_to_origin[chunk_index].results.append(result) + + # Create and push the search response frame + search_frame = LLMSearchResponseFrame( + search_result=search_result, + origins=origins, + rendered_content=rendered_content + ) + + logger.debug(f"Emitting LLMSearchResponseFrame with {len(origins)} origins, rendered_content available: {rendered_content is not None}") + await self.push_frame(search_frame) + def create_context_aggregator( self, context: OpenAILLMContext, From 4fd8df208f63733a2733759c3ecb4c172c7402d1 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 18:07:09 -0400 Subject: [PATCH 37/84] Add groundingMetadata events.py --- .../services/gemini_multimodal_live/events.py | 68 +++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/events.py b/src/pipecat/services/gemini_multimodal_live/events.py index b70e2bf3e..6df94148b 100644 --- a/src/pipecat/services/gemini_multimodal_live/events.py +++ b/src/pipecat/services/gemini_multimodal_live/events.py @@ -12,6 +12,7 @@ import json from enum import Enum from typing import List, Literal, Optional +from loguru import logger from PIL import Image from pydantic import BaseModel, Field @@ -247,6 +248,49 @@ class Config(BaseModel): setup: Setup +# +# Grounding metadata models +# + + +class SearchEntryPoint(BaseModel): + """Represents the search entry point with rendered content for search suggestions.""" + renderedContent: Optional[str] = None + + +class WebSource(BaseModel): + """Represents a web source from grounding chunks.""" + uri: Optional[str] = None + title: Optional[str] = None + + +class GroundingChunk(BaseModel): + """Represents a grounding chunk containing web source information.""" + web: Optional[WebSource] = None + + +class GroundingSegment(BaseModel): + """Represents a segment of text that is grounded.""" + startIndex: Optional[int] = None + endIndex: Optional[int] = None + text: Optional[str] = None + + +class GroundingSupport(BaseModel): + """Represents support information for grounded text segments.""" + segment: Optional[GroundingSegment] = None + groundingChunkIndices: Optional[List[int]] = None + confidenceScores: Optional[List[float]] = None + + +class GroundingMetadata(BaseModel): + """Represents grounding metadata from Google Search.""" + searchEntryPoint: Optional[SearchEntryPoint] = None + groundingChunks: Optional[List[GroundingChunk]] = None + groundingSupports: Optional[List[GroundingSupport]] = None + webSearchQueries: Optional[List[str]] = None + + # # Server events # @@ -338,6 +382,7 @@ class ServerContent(BaseModel): turnComplete: Optional[bool] = None inputTranscription: Optional[BidiGenerateContentTranscription] = None outputTranscription: Optional[BidiGenerateContentTranscription] = None + groundingMetadata: Optional[GroundingMetadata] = None class FunctionCall(BaseModel): @@ -430,7 +475,7 @@ class ServerEvent(BaseModel): usageMetadata: Optional[UsageMetadata] = None -def parse_server_event(str): +def parse_server_event(message_str): """Parse a server event from JSON string. Args: @@ -439,11 +484,26 @@ def parse_server_event(str): Returns: ServerEvent instance if parsing succeeds, None otherwise. """ + from loguru import logger # Import logger locally to avoid scoping issues + try: - evt = json.loads(str) - return ServerEvent.model_validate(evt) + evt_dict = json.loads(message_str) + + # Only log grounding metadata detection if truly needed for debugging + # In production, this could be removed entirely or moved to TRACE level + if 'serverContent' in evt_dict: + server_content = evt_dict['serverContent'] + if 'groundingMetadata' in server_content: + # Consider removing this log entirely for production + pass + + evt = ServerEvent.model_validate(evt_dict) + return evt except Exception as e: - print(f"Error parsing server event: {e}") + logger.error(f"Error parsing server event: {e}") + # Truncate raw message to avoid logging potentially sensitive or overly long data + truncated_message = message_str[:200] + "..." if len(message_str) > 200 else message_str + logger.error(f"Raw message (truncated): {truncated_message}") return None From a63d0da528872a07127f6fe0dd4d3c9bf716fbd0 Mon Sep 17 00:00:00 2001 From: Pete <78183014+getchannel@users.noreply.github.com> Date: Sat, 21 Jun 2025 14:29:09 -0400 Subject: [PATCH 38/84] Update gemini.py --- src/pipecat/services/gemini_multimodal_live/gemini.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 301290b45..29d17e689 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -62,6 +62,8 @@ from pipecat.processors.frame_processor import FrameDirection from pipecat.services.llm_service import FunctionCallFromLLM, LLMService from pipecat.services.google.frames import LLMSearchOrigin, LLMSearchResponseFrame, LLMSearchResult from pipecat.services.llm_service import LLMService +from pipecat.services.llm_service import FunctionCallFromLLM, LLMService + from pipecat.services.openai.llm import ( OpenAIAssistantContextAggregator, OpenAIUserContextAggregator, From 79e51051c7cfa16344bd456c995c1baa53d22186 Mon Sep 17 00:00:00 2001 From: vipyne Date: Tue, 1 Jul 2025 16:25:59 -0500 Subject: [PATCH 39/84] New lint rules and remove unused example file --- ...emini-multimodal-live-groundingMetadata.py | 164 ------------------ .../gemini_multimodal_live/__init__.py | 2 +- .../services/gemini_multimodal_live/events.py | 19 +- .../gemini_multimodal_live/file_api.py | 125 +++++++------ .../services/gemini_multimodal_live/gemini.py | 98 ++++++----- 5 files changed, 125 insertions(+), 283 deletions(-) delete mode 100644 examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py diff --git a/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py b/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py deleted file mode 100644 index 0c6d35ff0..000000000 --- a/examples/foundational/26g-gemini-multimodal-live-groundingMetadata.py +++ /dev/null @@ -1,164 +0,0 @@ - -import argparse -import os - -from dotenv import load_dotenv -from loguru import logger - -from pipecat.audio.vad.silero import SileroVADAnalyzer -from pipecat.audio.vad.vad_analyzer import VADParams -from pipecat.adapters.schemas.tools_schema import AdapterType, ToolsSchema -from pipecat.frames.frames import Frame -from pipecat.pipeline.pipeline import Pipeline -from pipecat.pipeline.runner import PipelineRunner -from pipecat.pipeline.task import PipelineParams, PipelineTask -from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext -from pipecat.processors.frame_processor import FrameDirection, FrameProcessor -from pipecat.services.gemini_multimodal_live.gemini import GeminiMultimodalLiveLLMService -from pipecat.services.google.frames import LLMSearchResponseFrame -from pipecat.transports.base_transport import TransportParams -from pipecat.transports.network.small_webrtc import SmallWebRTCTransport -from pipecat.transports.network.webrtc_connection import SmallWebRTCConnection - -load_dotenv(override=True) - -SYSTEM_INSTRUCTION = """ -You are a helpful AI assistant that actively uses Google Search to provide up-to-date, accurate information. - -IMPORTANT: For ANY question about current events, news, recent developments, real-time information, or anything that might have changed recently, you MUST use the google_search tool to get the latest information. - -You should use Google Search for: -- Current news and events -- Recent developments in any field -- Today's weather, stock prices, or other real-time data -- Any question that starts with "what's happening", "latest", "recent", "current", "today", etc. -- When you're not certain about recent information - -Always be proactive about using search when the user asks about anything that could benefit from real-time information. - -Your output will be converted to audio so don't include special characters in your answers. - -Respond to what the user said in a creative and helpful way, always using search for current information. -""" - - -class GroundingMetadataProcessor(FrameProcessor): - """Processor to capture and display grounding metadata from Gemini Live API.""" - - def __init__(self): - super().__init__() - self._grounding_count = 0 - - async def process_frame(self, frame: Frame, direction: FrameDirection): - # Always call super().process_frame first - await super().process_frame(frame, direction) - - # Only log important frame types, not every audio frame - if hasattr(frame, '__class__'): - frame_type = frame.__class__.__name__ - if frame_type in ['LLMTextFrame', 'TTSTextFrame', 'LLMFullResponseStartFrame', 'LLMFullResponseEndFrame']: - logger.debug(f"GroundingProcessor received: {frame_type}") - - if isinstance(frame, LLMSearchResponseFrame): - self._grounding_count += 1 - logger.info(f"\n🔍 GROUNDING METADATA RECEIVED #{self._grounding_count}") - logger.info(f"📝 Search Result Text: {frame.search_result[:200]}...") - - if frame.rendered_content: - logger.info(f"🔗 Rendered Content: {frame.rendered_content}") - - if frame.origins: - logger.info(f"📍 Number of Origins: {len(frame.origins)}") - for i, origin in enumerate(frame.origins): - logger.info(f" Origin {i+1}: {origin.site_title} - {origin.site_uri}") - if origin.results: - logger.info(f" Results: {len(origin.results)} items") - - # Always push the frame downstream - await self.push_frame(frame, direction) - - -async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespace): - logger.info(f"Starting Gemini Live Grounding Test Bot") - - # Initialize the SmallWebRTCTransport with the connection - transport = SmallWebRTCTransport( - webrtc_connection=webrtc_connection, - params=TransportParams( - audio_in_enabled=True, - audio_out_enabled=True, - video_in_enabled=False, - vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), - ), - ) - - # Create tools using ToolsSchema with custom tools for Gemini - tools = ToolsSchema( - standard_tools=[], # No standard function declarations needed - custom_tools={ - AdapterType.GEMINI: [ - {"google_search": {}}, - {"code_execution": {}} - ] - } - ) - - llm = GeminiMultimodalLiveLLMService( - api_key=os.getenv("GOOGLE_API_KEY"), - system_instruction=SYSTEM_INSTRUCTION, - voice_id="Charon", # Aoede, Charon, Fenrir, Kore, Puck - transcribe_user_audio=True, - tools=tools, - ) - - # Create a processor to capture grounding metadata - grounding_processor = GroundingMetadataProcessor() - - messages = [ - { - "role": "user", - "content": 'Please introduce yourself and let me know that you can help with current information by searching the web. Ask me what current information I\'d like to know about.', - }, - ] - - # Set up conversation context and management - context = OpenAILLMContext(messages) - context_aggregator = llm.create_context_aggregator(context) - - pipeline = Pipeline( - [ - transport.input(), - context_aggregator.user(), - llm, - grounding_processor, # Add our grounding processor here - transport.output(), - context_aggregator.assistant(), - ] - ) - - task = PipelineTask(pipeline) - - @transport.event_handler("on_client_connected") - async def on_client_connected(transport, client): - logger.info(f"Client connected") - # Kick off the conversation. - await task.queue_frames([context_aggregator.user().get_context_frame()]) - - @transport.event_handler("on_client_disconnected") - async def on_client_disconnected(transport, client): - logger.info(f"Client disconnected") - - @transport.event_handler("on_client_closed") - async def on_client_closed(transport, client): - logger.info(f"Client closed connection") - await task.cancel() - - runner = PipelineRunner(handle_sigint=False) - - await runner.run(task) - - -if __name__ == "__main__": - from run import main - - main() diff --git a/src/pipecat/services/gemini_multimodal_live/__init__.py b/src/pipecat/services/gemini_multimodal_live/__init__.py index 60a226e64..513d9fd66 100644 --- a/src/pipecat/services/gemini_multimodal_live/__init__.py +++ b/src/pipecat/services/gemini_multimodal_live/__init__.py @@ -1,2 +1,2 @@ -from .gemini import GeminiMultimodalLiveLLMService from .file_api import GeminiFileAPI +from .gemini import GeminiMultimodalLiveLLMService diff --git a/src/pipecat/services/gemini_multimodal_live/events.py b/src/pipecat/services/gemini_multimodal_live/events.py index 6df94148b..4687519c0 100644 --- a/src/pipecat/services/gemini_multimodal_live/events.py +++ b/src/pipecat/services/gemini_multimodal_live/events.py @@ -45,11 +45,12 @@ class ContentPart(BaseModel): text: Optional[str] = Field(default=None, validate_default=False) inlineData: Optional[MediaChunk] = Field(default=None, validate_default=False) - fileData: Optional['FileData'] = Field(default=None, validate_default=False) + fileData: Optional["FileData"] = Field(default=None, validate_default=False) class FileData(BaseModel): """Represents a file reference in the Gemini File API.""" + mimeType: str fileUri: str @@ -255,22 +256,26 @@ class Config(BaseModel): class SearchEntryPoint(BaseModel): """Represents the search entry point with rendered content for search suggestions.""" + renderedContent: Optional[str] = None class WebSource(BaseModel): """Represents a web source from grounding chunks.""" + uri: Optional[str] = None title: Optional[str] = None class GroundingChunk(BaseModel): """Represents a grounding chunk containing web source information.""" + web: Optional[WebSource] = None class GroundingSegment(BaseModel): """Represents a segment of text that is grounded.""" + startIndex: Optional[int] = None endIndex: Optional[int] = None text: Optional[str] = None @@ -278,6 +283,7 @@ class GroundingSegment(BaseModel): class GroundingSupport(BaseModel): """Represents support information for grounded text segments.""" + segment: Optional[GroundingSegment] = None groundingChunkIndices: Optional[List[int]] = None confidenceScores: Optional[List[float]] = None @@ -285,6 +291,7 @@ class GroundingSupport(BaseModel): class GroundingMetadata(BaseModel): """Represents grounding metadata from Google Search.""" + searchEntryPoint: Optional[SearchEntryPoint] = None groundingChunks: Optional[List[GroundingChunk]] = None groundingSupports: Optional[List[GroundingSupport]] = None @@ -485,15 +492,15 @@ def parse_server_event(message_str): ServerEvent instance if parsing succeeds, None otherwise. """ from loguru import logger # Import logger locally to avoid scoping issues - + try: evt_dict = json.loads(message_str) - + # Only log grounding metadata detection if truly needed for debugging # In production, this could be removed entirely or moved to TRACE level - if 'serverContent' in evt_dict: - server_content = evt_dict['serverContent'] - if 'groundingMetadata' in server_content: + if "serverContent" in evt_dict: + server_content = evt_dict["serverContent"] + if "groundingMetadata" in server_content: # Consider removing this log entirely for production pass diff --git a/src/pipecat/services/gemini_multimodal_live/file_api.py b/src/pipecat/services/gemini_multimodal_live/file_api.py index 39b7d9df9..2c79338b5 100644 --- a/src/pipecat/services/gemini_multimodal_live/file_api.py +++ b/src/pipecat/services/gemini_multimodal_live/file_api.py @@ -4,26 +4,29 @@ # SPDX-License-Identifier: BSD 2-Clause License # -import aiohttp import mimetypes -from typing import Dict, Any, Optional +from typing import Any, Dict, Optional +import aiohttp from loguru import logger + class GeminiFileAPI: """Client for the Gemini File API. - + This class provides methods for uploading, fetching, listing, and deleting files through Google's Gemini File API. - + Files uploaded through this API remain available for 48 hours and can be referenced in calls to the Gemini generative models. Maximum file size is 2GB, with total project storage limited to 20GB. """ - - def __init__(self, api_key: str, base_url: str = "https://generativelanguage.googleapis.com/v1beta/files"): + + def __init__( + self, api_key: str, base_url: str = "https://generativelanguage.googleapis.com/v1beta/files" + ): """Initialize the Gemini File API client. - + Args: api_key: Google AI API key base_url: Base URL for the Gemini File API (default is the v1beta endpoint) @@ -32,160 +35,148 @@ class GeminiFileAPI: self.base_url = base_url # Upload URL uses the /upload/ path self.upload_base_url = "https://generativelanguage.googleapis.com/upload/v1beta/files" - - async def upload_file(self, file_path: str, display_name: Optional[str] = None) -> Dict[str, Any]: + + async def upload_file( + self, file_path: str, display_name: Optional[str] = None + ) -> Dict[str, Any]: """Upload a file to the Gemini File API using the correct resumable upload protocol. - + Args: file_path: Path to the file to upload display_name: Optional display name for the file - + Returns: File metadata including uri, name, and display_name """ logger.info(f"Uploading file: {file_path}") - + async with aiohttp.ClientSession() as session: # Determine the file's MIME type mime_type, _ = mimetypes.guess_type(file_path) if not mime_type: mime_type = "application/octet-stream" - + # Read the file with open(file_path, "rb") as f: file_data = f.read() - + # Create the metadata payload metadata = {} if display_name: metadata = {"file": {"display_name": display_name}} - + # Step 1: Initial resumable request to get upload URL headers = { "X-Goog-Upload-Protocol": "resumable", "X-Goog-Upload-Command": "start", "X-Goog-Upload-Header-Content-Length": str(len(file_data)), "X-Goog-Upload-Header-Content-Type": mime_type, - "Content-Type": "application/json" + "Content-Type": "application/json", } - + logger.debug(f"Step 1: Getting upload URL from {self.upload_base_url}") async with session.post( - f"{self.upload_base_url}?key={self.api_key}", - headers=headers, - json=metadata + f"{self.upload_base_url}?key={self.api_key}", headers=headers, json=metadata ) as response: if response.status != 200: error_text = await response.text() logger.error(f"Error initiating file upload: {error_text}") raise Exception(f"Failed to initiate upload: {response.status} - {error_text}") - + # Get the upload URL from the response header upload_url = response.headers.get("X-Goog-Upload-URL") if not upload_url: logger.error(f"Response headers: {dict(response.headers)}") raise Exception("No upload URL in response headers") - + logger.debug(f"Got upload URL: {upload_url}") - + # Step 2: Upload the actual file data upload_headers = { "Content-Length": str(len(file_data)), "X-Goog-Upload-Offset": "0", - "X-Goog-Upload-Command": "upload, finalize" + "X-Goog-Upload-Command": "upload, finalize", } - + logger.debug(f"Step 2: Uploading file data to {upload_url}") - async with session.post( - upload_url, - headers=upload_headers, - data=file_data - ) as response: + async with session.post(upload_url, headers=upload_headers, data=file_data) as response: if response.status != 200: error_text = await response.text() logger.error(f"Error uploading file data: {error_text}") raise Exception(f"Failed to upload file: {response.status} - {error_text}") - + file_info = await response.json() logger.info(f"File uploaded successfully: {file_info.get('file', {}).get('name')}") return file_info - + async def get_file(self, name: str) -> Dict[str, Any]: """Get metadata for a file. - + Args: name: File name (or full path) - + Returns: File metadata """ # Extract just the name part if a full path is provided - if '/' in name: - name = name.split('/')[-1] - + if "/" in name: + name = name.split("/")[-1] + async with aiohttp.ClientSession() as session: - async with session.get( - f"{self.base_url}/{name}?key={self.api_key}" - ) as response: + async with session.get(f"{self.base_url}/{name}?key={self.api_key}") as response: if response.status != 200: error_text = await response.text() logger.error(f"Error getting file metadata: {error_text}") raise Exception(f"Failed to get file metadata: {response.status}") - + file_info = await response.json() return file_info - - async def list_files(self, page_size: int = 10, page_token: Optional[str] = None) -> Dict[str, Any]: + + async def list_files( + self, page_size: int = 10, page_token: Optional[str] = None + ) -> Dict[str, Any]: """List uploaded files. - + Args: page_size: Number of files to return per page page_token: Token for pagination - + Returns: List of files and next page token if available """ - params = { - "key": self.api_key, - "pageSize": page_size - } - + params = {"key": self.api_key, "pageSize": page_size} + if page_token: params["pageToken"] = page_token - + async with aiohttp.ClientSession() as session: - async with session.get( - self.base_url, - params=params - ) as response: + async with session.get(self.base_url, params=params) as response: if response.status != 200: error_text = await response.text() logger.error(f"Error listing files: {error_text}") raise Exception(f"Failed to list files: {response.status}") - + result = await response.json() return result - + async def delete_file(self, name: str) -> bool: """Delete a file. - + Args: name: File name (or full path) - + Returns: True if deleted successfully """ # Extract just the name part if a full path is provided - if '/' in name: - name = name.split('/')[-1] - + if "/" in name: + name = name.split("/")[-1] + async with aiohttp.ClientSession() as session: - async with session.delete( - f"{self.base_url}/{name}?key={self.api_key}" - ) as response: + async with session.delete(f"{self.base_url}/{name}?key={self.api_key}") as response: if response.status != 200: error_text = await response.text() logger.error(f"Error deleting file: {error_text}") raise Exception(f"Failed to delete file: {response.status}") - - return True + + return True diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 29d17e689..4d0090a41 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -59,11 +59,8 @@ from pipecat.processors.aggregators.openai_llm_context import ( OpenAILLMContextFrame, ) from pipecat.processors.frame_processor import FrameDirection -from pipecat.services.llm_service import FunctionCallFromLLM, LLMService from pipecat.services.google.frames import LLMSearchOrigin, LLMSearchResponseFrame, LLMSearchResult -from pipecat.services.llm_service import LLMService from pipecat.services.llm_service import FunctionCallFromLLM, LLMService - from pipecat.services.openai.llm import ( OpenAIAssistantContextAggregator, OpenAIUserContextAggregator, @@ -75,7 +72,6 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events -from .audio_transcriber import AudioTranscriber from .file_api import GeminiFileAPI try: @@ -226,9 +222,9 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): def add_file_reference(self, file_uri: str, mime_type: str, text: Optional[str] = None): """Add a file reference to the context. - + This adds a user message with a file reference that will be sent during context initialization. - + Args: file_uri: URI of the uploaded file mime_type: MIME type of the file @@ -238,15 +234,17 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts = [] if text: parts.append({"type": "text", "text": text}) - + # Add file reference part - parts.append({"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}}) - + parts.append( + {"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}} + ) + # Add to messages message = {"role": "user", "content": parts} self.messages.append(message) logger.info(f"Added file reference to context: {file_uri}") - + def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -273,12 +271,14 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -468,7 +468,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter - + def __init__( self, *, @@ -560,7 +560,7 @@ class GeminiMultimodalLiveLLMService(LLMService): else {}, "extra": params.extra if isinstance(params.extra, dict) else {}, } - + # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) @@ -1015,12 +1015,14 @@ class GeminiMultimodalLiveLLMService(LLMService): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -1167,7 +1169,9 @@ class GeminiMultimodalLiveLLMService(LLMService): # Process grounding metadata if we have accumulated any if self._accumulated_grounding_metadata: logger.debug("Processing grounding metadata...") - await self._process_grounding_metadata(self._accumulated_grounding_metadata, self._search_result_buffer) + await self._process_grounding_metadata( + self._accumulated_grounding_metadata, self._search_result_buffer + ) else: logger.debug("No grounding metadata to process") @@ -1285,17 +1289,23 @@ class GeminiMultimodalLiveLLMService(LLMService): async def _handle_evt_grounding_metadata(self, evt): """Handle dedicated grounding metadata events.""" logger.debug("Received dedicated grounding metadata event.") - + if evt.serverContent and evt.serverContent.groundingMetadata: grounding_metadata = evt.serverContent.groundingMetadata - logger.debug(f"Grounding data: {len(grounding_metadata.groundingChunks or [])} chunks, {len(grounding_metadata.groundingSupports or [])} supports") - + logger.debug( + f"Grounding data: {len(grounding_metadata.groundingChunks or [])} chunks, {len(grounding_metadata.groundingSupports or [])} supports" + ) + # Process the grounding metadata immediately await self._process_grounding_metadata(grounding_metadata, self._search_result_buffer) - async def _process_grounding_metadata(self, grounding_metadata: events.GroundingMetadata, search_result: str = ""): + async def _process_grounding_metadata( + self, grounding_metadata: events.GroundingMetadata, search_result: str = "" + ): """Process grounding metadata and emit LLMSearchResponseFrame.""" - logger.debug(f"Processing grounding metadata. Search result text length: {len(search_result)}") + logger.debug( + f"Processing grounding metadata. Search result text length: {len(search_result)}" + ) if not grounding_metadata: logger.warning("No grounding metadata provided to _process_grounding_metadata") return @@ -1304,49 +1314,47 @@ class GeminiMultimodalLiveLLMService(LLMService): # Extract rendered content for search suggestions rendered_content = None - if grounding_metadata.searchEntryPoint and grounding_metadata.searchEntryPoint.renderedContent: + if ( + grounding_metadata.searchEntryPoint + and grounding_metadata.searchEntryPoint.renderedContent + ): rendered_content = grounding_metadata.searchEntryPoint.renderedContent # Convert grounding chunks and supports to LLMSearchOrigin format origins = [] - + if grounding_metadata.groundingChunks and grounding_metadata.groundingSupports: # Create a mapping of chunk indices to origins chunk_to_origin = {} - + for index, chunk in enumerate(grounding_metadata.groundingChunks): if chunk.web: origin = LLMSearchOrigin( - site_uri=chunk.web.uri, - site_title=chunk.web.title, - results=[] + site_uri=chunk.web.uri, site_title=chunk.web.title, results=[] ) chunk_to_origin[index] = origin origins.append(origin) - + # Add grounding support results to the appropriate origins for support in grounding_metadata.groundingSupports: if support.segment and support.groundingChunkIndices: text = support.segment.text or "" confidence_scores = support.confidenceScores or [] - + # Add this result to all origins referenced by this support for chunk_index in support.groundingChunkIndices: if chunk_index in chunk_to_origin: - result = LLMSearchResult( - text=text, - confidence=confidence_scores - ) + result = LLMSearchResult(text=text, confidence=confidence_scores) chunk_to_origin[chunk_index].results.append(result) # Create and push the search response frame search_frame = LLMSearchResponseFrame( - search_result=search_result, - origins=origins, - rendered_content=rendered_content + search_result=search_result, origins=origins, rendered_content=rendered_content + ) + + logger.debug( + f"Emitting LLMSearchResponseFrame with {len(origins)} origins, rendered_content available: {rendered_content is not None}" ) - - logger.debug(f"Emitting LLMSearchResponseFrame with {len(origins)} origins, rendered_content available: {rendered_content is not None}") await self.push_frame(search_frame) def create_context_aggregator( From f1c9f5040b7808db2f2194621ce2c7b0fd28ccd5 Mon Sep 17 00:00:00 2001 From: vipyne Date: Tue, 1 Jul 2025 16:26:52 -0500 Subject: [PATCH 40/84] Update examples/foundational/26f-gemini-multimodal-live-files-api.py --- .../26f-gemini-multimodal-live-files-api.py | 158 +++++++++++------- 1 file changed, 95 insertions(+), 63 deletions(-) diff --git a/examples/foundational/26f-gemini-multimodal-live-files-api.py b/examples/foundational/26f-gemini-multimodal-live-files-api.py index 413830cf9..160cd5e1b 100644 --- a/examples/foundational/26f-gemini-multimodal-live-files-api.py +++ b/examples/foundational/26f-gemini-multimodal-live-files-api.py @@ -18,67 +18,87 @@ from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineParams, PipelineTask from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext from pipecat.services.gemini_multimodal_live.gemini import ( - GeminiMultimodalLiveLLMService, GeminiMultimodalLiveContext, + GeminiMultimodalLiveLLMService, ) -from pipecat.transports.base_transport import TransportParams -from pipecat.transports.network.small_webrtc import SmallWebRTCTransport -from pipecat.transports.network.webrtc_connection import SmallWebRTCConnection +from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.services.daily import DailyParams load_dotenv(override=True) +# We store functions so objects (e.g. SileroVADAnalyzer) don't get +# instantiated. The function will be called when the desired transport gets +# selected. +transport_params = { + "daily": lambda: DailyParams( + audio_in_enabled=True, + audio_out_enabled=True, + video_in_enabled=False, + vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), + ), + "twilio": lambda: FastAPIWebsocketParams( + audio_in_enabled=True, + audio_out_enabled=True, + video_in_enabled=False, + vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), + ), + "webrtc": lambda: TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + video_in_enabled=False, + vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), + ), +} + + +sample_file_path = "" + + async def create_sample_file(): - """Create a sample text file for testing the File API.""" - content = """# Sample Document for Gemini File API Test + if sample_file_path: + return sample_file_path + else: + """Create a sample text file for testing the File API.""" + content = """# Sample Document for Gemini File API Test -This is a test document to demonstrate the Gemini File API functionality. + This is a test document to demonstrate the Gemini File API functionality. -## Key Information: -- This document was created for testing purposes -- It contains information about AI assistants -- The document should be analyzed by Gemini -- The secret phrase for the test is "Pineapple Pizza" + ## Key Information: + - This document was created for testing purposes + - It contains information about AI assistants + - The document should be analyzed by Gemini + - The secret phrase for the test is "Pineapple Pizza" -## AI Assistant Capabilities: -1. Natural language processing -2. File analysis and understanding -3. Context-aware conversations -4. Multi-modal interactions + ## AI Assistant Capabilities: + 1. Natural language processing + 2. File analysis and understanding + 3. Context-aware conversations + 4. Multi-modal interactions -## Conclusion: -This document serves as a test case for the Gemini File API integration with Pipecat. -The AI should be able to reference and discuss the contents of this file. -""" - - # Create a temporary file - with tempfile.NamedTemporaryFile(mode='w', suffix='.txt', delete=False) as f: - f.write(content) - return f.name + ## Conclusion: + This document serves as a test case for the Gemini File API integration with Pipecat. + The AI should be able to reference and discuss the contents of this file. + """ + + # Create a temporary file + with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f: + f.write(content) + return f.name -async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespace): +async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): logger.info(f"Starting File API bot") # Create a sample file to upload sample_file_path = await create_sample_file() logger.info(f"Created sample file: {sample_file_path}") - # Initialize the SmallWebRTCTransport with the connection - transport = SmallWebRTCTransport( - webrtc_connection=webrtc_connection, - params=TransportParams( - audio_in_enabled=True, - audio_out_enabled=True, - video_in_enabled=False, - vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), - ), - ) - system_instruction = """ You are a helpful AI assistant with access to a document that has been uploaded for analysis. - The document contains test information including a secret phrase. You should be able to: + The document contains test information. + You should be able to: - Reference and discuss the contents of the uploaded document - Answer questions about what's in the document - Use the information from the document in our conversation @@ -100,15 +120,14 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac file_info = None try: file_info = await llm.file_api.upload_file( - sample_file_path, - display_name="Sample Test Document" + sample_file_path, display_name="Sample Test Document" ) logger.info(f"File uploaded successfully: {file_info['file']['name']}") - + # Get file URI and mime type file_uri = file_info["file"]["uri"] mime_type = "text/plain" - + # Create context with file reference context = OpenAILLMContext( [ @@ -117,22 +136,19 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac "content": [ { "type": "text", - "text": "Greet the user and let them know you have access to a document they can ask you about. Mention that you can discuss its contents." + "text": "Greet the user and let them know you have access to a document they can ask you about. Mention that you can discuss its contents.", }, { "type": "file_data", - "file_data": { - "mime_type": mime_type, - "file_uri": file_uri - } - } - ] + "file_data": {"mime_type": mime_type, "file_uri": file_uri}, + }, + ], } ] ) - + logger.info("File reference added to conversation context") - + except Exception as e: logger.error(f"Error uploading file: {e}") # Continue with a basic context if file upload fails @@ -140,7 +156,7 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac [ { "role": "user", - "content": "Greet the user and explain that there was an issue with file upload, but you're ready to help with other tasks." + "content": "Greet the user and explain that there was an issue with file upload, but you're ready to help with other tasks.", } ] ) @@ -149,13 +165,15 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac context_aggregator = llm.create_context_aggregator(context) # Build the pipeline - pipeline = Pipeline([ - transport.input(), - context_aggregator.user(), - llm, - transport.output(), - context_aggregator.assistant(), - ]) + pipeline = Pipeline( + [ + transport.input(), + context_aggregator.user(), + llm, + transport.output(), + context_aggregator.assistant(), + ] + ) # Configure the pipeline task task = PipelineTask( @@ -195,7 +213,7 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac logger.info("Cleaned up uploaded file from Gemini") except Exception as e: logger.error(f"Error cleaning up file: {e}") - + # Remove temporary file try: os.unlink(sample_file_path) @@ -205,6 +223,20 @@ async def run_bot(webrtc_connection: SmallWebRTCConnection, _: argparse.Namespac if __name__ == "__main__": - from run import main + from pipecat.examples.run import main - main() + upload_example_file = input(""" + + Please pass in a TEXT filepath to test upload. + NOTE: Files are stored on Google's servers for 48 hours. + + Press Enter to use a default test file. + + text filepath : """) + if upload_example_file: + print(f"Uploading file: {upload_example_file}") + sample_file_path = upload_example_file.strip() + else: + print(f"Using default file") + + main(run_example, transport_params=transport_params) From c7cbfe7a4ff6878ae4356e003f43a8d34a6d29b1 Mon Sep 17 00:00:00 2001 From: vipyne Date: Tue, 1 Jul 2025 17:17:13 -0500 Subject: [PATCH 41/84] remove grounding metadata commits --- .../services/gemini_multimodal_live/events.py | 74 +----------- .../gemini_multimodal_live/file_api.py | 14 +-- .../services/gemini_multimodal_live/gemini.py | 113 ------------------ 3 files changed, 11 insertions(+), 190 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/events.py b/src/pipecat/services/gemini_multimodal_live/events.py index 4687519c0..8fea91666 100644 --- a/src/pipecat/services/gemini_multimodal_live/events.py +++ b/src/pipecat/services/gemini_multimodal_live/events.py @@ -12,7 +12,6 @@ import json from enum import Enum from typing import List, Literal, Optional -from loguru import logger from PIL import Image from pydantic import BaseModel, Field @@ -249,55 +248,6 @@ class Config(BaseModel): setup: Setup -# -# Grounding metadata models -# - - -class SearchEntryPoint(BaseModel): - """Represents the search entry point with rendered content for search suggestions.""" - - renderedContent: Optional[str] = None - - -class WebSource(BaseModel): - """Represents a web source from grounding chunks.""" - - uri: Optional[str] = None - title: Optional[str] = None - - -class GroundingChunk(BaseModel): - """Represents a grounding chunk containing web source information.""" - - web: Optional[WebSource] = None - - -class GroundingSegment(BaseModel): - """Represents a segment of text that is grounded.""" - - startIndex: Optional[int] = None - endIndex: Optional[int] = None - text: Optional[str] = None - - -class GroundingSupport(BaseModel): - """Represents support information for grounded text segments.""" - - segment: Optional[GroundingSegment] = None - groundingChunkIndices: Optional[List[int]] = None - confidenceScores: Optional[List[float]] = None - - -class GroundingMetadata(BaseModel): - """Represents grounding metadata from Google Search.""" - - searchEntryPoint: Optional[SearchEntryPoint] = None - groundingChunks: Optional[List[GroundingChunk]] = None - groundingSupports: Optional[List[GroundingSupport]] = None - webSearchQueries: Optional[List[str]] = None - - # # Server events # @@ -389,7 +339,6 @@ class ServerContent(BaseModel): turnComplete: Optional[bool] = None inputTranscription: Optional[BidiGenerateContentTranscription] = None outputTranscription: Optional[BidiGenerateContentTranscription] = None - groundingMetadata: Optional[GroundingMetadata] = None class FunctionCall(BaseModel): @@ -482,7 +431,7 @@ class ServerEvent(BaseModel): usageMetadata: Optional[UsageMetadata] = None -def parse_server_event(message_str): +def parse_server_event(str): """Parse a server event from JSON string. Args: @@ -491,26 +440,11 @@ def parse_server_event(message_str): Returns: ServerEvent instance if parsing succeeds, None otherwise. """ - from loguru import logger # Import logger locally to avoid scoping issues - try: - evt_dict = json.loads(message_str) - - # Only log grounding metadata detection if truly needed for debugging - # In production, this could be removed entirely or moved to TRACE level - if "serverContent" in evt_dict: - server_content = evt_dict["serverContent"] - if "groundingMetadata" in server_content: - # Consider removing this log entirely for production - pass - - evt = ServerEvent.model_validate(evt_dict) - return evt + evt = json.loads(str) + return ServerEvent.model_validate(evt) except Exception as e: - logger.error(f"Error parsing server event: {e}") - # Truncate raw message to avoid logging potentially sensitive or overly long data - truncated_message = message_str[:200] + "..." if len(message_str) > 200 else message_str - logger.error(f"Raw message (truncated): {truncated_message}") + print(f"Error parsing server event: {e}") return None diff --git a/src/pipecat/services/gemini_multimodal_live/file_api.py b/src/pipecat/services/gemini_multimodal_live/file_api.py index 2c79338b5..f0f23ab83 100644 --- a/src/pipecat/services/gemini_multimodal_live/file_api.py +++ b/src/pipecat/services/gemini_multimodal_live/file_api.py @@ -31,8 +31,8 @@ class GeminiFileAPI: api_key: Google AI API key base_url: Base URL for the Gemini File API (default is the v1beta endpoint) """ - self.api_key = api_key - self.base_url = base_url + self._api_key = api_key + self._base_url = base_url # Upload URL uses the /upload/ path self.upload_base_url = "https://generativelanguage.googleapis.com/upload/v1beta/files" @@ -76,7 +76,7 @@ class GeminiFileAPI: logger.debug(f"Step 1: Getting upload URL from {self.upload_base_url}") async with session.post( - f"{self.upload_base_url}?key={self.api_key}", headers=headers, json=metadata + f"{self.upload_base_url}?key={self._api_key}", headers=headers, json=metadata ) as response: if response.status != 200: error_text = await response.text() @@ -123,7 +123,7 @@ class GeminiFileAPI: name = name.split("/")[-1] async with aiohttp.ClientSession() as session: - async with session.get(f"{self.base_url}/{name}?key={self.api_key}") as response: + async with session.get(f"{self._base_url}/{name}?key={self._api_key}") as response: if response.status != 200: error_text = await response.text() logger.error(f"Error getting file metadata: {error_text}") @@ -144,13 +144,13 @@ class GeminiFileAPI: Returns: List of files and next page token if available """ - params = {"key": self.api_key, "pageSize": page_size} + params = {"key": self._api_key, "pageSize": page_size} if page_token: params["pageToken"] = page_token async with aiohttp.ClientSession() as session: - async with session.get(self.base_url, params=params) as response: + async with session.get(self._base_url, params=params) as response: if response.status != 200: error_text = await response.text() logger.error(f"Error listing files: {error_text}") @@ -173,7 +173,7 @@ class GeminiFileAPI: name = name.split("/")[-1] async with aiohttp.ClientSession() as session: - async with session.delete(f"{self.base_url}/{name}?key={self.api_key}") as response: + async with session.delete(f"{self._base_url}/{name}?key={self._api_key}") as response: if response.status != 200: error_text = await response.text() logger.error(f"Error deleting file: {error_text}") diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 4d0090a41..9c49fdc21 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -564,10 +564,6 @@ class GeminiMultimodalLiveLLMService(LLMService): # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) - # Grounding metadata tracking - self._search_result_buffer = "" - self._accumulated_grounding_metadata = None - def can_generate_metrics(self) -> bool: """Check if the service can generate usage metrics. @@ -917,23 +913,12 @@ class GeminiMultimodalLiveLLMService(LLMService): await self._handle_evt_input_transcription(evt) elif evt.serverContent and evt.serverContent.outputTranscription: await self._handle_evt_output_transcription(evt) - elif evt.serverContent and evt.serverContent.groundingMetadata: - await self._handle_evt_grounding_metadata(evt) elif evt.toolCall: await self._handle_evt_tool_call(evt) elif False: # !!! todo: error events? await self._handle_evt_error(evt) # errors are fatal, so exit the receive loop return - else: - # Log unhandled events that might contain grounding metadata - logger.warning(f"Received unhandled server event type: {evt}") - pass - - async def _transcribe_audio_handler(self): - while True: - audio = await self._transcribe_audio_queue.get() - await self._handle_transcribe_user_audio(audio, self._context) # # @@ -1092,14 +1077,8 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.push_frame(LLMFullResponseStartFrame()) self._bot_text_buffer += text - self._search_result_buffer += text # Also accumulate for grounding await self.push_frame(LLMTextFrame(text=text)) - # Check for grounding metadata in server content - if evt.serverContent and evt.serverContent.groundingMetadata: - self._accumulated_grounding_metadata = evt.serverContent.groundingMetadata - logger.debug("Grounding metadata detected in model turn.") - inline_data = part.inlineData if not inline_data: return @@ -1166,20 +1145,6 @@ class GeminiMultimodalLiveLLMService(LLMService): self._llm_output_buffer = "" # Only push the TTSStoppedFrame if the bot is outputting audio - # Process grounding metadata if we have accumulated any - if self._accumulated_grounding_metadata: - logger.debug("Processing grounding metadata...") - await self._process_grounding_metadata( - self._accumulated_grounding_metadata, self._search_result_buffer - ) - else: - logger.debug("No grounding metadata to process") - - # Reset grounding tracking for next response - self._search_result_buffer = "" - self._accumulated_grounding_metadata = None - - # Only push the TTSStoppedFrame the bot is outputting audio # when text is found, modalities is set to TEXT and no audio # is produced. if not text: @@ -1257,13 +1222,6 @@ class GeminiMultimodalLiveLLMService(LLMService): # Collect text for tracing self._llm_output_buffer += text - # Accumulate text for grounding as well - self._search_result_buffer += text - - # Check for grounding metadata in server content - if evt.serverContent and evt.serverContent.groundingMetadata: - self._accumulated_grounding_metadata = evt.serverContent.groundingMetadata - await self.push_frame(LLMTextFrame(text=text)) await self.push_frame(TTSTextFrame(text=text)) @@ -1286,77 +1244,6 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.start_llm_usage_metrics(tokens) - async def _handle_evt_grounding_metadata(self, evt): - """Handle dedicated grounding metadata events.""" - logger.debug("Received dedicated grounding metadata event.") - - if evt.serverContent and evt.serverContent.groundingMetadata: - grounding_metadata = evt.serverContent.groundingMetadata - logger.debug( - f"Grounding data: {len(grounding_metadata.groundingChunks or [])} chunks, {len(grounding_metadata.groundingSupports or [])} supports" - ) - - # Process the grounding metadata immediately - await self._process_grounding_metadata(grounding_metadata, self._search_result_buffer) - - async def _process_grounding_metadata( - self, grounding_metadata: events.GroundingMetadata, search_result: str = "" - ): - """Process grounding metadata and emit LLMSearchResponseFrame.""" - logger.debug( - f"Processing grounding metadata. Search result text length: {len(search_result)}" - ) - if not grounding_metadata: - logger.warning("No grounding metadata provided to _process_grounding_metadata") - return - - # logger.debug(f"Processing grounding metadata: {grounding_metadata}") # Too verbose for PR - - # Extract rendered content for search suggestions - rendered_content = None - if ( - grounding_metadata.searchEntryPoint - and grounding_metadata.searchEntryPoint.renderedContent - ): - rendered_content = grounding_metadata.searchEntryPoint.renderedContent - - # Convert grounding chunks and supports to LLMSearchOrigin format - origins = [] - - if grounding_metadata.groundingChunks and grounding_metadata.groundingSupports: - # Create a mapping of chunk indices to origins - chunk_to_origin = {} - - for index, chunk in enumerate(grounding_metadata.groundingChunks): - if chunk.web: - origin = LLMSearchOrigin( - site_uri=chunk.web.uri, site_title=chunk.web.title, results=[] - ) - chunk_to_origin[index] = origin - origins.append(origin) - - # Add grounding support results to the appropriate origins - for support in grounding_metadata.groundingSupports: - if support.segment and support.groundingChunkIndices: - text = support.segment.text or "" - confidence_scores = support.confidenceScores or [] - - # Add this result to all origins referenced by this support - for chunk_index in support.groundingChunkIndices: - if chunk_index in chunk_to_origin: - result = LLMSearchResult(text=text, confidence=confidence_scores) - chunk_to_origin[chunk_index].results.append(result) - - # Create and push the search response frame - search_frame = LLMSearchResponseFrame( - search_result=search_result, origins=origins, rendered_content=rendered_content - ) - - logger.debug( - f"Emitting LLMSearchResponseFrame with {len(origins)} origins, rendered_content available: {rendered_content is not None}" - ) - await self.push_frame(search_frame) - def create_context_aggregator( self, context: OpenAILLMContext, From 0e60385871cd98a3add12911ab58ae2c224f0a60 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 9 May 2025 10:50:27 -0400 Subject: [PATCH 42/84] add FileAPI to gemini.py --- .../services/gemini_multimodal_live/gemini.py | 94 +++++++++++++++++-- 1 file changed, 87 insertions(+), 7 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 9c49fdc21..5a0f66400 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -72,6 +72,7 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events +from .audio_transcriber import AudioTranscriber from .file_api import GeminiFileAPI try: @@ -222,9 +223,9 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): def add_file_reference(self, file_uri: str, mime_type: str, text: Optional[str] = None): """Add a file reference to the context. - + This adds a user message with a file reference that will be sent during context initialization. - + Args: file_uri: URI of the uploaded file mime_type: MIME type of the file @@ -234,17 +235,19 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts = [] if text: parts.append({"type": "text", "text": text}) - + # Add file reference part - parts.append( - {"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}} - ) - + parts.append({"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}}) + # Add to messages message = {"role": "user", "content": parts} self.messages.append(message) logger.info(f"Added file reference to context: {file_uri}") +<<<<<<< HEAD +======= + +>>>>>>> cd4a893c (add FileAPI to gemini.py) def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -271,6 +274,7 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) +<<<<<<< HEAD parts.append( { "fileData": { @@ -279,6 +283,14 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): } } ) +======= + parts.append({ + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri") + } + }) +>>>>>>> cd4a893c (add FileAPI to gemini.py) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -469,6 +481,62 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter + """Gemini Live LLM Service with multimodal capabilities including File API support. + + This service implements the Gemini Multimodal Live API with support for: + - Audio input and output + - Image/video input + - File API (upload, reference, and management) + - Tools/function calling + + Example usage of File API: + ```python + # Initialize the service + gemini_service = GeminiMultimodalLiveLLMService(api_key="YOUR_API_KEY") + + # Upload a file from the client + file_path = "/path/to/user_uploaded_file.pdf" + file_info = await gemini_service.file_api.upload_file(file_path) + + # Get file URI and mime type from response + file_uri = file_info["file"]["uri"] + mime_type = "application/pdf" # Set appropriate MIME type + + # When starting a new bot session: + # 1. Initialize the context + context = GeminiMultimodalLiveContext() + + # 2. Add file reference to context BEFORE starting the conversation + context.add_file_reference( + file_uri=file_uri, + mime_type=mime_type, + text="Please analyze this document" + ) + + # 3. Now set the context to start the conversation with file reference included + await gemini_service.set_context(context) + + # Gemini now has access to the file reference in its context window + # The file URI remains valid for 48 hours before Google deletes it + + # Optional: List all files for this user + files = await gemini_service.file_api.list_files() + + # Optional: Get metadata for a specific file + file_metadata = await gemini_service.file_api.get_file(file_info["file"]["name"]) + + # Optional: Delete a file when no longer needed + await gemini_service.file_api.delete_file(file_info["file"]["name"]) + ``` + + Notes: + - Files are stored for 48 hours on Google's servers + - Maximum file size is 2GB + - Total storage per project is 20GB + - File references should be added to the context BEFORE starting the conversation + - The same file reference can be reused for multiple sessions within the 48-hour window + """ + def __init__( self, *, @@ -560,6 +628,9 @@ class GeminiMultimodalLiveLLMService(LLMService): else {}, "extra": params.extra if isinstance(params.extra, dict) else {}, } + + # Initialize the File API client + self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) @@ -1000,6 +1071,7 @@ class GeminiMultimodalLiveLLMService(LLMService): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) +<<<<<<< HEAD parts.append( { "fileData": { @@ -1008,6 +1080,14 @@ class GeminiMultimodalLiveLLMService(LLMService): } } ) +======= + parts.append({ + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri") + } + }) +>>>>>>> cd4a893c (add FileAPI to gemini.py) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: From 58aedc88a4bd26071a5b5cc5ac3bf4bf14132483 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Tue, 1 Jul 2025 16:57:07 -0700 Subject: [PATCH 43/84] DailyTransport: allow receiving audio in a single track --- CHANGELOG.md | 5 +- pyproject.toml | 4 +- src/pipecat/transports/services/daily.py | 91 ++++++++++++++++++++---- 3 files changed, 85 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f1f7d347..029fc2ed9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added new `DailyParams.audio_in_user_tracks` to allow receiving one track per + user (default) or a single track from the room (all participants mixed). + - Added support for providing "direct" functions, which don't need an accompanying `FunctionSchema` or function definition dict. Instead, metadata (i.e. `name`, `description`, `properties`, and `required`) are automatically @@ -53,7 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed -- Fixed a race condition that occurs in Python 3.10+ where the task could miss +- Fixed a race condition that occurs in Python 3.10+ where the task could miss the `CancelledError` and continue running indefinitely, freezing the pipeline. - Fixed a `AWSNovaSonicLLMService` issue introduced in 0.0.72. diff --git a/pyproject.toml b/pyproject.toml index 489da06dd..b364020ab 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,7 @@ classifiers = [ dependencies = [ "aiohttp~=3.11.12", "audioop-lts~=0.2.1; python_version>='3.13'", + "docstring_parser~=0.16", "loguru~=0.7.3", "Markdown~=3.7", "numpy~=1.26.4", @@ -32,7 +33,6 @@ dependencies = [ "resampy~=0.4.3", "soxr~=0.5.0", "openai~=1.70.0", - "docstring_parser~=0.16" ] [project.urls] @@ -131,7 +131,7 @@ ignore = [ [tool.ruff.lint.per-file-ignores] # Skip docstring checks for non-source code "examples/**/*.py" = ["D"] -"tests/**/*.py" = ["D"] +"tests/**/*.py" = ["D"] "scripts/**/*.py" = ["D"] "docs/**/*.py" = ["D"] # Skip D104 (missing docstring in public package) for __init__.py files diff --git a/src/pipecat/transports/services/daily.py b/src/pipecat/transports/services/daily.py index b62aa4b6e..a404f7648 100644 --- a/src/pipecat/transports/services/daily.py +++ b/src/pipecat/transports/services/daily.py @@ -27,6 +27,7 @@ from pipecat.frames.frames import ( EndFrame, ErrorFrame, Frame, + InputAudioRawFrame, InterimTranscriptionFrame, OutputAudioRawFrame, OutputDTMFFrame, @@ -59,6 +60,7 @@ try: EventHandler, VideoFrame, VirtualCameraDevice, + VirtualSpeakerDevice, ) except ModuleNotFoundError as e: logger.error(f"Exception: {e}") @@ -177,6 +179,7 @@ class DailyParams(TransportParams): Parameters: api_url: Daily API base URL. api_key: Daily API authentication key. + audio_in_user_tracks: Receive users' audio in separate tracks dialin_settings: Optional settings for dial-in functionality. camera_out_enabled: Whether to enable the main camera output track. microphone_out_enabled: Whether to enable the main microphone track. @@ -186,6 +189,7 @@ class DailyParams(TransportParams): api_url: str = "https://api.daily.co/v1" api_key: str = "" + audio_in_user_tracks: bool = True dialin_settings: Optional[DailyDialinSettings] = None camera_out_enabled: bool = True microphone_out_enabled: bool = True @@ -372,13 +376,18 @@ class DailyTransportClient(EventHandler): self._out_sample_rate = 0 self._camera: Optional[VirtualCameraDevice] = None + self._speaker: Optional[VirtualSpeakerDevice] = None self._microphone_track: Optional[DailyAudioTrack] = None self._custom_audio_tracks: Dict[str, DailyAudioTrack] = {} def _camera_name(self): - """Generate a unique camera name for this client instance.""" + """Generate a unique virtual camera name for this client instance.""" return f"camera-{self}" + def _speaker_name(self): + """Generate a unique virtual speaker name for this client instance.""" + return f"speaker-{self}" + @property def room_url(self) -> str: """Get the Daily room URL. @@ -434,6 +443,30 @@ class DailyTransportClient(EventHandler): ) await future + async def read_next_audio_frame(self) -> Optional[InputAudioRawFrame]: + """Reads the next 20ms audio frame from the virtual speaker.""" + if not self._speaker: + return None + + sample_rate = self._in_sample_rate + num_channels = self._params.audio_in_channels + num_frames = int(sample_rate / 100) * 2 # 20ms of audio + + future = self._get_event_loop().create_future() + self._speaker.read_frames(num_frames, completion=completion_callback(future)) + audio = await future + + if len(audio) > 0: + return InputAudioRawFrame( + audio=audio, sample_rate=sample_rate, num_channels=num_channels + ) + else: + # If we don't read any audio it could be there's no participant + # connected. daily-python will return immediately if that's the + # case, so let's sleep for a little bit (i.e. busy wait). + await asyncio.sleep(0.01) + return None + async def register_audio_destination(self, destination: str): """Register a custom audio destination for multi-track output. @@ -518,12 +551,21 @@ class DailyTransportClient(EventHandler): self._in_sample_rate = self._params.audio_in_sample_rate or frame.audio_in_sample_rate self._out_sample_rate = self._params.audio_out_sample_rate or frame.audio_out_sample_rate - if self._params.audio_in_enabled and not self._audio_task and self._task_manager: - self._audio_queue = WatchdogQueue(self._task_manager) - self._audio_task = self._task_manager.create_task( - self._callback_task_handler(self._audio_queue), - f"{self}::audio_callback_task", - ) + if self._params.audio_in_enabled: + if self._params.audio_in_user_tracks and not self._audio_task: + self._audio_queue = WatchdogQueue(self._task_manager) + self._audio_task = self._task_manager.create_task( + self._callback_task_handler(self._audio_queue), + f"{self}::audio_callback_task", + ) + elif not self._speaker: + self._speaker = Daily.create_speaker_device( + self._speaker_name(), + sample_rate=self._in_sample_rate, + channels=self._params.audio_in_channels, + non_blocking=True, + ) + Daily.select_speaker_device(self._speaker_name()) if self._params.video_in_enabled and not self._video_task and self._task_manager: self._video_queue = WatchdogQueue(self._task_manager) @@ -1332,6 +1374,9 @@ class DailyInputTransport(BaseInputTransport): # case we don't start streaming right away. self._capture_participant_audio = [] + # Audio task when using a virtual speaker (i.e. no user tracks). + self._audio_in_task: Optional[asyncio.Task] = None + self._vad_analyzer: Optional[VADAnalyzer] = params.vad_analyzer @property @@ -1349,10 +1394,18 @@ class DailyInputTransport(BaseInputTransport): return logger.debug(f"Start receiving audio") - for participant_id, audio_source, sample_rate in self._capture_participant_audio: - await self._client.capture_participant_audio( - participant_id, self._on_participant_audio_data, audio_source, sample_rate - ) + + if self._params.audio_in_enabled: + if self._params.audio_in_user_tracks: + # Capture invididual participant tracks. + for participant_id, audio_source, sample_rate in self._capture_participant_audio: + await self._client.capture_participant_audio( + participant_id, self._on_participant_audio_data, audio_source, sample_rate + ) + elif not self._audio_in_task: + # Create audio task. It reads audio frames from a single room + # track and pushes them internally for VAD processing. + self._audio_in_task = self.create_task(self._audio_in_task_handler()) self._streaming_started = True @@ -1407,6 +1460,10 @@ class DailyInputTransport(BaseInputTransport): await super().stop(frame) # Leave the room. await self._client.leave() + # Stop audio thread. + if self._audio_in_task: + await self.cancel_task(self._audio_in_task) + self._audio_in_task = None async def cancel(self, frame: CancelFrame): """Cancel the input transport and leave the Daily room. @@ -1418,6 +1475,10 @@ class DailyInputTransport(BaseInputTransport): await super().cancel(frame) # Leave the room. await self._client.leave() + # Stop audio thread. + if self._audio_in_task: + await self.cancel_task(self._audio_in_task) + self._audio_in_task = None # # FrameProcessor @@ -1494,6 +1555,12 @@ class DailyInputTransport(BaseInputTransport): frame.transport_source = audio_source await self.push_audio_frame(frame) + async def _audio_in_task_handler(self): + while True: + frame = await self._client.read_next_audio_frame() + if frame: + await self.push_audio_frame(frame) + # # Camera in # @@ -2175,7 +2242,7 @@ class DailyTransport(BaseTransport): id = participant["id"] logger.info(f"Participant joined {id}") - if self._input and self._params.audio_in_enabled: + if self._input and self._params.audio_in_enabled and self._params.audio_in_user_tracks: await self._input.capture_participant_audio( id, "microphone", self._client.in_sample_rate ) From 2ee935f784319b9b0c2ef9f14f485a259f5cb3e6 Mon Sep 17 00:00:00 2001 From: getchannel <78183014+getchannel@users.noreply.github.com> Date: Fri, 30 May 2025 12:19:40 -0400 Subject: [PATCH 44/84] Update gemini.py --- .../services/gemini_multimodal_live/gemini.py | 56 ------------------- 1 file changed, 56 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 5a0f66400..9a196765a 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -480,63 +480,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter - - """Gemini Live LLM Service with multimodal capabilities including File API support. - This service implements the Gemini Multimodal Live API with support for: - - Audio input and output - - Image/video input - - File API (upload, reference, and management) - - Tools/function calling - - Example usage of File API: - ```python - # Initialize the service - gemini_service = GeminiMultimodalLiveLLMService(api_key="YOUR_API_KEY") - - # Upload a file from the client - file_path = "/path/to/user_uploaded_file.pdf" - file_info = await gemini_service.file_api.upload_file(file_path) - - # Get file URI and mime type from response - file_uri = file_info["file"]["uri"] - mime_type = "application/pdf" # Set appropriate MIME type - - # When starting a new bot session: - # 1. Initialize the context - context = GeminiMultimodalLiveContext() - - # 2. Add file reference to context BEFORE starting the conversation - context.add_file_reference( - file_uri=file_uri, - mime_type=mime_type, - text="Please analyze this document" - ) - - # 3. Now set the context to start the conversation with file reference included - await gemini_service.set_context(context) - - # Gemini now has access to the file reference in its context window - # The file URI remains valid for 48 hours before Google deletes it - - # Optional: List all files for this user - files = await gemini_service.file_api.list_files() - - # Optional: Get metadata for a specific file - file_metadata = await gemini_service.file_api.get_file(file_info["file"]["name"]) - - # Optional: Delete a file when no longer needed - await gemini_service.file_api.delete_file(file_info["file"]["name"]) - ``` - - Notes: - - Files are stored for 48 hours on Google's servers - - Maximum file size is 2GB - - Total storage per project is 20GB - - File references should be added to the context BEFORE starting the conversation - - The same file reference can be reused for multiple sessions within the 48-hour window - """ - def __init__( self, *, From 9c9d4b35a433f58f1f109febc3a1be349db2736d Mon Sep 17 00:00:00 2001 From: Pete <78183014+getchannel@users.noreply.github.com> Date: Tue, 10 Jun 2025 11:22:16 -0400 Subject: [PATCH 45/84] remove audio_transcriber from gemini.py unecessary import removed. --- .../services/gemini_multimodal_live/gemini.py | 28 +------------------ 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 9a196765a..19860387e 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -72,7 +72,7 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events -from .audio_transcriber import AudioTranscriber + from .file_api import GeminiFileAPI try: @@ -243,11 +243,7 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): message = {"role": "user", "content": parts} self.messages.append(message) logger.info(f"Added file reference to context: {file_uri}") -<<<<<<< HEAD - -======= ->>>>>>> cd4a893c (add FileAPI to gemini.py) def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -274,23 +270,12 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) -<<<<<<< HEAD - parts.append( - { - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri"), - } - } - ) -======= parts.append({ "fileData": { "mimeType": file_data.get("mime_type"), "fileUri": file_data.get("file_uri") } }) ->>>>>>> cd4a893c (add FileAPI to gemini.py) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -1015,23 +1000,12 @@ class GeminiMultimodalLiveLLMService(LLMService): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) -<<<<<<< HEAD - parts.append( - { - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri"), - } - } - ) -======= parts.append({ "fileData": { "mimeType": file_data.get("mime_type"), "fileUri": file_data.get("file_uri") } }) ->>>>>>> cd4a893c (add FileAPI to gemini.py) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: From 1ab2ddd317715c3252528bf14a133d920f61cb26 Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Tue, 1 Jul 2025 23:55:34 -0700 Subject: [PATCH 46/84] fix lint error --- .../services/gemini_multimodal_live/gemini.py | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index f278ca3d4..1fd6e7bbf 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -72,7 +72,6 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events - from .file_api import GeminiFileAPI try: @@ -223,9 +222,9 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): def add_file_reference(self, file_uri: str, mime_type: str, text: Optional[str] = None): """Add a file reference to the context. - + This adds a user message with a file reference that will be sent during context initialization. - + Args: file_uri: URI of the uploaded file mime_type: MIME type of the file @@ -235,15 +234,17 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts = [] if text: parts.append({"type": "text", "text": text}) - + # Add file reference part - parts.append({"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}}) - + parts.append( + {"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}} + ) + # Add to messages message = {"role": "user", "content": parts} self.messages.append(message) logger.info(f"Added file reference to context: {file_uri}") - + def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -270,12 +271,14 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -465,7 +468,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter - + def __init__( self, *, @@ -557,7 +560,7 @@ class GeminiMultimodalLiveLLMService(LLMService): else {}, "extra": params.extra if isinstance(params.extra, dict) else {}, } - + # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) @@ -1011,12 +1014,14 @@ class GeminiMultimodalLiveLLMService(LLMService): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: From 4bcc536fd2d93d3c70dcbe088f7e4e278926bd1f Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Wed, 2 Jul 2025 00:03:27 -0700 Subject: [PATCH 47/84] added arg description in docstring for gemini live init --- src/pipecat/services/gemini_multimodal_live/gemini.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 1fd6e7bbf..f873e9d84 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -499,6 +499,7 @@ class GeminiMultimodalLiveLLMService(LLMService): params: Configuration parameters for the model. Defaults to InputParams(). inference_on_context_initialization: Whether to generate a response when context is first set. Defaults to True. + file_api_base_url: Base URL for the file API. Defaults to the official Gemini Live endpoint. **kwargs: Additional arguments passed to parent LLMService. """ super().__init__(base_url=base_url, **kwargs) From 18817fd81be87454ca1bea404fee62d06b616226 Mon Sep 17 00:00:00 2001 From: Yousif Astarabadi <6870090+yousifa@users.noreply.github.com> Date: Wed, 2 Jul 2025 00:09:48 -0700 Subject: [PATCH 48/84] added docstring in public GeminiFileAPI module --- src/pipecat/services/gemini_multimodal_live/file_api.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/pipecat/services/gemini_multimodal_live/file_api.py b/src/pipecat/services/gemini_multimodal_live/file_api.py index f0f23ab83..1324d4ee8 100644 --- a/src/pipecat/services/gemini_multimodal_live/file_api.py +++ b/src/pipecat/services/gemini_multimodal_live/file_api.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Gemini File API client for uploading and managing files. + +This module provides the GeminiFileAPI class for interacting with Google's Gemini File API, +including uploading, fetching, listing, and deleting files that can be used with Gemini +generative models. +""" + import mimetypes from typing import Any, Dict, Optional From 5328f84df410552620f3cb2d0592a17b747a857b Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 12:06:15 -0300 Subject: [PATCH 49/84] Fixed an issue to disconnect the iOS chatbot demo. --- .../SimpleChatbot.xcodeproj/project.pbxproj | 23 ++++++++++++------- .../xcshareddata/swiftpm/Package.resolved | 15 ++++++------ .../model/CallContainerModel.swift | 7 +++--- 3 files changed, 27 insertions(+), 18 deletions(-) diff --git a/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.pbxproj b/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.pbxproj index 0c770e711..478f90bbd 100644 --- a/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.pbxproj +++ b/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.pbxproj @@ -15,7 +15,6 @@ 90031FC22C616EE900408370 /* SimpleChatbotUITests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90031FC12C616EE900408370 /* SimpleChatbotUITests.swift */; }; 90031FC42C616EE900408370 /* SimpleChatbotUITestsLaunchTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90031FC32C616EE900408370 /* SimpleChatbotUITestsLaunchTests.swift */; }; 90031FDC2C6D5DD700408370 /* ToastModifier.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90031FDB2C6D5DD700408370 /* ToastModifier.swift */; }; - 907C98842D37E6AF0079441F /* PipecatClientIOSDaily in Frameworks */ = {isa = PBXBuildFile; productRef = 907C98832D37E6AF0079441F /* PipecatClientIOSDaily */; }; 90ABB98E2C735ED6000D9CC7 /* MeetingView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB98D2C735ED6000D9CC7 /* MeetingView.swift */; }; 90ABB9902C736A8B000D9CC7 /* WaveformView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB98F2C736A8B000D9CC7 /* WaveformView.swift */; }; 90ABB9932C73820D000D9CC7 /* MicrophoneView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB9922C73820D000D9CC7 /* MicrophoneView.swift */; }; @@ -25,6 +24,8 @@ 90ABB9A32C74E1CE000D9CC7 /* SettingsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB9A22C74E1CE000D9CC7 /* SettingsView.swift */; }; 90ABB9A62C74EA8A000D9CC7 /* SettingsPreference.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB9A52C74EA8A000D9CC7 /* SettingsPreference.swift */; }; 90ABB9A82C74EAB1000D9CC7 /* SettingsManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90ABB9A72C74EAB1000D9CC7 /* SettingsManager.swift */; }; + 90CC98B02E158093003C2706 /* PipecatClientIOSDaily in Frameworks */ = {isa = PBXBuildFile; productRef = 90CC98AF2E158093003C2706 /* PipecatClientIOSDaily */; }; + 90CC98B62E15820B003C2706 /* PipecatClientIOSDaily in Frameworks */ = {isa = PBXBuildFile; productRef = 90CC98B52E15820B003C2706 /* PipecatClientIOSDaily */; }; /* End PBXBuildFile section */ /* Begin PBXContainerItemProxy section */ @@ -73,7 +74,8 @@ isa = PBXFrameworksBuildPhase; buildActionMask = 2147483647; files = ( - 907C98842D37E6AF0079441F /* PipecatClientIOSDaily in Frameworks */, + 90CC98B62E15820B003C2706 /* PipecatClientIOSDaily in Frameworks */, + 90CC98B02E158093003C2706 /* PipecatClientIOSDaily in Frameworks */, ); runOnlyForDeploymentPostprocessing = 0; }; @@ -218,7 +220,8 @@ ); name = SimpleChatbot; packageProductDependencies = ( - 907C98832D37E6AF0079441F /* PipecatClientIOSDaily */, + 90CC98AF2E158093003C2706 /* PipecatClientIOSDaily */, + 90CC98B52E15820B003C2706 /* PipecatClientIOSDaily */, ); productName = SimpleChatbot; productReference = 90031FA32C616EE700408370 /* SimpleChatbot.app */; @@ -293,7 +296,7 @@ ); mainGroup = 90031F9A2C616EE700408370; packageReferences = ( - 907C98822D37E6AF0079441F /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */, + 90CC98B42E15820B003C2706 /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */, ); productRefGroup = 90031FA42C616EE700408370 /* Products */; projectDirPath = ""; @@ -682,20 +685,24 @@ /* End XCConfigurationList section */ /* Begin XCRemoteSwiftPackageReference section */ - 907C98822D37E6AF0079441F /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */ = { + 90CC98B42E15820B003C2706 /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */ = { isa = XCRemoteSwiftPackageReference; repositoryURL = "https://github.com/pipecat-ai/pipecat-client-ios-daily/"; requirement = { kind = upToNextMajorVersion; - minimumVersion = 0.3.2; + minimumVersion = 0.3.6; }; }; /* End XCRemoteSwiftPackageReference section */ /* Begin XCSwiftPackageProductDependency section */ - 907C98832D37E6AF0079441F /* PipecatClientIOSDaily */ = { + 90CC98AF2E158093003C2706 /* PipecatClientIOSDaily */ = { isa = XCSwiftPackageProductDependency; - package = 907C98822D37E6AF0079441F /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */; + productName = PipecatClientIOSDaily; + }; + 90CC98B52E15820B003C2706 /* PipecatClientIOSDaily */ = { + isa = XCSwiftPackageProductDependency; + package = 90CC98B42E15820B003C2706 /* XCRemoteSwiftPackageReference "pipecat-client-ios-daily" */; productName = PipecatClientIOSDaily; }; /* End XCSwiftPackageProductDependency section */ diff --git a/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved b/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved index 9cdcbc713..a81425dd0 100644 --- a/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved +++ b/examples/simple-chatbot/client/ios/SimpleChatbot.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved @@ -1,12 +1,13 @@ { + "originHash" : "cc17f08b06def9570d775e9c6f7a8dc10d1588b98127e977c47d052abac659b7", "pins" : [ { "identity" : "daily-client-ios", "kind" : "remoteSourceControl", "location" : "https://github.com/daily-co/daily-client-ios.git", "state" : { - "revision" : "15804ce495780da3ec2d05ab99736315f7bfbd24", - "version" : "0.28.0" + "revision" : "431938db25e5807120e89e2dc5bab1c076729f59", + "version" : "0.31.0" } }, { @@ -14,8 +15,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/pipecat-ai/pipecat-client-ios.git", "state" : { - "revision" : "c679512e367002a1a67da85d503fec72d9b17191", - "version" : "0.3.2" + "revision" : "f92b5e68e56a8311f7d8ead68a7a5674843cbc40", + "version" : "0.3.6" } }, { @@ -23,10 +24,10 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/pipecat-ai/pipecat-client-ios-daily/", "state" : { - "revision" : "a337fe6642c52376d2f90eafcb965f5be772ce72", - "version" : "0.3.2" + "revision" : "8f494da903192c22c367ecf9e51248c9b651fbc6", + "version" : "0.3.6" } } ], - "version" : 2 + "version" : 3 } diff --git a/examples/simple-chatbot/client/ios/SimpleChatbot/model/CallContainerModel.swift b/examples/simple-chatbot/client/ios/SimpleChatbot/model/CallContainerModel.swift index d8db7cced..b8663bb3b 100644 --- a/examples/simple-chatbot/client/ios/SimpleChatbot/model/CallContainerModel.swift +++ b/examples/simple-chatbot/client/ios/SimpleChatbot/model/CallContainerModel.swift @@ -78,10 +78,11 @@ class CallContainerModel: ObservableObject { self.saveCredentials(backendURL: baseUrl) } - @MainActor func disconnect() { - self.rtviClientIOS?.disconnect(completion: nil) - self.rtviClientIOS?.release() + Task { @MainActor in + try await self.rtviClientIOS?.disconnect() + self.rtviClientIOS?.release() + } } func showError(message: String) { From e71cb3ba68f82c6938cc58d3798495a6e3553e8c Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 2 Jul 2025 07:27:29 -0700 Subject: [PATCH 50/84] Docstring cleanup, fix missing examples imports --- .../daily-multi-translation/requirements.txt | 2 +- .../open-telemetry/jaeger/requirements.txt | 2 +- .../open-telemetry/langfuse/requirements.txt | 2 +- .../daily-twilio-sip-dial-in/requirements.txt | 2 +- .../observers/loggers/debug_log_observer.py | 5 ++-- src/pipecat/processors/aggregators/gated.py | 23 ------------------- .../processors/aggregators/sentence.py | 14 ++--------- .../aggregators/vision_image_frame.py | 11 --------- src/pipecat/processors/text_transformer.py | 8 ------- src/pipecat/utils/utils.py | 19 --------------- 10 files changed, 9 insertions(+), 79 deletions(-) diff --git a/examples/daily-multi-translation/requirements.txt b/examples/daily-multi-translation/requirements.txt index e20c41d5a..f75f059d7 100644 --- a/examples/daily-multi-translation/requirements.txt +++ b/examples/daily-multi-translation/requirements.txt @@ -2,4 +2,4 @@ aiofiles python-dotenv fastapi[all] uvicorn -pipecat-ai[daily,deepgram,openai,silero,cartesia] +pipecat-ai[daily,deepgram,openai,silero,cartesia,soundfile] diff --git a/examples/open-telemetry/jaeger/requirements.txt b/examples/open-telemetry/jaeger/requirements.txt index 7f5abb16d..344a0560e 100644 --- a/examples/open-telemetry/jaeger/requirements.txt +++ b/examples/open-telemetry/jaeger/requirements.txt @@ -1,6 +1,6 @@ fastapi uvicorn python-dotenv -pipecat-ai[webrtc,silero,cartesia,deepgram,openai,tracing] +pipecat-ai[daily,webrtc,silero,cartesia,deepgram,openai,tracing] pipecat-ai-small-webrtc-prebuilt opentelemetry-exporter-otlp-proto-grpc \ No newline at end of file diff --git a/examples/open-telemetry/langfuse/requirements.txt b/examples/open-telemetry/langfuse/requirements.txt index fe0f32468..6f06ac809 100644 --- a/examples/open-telemetry/langfuse/requirements.txt +++ b/examples/open-telemetry/langfuse/requirements.txt @@ -1,6 +1,6 @@ fastapi uvicorn python-dotenv -pipecat-ai[webrtc,silero,cartesia,deepgram,openai,tracing] +pipecat-ai[daily,webrtc,silero,cartesia,deepgram,openai,tracing] pipecat-ai-small-webrtc-prebuilt opentelemetry-exporter-otlp-proto-http \ No newline at end of file diff --git a/examples/phone-chatbot/daily-twilio-sip-dial-in/requirements.txt b/examples/phone-chatbot/daily-twilio-sip-dial-in/requirements.txt index cd12dd07a..1ba848312 100644 --- a/examples/phone-chatbot/daily-twilio-sip-dial-in/requirements.txt +++ b/examples/phone-chatbot/daily-twilio-sip-dial-in/requirements.txt @@ -1,4 +1,4 @@ -pipecat-ai[daily,elevenlabs,openai,silero] +pipecat-ai[daily,cartesia,openai,silero] fastapi==0.115.6 uvicorn python-dotenv diff --git a/src/pipecat/observers/loggers/debug_log_observer.py b/src/pipecat/observers/loggers/debug_log_observer.py index a8cf7d2d3..abb0db8d7 100644 --- a/src/pipecat/observers/loggers/debug_log_observer.py +++ b/src/pipecat/observers/loggers/debug_log_observer.py @@ -47,7 +47,7 @@ class DebugLogObserver(BaseObserver): Log specific frame types from any source/destination:: - from pipecat.frames.frames import TranscriptionFrame, InterimTranscriptionFrame + from pipecat.frames.frames import LLMTextFrame, TranscriptionFrame observers=[ DebugLogObserver(frame_types=(LLMTextFrame,TranscriptionFrame,)), ] @@ -55,7 +55,8 @@ class DebugLogObserver(BaseObserver): Log frames with specific source/destination filters:: from pipecat.frames.frames import StartInterruptionFrame, UserStartedSpeakingFrame, LLMTextFrame - from pipecat.transports.base_output_transport import BaseOutputTransport + from pipecat.observers.loggers.debug_log_observer import DebugLogObserver, FrameEndpoint + from pipecat.transports.base_output import BaseOutputTransport from pipecat.services.stt_service import STTService observers=[ diff --git a/src/pipecat/processors/aggregators/gated.py b/src/pipecat/processors/aggregators/gated.py index 33f80247d..cb153cde9 100644 --- a/src/pipecat/processors/aggregators/gated.py +++ b/src/pipecat/processors/aggregators/gated.py @@ -26,29 +26,6 @@ class GatedAggregator(FrameProcessor): until and not including the gate-closed frame. The aggregator maintains an internal gate state that controls whether frames are passed through immediately or accumulated for later release. - - Doctest: FIXME to work with asyncio - >>> from pipecat.frames.frames import ImageRawFrame - - >>> async def print_frames(aggregator, frame): - ... async for frame in aggregator.process_frame(frame): - ... if isinstance(frame, TextFrame): - ... print(frame.text) - ... else: - ... print(frame.__class__.__name__) - - >>> aggregator = GatedAggregator( - ... gate_close_fn=lambda x: isinstance(x, LLMResponseStartFrame), - ... gate_open_fn=lambda x: isinstance(x, ImageRawFrame), - ... start_open=False) - >>> asyncio.run(print_frames(aggregator, TextFrame("Hello"))) - >>> asyncio.run(print_frames(aggregator, TextFrame("Hello again."))) - >>> asyncio.run(print_frames(aggregator, ImageRawFrame(image=bytes([]), size=(0, 0)))) - ImageRawFrame - Hello - Hello again. - >>> asyncio.run(print_frames(aggregator, TextFrame("Goodbye."))) - Goodbye. """ def __init__( diff --git a/src/pipecat/processors/aggregators/sentence.py b/src/pipecat/processors/aggregators/sentence.py index 5a2bc59dc..da287bd6f 100644 --- a/src/pipecat/processors/aggregators/sentence.py +++ b/src/pipecat/processors/aggregators/sentence.py @@ -23,20 +23,10 @@ class SentenceAggregator(FrameProcessor): 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. """ def __init__(self): diff --git a/src/pipecat/processors/aggregators/vision_image_frame.py b/src/pipecat/processors/aggregators/vision_image_frame.py index ea1848ff1..de4d74186 100644 --- a/src/pipecat/processors/aggregators/vision_image_frame.py +++ b/src/pipecat/processors/aggregators/vision_image_frame.py @@ -20,17 +20,6 @@ class VisionImageFrameAggregator(FrameProcessor): 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. - - >>> 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 """ def __init__(self): diff --git a/src/pipecat/processors/text_transformer.py b/src/pipecat/processors/text_transformer.py index 7dcef31df..0fdbbb043 100644 --- a/src/pipecat/processors/text_transformer.py +++ b/src/pipecat/processors/text_transformer.py @@ -18,14 +18,6 @@ class StatelessTextTransformer(FrameProcessor): This processor intercepts TextFrame objects and applies a user-provided transformation function to the text content. The function can be either synchronous or asynchronous (coroutine). - - >>> async def print_frames(aggregator, frame): - ... async for frame in aggregator.process_frame(frame): - ... print(frame.text) - - >>> aggregator = StatelessTextTransformer(lambda x: x.upper()) - >>> asyncio.run(print_frames(aggregator, TextFrame("Hello"))) - HELLO """ def __init__( diff --git a/src/pipecat/utils/utils.py b/src/pipecat/utils/utils.py index f741bc05b..fb0299b2c 100644 --- a/src/pipecat/utils/utils.py +++ b/src/pipecat/utils/utils.py @@ -25,15 +25,6 @@ def obj_id() -> int: Returns: A unique integer identifier that increments globally across all objects. - - Examples:: - - >>> obj_id() - 0 - >>> obj_id() - 1 - >>> obj_id() - 2 """ with _ID_LOCK: return next(_ID) @@ -47,16 +38,6 @@ def obj_count(obj) -> int: Returns: A unique integer count that increments per class type. - - Examples:: - - >>> obj_count(object()) - 0 - >>> obj_count(object()) - 1 - >>> new_type = type('NewType', (object,), {}) - >>> obj_count(new_type()) - 0 """ with _COUNTS_LOCK: return next(_COUNTS[obj.__class__.__name__]) From f590a476e77311d5d55b76b1c81ad2b918896da3 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 2 Jul 2025 07:41:15 -0700 Subject: [PATCH 51/84] Gemini Live fixes, plus additional docstrings --- .../gemini_multimodal_live/file_api.py | 7 ++ .../services/gemini_multimodal_live/gemini.py | 68 +++++++++++++------ 2 files changed, 55 insertions(+), 20 deletions(-) diff --git a/src/pipecat/services/gemini_multimodal_live/file_api.py b/src/pipecat/services/gemini_multimodal_live/file_api.py index f0f23ab83..5ae7fdbb7 100644 --- a/src/pipecat/services/gemini_multimodal_live/file_api.py +++ b/src/pipecat/services/gemini_multimodal_live/file_api.py @@ -4,6 +4,13 @@ # SPDX-License-Identifier: BSD 2-Clause License # +"""Gemini File API client for uploading and managing files. + +This module provides a client for Google's Gemini File API, enabling file +uploads, metadata retrieval, listing, and deletion. Files uploaded through +this API can be referenced in Gemini generative model calls. +""" + import mimetypes from typing import Any, Dict, Optional diff --git a/src/pipecat/services/gemini_multimodal_live/gemini.py b/src/pipecat/services/gemini_multimodal_live/gemini.py index 19860387e..a31bbfe70 100644 --- a/src/pipecat/services/gemini_multimodal_live/gemini.py +++ b/src/pipecat/services/gemini_multimodal_live/gemini.py @@ -72,7 +72,6 @@ from pipecat.utils.time import time_now_iso8601 from pipecat.utils.tracing.service_decorators import traced_gemini_live, traced_stt from . import events - from .file_api import GeminiFileAPI try: @@ -223,9 +222,9 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): def add_file_reference(self, file_uri: str, mime_type: str, text: Optional[str] = None): """Add a file reference to the context. - + This adds a user message with a file reference that will be sent during context initialization. - + Args: file_uri: URI of the uploaded file mime_type: MIME type of the file @@ -235,15 +234,17 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts = [] if text: parts.append({"type": "text", "text": text}) - + # Add file reference part - parts.append({"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}}) - + parts.append( + {"type": "file_data", "file_data": {"mime_type": mime_type, "file_uri": file_uri}} + ) + # Add to messages message = {"role": "user", "content": parts} self.messages.append(message) logger.info(f"Added file reference to context: {file_uri}") - + def get_messages_for_initializing_history(self): """Get messages formatted for Gemini history initialization. @@ -270,12 +271,14 @@ class GeminiMultimodalLiveContext(OpenAILLMContext): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -379,7 +382,14 @@ class GeminiMultimodalModalities(Enum): class GeminiMediaResolution(str, Enum): - """Media resolution options for Gemini Multimodal Live.""" + """Media resolution options for Gemini Multimodal Live. + + Parameters: + UNSPECIFIED: Use default resolution setting. + LOW: Low resolution with 64 tokens. + MEDIUM: Medium resolution with 256 tokens. + HIGH: High resolution with zoomed reframing and 256 tokens. + """ UNSPECIFIED = "MEDIA_RESOLUTION_UNSPECIFIED" # Use default LOW = "MEDIA_RESOLUTION_LOW" # 64 tokens @@ -465,7 +475,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # Overriding the default adapter to use the Gemini one. adapter_class = GeminiLLMAdapter - + def __init__( self, *, @@ -496,6 +506,7 @@ class GeminiMultimodalLiveLLMService(LLMService): params: Configuration parameters for the model. Defaults to InputParams(). inference_on_context_initialization: Whether to generate a response when context is first set. Defaults to True. + file_api_base_url: Base URL for the Gemini File API. Defaults to the official endpoint. **kwargs: Additional arguments passed to parent LLMService. """ super().__init__(base_url=base_url, **kwargs) @@ -557,7 +568,7 @@ class GeminiMultimodalLiveLLMService(LLMService): else {}, "extra": params.extra if isinstance(params.extra, dict) else {}, } - + # Initialize the File API client self.file_api = GeminiFileAPI(api_key=api_key, base_url=file_api_base_url) @@ -757,6 +768,7 @@ class GeminiMultimodalLiveLLMService(LLMService): await self._ws_send(event.model_dump(exclude_none=True)) async def _connect(self): + """Establish WebSocket connection to Gemini Live API.""" if self._websocket: # Here we assume that if we have a websocket, we are connected. We # handle disconnections in the send/recv code paths. @@ -861,6 +873,7 @@ class GeminiMultimodalLiveLLMService(LLMService): self._websocket = None async def _disconnect(self): + """Disconnect from Gemini Live API and clean up resources.""" logger.info("Disconnecting from Gemini service") try: self._disconnecting = True @@ -877,6 +890,7 @@ class GeminiMultimodalLiveLLMService(LLMService): logger.error(f"{self} error disconnecting: {e}") async def _ws_send(self, message): + """Send a message to the WebSocket connection.""" # logger.debug(f"Sending message to websocket: {message}") try: if self._websocket: @@ -897,6 +911,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # async def _receive_task_handler(self): + """Handle incoming messages from the WebSocket connection.""" async for message in WatchdogAsyncIterator(self._websocket, manager=self.task_manager): evt = events.parse_server_event(message) # logger.debug(f"Received event: {message[:500]}") @@ -925,6 +940,7 @@ class GeminiMultimodalLiveLLMService(LLMService): # async def _send_user_audio(self, frame): + """Send user audio frame to Gemini Live API.""" if self._audio_input_paused: return # Send all audio to Gemini @@ -941,6 +957,7 @@ class GeminiMultimodalLiveLLMService(LLMService): self._user_audio_buffer = self._user_audio_buffer[-length:] async def _send_user_video(self, frame): + """Send user video frame to Gemini Live API.""" if self._video_input_paused: return @@ -954,6 +971,7 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.send_client_event(evt) async def _create_initial_response(self): + """Create initial response based on context history.""" if not self._api_session_ready: self._run_llm_when_api_session_ready = True return @@ -979,6 +997,7 @@ class GeminiMultimodalLiveLLMService(LLMService): self._needs_turn_complete_message = True async def _create_single_response(self, messages_list): + """Create a single response from a list of messages.""" # Refactor to combine this logic with same logic in GeminiMultimodalLiveContext messages = [] for item in messages_list: @@ -1000,12 +1019,14 @@ class GeminiMultimodalLiveLLMService(LLMService): parts.append({"text": part.get("text")}) elif part.get("type") == "file_data": file_data = part.get("file_data", {}) - parts.append({ - "fileData": { - "mimeType": file_data.get("mime_type"), - "fileUri": file_data.get("file_uri") + parts.append( + { + "fileData": { + "mimeType": file_data.get("mime_type"), + "fileUri": file_data.get("file_uri"), + } } - }) + ) else: logger.warning(f"Unsupported content type: {str(part)[:80]}") else: @@ -1029,6 +1050,7 @@ class GeminiMultimodalLiveLLMService(LLMService): @traced_gemini_live(operation="llm_tool_result") async def _tool_result(self, tool_result_message): + """Send tool result back to the API.""" # For now we're shoving the name into the tool_call_id field, so this # will work until we revisit that. id = tool_result_message.get("tool_call_id") @@ -1054,6 +1076,7 @@ class GeminiMultimodalLiveLLMService(LLMService): @traced_gemini_live(operation="llm_setup") async def _handle_evt_setup_complete(self, evt): + """Handle the setup complete event.""" # If this is our first context frame, run the LLM self._api_session_ready = True # Now that we've configured the session, we can run the LLM if we need to. @@ -1062,6 +1085,7 @@ class GeminiMultimodalLiveLLMService(LLMService): await self._create_initial_response() async def _handle_evt_model_turn(self, evt): + """Handle the model turn event.""" part = evt.serverContent.modelTurn.parts[0] if not part: return @@ -1103,6 +1127,7 @@ class GeminiMultimodalLiveLLMService(LLMService): @traced_gemini_live(operation="llm_tool_call") async def _handle_evt_tool_call(self, evt): + """Handle tool call events.""" function_calls = evt.toolCall.functionCalls if not function_calls: return @@ -1123,6 +1148,7 @@ class GeminiMultimodalLiveLLMService(LLMService): @traced_gemini_live(operation="llm_response") async def _handle_evt_turn_complete(self, evt): + """Handle the turn complete event.""" self._bot_is_speaking = False text = self._bot_text_buffer @@ -1206,6 +1232,7 @@ class GeminiMultimodalLiveLLMService(LLMService): ) async def _handle_evt_output_transcription(self, evt): + """Handle the output transcription event.""" if not evt.serverContent.outputTranscription: return @@ -1224,6 +1251,7 @@ class GeminiMultimodalLiveLLMService(LLMService): await self.push_frame(TTSTextFrame(text=text)) async def _handle_evt_usage_metadata(self, evt): + """Handle the usage metadata event.""" if not evt.usageMetadata: return From de5f9c9217da3f69e4f18aea79404fb9adda25fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Wed, 2 Jul 2025 09:51:36 -0700 Subject: [PATCH 52/84] pyproject: update daily-python to 0.19.4 --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 029fc2ed9..0ca45319a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,6 +54,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `session_token` parameter to `AWSNovaSonicLLMService`. +### Changed + +- Upgraded `daily-python` to 0.19.4. + ### Fixed - Fixed a race condition that occurs in Python 3.10+ where the task could miss diff --git a/pyproject.toml b/pyproject.toml index b364020ab..e0608f120 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,7 +48,7 @@ azure = [ "azure-cognitiveservices-speech~=1.42.0"] cartesia = [ "cartesia~=2.0.3", "websockets~=13.1" ] cerebras = [] deepseek = [] -daily = [ "daily-python~=0.19.3" ] +daily = [ "daily-python~=0.19.4" ] deepgram = [ "deepgram-sdk~=4.1.0" ] elevenlabs = [ "websockets~=13.1" ] fal = [ "fal-client~=0.5.9" ] From 5c2ea3b8049d9d069808fad2cf12ec919f3d4662 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 2 Jul 2025 06:37:03 -0700 Subject: [PATCH 53/84] Upgrade google-genai version to 1.24.0 --- CHANGELOG.md | 2 ++ pyproject.toml | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ca45319a..53b6a0e55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Upgraded `daily-python` to 0.19.4. +- Updated `google` optional dependency to use `google-genai` version `1.24.0`. + ### Fixed - Fixed a race condition that occurs in Python 3.10+ where the task could miss diff --git a/pyproject.toml b/pyproject.toml index e0608f120..42b06060d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,7 +55,7 @@ fal = [ "fal-client~=0.5.9" ] fireworks = [] fish = [ "ormsgpack~=1.7.0", "websockets~=13.1" ] gladia = [ "websockets~=13.1" ] -google = [ "google-cloud-speech~=2.32.0", "google-cloud-texttospeech~=2.26.0", "google-genai~=1.14.0", "websockets~=13.1" ] +google = [ "google-cloud-speech~=2.32.0", "google-cloud-texttospeech~=2.26.0", "google-genai~=1.24.0", "websockets~=13.1" ] grok = [] groq = [ "groq~=0.23.0" ] gstreamer = [ "pygobject~=3.50.0" ] From 25749bd4c09d22ed4470aa50c717ea3ffe97956c Mon Sep 17 00:00:00 2001 From: Fynn Merlevede Date: Wed, 2 Jul 2025 20:57:38 +0200 Subject: [PATCH 54/84] Update README.md fix: use correct protocol in READme --- examples/open-telemetry/langfuse/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/open-telemetry/langfuse/README.md b/examples/open-telemetry/langfuse/README.md index c17de8394..1ae95f400 100644 --- a/examples/open-telemetry/langfuse/README.md +++ b/examples/open-telemetry/langfuse/README.md @@ -26,7 +26,7 @@ Create a `.env` file with your API keys to enable tracing: ``` ENABLE_TRACING=true # OTLP endpoint for Langfuse -OTEL_EXPORTER_OTLP_ENDPOINT=http://cloud.langfuse.com/api/public/otel +OTEL_EXPORTER_OTLP_ENDPOINT=https://cloud.langfuse.com/api/public/otel OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic%20 # Set to any value to enable console output for debugging # OTEL_CONSOLE_EXPORT=true From c19f9bc43a17d1d628015be1d278458ec27a0309 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 16:19:47 -0300 Subject: [PATCH 55/84] Creating a new stream resampler which avoids clicks. --- .../audio/resamplers/soxr_stream_resampler.py | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 src/pipecat/audio/resamplers/soxr_stream_resampler.py diff --git a/src/pipecat/audio/resamplers/soxr_stream_resampler.py b/src/pipecat/audio/resamplers/soxr_stream_resampler.py new file mode 100644 index 000000000..bf6088867 --- /dev/null +++ b/src/pipecat/audio/resamplers/soxr_stream_resampler.py @@ -0,0 +1,101 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""SoX-based audio resampler stream implementation. + +This module provides an audio resampler that uses the SoX ResampleStream library +for very high quality audio sample rate conversion. + +When to use the SOXRStreamAudioResampler: +1. For real-time processing scenarios +2. When dealing with very long audio signals +3. When processing audio in chunks or streams +4. When you need to reuse the same resampler configuration multiple times, as it saves initialization overhead + +""" + +import time + +import numpy as np +import soxr + +from pipecat.audio.resamplers.base_audio_resampler import BaseAudioResampler + +CLEAR_STREAM_AFTER_SECS = 0.2 + + +class SOXRStreamAudioResampler(BaseAudioResampler): + """Audio resampler implementation using the SoX ResampleStream library. + + This resampler uses the SoX ResampleStream library configured for very high + quality (VHQ) resampling, providing excellent audio quality at the cost + of additional computational overhead. + It keeps an internal history which avoids clicks at chunk boundaries. + + Notes: + - Only supports mono audio (1 channel). + - Input must be 16-bit signed PCM audio as raw bytes. + """ + + def __init__(self, **kwargs): + """Initialize the resampler. + + Args: + **kwargs: Additional keyword arguments (currently unused). + """ + self._in_rate: float | None = None + self._out_rate: float | None = None + self._last_resample_time: float = 0 + self._soxr_stream: soxr.ResampleStream | None = None + + def _initialize(self, in_rate: float, out_rate: float): + self._in_rate = in_rate + self._out_rate = out_rate + self._last_resample_time = time.time() + self._soxr_stream = soxr.ResampleStream( + in_rate=in_rate, out_rate=out_rate, num_channels=1, quality="VHQ", dtype="int16" + ) + + def _maybe_clear_internal_state(self): + current_time = time.time() + time_since_last_resample = current_time - self._last_resample_time + # If more than CLEAR_STREAM_AFTER_SECS seconds have passed, clear the resampler state + if time_since_last_resample > CLEAR_STREAM_AFTER_SECS: + if self._soxr_stream: + self._soxr_stream.clear() + self._last_resample_time = current_time + + def _maybe_initialize_sox_stream(self, in_rate: int, out_rate: int): + if self._soxr_stream is None: + self._initialize(in_rate, out_rate) + else: + self._maybe_clear_internal_state() + + if self._in_rate != in_rate or self._out_rate != out_rate: + raise ValueError( + f"SOXRStreamAudioResampler cannot be reused with different sample rates: " + f"expected {self._in_rate}->{self._out_rate}, got {in_rate}->{out_rate}" + ) + + async def resample(self, audio: bytes, in_rate: int, out_rate: int) -> bytes: + """Resample audio data using soxr.ResampleStream resampler library. + + Args: + audio: Input audio data as raw bytes (16-bit signed integers). + in_rate: Original sample rate in Hz. + out_rate: Target sample rate in Hz. + + Returns: + Resampled audio data as raw bytes (16-bit signed integers). + """ + if in_rate == out_rate: + return audio + + self._maybe_initialize_sox_stream(in_rate, out_rate) + audio_data = np.frombuffer(audio, dtype=np.int16) + resampled_audio = self._soxr_stream.resample_chunk(audio_data) + result = resampled_audio.astype(np.int16).tobytes() + return result From 3de271161c54203cd4efe910e16b16b2b4742c43 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 16:19:57 -0300 Subject: [PATCH 56/84] Fixing the ruff script to also try to fix docstrings. --- scripts/fix-ruff.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/fix-ruff.sh b/scripts/fix-ruff.sh index 6bd24300d..d913ffb65 100755 --- a/scripts/fix-ruff.sh +++ b/scripts/fix-ruff.sh @@ -2,4 +2,4 @@ ruff format src ruff format examples ruff format tests ruff format scripts -ruff check --select I --fix \ No newline at end of file +ruff check --select I,D --fix \ No newline at end of file From 5af563cd91b4e59156f3c77a7e8a4c96e4a09786 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 16:20:34 -0300 Subject: [PATCH 57/84] Configured the services to use create_stream_resampler instead of create_default_resampler --- .../audio/audio_buffer_processor.py | 26 ++++++++++++------- src/pipecat/serializers/exotel.py | 9 ++++--- src/pipecat/serializers/plivo.py | 9 ++++--- src/pipecat/serializers/telnyx.py | 13 +++++----- src/pipecat/serializers/twilio.py | 9 ++++--- src/pipecat/services/aws/tts.py | 4 +-- src/pipecat/services/tavus/video.py | 4 +-- src/pipecat/services/xtts/tts.py | 4 +-- src/pipecat/transports/base_output.py | 4 +-- src/pipecat/transports/services/livekit.py | 4 +-- src/pipecat/transports/services/tavus.py | 3 --- 11 files changed, 49 insertions(+), 40 deletions(-) diff --git a/src/pipecat/processors/audio/audio_buffer_processor.py b/src/pipecat/processors/audio/audio_buffer_processor.py index 78561b2f9..9cfc08daa 100644 --- a/src/pipecat/processors/audio/audio_buffer_processor.py +++ b/src/pipecat/processors/audio/audio_buffer_processor.py @@ -14,9 +14,8 @@ configurations and event-driven processing. import time from typing import Optional -from pipecat.audio.utils import create_default_resampler, interleave_stereo_audio, mix_audio +from pipecat.audio.utils import create_stream_resampler, interleave_stereo_audio, mix_audio from pipecat.frames.frames import ( - AudioRawFrame, BotStartedSpeakingFrame, BotStoppedSpeakingFrame, CancelFrame, @@ -106,7 +105,8 @@ class AudioBufferProcessor(FrameProcessor): self._recording = False - self._resampler = create_default_resampler() + self._input_resampler = create_stream_resampler() + self._output_resampler = create_stream_resampler() self._register_event_handler("on_audio_data") self._register_event_handler("on_track_audio_data") @@ -210,7 +210,7 @@ class AudioBufferProcessor(FrameProcessor): silence = self._compute_silence(self._last_user_frame_at) self._user_audio_buffer.extend(silence) # Add user audio. - resampled = await self._resample_audio(frame) + resampled = await self._resample_input_audio(frame) self._user_audio_buffer.extend(resampled) # Save time of frame so we can compute silence. self._last_user_frame_at = time.time() @@ -219,7 +219,7 @@ class AudioBufferProcessor(FrameProcessor): silence = self._compute_silence(self._last_bot_frame_at) self._bot_audio_buffer.extend(silence) # Add bot audio. - resampled = await self._resample_audio(frame) + resampled = await self._resample_output_audio(frame) self._bot_audio_buffer.extend(resampled) # Save time of frame so we can compute silence. self._last_bot_frame_at = time.time() @@ -247,7 +247,7 @@ class AudioBufferProcessor(FrameProcessor): self._bot_turn_audio_buffer = bytearray() if isinstance(frame, InputAudioRawFrame): - resampled = await self._resample_audio(frame) + resampled = await self._resample_input_audio(frame) self._user_turn_audio_buffer += resampled # In the case of the user, we need to keep a short buffer of audio # since VAD notification of when the user starts speaking comes @@ -259,7 +259,7 @@ class AudioBufferProcessor(FrameProcessor): discarded = len(self._user_turn_audio_buffer) - self._audio_buffer_size_1s self._user_turn_audio_buffer = self._user_turn_audio_buffer[discarded:] elif self._bot_speaking and isinstance(frame, OutputAudioRawFrame): - resampled = await self._resample_audio(frame) + resampled = await self._resample_output_audio(frame) self._bot_turn_audio_buffer += resampled async def _call_on_audio_data_handler(self): @@ -301,9 +301,17 @@ class AudioBufferProcessor(FrameProcessor): self._user_turn_audio_buffer = bytearray() self._bot_turn_audio_buffer = bytearray() - async def _resample_audio(self, frame: AudioRawFrame) -> bytes: + async def _resample_input_audio(self, frame: InputAudioRawFrame) -> bytes: """Resample audio frame to the target sample rate.""" - return await self._resampler.resample(frame.audio, frame.sample_rate, self._sample_rate) + return await self._input_resampler.resample( + frame.audio, frame.sample_rate, self._sample_rate + ) + + async def _resample_output_audio(self, frame: OutputAudioRawFrame) -> bytes: + """Resample audio frame to the target sample rate.""" + return await self._output_resampler.resample( + frame.audio, frame.sample_rate, self._sample_rate + ) def _compute_silence(self, from_time: float) -> bytes: """Compute silence to insert based on time gap.""" diff --git a/src/pipecat/serializers/exotel.py b/src/pipecat/serializers/exotel.py index 960cbe74a..81f0daf39 100644 --- a/src/pipecat/serializers/exotel.py +++ b/src/pipecat/serializers/exotel.py @@ -13,7 +13,7 @@ from typing import Optional from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.frames.frames import ( AudioRawFrame, Frame, @@ -67,7 +67,8 @@ class ExotelFrameSerializer(FrameSerializer): self._exotel_sample_rate = self._params.exotel_sample_rate self._sample_rate = 0 # Pipeline input rate - self._resampler = create_default_resampler() + self._input_resampler = create_stream_resampler() + self._output_resampler = create_stream_resampler() @property def type(self) -> FrameSerializerType: @@ -104,7 +105,7 @@ class ExotelFrameSerializer(FrameSerializer): data = frame.audio # Output: Exotel outputs PCM audio, but we need to resample to match requested sample_rate - serialized_data = await self._resampler.resample( + serialized_data = await self._output_resampler.resample( data, frame.sample_rate, self._exotel_sample_rate ) payload = base64.b64encode(serialized_data).decode("ascii") @@ -138,7 +139,7 @@ class ExotelFrameSerializer(FrameSerializer): payload_base64 = message["media"]["payload"] payload = base64.b64decode(payload_base64) - deserialized_data = await self._resampler.resample( + deserialized_data = await self._input_resampler.resample( payload, self._exotel_sample_rate, self._sample_rate, diff --git a/src/pipecat/serializers/plivo.py b/src/pipecat/serializers/plivo.py index d0c19be0a..1b2ebb57f 100644 --- a/src/pipecat/serializers/plivo.py +++ b/src/pipecat/serializers/plivo.py @@ -13,7 +13,7 @@ from typing import Optional from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm +from pipecat.audio.utils import create_stream_resampler, pcm_to_ulaw, ulaw_to_pcm from pipecat.frames.frames import ( AudioRawFrame, CancelFrame, @@ -81,7 +81,8 @@ class PlivoFrameSerializer(FrameSerializer): self._plivo_sample_rate = self._params.plivo_sample_rate self._sample_rate = 0 # Pipeline input rate - self._resampler = create_default_resampler() + self._input_resampler = create_stream_resampler() + self._output_resampler = create_stream_resampler() self._hangup_attempted = False @property @@ -129,7 +130,7 @@ class PlivoFrameSerializer(FrameSerializer): # Output: Convert PCM at frame's rate to 8kHz μ-law for Plivo serialized_data = await pcm_to_ulaw( - data, frame.sample_rate, self._plivo_sample_rate, self._resampler + data, frame.sample_rate, self._plivo_sample_rate, self._output_resampler ) payload = base64.b64encode(serialized_data).decode("utf-8") answer = { @@ -224,7 +225,7 @@ class PlivoFrameSerializer(FrameSerializer): # Input: Convert Plivo's 8kHz μ-law to PCM at pipeline input rate deserialized_data = await ulaw_to_pcm( - payload, self._plivo_sample_rate, self._sample_rate, self._resampler + payload, self._plivo_sample_rate, self._sample_rate, self._input_resampler ) audio_frame = InputAudioRawFrame( audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate diff --git a/src/pipecat/serializers/telnyx.py b/src/pipecat/serializers/telnyx.py index adc235555..133c50dc9 100644 --- a/src/pipecat/serializers/telnyx.py +++ b/src/pipecat/serializers/telnyx.py @@ -16,7 +16,7 @@ from pydantic import BaseModel from pipecat.audio.utils import ( alaw_to_pcm, - create_default_resampler, + create_stream_resampler, pcm_to_alaw, pcm_to_ulaw, ulaw_to_pcm, @@ -93,7 +93,8 @@ class TelnyxFrameSerializer(FrameSerializer): self._telnyx_sample_rate = self._params.telnyx_sample_rate self._sample_rate = 0 # Pipeline input rate - self._resampler = create_default_resampler() + self._input_resampler = create_stream_resampler() + self._output_resampler = create_stream_resampler() self._hangup_attempted = False @property @@ -145,11 +146,11 @@ class TelnyxFrameSerializer(FrameSerializer): # Output: Convert PCM at frame's rate to 8kHz encoded for Telnyx if self._params.inbound_encoding == "PCMU": serialized_data = await pcm_to_ulaw( - data, frame.sample_rate, self._telnyx_sample_rate, self._resampler + data, frame.sample_rate, self._telnyx_sample_rate, self._output_resampler ) elif self._params.inbound_encoding == "PCMA": serialized_data = await pcm_to_alaw( - data, frame.sample_rate, self._telnyx_sample_rate, self._resampler + data, frame.sample_rate, self._telnyx_sample_rate, self._output_resampler ) else: raise ValueError(f"Unsupported encoding: {self._params.inbound_encoding}") @@ -249,14 +250,14 @@ class TelnyxFrameSerializer(FrameSerializer): payload, self._telnyx_sample_rate, self._sample_rate, - self._resampler, + self._input_resampler, ) elif self._params.outbound_encoding == "PCMA": deserialized_data = await alaw_to_pcm( payload, self._telnyx_sample_rate, self._sample_rate, - self._resampler, + self._input_resampler, ) else: raise ValueError(f"Unsupported encoding: {self._params.outbound_encoding}") diff --git a/src/pipecat/serializers/twilio.py b/src/pipecat/serializers/twilio.py index ae4d54e4d..50ca420fa 100644 --- a/src/pipecat/serializers/twilio.py +++ b/src/pipecat/serializers/twilio.py @@ -13,7 +13,7 @@ from typing import Optional from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler, pcm_to_ulaw, ulaw_to_pcm +from pipecat.audio.utils import create_stream_resampler, pcm_to_ulaw, ulaw_to_pcm from pipecat.frames.frames import ( AudioRawFrame, CancelFrame, @@ -81,7 +81,8 @@ class TwilioFrameSerializer(FrameSerializer): self._twilio_sample_rate = self._params.twilio_sample_rate self._sample_rate = 0 # Pipeline input rate - self._resampler = create_default_resampler() + self._input_resampler = create_stream_resampler() + self._output_resampler = create_stream_resampler() self._hangup_attempted = False @property @@ -129,7 +130,7 @@ class TwilioFrameSerializer(FrameSerializer): # Output: Convert PCM at frame's rate to 8kHz μ-law for Twilio serialized_data = await pcm_to_ulaw( - data, frame.sample_rate, self._twilio_sample_rate, self._resampler + data, frame.sample_rate, self._twilio_sample_rate, self._output_resampler ) payload = base64.b64encode(serialized_data).decode("utf-8") answer = { @@ -214,7 +215,7 @@ class TwilioFrameSerializer(FrameSerializer): # Input: Convert Twilio's 8kHz μ-law to PCM at pipeline input rate deserialized_data = await ulaw_to_pcm( - payload, self._twilio_sample_rate, self._sample_rate, self._resampler + payload, self._twilio_sample_rate, self._sample_rate, self._input_resampler ) audio_frame = InputAudioRawFrame( audio=deserialized_data, num_channels=1, sample_rate=self._sample_rate diff --git a/src/pipecat/services/aws/tts.py b/src/pipecat/services/aws/tts.py index ce89dea9e..7f4ccd079 100644 --- a/src/pipecat/services/aws/tts.py +++ b/src/pipecat/services/aws/tts.py @@ -17,7 +17,7 @@ from typing import AsyncGenerator, List, Optional from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.frames.frames import ( ErrorFrame, Frame, @@ -195,7 +195,7 @@ class AWSPollyTTSService(TTSService): "lexicon_names": params.lexicon_names, } - self._resampler = create_default_resampler() + self._resampler = create_stream_resampler() self.set_voice(voice_id) diff --git a/src/pipecat/services/tavus/video.py b/src/pipecat/services/tavus/video.py index d633329bb..f9ba2833b 100644 --- a/src/pipecat/services/tavus/video.py +++ b/src/pipecat/services/tavus/video.py @@ -17,7 +17,7 @@ import aiohttp from daily.daily import AudioData, VideoFrame from loguru import logger -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.frames.frames import ( CancelFrame, EndFrame, @@ -75,7 +75,7 @@ class TavusVideoService(AIService): self._client: Optional[TavusTransportClient] = None self._conversation_id: str - self._resampler = create_default_resampler() + self._resampler = create_stream_resampler() self._audio_buffer = bytearray() self._send_task: Optional[asyncio.Task] = None diff --git a/src/pipecat/services/xtts/tts.py b/src/pipecat/services/xtts/tts.py index 6332e26ef..844e0fbaf 100644 --- a/src/pipecat/services/xtts/tts.py +++ b/src/pipecat/services/xtts/tts.py @@ -15,7 +15,7 @@ from typing import Any, AsyncGenerator, Dict, Optional import aiohttp from loguru import logger -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.frames.frames import ( ErrorFrame, Frame, @@ -121,7 +121,7 @@ class XTTSService(TTSService): self._studio_speakers: Optional[Dict[str, Any]] = None self._aiohttp_session = aiohttp_session - self._resampler = create_default_resampler() + self._resampler = create_stream_resampler() def can_generate_metrics(self) -> bool: """Check if this service can generate processing metrics. diff --git a/src/pipecat/transports/base_output.py b/src/pipecat/transports/base_output.py index 93a11f5a3..4d1120cc7 100644 --- a/src/pipecat/transports/base_output.py +++ b/src/pipecat/transports/base_output.py @@ -21,7 +21,7 @@ from loguru import logger from PIL import Image from pipecat.audio.mixers.base_audio_mixer import BaseAudioMixer -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.frames.frames import ( BotSpeakingFrame, BotStartedSpeakingFrame, @@ -358,7 +358,7 @@ class BaseOutputTransport(FrameProcessor): self._audio_buffer = bytearray() # This will be used to resample incoming audio to the output sample rate. - self._resampler = create_default_resampler() + self._resampler = create_stream_resampler() # The user can provide a single mixer, to be used by the default # destination, or a destination/mixer mapping. diff --git a/src/pipecat/transports/services/livekit.py b/src/pipecat/transports/services/livekit.py index d7363b9e7..68fc6a8a8 100644 --- a/src/pipecat/transports/services/livekit.py +++ b/src/pipecat/transports/services/livekit.py @@ -18,7 +18,7 @@ from typing import Any, Awaitable, Callable, List, Optional from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler +from pipecat.audio.utils import create_stream_resampler from pipecat.audio.vad.vad_analyzer import VADAnalyzer from pipecat.frames.frames import ( AudioRawFrame, @@ -513,7 +513,7 @@ class LiveKitInputTransport(BaseInputTransport): self._audio_in_task = None self._vad_analyzer: Optional[VADAnalyzer] = params.vad_analyzer - self._resampler = create_default_resampler() + self._resampler = create_stream_resampler() # Whether we have seen a StartFrame already. self._initialized = False diff --git a/src/pipecat/transports/services/tavus.py b/src/pipecat/transports/services/tavus.py index e83dc6a20..10ae001e0 100644 --- a/src/pipecat/transports/services/tavus.py +++ b/src/pipecat/transports/services/tavus.py @@ -20,7 +20,6 @@ from daily.daily import AudioData from loguru import logger from pydantic import BaseModel -from pipecat.audio.utils import create_default_resampler from pipecat.frames.frames import ( CancelFrame, EndFrame, @@ -437,8 +436,6 @@ class TavusInputTransport(BaseInputTransport): super().__init__(params, **kwargs) self._client = client self._params = params - self._resampler = create_default_resampler() - # Whether we have seen a StartFrame already. self._initialized = False From 38bcc033a2bec55690b1639449cd86e08d00c89d Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 16:20:48 -0300 Subject: [PATCH 58/84] Improving the docs about when to use: SOXRAudioResampler x SOXRStreamAudioResampler --- src/pipecat/audio/resamplers/soxr_resampler.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/pipecat/audio/resamplers/soxr_resampler.py b/src/pipecat/audio/resamplers/soxr_resampler.py index 9f285069f..4ac5d0a73 100644 --- a/src/pipecat/audio/resamplers/soxr_resampler.py +++ b/src/pipecat/audio/resamplers/soxr_resampler.py @@ -7,7 +7,12 @@ """SoX-based audio resampler implementation. This module provides an audio resampler that uses the SoX resampler library -for very high quality audio sample rate conversion. +for very high-quality audio sample rate conversion. + +When to use the SOXRAudioResampler: +1. For batch processing of complete audio files +2. When you have all the audio data available at once + """ import numpy as np From 76388a10b5215f24ddb5d510e9f580e94126400a Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Wed, 2 Jul 2025 16:20:58 -0300 Subject: [PATCH 59/84] Deprecating the create_default_resampler and adding the changelog. --- CHANGELOG.md | 5 +++++ src/pipecat/audio/utils.py | 40 +++++++++++++++++++++++++++++++++++++- 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 53b6a0e55..fcced9255 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added a new `SOXRStreamAudioResampler` for processing audio in chunks or streams. + - Added new `DailyParams.audio_in_user_tracks` to allow receiving one track per user (default) or a single track from the room (all participants mixed). @@ -56,6 +58,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Updated all the services to use the new `SOXRStreamAudioResampler`, ensuring smooth + transitions and eliminating clicks. + - Upgraded `daily-python` to 0.19.4. - Updated `google` optional dependency to use `google-genai` version `1.24.0`. diff --git a/src/pipecat/audio/utils.py b/src/pipecat/audio/utils.py index 7b72be1a9..6d5a12929 100644 --- a/src/pipecat/audio/utils.py +++ b/src/pipecat/audio/utils.py @@ -15,15 +15,41 @@ import audioop import numpy as np import pyloudnorm as pyln -import soxr from pipecat.audio.resamplers.base_audio_resampler import BaseAudioResampler from pipecat.audio.resamplers.soxr_resampler import SOXRAudioResampler +from pipecat.audio.resamplers.soxr_stream_resampler import SOXRStreamAudioResampler def create_default_resampler(**kwargs) -> BaseAudioResampler: """Create a default audio resampler instance. + . deprecated:: 0.0.74 + This function is deprecated and will be removed in a future version. + Use `create_stream_resampler` for real-time processing scenarios or + `create_file_resampler` for batch processing of complete audio files. + + Args: + **kwargs: Additional keyword arguments passed to the resampler constructor. + + Returns: + A configured SOXRAudioResampler instance. + """ + import warnings + + warnings.warn( + "`create_default_resampler` is deprecated. " + "Use `create_stream_resampler` for real-time processing scenarios or " + "`create_file_resampler` for batch processing of complete audio files.", + DeprecationWarning, + stacklevel=2, + ) + return SOXRAudioResampler(**kwargs) + + +def create_file_resampler(**kwargs) -> BaseAudioResampler: + """Create an audio resampler instance for batch processing of complete audio files. + Args: **kwargs: Additional keyword arguments passed to the resampler constructor. @@ -33,6 +59,18 @@ def create_default_resampler(**kwargs) -> BaseAudioResampler: return SOXRAudioResampler(**kwargs) +def create_stream_resampler(**kwargs) -> BaseAudioResampler: + """Create a stream audio resampler instance. + + Args: + **kwargs: Additional keyword arguments passed to the resampler constructor. + + Returns: + A configured SOXRStreamAudioResampler instance. + """ + return SOXRStreamAudioResampler(**kwargs) + + def mix_audio(audio1: bytes, audio2: bytes) -> bytes: """Mix two audio streams together by adding their samples. From c5d54d06bba7c92c524dd7d171130f0e33ec4140 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Wed, 2 Jul 2025 11:12:49 -0700 Subject: [PATCH 60/84] add run_llm to LLMMessagesAppendFrame and LLMMessagesUpdateFrame --- CHANGELOG.md | 7 ++++- src/pipecat/frames/frames.py | 4 +++ .../processors/aggregators/llm_response.py | 28 ++++++++++++++++--- 3 files changed, 34 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fcced9255..b34a057b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Added a new `SOXRStreamAudioResampler` for processing audio in chunks or streams. +- Added `run_llm` field to `LLMMessagesAppendFrame` and `LLMMessagesUpdateFrame` + frames. If true, a context frame will be pushed triggering the LLM to respond. + +- Added a new `SOXRStreamAudioResampler` for processing audio in chunks or + streams. If you write your own processor and need to use an audio resampler, + use the new `create_stream_resampler()`. - Added new `DailyParams.audio_in_user_tracks` to allow receiving one track per user (default) or a single track from the room (all participants mixed). diff --git a/src/pipecat/frames/frames.py b/src/pipecat/frames/frames.py index 59e862818..c7d7b4c75 100644 --- a/src/pipecat/frames/frames.py +++ b/src/pipecat/frames/frames.py @@ -484,9 +484,11 @@ class LLMMessagesAppendFrame(DataFrame): Parameters: messages: List of message dictionaries to append. + run_llm: Whether the context update should be sent to the LLM. """ messages: List[dict] + run_llm: Optional[bool] = None @dataclass @@ -499,9 +501,11 @@ class LLMMessagesUpdateFrame(DataFrame): Parameters: messages: List of message dictionaries to replace current context. + run_llm: Whether the context update should be sent to the LLM. """ messages: List[dict] + run_llm: Optional[bool] = None @dataclass diff --git a/src/pipecat/processors/aggregators/llm_response.py b/src/pipecat/processors/aggregators/llm_response.py index 85c4a3b06..99834447f 100644 --- a/src/pipecat/processors/aggregators/llm_response.py +++ b/src/pipecat/processors/aggregators/llm_response.py @@ -470,9 +470,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): @@ -544,6 +544,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) @@ -767,9 +777,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): @@ -808,6 +818,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 From abee0f853cf8e627a5249b44219df7131bcd1a22 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 2 Jul 2025 13:57:57 -0700 Subject: [PATCH 61/84] Add deprecation directives, add indexing, only autodoc members --- CONTRIBUTING.md | 54 +++++++++---------- docs/api/conf.py | 3 +- src/pipecat/pipeline/task.py | 4 ++ .../audio/audio_buffer_processor.py | 7 ++- src/pipecat/services/aws/tts.py | 7 ++- src/pipecat/services/aws_nova_sonic/aws.py | 2 +- src/pipecat/services/cartesia/tts.py | 10 +++- src/pipecat/services/deepgram/stt.py | 6 ++- src/pipecat/services/gladia/config.py | 7 ++- src/pipecat/services/gladia/stt.py | 3 ++ src/pipecat/services/google/stt.py | 2 +- src/pipecat/services/llm_service.py | 4 ++ src/pipecat/services/riva/stt.py | 5 +- src/pipecat/services/riva/tts.py | 5 +- src/pipecat/services/tts_service.py | 4 ++ src/pipecat/transports/base_transport.py | 50 +++++++++++++++++ src/pipecat/transports/services/daily.py | 3 ++ 17 files changed, 132 insertions(+), 44 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bee07b8e0..2551ba6c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,6 +86,13 @@ We follow Google-style docstrings with these specific conventions: - Use section headers like "Supported features:" or "Behavior:" before lists - For complex nested information, consider using paragraph format instead +**Deprecations:** + +- Use `warnings.warn()` in code for runtime deprecation warnings +- Add `.. deprecated::` directive in docstrings for documentation visibility +- Include version information and describe current status +- Describe parameters in present tense, use directive to indicate deprecation status + #### Examples: ```python @@ -103,14 +110,24 @@ class MyService(BaseService): - Feature three for advanced use cases """ - def __init__(self, param1: str, param2: bool = True, **kwargs): + def __init__(self, param1: str, old_param: str = None, **kwargs): """Initialize the service. Args: param1: Description of param1. - param2: Description of param2. Defaults to True. + old_param: Controls legacy behavior. + + .. deprecated:: 1.2.0 + This parameter no longer has any effect and will be removed in version 2.0. + **kwargs: Additional arguments passed to parent. """ + if old_param is not None: + import warnings + warnings.warn( + "Parameter 'old_param' is deprecated and will be removed in version 2.0.", + DeprecationWarning, + ) super().__init__(**kwargs) @property @@ -133,21 +150,6 @@ class MyService(BaseService): """ pass -# Dataclass -@dataclass -class ConfigParams: - """Configuration parameters for the service. - - Parameters: - host: The host address. - port: The port number. Defaults to 8080. - timeout: Connection timeout in seconds. - """ - - host: str - port: int = 8080 - timeout: float = 30.0 - # Dataclass with code examples @dataclass class MessageFrame: @@ -155,20 +157,12 @@ class MessageFrame: Supports both simple and content list message formats. - Examples: - Simple format:: + Example:: - [ - {"role": "user", "content": "Hello"}, - {"role": "assistant", "content": "Hi there!"} - ] - - Content list format:: - - [ - {"role": "user", "content": [{"type": "text", "text": "Hello"}]}, - {"role": "assistant", "content": [{"type": "text", "text": "Hi there!"}]} - ] + [ + {"role": "user", "content": "Hello"}, + {"role": "assistant", "content": "Hi there!"} + ] Parameters: messages: List of messages in OpenAI format. diff --git a/docs/api/conf.py b/docs/api/conf.py index 31c9fac25..1620341b9 100644 --- a/docs/api/conf.py +++ b/docs/api/conf.py @@ -38,9 +38,8 @@ napoleon_include_init_with_doc = True autodoc_default_options = { "members": True, "member-order": "bysource", - "undoc-members": True, + "undoc-members": False, "exclude-members": "__weakref__,model_config", - "no-index": True, "show-inheritance": True, } diff --git a/src/pipecat/pipeline/task.py b/src/pipecat/pipeline/task.py index a8b55e77c..2d3cfed77 100644 --- a/src/pipecat/pipeline/task.py +++ b/src/pipecat/pipeline/task.py @@ -76,6 +76,10 @@ class PipelineParams(BaseModel): heartbeats_period_secs: Period between heartbeats in seconds. interruption_strategies: Strategies for bot interruption behavior. observers: [deprecated] Use `observers` arg in `PipelineTask` class. + + .. deprecated:: 0.0.58 + Use the `observers` argument in the `PipelineTask` class instead. + report_only_initial_ttfb: Whether to report only initial time to first byte. send_initial_empty_metrics: Whether to send initial empty metrics. start_metadata: Additional metadata for pipeline start. diff --git a/src/pipecat/processors/audio/audio_buffer_processor.py b/src/pipecat/processors/audio/audio_buffer_processor.py index 78561b2f9..97f36e3a6 100644 --- a/src/pipecat/processors/audio/audio_buffer_processor.py +++ b/src/pipecat/processors/audio/audio_buffer_processor.py @@ -70,7 +70,12 @@ class AudioBufferProcessor(FrameProcessor): sample_rate: Desired output sample rate. If None, uses source rate. num_channels: Number of channels (1 for mono, 2 for stereo). Defaults to 1. buffer_size: Size of buffer before triggering events. 0 for no buffering. - user_continuous_stream: Deprecated parameter for backwards compatibility. + user_continuous_stream: Controls whether user audio is treated as a continuous + stream for buffering purposes. + + .. deprecated:: 0.0.72 + This parameter no longer has any effect and will be removed in a future version. + enable_turn_audio: Whether turn audio event handlers should be triggered. **kwargs: Additional arguments passed to parent class. """ diff --git a/src/pipecat/services/aws/tts.py b/src/pipecat/services/aws/tts.py index ce89dea9e..248d11210 100644 --- a/src/pipecat/services/aws/tts.py +++ b/src/pipecat/services/aws/tts.py @@ -343,7 +343,12 @@ class AWSPollyTTSService(TTSService): class PollyTTSService(AWSPollyTTSService): - """Deprecated alias for AWSPollyTTSService.""" + """Deprecated alias for AWSPollyTTSService. + + .. deprecated:: 0.0.67 + `PollyTTSService` is deprecated, use `AWSPollyTTSService` instead. + + """ def __init__(self, **kwargs): """Initialize the deprecated PollyTTSService. diff --git a/src/pipecat/services/aws_nova_sonic/aws.py b/src/pipecat/services/aws_nova_sonic/aws.py index a7832669e..90c93fc39 100644 --- a/src/pipecat/services/aws_nova_sonic/aws.py +++ b/src/pipecat/services/aws_nova_sonic/aws.py @@ -151,7 +151,7 @@ class CurrentContent: class Params(BaseModel): """Configuration parameters for AWS Nova Sonic. - Attributes: + Parameters: input_sample_rate: Audio input sample rate in Hz. input_sample_size: Audio input sample size in bits. input_channel_count: Number of input audio channels. diff --git a/src/pipecat/services/cartesia/tts.py b/src/pipecat/services/cartesia/tts.py index 68cab0600..8d88179a5 100644 --- a/src/pipecat/services/cartesia/tts.py +++ b/src/pipecat/services/cartesia/tts.py @@ -98,7 +98,10 @@ class CartesiaTTSService(AudioContextWordTTSService): Parameters: language: Language to use for synthesis. speed: Voice speed control (string or float). - emotion: List of emotion controls (deprecated). + emotion: List of emotion controls. + + .. deprecated:: 0.0.68 + The `emotion` parameter is deprecated and will be removed in a future version. """ language: Optional[Language] = Language.EN @@ -414,7 +417,10 @@ class CartesiaHttpTTSService(TTSService): Parameters: language: Language to use for synthesis. speed: Voice speed control (string or float). - emotion: List of emotion controls (deprecated). + emotion: List of emotion controls. + + .. deprecated:: 0.0.68 + The `emotion` parameter is deprecated and will be removed in a future version. """ language: Optional[Language] = Language.EN diff --git a/src/pipecat/services/deepgram/stt.py b/src/pipecat/services/deepgram/stt.py index d30e4da39..56658cad5 100644 --- a/src/pipecat/services/deepgram/stt.py +++ b/src/pipecat/services/deepgram/stt.py @@ -65,7 +65,11 @@ class DeepgramSTTService(STTService): Args: api_key: Deepgram API key for authentication. - url: Deprecated. Use base_url instead. + url: Custom Deepgram API base URL. + + .. deprecated:: 0.0.64 + Parameter `url` is deprecated, use `base_url` instead. + base_url: Custom Deepgram API base URL. sample_rate: Audio sample rate. If None, uses default or live_options value. live_options: Deepgram LiveOptions for detailed configuration. diff --git a/src/pipecat/services/gladia/config.py b/src/pipecat/services/gladia/config.py index 0af008773..09ed61bb0 100644 --- a/src/pipecat/services/gladia/config.py +++ b/src/pipecat/services/gladia/config.py @@ -153,7 +153,12 @@ class GladiaInputParams(BaseModel): custom_metadata: Additional metadata to include with requests endpointing: Silence duration in seconds to mark end of speech maximum_duration_without_endpointing: Maximum utterance duration without silence - language: DEPRECATED - Use language_config instead + language: Language code for transcription + + .. deprecated:: 0.0.62 + The 'language' parameter is deprecated and will be removed in a future version. + Use 'language_config' instead. + language_config: Detailed language configuration pre_processing: Audio pre-processing options realtime_processing: Real-time processing features diff --git a/src/pipecat/services/gladia/stt.py b/src/pipecat/services/gladia/stt.py index f931993b3..a92fd5aef 100644 --- a/src/pipecat/services/gladia/stt.py +++ b/src/pipecat/services/gladia/stt.py @@ -189,6 +189,9 @@ class GladiaSTTService(STTService): Provides automatic reconnection, audio buffering, and comprehensive error handling. For complete API documentation, see: https://docs.gladia.io/api-reference/v2/live/init + + .. deprecated:: 0.0.62 + Use :class:`~pipecat.services.gladia.config.GladiaInputParams` directly instead. """ # Maintain backward compatibility diff --git a/src/pipecat/services/google/stt.py b/src/pipecat/services/google/stt.py index 9cd2ac3ae..5e3e36e62 100644 --- a/src/pipecat/services/google/stt.py +++ b/src/pipecat/services/google/stt.py @@ -362,7 +362,7 @@ class GoogleSTTService(STTService): with streaming support. Handles audio transcription and optional voice activity detection. Implements automatic stream reconnection to handle Google's 4-minute streaming limit. - Attributes: + Parameters: InputParams: Configuration parameters for the STT service. STREAMING_LIMIT: Google Cloud's streaming limit in milliseconds (4 minutes). diff --git a/src/pipecat/services/llm_service.py b/src/pipecat/services/llm_service.py index 669a34803..cc4cd3916 100644 --- a/src/pipecat/services/llm_service.py +++ b/src/pipecat/services/llm_service.py @@ -273,6 +273,10 @@ class LLMService(AIService): parameter. start_callback: Legacy callback function (deprecated). Put initialization code at the top of your handler instead. + + .. deprecated:: 0.0.59 + The `start_callback` parameter is deprecated and will be removed in a future version. + cancel_on_interruption: Whether to cancel this function call when an interruption occurs. Defaults to True. """ diff --git a/src/pipecat/services/riva/stt.py b/src/pipecat/services/riva/stt.py index a7d114a12..23cff7c5e 100644 --- a/src/pipecat/services/riva/stt.py +++ b/src/pipecat/services/riva/stt.py @@ -660,8 +660,9 @@ class RivaSegmentedSTTService(SegmentedSTTService): class ParakeetSTTService(RivaSTTService): """Deprecated speech-to-text service using NVIDIA Parakeet models. - This class is deprecated. Use RivaSTTService instead for equivalent functionality - with Parakeet models by specifying the appropriate model_function_map. + .. deprecated:: 0.0.66 + This class is deprecated. Use `RivaSTTService` instead for equivalent functionality + with Parakeet models by specifying the appropriate model_function_map. """ def __init__( diff --git a/src/pipecat/services/riva/tts.py b/src/pipecat/services/riva/tts.py index b75f09db0..6e5937c6f 100644 --- a/src/pipecat/services/riva/tts.py +++ b/src/pipecat/services/riva/tts.py @@ -188,8 +188,9 @@ class RivaTTSService(TTSService): class FastPitchTTSService(RivaTTSService): """Deprecated FastPitch TTS service. - This class is deprecated. Use RivaTTSService instead for new implementations. - Provides backward compatibility for existing FastPitch TTS integrations. + .. deprecated:: 0.0.66 + This class is deprecated. Use RivaTTSService instead for new implementations. + Provides backward compatibility for existing FastPitch TTS integrations. """ def __init__( diff --git a/src/pipecat/services/tts_service.py b/src/pipecat/services/tts_service.py index 43ab5634f..62fcdd4e6 100644 --- a/src/pipecat/services/tts_service.py +++ b/src/pipecat/services/tts_service.py @@ -94,6 +94,10 @@ class TTSService(AIService): text_aggregator: Custom text aggregator for processing incoming text. text_filters: Sequence of text filters to apply after aggregation. text_filter: Single text filter (deprecated, use text_filters). + + .. deprecated:: 0.0.59 + Use `text_filters` instead, which allows multiple filters. + transport_destination: Destination for generated audio frames. **kwargs: Additional arguments passed to the parent AIService. """ diff --git a/src/pipecat/transports/base_transport.py b/src/pipecat/transports/base_transport.py index 8e722127f..b48cec02d 100644 --- a/src/pipecat/transports/base_transport.py +++ b/src/pipecat/transports/base_transport.py @@ -29,13 +29,53 @@ class TransportParams(BaseModel): Parameters: camera_in_enabled: Enable camera input (deprecated, use video_in_enabled). + + .. deprecated:: 0.0.66 + The `camera_in_enabled` parameter is deprecated, use + `video_in_enabled` instead. + camera_out_enabled: Enable camera output (deprecated, use video_out_enabled). + + .. deprecated:: 0.0.66 + The `camera_out_enabled` parameter is deprecated, use + `video_out_enabled` instead. + camera_out_is_live: Enable real-time camera output (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_is_live` parameter is deprecated, use + `video_out_is_live` instead. + camera_out_width: Camera output width in pixels (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_width` parameter is deprecated, use + `video_out_width` instead. + camera_out_height: Camera output height in pixels (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_height` parameter is deprecated, use + `video_out_height` instead. + camera_out_bitrate: Camera output bitrate in bits per second (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_bitrate` parameter is deprecated, use + `video_out_bitrate` instead. + camera_out_framerate: Camera output frame rate in FPS (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_framerate` parameter is deprecated, use + `video_out_framerate` instead. + camera_out_color_format: Camera output color format string (deprecated). + + .. deprecated:: 0.0.66 + The `camera_out_color_format` parameter is deprecated, use + `video_out_color_format` instead. + audio_out_enabled: Enable audio output streaming. audio_out_sample_rate: Output audio sample rate in Hz. audio_out_channels: Number of output audio channels. @@ -59,7 +99,17 @@ class TransportParams(BaseModel): video_out_color_format: Video output color format string. video_out_destinations: List of video output destination identifiers. vad_enabled: Enable Voice Activity Detection (deprecated). + + .. deprecated:: 0.0.66 + The `vad_enabled` parameter is deprecated, use `audio_in_enabled` + and `TransportParams.vad_analyzer` instead. + vad_audio_passthrough: Enable VAD audio passthrough (deprecated). + + .. deprecated:: 0.0.66 + The `vad_audio_passthrough` parameter is deprecated, use `audio_in_passthrough` + instead. + vad_analyzer: Voice Activity Detection analyzer instance. turn_analyzer: Turn-taking analyzer instance for conversation management. """ diff --git a/src/pipecat/transports/services/daily.py b/src/pipecat/transports/services/daily.py index a404f7648..fdbca6643 100644 --- a/src/pipecat/transports/services/daily.py +++ b/src/pipecat/transports/services/daily.py @@ -1977,6 +1977,9 @@ class DailyTransport(BaseTransport): async def send_dtmf(self, settings): """Send DTMF tones during a call (deprecated). + .. deprecated:: 0.0.69 + Push an `OutputDTMFFrame` or an `OutputDTMFUrgentFrame` instead. + Args: settings: DTMF settings including tones and target session. """ From a1784e323767306d2c229709c8472902133686ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Wed, 2 Jul 2025 16:08:54 -0700 Subject: [PATCH 62/84] update dev-requirements (dependabot) --- dev-requirements.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/dev-requirements.txt b/dev-requirements.txt index 2bab71684..f14a1d161 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -1,13 +1,13 @@ build~=1.2.2 -coverage~=7.6.12 +coverage~=7.9.1 grpcio-tools~=1.67.1 pip-tools~=7.4.1 -pre-commit~=4.0.1 -pyright~=1.1.400 -pytest~=8.3.4 -pytest-asyncio~=0.25.3 +pre-commit~=4.2.0 +pyright~=1.1.402 +pytest~=8.4.1 +pytest-asyncio~=1.0.0 pytest-aiohttp==1.1.0 -ruff~=0.11.13 -setuptools~=70.0.0 -setuptools_scm~=8.1.0 -python-dotenv~=1.0.1 +ruff~=0.12.1 +setuptools~=78.1.1 +setuptools_scm~=8.3.1 +python-dotenv~=1.1.1 From a437c2d365c2a1439d6aef1159cbc6ee08c41e67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Wed, 2 Jul 2025 16:33:24 -0700 Subject: [PATCH 63/84] update examples (dependabot) --- .../client/react-native/package-lock.json | 12 +- .../nextjs-webhook-server/package-lock.json | 118 ++++++++---------- .../client/package-lock.json | 104 +++++++-------- 3 files changed, 110 insertions(+), 124 deletions(-) diff --git a/examples/bot-ready-signalling/client/react-native/package-lock.json b/examples/bot-ready-signalling/client/react-native/package-lock.json index 8cb49bde7..244ba6a98 100644 --- a/examples/bot-ready-signalling/client/react-native/package-lock.json +++ b/examples/bot-ready-signalling/client/react-native/package-lock.json @@ -4364,9 +4364,9 @@ } }, "node_modules/brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -6081,9 +6081,9 @@ } }, "node_modules/glob/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", "dependencies": { "balanced-match": "^1.0.0" } diff --git a/examples/deployment/pipecat-cloud-daily-pstn-server/nextjs-webhook-server/package-lock.json b/examples/deployment/pipecat-cloud-daily-pstn-server/nextjs-webhook-server/package-lock.json index 2710cd886..e466f5ce6 100644 --- a/examples/deployment/pipecat-cloud-daily-pstn-server/nextjs-webhook-server/package-lock.json +++ b/examples/deployment/pipecat-cloud-daily-pstn-server/nextjs-webhook-server/package-lock.json @@ -215,10 +215,9 @@ } }, "node_modules/@next/env": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/env/-/env-14.2.26.tgz", - "integrity": "sha512-vO//GJ/YBco+H7xdQhzJxF7ub3SUwft76jwaeOyVVQFHCi5DCnkP16WHB+JBylo4vOKPoZBlR94Z8xBxNBdNJA==", - "license": "MIT" + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/env/-/env-14.2.30.tgz", + "integrity": "sha512-KBiBKrDY6kxTQWGzKjQB7QirL3PiiOkV7KW98leHFjtVRKtft76Ra5qSA/SL75xT44dp6hOcqiiJ6iievLOYug==" }, "node_modules/@next/eslint-plugin-next": { "version": "14.2.25", @@ -231,13 +230,12 @@ } }, "node_modules/@next/swc-darwin-arm64": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-14.2.26.tgz", - "integrity": "sha512-zDJY8gsKEseGAxG+C2hTMT0w9Nk9N1Sk1qV7vXYz9MEiyRoF5ogQX2+vplyUMIfygnjn9/A04I6yrUTRTuRiyQ==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-14.2.30.tgz", + "integrity": "sha512-EAqfOTb3bTGh9+ewpO/jC59uACadRHM6TSA9DdxJB/6gxOpyV+zrbqeXiFTDy9uV6bmipFDkfpAskeaDcO+7/g==", "cpu": [ "arm64" ], - "license": "MIT", "optional": true, "os": [ "darwin" @@ -247,13 +245,12 @@ } }, "node_modules/@next/swc-darwin-x64": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.26.tgz", - "integrity": "sha512-U0adH5ryLfmTDkahLwG9sUQG2L0a9rYux8crQeC92rPhi3jGQEY47nByQHrVrt3prZigadwj/2HZ1LUUimuSbg==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.30.tgz", + "integrity": "sha512-TyO7Wz1IKE2kGv8dwQ0bmPL3s44EKVencOqwIY69myoS3rdpO1NPg5xPM5ymKu7nfX4oYJrpMxv8G9iqLsnL4A==", "cpu": [ "x64" ], - "license": "MIT", "optional": true, "os": [ "darwin" @@ -263,13 +260,12 @@ } }, "node_modules/@next/swc-linux-arm64-gnu": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.26.tgz", - "integrity": "sha512-SINMl1I7UhfHGM7SoRiw0AbwnLEMUnJ/3XXVmhyptzriHbWvPPbbm0OEVG24uUKhuS1t0nvN/DBvm5kz6ZIqpg==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.30.tgz", + "integrity": "sha512-I5lg1fgPJ7I5dk6mr3qCH1hJYKJu1FsfKSiTKoYwcuUf53HWTrEkwmMI0t5ojFKeA6Vu+SfT2zVy5NS0QLXV4Q==", "cpu": [ "arm64" ], - "license": "MIT", "optional": true, "os": [ "linux" @@ -279,13 +275,12 @@ } }, "node_modules/@next/swc-linux-arm64-musl": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.26.tgz", - "integrity": "sha512-s6JaezoyJK2DxrwHWxLWtJKlqKqTdi/zaYigDXUJ/gmx/72CrzdVZfMvUc6VqnZ7YEvRijvYo+0o4Z9DencduA==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.30.tgz", + "integrity": "sha512-8GkNA+sLclQyxgzCDs2/2GSwBc92QLMrmYAmoP2xehe5MUKBLB2cgo34Yu242L1siSkwQkiV4YLdCnjwc/Micw==", "cpu": [ "arm64" ], - "license": "MIT", "optional": true, "os": [ "linux" @@ -295,13 +290,12 @@ } }, "node_modules/@next/swc-linux-x64-gnu": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.26.tgz", - "integrity": "sha512-FEXeUQi8/pLr/XI0hKbe0tgbLmHFRhgXOUiPScz2hk0hSmbGiU8aUqVslj/6C6KA38RzXnWoJXo4FMo6aBxjzg==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.30.tgz", + "integrity": "sha512-8Ly7okjssLuBoe8qaRCcjGtcMsv79hwzn/63wNeIkzJVFVX06h5S737XNr7DZwlsbTBDOyI6qbL2BJB5n6TV/w==", "cpu": [ "x64" ], - "license": "MIT", "optional": true, "os": [ "linux" @@ -311,13 +305,12 @@ } }, "node_modules/@next/swc-linux-x64-musl": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.26.tgz", - "integrity": "sha512-BUsomaO4d2DuXhXhgQCVt2jjX4B4/Thts8nDoIruEJkhE5ifeQFtvW5c9JkdOtYvE5p2G0hcwQ0UbRaQmQwaVg==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.30.tgz", + "integrity": "sha512-dBmV1lLNeX4mR7uI7KNVHsGQU+OgTG5RGFPi3tBJpsKPvOPtg9poyav/BYWrB3GPQL4dW5YGGgalwZ79WukbKQ==", "cpu": [ "x64" ], - "license": "MIT", "optional": true, "os": [ "linux" @@ -327,13 +320,12 @@ } }, "node_modules/@next/swc-win32-arm64-msvc": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.26.tgz", - "integrity": "sha512-5auwsMVzT7wbB2CZXQxDctpWbdEnEW/e66DyXO1DcgHxIyhP06awu+rHKshZE+lPLIGiwtjo7bsyeuubewwxMw==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.30.tgz", + "integrity": "sha512-6MMHi2Qc1Gkq+4YLXAgbYslE1f9zMGBikKMdmQRHXjkGPot1JY3n5/Qrbg40Uvbi8//wYnydPnyvNhI1DMUW1g==", "cpu": [ "arm64" ], - "license": "MIT", "optional": true, "os": [ "win32" @@ -343,13 +335,12 @@ } }, "node_modules/@next/swc-win32-ia32-msvc": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.26.tgz", - "integrity": "sha512-GQWg/Vbz9zUGi9X80lOeGsz1rMH/MtFO/XqigDznhhhTfDlDoynCM6982mPCbSlxJ/aveZcKtTlwfAjwhyxDpg==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.30.tgz", + "integrity": "sha512-pVZMnFok5qEX4RT59mK2hEVtJX+XFfak+/rjHpyFh7juiT52r177bfFKhnlafm0UOSldhXjj32b+LZIOdswGTg==", "cpu": [ "ia32" ], - "license": "MIT", "optional": true, "os": [ "win32" @@ -359,13 +350,12 @@ } }, "node_modules/@next/swc-win32-x64-msvc": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.26.tgz", - "integrity": "sha512-2rdB3T1/Gp7bv1eQTTm9d1Y1sv9UuJ2LAwOE0Pe2prHKe32UNscj7YS13fRB37d0GAiGNR+Y7ZcW8YjDI8Ns0w==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.30.tgz", + "integrity": "sha512-4KCo8hMZXMjpTzs3HOqOGYYwAXymXIy7PEPAXNEcEOyKqkjiDlECumrWziy+JEF0Oi4ILHGxzgQ3YiMGG2t/Lg==", "cpu": [ "x64" ], - "license": "MIT", "optional": true, "os": [ "win32" @@ -620,11 +610,10 @@ } }, "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", "dev": true, - "license": "MIT", "dependencies": { "balanced-match": "^1.0.0" } @@ -1224,11 +1213,10 @@ "license": "MIT" }, "node_modules/brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", "dev": true, - "license": "MIT", "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -2614,11 +2602,10 @@ } }, "node_modules/glob/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", "dev": true, - "license": "MIT", "dependencies": { "balanced-match": "^1.0.0" } @@ -3613,12 +3600,11 @@ "license": "MIT" }, "node_modules/next": { - "version": "14.2.26", - "resolved": "https://registry.npmjs.org/next/-/next-14.2.26.tgz", - "integrity": "sha512-b81XSLihMwCfwiUVRRja3LphLo4uBBMZEzBBWMaISbKTwOmq3wPknIETy/8000tr7Gq4WmbuFYPS7jOYIf+ZJw==", - "license": "MIT", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/next/-/next-14.2.30.tgz", + "integrity": "sha512-+COdu6HQrHHFQ1S/8BBsCag61jZacmvbuL2avHvQFbWa2Ox7bE+d8FyNgxRLjXQ5wtPyQwEmk85js/AuaG2Sbg==", "dependencies": { - "@next/env": "14.2.26", + "@next/env": "14.2.30", "@swc/helpers": "0.5.5", "busboy": "1.6.0", "caniuse-lite": "^1.0.30001579", @@ -3633,15 +3619,15 @@ "node": ">=18.17.0" }, "optionalDependencies": { - "@next/swc-darwin-arm64": "14.2.26", - "@next/swc-darwin-x64": "14.2.26", - "@next/swc-linux-arm64-gnu": "14.2.26", - "@next/swc-linux-arm64-musl": "14.2.26", - "@next/swc-linux-x64-gnu": "14.2.26", - "@next/swc-linux-x64-musl": "14.2.26", - "@next/swc-win32-arm64-msvc": "14.2.26", - "@next/swc-win32-ia32-msvc": "14.2.26", - "@next/swc-win32-x64-msvc": "14.2.26" + "@next/swc-darwin-arm64": "14.2.30", + "@next/swc-darwin-x64": "14.2.30", + "@next/swc-linux-arm64-gnu": "14.2.30", + "@next/swc-linux-arm64-musl": "14.2.30", + "@next/swc-linux-x64-gnu": "14.2.30", + "@next/swc-linux-x64-musl": "14.2.30", + "@next/swc-win32-arm64-msvc": "14.2.30", + "@next/swc-win32-ia32-msvc": "14.2.30", + "@next/swc-win32-x64-msvc": "14.2.30" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", diff --git a/examples/storytelling-chatbot/client/package-lock.json b/examples/storytelling-chatbot/client/package-lock.json index 57761664d..745475270 100644 --- a/examples/storytelling-chatbot/client/package-lock.json +++ b/examples/storytelling-chatbot/client/package-lock.json @@ -345,9 +345,9 @@ } }, "node_modules/@next/env": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/env/-/env-14.2.28.tgz", - "integrity": "sha512-PAmWhJfJQlP+kxZwCjrVd9QnR5x0R3u0mTXTiZDgSd4h5LdXmjxCCWbN9kq6hkZBOax8Rm3xDW5HagWyJuT37g==" + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/env/-/env-14.2.30.tgz", + "integrity": "sha512-KBiBKrDY6kxTQWGzKjQB7QirL3PiiOkV7KW98leHFjtVRKtft76Ra5qSA/SL75xT44dp6hOcqiiJ6iievLOYug==" }, "node_modules/@next/eslint-plugin-next": { "version": "14.1.4", @@ -359,9 +359,9 @@ } }, "node_modules/@next/swc-darwin-arm64": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-14.2.28.tgz", - "integrity": "sha512-kzGChl9setxYWpk3H6fTZXXPFFjg7urptLq5o5ZgYezCrqlemKttwMT5iFyx/p1e/JeglTwDFRtb923gTJ3R1w==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-14.2.30.tgz", + "integrity": "sha512-EAqfOTb3bTGh9+ewpO/jC59uACadRHM6TSA9DdxJB/6gxOpyV+zrbqeXiFTDy9uV6bmipFDkfpAskeaDcO+7/g==", "cpu": [ "arm64" ], @@ -374,9 +374,9 @@ } }, "node_modules/@next/swc-darwin-x64": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.28.tgz", - "integrity": "sha512-z6FXYHDJlFOzVEOiiJ/4NG8aLCeayZdcRSMjPDysW297Up6r22xw6Ea9AOwQqbNsth8JNgIK8EkWz2IDwaLQcw==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.30.tgz", + "integrity": "sha512-TyO7Wz1IKE2kGv8dwQ0bmPL3s44EKVencOqwIY69myoS3rdpO1NPg5xPM5ymKu7nfX4oYJrpMxv8G9iqLsnL4A==", "cpu": [ "x64" ], @@ -389,9 +389,9 @@ } }, "node_modules/@next/swc-linux-arm64-gnu": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.28.tgz", - "integrity": "sha512-9ARHLEQXhAilNJ7rgQX8xs9aH3yJSj888ssSjJLeldiZKR4D7N08MfMqljk77fAwZsWwsrp8ohHsMvurvv9liQ==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.30.tgz", + "integrity": "sha512-I5lg1fgPJ7I5dk6mr3qCH1hJYKJu1FsfKSiTKoYwcuUf53HWTrEkwmMI0t5ojFKeA6Vu+SfT2zVy5NS0QLXV4Q==", "cpu": [ "arm64" ], @@ -404,9 +404,9 @@ } }, "node_modules/@next/swc-linux-arm64-musl": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.28.tgz", - "integrity": "sha512-p6gvatI1nX41KCizEe6JkF0FS/cEEF0u23vKDpl+WhPe/fCTBeGkEBh7iW2cUM0rvquPVwPWdiUR6Ebr/kQWxQ==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.30.tgz", + "integrity": "sha512-8GkNA+sLclQyxgzCDs2/2GSwBc92QLMrmYAmoP2xehe5MUKBLB2cgo34Yu242L1siSkwQkiV4YLdCnjwc/Micw==", "cpu": [ "arm64" ], @@ -419,9 +419,9 @@ } }, "node_modules/@next/swc-linux-x64-gnu": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.28.tgz", - "integrity": "sha512-nsiSnz2wO6GwMAX2o0iucONlVL7dNgKUqt/mDTATGO2NY59EO/ZKnKEr80BJFhuA5UC1KZOMblJHWZoqIJddpA==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.30.tgz", + "integrity": "sha512-8Ly7okjssLuBoe8qaRCcjGtcMsv79hwzn/63wNeIkzJVFVX06h5S737XNr7DZwlsbTBDOyI6qbL2BJB5n6TV/w==", "cpu": [ "x64" ], @@ -434,9 +434,9 @@ } }, "node_modules/@next/swc-linux-x64-musl": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.28.tgz", - "integrity": "sha512-+IuGQKoI3abrXFqx7GtlvNOpeExUH1mTIqCrh1LGFf8DnlUcTmOOCApEnPJUSLrSbzOdsF2ho2KhnQoO0I1RDw==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.30.tgz", + "integrity": "sha512-dBmV1lLNeX4mR7uI7KNVHsGQU+OgTG5RGFPi3tBJpsKPvOPtg9poyav/BYWrB3GPQL4dW5YGGgalwZ79WukbKQ==", "cpu": [ "x64" ], @@ -449,9 +449,9 @@ } }, "node_modules/@next/swc-win32-arm64-msvc": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.28.tgz", - "integrity": "sha512-l61WZ3nevt4BAnGksUVFKy2uJP5DPz2E0Ma/Oklvo3sGj9sw3q7vBWONFRgz+ICiHpW5mV+mBrkB3XEubMrKaA==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.30.tgz", + "integrity": "sha512-6MMHi2Qc1Gkq+4YLXAgbYslE1f9zMGBikKMdmQRHXjkGPot1JY3n5/Qrbg40Uvbi8//wYnydPnyvNhI1DMUW1g==", "cpu": [ "arm64" ], @@ -464,9 +464,9 @@ } }, "node_modules/@next/swc-win32-ia32-msvc": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.28.tgz", - "integrity": "sha512-+Kcp1T3jHZnJ9v9VTJ/yf1t/xmtFAc/Sge4v7mVc1z+NYfYzisi8kJ9AsY8itbgq+WgEwMtOpiLLJsUy2qnXZw==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.30.tgz", + "integrity": "sha512-pVZMnFok5qEX4RT59mK2hEVtJX+XFfak+/rjHpyFh7juiT52r177bfFKhnlafm0UOSldhXjj32b+LZIOdswGTg==", "cpu": [ "ia32" ], @@ -479,9 +479,9 @@ } }, "node_modules/@next/swc-win32-x64-msvc": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.28.tgz", - "integrity": "sha512-1gCmpvyhz7DkB1srRItJTnmR2UwQPAUXXIg9r0/56g3O8etGmwlX68skKXJOp9EejW3hhv7nSQUJ2raFiz4MoA==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.30.tgz", + "integrity": "sha512-4KCo8hMZXMjpTzs3HOqOGYYwAXymXIy7PEPAXNEcEOyKqkjiDlECumrWziy+JEF0Oi4ILHGxzgQ3YiMGG2t/Lg==", "cpu": [ "x64" ], @@ -1317,9 +1317,9 @@ } }, "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", "dev": true, "dependencies": { "balanced-match": "^1.0.0" @@ -1960,9 +1960,9 @@ "integrity": "sha512-AlcaJBi/pqqJBIQ8U9Mcpc9i8Aqxn88Skv5d+xBX006BY5u8N3mGLHa5Lgppa7L/HfwgwLgZ6NYs+Ag6uUmJRA==" }, "node_modules/brace-expansion": { - "version": "1.1.11", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", - "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "version": "1.1.12", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz", + "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==", "dev": true, "dependencies": { "balanced-match": "^1.0.0", @@ -3391,9 +3391,9 @@ } }, "node_modules/glob/node_modules/brace-expansion": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", - "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", "dependencies": { "balanced-match": "^1.0.0" } @@ -4389,11 +4389,11 @@ "dev": true }, "node_modules/next": { - "version": "14.2.28", - "resolved": "https://registry.npmjs.org/next/-/next-14.2.28.tgz", - "integrity": "sha512-QLEIP/kYXynIxtcKB6vNjtWLVs3Y4Sb+EClTC/CSVzdLD1gIuItccpu/n1lhmduffI32iPGEK2cLLxxt28qgYA==", + "version": "14.2.30", + "resolved": "https://registry.npmjs.org/next/-/next-14.2.30.tgz", + "integrity": "sha512-+COdu6HQrHHFQ1S/8BBsCag61jZacmvbuL2avHvQFbWa2Ox7bE+d8FyNgxRLjXQ5wtPyQwEmk85js/AuaG2Sbg==", "dependencies": { - "@next/env": "14.2.28", + "@next/env": "14.2.30", "@swc/helpers": "0.5.5", "busboy": "1.6.0", "caniuse-lite": "^1.0.30001579", @@ -4408,15 +4408,15 @@ "node": ">=18.17.0" }, "optionalDependencies": { - "@next/swc-darwin-arm64": "14.2.28", - "@next/swc-darwin-x64": "14.2.28", - "@next/swc-linux-arm64-gnu": "14.2.28", - "@next/swc-linux-arm64-musl": "14.2.28", - "@next/swc-linux-x64-gnu": "14.2.28", - "@next/swc-linux-x64-musl": "14.2.28", - "@next/swc-win32-arm64-msvc": "14.2.28", - "@next/swc-win32-ia32-msvc": "14.2.28", - "@next/swc-win32-x64-msvc": "14.2.28" + "@next/swc-darwin-arm64": "14.2.30", + "@next/swc-darwin-x64": "14.2.30", + "@next/swc-linux-arm64-gnu": "14.2.30", + "@next/swc-linux-arm64-musl": "14.2.30", + "@next/swc-linux-x64-gnu": "14.2.30", + "@next/swc-linux-x64-musl": "14.2.30", + "@next/swc-win32-arm64-msvc": "14.2.30", + "@next/swc-win32-ia32-msvc": "14.2.30", + "@next/swc-win32-x64-msvc": "14.2.30" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", From 4ae045d704656ed97b71e81d5e8563120154f43e Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Wed, 2 Jul 2025 19:53:48 -0700 Subject: [PATCH 64/84] Add docs deprecation for handle_function_call_start --- src/pipecat/processors/frameworks/rtvi.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/pipecat/processors/frameworks/rtvi.py b/src/pipecat/processors/frameworks/rtvi.py index 7c03561a9..06784d0df 100644 --- a/src/pipecat/processors/frameworks/rtvi.py +++ b/src/pipecat/processors/frameworks/rtvi.py @@ -1005,6 +1005,10 @@ class RTVIProcessor(FrameProcessor): ): """Handle the start of a function call from the LLM. + .. deprecated:: 0.0.66 + This method is deprecated and will be removed in a future version. + Use `RTVIProcessor.handle_function_call()` instead. + Args: function_name: Name of the function being called. llm: The LLM processor making the call. From 72d503d3a3a1561e68e042239d1571ad3db7e132 Mon Sep 17 00:00:00 2001 From: Victor Date: Thu, 3 Jul 2025 10:48:26 -0300 Subject: [PATCH 65/84] Azure TTS fixed by clearing the audio queue before synthesizing the next text --- CHANGELOG.md | 3 +++ src/pipecat/services/azure/tts.py | 7 +++++++ 2 files changed, 10 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b34a057b8..bbfc5d304 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- Fixed an issue where audio would get stuck in the queue when an interrupt occurs + during Azure TTS synthesis. + - Fixed a race condition that occurs in Python 3.10+ where the task could miss the `CancelledError` and continue running indefinitely, freezing the pipeline. diff --git a/src/pipecat/services/azure/tts.py b/src/pipecat/services/azure/tts.py index 07e706a9b..0cf029c6b 100644 --- a/src/pipecat/services/azure/tts.py +++ b/src/pipecat/services/azure/tts.py @@ -282,6 +282,13 @@ class AzureTTSService(AzureBaseTTSService): """ logger.debug(f"{self}: Generating TTS [{text}]") + # Clear the audio queue in case there's still audio in it, causing the next audio response + # to be cut off by the 'None' element returned at the end of the previous audio synthesis. + # Empty the audio queue before processing the new text + while not self._audio_queue.empty(): + self._audio_queue.get_nowait() + self._audio_queue.task_done() + try: if self._speech_synthesizer is None: error_msg = "Speech synthesizer not initialized." From 30a3b24287017cbbcb2f1e22f4e431a932cdff82 Mon Sep 17 00:00:00 2001 From: carolin-tavus Date: Thu, 3 Jul 2025 14:02:54 +0000 Subject: [PATCH 66/84] Add persona validation (check that microphone is enabled) --- src/pipecat/transports/services/tavus.py | 26 ++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/pipecat/transports/services/tavus.py b/src/pipecat/transports/services/tavus.py index 10ae001e0..4e8ab208a 100644 --- a/src/pipecat/transports/services/tavus.py +++ b/src/pipecat/transports/services/tavus.py @@ -126,6 +126,31 @@ class TavusApi: response = await r.json() logger.debug(f"Fetched Tavus persona: {response}") return response["persona_name"] + + async def _validate_persona(self, persona_id: str): + """Validate that the persona's microphone is enabled. + + Args: + persona_id: ID of the persona to validate. + """ + if self._dev_room_url is not None: + return + + url = f"{self.BASE_URL}/personas/{persona_id}" + async with self._session.get(url, headers=self._headers) as r: + r.raise_for_status() + response = await r.json() + logger.debug(f"Fetched Tavus persona: {response}") + try: + transport_settings = response.get("layers", {}).get("transport", {}) + microphone_enabled = transport_settings.get("input_settings", {}).get("microphone", "") + if microphone_enabled != "enabled": + raise Exception("Microphone is not enabled for this persona. Please update the persona or use the persona pipecat-stream.") + except Exception as e: + logger.error(f"Error validating persona {persona_id}: {e}") + raise e + logger.info(f"Persona {persona_id} is valid") + return True class TavusCallbacks(BaseModel): @@ -200,6 +225,7 @@ class TavusTransportClient: async def _initialize(self) -> str: """Initialize the conversation and return the room URL.""" + await self._api._validate_persona(self._persona_id) response = await self._api.create_conversation(self._replica_id, self._persona_id) self._conversation_id = response["conversation_id"] return response["conversation_url"] From cb81f3d50e0fd3253dd8ea797be5a74563fda2e4 Mon Sep 17 00:00:00 2001 From: carolin-tavus Date: Thu, 3 Jul 2025 14:38:20 +0000 Subject: [PATCH 67/84] format --- src/pipecat/transports/services/tavus.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/pipecat/transports/services/tavus.py b/src/pipecat/transports/services/tavus.py index 4e8ab208a..060c0ec61 100644 --- a/src/pipecat/transports/services/tavus.py +++ b/src/pipecat/transports/services/tavus.py @@ -126,10 +126,10 @@ class TavusApi: response = await r.json() logger.debug(f"Fetched Tavus persona: {response}") return response["persona_name"] - + async def _validate_persona(self, persona_id: str): """Validate that the persona's microphone is enabled. - + Args: persona_id: ID of the persona to validate. """ @@ -143,9 +143,13 @@ class TavusApi: logger.debug(f"Fetched Tavus persona: {response}") try: transport_settings = response.get("layers", {}).get("transport", {}) - microphone_enabled = transport_settings.get("input_settings", {}).get("microphone", "") + microphone_enabled = transport_settings.get("input_settings", {}).get( + "microphone", "" + ) if microphone_enabled != "enabled": - raise Exception("Microphone is not enabled for this persona. Please update the persona or use the persona pipecat-stream.") + raise Exception( + "Microphone is not enabled for this persona. Please update the persona or use the persona pipecat-stream." + ) except Exception as e: logger.error(f"Error validating persona {persona_id}: {e}") raise e From bf664534ccb79b9d92313e41476644c117639dda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 08:15:31 -0700 Subject: [PATCH 68/84] PipelineTask: cancel idle queue before cancelling task --- src/pipecat/pipeline/task.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pipecat/pipeline/task.py b/src/pipecat/pipeline/task.py index a8b55e77c..8038be077 100644 --- a/src/pipecat/pipeline/task.py +++ b/src/pipecat/pipeline/task.py @@ -565,6 +565,7 @@ class PipelineTask(BasePipelineTask): async def _maybe_cancel_idle_task(self): """Cancel idle monitoring task if it is running.""" if self._idle_timeout_secs and self._idle_monitor_task: + self._idle_queue.cancel() await self._task_manager.cancel_task(self._idle_monitor_task) self._idle_monitor_task = None From 64c8230960f3c7f4bcda38fcd8c6f22a331f3955 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 08:15:31 -0700 Subject: [PATCH 69/84] PipelineTask: cancel idle queue before cancelling task --- src/pipecat/pipeline/task.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/pipecat/pipeline/task.py b/src/pipecat/pipeline/task.py index 2d3cfed77..5ddd97628 100644 --- a/src/pipecat/pipeline/task.py +++ b/src/pipecat/pipeline/task.py @@ -569,6 +569,7 @@ class PipelineTask(BasePipelineTask): async def _maybe_cancel_idle_task(self): """Cancel idle monitoring task if it is running.""" if self._idle_timeout_secs and self._idle_monitor_task: + self._idle_queue.cancel() await self._task_manager.cancel_task(self._idle_monitor_task) self._idle_monitor_task = None From af8b4901d4ad565ad50e4876beebbd0eaaf03bfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 08:18:48 -0700 Subject: [PATCH 70/84] DtmfAggregator: cancel interruption task to avoid a dangling task --- .../processors/aggregators/dtmf_aggregator.py | 17 ++++++++++------- tests/test_dtmf_aggregator.py | 2 +- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/src/pipecat/processors/aggregators/dtmf_aggregator.py b/src/pipecat/processors/aggregators/dtmf_aggregator.py index f3485245c..43c59b661 100644 --- a/src/pipecat/processors/aggregators/dtmf_aggregator.py +++ b/src/pipecat/processors/aggregators/dtmf_aggregator.py @@ -64,6 +64,7 @@ class DTMFAggregator(FrameProcessor): self._digit_event = asyncio.Event() self._aggregation_task: Optional[asyncio.Task] = None + self._interruption_task: Optional[asyncio.Task] = None async def process_frame(self, frame: Frame, direction: FrameDirection) -> None: """Process incoming frames and handle DTMF aggregation. @@ -81,6 +82,7 @@ class DTMFAggregator(FrameProcessor): if self._aggregation: await self._flush_aggregation() await self._stop_aggregation_task() + await self._stop_interruption_task() await self.push_frame(frame, direction) elif isinstance(frame, InputDTMFFrame): # Push the DTMF frame downstream first @@ -100,7 +102,7 @@ class DTMFAggregator(FrameProcessor): # For first digit, schedule interruption in separate task if is_first_digit: - asyncio.create_task(self._send_interruption_task()) + self._interruption_task = self.create_task(self._send_interruption_task()) # Check for immediate flush conditions if frame.button == self._termination_digit: @@ -111,12 +113,13 @@ class DTMFAggregator(FrameProcessor): async def _send_interruption_task(self): """Send interruption frame safely in a separate task.""" - try: - # Send the interruption frame - await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM) - except Exception as e: - # Log error but don't propagate - print(f"Error sending interruption: {e}") + await self.push_frame(BotInterruptionFrame(), FrameDirection.UPSTREAM) + + async def _stop_interruption_task(self) -> None: + """Stops the interruption task.""" + if self._interruption_task: + await self.cancel_task(self._interruption_task) + self._interruption_task = None def _create_aggregation_task(self) -> None: """Creates the aggregation task if it hasn't been created yet.""" diff --git a/tests/test_dtmf_aggregator.py b/tests/test_dtmf_aggregator.py index d2e1cc9aa..40d3ece13 100644 --- a/tests/test_dtmf_aggregator.py +++ b/tests/test_dtmf_aggregator.py @@ -214,7 +214,7 @@ class TestDTMFAggregator(unittest.IsolatedAsyncioTestCase): ] # All the InputDTMFFrames plus one TranscriptionFrame - expected_down_frames = [InputDTMFFrame] * 12 + [TranscriptionFrame] + expected_down_frames = [InputDTMFFrame] * len(frames_to_send) + [TranscriptionFrame] received_down_frames, _ = await run_test( aggregator, From a62be8ea323ee7ecfdced41bad6e3b397bfc44e6 Mon Sep 17 00:00:00 2001 From: vipyne Date: Thu, 3 Jul 2025 11:44:34 -0500 Subject: [PATCH 71/84] docs: add changelog line for gemini files api --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbfc5d304..a7d9cc05b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,6 +61,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `session_token` parameter to `AWSNovaSonicLLMService`. +- Added Gemini Multimodal Live File API for uploading, fetching, listing, and +deleting files. See `26f-gemini-multimodal-live-files-api.py` for example usage. + ### Changed - Updated all the services to use the new `SOXRStreamAudioResampler`, ensuring smooth From 1a8d512abb8b9a296b9e9a78056fb851a69c932b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 10:01:42 -0700 Subject: [PATCH 72/84] scripts(evals): make sure we cancel pending tasks after timeout --- scripts/evals/eval.py | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/scripts/evals/eval.py b/scripts/evals/eval.py index 743b62222..e683ff8e1 100644 --- a/scripts/evals/eval.py +++ b/scripts/evals/eval.py @@ -100,17 +100,18 @@ class EvalRunner: start_time = time.time() try: - await asyncio.wait( - [ - asyncio.create_task(run_example_pipeline(script_path)), - asyncio.create_task(run_eval_pipeline(self, example_file, prompt, eval)), - ], - timeout=90, - ) - except asyncio.CancelledError: - pass + tasks = [ + asyncio.create_task(run_example_pipeline(script_path)), + asyncio.create_task(run_eval_pipeline(self, example_file, prompt, eval)), + ] + _, pending = await asyncio.wait(tasks, timeout=10) + if pending: + logger.error(f"ERROR: Eval timeout expired, cancelling pending tasks...") + for task in pending: + task.cancel() + await asyncio.gather(*pending, return_exceptions=True) except Exception as e: - print(f"ERROR: Unable to run {example_file}: {e}") + logger.error(f"ERROR: Unable to run {example_file}: {e}") try: result = await asyncio.wait_for(self._queue.get(), timeout=1.0) @@ -134,6 +135,7 @@ class EvalRunner: async def save_audio(self, name: str, audio: bytes, sample_rate: int, num_channels: int): if len(audio) > 0: filename = self._recording_file_name(name) + logger.debug(f"Saving {name} audio to {filename}") with io.BytesIO() as buffer: with wave.open(buffer, "wb") as wf: wf.setsampwidth(2) @@ -142,7 +144,6 @@ class EvalRunner: wf.writeframes(audio) async with aiofiles.open(filename, "wb") as file: await file.write(buffer.getvalue()) - logger.debug(f"Saving {name} audio to {filename}") else: logger.warning(f"There's no audio to save for {name}") From 6045a8ad8c9c7c3c9fc26c6db52da0d70a03b1c9 Mon Sep 17 00:00:00 2001 From: otaqwawi Date: Fri, 4 Jul 2025 01:12:35 +0700 Subject: [PATCH 73/84] Add option to change the base URL for Google Generative AI. (#2113) * Add option to change the base URL for Google Generative AI. This would be useful to support private instance or gateway of the API * fix: add proper type hints for http_options in Google LLM service --- src/pipecat/services/google/llm.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/pipecat/services/google/llm.py b/src/pipecat/services/google/llm.py index bc7595382..f7589beaf 100644 --- a/src/pipecat/services/google/llm.py +++ b/src/pipecat/services/google/llm.py @@ -67,6 +67,7 @@ try: Content, FunctionCall, FunctionResponse, + HttpOptions, GenerateContentConfig, Part, ) @@ -678,6 +679,7 @@ class GoogleLLMService(LLMService): system_instruction: Optional[str] = None, tools: Optional[List[Dict[str, Any]]] = None, tool_config: Optional[Dict[str, Any]] = None, + http_options: Optional[HttpOptions] = None, **kwargs, ): """Initialize the Google LLM service. @@ -689,6 +691,7 @@ class GoogleLLMService(LLMService): system_instruction: System instruction/prompt for the model. tools: List of available tools/functions. tool_config: Configuration for tool usage. + http_options: HTTP options for the client. **kwargs: Additional arguments passed to parent class. """ super().__init__(**kwargs) @@ -698,7 +701,8 @@ class GoogleLLMService(LLMService): self.set_model_name(model) self._api_key = api_key self._system_instruction = system_instruction - self._create_client(api_key) + self._http_options = http_options + self._create_client(api_key, http_options) self._settings = { "max_tokens": params.max_tokens, "temperature": params.temperature, @@ -717,6 +721,9 @@ class GoogleLLMService(LLMService): """ return True + def _create_client(self, api_key: str, http_options: Optional[HttpOptions] = None): + self._client = genai.Client(api_key=api_key, http_options=http_options) + def needs_mcp_alternate_schema(self) -> bool: """Check if this LLM service requires alternate MCP schema. @@ -728,9 +735,6 @@ class GoogleLLMService(LLMService): """ return True - def _create_client(self, api_key: str): - self._client = genai.Client(api_key=api_key) - def _maybe_unset_thinking_budget(self, generation_params: Dict[str, Any]): try: # There's no way to introspect on model capabilities, so From 251ea756c8f3199e2191a30124064af680b3d55e Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Thu, 3 Jul 2025 12:56:24 -0700 Subject: [PATCH 74/84] FishTTSService: deprecate model, add reference_id --- CHANGELOG.md | 12 ++++++--- src/pipecat/services/fish/tts.py | 45 +++++++++++++++++++++----------- 2 files changed, 39 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a7d9cc05b..696dd99fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -61,8 +61,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `session_token` parameter to `AWSNovaSonicLLMService`. -- Added Gemini Multimodal Live File API for uploading, fetching, listing, and -deleting files. See `26f-gemini-multimodal-live-files-api.py` for example usage. +- Added Gemini Multimodal Live File API for uploading, fetching, listing, and + deleting files. See `26f-gemini-multimodal-live-files-api.py` for example usage. ### Changed @@ -75,7 +75,7 @@ deleting files. See `26f-gemini-multimodal-live-files-api.py` for example usage. ### Fixed -- Fixed an issue where audio would get stuck in the queue when an interrupt occurs +- Fixed an issue where audio would get stuck in the queue when an interrupt occurs during Azure TTS synthesis. - Fixed a race condition that occurs in Python 3.10+ where the task could miss @@ -83,6 +83,12 @@ deleting files. See `26f-gemini-multimodal-live-files-api.py` for example usage. - Fixed a `AWSNovaSonicLLMService` issue introduced in 0.0.72. +### Deprecated + +- In `FishTTSService`, deprecated `model` and replaced with `reference_id`. + This change is to better align with Fish Audio's variable naming and to + reduce confusion about what functionality the variable controls. + ## [0.0.73] - 2025-06-26 ### Fixed diff --git a/src/pipecat/services/fish/tts.py b/src/pipecat/services/fish/tts.py index 7f2b85bdb..9d5af657e 100644 --- a/src/pipecat/services/fish/tts.py +++ b/src/pipecat/services/fish/tts.py @@ -71,7 +71,8 @@ class FishAudioTTSService(InterruptibleTTSService): self, *, api_key: str, - model: str, # This is the reference_id + reference_id: Optional[str] = None, # This is the voice ID + model: Optional[str] = None, # Deprecated output_format: FishAudioOutputFormat = "pcm", sample_rate: Optional[int] = None, params: Optional[InputParams] = None, @@ -81,7 +82,13 @@ class FishAudioTTSService(InterruptibleTTSService): Args: api_key: Fish Audio API key for authentication. - model: Reference ID of the voice model to use for synthesis. + reference_id: Reference ID of the voice model to use for synthesis. + model: Deprecated. Reference ID of the voice model to use for synthesis. + + .. deprecated:: 0.0.74 + The `model` parameter is deprecated and will be removed in version 0.1.0. + Use `reference_id` instead to specify the voice model. + output_format: Audio output format. Defaults to "pcm". sample_rate: Audio sample rate. If None, uses default. params: Additional input parameters for voice customization. @@ -96,6 +103,26 @@ class FishAudioTTSService(InterruptibleTTSService): params = params or FishAudioTTSService.InputParams() + # Validation for model and reference_id parameters + if model and reference_id: + raise ValueError( + "Cannot specify both 'model' and 'reference_id'. Use 'reference_id' only." + ) + + if model is None and reference_id is None: + raise ValueError("Must specify 'reference_id' (or deprecated 'model') parameter.") + + if model: + import warnings + + warnings.warn( + "Parameter 'model' is deprecated and will be removed in a future version. " + "Use 'reference_id' instead.", + DeprecationWarning, + stacklevel=2, + ) + reference_id = model + self._api_key = api_key self._base_url = "wss://api.fish.audio/v1/tts/live" self._websocket = None @@ -111,11 +138,9 @@ class FishAudioTTSService(InterruptibleTTSService): "speed": params.prosody_speed, "volume": params.prosody_volume, }, - "reference_id": model, + "reference_id": reference_id, } - self.set_model_name(model) - def can_generate_metrics(self) -> bool: """Check if this service can generate processing metrics. @@ -124,16 +149,6 @@ class FishAudioTTSService(InterruptibleTTSService): """ return True - async def set_model(self, model: str): - """Set the TTS model (reference ID). - - Args: - model: The reference ID of the voice model to use. - """ - self._settings["reference_id"] = model - await super().set_model(model) - logger.info(f"Switching TTS model to: [{model}]") - async def start(self, frame: StartFrame): """Start the Fish Audio TTS service. From ec09505f6bed113a6b64586e68d5884c550c1af3 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Thu, 3 Jul 2025 13:14:15 -0700 Subject: [PATCH 75/84] FishAudioTTSService: Add normalize as InputParam, model_id as arg --- CHANGELOG.md | 9 ++++++--- src/pipecat/services/fish/tts.py | 19 +++++++++++++++++++ 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 696dd99fd..79b9c04f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added `normalize` and `model_id` to `FishAudioTTSService`. + - Added `run_llm` field to `LLMMessagesAppendFrame` and `LLMMessagesUpdateFrame` frames. If true, a context frame will be pushed triggering the LLM to respond. @@ -85,9 +87,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Deprecated -- In `FishTTSService`, deprecated `model` and replaced with `reference_id`. - This change is to better align with Fish Audio's variable naming and to - reduce confusion about what functionality the variable controls. +- In `FishAudioTTSService`, deprecated `model` and replaced with + `reference_id`. This change is to better align with Fish Audio's variable + naming and to reduce confusion about what functionality the variable + controls. ## [0.0.73] - 2025-06-26 diff --git a/src/pipecat/services/fish/tts.py b/src/pipecat/services/fish/tts.py index 9d5af657e..598bac0f3 100644 --- a/src/pipecat/services/fish/tts.py +++ b/src/pipecat/services/fish/tts.py @@ -58,12 +58,14 @@ class FishAudioTTSService(InterruptibleTTSService): Parameters: language: Language for synthesis. Defaults to English. latency: Latency mode ("normal" or "balanced"). Defaults to "normal". + normalize: Whether to normalize audio output. Defaults to True. prosody_speed: Speech speed multiplier (0.5-2.0). Defaults to 1.0. prosody_volume: Volume adjustment in dB. Defaults to 0. """ language: Optional[Language] = Language.EN latency: Optional[str] = "normal" # "normal" or "balanced" + normalize: Optional[bool] = True prosody_speed: Optional[float] = 1.0 # Speech speed (0.5-2.0) prosody_volume: Optional[int] = 0 # Volume adjustment in dB @@ -73,6 +75,7 @@ class FishAudioTTSService(InterruptibleTTSService): api_key: str, reference_id: Optional[str] = None, # This is the voice ID model: Optional[str] = None, # Deprecated + model_id: str = "speech-1.5", output_format: FishAudioOutputFormat = "pcm", sample_rate: Optional[int] = None, params: Optional[InputParams] = None, @@ -89,6 +92,7 @@ class FishAudioTTSService(InterruptibleTTSService): The `model` parameter is deprecated and will be removed in version 0.1.0. Use `reference_id` instead to specify the voice model. + model_id: Specify which Fish Audio TTS model to use (e.g. "speech-1.5") output_format: Audio output format. Defaults to "pcm". sample_rate: Audio sample rate. If None, uses default. params: Additional input parameters for voice customization. @@ -134,6 +138,7 @@ class FishAudioTTSService(InterruptibleTTSService): "sample_rate": 0, "latency": params.latency, "format": output_format, + "normalize": params.normalize, "prosody": { "speed": params.prosody_speed, "volume": params.prosody_volume, @@ -141,6 +146,8 @@ class FishAudioTTSService(InterruptibleTTSService): "reference_id": reference_id, } + self.set_model_name(model_id) + def can_generate_metrics(self) -> bool: """Check if this service can generate processing metrics. @@ -149,6 +156,17 @@ class FishAudioTTSService(InterruptibleTTSService): """ return True + async def set_model(self, model: str): + """Set the TTS model and reconnect. + + Args: + model: The model name to use for synthesis. + """ + await super().set_model(model) + logger.info(f"Switching TTS model to: [{model}]") + await self._disconnect() + await self._connect() + async def start(self, frame: StartFrame): """Start the Fish Audio TTS service. @@ -197,6 +215,7 @@ class FishAudioTTSService(InterruptibleTTSService): logger.debug("Connecting to Fish Audio") headers = {"Authorization": f"Bearer {self._api_key}"} + headers["model"] = self.model_name self._websocket = await websockets.connect(self._base_url, extra_headers=headers) # Send initial start message with ormsgpack From 096067b0973008fd45cf6c7af4dd4be92be8c8a1 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Thu, 3 Jul 2025 13:23:13 -0700 Subject: [PATCH 76/84] GoogleLLMService: Linting fixes --- src/pipecat/services/google/llm.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pipecat/services/google/llm.py b/src/pipecat/services/google/llm.py index f7589beaf..f0e74d2ce 100644 --- a/src/pipecat/services/google/llm.py +++ b/src/pipecat/services/google/llm.py @@ -67,8 +67,8 @@ try: Content, FunctionCall, FunctionResponse, - HttpOptions, GenerateContentConfig, + HttpOptions, Part, ) except ModuleNotFoundError as e: @@ -723,7 +723,7 @@ class GoogleLLMService(LLMService): def _create_client(self, api_key: str, http_options: Optional[HttpOptions] = None): self._client = genai.Client(api_key=api_key, http_options=http_options) - + def needs_mcp_alternate_schema(self) -> bool: """Check if this LLM service requires alternate MCP schema. From 7596d71460d7c0a4f76159ceba9b7cfd8bccb65e Mon Sep 17 00:00:00 2001 From: Sam Sykes Date: Thu, 3 Jul 2025 21:25:13 +0100 Subject: [PATCH 77/84] Speechmatics STT + multi-speaker conversations (#2036) * initial config * skeleton * Added a README (to be added to). * Payloads coming from the ASR. * doc update * handle the partials and finals * enable diarization in the example * support sending messages to pipecat pipeline * requirements fix in README * updated example (with amusement) * updated example to match master * updated docs * support for diarization tags * logic fix for wrapper * Use an internal SpeechFrame for speaker_id (not user_id). * only include speaker tags on finalised transcript (as this may skew end of utterance detection) * updated docs * correction to docs and updated example * updated requirement * Fix for using default EU server. * Updates from PR comments. * Refactor based on comments in the original PR. Primary focus on documentation, naming conventions and how `user_id` is used. * Check for SMX installed when importing. * Variable name change * Comment correction. * Support for Esporanto and Uyghur * Impoved language support * function name change * Locale fix * intercept * interim changes * pass the pipeline task to the module for adding events to the top of the pipeline * logging for the pipeline * Reduce timeout for content aggregator. * staged update * testing with Azure * Updated context (Azure was dropping punctuation) and using better ElevenLabs model. * Updated to RT 0.3.0 and use OpenAI (not Azure). * Missing OpenAI import; parameter name change for output locale validation. * Revert to `0.2.0` of RT SDK. * fix for assignment of `output_locale_code`. * update Speechmatics library to 0.3.1 * new transcription example * updated asyncio task handling * Updated doc strings * enable OpenTelemetry logging * removed import from stt for __init__ * updated examples and default values * updated examples * prevent lock up when closing the STT connection --- README.md | 26 +- docs/api/requirements.txt | 1 + dot-env.template | 4 + .../07a-interruptible-speechmatics.py | 153 ++++ .../13h-speechmatics-transcription.py | 89 ++ pyproject.toml | 1 + src/pipecat/services/speechmatics/__init__.py | 5 + src/pipecat/services/speechmatics/stt.py | 813 ++++++++++++++++++ src/pipecat/transcriptions/language.py | 6 + 9 files changed, 1085 insertions(+), 13 deletions(-) create mode 100644 examples/foundational/07a-interruptible-speechmatics.py create mode 100644 examples/foundational/13h-speechmatics-transcription.py create mode 100644 src/pipecat/services/speechmatics/__init__.py create mode 100644 src/pipecat/services/speechmatics/stt.py diff --git a/README.md b/README.md index 2d14f37c9..45f6611a7 100644 --- a/README.md +++ b/README.md @@ -51,19 +51,19 @@ You can connect to Pipecat from any platform using our official SDKs: ## 🧩 Available services -| Category | Services | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Speech-to-Text | [AssemblyAI](https://docs.pipecat.ai/server/services/stt/assemblyai), [AWS](https://docs.pipecat.ai/server/services/stt/aws), [Azure](https://docs.pipecat.ai/server/services/stt/azure), [Cartesia](https://docs.pipecat.ai/server/services/stt/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/stt/deepgram), [Fal Wizper](https://docs.pipecat.ai/server/services/stt/fal), [Gladia](https://docs.pipecat.ai/server/services/stt/gladia), [Google](https://docs.pipecat.ai/server/services/stt/google), [Groq (Whisper)](https://docs.pipecat.ai/server/services/stt/groq), [OpenAI (Whisper)](https://docs.pipecat.ai/server/services/stt/openai), [Parakeet (NVIDIA)](https://docs.pipecat.ai/server/services/stt/parakeet), [SambaNova (Whisper)](https://docs.pipecat.ai/server/services/stt/sambanova) [Ultravox](https://docs.pipecat.ai/server/services/stt/ultravox), [Whisper](https://docs.pipecat.ai/server/services/stt/whisper) | -| LLMs | [Anthropic](https://docs.pipecat.ai/server/services/llm/anthropic), [AWS](https://docs.pipecat.ai/server/services/llm/aws), [Azure](https://docs.pipecat.ai/server/services/llm/azure), [Cerebras](https://docs.pipecat.ai/server/services/llm/cerebras), [DeepSeek](https://docs.pipecat.ai/server/services/llm/deepseek), [Fireworks AI](https://docs.pipecat.ai/server/services/llm/fireworks), [Gemini](https://docs.pipecat.ai/server/services/llm/gemini), [Grok](https://docs.pipecat.ai/server/services/llm/grok), [Groq](https://docs.pipecat.ai/server/services/llm/groq), [NVIDIA NIM](https://docs.pipecat.ai/server/services/llm/nim), [Ollama](https://docs.pipecat.ai/server/services/llm/ollama), [OpenAI](https://docs.pipecat.ai/server/services/llm/openai), [OpenRouter](https://docs.pipecat.ai/server/services/llm/openrouter), [Perplexity](https://docs.pipecat.ai/server/services/llm/perplexity), [Qwen](https://docs.pipecat.ai/server/services/llm/qwen), [SambaNova](https://docs.pipecat.ai/server/services/llm/sambanova) [Together AI](https://docs.pipecat.ai/server/services/llm/together) | -| Text-to-Speech | [AWS](https://docs.pipecat.ai/server/services/tts/aws), [Azure](https://docs.pipecat.ai/server/services/tts/azure), [Cartesia](https://docs.pipecat.ai/server/services/tts/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/tts/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/tts/elevenlabs), [FastPitch (NVIDIA)](https://docs.pipecat.ai/server/services/tts/fastpitch), [Fish](https://docs.pipecat.ai/server/services/tts/fish), [Google](https://docs.pipecat.ai/server/services/tts/google), [LMNT](https://docs.pipecat.ai/server/services/tts/lmnt), [MiniMax](https://docs.pipecat.ai/server/services/tts/minimax), [Neuphonic](https://docs.pipecat.ai/server/services/tts/neuphonic), [OpenAI](https://docs.pipecat.ai/server/services/tts/openai), [Piper](https://docs.pipecat.ai/server/services/tts/piper), [PlayHT](https://docs.pipecat.ai/server/services/tts/playht), [Rime](https://docs.pipecat.ai/server/services/tts/rime), [Sarvam](https://docs.pipecat.ai/server/services/tts/sarvam), [XTTS](https://docs.pipecat.ai/server/services/tts/xtts) | -| Speech-to-Speech | [AWS Nova Sonic](https://docs.pipecat.ai/server/services/s2s/aws), [Gemini Multimodal Live](https://docs.pipecat.ai/server/services/s2s/gemini), [OpenAI Realtime](https://docs.pipecat.ai/server/services/s2s/openai) | -| Transport | [Daily (WebRTC)](https://docs.pipecat.ai/server/services/transport/daily), [FastAPI Websocket](https://docs.pipecat.ai/server/services/transport/fastapi-websocket), [SmallWebRTCTransport](https://docs.pipecat.ai/server/services/transport/small-webrtc), [WebSocket Server](https://docs.pipecat.ai/server/services/transport/websocket-server), Local | -| Serializers | [Plivo](https://docs.pipecat.ai/server/utilities/serializers/plivo), [Twilio](https://docs.pipecat.ai/server/utilities/serializers/twilio), [Telnyx](https://docs.pipecat.ai/server/utilities/serializers/telnyx) | -| Video | [Tavus](https://docs.pipecat.ai/server/services/video/tavus), [Simli](https://docs.pipecat.ai/server/services/video/simli) | -| Memory | [mem0](https://docs.pipecat.ai/server/services/memory/mem0) | -| Vision & Image | [fal](https://docs.pipecat.ai/server/services/image-generation/fal), [Google Imagen](https://docs.pipecat.ai/server/services/image-generation/fal), [Moondream](https://docs.pipecat.ai/server/services/vision/moondream) | -| Audio Processing | [Silero VAD](https://docs.pipecat.ai/server/utilities/audio/silero-vad-analyzer), [Krisp](https://docs.pipecat.ai/server/utilities/audio/krisp-filter), [Koala](https://docs.pipecat.ai/server/utilities/audio/koala-filter), [Noisereduce](https://docs.pipecat.ai/server/utilities/audio/noisereduce-filter) | -| Analytics & Metrics | [OpenTelemetry](https://docs.pipecat.ai/server/utilities/opentelemetry), [Sentry](https://docs.pipecat.ai/server/services/analytics/sentry) | +| Category | Services | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Speech-to-Text | [AssemblyAI](https://docs.pipecat.ai/server/services/stt/assemblyai), [AWS](https://docs.pipecat.ai/server/services/stt/aws), [Azure](https://docs.pipecat.ai/server/services/stt/azure), [Cartesia](https://docs.pipecat.ai/server/services/stt/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/stt/deepgram), [Fal Wizper](https://docs.pipecat.ai/server/services/stt/fal), [Gladia](https://docs.pipecat.ai/server/services/stt/gladia), [Google](https://docs.pipecat.ai/server/services/stt/google), [Groq (Whisper)](https://docs.pipecat.ai/server/services/stt/groq), [OpenAI (Whisper)](https://docs.pipecat.ai/server/services/stt/openai), [Parakeet (NVIDIA)](https://docs.pipecat.ai/server/services/stt/parakeet), [SambaNova (Whisper)](https://docs.pipecat.ai/server/services/stt/sambanova), [Speechmatics](https://docs.pipecat.ai/server/services/stt/speechmatics), [Ultravox](https://docs.pipecat.ai/server/services/stt/ultravox), [Whisper](https://docs.pipecat.ai/server/services/stt/whisper) | +| LLMs | [Anthropic](https://docs.pipecat.ai/server/services/llm/anthropic), [AWS](https://docs.pipecat.ai/server/services/llm/aws), [Azure](https://docs.pipecat.ai/server/services/llm/azure), [Cerebras](https://docs.pipecat.ai/server/services/llm/cerebras), [DeepSeek](https://docs.pipecat.ai/server/services/llm/deepseek), [Fireworks AI](https://docs.pipecat.ai/server/services/llm/fireworks), [Gemini](https://docs.pipecat.ai/server/services/llm/gemini), [Grok](https://docs.pipecat.ai/server/services/llm/grok), [Groq](https://docs.pipecat.ai/server/services/llm/groq), [NVIDIA NIM](https://docs.pipecat.ai/server/services/llm/nim), [Ollama](https://docs.pipecat.ai/server/services/llm/ollama), [OpenAI](https://docs.pipecat.ai/server/services/llm/openai), [OpenRouter](https://docs.pipecat.ai/server/services/llm/openrouter), [Perplexity](https://docs.pipecat.ai/server/services/llm/perplexity), [Qwen](https://docs.pipecat.ai/server/services/llm/qwen), [SambaNova](https://docs.pipecat.ai/server/services/llm/sambanova) [Together AI](https://docs.pipecat.ai/server/services/llm/together) | +| Text-to-Speech | [AWS](https://docs.pipecat.ai/server/services/tts/aws), [Azure](https://docs.pipecat.ai/server/services/tts/azure), [Cartesia](https://docs.pipecat.ai/server/services/tts/cartesia), [Deepgram](https://docs.pipecat.ai/server/services/tts/deepgram), [ElevenLabs](https://docs.pipecat.ai/server/services/tts/elevenlabs), [FastPitch (NVIDIA)](https://docs.pipecat.ai/server/services/tts/fastpitch), [Fish](https://docs.pipecat.ai/server/services/tts/fish), [Google](https://docs.pipecat.ai/server/services/tts/google), [LMNT](https://docs.pipecat.ai/server/services/tts/lmnt), [MiniMax](https://docs.pipecat.ai/server/services/tts/minimax), [Neuphonic](https://docs.pipecat.ai/server/services/tts/neuphonic), [OpenAI](https://docs.pipecat.ai/server/services/tts/openai), [Piper](https://docs.pipecat.ai/server/services/tts/piper), [PlayHT](https://docs.pipecat.ai/server/services/tts/playht), [Rime](https://docs.pipecat.ai/server/services/tts/rime), [Sarvam](https://docs.pipecat.ai/server/services/tts/sarvam), [XTTS](https://docs.pipecat.ai/server/services/tts/xtts) | +| Speech-to-Speech | [AWS Nova Sonic](https://docs.pipecat.ai/server/services/s2s/aws), [Gemini Multimodal Live](https://docs.pipecat.ai/server/services/s2s/gemini), [OpenAI Realtime](https://docs.pipecat.ai/server/services/s2s/openai) | +| Transport | [Daily (WebRTC)](https://docs.pipecat.ai/server/services/transport/daily), [FastAPI Websocket](https://docs.pipecat.ai/server/services/transport/fastapi-websocket), [SmallWebRTCTransport](https://docs.pipecat.ai/server/services/transport/small-webrtc), [WebSocket Server](https://docs.pipecat.ai/server/services/transport/websocket-server), Local | +| Serializers | [Plivo](https://docs.pipecat.ai/server/utilities/serializers/plivo), [Twilio](https://docs.pipecat.ai/server/utilities/serializers/twilio), [Telnyx](https://docs.pipecat.ai/server/utilities/serializers/telnyx) | +| Video | [Tavus](https://docs.pipecat.ai/server/services/video/tavus), [Simli](https://docs.pipecat.ai/server/services/video/simli) | +| Memory | [mem0](https://docs.pipecat.ai/server/services/memory/mem0) | +| Vision & Image | [fal](https://docs.pipecat.ai/server/services/image-generation/fal), [Google Imagen](https://docs.pipecat.ai/server/services/image-generation/fal), [Moondream](https://docs.pipecat.ai/server/services/vision/moondream) | +| Audio Processing | [Silero VAD](https://docs.pipecat.ai/server/utilities/audio/silero-vad-analyzer), [Krisp](https://docs.pipecat.ai/server/utilities/audio/krisp-filter), [Koala](https://docs.pipecat.ai/server/utilities/audio/koala-filter), [Noisereduce](https://docs.pipecat.ai/server/utilities/audio/noisereduce-filter) | +| Analytics & Metrics | [OpenTelemetry](https://docs.pipecat.ai/server/utilities/opentelemetry), [Sentry](https://docs.pipecat.ai/server/services/analytics/sentry) | 📚 [View full services documentation →](https://docs.pipecat.ai/server/services/supported-services) diff --git a/docs/api/requirements.txt b/docs/api/requirements.txt index d783b33e8..c9e8e2ce9 100644 --- a/docs/api/requirements.txt +++ b/docs/api/requirements.txt @@ -46,6 +46,7 @@ pipecat-ai[sambanova] pipecat-ai[silero] pipecat-ai[simli] pipecat-ai[soundfile] +pipecat-ai[speechmatics] pipecat-ai[tavus] pipecat-ai[together] # pipecat-ai[ultravox] # Mocked diff --git a/dot-env.template b/dot-env.template index f4fd43eea..ab085757f 100644 --- a/dot-env.template +++ b/dot-env.template @@ -109,6 +109,10 @@ MINIMAX_GROUP_ID=... # Sarvam AI SARVAM_API_KEY=... +# Speechmatics +SPEECHMATICS_API_KEY=... + + # SambaNova SAMBANOVA_API_KEY=... diff --git a/examples/foundational/07a-interruptible-speechmatics.py b/examples/foundational/07a-interruptible-speechmatics.py new file mode 100644 index 000000000..1582e79ba --- /dev/null +++ b/examples/foundational/07a-interruptible-speechmatics.py @@ -0,0 +1,153 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +import argparse +import os + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.audio.vad.silero import SileroVADAnalyzer +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineParams, PipelineTask +from pipecat.processors.aggregators.llm_response import ( + LLMUserAggregatorParams, +) +from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext +from pipecat.services.elevenlabs.tts import ElevenLabsTTSService +from pipecat.services.openai.base_llm import BaseOpenAILLMService +from pipecat.services.openai.llm import OpenAILLMService +from pipecat.services.speechmatics.stt import SpeechmaticsSTTService +from pipecat.transcriptions.language import Language +from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams +from pipecat.transports.services.daily import DailyParams + +load_dotenv(override=True) + +# We store functions so objects (e.g. SileroVADAnalyzer) don't get +# instantiated. The function will be called when the desired transport gets +# selected. +transport_params = { + "daily": lambda: DailyParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), + "twilio": lambda: FastAPIWebsocketParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), + "webrtc": lambda: TransportParams( + audio_in_enabled=True, + audio_out_enabled=True, + vad_analyzer=SileroVADAnalyzer(), + ), +} + + +async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): + """Run example using Speechmatics STT. + + This example will use diarization within our STT service and output the words spoken by + each individual speaker and wrap them with XML tags for the LLM to process. Note the + instructions in the system context for the LLM. This greatly improves the conversation + experience by allowing the LLM to understand who is speaking in a multi-party call. + + If you do not wish to use diarization, then set the `enable_speaker_diarization` parameter + to `False` or omit it altogether. The `text_format` will only be used if diarization is enabled. + + By default, this example will use our ENHANCED operating point, which is optimized for + high accuracy. You can change this by setting the `operating_point` parameter to a different + value. + + For more information on operating points, see the Speechmatics documentation: + https://docs.speechmatics.com/rt-api-ref + """ + logger.info(f"Starting bot") + + stt = SpeechmaticsSTTService( + api_key=os.getenv("SPEECHMATICS_API_KEY"), + language=Language.EN, + enable_speaker_diarization=True, + text_format="<{speaker_id}>{text}", + ) + + tts = ElevenLabsTTSService( + api_key=os.getenv("ELEVENLABS_API_KEY", ""), + voice_id=os.getenv("ELEVENLABS_VOICE_ID", ""), + model="eleven_turbo_v2_5", + ) + + llm = OpenAILLMService( + api_key=os.getenv("OPENAI_API_KEY"), + params=BaseOpenAILLMService.InputParams(temperature=0.75), + ) + + messages = [ + { + "role": "system", + "content": ( + "You are a helpful British assistant called Alfred. " + "Your goal is to demonstrate your capabilities in a succinct way. " + "Your output will be converted to audio so don't include special characters in your answers. " + "Always include punctuation in your responses. " + "Give very short replies - do not give longer replies unless strictly necessary. " + "Respond to what the user said in a concise, funny, creative and helpful way. " + "Use `` tags to identify different speakers - do not use tags in your replies." + ), + }, + ] + + context = OpenAILLMContext(messages) + context_aggregator = llm.create_context_aggregator( + context, + user_params=LLMUserAggregatorParams(aggregation_timeout=0.005), + ) + + pipeline = Pipeline( + [ + transport.input(), # Transport user input + stt, # STT + context_aggregator.user(), # User responses + llm, # LLM + tts, # TTS + transport.output(), # Transport bot output + context_aggregator.assistant(), # Assistant spoken responses + ] + ) + + task = PipelineTask( + pipeline, + params=PipelineParams( + enable_metrics=True, + enable_usage_metrics=True, + ), + ) + + @transport.event_handler("on_client_connected") + async def on_client_connected(transport, client): + logger.info(f"Client connected") + # Kick off the conversation. + messages.append({"role": "system", "content": "Say a short hello to the user."}) + await task.queue_frames([context_aggregator.user().get_context_frame()]) + + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + await task.cancel() + + runner = PipelineRunner(handle_sigint=handle_sigint) + + await runner.run(task) + + +if __name__ == "__main__": + from pipecat.examples.run import main + + main(run_example, transport_params=transport_params) diff --git a/examples/foundational/13h-speechmatics-transcription.py b/examples/foundational/13h-speechmatics-transcription.py new file mode 100644 index 000000000..ec3197e19 --- /dev/null +++ b/examples/foundational/13h-speechmatics-transcription.py @@ -0,0 +1,89 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +import argparse +import os + +from dotenv import load_dotenv +from loguru import logger + +from pipecat.frames.frames import Frame, TranscriptionFrame +from pipecat.pipeline.pipeline import Pipeline +from pipecat.pipeline.runner import PipelineRunner +from pipecat.pipeline.task import PipelineTask +from pipecat.processors.frame_processor import FrameDirection, FrameProcessor +from pipecat.services.speechmatics.stt import SpeechmaticsSTTService +from pipecat.transcriptions.language import Language +from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams +from pipecat.transports.services.daily import DailyParams + +load_dotenv(override=True) + + +class TranscriptionLogger(FrameProcessor): + async def process_frame(self, frame: Frame, direction: FrameDirection): + await super().process_frame(frame, direction) + + if isinstance(frame, TranscriptionFrame): + print(f"Transcription: {frame.text}") + + +# We store functions so objects (e.g. SileroVADAnalyzer) don't get +# instantiated. The function will be called when the desired transport gets +# selected. +transport_params = { + "daily": lambda: DailyParams(audio_in_enabled=True), + "twilio": lambda: FastAPIWebsocketParams(audio_in_enabled=True), + "webrtc": lambda: TransportParams(audio_in_enabled=True), +} + + +async def run_example(transport: BaseTransport, _: argparse.Namespace, handle_sigint: bool): + """Run example using Speechmatics STT. + + This example will use diarization within our STT service and output the words spoken by + each individual speaker and wrap them with XML tags. + + If you do not wish to use diarization, then set the `enable_speaker_diarization` parameter + to `False` or omit it altogether. The `text_format` will only be used if diarization is enabled. + + By default, this example will use our ENHANCED operating point, which is optimized for + high accuracy. You can change this by setting the `operating_point` parameter to a different + value. + + For more information on operating points, see the Speechmatics documentation: + https://docs.speechmatics.com/rt-api-ref + """ + logger.info(f"Starting bot") + + stt = SpeechmaticsSTTService( + api_key=os.getenv("SPEECHMATICS_API_KEY"), + language=Language.EN, + enable_speaker_diarization=True, + text_format="<{speaker_id}>{text}", + ) + + tl = TranscriptionLogger() + + pipeline = Pipeline([transport.input(), stt, tl]) + + task = PipelineTask(pipeline) + + @transport.event_handler("on_client_disconnected") + async def on_client_disconnected(transport, client): + logger.info(f"Client disconnected") + await task.cancel() + + runner = PipelineRunner(handle_sigint=handle_sigint) + + await runner.run(task) + + +if __name__ == "__main__": + from pipecat.examples.run import main + + main(run_example, transport_params=transport_params) diff --git a/pyproject.toml b/pyproject.toml index 42b06060d..2a0fd2175 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -87,6 +87,7 @@ remote-smart-turn = [] silero = [ "onnxruntime~=1.20.1" ] simli = [ "simli-ai~=0.1.10"] soundfile = [ "soundfile~=0.13.0" ] +speechmatics = [ "speechmatics-rt>=0.3.1" ] tavus=[] together = [] tracing = [ "opentelemetry-sdk>=1.33.0", "opentelemetry-api>=1.33.0", "opentelemetry-instrumentation>=0.54b0" ] diff --git a/src/pipecat/services/speechmatics/__init__.py b/src/pipecat/services/speechmatics/__init__.py new file mode 100644 index 000000000..d23112945 --- /dev/null +++ b/src/pipecat/services/speechmatics/__init__.py @@ -0,0 +1,5 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# diff --git a/src/pipecat/services/speechmatics/stt.py b/src/pipecat/services/speechmatics/stt.py new file mode 100644 index 000000000..5cba8d931 --- /dev/null +++ b/src/pipecat/services/speechmatics/stt.py @@ -0,0 +1,813 @@ +# +# Copyright (c) 2024–2025, Daily +# +# SPDX-License-Identifier: BSD 2-Clause License +# + +"""Speechmatics STT service integration.""" + +import asyncio +import datetime +import re +from dataclasses import dataclass, field +from typing import Any, AsyncGenerator, Optional +from urllib.parse import urlencode + +from loguru import logger + +from pipecat.frames.frames import ( + CancelFrame, + EndFrame, + Frame, + InterimTranscriptionFrame, + StartFrame, + TranscriptionFrame, +) +from pipecat.services.stt_service import STTService +from pipecat.transcriptions.language import Language +from pipecat.utils.tracing.service_decorators import traced_stt + +try: + from speechmatics.rt import ( + AsyncClient, + AudioEncoding, + AudioFormat, + ConversationConfig, + OperatingPoint, + ServerMessageType, + SpeakerDiarizationConfig, + TranscriptionConfig, + __version__, + ) +except ModuleNotFoundError as e: + logger.error(f"Exception: {e}") + logger.error( + "In order to use Speechmatics, you need to `pip install pipecat-ai[speechmatics]`." + ) + raise Exception(f"Missing module: {e}") + + +class AudioBuffer: + """Audio buffer for STT clients. + + The Python SDK expects audio in a pre-defined number of frames. This + buffer will accumulate the data from the pipeline and provide it to the + STT client in the correct lengths, waiting for the number of frames to + be available. + """ + + def __init__(self, maxsize: int = 0): + """Initialize the audio buffer. + + Args: + maxsize: Maximum size of the buffer. + """ + self._queue = asyncio.Queue(maxsize=maxsize) + self._current_chunk = b"" + self._position = 0 + self._closed = False + + def write_audio(self, data: bytes) -> None: + """Write audio data to the buffer (thread-safe). + + Args: + data: Audio data to write. + """ + if data: + try: + self._queue.put_nowait(data) + except asyncio.QueueFull: + pass + + async def read(self, size: int) -> bytes: + """Read exactly `size` bytes from the buffer (thread-safe). + + This process will block until the required number of bytes are available + in the buffer. Audio is received from the pipeline in varying sizes, so + this buffer will accumulate the data and provide it to the STT client in + the correct lengths, waiting for the number of frames to be available. + + Calling stop() will close the buffer and release the blocking read + process. + + Args: + size: Number of bytes to read. + + Returns: + bytes: Audio data read from the buffer. + """ + result = b"" + bytes_needed = size + + while bytes_needed > 0 and not self._closed: + # Use data from current chunk if available + if self._position < len(self._current_chunk): + available = len(self._current_chunk) - self._position + take = min(bytes_needed, available) + result += self._current_chunk[self._position : self._position + take] + self._position += take + bytes_needed -= take + continue + + # Get next chunk + try: + chunk = await asyncio.wait_for(self._queue.get(), timeout=0.1) + if chunk is None: + continue + self._current_chunk = chunk + self._position = 0 + except asyncio.TimeoutError: + await asyncio.sleep(0) + continue + + return result + + def stop(self) -> None: + """Close the audio buffer.""" + self._closed = True + + +@dataclass +class SpeechFragment: + """Fragment of an utterance. + + Parameters: + start_time: Start time of the fragment in seconds (from session start). + end_time: End time of the fragment in seconds (from session start). + language: Language of the fragment. Defaults to `Language.EN`. + is_eos: Whether the fragment is the end of a sentence. Defaults to `False`. + is_final: Whether the fragment is the final fragment. Defaults to `False`. + attaches_to: Whether the fragment attaches to the previous or next fragment (punctuation). Defaults to empty string. + content: Content of the fragment. Defaults to empty string. + speaker: Speaker of the fragment (if diarization is enabled). Defaults to `None`. + confidence: Confidence of the fragment (0.0 to 1.0). Defaults to `1.0`. + result: Raw result of the fragment from the TTS. + """ + + start_time: float + end_time: float + language: Language = Language.EN + is_eos: bool = False + is_final: bool = False + attaches_to: str = "" + content: str = "" + speaker: Optional[str] = None + confidence: float = 1.0 + result: Optional[Any] = None + + +@dataclass +class SpeakerFragments: + """SpeechFragment items grouped by speaker_id. + + Parameters: + speaker_id: The ID of the speaker. + timestamp: The timestamp of the frame. + language: The language of the frame. + fragments: The list of SpeechFragment items. + """ + + speaker_id: Optional[str] = None + timestamp: Optional[str] = None + language: Optional[Language] = None + fragments: list[SpeechFragment] = field(default_factory=list) + + def __str__(self): + """Return a string representation of the object.""" + return f"SpeakerFragments(speaker_id: {self.speaker_id}, timestamp: {self.timestamp}, language: {self.language}, text: {self._format_text()})" + + def _format_text(self, format: Optional[str] = None) -> str: + """Wrap text with speaker ID in an optional f-string format. + + Args: + format: Format to wrap the text with. + + Returns: + str: The wrapped text. + """ + # Cumulative contents + content = "" + + # Assemble the text + for frag in self.fragments: + if content == "" or frag.attaches_to == "previous": + content += frag.content + else: + content += " " + frag.content + + # Format the text, if format is provided + if format is None or self.speaker_id is None: + return content + return format.format(**{"speaker_id": self.speaker_id, "text": content}) + + def _as_frame_attributes(self, format: Optional[str] = None) -> dict[str, Any]: + """Return a dictionary of attributes for a TranscriptionFrame. + + Args: + format: Format to wrap the text with. + + Returns: + dict[str, Any]: The dictionary of attributes. + """ + return { + "text": self._format_text(format), + "user_id": self.speaker_id, + "timestamp": self.timestamp, + "language": self.language, + "result": [frag.result for frag in self.fragments], + } + + +class SpeechmaticsSTTService(STTService): + """Speechmatics STT service implementation. + + This service provides real-time speech-to-text transcription using the Speechmatics API. + It supports partial and final transcriptions, multiple languages, various audio formats, + and speaker diarization. + """ + + def __init__( + self, + *, + api_key: str, + language: Optional[Language] = None, + language_code: Optional[str] = None, + base_url: str = "wss://eu2.rt.speechmatics.com/v2", + domain: Optional[str] = None, + output_locale: Optional[Language] = None, + output_locale_code: Optional[str] = None, + enable_partials: bool = True, + max_delay: float = 1.5, + sample_rate: Optional[int] = 16000, + chunk_size: int = 256, + audio_encoding: AudioEncoding = AudioEncoding.PCM_S16LE, + end_of_utterance_silence_trigger: float = 0.5, + operating_point: OperatingPoint = OperatingPoint.ENHANCED, + enable_speaker_diarization: bool = False, + text_format: str = "<{speaker_id}>{text}", + max_speakers: Optional[int] = None, + transcription_config: Optional[TranscriptionConfig] = None, + **kwargs, + ): + """Initialize the Speechmatics STT service. + + Args: + api_key: Speechmatics API key for authentication. + language: Language code for transcription. Defaults to `None`. + language_code: Language code string for transcription. Defaults to `None`. + base_url: Base URL for Speechmatics API. Defaults to `wss://eu2.rt.speechmatics.com/v2`. + domain: Domain for Speechmatics API. Defaults to `None`. + output_locale: Output locale for transcription, e.g. `Language.EN_GB`. Defaults to `None`. + output_locale_code: Output locale code for transcription. Defaults to `None`. + enable_partials: Enable partial transcription results. Defaults to `True`. + max_delay: Maximum delay for transcription in seconds. Defaults to `1.5`. + sample_rate: Audio sample rate in Hz. Defaults to `16000`. + chunk_size: Audio chunk size for streaming. Defaults to `256`. + audio_encoding: Audio encoding format. Defaults to `pcm_s16le`. + end_of_utterance_silence_trigger: Silence duration in seconds to trigger end of utterance detection. Defaults to `0.5`. + operating_point: Operating point for transcription accuracy vs. latency tradeoff. Defaults to `enhanced`. + enable_speaker_diarization: Enable speaker diarization to identify different speakers. Defaults to `False`. + text_format: Wrapper for speaker ID. Defaults to `<{speaker_id}>{text}`. + max_speakers: Maximum number of speakers to detect. Defaults to `None` (auto-detect). + transcription_config: Custom transcription configuration (other set parameters are merged). Defaults to `None`. + **kwargs: Additional arguments passed to STTService. + """ + super().__init__(sample_rate=sample_rate, **kwargs) + + # Client configuration + self._api_key: str = api_key + self._language: Optional[Language] = language + self._language_code: Optional[str] = language_code + self._base_url: str = base_url + self._domain: Optional[str] = domain + self._output_locale: Optional[Language] = output_locale + self._output_locale_code: Optional[str] = output_locale_code + self._enable_partials: bool = enable_partials + self._max_delay: float = max_delay + self._sample_rate: int = sample_rate + self._chunk_size: int = chunk_size + self._audio_encoding: AudioEncoding = audio_encoding + self._end_of_utterance_silence_trigger: Optional[float] = end_of_utterance_silence_trigger + self._operating_point: OperatingPoint = operating_point + self._enable_speaker_diarization: bool = enable_speaker_diarization + self._text_format: str = text_format + self._max_speakers: Optional[int] = max_speakers + + # Check we have required attributes + if not self._api_key: + raise ValueError("Missing Speechmatics API key") + if not self._base_url: + raise ValueError("Missing Speechmatics base URL") + + # Validate the language code + if self._language and self._language_code: + raise ValueError("Language and language code cannot both be specified") + elif self._language: + self._language_code = _language_to_speechmatics_language(self._language) + + # Validate the output locale code + if self._output_locale and self._output_locale_code: + raise ValueError("Output locale and output locale code cannot both be specified") + elif self._output_locale: + self._output_locale_code = _locale_to_speechmatics_locale( + self._language_code, self._output_locale + ) + + # Complete configuration objects + self._transcription_config: TranscriptionConfig = None + self._process_config(transcription_config) + + # STT client + self._client: Optional[AsyncClient] = None + self._client_task: Optional[asyncio.Task] = None + self._audio_buffer: AudioBuffer = AudioBuffer(maxsize=10) + self._start_time: Optional[datetime.datetime] = None + + # Current utterance speech data + self._speech_fragments: list[SpeechFragment] = [] + + async def start(self, frame: StartFrame): + """Called when the new session starts.""" + await super().start(frame) + await self._connect() + + async def stop(self, frame: EndFrame): + """Called when the session ends.""" + await super().stop(frame) + await self._disconnect() + + async def cancel(self, frame: CancelFrame): + """Called when the session is cancelled.""" + await super().cancel(frame) + await self._disconnect() + + async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]: + """Adds audio to the audio buffer and yields None.""" + self._audio_buffer.write_audio(audio) + yield None + + async def _run_client(self) -> None: + """Runs the Speechmatics client in a thread.""" + await self._client.transcribe( + self._audio_buffer, + transcription_config=self._transcription_config, + audio_format=AudioFormat( + encoding=self._audio_encoding, + sample_rate=self.sample_rate, + chunk_size=self._chunk_size, + ), + ) + + async def _connect(self) -> None: + """Connect to the STT service.""" + # Create new STT RT client + self._client = AsyncClient( + api_key=self._api_key, + url=_get_endpoint_url(self._base_url), + ) + + # Log the event + logger.debug("Connected to Speechmatics STT service") + + # Recognition started event + @self._client.on(ServerMessageType.RECOGNITION_STARTED) + def _evt_on_recognition_started(message: dict[str, Any]): + logger.debug(f"Recognition started (session: {message.get('id')})") + self._start_time = datetime.datetime.now(datetime.timezone.utc) + + # Partial transcript event + @self._client.on(ServerMessageType.ADD_PARTIAL_TRANSCRIPT) + def _evt_on_partial_transcript(message: dict[str, Any]): + self._handle_transcript(message, is_final=False) + + # Final transcript event + @self._client.on(ServerMessageType.ADD_TRANSCRIPT) + def _evt_on_final_transcript(message: dict[str, Any]): + self._handle_transcript(message, is_final=True) + + # End of Utterance + @self._client.on(ServerMessageType.END_OF_UTTERANCE) + def _evt_on_end_of_utterance(message: dict[str, Any]): + logger.debug("End of utterance received from STT") + asyncio.run_coroutine_threadsafe( + self._send_frames(finalized=True), self.get_event_loop() + ) + + # Start the client in a thread + self._client_task = self.create_task(self._run_client()) + + async def _disconnect(self) -> None: + """Disconnect from the STT service.""" + # Stop the audio buffer + self._audio_buffer.stop() + + # Disconnect the client + try: + if self._client: + await asyncio.wait_for(self._client.close(), timeout=1.0) + except asyncio.TimeoutError: + logger.warning("Timeout while closing Speechmatics client connection") + except Exception as e: + logger.error(f"Error closing Speechmatics client: {e}") + finally: + self._client = None + + # Cancel the client task + if self._client_task: + await self.cancel_task(self._client_task) + self._client_task = None + + # Log the event + logger.debug("Disconnected from Speechmatics STT service") + + def _process_config(self, transcription_config: Optional[TranscriptionConfig] = None) -> None: + """Create a formatted STT transcription config. + + This takes an optional TranscriptionConfig object and populates it with the + values from the STT service. Individual parameters take priority over those + within the config object. + + Args: + transcription_config: Optional transcription config to use. + """ + # Transcription config + if not transcription_config: + transcription_config = TranscriptionConfig( + language=self._language_code or "en", + domain=self._domain, + output_locale=self._output_locale_code, + operating_point=self._operating_point, + diarization="speaker" if self._enable_speaker_diarization else None, + enable_partials=self._enable_partials, + max_delay=self._max_delay or 2.0, + ) + else: + if self._language_code: + transcription_config.language = self._language_code + if self._domain: + transcription_config.domain = self._domain + if self._output_locale_code: + transcription_config.output_locale = self._output_locale_code + if self._operating_point: + transcription_config.operating_point = self._operating_point + if self._enable_speaker_diarization: + transcription_config.diarization = "speaker" + if self._enable_partials: + transcription_config.enable_partials = self._enable_partials + if self._max_delay: + transcription_config.max_delay = self._max_delay + + # Diarization + if self._enable_speaker_diarization and self._max_speakers: + transcription_config.speaker_diarization_config = SpeakerDiarizationConfig( + max_speakers=self._max_speakers, + ) + + # End of Utterance + if self._end_of_utterance_silence_trigger: + transcription_config.conversation_config = ConversationConfig( + end_of_utterance_silence_trigger=self._end_of_utterance_silence_trigger, + ) + + # Set config + self._transcription_config = transcription_config + + def _handle_transcript(self, message: dict[str, Any], is_final: bool) -> None: + """Handle the partial and final transcript events. + + Args: + message: The new Partial or Final from the STT engine. + is_final: Whether the data is final or partial. + """ + # Add the speech fragments + has_changed = self._add_speech_fragments( + message=message, + is_final=is_final, + ) + + # Skip if unchanged + if not has_changed: + return + + # Send frames + asyncio.run_coroutine_threadsafe(self._send_frames(), self.get_event_loop()) + + @traced_stt + async def _handle_transcription( + self, transcript: str, is_final: bool, language: Optional[Language] = None + ): + """Handle a transcription result with tracing.""" + pass + + async def _send_frames(self, finalized: bool = False) -> None: + """Send frames to the pipeline. + + Send speech frames to the pipeline. If VAD is enabled, then this will + also send an interruption and user started speaking frames. When the + final transcript is received, then this will send a user stopped speaking + and stop interruption frames. + + Args: + finalized: Whether the data is final or partial. + """ + # Get speech frames (InterimTranscriptionFrame) + speech_frames = self._get_frames_from_fragments() + + # Skip if no frames + if not speech_frames: + return + + # If final, then re=parse into TranscriptionFrame + if finalized: + # Reset the speech fragments + self._speech_fragments.clear() + + # Transform frames + frames = [ + TranscriptionFrame(**frame._as_frame_attributes(self._text_format)) + for frame in speech_frames + ] + + # Log transcript(s) + logger.debug(f"Finalized transcript: {[f.text for f in frames]}") + + # Return as interim results + else: + frames = [ + InterimTranscriptionFrame(**frame._as_frame_attributes()) for frame in speech_frames + ] + + # Send the frames back to pipecat + for frame in frames: + await self._handle_transcription( + transcript=frame.text, + is_final=finalized, + language=frame.language, + ) + await self.push_frame(frame) + + def _add_speech_fragments(self, message: dict[str, Any], is_final: bool = False) -> bool: + """Takes a new Partial or Final from the STT engine. + + Accumulates it into the _speech_data list. As new final data is added, all + partials are removed from the list. + + Note: If a known speaker is `__[A-Z0-9_]{2,}__`, then the words are skipped, + as this is used to protect against self-interruption by the assistant or to + block out specific known voices. + + Args: + message: The new Partial or Final from the STT engine. + is_final: Whether the data is final or partial. + + Returns: + bool: True if the speech data was updated, False otherwise. + """ + # Parsed new speech data from the STT engine + fragments: list[SpeechFragment] = [] + + # Current length of the speech data + current_length = len(self._speech_fragments) + + # Iterate over the results in the payload + for result in message.get("results", []): + alt = result.get("alternatives", [{}])[0] + if alt.get("content", None): + # Create the new fragment + fragment = SpeechFragment( + start_time=result.get("start_time", 0), + end_time=result.get("end_time", 0), + language=alt.get("language", Language.EN), + is_eos=alt.get("is_eos", False), + is_final=is_final, + attaches_to=result.get("attaches_to", ""), + content=alt.get("content", ""), + speaker=alt.get("speaker", None), + confidence=alt.get("confidence", 1.0), + result=result, + ) + + # Drop `__XX__` speakers + if fragment.speaker and re.match(r"^__[A-Z0-9_]{2,}__$", fragment.speaker): + continue + + # Add the fragment + fragments.append(fragment) + + # Remove existing partials, as new partials and finals are provided + self._speech_fragments = [frag for frag in self._speech_fragments if frag.is_final] + + # Return if no new fragments and length of the existing data is unchanged + if not fragments and len(self._speech_fragments) == current_length: + return False + + # Add the fragments to the speech data + self._speech_fragments.extend(fragments) + + # Data was updated + return True + + def _get_frames_from_fragments(self) -> list[SpeakerFragments]: + """Get speech data objects for the current fragment list. + + Each speech fragments is grouped by contiguous speaker and then + returned as internal SpeakerFragments objects with the `speaker_id` field + set to the current speaker (string). An utterance may contain speech from + more than one speaker (e.g. S1, S2, S1, S3, ...), so they are kept + in strict order for the context of the conversation. + + Returns: + list[SpeakerFragments]: The list of objects. + """ + # Speaker groups + current_speaker: str | None = None + speaker_groups: list[list[SpeechFragment]] = [[]] + + # Group by speakers + for frag in self._speech_fragments: + if frag.speaker != current_speaker: + current_speaker = frag.speaker + if speaker_groups[-1]: + speaker_groups.append([]) + speaker_groups[-1].append(frag) + + # Create SpeakerFragments objects + speaker_fragments: list[SpeakerFragments] = [] + for group in speaker_groups: + sd = self._get_speaker_fragments_from_fragment_group(group) + if sd: + speaker_fragments.append(sd) + + # Return the grouped SpeakerFragments objects + return speaker_fragments + + def _get_speaker_fragments_from_fragment_group( + self, + group: list[SpeechFragment], + ) -> SpeakerFragments | None: + """Take a group of fragments and piece together into SpeakerFragments. + + Each fragment for a given speaker is assembled into a string, + taking into consideration whether words are attached to the + previous or next word (notably punctuation). This ensures that + the text does not have extra spaces. This will also check for + any straggling punctuation from earlier utterances that should + be removed. + + Args: + group: List of SpeechFragment objects. + + Returns: + SpeakerFragments: The object for the group. + """ + # Check for starting fragments that are attached to previous + if group and group[0].attaches_to == "previous": + group = group[1:] + + # Check for trailing fragments that are attached to next + if group and group[-1].attaches_to == "next": + group = group[:-1] + + # Check there are results + if not group: + return None + + # Get the timing extremes + start_time = min(frag.start_time for frag in group) + + # Timestamp + ts = (self._start_time + datetime.timedelta(seconds=start_time)).isoformat( + timespec="milliseconds" + ) + + # Return the SpeakerFragments object + return SpeakerFragments( + speaker_id=group[0].speaker, + timestamp=ts, + language=group[0].language, + fragments=group, + ) + + +def _get_endpoint_url(url: str) -> str: + """Format the endpoint URL with the SDK and app versions. + + Args: + url: The base URL for the endpoint. + + Returns: + str: The formatted endpoint URL. + """ + query_params = dict() + query_params["sm-app"] = f"pipecat/{__version__}" + query = urlencode(query_params) + + return f"{url}?{query}" + + +def _language_to_speechmatics_language(language: Language) -> str: + """Convert a Language enum to a Speechmatics language code. + + Args: + language: The Language enum to convert. + + Returns: + str: The Speechmatics language code, if found. + """ + # List of supported input languages + BASE_LANGUAGES = { + Language.AR: "ar", + Language.BA: "ba", + Language.EU: "eu", + Language.BE: "be", + Language.BG: "bg", + Language.BN: "bn", + Language.YUE: "yue", + Language.CA: "ca", + Language.HR: "hr", + Language.CS: "cs", + Language.DA: "da", + Language.NL: "nl", + Language.EN: "en", + Language.EO: "eo", + Language.ET: "et", + Language.FA: "fa", + Language.FI: "fi", + Language.FR: "fr", + Language.GL: "gl", + Language.DE: "de", + Language.EL: "el", + Language.HE: "he", + Language.HI: "hi", + Language.HU: "hu", + Language.IT: "it", + Language.ID: "id", + Language.GA: "ga", + Language.JA: "ja", + Language.KO: "ko", + Language.LV: "lv", + Language.LT: "lt", + Language.MS: "ms", + Language.MT: "mt", + Language.CMN: "cmn", + Language.MR: "mr", + Language.MN: "mn", + Language.NO: "no", + Language.PL: "pl", + Language.PT: "pt", + Language.RO: "ro", + Language.RU: "ru", + Language.SK: "sk", + Language.SL: "sl", + Language.ES: "es", + Language.SV: "sv", + Language.SW: "sw", + Language.TA: "ta", + Language.TH: "th", + Language.TR: "tr", + Language.UG: "ug", + Language.UK: "uk", + Language.UR: "ur", + Language.VI: "vi", + Language.CY: "cy", + } + + # Get the language code + result = BASE_LANGUAGES.get(language) + + # Fail if language is not supported + if not result: + raise ValueError(f"Unsupported language: {language}") + + # Return the language code + return result + + +def _locale_to_speechmatics_locale(language_code: str, locale: Language) -> Optional[str]: + """Convert a Language enum to a Speechmatics language code. + + Args: + language_code: The language code. + locale: The Language enum to convert. + + Returns: + str: The Speechmatics language code, if found. + """ + # Languages and output locales + LOCALES = { + "en": { + Language.EN_GB: "en-GB", + Language.EN_US: "en-US", + Language.EN_AU: "en-AU", + }, + } + + # Get the locale code + result = LOCALES.get(language_code, {}).get(locale) + + # Fail if locale is not supported + if not result: + logger.warning(f"Unsupported output locale: {locale}, defaulting to {language_code}") + + # Return the locale code + return result diff --git a/src/pipecat/transcriptions/language.py b/src/pipecat/transcriptions/language.py index a2f269309..182a89321 100644 --- a/src/pipecat/transcriptions/language.py +++ b/src/pipecat/transcriptions/language.py @@ -145,6 +145,9 @@ class Language(StrEnum): EN_US = "en-US" EN_ZA = "en-ZA" + # Esperanto + EO = "eo" + # Spanish ES = "es" ES_AR = "es-AR" @@ -474,6 +477,9 @@ class Language(StrEnum): # Tatar TT = "tt" + # Uyghur + UG = "ug" + # Ukrainian UK = "uk" UK_UA = "uk-UA" From 5df7be6892c1160d69970706ed5826ea1abbc4f7 Mon Sep 17 00:00:00 2001 From: Filipi Fuchter Date: Thu, 3 Jul 2025 17:35:30 -0300 Subject: [PATCH 78/84] Mentioning the SpeechmaticsSTTService in the changelog. --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 79b9c04f0..8287b1b50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Added a new STT service, `SpeechmaticsSTTService`. This service provides + real-time speech-to-text transcription using the Speechmatics API. It supports + partial and final transcriptions, multiple languages, various audio formats, + and speaker diarization. + - Added `normalize` and `model_id` to `FishAudioTTSService`. - Added `run_llm` field to `LLMMessagesAppendFrame` and `LLMMessagesUpdateFrame` From 093285868e118746300b80e60d89acaa9562353e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 11:17:41 -0700 Subject: [PATCH 79/84] scripts(evals): update timeout back to 90 seconds --- scripts/evals/eval.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/evals/eval.py b/scripts/evals/eval.py index e683ff8e1..71d5c9e9e 100644 --- a/scripts/evals/eval.py +++ b/scripts/evals/eval.py @@ -104,7 +104,7 @@ class EvalRunner: asyncio.create_task(run_example_pipeline(script_path)), asyncio.create_task(run_eval_pipeline(self, example_file, prompt, eval)), ] - _, pending = await asyncio.wait(tasks, timeout=10) + _, pending = await asyncio.wait(tasks, timeout=90) if pending: logger.error(f"ERROR: Eval timeout expired, cancelling pending tasks...") for task in pending: From baa878272d21bad611b155a08ef4a952889be9e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 13:44:02 -0700 Subject: [PATCH 80/84] scripts(evals): added 07a-interruptible-speechmatics.py --- scripts/evals/README.md | 2 +- scripts/evals/run-release-evals.py | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/evals/README.md b/scripts/evals/README.md index ad94e4605..b67d5d75b 100644 --- a/scripts/evals/README.md +++ b/scripts/evals/README.md @@ -49,7 +49,7 @@ python run-release-evals.py -p 07 -a -v You can also run evals for a single example (not part of the release set): ```sh -python run-eval.py YOUR_EXAMPLE_SCRIPT -a -v +python run-eval.py -p "A simple math addition" -a -v YOUR_EXAMPLE_SCRIPT ``` Your script needs to follow any of the foundation examples pattern. diff --git a/scripts/evals/run-release-evals.py b/scripts/evals/run-release-evals.py index 2e4d563c7..3cf844735 100644 --- a/scripts/evals/run-release-evals.py +++ b/scripts/evals/run-release-evals.py @@ -39,6 +39,7 @@ TESTS_07 = [ # 07 series ("07-interruptible.py", PROMPT_SIMPLE_MATH, None), ("07-interruptible-cartesia-http.py", PROMPT_SIMPLE_MATH, None), + ("07a-interruptible-speechmatics.py", PROMPT_SIMPLE_MATH, None), ("07b-interruptible-langchain.py", PROMPT_SIMPLE_MATH, None), ("07c-interruptible-deepgram.py", PROMPT_SIMPLE_MATH, None), ("07d-interruptible-elevenlabs.py", PROMPT_SIMPLE_MATH, None), From f5c2d57e4bd88d3537ce386c7e44f290f625fa48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 11:15:35 -0700 Subject: [PATCH 81/84] update CHANGELOG for 0.0.74 --- CHANGELOG.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8287b1b50..30742d536 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,17 +5,19 @@ All notable changes to **Pipecat** will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.0.74] - 2025-07-03 ### Added -- Added a new STT service, `SpeechmaticsSTTService`. This service provides +- Added a new STT service, `SpeechmaticsSTTService`. This service provides real-time speech-to-text transcription using the Speechmatics API. It supports - partial and final transcriptions, multiple languages, various audio formats, + partial and final transcriptions, multiple languages, various audio formats, and speaker diarization. - Added `normalize` and `model_id` to `FishAudioTTSService`. +- Added `http_options` argument to `GoogleLLMService`. + - Added `run_llm` field to `LLMMessagesAppendFrame` and `LLMMessagesUpdateFrame` frames. If true, a context frame will be pushed triggering the LLM to respond. @@ -57,9 +59,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 tools = ToolsSchema(standard_tools=[do_something]) ``` - - `user_id` is now populated in the `TranscriptionFrame` and - `InterimTranscriptionFrame` when using a transport that provides a - `user_id`, like `DailyTransport` or `LiveKitTransport`. +- `user_id` is now populated in the `TranscriptionFrame` and + `InterimTranscriptionFrame` when using a transport that provides a `user_id`, + like `DailyTransport` or `LiveKitTransport`. - Added `watchdog_coroutine()`. This is a watchdog helper for couroutines. So, if you have a coroutine that is waiting for a result and that takes a long From 57c6ce7ffa6a8bc45e964b25108ce85cc083c8a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Thu, 3 Jul 2025 13:55:02 -0700 Subject: [PATCH 82/84] github: update publish message to make it clear --- .github/workflows/publish.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index 68424f106..595bab82d 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -5,7 +5,7 @@ on: inputs: gitref: type: string - description: "what git ref to build" + description: "what git tag to build (e.g. v0.0.74)" required: true jobs: From 02b63c28a599fa5037a23dc16665ad0ab21f40cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aleix=20Conchillo=20Flaqu=C3=A9?= Date: Wed, 2 Jul 2025 16:49:41 -0700 Subject: [PATCH 83/84] FrameProcessor: remove unnecessary push task When we call `FrameProcessor.push_frame()` we end up calling `FrameProcessor.queue_frame()` on the next or previous processor which already uses the input queue and guarantees frame ordering. So, there's no need to have a two queues next to each other. --- CHANGELOG.md | 6 ++++ src/pipecat/processors/frame_processor.py | 39 +---------------------- 2 files changed, 7 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30742d536..eb28247fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to **Pipecat** will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Performance + +- Remove unncessary push task in each `FrameProcessor`. + ## [0.0.74] - 2025-07-03 ### Added diff --git a/src/pipecat/processors/frame_processor.py b/src/pipecat/processors/frame_processor.py index 0d5a6db62..a049fabdb 100644 --- a/src/pipecat/processors/frame_processor.py +++ b/src/pipecat/processors/frame_processor.py @@ -152,11 +152,6 @@ class FrameProcessor(BaseObject): self.__input_event = None self.__input_frame_task: Optional[asyncio.Task] = None - # Every processor in Pipecat should only output frames from a single - # task. This avoid problems like audio overlapping. System frames are the - # exception to this rule. This create this task. - self.__push_frame_task: Optional[asyncio.Task] = None - @property def id(self) -> int: """Get the unique identifier for this processor. @@ -385,7 +380,6 @@ class FrameProcessor(BaseObject): """Clean up processor resources.""" await super().cleanup() await self.__cancel_input_task() - await self.__cancel_push_task() if self._metrics is not None: await self._metrics.cleanup() @@ -512,10 +506,7 @@ class FrameProcessor(BaseObject): if not self._check_started(frame): return - if isinstance(frame, SystemFrame): - await self.__internal_push_frame(frame, direction) - else: - await self.__push_queue.put((frame, direction)) + await self.__internal_push_frame(frame, direction) async def __start(self, frame: StartFrame): """Handle the start frame to initialize processor state. @@ -530,7 +521,6 @@ class FrameProcessor(BaseObject): self._interruption_strategies = frame.interruption_strategies self._report_only_initial_ttfb = frame.report_only_initial_ttfb self.__create_input_task() - self.__create_push_task() async def __cancel(self, frame: CancelFrame): """Handle the cancel frame to stop processor operation. @@ -540,7 +530,6 @@ class FrameProcessor(BaseObject): """ self._cancelling = True await self.__cancel_input_task() - await self.__cancel_push_task() async def __pause(self, frame: FrameProcessorPauseFrame | FrameProcessorPauseUrgentFrame): """Handle pause frame to pause processor operation. @@ -567,9 +556,6 @@ class FrameProcessor(BaseObject): async def _start_interruption(self): """Start handling an interruption by canceling current tasks.""" try: - # Cancel the push frame task. This will stop pushing frames downstream. - await self.__cancel_push_task() - # Cancel the input task. This will stop processing queued frames. await self.__cancel_input_task() except Exception as e: @@ -579,9 +565,6 @@ class FrameProcessor(BaseObject): # Create a new input queue and task. self.__create_input_task() - # Create a new output queue and task. - self.__create_push_task() - async def _stop_interruption(self): """Stop handling an interruption.""" # Nothing to do right now. @@ -677,23 +660,3 @@ class FrameProcessor(BaseObject): await self.push_error(ErrorFrame(str(e))) finally: self.__input_queue.task_done() - - def __create_push_task(self): - """Create the frame pushing task.""" - if not self.__push_frame_task: - self.__push_queue = WatchdogQueue(self.task_manager) - self.__push_frame_task = self.create_task(self.__push_frame_task_handler()) - - async def __cancel_push_task(self): - """Cancel the frame pushing task.""" - if self.__push_frame_task: - self.__push_queue.cancel() - await self.cancel_task(self.__push_frame_task) - self.__push_frame_task = None - - async def __push_frame_task_handler(self): - """Handle frames from the push queue.""" - while True: - (frame, direction) = await self.__push_queue.get() - await self.__internal_push_frame(frame, direction) - self.__push_queue.task_done() From 6cf254e2f98671f4b15b7ac15757e8f68f7e2dc2 Mon Sep 17 00:00:00 2001 From: Mark Backman Date: Thu, 3 Jul 2025 13:47:54 -0700 Subject: [PATCH 84/84] Fix: missing import in 26f foundational example, update twilio transport_params to FastAPIWebsocketParams --- examples/foundational/07d-interruptible-elevenlabs-http.py | 2 +- examples/foundational/14j-function-calling-nim.py | 2 +- examples/foundational/16-gpu-container-local-bot.py | 2 +- examples/foundational/26e-gemini-multimodal-google-search.py | 2 +- examples/foundational/26f-gemini-multimodal-live-files-api.py | 2 +- examples/open-telemetry/jaeger/bot.py | 3 ++- examples/open-telemetry/langfuse/bot.py | 3 ++- 7 files changed, 9 insertions(+), 7 deletions(-) diff --git a/examples/foundational/07d-interruptible-elevenlabs-http.py b/examples/foundational/07d-interruptible-elevenlabs-http.py index 395b9331c..6b4a5b55c 100644 --- a/examples/foundational/07d-interruptible-elevenlabs-http.py +++ b/examples/foundational/07d-interruptible-elevenlabs-http.py @@ -35,7 +35,7 @@ transport_params = { audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), diff --git a/examples/foundational/14j-function-calling-nim.py b/examples/foundational/14j-function-calling-nim.py index 0365a4369..6aa101ee8 100644 --- a/examples/foundational/14j-function-calling-nim.py +++ b/examples/foundational/14j-function-calling-nim.py @@ -42,7 +42,7 @@ transport_params = { audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), diff --git a/examples/foundational/16-gpu-container-local-bot.py b/examples/foundational/16-gpu-container-local-bot.py index 5d9eff072..fe8437be0 100644 --- a/examples/foundational/16-gpu-container-local-bot.py +++ b/examples/foundational/16-gpu-container-local-bot.py @@ -33,7 +33,7 @@ transport_params = { audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), diff --git a/examples/foundational/26e-gemini-multimodal-google-search.py b/examples/foundational/26e-gemini-multimodal-google-search.py index a9a2bc384..907634694 100644 --- a/examples/foundational/26e-gemini-multimodal-google-search.py +++ b/examples/foundational/26e-gemini-multimodal-google-search.py @@ -55,7 +55,7 @@ transport_params = { # endpointing, for now. vad_analyzer=SileroVADAnalyzer(params=VADParams(stop_secs=0.5)), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, # set stop_secs to something roughly similar to the internal setting diff --git a/examples/foundational/26f-gemini-multimodal-live-files-api.py b/examples/foundational/26f-gemini-multimodal-live-files-api.py index 160cd5e1b..07b427c37 100644 --- a/examples/foundational/26f-gemini-multimodal-live-files-api.py +++ b/examples/foundational/26f-gemini-multimodal-live-files-api.py @@ -18,10 +18,10 @@ from pipecat.pipeline.runner import PipelineRunner from pipecat.pipeline.task import PipelineParams, PipelineTask from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext from pipecat.services.gemini_multimodal_live.gemini import ( - GeminiMultimodalLiveContext, GeminiMultimodalLiveLLMService, ) from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams from pipecat.transports.services.daily import DailyParams load_dotenv(override=True) diff --git a/examples/open-telemetry/jaeger/bot.py b/examples/open-telemetry/jaeger/bot.py index 980245a02..5b16814b5 100644 --- a/examples/open-telemetry/jaeger/bot.py +++ b/examples/open-telemetry/jaeger/bot.py @@ -24,6 +24,7 @@ from pipecat.services.deepgram.stt import DeepgramSTTService from pipecat.services.llm_service import FunctionCallParams from pipecat.services.openai.llm import OpenAILLMService from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams from pipecat.transports.services.daily import DailyParams from pipecat.utils.tracing.setup import setup_tracing @@ -61,7 +62,7 @@ transport_params = { audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), diff --git a/examples/open-telemetry/langfuse/bot.py b/examples/open-telemetry/langfuse/bot.py index 08139ad19..b1bf65d99 100644 --- a/examples/open-telemetry/langfuse/bot.py +++ b/examples/open-telemetry/langfuse/bot.py @@ -24,6 +24,7 @@ from pipecat.services.deepgram.stt import DeepgramSTTService from pipecat.services.llm_service import FunctionCallParams from pipecat.services.openai.llm import OpenAILLMService from pipecat.transports.base_transport import BaseTransport, TransportParams +from pipecat.transports.network.fastapi_websocket import FastAPIWebsocketParams from pipecat.transports.services.daily import DailyParams from pipecat.utils.tracing.setup import setup_tracing @@ -58,7 +59,7 @@ transport_params = { audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(), ), - "twilio": lambda: TransportParams( + "twilio": lambda: FastAPIWebsocketParams( audio_in_enabled=True, audio_out_enabled=True, vad_analyzer=SileroVADAnalyzer(),