qiFdZddlZddlmZddlmZmZddlmZddl m Z m Z m Z m Z mZmZddlmZdZd Zd Zd Zd Zd ZeGddZGddZy)aDMixin 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. N) dataclass)LiteralOptional)logger)FrameInterruptionFrameLLMFullResponseEndFrameLLMMessagesAppendFrame LLMRunFrame LLMTextFrame)FrameDirectionu✓u○u◐uThe user paused briefly. Generate a brief, natural prompt to encourage them to continue. IMPORTANT: You MUST respond with ✓ followed by your message. Do NOT output ○ or ◐ - the user has already been given time to continue. Your response should: - Be contextually relevant to what was just discussed - Sound natural and conversational - Be very concise (1 sentence max) - Gently prompt them to continue Example format: ✓ Go ahead, I'm listening. Generate your ✓ response now.uThe user has been quiet for a while. Generate a friendly check-in message. IMPORTANT: You MUST respond with ✓ followed by your message. Do NOT output ○ or ◐ - the user has already been given plenty of time. Your response should: - Acknowledge they might be thinking or busy - Offer to help or continue when ready - Be warm and understanding - Be brief (1 sentence) Example format: ✓ No rush! Let me know when you're ready to continue. Generate your ✓ response now.u CRITICAL INSTRUCTION - MANDATORY RESPONSE FORMAT: Every single response MUST begin with a turn completion indicator. This is not optional. TURN COMPLETION DECISION FRAMEWORK: Ask yourself: "Has the user provided enough information for me to give a meaningful, substantive response?" Mark as COMPLETE (✓) when: - The user has answered your question with actual content - The user has made a complete request or statement - The user has provided all necessary information for you to respond meaningfully - The conversation can naturally progress to your substantive response Mark as INCOMPLETE SHORT (○) when the user will likely continue soon: - The user was clearly cut off mid-sentence or mid-word - The user is in the middle of a thought that got interrupted - Brief technical interruption (they'll resume in a few seconds) Mark as INCOMPLETE LONG (◐) when the user needs more time: - The user explicitly asks for time: "let me think", "give me a minute", "hold on" - The user is clearly pondering or deliberating: "hmm", "well...", "that's a good question" - The user acknowledged but hasn't answered yet: "That's interesting..." - The response feels like a preamble before the actual answer RESPOND in one of these three formats: 1. If COMPLETE: `✓` followed by a space and your full substantive response 2. If INCOMPLETE SHORT: ONLY the character `○` (user will continue in a few seconds) 3. If INCOMPLETE LONG: ONLY the character `◐` (user needs more time to think) KEY INSIGHT: Grammatically complete ≠ conversationally complete - "That's a really good question." is grammatically complete but conversationally incomplete (use ◐) - "I'd go to Japan because I love" is mid-sentence (use ○) EXAMPLES: You ask: "Where would you travel?" User: "I'd go to Japan because I love" → `○` (Cut off mid-sentence - they'll continue in seconds) You ask: "Where would you travel?" User: "That's a good question. Let me think..." → `◐` (User is deliberating - give them time) You ask: "Where would you travel?" User: "Hmm, hold on a second." → `◐` (User explicitly asked for time) You ask: "Where would you travel?" User: "I'd go to Japan because I love the culture." → `✓ Japan is a wonderful choice! The blend of ancient traditions and modern innovation is truly unique. Have you been before?` (Complete answer - give full response) User: "I need help with" → `○` (Cut off mid-request - they'll finish soon) User: "Well, let me think about that for a moment." → `◐` (User needs time to think) User: "Can you help me book a flight to New York next week?" → `✓ I'd be happy to help you with that! Let me gather some information...` (Complete request - provide full response) User: "Give me a minute to gather my thoughts." → `◐` (User explicitly asked for time) FORMAT REQUIREMENTS: - ALWAYS use single-character indicators: `✓` (complete), `○` (short wait), or `◐` (long wait) - For COMPLETE: `✓` followed by a space and your full response - For INCOMPLETE: ONLY the single character (`○` or `◐`) with absolutely nothing else - Your turn indicator must be the very first character in your response Remember: Focus on conversational completeness and how long the user might need. Was it a mid-sentence cutoff (○) or do they need time to think (◐)?ceZdZUdZdZeeed<dZe ed<dZ e ed<dZ eeed<dZ eeed <e d efd Ze d efd Ze d efd Zy)UserTurnCompletionConfigu!Configuration for turn completion behavior. Attributes: 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. N instructionsg@incomplete_short_timeoutg$@incomplete_long_timeoutincomplete_short_promptincomplete_long_promptreturnc*|jxstS)z7Turn completion instructions, using default if not set.)r!USER_TURN_COMPLETION_INSTRUCTIONSselfs Z/opt/pipecat/venv/lib/python3.12/site-packages/pipecat/turns/user_turn_completion_mixin.pycompletion_instructionsz0UserTurnCompletionConfig.completion_instructionss  E$EEc*|jxstS)z2Short incomplete prompt, using default if not set.)rDEFAULT_INCOMPLETE_SHORT_PROMPTrs r short_promptz%UserTurnCompletionConfig.short_prompts++N/NNrc*|jxstS)z1Long incomplete prompt, using default if not set.)rDEFAULT_INCOMPLETE_LONG_PROMPTrs r long_promptz$UserTurnCompletionConfig.long_prompts**L.LLr)__name__ __module__ __qualname____doc__rrstr__annotations__rfloatrrrpropertyrrr"rrrrs #'L(3-&&)e)%)U)-1Xc]1,0HSM0 FFFOcOOMSMMrrceZdZdZfdZdefdZdedfdZdZ dedd e fd Z d Z d e d effd Zej fd e d effd ZdefdZxZS)!UserTurnCompletionLLMServiceMixinuMixin 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: The LLM service controls when to use turn completion by calling _push_turn_text instead of push_frame: # 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 mixin requires that the base class has a `push_frame` method compatible with FrameProcessor's signature. ct||i|d|_d|_d|_t |_d|_d|_y)zInitialize the turn completion mixin. Args: *args: Positional arguments passed to parent class. **kwargs: Keyword arguments passed to parent class. FN) super__init___turn_text_buffer_turn_suppressed_turn_complete_foundr_user_turn_completion_config_incomplete_timeout_task_incomplete_type)rargskwargs __class__s rr1z*UserTurnCompletionLLMServiceMixin.__init__sO $)&)!#!&$)!-E,F)@D%DHrconfigc||_y)zuSet the turn completion configuration. Args: config: The turn completion configuration. N)r5)rr;s rset_user_turn_completion_configzAUserTurnCompletionLLMServiceMixin.set_user_turn_completion_configs -3)rincomplete_type)shortlongc>K|jd{||_|dk(r|jj}n|jj}t j d|d|d|j|j||d||_ y7w)zStart a timeout task for incomplete turn handling. Args: incomplete_type: Either "short" or "long" to determine timeout duration. Nr?z Starting z incomplete timeout (zs)_incomplete_timeout_) _cancel_incomplete_timeoutr7r5rrrdebug create_task_incomplete_timeout_handlerr6)rr>timeouts r_start_incomplete_timeoutz;UserTurnCompletionLLMServiceMixin._start_incomplete_timeouts--/// / g %77PPG77OOG y 11FwirRS(,(8(8  , ,_g F"?"3 4) % 0sBBBBcK|jrR|jjs8tjd|j |jd{d|_d|_y7w)z+Cancel any pending incomplete timeout task.zCancelling incomplete timeoutN)r6donerrD cancel_taskr7rs rrCzrGprompts rrFz=UserTurnCompletionLLMServiceMixin._incomplete_timeout_handler s --( ( ( KK+o%66UV W""$ $ $,0D )$(D !')::GG::FF//&(v1V0WX  //+-0 0 0% ) %  1%%   soC<C#C0C# CA&C#4C5 C#C!C#C<C#C#C#!C##C96C<8C99C<cK|jxs |j}|sP|jrDtj|d|j t |jd{d|_d|_d|_y7w)arReset turn completion state between responses. Call this at the end of each LLM response to clear buffered text and reset state. If no marker was found, pushes the buffered text to avoid losing content. Note: This does NOT cancel pending incomplete timeouts. Timeouts are only cancelled on InterruptionFrame (when user speaks). u: filter_incomplete_user_turns is enabled but LLM response did not contain turn completion markers (✓/○/◐). Pushing text anyway. The system prompt may be missing turn completion instructions.Nr/F)r3r4r2rwarningrUr )r marker_founds rrTz-UserTurnCompletionLLMServiceMixin._turn_reset,s,,I0I0I  6 6 NN&QQ  //,t/E/E"FG G G!# %$)! HsA(B*B+Bframe directioncKt|tr0|jd{|jd{t|||d{y7577 w)zProcess frames, handling turn completion state resets. Args: frame: The frame to process. direction: The direction of frame processing. N) isinstancerrCrTr0 process_framerr[r\r:s rr_z/UserTurnCompletionLLMServiceMixin.process_frameDs^ e. /113 3 3""$ $ $g#E9555 4 $ 6s2$A#AA#AA#A!A#A#!A#cKt|tr|jd{t|||d{y77w)aPush 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``. Args: frame: The frame to push downstream. direction: The direction of frame flow. Defaults to downstream. N)r^r rTr0rUr`s rrUz,UserTurnCompletionLLMServiceMixin.push_frameSsD e4 5""$ $ $g  222 %2s $A AA AA A textc:K|jry|jr#|jt|d{y|xj|z c_d}t |jvrd}nt |jvrd}|r|dk(rt nt }tjd|jd|dd|_t|j}d|_ |j|d{d|_|j|d{yt|jvrtjd td |jjt}|ttz}|jd|}t|}d|_ |j|d{|j|d}|r:|jd r|d d}|r"|jt|d{d|_d|_yy7777h7w) uhPush LLM text with turn completion detection. This method should be used instead of `push_frame(LLMTextFrame(text))` when turn completion is enabled. It will: 1. Detect turn markers (✓, ○, or ◐) 2. When ○ (SHORT) is found: suppress text, start short timeout 3. When ◐ (LONG) is found: suppress text, start long timeout 4. When ✓ (COMPLETE) is found: push all text with marker marked as skip_tts 5. After marker detected: all subsequent text flows through immediately Args: text: The text content from the LLM to push. Nr?r@z INCOMPLETE z (z) detected, suppressing textTr/z COMPLETE (z!) detected, pushing buffered text )r3r4rUr r2!USER_TURN_INCOMPLETE_SHORT_MARKER USER_TURN_INCOMPLETE_LONG_MARKERrrDupperskip_ttsrHUSER_TURN_COMPLETE_MARKERindexlen startswith) rrbr>markerr[ marker_pos marker_end marker_textremaining_texts r_push_turn_textz1UserTurnCompletionLLMServiceMixin._push_turn_textbs "    $ $//,t"45 5 5  $& ?C ,0F0F F%O -1G1G G$O #g-25  LLo3356b@\] %)D !!!7!78E!EN//%( ( (%'D "00A A A  %(>(> > LL:&?%@@ab c//556OPJ#c*C&DDJ00*=K -E!EN//%( ( ("33JK@N!,,S1%3AB%7N!//,~*FGGG&(D "(,D % 5 ?K 6< ) B )HsZ7HHB9H3H4HHBH.H/A H9H:HHHHH)r#r$r%r&r1rr=rrHrCr)rFrTrr r_ DOWNSTREAMrUr'rs __classcell__)r:s@rr-r-s4I(36N3 w?W ,% &7 BG D*0 6 6> 6JXIbIb 3e 3 3U#Urr-)r&rQ dataclassesrtypingrrlogururpipecat.frames.framesrrr r r r "pipecat.processors.frame_processorr rjrfrgrr!rrr-r+rrr{s!$>"$)!#(  ## "#M%\!` MM MDBBr