Domain

In Rasa, your domain defines the universe in which your assistant operates. Specifically, it lists:

• The responses that can be used as templated messages to send to a user.
• The custom actions that can be predicted by dialogue policies.
• The slots that act as your assistant's memory throughout a conversation.
• Session configuration parameters including inactivity timeout.

If you are building an NLU-based assistant, refer to the Domain documentation to see how intents, entities, slot mappings, and slot featurization can be configured in your domain.

Multiple Domain Files#

The domain can be defined as a single YAML file or split across multiple files in a directory. When split across multiple files, the domain contents will be read and automatically merged together. You can also manage your responses, slots, custom actions in Rasa Studio.

Using the command line interface, you can train a model with split domain files by running:

Responses#

Responses are templated messages that your assistant can send to your user. Responses can contain rich content like buttons, images, and custom json payloads. Every response is also an action, meaning that it can be used directly in an action step in a flow. Responses can be defined directly in the domain file under the responses key. For more information on responses and how to define them, see Responses.

Actions#

Actions are the things your bot can do. For example, an action could:

• respond to a user,

• make an external API call,

• query a database, or

• just about anything!

All custom actions should be listed in your domain.

Rasa also has default actions which you do not need to list in your domain.

Slots#

Slots are your assistant's memory. They act as a key-value store which can be used to store information the user provided (e.g. their home city) as well as information gathered about the outside world (e.g. the result of a database query).

Slots are defined in the slots section of your domain with their name, type and default value. Different slot types exist to restrict the possible values a slot can take.

Slot Types#

Text Slot#

A text slot can take on any string value.

• Example

  Copy

  slots:

  cuisine:

  type: text

• Allowed Values

  Any string

Boolean Slot#

A boolean slot can only take on the values true or false. This is useful when you want to store a binary value.

• Example

  Copy

  slots:

  confirmation:

  type: bool

• Allowed Values

  true or false

Categorical Slot#

A categorical slot can only take on values from a predefined set. This is useful when you want to restrict the possible values a slot can take.

If the user provides a value where the casing does not match the casing of the values defined in the domain, the value will be coerced to the correct casing. For example, if the user provides the value LOW for a slot with values low, medium, high, the value will be converted to low and stored in the slot.

If you define a categorical slot with a list of values, where multiple of the values coerce to the same value, a warning will be issued and you should remove one of the values from the set in the domain. For example, if you define a categorical slot with values low, medium, high, and Low, the value Low will be coerced to low and a warning will be issued.

• Example

  Copy

  slots:

  risk_level:

  type: categorical

  values:

  - low

  - medium

  - high

Float Slot#

A float slot can only take on floating point values. This is useful when you want to store a number with a decimal point.

• Example

  Copy

  slots:

  temperature:

  type: float

Any Slot#

This slot type can take on any value. This is useful when you want to store any type of information, including structured data like dictionaries.

• Example

  Copy

  slots:

  shopping_items:

  type: any

List Slot#

A list slot can take on a list of values. Note that the list slot type is only supported in custom actions when building an assistant with CALM. List slots cannot be filled with flows in either the collect or set_slots flow step types.

CALM Slot Mappings#

NLU-based predefined slot mappings#

You can continue using the nlu-based predefined slot mappings such as from_entity or from_intent when building an assistant with CALM. In addition to including tokenizers, featurizers, intent classifiers, and entity extractors to your pipeline, you must also add the NLUCommandAdapter to the config.yml file. The NLUCommandAdapter will match the output of the NLU pipeline (intents and entities) against the slot mappings defined in the domain file. If the slot mappings are satisfied, the NLUCommandAdapter will issue set slot commands to fill the slots.

If during message processing, the NLUCommandAdapter issues commands, then the following command generators in the pipeline such as LLM-based command generators will be entirely bypassed. As a consequence, LLM-based command generators will not be able to fill slots by issuing set slot commands at any point in the conversation flow. If the LLM-based command generator issues commands to fill slots with nlu-based predefined mappings, these set slot commands from LLM-based command generator are ignored. If no other commands were predicted for the same turn, then the assistant will trigger the cannot_handle conversation repair pattern.

Sometimes the user message may contain intentions that go beyond setting a slot. For example, the user message may contain an entity that fills a slot but also starts a digression that must be handled. In such cases, we recommend using NLU triggers to handle those specific intents within flows. Please refer to the Impact of slot mappings in different scenarios section for more details.

from_llm#

You can use the from_llm slot mapping type to fill slots with values generated by LLM-based command generators. This is the default slot mapping type if the mappings are not explicitly defined in the domain file.

Here is an example:

In this example, the user_name slot will be filled with the value generated by the LLM-based command generator. The LLM-based command generator is allowed to fill this slot at any point in the conversation flow, not just at the corresponding collect step for this slot.

If you have defined additional NLU-based components in the config.yml pipeline, these components will continue to process the user message however they will not be able to fill slots. The NLUCommandAdapter will skip any slots with from_llm mappings and will not issue set slot commands to fill these slots. Please refer to the Impact of slot mappings in different scenarios section for more details.

Note that a slot must not have both from_llm and NLU-based predefined mappings or custom slot mappings. If you define a slot with from_llm mapping, you cannot define any other mapping types for that slot.

Mapping Conditions#

You can define conditions for slot mappings to be satisfied before the slot is filled. The conditions are defined as a list of conditions under the conditions key. Each condition can specify the flow id that must be active to the active_flow property.

This is particularly useful if you define several slots mapped to the same entity, but you do not want to fill all of them when the entity is extracted.

For example:

Custom Slot Mappings#

You can use the custom mapping type to define custom slot mappings for slots that should be filled by a custom action. The custom action must be specified in the action property of the slot mapping. You must also list the action in the domain file under the actions key.

For example:

In this example, the user_name slot will be filled by the action_fill_user_name custom action. The custom action must return a SlotSet event with the slot name and value to fill the slot.

Note that if you're using the action_ask_<slot_name> naming convention for requesting user input via a custom action, but the slot is filled by the value generated by the LLM-based command generator, you should not define a custom slot mapping for that slot. Instead, use from_llm mapping type, because custom mapping type is reserved for slots that are set by a custom action returning a SlotSet event (e.g. for slots set by external sources). You can continue using the action_ask_<slot_name> convention to request user input for slots that are filled by the LLM-based command generator.

If you are using custom validation actions (using the validate_<slot_name> naming convention) to validate slot values extracted by the LLM-based generator from the end user's input, you should not define custom slot mappings for those slots either. Instead, use the from_llm mapping type for those slots.

Impact of slot mappings in different scenarios#

This section clarifies which components in a CALM assistant built with flows and a NLU pipeline are responsible for filling slots in different scenarios when the flow is at either the collect step for slot name or at any other step.

1. Assume slot name is defined with the from_llm mapping type.

Main takeaway is that the NLUCommandAdapter cannot fill slots with from_llm mappings at any point in the conversation.

2. Assume slot name is defined with one of the NLU-based predefined mappings such as from_entity.

Main takeaways:

• The LLM-based generator cannot fill slots with NLU-based predefined mappings at any point in the conversation.
• The LLM-based generator will not be active at the collect step for slot name. If you expect the user utterance to contain digressions or other intentions beyond information for setting a slot, you should use NLU triggers to handle those specific intents within flows.
• The LLM-based generator can fill other slots at steps where slot name is not collected and they have from_llm mapping type.

Initial slot values#

You can provide an initial value for any slot in your domain file:

Persistence of Slots during Coexistence#

In Coexistence of NLU-based and CALM systems the action action_reset_routing resets all slots and hides events from featurization for the NLU-based system policies to prevent them from seeing events that originated while CALM was active. However, you might want to share some slots that both CALM and the NLU-based system should be able to use. One use case for these slots are basic user profile slots. Both the NLU-based system and CALM should likely be able to know whether a user is logged in or not, what their user name is, or what channel they are using. If you are storing this kind of data in slots you can annotate those slot definitions with the option shared_for_coexistence: True.

In the coexistence mode, if the option shared_for_coexistence is NOT set to true, it invalidates the reset_after_flow_ends: False property in the flow definition. In order for the slot value to be retained throughout the conversation, the shared_for_coexistence must be set to true.

Session configuration#

A conversation session represents the dialogue between the assistant and the user. Conversation sessions can begin in three ways:

1. the user begins the conversation with the assistant,

2. the user sends their first message after a configurable period of inactivity, or

3. a manual session start is triggered with the /session_start intent message.

You can define the period of inactivity after which a new conversation session is triggered in the domain under the session_config key.

Available parameters are:

• session_expiration_time defines the time of inactivity in minutes after which a new session will begin.
• carry_over_slots_to_new_session determines whether existing set slots should be carried over to new sessions.

The default session configuration looks as follows:

This means that if a user sends their first message after 60 minutes of inactivity, a new conversation session is triggered, and that any existing slots are carried over into the new session. Setting the value of session_expiration_time to 0 means that sessions will not end (note that the action_session_start action will still be triggered at the very beginning of conversations).

Select which actions should receive domain#

To do this you must first enable selective domain in you endpoint configuration for action_endpoint in endpoints.yml.

After selective domain for custom actions is enabled, domain will be sent only to those custom actions which have specifically stated that they need it. Custom actions inheriting from rasa-sdk FormValidationAction parent class are an exception to this rule as they will always have the domain sent to them. To specify if an action needs the domain add {send_domain: true} to custom action in the list of actions in domain.yml: