Skip to main content

Matching

When an input is received by a solution, the initial input processing occurs. This is followed by Matching, where the input is tested against the in-scope transitions and triggers to decide what the end user is trying to achieve.

On this page, we discuss specifically how to control the matching of an input using triggers and transitions - and how the different options will appear for an end user communicating with the solution.

The sections on this page provide information about the various aspects of Matching:

Concept​

note

The complete processing cycle within Teneo is described in details in the page From Request to Response, in this section we will focus only on the Matching.

Each input from the user needs to be understood by the system so the solution can act on behalf of/respond to the user correctly. Matching is part of this process where the system understands the user's intention and decides which path to follow.

In practice, this means that the system uses matching to:

  1. Understand the input/user's intent (NLU*) - Hybrid matching
  2. Account for position within the dialogue (Context) - triggers vs transitions

This means that Matching determines the path the end-user takes, whether a new Flow is triggered or an existing Flow is continued, which technology is involved in the processing, etc. So, the Matching process controls which action should be taken to resolve the given input at a particular point in a dialogue. This is therefore critical for a solution to function correctly.

note

* Natural Language Understanding (NLU) focuses on enabling machines to understand the meaning, context, and intent of human language.

Triggers vs Transitions​

Triggers and transitions essentially do the same job; they control whether a given input matches a path in the dialogue. However, their usage is different and depends entirely on dialogue context:

  • A trigger controls when a new task (or Flow) begins;
  • A transition controls whether an existing task should continue.

The system will always try to continue a process if possible. However, if the user's intent cannot be fulfilled by the active Flow, it is always possible to trigger a new Flow and return to the previous process afterwards.

When an input is received...​

If this is the first input from this user or there are no active Flows:

  • In this case only triggers are tested.
    This allows the user to tell the solution what they are trying to achieve and the system to launch a Flow to handle that use case.

If the user has already started a conversation with the solution and they are working towards an outcome, then there will be an active Flow.

  1. In this case, the next transitions in the active Flow will be tested first.
    This allows the user to continue that process if that is their intention.
  2. If the input does not match any of these in-scope transitions, then triggers will be tested.
    This allows the user to interrupt the current process.

Choose a Match​

Choosing a Match or the combination of various Matches always depends on the particular use case and the dialogue requirements. The following sub-section provides an overview of the available Match types.

Match Types​

The following Match types are available in Teneo Studio:

  • Gen AI
  • Class
  • TLML Syntax
  • Entity
  • Language Object
  • Script
  • Scripted Context
  • Flow Variable
  • Global Variable
Gen AI​

A Gen AI Match matches when a value returned by a Gen AI Annotator matches the input. A Gen AI Annotator annotates input based on a prompt and acts as a bridge between the raw user input and labelled data within a solution. This labelled data can then be specified as a match value in the Gen AI Match.

Class Match​

A Class Match matches when the Class specified in the Match has the highest confidence for that input. The Class with the highest confidence is annotated as the TOP_INTENT. Since Teneo Predict selects a single TOP_INTENT Class for each presented input, only one Class Match can be defined per trigger/transition. To define the Class, in the Class Match element, simply write the name of the Class which should be used to match.

tip

A Class Match is usually a good go-to option for triggers when first creating a Flow, mostly because after providing a number of training data examples the machine learning model is automatically trained and works out-of-the-box. When a Class is performing as intended, the Flow it is used in will be triggered correctly and often nothing more is needed for the matching.

In Teneo Studio Desktop, when writing the name of a nonexistent Class, it is possible to press Ctrl + double-click to open the Class Manager and create the new Class with the specified name.

Note that positive examples of User Intent on a trigger or transition that uses a Class as a Class Match are used as Linked Test Examples by the solution's intent classifier.

A Class can be improved using the Classifier or by adding training data examples in the Class Manager.

tip

Is the Class over-triggering? Then take a look at the Hybrid Matches section.

TLML Syntax​

The TLML Syntax Match satisfies inputs based on a syntactic condition, manually written with Teneo Linguistic Modeling Language (TLML) in the Syntax editor.

In Teneo Studio Desktop, just below the Syntax editor, the Advanced Options provide the following two options:

  • "Limit unused words to" allows to limit the number of unused words present in the user input by specifying a maximum number of words which the user input may contain besides those matching the TLML syntax for the match to be satisfied; see Unused Word Limitation
  • Use Draft to have Teneo draw up a TLML Syntax based on the User Intent examples in the trigger/transition, the drafted syntax can afterwards manually be adapted and/or expanded as needed and provides a starting point for TLML syntax writing; learn more.

When the syntax of a TLML Syntax Match is very precise and it only matches on very specific inputs, the trigger where the Match is defined should be added in an order group in the top of the Ordering. This way the precise trigger is tested before a broader trigger and if it matches, the precise trigger will then be selected for triggering. Alternatively, if the trigger is broad, it should be added lower in the Ordering to allow the testing of more precise triggers first. This way, the broad TLML Syntax trigger will not inadvertently catch inputs that could have been caught by a more precise trigger.

More information on ordering can be found here.

note

To change the behavior of a trigger with a TLML Syntax Match, modify its language syntax.

Entity​

An Entity Match matches when the selected Entity is present in the user input; to define the Entity, in the Match Entity element simply write the name of the desired Entity. Available Entities can be found by writing the first few letters of the name and pressing Ctrl + space.

In Teneo Studio Desktop, when writing the name of a nonexistent Entity, pressing Ctrl while double-clicking allows for the creation of an Entity with the specified name.

Learn more about Entities here.

Language Object​

The Language Object Match is satisfied if the syntax of the selected Language Object matches the user input; to define the Language Object, in the Match Language Object element simply write the name of the desired Language Object. Available Language Objects can be found by writing the first few letters of the name and pressing Ctrl + space.

In Teneo Studio Desktop, when writing the name of a nonexistent Language Object, pressing Ctrl while double-clicking allows for the creation of a Language Object with the specified name.

Learn more about Language Objects here.

Script​

A Script Match matches if the script returns a value that can be interpreted as a True Boolean value; in Teneo Studio, scripts are written in Groovy.

Script Matches are the slowest among the Match requirements (at evaluation time), so users are encouraged to use them late in the Match chain; in this way, the execution of a Script Match is prevented if another Match in the same trigger doesn't match, given that all Match requirements in one trigger must match for the trigger itself to be matched.

To define a script, in the Match Script element, simply write the evaluation script (in Groovy).

Scripted Context​

A Scripted Context matches whenever the evaluated Scripted Context is one of the selected states; it is possible to add more than one Scripted Context Match to the same trigger/transition.

By default, when adding a Scripted Context Match in Teneo Studio Desktop, the Context will be assigned with the first expected state available. If the Context has several expected states, the user should choose which to test against by clicking the pencil icon below States and selecting/deselecting the desired expected states.

Learn more about Global Scripted Contexts here.

Flow Variable​

A Flow Variable matches whenever the value of the selected Flow Variable matches the return value of the expression (evaluation script) in the Match.

Read more about Flow Variables here.

Global Variable​

A Global Variable matches whenever the value of the selected Global Variable matches the return value of the expression (evaluation script) in the Match.

Learn more about Global Variables here.

Hybrid Matches​

note

In this section triggers and transitions can be considered the same, so we will use the term trigger only. It is safe to assume that anything said about triggers is also true for transitions (unless stated otherwise).

Whether a trigger matches depends on a number of criteria applied to that trigger. As described under match types, there are a number of different types of Match criteria that can be applied: for example, TLML (for precisely controlled rule based matching), Class (for broader intent classification), and Scripting (for anything Groovy supports).

These criteria can be applied in (almost) any combination creating truly hybrid Matching options, allowing the most appropriate technology to be used for each criteria and combining them.

A Match can be seen as a simple true or false condition - each criteria either does or does not match. This makes defining each individual Match a simple atomic task while allowing the flexibility and complexity required for some solution scenarios to be applied by combining these simple building blocks.

  • Matches are tested in the order they are defined on the trigger.
  • All must match for the trigger to match.

A trigger can be seen as a combination of all the individual Match criteria in almost any combination:

  • A trigger may have many different Match types:
    • For example, a Class Match with a TLML Match added to provide more precision.
    • PRODUCT_ORDER (Class) and %PRODUCT_CODE (TLML): only launch the order process if there is a known product.
  • Multiple triggers may have the same individual Match type:
    • For example, the same Class Match could be used on multiple triggers - in combination with different TLML Matches.
    • BOOK_A_FLIGHT (Class) and INTERNATIONAL_AIRPORT (Language Object) - launch the international flight booking Flow.
    • BOOK_A_FLIGHT (Class) and DOMESTIC_AIRPORT (Language Object) - launch the domestic flight booking Flow.
  • The same Match type can be applied multiple times on a single trigger:
    • For example, 2 Entity Matches for different Entities on the same trigger - meaning BOTH Entities must be found in the input.
    • COUNTRY (Entity) and CITY (Entity) - only continue to get directions if both country and city are included in the input.
    • The exception is Classes - because it is impossible for two Classes to both be the TOP intent(link to class management/classifying).
TIP TODO

It is perfectly valid to not assign any Matches to a trigger. This then means that the trigger is considered to be in a "TODO" state, meaning that its existence and purpose has been defined - but it has not yet been implemented, so it will not affect the functionality of the solution.

TIP COST

When a Match is tested but does not match, the remaining untested Matches for that trigger will not be tested.

For this reason, it is recommended to put any expensive (either financial, resources or latency) Matches, such as a Gen AI match, at the end to ensure that they are only tested when needed.

Matching Order​

When testing to find the correct path to continue the dialogue, the system will test the in-scope transitions and triggers in a defined order. This order is controlled by a few different features of a solution:

  • Dialogue Context defines whether any transitions are in scope, i.e., whether there is an active Flow.
  • Transition Order defines the order in which the transitions should be tested. This is an absolute order and can be seen in the Flow graph as transitions being tested left-to-right.
  • Trigger Order defines the relationship between the matching criteria of different triggers, and is used by Engine at runtime to calculate which trigger should match. These relationships are defined using order groups and trigger relations(add link to trigger ordering).

These different orders are applied broadly as follows when an input is received:

  1. If there is an active Flow, then the transitions leaving the current node will be in scope - these transitions are tested first.
    • The in-scope transitions are tested in transition order (left to right on the Flow graph).
    • If a transition matches then this transition is triggered.
    • No more transitions (or triggers) will be tested.
  2. If there are no active Flow (or none of the in scope transitions matched), then triggers are tested.
    • The triggers are tested group by group - in the order defined in the solution.
    • All triggers in a group are analyzed for matching.
    • If there are any Matches, then the trigger with no matching-related triggers before it is chosen to be triggered.
    • If there are no Matches, then the triggers in the next group are tested.
NO MATCH

If nothing matches the user's input - either in-scope transitions nor any of the triggers - then no action will be taken by the solution to handle this input.

This will result in an empty response to the user.

Thus, it is recommended to have some safety net functionality to handle these cases - see more at the safetynet section for information on how to ensure there is always a response of some kind from the solution.

How To​

Add a Match​

Add a Match from the Flow graph

To add a new Match from the Flow editor:

  1. In the Flow editor, below the User Intent node (either in the trigger or transition), click the Plus icon.

  2. Under Match select one of the following options:

    • match when a value returned by the Gen AI Annotator matches the input

    • match when a given Class is predicted

    • match when a TLML Syntax rule matches the input

    • match when an Entity is recognised in the input

    • match when a Language Object matches the input

    • match when a script returns true

    • match when a Scripted Context state is active

    • match when a Flow Variable matches a given script

    • match when a Global Variable matches a given script

  3. In the right-side panel under Match, define the specifics for the selected Match type.

Add a Match in the right-side panel

To add a new Match from the right-side panel:

  1. In the Flow editor, first select the trigger/transition to open the Trigger or Transition panel.
  2. In the Match section of the panel, click Add and select the wanted Match type.
  3. Next, define the specifics for the selected Match type.
info

New Matches are inserted at the top of the list; a handle to drag/drop them into the desired order is available in the top-right corner of the Match box.

Edit a Match​

  1. Select the trigger/transition of the Match.
  2. In the right-side panel, simply click in the field of the Match to modify the details.

Delete a Match​

  1. Select the trigger/transition of the Match.
  2. In the right-side panel, click the cross (X) available in the top of the Match's field.

Generate a Match​

The option to Generate a draft implementation becomes available when positive examples (and, optionally, negative examples) of User Intent are added to a trigger or transition. This allows Teneo to generate a draft of the Match implementation based on the User Intent examples. You can also edit or remove the draft or even add further Matches.

With the Flow open, follow these steps to generate a draft of the Match implementation:

  1. Click the Plus icon following the User Intent either in a trigger or transition.

  2. Under Match, click Generate a draft implementation from the Intent examples.

    generate

  3. Alternatively, a draft implementation can be generated by selecting the trigger/transition and clicking Generate in the right-side panel (Match section)

    generate 2

  4. A Generating... message is displayed in the Match section until the draft is ready. You can then edit the implementation or add more Matches if necessary.

UI​

Plus Icons​

Plus IconsDescriptionRelated Pages
desktop plus iconThe Plus icon below the trigger node allows to define Matches for the selected triggerTriggers
desktop plus icon transitionPlus icons throughout the Flow graph allows to define Matches for the selected transitionTransitions

Matches​

VisualizationDescriptionRelated Pages
GenerateGenerate an implementation of the Match requirement based on the User Intent examples, the drafted implementation can of course be edited afterwards. Option only available when examples are added and the Tryout engine is running.User Intent
gen ai match
gen ai match panel		Allows to match user inputs based on their annotations. The Annotations are given by an Annotator, which uses a Large Language Model (LLM) and a prompt defined by the developer.Annotators
Annotations
Class Match desktop node class matchAllows to match user inputs using an Intent Classifier; to define the Class, in the text field, simply write the name of the Class.Class Matches
Class Manager
Intent Classification
TLML Syntax Match desktop node tlml matchWrite a TLML Syntax in the editor and match user inputs against the syntax.TLML Syntax Match
TLML Manual
Syntax Editor
Entity Match desktop node entity matchMatch user inputs against an Entity; the Entity Match matches when the selected Entity is present in the user inputEntity Match
Entities
Language Object Match desktop node lob matchMake use of a Language Object to match user inputs against it; a Language Object Match is satisfied when the syntax of the selected Language Object matches the user input.Language Object Match
Language Objects
Script Match desktop node script matchAdd a Script Match to be able to match on a Groovy script; the Script Match matches when the script returns a value that can be interpreted as a True Boolean value.Script Match
Scripting
Scripted Context Match desktop node scripted context matchDefine a Scripted Context Match by selecting the wanted Context and defining the wanted state(s), note that the first expected state is assigned by default and that it is also possible to add more than one Scripted Context to the same trigger/transition. A Scripted Context Match matches whenever the evaluated Scripted Context is one of the selected states.Global Scripted Contexts
Scripted Context match
Flow Variable Match desktop node flow variable matchAdd a Flow Variable Match to be able to match whenever the value of the selected Flow Variable matches the return value of the defined expression (evaluation script) in the Match.Flow Variables
Flow Variable match
Global Variable Match desktop node global variable matchMatch user inputs against a Global Variable, the Global Variable Match matches whenever the value of the selected Global Variable matches the return value of the expression (evaluation script) in the Match.Global Variables
Global Variable match

Practical Examples​

Hybrid Match: Class Match and TLML Syntax Match​

In this section, let's look at practical example from a coffee shop. The bot currently answers questions related to all the available coffee types, but due to the way the dialogue is designed, all user inputs containing any type of beverage are now matched by the same coffee Flow. The idea is to create a specific answer for any beverage type which is not coffee, in order to hopefully bring the end-users' attention back to the coffees.

Now, multiple Matches can be applied to triggers and transitions in any configuration, and one common hybrid approach is the combination of a Class Match and a TLML Syntax Match. While machine-learned Classes are able to cover a wide variety of user inputs based on training data, the TLML Syntax allows to make the triggers more selective and precise in the matching. Hence, in cases where the Class Match might be too greedy, a TLML Syntax Match can be added for higher degree of precision.

Now, in our coffee shop solution, the before-mentioned Flow about coffee currently has a Class Match in the trigger.

class match

This trigger, for example, covers inputs like the below but also inputs mentioning other beverage types:

EXAMPLE

User: Which coffees do you serve?

Bot: We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.

Now, as the coffee shop exclusively serves coffee drinks, they want to make sure that inputs mentioning other beverage types are handled separately; first of all, to be able to bring the end-users' attention back to the coffees offered, but also to easier track which beverages are requested, so that they can later decide on whether or not their assortment should be expanded with the requested beverage types.

By adding a second Match to the trigger (where the above Class Match is implemented), the inputs matching on the Class can be limited. In this particular use case, a TLML Syntax Match with the following syntax is suggested, as it allows to limit the Class Match to only trigger when the words coffee, drink or a particular coffee type is mentioned:

(%COFFEE.NN.SYN/%DRINK.NN.LEX)
class and tlml hybrid match

This example for TLML Syntax ensures that a Match only occurs if part of the input matches either of the two Language Objects COFFEE.NN.SYN or DRINK.NN.LEX. This also means that the Class Match is still used, but it is restricted by the TLML Syntax Match to ensure the desired behavior and that the above Flow is not triggered when the user asks about tea or another beverage type other than coffee. For these cases, it is now up to the team to create, for example, a specific Flow which recognizes all other beverage types and results in a dialogue similar to the below:

Example

User: Which teas do you serve?

Bot: I'm sorry, we do not serve teas. We offer a variety of handcrafted coffee drinks - from espressos to macchiatos to flat whites and more.

This will allow the team to easily analyze log data related to new beverage types and more importantly it brings the end-user's attention back to the coffee.

Hybrid Match: Class Match and Context Match​

Another practical example of hybrid matching is when one or more Context Match requirements limit the matched user inputs based on the Class Confidence score.

In the Teneo Dialogue Resources examples of this kind of hybrid matching are found in several Flows, for instance, "The user wants to know how intelligent the bot is" from where the following image is.

Here the Class TDR_HOW_INTELLIGENT_ARE_YOU is restricted by the addition of the Context Match Multi-Word Input to ensure that the user input contains at least 2 words (or more) defined by the context state. On top of that, the Context Match Class Confidence Medium with the state 0.60 ensures that only inputs with a confidence score above 0.60 actually trigger the Flow.

class and context