user_turn_completion_mixin

Mixin for adding turn completion detection to LLM services.

This mixin enables LLM services to detect and process turn completion markers (COMPLETE/INCOMPLETE) in LLM responses, allowing for smarter conversation flow where the LLM can indicate whether the user’s input was complete or if they were interrupted mid-thought.

class pipecat.turns.user_turn_completion_mixin.UserTurnCompletionConfig(instructions: str | None = None, incomplete_short_timeout: float = 5.0, incomplete_long_timeout: float = 10.0, incomplete_short_prompt: str | None = None, incomplete_long_prompt: str | None = None)

Bases: object

Configuration for turn completion behavior.

Parameters:

• instructions – Custom instructions for turn completion. If not provided, uses default USER_TURN_COMPLETION_INSTRUCTIONS.

• incomplete_short_timeout – Seconds to wait after short incomplete (○) before prompting.

• incomplete_long_timeout – Seconds to wait after long incomplete (◐) before prompting.

• incomplete_short_prompt – Custom prompt when short timeout expires.

• incomplete_long_prompt – Custom prompt when long timeout expires.

instructions: str | None = None

incomplete_short_timeout: float = 5.0

incomplete_long_timeout: float = 10.0

incomplete_short_prompt: str | None = None

incomplete_long_prompt: str | None = None

property completion_instructions: str

Turn completion instructions, using default if not set.

property short_prompt: str

Short incomplete prompt, using default if not set.

property long_prompt: str

Long incomplete prompt, using default if not set.

class pipecat.turns.user_turn_completion_mixin.UserTurnCompletionLLMServiceMixin(*args, **kwargs)

Bases: FrameProcessor

Mixin that adds turn completion detection to LLM services.

This mixin provides methods to push LLM text with turn completion detection. It processes turn completion markers to enable smarter conversation flow:

• ✓ (COMPLETE): Push response normally

• ○ (INCOMPLETE SHORT): Suppress response, wait ~5s, then prompt

• ◐ (INCOMPLETE LONG): Suppress response, wait ~15s, then prompt

When incomplete timeouts expire, the mixin automatically prompts the LLM with a contextual follow-up message to re-engage the user.

Usage example:

# With turn completion:
if self._filter_incomplete_user_turns:
    await self._push_turn_text(chunk.text)
else:
    await self.push_frame(LLMTextFrame(chunk.text))

The LLM service controls when to use turn completion by calling _push_turn_text instead of push_frame.

The mixin requires that the base class has a push_frame method compatible with FrameProcessor’s signature.

__init__(*args, **kwargs)

Initialize the turn completion mixin.

Parameters:

• *args – Positional arguments passed to parent class.

• **kwargs – Keyword arguments passed to parent class.

set_user_turn_completion_config(config: UserTurnCompletionConfig)

Set the turn completion configuration.

Parameters:

config – The turn completion configuration.

async process_frame(frame: Frame, direction: FrameDirection)

Process frames, handling turn completion state resets.

Parameters:

• frame – The frame to process.

• direction – The direction of frame processing.

async push_frame(frame: Frame, direction: FrameDirection = FrameDirection.DOWNSTREAM)

Push a frame downstream, resetting turn state at end of each LLM response.

LLMFullResponseEndFrame is generated by the LLM service itself (pushed, not received), so it must be handled here rather than in process_frame.

Parameters:

• frame – The frame to push downstream.

• direction – The direction of frame flow. Defaults to downstream.