Annotations

Annotations can be considered 'labels' that are attached to inputs. A word, word sequence, sentence, or full input can have multiple annotations that you can use in your language conditions. In most cases machine learned models are used for annotations, like Named Entity Recognizers (NER) or Classifiers. Teneo adds various such annotations out of the box. Just like language objects, annotations are building blocks for language conditions.

The main components of an annotation are:

• its name
• its (optional) annotation variables

The name reflects what is annotated. The annotation variables can contain extra information related to the annotation. For example, an annotation USER_ASKS_ABOUT_OPENING_HOURS.TOP_INTENT may have a variable containing the confidence score. Annotation variables can be retrieved in the same way as entity variables.

Predefined annotations

Teneo provides various annotations out of the box. The main types of annotations are Named Entities (NER), Part of Speech (POS), and Language (LANG). An input like 'Teneo's a product from Artificial Solutions' is annotated as follows:

A full list of all annotations can be found in the Annotations Reference.

Class annotations

In addition to the predefined annotations, Teneo can add annotations for Class Match Requirements. When Teneo receives an input, the class trigger with the highest confidence score will be annotated as the top intent, for example: WHERE_DO_YOU_HAVE_STORES.TOP_INTENT. For classes that have a confidence score that is close to the top intent, additional annotations can be added, like DO_YOU_HAVE_A_STORE_IN_CITY.INTENT.

When a class match requirement is generated in a flow, a class label is automatically created for that trigger. But you can also specify it yourself in the Class Manager window.

How to use annotations

You use annotations the same way as you use language objects in a condition. It's just the prefix that looks slightly different. Instead of %, you add %$ before the name. Like this: %$LOCATION.NER. The following is an example of a condition using both a language object and an annotation:

Inspecting annotations in Tryout

If you want to see how an input is annotated, enter the input in Tryout and open the 'Advanced' window.. You will find all annotations in the Input section under 'Annotations'. Hovering over an annotation will display additional information that is stored in annotation variables.

Creating annotations

While the predefined and class annotations will suffice in most cases, you're not limited to just those. With a bit of script code, you can add your own annotation as well. This can for example be useful if you want to annotate inputs using regular expressions, which can be useful for annotating patterns like, for example, postal codes.

Annotations can be added in two places in Teneo — in Global listeners and Pre-matching global scripts. To add one, you need to use the Teneo Engine Backend API. The following two methods should be called to add an annotation (in Teneo an underscore is used as an alias for the Teneo Engine):

1_.inputAnnotations.add(_.createInputAnnotation(String annotation_name, int sentence_index, Set<Integer> words_indices, Map<String, Object> annotation_variables))
2

The createInputAnnotation method expects 4 arguments:

• annotation_name: the name that you will use in language conditions later. The word will be annotated with this name and it's good practice to uppercase the name of the annotation.
• sentence_index: the index of the sentence that you want to annotate.
• words_indices: the indices of the word(s) this annotation is assigned to (the first word has index 0, the set may be empty)
• annotation_variables: variables you may want to add to the annotation, e.g. a confidence level. The annotation variables are provided as a map, the key is a string with the name of the annotation variable, and the value is an object. If you don't want to provide annotation variables, use 'null' instead.

Suppose you would like to annotate the words 'hunky dory' as 'MOOD' in the sentence 'I feel hunky dory'. And you also want to add an annotation variable 'feeling' with the value 'good' to the annotation. The code for this would look as follows:

1_.inputAnnotations.add(_.createInputAnnotation("MOOD", 0, [2,3] as Set, ["feeling":"good"]))
2

The result in the Input section in Tryout would look like this:

You can find a practical example of a script used to add annotations in the Scripting section: How to annotate user inputs.