direct_function

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).

pipecat.adapters.schemas.direct_function.DirectFunction

A “direct” function that handles LLM function calls.

A direct function is an async function whose first parameter is params (a FunctionCallParams), followed by the tool’s arguments. Its metadata (name, description, and parameter schemas) is extracted automatically from its signature and docstring, so it can be used without an accompanying FunctionSchema or provider-specific configuration.

Typed as a permissive Callable so that concrete function signatures (which a stricter Protocol form would reject) type-check when passed to public APIs. The precise contract — async, with a first parameter named params — is validated at runtime by DirectFunctionWrapper.validate_function.

alias of Callable[[…], Awaitable[Any]]

class pipecat.adapters.schemas.direct_function.BaseDirectFunctionWrapper(function: Callable)

Bases: object

Base class for a wrapper around a DirectFunction.

Provides functionality to:

• extract metadata from the function signature and docstring

• use that metadata to generate a corresponding FunctionSchema

__init__(function: Callable)

Initialize the direct function wrapper.

Parameters:

function – The function to wrap and extract metadata from.

classmethod special_first_param_name() → 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.

classmethod validate_function(function: Callable) → None

Validate that the function meets direct function requirements.

Parameters:

function – The function to validate.

Raises:

Exception – If function doesn’t meet requirements (not async, missing parameters, incorrect first parameter name).

to_function_schema() → FunctionSchema

Convert the wrapped function to a FunctionSchema.

Returns:

A FunctionSchema instance with extracted metadata.

class pipecat.adapters.schemas.direct_function.DirectFunctionWrapper(function: Callable)

Bases: BaseDirectFunctionWrapper

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 special_first_param_name() → str

Get the special first parameter name for direct functions.

Returns:

The string “params” which is expected as the first parameter.

async invoke(args: Mapping[str, Any], params: FunctionCallParams)

Invoke the wrapped function with the provided arguments.

Parameters:

• args – Arguments to pass to the function.

• params – Function call parameters from the LLM service.

Returns:

The result of the function call.

pipecat.adapters.schemas.direct_function.tool_options(fn=None, *, cancel_on_interruption: bool = True, timeout_secs: float | None = None)

Configure a handler’s call options.

This decorator is optional. A handler advertised in an LLMContext’s tools — a direct function, or the handler a FunctionSchema carries — is registered automatically with default call options, so the decorator is only needed when you want to override those defaults. It attaches the options to the handler and returns it unchanged — it does not register anything, so decorated handlers can stay at module level.

On an LLMWorker, use @tool instead, which applies these same options and additionally marks the method for collection as one of the worker’s tools.

Can be used with or without arguments:

@tool_options
async def get_weather(params, location: str):
    ...

@tool_options(cancel_on_interruption=False, timeout_secs=60)
async def end_call(params, reason: str):
    ...

Parameters:

• fn – The function to decorate (when used without arguments).

• cancel_on_interruption – Whether to cancel this function call when an interruption occurs. Defaults to True.

• timeout_secs – Optional per-tool timeout in seconds. Defaults to None (uses the LLM service default).

Returns:

The decorated function, unchanged except for pipecat call-option metadata attached under private _pipecat_* attributes (read internally; not part of the public API).