System and custom entities

An entity is a CAILA NLU unit. It represents a sequence of words linked by intent or rule. For example, names, date and time, location, etc.

CAILA offers the following to the developer:

System entities — built-in entities that the developer can activate in the entity editor.
My entities — entities that the developer enters and constructs in the entity editor.

More about the entity editor

Using entities

Directly

All entities found in a phrase will be available in the script via the $jsapi.context().entities or $entities variable.

For example:

state:
    q!: Information about product *
    a: Information about product: {{ $entities[0].value }}

In intents

Entities can be used in intents.

More details about filling in slots in intents and the Slot filling process

When the intent is activated, the data of the respective slot will be written to the variable $parseTree._<slot name>.

The initial text for which a match has been found will be written to this variable; alternatively, the DATA specified for this entity in the entity editor will be written to this variable.

For example:

state:
    intent: /bye
    a: Action: {{ $parseTree._Action }}, Product: {{ $parseTree._Product }}

state:
    intent: /sell
    a: Action: {{ $parseTree._Action }}, Product: {{ $parseTree._Product }}

In patterns

You can use entities in patterns by referencing them as @<entity name> or @<entity name>::<slot name>.

For an entity specified in a pattern, a slot is created automatically and the entity is included in the $parseTree.

The value of the entity will be available in the script as $parseTree._<slot name>.

For example:

state:
    q!: * @Product::p1 *
    a: Information about product: {{ $parseTree._p1 }}

You can also use converters in entities. First, you need to define an entity through a named pattern using the patterns tag, and then declare a converter in it. For example:

patterns:
    $four = @four || converter = function() {return 4}

In this example, we created the @four entity, in which we declared converter. The converter function returns 4.

In entities

In JAICP entities can refer to other entities.

Let’s have a look at entities behavior when:

filling the Value field;
filling the Data field.

Filling the Value field

Let’s have a look at how the client’s address fills in the entities. The address consists of two parts: street and house number.

Go to the CAILA > Entities > My entities tab on the control panel. Create the following entities:

street_name with patterns:

Main
West

street with a pattern:

@street_name street

Now let’s create an address entity. It refers to the street entity and the @duckling.number system entity:

@street @duckling.number

Now let’s say the client enters the message Main Street. The Value field is filled in the following way:

Main in the street_name entity;
Main street in the street entity.

If the client enters the message Main Street 15, then Value fills in as follows:

Main in the street_name entity;
Main street in the street entity;
Main Street 15 in the address entity.

Filling the Data field

Let’s say we have our own online store that sells groceries. We will use the entities to specify from the client’s request what kind of fruits and vegetables they want to buy.

Go to the CAILA > Entities > My entities tab on the control panel. Create the following entities:

fruit with patterns:

apple
banana
lime

vegetable with patterns:

potato
tomato
cucumber

In addition, specify values name and type in the DATA field for each pattern that will correspond to the name and type of the product. In the DATA field, you can add any information in JSON format that may be needed in the script.

For example, for the pattern banana specify:

{
    "name": "banana",
    "type": "fruit"
}

Do the same for each pattern of the vegetable entity. For instance:

{
    "name": "potato",
    "type": "vegetable"
}

Now, let’s combine these entities into the grocery entity. Create an entity grocery and specify the @vegetable and @fruit patterns in the Dictionary field.

Entity grocery

Let’s look at the script. The client sends a message containing information about the product they want. The bot’s reply will consist of two messages: the name and type of this product.

state: Start
    q!: $regex</start>
    a: Hello! Our store offers a wide range of vegetables and fruit. What would you like to order?

    state: Grocery
        q!: * @grocery *
        script:
            $reactions.answer("The product name: {{ $parseTree._grocery.name }}");
            $reactions.answer("The product type: {{ $parseTree._grocery.type }}");

For example, the client writes the message Potato. The DATA field of the grocery entity will be filled with the information specified in the DATA field of the vegetable entity. Because the entity grocery contains the entity vegetable the message will be recognized by both these entities. As a result, the bot will send the following:

The product name: potato
The product type: vegetable