notice

This is unreleased documentation for Rasa Open Source Documentation Master/Unreleased version.
For the latest released documentation, see the latest version (2.0.x).

Version: Master/Unreleased

Domain

The domain defines the universe in which your assistant operates. It specifies the intents, entities, slots, responses, forms, and actions your bot should know about. It also defines a configuration for conversation sessions.

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

version: "2.0"
intents:
- affirm
- deny
- greet
- thankyou
- goodbye
- search_concerts
- search_venues
- compare_reviews
- bot_challenge
- nlu_fallback
- how_to_get_started
entities:
- name
slots:
concerts:
type: list
influence_conversation: false
venues:
type: list
influence_conversation: false
likes_music:
type: bool
influence_conversation: true
responses:
utter_greet:
- text: "Hey there!"
utter_goodbye:
- text: "Goodbye :("
utter_default:
- text: "Sorry, I didn't get that, can you rephrase?"
utter_youarewelcome:
- text: "You're very welcome."
utter_iamabot:
- text: "I am a bot, powered by Rasa."
utter_get_started:
- text: "I can help you find concerts and venues. Do you like music?"
utter_awesome:
- text: "Awesome! You can ask me things like \"Find me some concerts\" or \"What's a good venue\""
actions:
- action_search_concerts
- action_search_venues
- action_show_concert_reviews
- action_show_venue_reviews
- action_set_music_preference
session_config:
session_expiration_time: 60 # value in minutes
carry_over_slots_to_new_session: true

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:

rasa train --domain path_to_domain_directory

Intents

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

Ignoring entities for certain intents

If you want all entities to be ignored for certain intents, you can add the use_entities: [] parameter to the intent in your domain file like this:

intents:
- greet:
use_entities: []

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

intents:
- greet:
use_entities:
- name
- first_name
ignore_entities:
- location
- age

This means that 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 this parameter, the entities will be featurized as normal.

note

If you really want these entities not to influence action prediction we suggest you set the influence_conversation: false parameter for slots with the same name.

Entities

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

For example:

entities:
- PERSON # entity extracted by SpacyEntityExtractor
- time # entity extracted by DucklingEntityExtractor
- membership_type # custom entity extracted by DIETClassifier
- priority # custom entity extracted by DIETClassifier

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:
slot_name:
type: text

Slots and Conversation Behavior

You can specify whether or not a slot influences the conversation with the property influence_conversation. If you want to store information but don't want a slot to influence the conversation, set the influence_conversation property of your slot to false. By default all slot types will influence the conversation except slots of the type any. Depending on the slot type, a slot with the influence_conversation property set to true will cause different behavior of your assistant.

For example, if your user should provide their home city, you might use a slot called home_city to store this information. If the user asks for the weather, and you don't know their home city, you will have to ask them for it. You could make home_city a text slot and set the influence_conversation property to true. 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.

slots:
# this slot will influence the conversation depending on
# whether the slot is set or not
home_city:
type: text
influence_conversation: true

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 during the conversation.

slots:
age:
type: text
# this slot will not influence the predictions
# of the dialogue policies
influence_conversation: false

Slot Types

Text Slot

  • Type

    text

  • Use For

    Storing text values.

  • Example

    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:

    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

    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 set to true or false. An empty bool slot is the same as if the slot was set to false.

Categorical Slot

  • Type

    categorical

  • Use For

    Storing slots which can take one of N values.

  • Example

    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

    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

    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.

Any Slot

  • Type

    any

  • Use For

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

  • Example

    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.

In the code below, we define a slot class called NumberOfPeopleSlot. The featurization defines how the value of this slot gets converted to a vector to our machine learning model can deal with. Our slot has three possible “values”, which we can represent with a vector of length 2.

(0,0)not yet set
(1,0)between 1 and 6
(0,1)more than 6
from rasa.shared.core.slots import Slot
class NumberOfPeopleSlot(Slot):
def feature_dimensionality(self):
return 2
def as_feature(self):
r = [0.0] * self.feature_dimensionality()
if self.value:
if self.value <= 6:
r[0] = 1.0
else:
r[1] = 1.0
return r

Now we also need some training stories, so that Rasa Core can learn from these how to handle the different situations:

stories:
- story: collecting table info
steps:
# ... other story steps
- intent: inform
entities:
- people: 3
- slot_was_set:
- people: 3
- action: action_book_table
- story: too many people at the table
steps:
# ... other story steps
- intent: inform
entities:
- people: 9
- slot_was_set:
- people: 9
- action: action_explain_table_limit

Unfeaturized Slot

deprecated

The slot type unfeaturized is deprecated. Please use the property influence_conversation as described here or the slot type any instead.

  • Type

    unfeaturized

  • Use For

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

  • Example

    slots:
    internal_user_id:
    type: unfeaturized
  • Description

    Slots of this type will never influence the conversation.

Slot Auto-fill

If your NLU model picks up an entity, and your domain contains a slot with the same name as the entity type, the slot will be set automatically with the entity value. For example:

stories:
- story: entity slot-filling
steps:
- intent: greet
entities:
- name: Ali
- slot_was_set:
- name: Ali

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 this behavior for a particular slot, you can set the auto_fill attribute to False in the domain file:

slots:
name:
type: text
auto_fill: False

Initial slot values

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

slots:
num_fallbacks:
type: float
initial_value: 0

Responses

Responses are actions that simply 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. 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:

session_config:
session_expiration_time: 60 # value in minutes, 0 means infinitely long
carry_over_slots_to_new_session: true # set to false to forget slots between sessions

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

note

A session start triggers the default action action_session_start. Its default implementation moves all existing slots into the new session. Note that all conversations begin with an action_session_start. Overriding this action could for instance be used to initialize the tracker with slots from an external API call, or to start the conversation with a bot message. The docs on Customizing the session start action shows you how to do that.

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:

domain.yml
config:
store_entities_as_slots: false

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

looking for config.yml?

If you're looking for information on the config.yml file, check out the docs on Model Configuration.