Zoom intent

Intent

All Diatheke models must have a directory called “intents”. Under the intents directory, each user intent that Diatheke can detect is defined in a separate file where the file name must be the same as the intent. For example, the zoom intent should be defined in a file called zoom_intent.yaml under the intents directory.

An intent file specifies example utterances, that is, different ways to express the user’s intention.

For example, zoom_intent.yaml defines different phrases a user might say to zoom in on a picture:

language_data:
  en_US:
    example_utterances:
      - Zoom
      - Enhance

The example utterances can go beyond having a simple list of example utterances and include slots for different entities. An expanded yaml file for the zoom intent is shown below.

In this second example, we have utterances such as “Zoom ${zoom_amount}” where zoom amount is an entity that should be specified by the user. For example, if the user says “Zoom 50 percent”, then the entity zoom_amount is set to “50 percent”.

language_data:
  en_US:
    example_utterances:
      - Zoom
      - Enhance
      - Enhance ${zoom_amount}
      - Zoom ${zoom_direction}
      - Zoom ${zoom_amount}
      - Zoom ${zoom_direction} ${zoom_amount}

Entities

The slots in the intent definition file show how entities are used, but how are they defined? Each Diatheke model folder has a subfolder called “entities”. Each entity is defined in a separate file under that folder with the same name as the entity. For example, the zoom_direction entity is defined in a zoom_direction.yaml file as shown below. In this case, zoom_direction entity is simply a list of possible zoom directions which are “in” and “out”.

format: value_list

language_data:
  en_US:
    values:
      - in
      - out

Sometimes, it is not feasible or practical to list all possible entity phrases. To address those cases, Diatheke allows using regular expressions in entity definition files. In our zoom example, it would be tedious to enumerate all possible percentages, so we define a regular expression allowing the value to be either 100 or any one- or two-digit number, optionally followed by either the word “percent” or “times”.

format: regular_expression

language_data:
  en_US:
    expression: (100|[0-9]{1,2})( percent| times)?

Examples

Putting it altogether, Diatheke would recognize the following intent and entities for the following example utterances:

The main story designates zoom_story.yaml as what Diatheke should do in response to the zoom intent, so we’ll look at that next.