rasa-pro 3.12.0.dev9__py3-none-any.whl → 3.12.0.dev11__py3-none-any.whl

rasa/core/channels/voice_stream/genesys.py

@@ -0,0 +1,331 @@
+import asyncio
+import json
+from typing import Any, Awaitable, Callable, Dict, Optional, Text
+
+import structlog
+from sanic import (  # type: ignore[attr-defined]
+    Blueprint,
+    HTTPResponse,
+    Request,
+    Websocket,
+    response,
+)
+
+from rasa.core.channels import UserMessage
+from rasa.core.channels.voice_ready.utils import CallParameters
+from rasa.core.channels.voice_stream.audio_bytes import RasaAudioBytes
+from rasa.core.channels.voice_stream.call_state import (
+    call_state,
+)
+from rasa.core.channels.voice_stream.tts.tts_engine import TTSEngine
+from rasa.core.channels.voice_stream.voice_channel import (
+    ContinueConversationAction,
+    EndConversationAction,
+    NewAudioAction,
+    VoiceChannelAction,
+    VoiceInputChannel,
+    VoiceOutputChannel,
+)
+
+# Not mentioned in the documentation but observed in Geneys's example
+# https://github.com/GenesysCloudBlueprints/audioconnector-server-reference-implementation
+MAXIMUM_BINARY_MESSAGE_SIZE = 64000  # 64KB
+logger = structlog.get_logger(__name__)
+
+
+def map_call_params(data: Dict[Text, Any]) -> CallParameters:
+    """Map the twilio stream parameters to the CallParameters dataclass."""
+    parameters = data["parameters"]
+    participant = parameters["participant"]
+    # sent as {"ani": "tel:+491604697810"}
+    ani = participant.get("ani", "")
+    user_phone = ani.split(":")[-1] if ani else ""
+
+    return CallParameters(
+        call_id=parameters.get("conversationId", ""),
+        user_phone=user_phone,
+        bot_phone=participant.get("dnis", ""),
+    )
+
+
+class GenesysOutputChannel(VoiceOutputChannel):
+    @classmethod
+    def name(cls) -> str:
+        return "genesys"
+
+    async def send_audio_bytes(
+        self, recipient_id: str, audio_bytes: RasaAudioBytes
+    ) -> None:
+        """
+        Send audio bytes to the recipient with buffering.
+
+        Genesys throws a rate limit error with too many audio messages.
+        To avoid this, we buffer the audio messages and send them in chunks.
+
+        - global.inbound.binary.average.rate.per.second: 5
+        The allowed average rate per second of inbound binary data
+
+        - global.inbound.binary.max: 25
+        The maximum number of inbound binary data messages
+        that can be sent instantaneously
+
+        https://developer.genesys.cloud/organization/organization/limits#audiohook
+        """
+        call_state.audio_buffer.extend(audio_bytes)
+
+        # If we receive a non-standard chunk size, assume it's the end of a sequence
+        # or buffer is more than 32KB (this is half of genesys's max audio message size)
+        if len(audio_bytes) != 1024 or len(call_state.audio_buffer) >= (
+            MAXIMUM_BINARY_MESSAGE_SIZE / 2
+        ):
+            # TODO: we should send the buffer when we receive a synthesis complete event
+            # from TTS. This will ensure that the last audio chunk is always sent.
+            await self._send_audio_buffer(self.voice_websocket)
+
+    async def _send_audio_buffer(self, ws: Websocket) -> None:
+        """Send the audio buffer to the recipient if it's not empty."""
+        if call_state.audio_buffer:
+            buffer_bytes = bytes(call_state.audio_buffer)
+            await self._send_bytes_to_ws(ws, buffer_bytes)
+            call_state.audio_buffer.clear()
+
+    async def _send_bytes_to_ws(self, ws: Websocket, data: bytes) -> None:
+        """Send audio bytes to the recipient as a binary websocket message."""
+        if len(data) <= MAXIMUM_BINARY_MESSAGE_SIZE:
+            await self.voice_websocket.send(data)
+        else:
+            # split the audio into chunks
+            current_position = 0
+            while current_position < len(data):
+                end_position = min(
+                    current_position + MAXIMUM_BINARY_MESSAGE_SIZE, len(data)
+                )
+                await self.voice_websocket.send(data[current_position:end_position])
+                current_position = end_position
+
+    async def send_marker_message(self, recipient_id: str) -> None:
+        """Send a message that marks positions in the audio stream."""
+        pass
+
+
+class GenesysInputChannel(VoiceInputChannel):
+    @classmethod
+    def name(cls) -> str:
+        return "genesys"
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    def _get_next_sequence(self) -> int:
+        """
+        Get the next message sequence number
+        Rasa == Server
+        Genesys == Client
+
+        Genesys requires the server and client each maintain a
+        monotonically increasing message sequence number.
+        """
+        cs = call_state
+        cs.server_sequence_number += 1  # type: ignore[attr-defined]
+        return cs.server_sequence_number
+
+    def _get_last_client_sequence(self) -> int:
+        """Get the last client(Genesys) sequence number."""
+        return call_state.client_sequence_number
+
+    def _update_client_sequence(self, seq: int) -> None:
+        """Update the client(Genesys) sequence number."""
+        if seq - call_state.client_sequence_number != 1:
+            logger.warning(
+                "genesys.update_client_sequence.sequence_gap",
+                received_seq=seq,
+                last_seq=call_state.client_sequence_number,
+            )
+        call_state.client_sequence_number = seq  # type: ignore[attr-defined]
+
+    def channel_bytes_to_rasa_audio_bytes(self, input_bytes: bytes) -> RasaAudioBytes:
+        return RasaAudioBytes(input_bytes)
+
+    async def collect_call_parameters(
+        self, channel_websocket: Websocket
+    ) -> Optional[CallParameters]:
+        """Call Parameters are collected during the open event."""
+        async for message in channel_websocket:
+            data = json.loads(message)
+            self._update_client_sequence(data["seq"])
+            if data.get("type") == "open":
+                call_params = await self.handle_open(channel_websocket, data)
+                return call_params
+            else:
+                logger.error("genesys.receive.unexpected_initial_message", message=data)
+
+        return None
+
+    def map_input_message(
+        self,
+        message: Any,
+        ws: Websocket,
+    ) -> VoiceChannelAction:
+        # if message is binary, it's audio
+        if isinstance(message, bytes):
+            return NewAudioAction(self.channel_bytes_to_rasa_audio_bytes(message))
+        else:
+            # process text message
+            data = json.loads(message)
+            self._update_client_sequence(data["seq"])
+            msg_type = data.get("type")
+            if msg_type == "close":
+                logger.info("genesys.handle_close", message=data)
+                self.handle_close(ws, data)
+                return EndConversationAction()
+            elif msg_type == "ping":
+                logger.info("genesys.handle_ping", message=data)
+                self.handle_ping(ws, data)
+            elif msg_type == "playback_started":
+                logger.debug("genesys.handle_playback_started", message=data)
+                call_state.is_bot_speaking = True  # type: ignore[attr-defined]
+            elif msg_type == "playback_completed":
+                logger.debug("genesys.handle_playback_completed", message=data)
+                call_state.is_bot_speaking = False  # type: ignore[attr-defined]
+                if call_state.should_hangup:
+                    logger.info("genesys.hangup")
+                    self.disconnect(ws, data)
+            elif msg_type == "dtmf":
+                logger.info("genesys.handle_dtmf", message=data)
+            elif msg_type == "error":
+                logger.warning("genesys.handle_error", message=data)
+            else:
+                logger.warning("genesys.map_input_message.unknown_type", message=data)
+
+        return ContinueConversationAction()
+
+    def create_output_channel(
+        self, voice_websocket: Websocket, tts_engine: TTSEngine
+    ) -> VoiceOutputChannel:
+        return GenesysOutputChannel(
+            voice_websocket,
+            tts_engine,
+            self.tts_cache,
+        )
+
+    async def handle_open(self, ws: Websocket, message: dict) -> CallParameters:
+        """Handle initial open transaction from Genesys."""
+        call_parameters = map_call_params(message)
+        params = message["parameters"]
+        media_options = params.get("media", [])
+
+        # Send opened response
+        if media_options:
+            logger.info("genesys.handle_open", media_parameter=media_options[0])
+            response = {
+                "version": "2",
+                "type": "opened",
+                "seq": self._get_next_sequence(),
+                "clientseq": self._get_last_client_sequence(),
+                "id": message.get("id"),
+                "parameters": {"startPaused": False, "media": [media_options[0]]},
+            }
+            logger.debug("genesys.handle_open.opened", response=response)
+            await ws.send(json.dumps(response))
+        else:
+            logger.warning(
+                "genesys.handle_open.no_media_formats", client_message=message
+            )
+        return call_parameters
+
+    def handle_ping(self, ws: Websocket, message: dict) -> None:
+        """Handle ping message from Genesys."""
+        response = {
+            "version": "2",
+            "type": "pong",
+            "seq": self._get_next_sequence(),
+            "clientseq": message.get("seq"),
+            "id": message.get("id"),
+            "parameters": {},
+        }
+        logger.debug("genesys.handle_ping.pong", response=response)
+        _schedule_ws_task(ws.send(json.dumps(response)))
+
+    def handle_close(self, ws: Websocket, message: dict) -> None:
+        """Handle close message from Genesys."""
+        response = {
+            "version": "2",
+            "type": "closed",
+            "seq": self._get_next_sequence(),
+            "clientseq": self._get_last_client_sequence(),
+            "id": message.get("id"),
+            "parameters": message.get("parameters", {}),
+        }
+        logger.debug("genesys.handle_close.closed", response=response)
+
+        _schedule_ws_task(ws.send(json.dumps(response)))
+        _schedule_ws_task(ws.close())
+
+    def disconnect(self, ws: Websocket, data: dict) -> None:
+        """
+        Send disconnect message to Genesys.
+
+        https://developer.genesys.cloud/devapps/audiohook/protocol-reference#disconnect
+        It should be used to hangup the call.
+        Genesys will respond with a "close" message to us
+        that is handled by the handle_close method.
+        """
+        message = {
+            "version": "2",
+            "type": "disconnect",
+            "seq": self._get_next_sequence(),
+            "clientseq": self._get_last_client_sequence(),
+            "id": data.get("id"),
+            "parameters": {
+                "reason": "completed",
+                # arbitrary values can be sent here
+            },
+        }
+        logger.debug("genesys.disconnect", message=message)
+        _schedule_ws_task(ws.send(json.dumps(message)))
+
+    def blueprint(
+        self, on_new_message: Callable[[UserMessage], Awaitable[Any]]
+    ) -> Blueprint:
+        """Defines a Sanic blueprint for the voice input channel."""
+        blueprint = Blueprint("genesys", __name__)
+
+        @blueprint.route("/", methods=["GET"])
+        async def health(_: Request) -> HTTPResponse:
+            return response.json({"status": "ok"})
+
+        @blueprint.websocket("/websocket")  # type: ignore[misc]
+        async def receive(request: Request, ws: Websocket) -> None:
+            logger.debug(
+                "genesys.receive",
+                audiohook_session_id=request.headers.get("audiohook-session-id"),
+            )
+            # validate required headers
+            required_headers = [
+                "audiohook-organization-id",
+                "audiohook-correlation-id",
+                "audiohook-session-id",
+                "x-api-key",
+            ]
+
+            for header in required_headers:
+                if header not in request.headers:
+                    await ws.close(1008, f"Missing required header: {header}")
+                    return
+
+            # TODO: validate API key header
+            # process audio streaming
+            logger.info("genesys.receive", message="Starting audio streaming")
+            await self.run_audio_streaming(on_new_message, ws)
+
+        return blueprint
+
+
+def _schedule_ws_task(coro: Awaitable[Any]) -> None:
+    """Helper function to schedule a coroutine in the event loop.
+
+    Args:
+        coro: The coroutine to schedule
+    """
+    loop = asyncio.get_running_loop()
+    loop.call_soon_threadsafe(lambda: loop.create_task(coro))

rasa/core/channels/voice_stream/tts/azure.py

@@ -81,7 +81,8 @@ class AzureTTS(TTSEngine[AzureTTSConfig]):
     @staticmethod
     def create_request_body(text: str, conf: AzureTTSConfig) -> str:
         return f"""
-        <speak version='1.0' xml:lang='{conf.language}'>
+        <speak version='1.0' xml:lang='{conf.language}' xmlns:mstts='http://www.w3.org/2001/mstts'
+                xmlns='http://www.w3.org/2001/10/synthesis'>
             <voice xml:lang='{conf.language}' name='{conf.voice}'>
                 {text}
             </voice>

rasa/core/channels/voice_stream/tts/cartesia.py

@@ -1,3 +1,5 @@
+import base64
+import json
 import os
 from dataclasses import dataclass
 from typing import AsyncIterator, Dict, Optional
@@ -39,7 +41,7 @@ class CartesiaTTS(TTSEngine[CartesiaTTSConfig]):
     @staticmethod
     def get_tts_endpoint() -> str:
         """Create the endpoint string for cartesia."""
-        return "https://api.cartesia.ai/tts/bytes"
+        return "https://api.cartesia.ai/tts/sse"
 
     @staticmethod
     def get_request_body(text: str, config: CartesiaTTSConfig) -> Dict:
@@ -85,8 +87,19 @@ class CartesiaTTS(TTSEngine[CartesiaTTSConfig]):
                 url, headers=headers, json=payload, chunked=True
             ) as response:
                 if 200 <= response.status < 300:
-                    async for data in response.content.iter_chunked(1024):
-                        yield self.engine_bytes_to_rasa_audio_bytes(data)
+                    async for chunk in response.content:
+                        # we are looking for chunks in the response that look like
+                        # b"data: {..., data: <base64 encoded audio bytes> ...}"
+                        # and extract the audio bytes from that
+                        if chunk.startswith(b"data: "):
+                            json_bytes = chunk[5:-1]
+                            json_data = json.loads(json_bytes.decode())
+                            if "data" in json_data:
+                                base64_encoded_bytes = json_data["data"]
+                                channel_bytes = base64.b64decode(base64_encoded_bytes)
+                                yield self.engine_bytes_to_rasa_audio_bytes(
+                                    channel_bytes
+                                )
                     return
                 else:
                     structlogger.error(

rasa/core/channels/voice_stream/twilio_media_streams.py

@@ -98,6 +98,7 @@ class TwilioMediaStreamsInputChannel(VoiceInputChannel):
     def map_input_message(
         self,
         message: Any,
+        ws: Websocket,
     ) -> VoiceChannelAction:
         data = json.loads(message)
         if data["event"] == "media":
@@ -142,7 +143,7 @@ class TwilioMediaStreamsInputChannel(VoiceInputChannel):
     def blueprint(
         self, on_new_message: Callable[[UserMessage], Awaitable[Any]]
     ) -> Blueprint:
-        """Defines a Sanic bluelogger.debug."""
+        """Defines a Sanic blueprint for the voice input channel."""
         blueprint = Blueprint("twilio_media_streams", __name__)
 
         @blueprint.route("/", methods=["GET"])

rasa/core/channels/voice_stream/voice_channel.py

@@ -315,6 +315,7 @@ class VoiceInputChannel(InputChannel):
     def map_input_message(
         self,
         message: Any,
+        ws: Websocket,
     ) -> VoiceChannelAction:
         """Map a channel input message to a voice channel action."""
         raise NotImplementedError
@@ -340,7 +341,7 @@ class VoiceInputChannel(InputChannel):
         async def consume_audio_bytes() -> None:
             async for message in channel_websocket:
                 is_bot_speaking_before = call_state.is_bot_speaking
-                channel_action = self.map_input_message(message)
+                channel_action = self.map_input_message(message, channel_websocket)
                 is_bot_speaking_after = call_state.is_bot_speaking
 
                 if not is_bot_speaking_before and is_bot_speaking_after:

rasa/core/migrate.py

@@ -14,7 +14,7 @@ from rasa.shared.constants import (
 )
 from rasa.shared.core.constants import (
     ACTIVE_LOOP,
-    MAPPING_TYPE,
+    KEY_MAPPING_TYPE,
     REQUESTED_SLOT,
     SLOT_MAPPINGS,
     SlotMappingType,
@@ -43,7 +43,7 @@ def _create_back_up(domain_file: Path, backup_location: Path) -> Dict[Text, Any]
 def _get_updated_mapping_condition(
     condition: Dict[Text, Text], mapping: Dict[Text, Any], slot_name: Text
 ) -> Dict[Text, Text]:
-    if mapping.get(MAPPING_TYPE) not in [
+    if mapping.get(KEY_MAPPING_TYPE) not in [
         str(SlotMappingType.FROM_ENTITY),
         str(SlotMappingType.FROM_TRIGGER_INTENT),
     ]:

rasa/core/policies/flows/flow_executor.py

@@ -23,6 +23,7 @@ from rasa.core.policies.flows.flow_step_result import (
 )
 from rasa.dialogue_understanding.commands import CancelFlowCommand
 from rasa.dialogue_understanding.patterns.cancel import CancelPatternFlowStackFrame
+from rasa.dialogue_understanding.patterns.clarify import ClarifyPatternFlowStackFrame
 from rasa.dialogue_understanding.patterns.collect_information import (
     CollectInformationPatternFlowStackFrame,
 )
@@ -50,9 +51,12 @@ from rasa.dialogue_understanding.stack.frames.flow_stack_frame import (
 )
 from rasa.dialogue_understanding.stack.utils import (
     top_user_flow_frame,
+    user_flows_on_the_stack,
 )
 from rasa.shared.constants import RASA_PATTERN_HUMAN_HANDOFF
-from rasa.shared.core.constants import ACTION_LISTEN_NAME, SlotMappingType
+from rasa.shared.core.constants import (
+    ACTION_LISTEN_NAME,
+)
 from rasa.shared.core.events import (
     Event,
     FlowCompleted,
@@ -272,6 +276,28 @@ def trigger_pattern_continue_interrupted(
     return events
 
 
+def trigger_pattern_clarification(
+    current_frame: DialogueStackFrame, stack: DialogueStack, flows: FlowsList
+) -> None:
+    """Trigger the pattern to clarify which topic to continue if needed."""
+    if not isinstance(current_frame, UserFlowStackFrame):
+        return None
+
+    if current_frame.frame_type == FlowStackFrameType.CALL:
+        # we want to return to the flow that called the current flow
+        return None
+
+    pending_flows = [
+        flows.flow_by_id(frame.flow_id)
+        for frame in stack.frames
+        if isinstance(frame, UserFlowStackFrame)
+        and frame.flow_id != current_frame.flow_id
+    ]
+
+    flow_names = [flow.readable_name() for flow in pending_flows if flow is not None]
+    stack.push(ClarifyPatternFlowStackFrame(names=flow_names))
+
+
 def trigger_pattern_completed(
     current_frame: DialogueStackFrame, stack: DialogueStack, flows: FlowsList
 ) -> None:
@@ -540,38 +566,6 @@ def cancel_flow_and_push_internal_error(stack: DialogueStack, flow_name: str) ->
     stack.push(InternalErrorPatternFlowStackFrame())
 
 
-def validate_custom_slot_mappings(
-    step: CollectInformationFlowStep,
-    stack: DialogueStack,
-    tracker: DialogueStateTracker,
-    available_actions: List[str],
-    flow_name: str,
-) -> bool:
-    """Validate a slot with custom mappings.
-
-    If invalid, trigger pattern_internal_error and return False.
-    """
-    slot = tracker.slots.get(step.collect, None)
-    slot_mappings = slot.mappings if slot else []
-    for mapping in slot_mappings:
-        if (
-            mapping.get("type") == SlotMappingType.CUSTOM.value
-            and mapping.get("action") is None
-        ):
-            # this is a slot that must be filled by a custom action
-            # check if collect_action exists
-            if step.collect_action not in available_actions:
-                structlogger.error(
-                    "flow.step.run.collect_action_not_found_for_custom_slot_mapping",
-                    action=step.collect_action,
-                    collect=step.collect,
-                )
-                cancel_flow_and_push_internal_error(stack, flow_name)
-                return False
-
-    return True
-
-
 def attach_stack_metadata_to_events(
     step_id: str,
     flow_id: str,
@@ -669,7 +663,15 @@ def _run_end_step(
     structlogger.debug("flow.step.run.flow_end")
     current_frame = stack.pop()
     trigger_pattern_completed(current_frame, stack, flows)
-    resumed_events = trigger_pattern_continue_interrupted(current_frame, stack, flows)
+    resumed_events = []
+    if len(user_flows_on_the_stack(stack)) > 1:
+        # if there are more user flows on the stack,
+        # we need to trigger the pattern clarify
+        trigger_pattern_clarification(current_frame, stack, flows)
+    else:
+        resumed_events = trigger_pattern_continue_interrupted(
+            current_frame, stack, flows
+        )
     reset_events: List[Event] = reset_scoped_slots(current_frame, flow, tracker)
     return ContinueFlowWithNextStep(
         events=initial_events + reset_events + resumed_events, has_flow_ended=True
@@ -760,14 +762,6 @@ def _run_collect_information_step(
         # if we return any other FlowStepResult, the assistant will stay silent
         # instead of triggering the internal error pattern
         return ContinueFlowWithNextStep(events=initial_events)
-    is_mapping_valid = validate_custom_slot_mappings(
-        step, stack, tracker, available_actions, flow_name
-    )
-
-    if not is_mapping_valid:
-        # if we return any other FlowStepResult, the assistant will stay silent
-        # instead of triggering the internal error pattern
-        return ContinueFlowWithNextStep(events=initial_events)
 
     structlogger.debug("flow.step.run.collect")
     trigger_pattern_ask_collect_information(

rasa/core/run.py

@@ -283,9 +283,10 @@ def serve_application(
         endpoints.lock_store if endpoints else None
     )
 
-    telemetry.track_server_start(
-        input_channels, endpoints, model_path, number_of_workers, enable_api
-    )
+    if not inspect:
+        telemetry.track_server_start(
+            input_channels, endpoints, model_path, number_of_workers, enable_api
+        )
 
     rasa.utils.common.update_sanic_log_level(
         log_file, use_syslog, syslog_address, syslog_port, syslog_protocol

rasa/dialogue_understanding/commands/can_not_handle_command.py

@@ -74,7 +74,7 @@ class CannotHandleCommand(Command):
 
     def to_dsl(self) -> str:
         """Converts the command to a DSL string."""
-        return "cannot handle"
+        return "CannotHandle()"
 
     @classmethod
     def from_dsl(cls, match: re.Match, **kwargs: Any) -> CannotHandleCommand:
@@ -86,4 +86,4 @@ class CannotHandleCommand(Command):
 
     @staticmethod
     def regex_pattern() -> str:
-        return r"^cannot handle$"
+        return r"CannotHandle\(\)"

rasa/dialogue_understanding/commands/cancel_flow_command.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 import re
 from dataclasses import dataclass
 from typing import Any, Dict, List
@@ -8,8 +9,11 @@ import structlog
 
 from rasa.dialogue_understanding.commands.command import Command
 from rasa.dialogue_understanding.patterns.cancel import CancelPatternFlowStackFrame
+from rasa.dialogue_understanding.patterns.clarify import ClarifyPatternFlowStackFrame
 from rasa.dialogue_understanding.stack.dialogue_stack import DialogueStack
-from rasa.dialogue_understanding.stack.frames import UserFlowStackFrame
+from rasa.dialogue_understanding.stack.frames import (
+    UserFlowStackFrame,
+)
 from rasa.dialogue_understanding.stack.frames.flow_stack_frame import FlowStackFrameType
 from rasa.dialogue_understanding.stack.utils import top_user_flow_frame
 from rasa.shared.core.events import Event, FlowCancelled
@@ -89,7 +93,8 @@ class CancelFlowCommand(Command):
         original_stack = original_tracker.stack
 
         applied_events: List[Event] = []
-
+        # capture the top frame before we push new frames onto the stack
+        initial_top_frame = stack.top()
         user_frame = top_user_flow_frame(original_stack)
         current_flow = user_frame.flow(all_flows) if user_frame else None
 
@@ -114,6 +119,21 @@ class CancelFlowCommand(Command):
         if user_frame:
             applied_events.append(FlowCancelled(user_frame.flow_id, user_frame.step_id))
 
+        if initial_top_frame and isinstance(
+            initial_top_frame, ClarifyPatternFlowStackFrame
+        ):
+            structlogger.debug(
+                "command_executor.cancel_flow.cancel_clarification_options",
+                clarification_options=initial_top_frame.clarification_options,
+            )
+            applied_events += cancel_all_pending_clarification_options(
+                initial_top_frame,
+                original_stack,
+                canceled_frames,
+                all_flows,
+                stack,
+            )
+
         return applied_events + tracker.create_stack_updated_events(stack)
 
     def __hash__(self) -> int:
@@ -124,7 +144,7 @@ class CancelFlowCommand(Command):
 
     def to_dsl(self) -> str:
         """Converts the command to a DSL string."""
-        return "cancel"
+        return "CancelFlow()"
 
     @classmethod
     def from_dsl(cls, match: re.Match, **kwargs: Any) -> CancelFlowCommand:
@@ -133,4 +153,42 @@ class CancelFlowCommand(Command):
 
     @staticmethod
     def regex_pattern() -> str:
-        return r"^cancel$"
+        return r"CancelFlow\(\)"
+
+
+def cancel_all_pending_clarification_options(
+    initial_top_frame: ClarifyPatternFlowStackFrame,
+    original_stack: DialogueStack,
+    canceled_frames: List[str],
+    all_flows: FlowsList,
+    stack: DialogueStack,
+) -> List[FlowCancelled]:
+    """Cancel all pending clarification options.
+
+    This is a special case when the assistant asks the user to clarify
+    which pending digression flow to start after the completion of an active flow.
+    If the user chooses to cancel all options, this function takes care of
+    updating the stack by removing all pending flow stack frames
+    listed as clarification options.
+    """
+    clarification_names = set(initial_top_frame.names)
+    to_be_canceled_frames = []
+    applied_events = []
+    for frame in reversed(original_stack.frames):
+        if frame.frame_id in canceled_frames:
+            continue
+
+        to_be_canceled_frames.append(frame.frame_id)
+        if isinstance(frame, UserFlowStackFrame):
+            readable_flow_name = frame.flow(all_flows).readable_name()
+            if readable_flow_name in clarification_names:
+                stack.push(
+                    CancelPatternFlowStackFrame(
+                        canceled_name=readable_flow_name,
+                        canceled_frames=copy.deepcopy(to_be_canceled_frames),
+                    )
+                )
+                applied_events.append(FlowCancelled(frame.flow_id, frame.step_id))
+                to_be_canceled_frames.clear()
+
+    return applied_events