Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Filter Incomplete Turns is an LLM-powered feature that detects when a user’s conversational turn was incomplete (they were cut off or need time to think) and suppresses the bot’s response accordingly. Instead of responding to partial input, the bot waits for the user to continue, then automatically re-engages if they remain silent. This creates more natural conversations by:
  • Preventing the bot from responding to incomplete thoughts
  • Giving users time to finish speaking without interruption
  • Automatically prompting users to continue after pauses

​
How It Works

When enabled, the LLM outputs a turn completion marker as the first character of every response:
MarkerMeaningBot Behavior
✓Complete - User finished their thoughtRespond normally
○Incomplete Short - User was cut off mid-sentenceSuppress response, wait 5s, then prompt
◐Incomplete Long - User needs time to thinkSuppress response, wait 10s, then prompt
The system automatically:
  1. Injects turn completion instructions into the LLM’s system prompt
  2. Detects markers in the LLM’s streaming response
  3. Suppresses bot speech for incomplete turns
  4. Starts a timeout based on the incomplete type
  5. Re-prompts the LLM when the timeout expires
The public on_user_turn_stopped event fires only after the LLM confirms the turn is complete (✓). The detector that ends speech (e.g. smart turn) instead fires on_user_turn_inference_triggered, which kicks LLM inference. Observers, transcript appenders, and UI indicators that should react to a finalized turn stay quiet on ○ / ◐ markers.

​
Configuration

Enable the feature by passing FilterIncompleteUserTurnStrategies as the user_turn_strategies on LLMUserAggregatorParams when creating an LLMContextAggregatorPair: 
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

context = LLMContext(messages)
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(),
    ),
)

​
FilterIncompleteUserTurnStrategies

FilterIncompleteUserTurnStrategies is a UserTurnStrategies specialization. It keeps your detector chain (the defaults, or any strategies you pass via start/stop) for triggering LLM inference, and appends an LLMTurnCompletionUserTurnStopStrategy that gates the public on_user_turn_stopped event on the LLM’s ✓ verdict. The detector stop strategies are wrapped with deferred(...) automatically, so they trigger inference but leave turn finalization to the LLM gate.
​
config
UserTurnCompletionConfig
default:"None"
Optional configuration object for customizing turn completion behavior (instructions, incomplete-turn timeouts, and re-prompts). If not provided, default values are used.
​
start
List[BaseUserTurnStartStrategy]
default:"[VADUser...(), TranscriptionUser...()]"
Start strategies for detecting when the user begins speaking. Defaults to the standard start strategies.
​
stop
List[BaseUserTurnStopStrategy]
Detector stop strategies that trigger LLM inference. They are wrapped with deferred(...) automatically and the LLM gate is appended as the finalizer. Defaults to AI-powered smart turn detection.

​
Deprecated parameters

The following LLMUserAggregatorParams fields predate FilterIncompleteUserTurnStrategies. They still work for one release — setting either auto-translates to FilterIncompleteUserTurnStrategies and emits a DeprecationWarning — but new code should configure the feature via user_turn_strategies instead.
​
filter_incomplete_user_turns
bool
default:"False"
deprecated
Enable LLM-based turn completion detection. When True, the system automatically appends turn completion instructions to the LLM’s system prompt and configures the LLM service to process turn markers. Deprecated in v1.2.0. Use user_turn_strategies=FilterIncompleteUserTurnStrategies() instead. Will be removed in v2.0.0.
​
user_turn_completion_config
UserTurnCompletionConfig
default:"None"
deprecated
Optional configuration object for customizing turn completion behavior. If not provided, default values are used. Deprecated in v1.2.0. Pass the config directly to FilterIncompleteUserTurnStrategies(config=...) instead. Will be removed in v2.0.0.

​
UserTurnCompletionConfig

Use UserTurnCompletionConfig to customize timeouts, prompts, and instructions. Pass it to FilterIncompleteUserTurnStrategies via config: 
from pipecat.turns.user_turn_completion_mixin import UserTurnCompletionConfig
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(
            config=UserTurnCompletionConfig(
                incomplete_short_timeout=5.0,
                incomplete_long_timeout=10.0,
                incomplete_short_prompt="Custom prompt for short pauses...",
                incomplete_long_prompt="Custom prompt for long pauses...",
                instructions="Custom turn completion instructions...",
            ),
        ),
    ),
)

​
Parameters

​
incomplete_short_timeout
float
default:"5.0"
Seconds to wait after detecting ○ (incomplete short) before re-prompting the LLM. Use shorter values for more responsive re-engagement.
​
incomplete_long_timeout
float
default:"10.0"
Seconds to wait after detecting ◐ (incomplete long) before re-prompting the LLM. Use longer values to give users more time to think.
​
incomplete_short_prompt
str
default:"..."
System prompt sent to the LLM when the short timeout expires. Should instruct the LLM to generate a brief, natural prompt encouraging the user to continue.
​
incomplete_long_prompt
str
default:"..."
System prompt sent to the LLM when the long timeout expires. Should instruct the LLM to generate a friendly check-in message.
​
instructions
str
default:"..."
Complete turn completion instructions appended to the system prompt. Override this to customize how the LLM determines turn completeness.

​
Markers Explained

​
Complete (✓)

The user has provided enough information for a meaningful response: 
User: "I'd go to Japan because I love the culture and food."
LLM: "✓ Japan is a wonderful choice! The blend of ancient traditions..."
The ✓ marker tells the system to push the response normally. The marker itself is persisted to the conversation context (so the LLM stays consistent on later turns) but is not spoken or included in transcripts.

​
Incomplete Short (○)

The user was cut off mid-sentence and will likely continue soon: 
User: "I'd go to Japan because I love"
LLM: "○"
The ○ marker suppresses the bot’s response entirely. After 5 seconds (configurable), the LLM is prompted to re-engage with something like “Go ahead, I’m listening.”

​
Incomplete Long (◐)

The user needs more time to think or explicitly asked for time: 
User: "That's a good question. Let me think..."
LLM: "◐"
The ◐ marker also suppresses the response, but waits 10 seconds (configurable) before prompting. This handles cases like:
  • “Hold on a second”
  • “Let me think about that”
  • “Hmm, that’s interesting…”

​
Usage Examples

​
Basic Usage

Enable turn completion with default settings: 
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
    LLMUserAggregatorParams,
)
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

messages = [
    {
        "role": "developer",
        "content": "You are a helpful assistant...",
    }
]

context = LLMContext(messages)
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(),
    ),
)
You don’t need to modify your system prompt. Turn completion instructions are automatically appended when FilterIncompleteUserTurnStrategies is configured.

​
Custom Timeouts

Adjust timeouts for your use case: 
from pipecat.turns.user_turn_completion_mixin import UserTurnCompletionConfig
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(
            config=UserTurnCompletionConfig(
                incomplete_short_timeout=3.0,  # More responsive
                incomplete_long_timeout=20.0,  # More patient
            ),
        ),
    ),
)

​
Custom Prompts

Customize what the LLM says when re-engaging: 
from pipecat.turns.user_turn_completion_mixin import UserTurnCompletionConfig
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(
            config=UserTurnCompletionConfig(
                incomplete_short_prompt="""The user paused briefly.
Generate a contextual prompt to encourage them to continue.
Respond with ✓ followed by your message.""",
                incomplete_long_prompt="""The user has been quiet for a while.
Generate a friendly check-in.
Respond with ✓ followed by your message.""",
            ),
        ),
    ),
)
Custom prompts must instruct the LLM to respond with ✓ followed by the message. This ensures the re-engagement message is spoken normally.

​
With Smart Turn Detection

Combine with smart turn detection for better end-of-turn detection: Smart turn detection is the default detector chain, so FilterIncompleteUserTurnStrategies() already uses it. To configure the analyzer explicitly, pass it as a stop strategy — it’s wrapped as an inference trigger automatically: 
from pipecat.audio.turn.smart_turn.local_smart_turn_v3 import LocalSmartTurnAnalyzerV3
from pipecat.turns.user_stop import TurnAnalyzerUserTurnStopStrategy
from pipecat.turns.user_turn_strategies import FilterIncompleteUserTurnStrategies

user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    user_params=LLMUserAggregatorParams(
        user_turn_strategies=FilterIncompleteUserTurnStrategies(
            stop=[
                TurnAnalyzerUserTurnStopStrategy(
                    turn_analyzer=LocalSmartTurnAnalyzerV3()
                )
            ],
        ),
    ),
)
Smart turn detection helps determine when the user stops speaking, while turn completion filtering determines whether to respond. They work well together for natural conversations.

​
Transcripts

Turn completion markers are automatically stripped from assistant transcripts emitted via the on_assistant_turn_stopped event. Your transcript handlers will receive clean text without markers: 
@assistant_aggregator.event_handler("on_assistant_turn_stopped")
async def on_assistant_turn_stopped(aggregator, message: AssistantTurnStoppedMessage):
    # message.content will be "Japan is a wonderful choice!"
    # NOT "✓ Japan is a wonderful choice!"
    # Markers are automatically stripped from transcripts
    if message.content:
        print(f"Assistant: {message.content}")
    if message.interrupted:
        print("(Turn was interrupted)")

​
Supported LLM Services

Turn completion detection works with any LLM service that inherits from LLMService:
  • OpenAI (OpenAILLMService)
  • Anthropic (AnthropicLLMService)
  • Google Gemini (GoogleLLMService)
  • AWS Bedrock (AWSLLMService)
  • And other compatible services

​
Graceful Degradation

If the LLM fails to output a turn marker:
  1. The system logs a warning indicating markers were expected but not found
  2. The buffered text is pushed normally to avoid losing the response
  3. The conversation continues without interruption
This ensures the feature doesn’t break conversations if the LLM occasionally disobeys instructions.