Imports and lookups

Imports are an advanced SAL feature that enables you to define long lists outside the SAL syntax. The lookup entity type allows you to define a normalized return value for entities that have several synonyms.

Imports

The imports feature enables you to define lists outside the SAL configuration, and load them to variables that you can use as part of your SAL templates.

Normally, a list is assigned to a variable in SAL as follows:

fruit = [apple | orange | blood orange | banana | lemon | apricot | peach | pineapple]

However, if your list contains hundreds of items, the above becomes cumbersome to write and maintain.

Using the import functionality, you can import the list from a CSV file. The CSV file must have the list items in one of its columns, and the file must be located in the same directory as your config.yaml file.

Gotcha

Speechly Dashboard doesn't yet support single column imports. However, creating and importing lookups is fully supported.

Example import

In the simplest case the CSV file to be imported contains only one column, with one list item per row.

1. Prepare a CSV file with a list of fruits:

fruits.csv

apple
orange
blood orange
banana
lemon
apricot
peach
pineapple

2. Import the list from fruits.csv and store it in a variable called fruit:

config.yaml

imports: 
  - name: fruit
    source: fruits.csv
    field: 1

Now, you can use $fruit in your templates, exactly as you would after having defined it in a SAL expression. The imported variable is like any other variable in SAL.

Multiple imports

You can specify as many imports as you like. If you had a similar list in another file called vegetables.csv, you can import both lists to their respective variables by defining:

config.yaml

imports: 
  - name: fruit
    source: fruits.csv
    field: 1
  - name: vegetable
    source: vegetables.csv
    field: 1

Import reference

Import reference

Lookups

The returned values of entities having entity data type lookup are normalized according to a simple lookup mechanism. This is useful for mapping synonyms to a normalized value, such as always returning the entity value "tv" even if the user said "television", "tv set", or "telly".

Example lookup

To define a lookup entity, you must specify an explicit mapping that provides for every synonym its normalized value that is returned by the API.

1. Prepare a CSV file with two columns, one of which contains a list of synonyms, and another that contains the normalized values:

devices.csv

light,light
lights,light
lamp,light
tv,tv
telly,tv
television,tv
radio,radio
stereo,radio

2. Import both columns of devices.csv into two variables using the imports property:

config.yaml

imports:
  - name: device_as_spoken
    source: devices.csv
    field: 1
  - name: device_normalized
    source: devices.csv
    field: 2

Now $device_as_spoken is a list that contains the first column of devices.csv, and $device_normalized contains the second column.

3. Define the entity to be of type lookup and reference the imported columns using input_items and output_items keys:

config.yaml

entities:
  - name: device
    type: lookup
    input_items: $device_as_spoken
    output_items: $device_normalized

Unlike other entity data types that are defined simply by specifying the name and type, the lookup entity type requires two additional parameters: input_items and output_items, which here are assigned the $device_as_spoken and $device_as_normalized lists.

4. When defining your SAL templates, you should only use $device_as_spoken, because remember that the example utterances you define must accurately reflect how your users talk:

templates: |
  *turn_on [turn | switch] on the $device_as_spoken(device)
  *turn_on [turn | switch] the $device_as_spoken(device) on

Now, when the user says "turn on the stereo", the returned device entity has the value radio.

Gotcha

Remember when using lookups that if the user says something that the entity detector can identify as a device, but the corresponding synonym is not present in the lookup mapping, the system returns verbatim the user's expression.

For example, if the user says "turn the music player on", the entity detector probably identifies "music player" as a device, but since "music player" is not defined in the lookup, the returned device entity would have the value music player.

Lookup reference

Lookup reference