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 or Classifiers. Teneo adds various of 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 'Taylor Swift performed in New York' is annotated as follows:

Taylor Swift performed in New York
KNOWN_FIGURE.NER LOCATION.NER
NN.POS
SG.POS
PROPER.POS
NN.POS
SG.POS
PROPER.POS
VB.POS
PAST.POS
PARTICIPLE.POS
PREP.POS NN.POS
SG.POS
PROPER.POS
NN.POS
SG.POS
PROPER.POS
EN.LANG

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 triggers. 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.

You can use these annotations in language conditions to create hybrid triggers, allowing you to constrain a class with some conditional part.

When a class trigger is added to a solution, a class label is automatically generated for that trigger. But you can also specify it yourself in the 'Learning examples' panel for the class trigger.

Setting class name

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:

Example of a condition that uses an NER

Inspecting annotations in Try out

If you want to see how an input is annotated, enter the input in 'Try out' and open the 'Response Info' tab. You will find all annotations in the 'Input Summary' section (you may need to uncollapse it). Hovering over an annotation will display additional information that is stored in annotation variables.

Annotations in tryout

Creating annotations

While the pre-defined and class annotations in most cases will suffice, 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, to annotate patterns like 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):

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

The createInputAnnotation method expects 4 arguments:

  • annotation_name: the name that you will use in language conditions later. It's good practice to uppercase the name of the annotation.
  • sentence_index: index of the sentence that you want to annotate
  • words_indices: 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, for example 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:

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

The result in the Response info panel would look like this:

Annotation example in response info panel

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

Was this page helpful?