Domain

Here is a full example of a domain, taken from the concertbot example:

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.

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

Intents#

The intents key in your domain file lists all intents used in your NLU data and conversation training data.

Ignoring Entities for Certain Intents#

To ignore all entities for certain intents, you can add the use_entities: [] parameter to the intent in your domain file like this:

To ignore some entities or explicitly take only certain entities into account you can use this syntax:

You can only use_entities or ignore_entities for a single intent.

Excluded entities for those intents will be unfeaturized and therefore will not impact the next action predictions. This is useful when you have an intent where you don't care about the entities being picked up.

If you list your intents without a use_entities or ignore_entities parameter, the entities will be featurized as normal.

Entities#

The entities section lists all entities that can be extracted by any entity extractor in your NLU pipeline.

For example:

When using multiple domain files, entities can be specified in any domain file, and can be used or ignored by any intent in any domain file.

If you are using the feature Entity Roles and Groups you also need to list the roles and groups of an entity in this section.

For example:

Slots#

Slots are your bot'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 if and how they should influence the assistant's behavior. The following example defines a slot with name "slot_name" and type text.

Slots and Conversation Behavior#

You can specify whether or not a slot influences the conversation with the influence_conversation property.

If you want to store information in a slot without it influencing the conversation, set influence_conversation: false when defining your slot.

The following example defines a slot age which will store information about the user's age, but which will not influence the flow of the conversation. This means that the assistant will ignore the value of the slot each time it predicts the next action.

When defining a slot, if you leave out influence_conversation or set it to true, that slot will influence the next action prediction, unless it has slot type any. The way the slot influences the conversation will depend on its slot type.

The following example defines a slot home_city that influences the conversation. A text slot will influence the assistant's behavior depending on whether the slot has a value. The specific value of a text slot (e.g. Bangalore or New York or Hong Kong) doesn't make any difference.

As an example, consider the two inputs "What is the weather like?" and "What is the weather like in Bangalore?" The conversation should diverge based on whether the home_city slot was set automatically by the NLU. If the slot is already set, the bot can predict the action_forecast action. If the slot is not set, it needs to get the home_city information before it is able to predict the weather.

Slot Types#

Text Slot#

• Type

  text

• Use For

  Storing text values.

• Example

  Copy

  slots:

  cuisine:

  type: text

• Description

  If influence_conversation is set to true, the assistant's behavior will change depending on whether the slot is set or not. Different texts do not influence the conversation any further. This means the following two stories are equal:

  Copy

  stories:

  - story: French cuisine

  steps:

  - intent: inform

  - slot_was_set:

  - cuisine: french

  - story: Vietnamese cuisine

  steps:

  - intent: inform

  - slot_was_set:

  - cuisine: vietnamese

Boolean Slot#

• Type

  bool

• Use For

  Storing true or false values.

• Example

  Copy

  slots:

  is_authenticated:

  type: bool

• Description

  If influence_conversation is set to true, the assistant's behavior will change depending on whether the slot is empty, set to true or set to false. Note that an empty bool slot influences the conversation differently than if the slot was set to false.

Categorical Slot#

• Type

  categorical

• Use For

  Storing slots which can take one of N values.

• Example

  Copy

  slots:

  risk_level:

  type: categorical

  values:

  - low

  - medium

  - high

• Description

  If influence_conversation is set to true, the assistant's behavior will change depending on the concrete value of the slot. This means the assistant's behavior is different depending on whether the slot in the above example has the value low, medium, or high.

  A default value __other__ is automatically added to the user-defined values. All values encountered which are not explicitly defined in the slot's values are mapped to __other__. __other__ should not be used as a user-defined value; if it is, it will still behave as the default to which all unseen values are mapped.

Float Slot#

• Type

  float

• Use For

  Storing real numbers.

• Example

  Copy

  slots:

  temperature:

  type: float

  min_value: -100.0

  max_value: 100.0

• Defaults

  max_value=1.0, min_value=0.0

• Description

  If influence_conversation is set to true, the assistant's behavior will change depending on the value of the slot. If the value is between min_value and max_value, the specific value of the number is used. All values below min_value will be treated as min_value, and all values above max_value will be treated as max_value. Hence, if max_value is set to 1, there is no difference between the slot values 2 and 3.5.

List Slot#

• Type

  list

• Use For

  Storing lists of values.

• Example

  Copy

  slots:

  shopping_items:

  type: list

• Description

  If influence_conversation is set to true, the assistant's behavior will change depending on whether the list is empty or not. The length of the list stored in the slot does not influence the dialogue. It only matters whether list length is zero or non-zero.

Any Slot#

• Type

  any

• Use For

  Storing arbitrary values (they can be of any type, such as dictionaries or lists).

• Example

  Copy

  slots:

  shopping_items:

  type: any

• Description

  Slots of type any are always ignored during conversations. The property influence_conversation cannot be set to true for this slot type. If you want to store a custom data structure which should influence the conversation, use a custom slot type.

Custom Slot Types#

Maybe your restaurant booking system can only handle bookings for up to 6 people. In this case you want the value of the slot to influence the next selected action (and not just whether it's been specified). You can do this by defining a custom slot class.

The code below defines a custom slot class called NumberOfPeopleSlot. The featurization defines how the value of this slot gets converted to a vector so Rasa Open Source machine learning model can deal with it. The NumberOfPeopleSlot has three possible “values”, which can be represented with a vector of length 2.

You can implement a custom slot class as an independent python module, separate from custom action code. Save the code for your custom slot in a directory alongside an empty file called "__init__.py" so that it will be recognized as a python module. You can then refer to the custom slot class by it's module path.

For example, say you have saved the code above in "addons/my_custom_slots.py", a directory relative to your bot project:

Your custom slot type's module path is then addons.my_custom_slots.NumberOfPeopleSlot. Use the module path to refer to the custom slot type in your domain file:

Now that your custom slot class can be used by Rasa Open Source, add training stories that diverge based on the value of the people slot. You could write one story for the case where people has a value between 1 and 6, and one for a value greater than six. You can choose any value within these ranges to put in your stories, since they are all featurized the same way (see the featurization table above).

Unfeaturized Slot#

• Type

  unfeaturized

• Use For

  Data you want to store which shouldn't influence the dialogue flow.

• Example

  Copy

  slots:

  internal_user_id:

  type: unfeaturized

• Description

  Slots of this type will never influence the conversation.

Slot Auto-fill#

The slot will be set automatically if your NLU model picks up an entity, and your domain contains a slot with the same name, provided the following conditions are met:

1. store_entities_as_slots is set to true
2. the slot's auto_fill property is set to true

For example:

In this case, you don't have to include the slot_was_set part in the story, because it is automatically picked up:

To disable auto-filling for a particular slot, you can set the auto_fill attribute to false in the domain file:

Initial slot values#

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

Responses#

Responses are actions that send a message to a user without running any custom code or returning events. These responses can be defined directly in the domain file under the responses key and can include rich content such as buttons and attachments. For more information on responses and how to define them, see Responses.

Forms#

Forms are a special type of action meant to help your assistant collect information from a user. Define forms under the forms key in your domain file. For more information on form and how to define them, see Forms.

Actions#

Actions are the things your bot can actually 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, except responses which need not be listed under actions: as they are already listed under responses:.

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).

Config#

The config key in the domain file maintains the store_entities_as_slots parameter. When an entity is recognized by the NLU model and the entity name matches a slot name, store_entities_as_slots defines whether the entity value should be placed in that slot. By default, entities will auto-fill slots of the same name.

You can turn off all slot auto-filling by setting the store_entities_as_slots parameter to false:

You can also turn off this behavior for a specific slot using the auto_fill parameter in that slot's definition.