Knowledge Base Actions

This feature is experimental. We introduce experimental features to get feedback from our community, so we encourage you to try it out! However, the functionality might be changed or removed in the future. If you have feedback (positive or negative) please share it with us on the forum.

Using `ActionQueryKnowledgeBase`

Create a Knowledge Base

The data used to answer the user’s requests will be stored in a knowledge base. A knowledge base can be used to store complex data structures. We suggest you get started by using the InMemoryKnowledgeBase. Once you want to start working with a large amount of data, you can switch to a custom knowledge base (see Creating Your Own Knowledge Base).

To initialize an InMemoryKnowledgeBase, you need to provide the data in a json file. The following example contains data about restaurants and hotels.

{
    "restaurant": [
        {
            "id": 0,
            "name": "Donath",
            "cuisine": "Italian",
            "outside-seating": true,
            "price-range": "mid-range"
        },
        {
            "id": 1,
            "name": "Berlin Burrito Company",
            "cuisine": "Mexican",
            "outside-seating": false,
            "price-range": "cheap"
        },
        {
            "id": 2,
            "name": "I due forni",
            "cuisine": "Italian",
            "outside-seating": true,
            "price-range": "mid-range"
        }
    ],
    "hotel": [
        {
            "id": 0,
            "name": "Hilton",
            "price-range": "expensive",
            "breakfast-included": true,
            "city": "Berlin",
            "free-wifi": true,
            "star-rating": 5,
            "swimming-pool": true
        },
        {
            "id": 1,
            "name": "Hilton",
            "price-range": "expensive",
            "breakfast-included": true,
            "city": "Frankfurt am Main",
            "free-wifi": true,
            "star-rating": 4,
            "swimming-pool": false
        },
        {
            "id": 2,
            "name": "B&B",
            "price-range": "mid-range",
            "breakfast-included": false,
            "city": "Berlin",
            "free-wifi": false,
            "star-rating": 1,
            "swimming-pool": false
        }
    ]
}

Once the data is defined in a json file, called, for example, data.json, you will be able use the this data file to create your InMemoryKnowledgeBase, which will be passed to the action that queries the knowledge base.

Every object in your knowledge base should have at least the "name" and "id" fields to use the default implementation. If it doesn’t, you’ll have to customize your InMemoryKnowledgeBase.

Define the NLU Data

In this section:

we will introduce a new intent, query_knowledge_base
we will to annotate mention entities so that our model detects indirect mentions of objects like “the first one”
we will use synonyms extensively

For the bot to understand that the user wants to retrieve information from the knowledge base, you need to define a new intent. We will call it query_knowledge_base.

We can split requests that ActionQueryKnowledgeBase can handle into two categories:

the user wants to obtain a list of objects of a specific type, or
the user wants to know about a certain attribute of an object. The intent should contain lots of variations of both of these requests:

## intent:query_knowledge_base
- what [restaurants](object_type:restaurant) can you recommend?
- list some [restaurants](object_type:restaurant)
- can you name some [restaurants](object_type:restaurant) please?
- can you show me some [restaurant](object_type:restaurant) options
- list [German](cuisine) [restaurants](object_type:restaurant)
- do you have any [mexican](cuisine) [restaurants](object_type:restaurant)?
- do you know the [price range](attribute:price-range) of [that one](mention)?
- what [cuisine](attribute) is [it](mention)?
- do you know what [cuisine](attribute) the [last one](mention:LAST) has?
- does the [first one](mention:1) have [outside seating](attribute:outside-seating)?
- what is the [price range](attribute:price-range) of [Berlin Burrito Company](restaurant)?
- what about [I due forni](restaurant)?
- can you tell me the [price range](attribute) of [that restaurant](mention)?
- what [cuisine](attribute) do [they](mention) have?

The above example just shows examples related to the restaurant domain. You should add examples for every object type that exists in your knowledge base to the same query_knowledge_base intent.

In addition to adding a variety of training examples for each query type, you need to specify the and annotate the following entities in your training examples:

object_type: Whenever a training example references a specific object type from your knowledge base, the object type should be marked as an entity. Use synonyms to map e.g. restaurants to restaurant, the correct object type listed as a key in the knowledge base.
mention: If the user refers to an object via “the first one”, “that one”, or “it”, you should mark those terms as mention. We also use synonyms to map some of the mentions to symbols. You can learn about that in resolving mentions.
attribute: All attribute names defined in your knowledge base should be identified as attribute in the NLU data. Again, use synonyms to map variations of an attribute name to the one used in the knowledge base.

Remember to add those entities to your domain file (as entities and slots):

entities:
  - object_type
  - mention
  - attribute

slots:
  object_type:
    type: unfeaturized
  mention:
    type: unfeaturized
  attribute:
    type: unfeaturized

Create an Action to Query your Knowledge Base

To create your own knowledge base action, you need to inherit ActionQueryKnowledgeBase and pass the knowledge base to the constructor of ActionQueryKnowledgeBase.

class MyKnowledgeBaseAction(ActionQueryKnowledgeBase):
    def __init__(self):
        knowledge_base = InMemoryKnowledgeBase("data.json")
        super().__init__(knowledge_base)

Whenever you create an ActionQueryKnowledgeBase, you need to pass a KnowledgeBase to the constructor. It can be either an InMemoryKnowledgeBase or your own implementation of a KnowledgeBase (see Creating Your Own Knowledge Base). You can only pull information from one knowledge base, as the usage of multiple knowledge bases at the same time is not supported.

This is the entirety of the code for this action! The name of the action is action_query_knowledge_base. Don’t forget to add it to your domain file:

actions:
- action_query_knowledge_base

Note If you overwrite the default action name action_query_knowledge_base, you need to add the following three unfeaturized slots to your domain file: knowledge_base_objects, knowledge_base_last_object, and knowledge_base_last_object_type. The slots are used internally by ActionQueryKnowledgeBase. If you keep the default action name, those slots will be automatically added for you.

You also need to make sure to add a story to your stories file that includes the intent query_knowledge_base and the action action_query_knowledge_base. For example:

## Happy Path
* greet
  - utter_greet
* query_knowledge_base
  - action_query_knowledge_base
* goodbye
  - utter_goodbye

The last thing you need to do is to define the response utter_ask_rephrase in your domain file. If the action doesn’t know how to handle the user’s request, it will use this response to ask the user to rephrase. For example, add the following responses to your domain file:

utter_ask_rephrase:
- text: "Sorry, I'm not sure I understand. Could you rephrase it?"
- text: "Could you please rephrase your message? I didn't quite get that."

After adding all the relevant pieces, the action is now able to query the knowledge base.

Knowledge Base Actions

Using ActionQueryKnowledgeBase

Create a Knowledge Base

Define the NLU Data

Create an Action to Query your Knowledge Base

Using `ActionQueryKnowledgeBase`