rasa-pro 3.12.0.dev1__py3-none-any.whl

rasa/shared/core/flows/steps/__init__.py

@@ -0,0 +1,24 @@
+from .no_operation import NoOperationFlowStep
+from .action import ActionFlowStep
+from .collect import CollectInformationFlowStep
+from .continuation import ContinueFlowStep
+from .end import EndFlowStep
+from .internal import InternalFlowStep
+from .link import LinkFlowStep
+from .set_slots import SetSlotsFlowStep
+from .start import StartFlowStep
+from .call import CallFlowStep
+
+# to make ruff happy and use the imported names
+all_steps = [
+    ActionFlowStep,
+    CollectInformationFlowStep,
+    ContinueFlowStep,
+    EndFlowStep,
+    InternalFlowStep,
+    LinkFlowStep,
+    SetSlotsFlowStep,
+    StartFlowStep,
+    NoOperationFlowStep,
+    CallFlowStep,
+]

rasa/shared/core/flows/steps/action.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Text, Dict, Any, Set
+
+from rasa.shared.constants import UTTER_PREFIX
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+@dataclass
+class ActionFlowStep(FlowStep):
+    """A flow step that that defines an action to be executed."""
+
+    action: Text
+    """The action of the flow step."""
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> ActionFlowStep:
+        """Create an ActionFlowStep object from serialized data
+
+        Args:
+            data: data for an ActionFlowStep object in a serialized format
+
+        Returns:
+            An ActionFlowStep object
+        """
+        base = super().from_json(data)
+        return ActionFlowStep(
+            action=data["action"],
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Serialize the ActionFlowStep
+
+        Returns:
+            The ActionFlowStep object as serialized data.
+        """
+        data = super().as_json()
+        data["action"] = self.action
+        return data
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return self.action
+
+    @property
+    def utterances(self) -> Set[str]:
+        """Return all the utterances used in this step."""
+        return {self.action} if self.action.startswith(UTTER_PREFIX) else set()
+
+    @property
+    def custom_action(self) -> Optional[str]:
+        """Return all the custom actions used in this step."""
+        return self.action if not self.action.startswith(UTTER_PREFIX) else None

rasa/shared/core/flows/steps/call.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Generator, Optional, Text, Dict, Any
+
+from rasa.shared.core.flows.flow_step import FlowStep
+
+if TYPE_CHECKING:
+    from rasa.shared.core.flows.flow import Flow
+
+
+@dataclass
+class CallFlowStep(FlowStep):
+    """Represents the configuration of an call flow step."""
+
+    call: Text
+    """The flow to be called."""
+    called_flow_reference: Optional["Flow"] = None
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> CallFlowStep:
+        """Used to read flow steps from parsed YAML.
+
+        Args:
+            data: The parsed YAML as a dictionary.
+
+        Returns:
+            The parsed flow step.
+        """
+        base = super().from_json(data)
+        return CallFlowStep(
+            call=data.get("call", ""),
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Returns the flow step as a dictionary.
+
+        Returns:
+            The flow step as a dictionary.
+        """
+        dump = super().as_json()
+        dump["call"] = self.call
+        return dump
+
+    def steps_in_tree(
+        self, should_resolve_calls: bool = True
+    ) -> Generator[FlowStep, None, None]:
+        """Returns the steps in the tree of the flow step."""
+
+        yield self
+
+        if should_resolve_calls:
+            if not self.called_flow_reference:
+                raise ValueError("Call flow reference not set.")
+
+            yield from self.called_flow_reference.steps_with_calls_resolved
+
+        yield from self.next.steps_in_tree(should_resolve_calls)
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return f"call_{self.call}"

rasa/shared/core/flows/steps/collect.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Any, List, Set
+
+from rasa.shared.constants import UTTER_ASK_PREFIX, ACTION_ASK_PREFIX
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+@dataclass
+class SlotRejection:
+    """A pair of validation condition and an utterance for the case of failure."""
+
+    if_: str
+    """The condition that should be checked."""
+    utter: str
+    """The utterance that should be executed if the condition is met."""
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> SlotRejection:
+        """Create a SlotRejection object from serialized data.
+
+        Args:
+            data: data for a SlotRejection object in a serialized format
+
+        Returns:
+            A SlotRejection object
+        """
+        return SlotRejection(
+            if_=data["if"],
+            utter=data["utter"],
+        )
+
+    def as_dict(self) -> Dict[str, Any]:
+        """Serialize the SlotRejection object.
+
+        Returns:
+            the SlotRejection object as serialized data
+        """
+        return {
+            "if": self.if_,
+            "utter": self.utter,
+        }
+
+
+@dataclass
+class CollectInformationFlowStep(FlowStep):
+    """A flow step for asking the user for information to fill a specific slot."""
+
+    collect: str
+    """The collect information of the flow step."""
+    utter: str
+    """The utterance that the assistant uses to ask for the slot."""
+    collect_action: str
+    """The action that the assistant uses to ask for the slot."""
+    rejections: List[SlotRejection]
+    """how the slot value is validated using predicate evaluation."""
+    ask_before_filling: bool = False
+    """Whether to always ask the question even if the slot is already filled."""
+    reset_after_flow_ends: bool = True
+    """Whether to reset the slot value at the end of the flow."""
+
+    @classmethod
+    def from_json(cls, data: Dict[str, Any]) -> CollectInformationFlowStep:
+        """Create a CollectInformationFlowStep object from serialized data.
+
+        Args:
+            data: data for a CollectInformationFlowStep object in a serialized format
+
+        Returns:
+            A CollectInformationFlowStep object
+        """
+        base = super().from_json(data)
+        return CollectInformationFlowStep(
+            collect=data["collect"],
+            utter=data.get("utter", f"{UTTER_ASK_PREFIX}{data['collect']}"),
+            # as of now it is not possible to define a different name for the
+            # action, always use the default name 'action_ask_<slot_name>'
+            collect_action=f"{ACTION_ASK_PREFIX}{data['collect']}",
+            ask_before_filling=data.get("ask_before_filling", False),
+            reset_after_flow_ends=data.get("reset_after_flow_ends", True),
+            rejections=[
+                SlotRejection.from_dict(rejection)
+                for rejection in data.get("rejections", [])
+            ],
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[str, Any]:
+        """Serialize the CollectInformationFlowStep object.
+
+        Returns:
+            the CollectInformationFlowStep object as serialized data
+        """
+        data = super().as_json()
+        data["collect"] = self.collect
+        data["utter"] = self.utter
+        data["ask_before_filling"] = self.ask_before_filling
+        data["reset_after_flow_ends"] = self.reset_after_flow_ends
+        data["rejections"] = [rejection.as_dict() for rejection in self.rejections]
+
+        return data
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return f"collect_{self.collect}"
+
+    @property
+    def utterances(self) -> Set[str]:
+        """Return all the utterances used in this step."""
+        return {self.utter} | {r.utter for r in self.rejections}

rasa/shared/core/flows/steps/constants.py

@@ -0,0 +1,5 @@
+CONTINUE_STEP_PREFIX = "NEXT:"
+START_STEP = "START"
+END_STEP = "END"
+DEFAULT_STEPS = {END_STEP, START_STEP}
+UNSET_FLOW_STEP_ID = -1

rasa/shared/core/flows/steps/continuation.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rasa.shared.core.flows.flow_step_links import FlowStepLinks, StaticFlowStepLink
+from rasa.shared.core.flows.steps.constants import (
+    CONTINUE_STEP_PREFIX,
+    UNSET_FLOW_STEP_ID,
+)
+from rasa.shared.core.flows.steps.internal import InternalFlowStep
+
+
+@dataclass
+class ContinueFlowStep(InternalFlowStep):
+    """A flow step that is dynamically introduced to jump to other flow steps."""
+
+    def __init__(self, target_step_id: str) -> None:
+        """Initializes a continue-step flow step."""
+        super().__init__(
+            idx=UNSET_FLOW_STEP_ID,
+            custom_id=CONTINUE_STEP_PREFIX + target_step_id,
+            description=None,
+            metadata={},
+            # The continue step links to the step that should be continued.
+            # The flow policy in a sense only "runs" the logic of a step
+            # when it transitions to that step, once it is there it will use
+            # the next link to transition to the next step. This means that
+            # if we want to "re-run" a step, we need to link to it again.
+            # This is why the continue step links to the step that should be
+            # continued.
+            next=FlowStepLinks(links=[StaticFlowStepLink(target_step_id)]),
+        )
+
+    @staticmethod
+    def continue_step_for_id(step_id: str) -> str:
+        return CONTINUE_STEP_PREFIX + step_id

rasa/shared/core/flows/steps/end.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rasa.shared.core.flows.flow_step_links import FlowStepLinks
+from rasa.shared.core.flows.steps.constants import END_STEP, UNSET_FLOW_STEP_ID
+from rasa.shared.core.flows.steps.internal import InternalFlowStep
+
+
+@dataclass
+class EndFlowStep(InternalFlowStep):
+    """A dynamically added flow step that marks the end of a flow."""
+
+    def __init__(self) -> None:
+        """Initializes an end flow step."""
+        super().__init__(
+            idx=UNSET_FLOW_STEP_ID,
+            custom_id=END_STEP,
+            description=None,
+            metadata={},
+            next=FlowStepLinks(links=[]),
+        )

rasa/shared/core/flows/steps/internal.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Dict, Text, Any
+
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+class InternalFlowStep(FlowStep):
+    """A superclass for built-in flow steps.
+
+    Built-in flow steps are required to manage the lifecycle of a
+    flow and are not intended to be used by users.
+    """
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> InternalFlowStep:
+        """Create an InternalFlowStep object from serialized data.
+
+        Args:
+            data: data for an InternalFlowStep in a serialized format
+
+        Returns:
+            Raises because InternalFlowSteps are not serialized or de-serialized.
+        """
+        raise ValueError(
+            "Internal flow steps are ephemeral and are not to be serialized "
+            "or de-serialized."
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Serialize the InternalFlowStep object
+
+        Returns:
+            Raises because InternalFlowSteps are not serialized or de-serialized.
+        """
+        raise ValueError(
+            "Internal flow steps are ephemeral and are not to be serialized "
+            "or de-serialized."
+        )
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        raise ValueError("Internal flow steps do not need a default id")

rasa/shared/core/flows/steps/link.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Text, Dict, Any
+
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+@dataclass
+class LinkFlowStep(FlowStep):
+    """A flow step at the end of a flow that links to and starts another flow."""
+
+    link: Text
+    """The id of the flow that should be started subsequently."""
+
+    def does_allow_for_next_step(self) -> bool:
+        """Returns whether this step allows for following steps.
+
+        Link steps need to be terminal steps, so can't have a next step."""
+        return False
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> LinkFlowStep:
+        """Create a LinkFlowStep from serialized data
+
+        Args:
+            data: data for a LinkFlowStep in a serialized format
+
+        Returns:
+            a LinkFlowStep object
+        """
+        base = super().from_json(data)
+        return LinkFlowStep(
+            link=data["link"],
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Serialize the LinkFlowStep object
+
+        Returns:
+            the LinkFlowStep object as serialized data.
+        """
+        data = super().as_json()
+        data["link"] = self.link
+        return data
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return f"link_{self.link}"

rasa/shared/core/flows/steps/no_operation.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+from dataclasses import dataclass
+
+from typing import Dict, Text, Any
+
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+@dataclass
+class NoOperationFlowStep(FlowStep):
+    """A step that doesn't do a thing.
+
+    This is NOT a branching step (but it can branch - but in addition to that
+    it also does nothing)."""
+
+    noop: Any
+    """The id of the flow that should be started subsequently."""
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> NoOperationFlowStep:
+        """Create a NoOperationFlowStep from serialized data
+
+        Args:
+            data: data for a NoOperationFlowStep in a serialized format
+
+        Returns:
+            a NoOperationFlowStep object
+        """
+        base = super().from_json(data)
+        return NoOperationFlowStep(
+            noop=data["noop"],
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Serialize the NoOperationFlowStep object
+
+        Returns:
+            the NoOperationFlowStep object as serialized data.
+        """
+        data = super().as_json()
+        data["noop"] = self.noop
+        return data
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return "noop"

rasa/shared/core/flows/steps/set_slots.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Dict, Any, Text
+
+from rasa.shared.core.flows.flow_step import FlowStep
+
+
+@dataclass
+class SetSlotsFlowStep(FlowStep):
+    """A flow step that sets one or multiple slots."""
+
+    slots: List[Dict[str, Any]]
+    """Slots and their values to set in the flow step."""
+
+    @classmethod
+    def from_json(cls, data: Dict[Text, Any]) -> SetSlotsFlowStep:
+        """Create a SetSlotsFlowStep from serialized data
+
+        Args:
+            data: data for a SetSlotsFlowStep in a serialized format
+
+        Returns:
+            a SetSlotsFlowStep object
+        """
+        base = super().from_json(data)
+        slots = [
+            {"key": k, "value": v}
+            for slot_sets in data["set_slots"]
+            for k, v in slot_sets.items()
+        ]
+        return SetSlotsFlowStep(
+            slots=slots,
+            **base.__dict__,
+        )
+
+    def as_json(self) -> Dict[Text, Any]:
+        """Serialize the SetSlotsFlowStep object
+
+        Returns:
+            the SetSlotsFlowStep object as serialized data
+        """
+        data = super().as_json()
+        data["set_slots"] = [{slot["key"]: slot["value"]} for slot in self.slots]
+        return data
+
+    @property
+    def default_id_postfix(self) -> str:
+        """Returns the default id postfix of the flow step."""
+        return "set_slots"

rasa/shared/core/flows/steps/start.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Text
+
+from rasa.shared.core.flows.flow_step_links import (
+    FlowStepLinks,
+    StaticFlowStepLink,
+)
+from rasa.shared.core.flows.steps.constants import START_STEP, UNSET_FLOW_STEP_ID
+from rasa.shared.core.flows.steps.internal import InternalFlowStep
+
+
+@dataclass
+class StartFlowStep(InternalFlowStep):
+    """A dynamically added flow step that represents the beginning of a flow."""
+
+    def __init__(self, start_step_id: Text) -> None:
+        """Initializes a start flow step.
+
+        Args:
+            start_step_id: The step id of the first step of the flow
+        """
+        super().__init__(
+            idx=UNSET_FLOW_STEP_ID,
+            custom_id=START_STEP,
+            description=None,
+            metadata={},
+            next=FlowStepLinks(links=[StaticFlowStepLink(start_step_id)]),
+        )

rasa/shared/core/flows/utils.py

@@ -0,0 +1,39 @@
+from typing import Set
+from rasa.shared.utils.io import raise_deprecation_warning
+
+RESET_PROPERTY_NAME = "reset_after_flow_ends"
+PERSIST_PROPERTY_NAME = "persisted_slots"
+
+
+def warn_deprecated_collect_step_config(flow_id: str, collect_step: str) -> None:
+    """Warns about deprecated reset_after_flow_ends usage in collect steps."""
+    raise_deprecation_warning(
+        f"Configuring '{RESET_PROPERTY_NAME}' in collect step '{collect_step}' is "
+        f"deprecated and will be removed in Rasa Pro 4.0.0. In flow id '{flow_id}', "
+        f"please use the '{PERSIST_PROPERTY_NAME}' "
+        "property at the flow level instead."
+    )
+
+
+def get_duplicate_slot_persistence_config_error_message(
+    flow_id: str, collect_step: str
+) -> str:
+    """Returns an error message for duplicate slot persistence configuration."""
+    return (
+        f"Flow with id '{flow_id}' uses the '{RESET_PROPERTY_NAME}' property "
+        f"in collect step '{collect_step}' and also the "
+        f"'{PERSIST_PROPERTY_NAME}' property at the flow level. "
+        "Please use only one of the two configuration methods."
+    )
+
+
+def get_invalid_slot_persistence_config_error_message(
+    flow_id: str, invalid_slots: Set[str]
+) -> str:
+    """Returns an error message for invalid slot persistence configuration."""
+    return (
+        f"Flow with id '{flow_id}' lists slot(s) '{invalid_slots}' in the "
+        f"'{PERSIST_PROPERTY_NAME}' property. However these slots "
+        f"are neither used in a collect step nor a set_slot step of the flow. "
+        f"Please remove such slots from the '{PERSIST_PROPERTY_NAME}' property."
+    )