Teneo Developers

Table of Contents

Was this page helpful?

Share to

Condition reference manual

Introduction

This manual target conversational AI developers and users of the Teneo Platform.

The Teneo Engine uses conditions and operators written in the Teneo Linguistic Modelling Language to evaluate and process sentences. Here the syntax and the different conditions available in the Teneo Linguistic Modelling Language are described.

Basic concepts

Conditions

Very briefly, conditions describe word patterns the system needs to recognize in the sentence, in order to produce a match, which results in the system triggering a Flow, selecting a transition, etc. They can either be built using the NLU Generator or can be defined and written in Teneo Linguistic Modelling Language by the Platform users.

There are two types of conditions:

  • Atomic conditions, which can be used on their own, and
  • Compound conditions, which are formed by a combination of one or more conditions and an operator, which defines the relationship between said conditions.

In some of the examples used here, atomic conditions are expressed using letters (A B C) while operators are represented by different symbols (like + & >>). A compound condition would like like A & B, where A and B would be referred to as the operands.

Conditions are initially entered in the solution as text strings, which are parsed in Engine according to the Condition syntax; the result of the parsing is an Abstract Syntax tree (AST) structure that determines how the condition is evaluated (see the section Evaluating a condition). The condition functionality resides in the elements of the AST.

Parsing splits the condition text into parts, according to the condition semantics.

In general terms, conditions are not case-sensitive. See sectionExact option for further details on the exceptions.

Sentence & Word, Sentence Range and Range Start

Sentence & Word

Before the evaluation of conditions begins, the system pre-processes the user input and splits it into sentences and words by the Input Processors. Sentences are formed by one or more words (unless the user input is empty; then only one sentence exists that contain no words).

Words are made available in multiple forms although only two are relevant for the condition evaluation:

  • The raw form, which is the spelling of the word exactly as found in the evaluated sentence.
  • The final form, which is the spelling of the word after applying normalization and spelling corrections.

Conditions test the final form of a word. Exception: if Exact Option is being applied, then the raw form is tested.

In some of the examples here, words are expressed using letters; if a sentence contain the same word more than once it will be identified by a number (A B C1 C2).

Sentence Range

Conditions are matched against a whole sentence or, depending on many factors, a certain range of words from a sentence. The sentence words that are tested against a condition are known as the sentence range.

For instance, if having the sentence A B1 C B2 E but the evaluation of the sentence starts at C, then the sentence range would be C B2 E.

See the example below for further details.

Range Start

The index of the first word of the sentence range is the range start. I.e. the range start (RS) is a number that indicates the position of the word in the sentence where the condition needs to start being (or continue to be) tested.

The range start works as follows:

  • At the beginning of the evaluation of a sentence the range start is 1, so it points at the first word of the sentence. This means that, at this stage, conditions may match words in the entire sentence.
  • When the condition is matched, the range start is updated to the index of the word following the one that has matched the condition being tested (note that this rule isn't followed by the Maybe (~) Operator). With each increase of the range start, the range of sentence words available for matching decreases.
  • The evaluated range of words begins at range start and always extends until the end of the sentence.

Some compound conditions reset the range start to the beginning of the sentence when they evaluate a condition operand.

Example

Condition: B
Sentence: A B1 C B2 E

The condition evaluation will do the following:

  • At the beginning of the evaluation, the sentence range is the whole sentence A B1 C B2 E, and the range start is 1.
  • When the B in the second position of the input sentence is matched, the range start is set to 3 and thus reduces the sentence range to C B2 E.
  • When the B in the fourth position of the input sentence is matched, the range start is set to 5 and thus reduces the sentence range to E.

Dependencies between sentences

Sentences are evaluated independently against the conditions; therefore, one sentence's test results are not affected by other sentences.

There is, however, an exception: script conditions may set variables (via side effects) in one sentence and test these variables on the next sentence. This creates a dependency between sentences and would be affected by sentence testing order.

Condition Match Instance and Used Words

If a condition matches a sentence, then the Boolean condition result is “true”, and for each possible match a match data instance is generated.

A match data instance, or match instance (MI), provides the following information:

  • The used words (UW), which are the words in the sentence that matched the condition.
  • The range start to be used for the ongoing condition evaluation.
  • The Language Object (LOB) variables, which are defined by LOBs. During condition evaluation, LOB variables are maintained in a separate hidden variable space and become available to general scripting after condition evaluation.
  • The Natural Language Understanding (NLU) data; see NLU variables and attached scripts for more details.

If a condition does not match a sentence, then the Boolean condition result is “false”, and match data instances are not generated.

Example

Condition: B
Sentence: A B1 C B2 E

This combination of sentence and condition will produce 2 match instances:

  • When the B in the second position of the input sentence matches, the match instance generated contains the values UW = B (at word position 2) and RS = 3.
  • When the B in the fourth position matches, the match instance generated contains the values UW = B (at word position 4) and RS = 5.

Condition context

When using the Teneo Platform, conditions are usually complex, composed by many atomic conditions and operators; these elements affect how a condition is evaluated.

Example

Condition: A
Sentence: A B C

In this example, under ordinary circumstances (range start = 1), the condition would match, since A is in the sentence range.

However, if a match were to modify the value of the range start to 2 or 3, then the sentence range would no longer contain A and therefore the condition would not be fulfilled, even though the word A is in the sentence.

Condition context

As seen in the example, the operations happening before evaluating a condition may have a huge impact testing it.

The entirety of conditions evaluated before a particular condition is named the condition context, which provides the following data:

  • One or more match data instance(s) that have already been generated by the evaluation of the conditions. If the condition hasn’t started being evaluated, there is a default match instance which contains the initial values of the condition context such as range start equal to 1.
  • The flag DIRECTLY_FOLLOWED_BY (DFB), which indicates whether the current condition is being evaluated in the context of the right operand of a compound condition of the type Directly Followed By (>>) - Operator.

Usually the value of the DFB flag is propagated through compound conditions, with some exceptions that are described in the sectionCompound conditions.

Evaluating a condition

Important: The objective of this section is to explain how Teneo Engine determines the evaluation steps for the conditions (by traversing the AST), not how particular operators work.

Operators are described in full detail in the section Compound Conditions.

Evaluation of a condition according to the AST

As mentioned, conditions can be quite complex and require several operations to complete their testing. Condition matching follows the AST structure, which determines which steps (and in what order) need to be followed to test the condition. The system evaluates the operators (like + & >>) with a top-to-bottom approach, and operands (like A B C) left-to-right.

Let’s say we have the condition A >> B, it would correspond to the following AST and evaluation steps:

  1. Create default MI and condition context. Pass it to the operator.
  2. Pass the received condition context to the left operand.
  3. Test left operand A. Update and/or create new MIs if matches occur.
  4. If the operator requires it, modify the condition context. The resulting condition context is passed to the right operand.
  5. Test right operand B. Update and/or create new MIs if matches occur.
  6. Continue with the next condition to be evaluated. If it’s the last condition, select the final result.

Passing the condition context

It is important to highlight that operators have different behaviors regarding the condition context.

Some operators pass the condition context (including the existing MI) to the first operand, which modifies the existing MIs (or creates new ones) if matches occur. Once the first operand is evaluated, the updated condition context is returned to the operator, which forwards it to the second operand to continue the evaluation. The second operand is evaluated, and the context is updated if necessary, generating the results of the condition.

Other operators (& and extended & operators typically), however, duplicate the MI and pass one copy to each operand. Operands evaluate the sentence independently and return their updated condition context to the operator. These two contexts are then merged by the operator by joining left operand MIs with right operand MIs, resulting in the final context.

Obtaining the final result

Firstly, for each condition part to which Longest Match is applied, the highest used words count of all matches is determined. Those matches with fewer words are discarded.

Afterwards, if several possible matches remained, the system selects the final result according to these rules:

  • Rule 1: Left Most of First. First, the system determines the leftmost first used word of all MIs and selects the MIs which contain this used word.
  • Rule 2: Left Most of Last. If there are two or more MI that contain the Left Most first used word, then out of them the system selects the MIs that contain the Left Most last used word.
  • Rule 3: Longest Match. If Rules 1 and 2 do not narrow it down to a single MI, then out of them the system selects those with the highest count of used words.
  • Rule 4: Internal Order. If after applying these rules there are still two or more MI left, then out of them the system picks up the first MI, according to the order in which the MIs where generated by the condition.

Unused Word Limitation

It is possible to limit the amount of Unused Words to take into account when evaluating the condition (this is quite useful to carry on conversations regarding a specific topic, for instance). If applied, the process of evaluating the condition described in the past section is followed by a check whether count of words not used by the condition term of the selected match is not exceeding said limit. That is, if the amount of Unused Words is set to e.g. 3, the condition is fulfilled only if at most 3 words in the sentence are not used by the matching condition term.

To do so, set the desired amount of unused words at the “Limit unused words to” setting under Advanced Options in the Condition.

Condition Match Requirement

The following examples illustrate how the unused word limit is applied.

Unused Words LimitConditionMatched User InputUnmatched User Input
[left blank]who+are+youWho are you?You are who?
Who are you going to marry?
Unused Words LimitConditionMatched User InputUnmatched User Input
0who+are+youWho are you?[anything else]
Unused Words LimitConditionMatched User InputUnmatched User Input
1who+are+youWho are you?Who are you talking to?
Just who are you?Who are the people you met?
Unused Words LimitConditionMatched User InputUnmatched User Input
5who+are+youWho are you?Who are you going to marry next Sunday, Fred?
Who are you going to marry?

Examples

Please note that the following examples are meant to explain the condition AST, the workflow of the condition evaluation and how condition context is built, and not to explain how operators work.

Example 1: A+B and A>>B

Condition: A + B and A >> B
Sentence: A1 A2 B

Note: for explanatory purposes equal sentence words will be identified with a number as well, e.g. A1.

This example illustrates the case when:

  1. the condition context is updated by the operands and then forwarded between the operator and the operands
  2. the condition context is updated by the operands and while being forwarded between the operator and the operands

* See the section Obtaining the final result.

Example 2: (A+B)>>C

Condition: (A+B) >> C
Sentence: A B1 B2 C

Note: for explanatory purposes, equal sentence words will be identified with a number as well, e.g. A1.

This example illustrates a more complex case in which the condition context is updated by multiple operands and while being forwarded between operators and operands.

Condition Syntax

In this document, the following metasyntax (based on the Backus-Naur form) is used for the formal description of the condition syntax. However, it is important to highlight that the condition syntax itself is not based on the Backus-Naur form, only the metasyntax.

The syntax of a condition is specified as a set of one or more derivation rules, written as:

symbol = expression

Where symbol is a non-terminal Entity defined by the expression, which consists of one or more sequences of symbols or literal characters (literals).

Multiple sequences of symbols and literals are separated by the vertical bar "|", which indicates a choice. The symbol may then be substituted by any of the expressions on the right:

color = red | green | blue

If the expression contains sequences of literal characters, they must be enclosed into single quotes:

digit = '0' | '1' | '2' | ... | '9'

An optional part of an expression is enclosed into square brackets:

number = [ '-' ] digits

A plus “+” sign is used to denote one or more repetitions, and an asterisk “*” represents zero or more repetitions:

number = [ '-' ] digit+ [ '.' digit* ]

Round brackets “()” are used for grouping:

number = ( '0' octal-digits ) | ('0x' hex-digits )

Minus “- “ is used for exclusion:

valid_characters = all_characters - invalid_characters

Common syntax elements

As explained before, conditions test the words of the sentence. In the condition syntax a word is a sequence of one or more non-reserved, non-whitespace Unicode characters (the Unicode characters covered by the Unicode standard).

If reserved characters are included in the word, then the entire word must be delimited by double quotes. Therefore, if a word includes a literal double quote, then this quote must be duplicated and the word must be written between quotes as well. The effectively resulting word is the concatenation of the non_quote_characters and singular double quote characters.

Formally, the common syntax elements are the following:

  • unicode_chars = all possible Unicode characters
  • word = (unicode_chars - delimiter)+ | ( '"' non_quote_character* ( '""' non_quote_character* )* '"' )
  • delimiter = reserved_character | comment_delimiter | whitespace
  • reserved_character = '&' | '+' | '>' | '~' | '/' | '(' | ')' | '!' | '§' | '|' | '*' | ':' | '#' | '%' | '@' | '{' | '}' | '^' | '"' | '='
  • comment_delimiter = '=='
  • whitespace = blank | tab | end_of_line | java_whitespace
  • non_quote_character = unicode_chars - '"'

For details on whitespace, see the Javadoc of Character.isWhitespace and Character.isSpaceChar.
For details on the comment_delimiter, see the section Comments.
The unicode_chars are all characters valid in the Teneo Platform (these are the characters defined by the Unicode standard).

Atomic conditions

Atomic Conditions get their name from the fact that they are the smallest possible units of a Condition, and all Conditions must be built using them.

The atomic conditions are:

  • Word Condition
  • Word Part condition
  • Language Object Condition
  • Input Annotation Condition
  • Dynamic Condition
  • Topic Condition
  • Script Condition

The following additional options are available for word, word part, and dynamic conditions:

  • Position Option
  • Exact Option

When writing conditions, it is important to be aware of the reserved characters. For more information please see theReserved Characters section.

Word condition

Official name: Word condition
Alternative name: Raw Word condition

Syntax

word

General description

For a word condition to be fulfilled, the given word must be recognized in the sentence. Here, the position and frequency of the word within the sentence are irrelevant. This condition is not case-sensitive.

The word condition supports the Position Option and the Exact Option.

Logical behavior

The word condition is true if and only if at least one match instance of the condition context exists so that

  • if the DFB flag is NOT activated, the word matches one or more of the sentence words from range start of the match instance to sentence end.
  • if the DFB flag is activated, the word matches the sentence word at and only at range start of the match instance.

For more information on DFB, please see the Directly Followed By (>>) – operator.

Generated match data

The matching word is added to each MI in the condition context with a range start lower than or equal to (exactly equal to if the DFB flag is activated) the position of the matching word. All MIs with a range start higher than the positions of all matching words are dropped.

If the sentence contains multiple words which match the condition, a copy of all the MIs will be created for each match (i.e. each match will have its own set of MIs); then each matching word will be added to the used words of its set of MIs.

  • Range start: next word after the matching sentence word
  • Used words: used words of the condition context match plus the matching sentence word
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

ConditionMatched User InputUnmatched User Input
CongressCongressCongressional
Congress personCongressperson

Word Part condition

Official name: Word part condition

Syntax

There are 4 possible ways to use the word part condition:

word '*' | '*' word | '*' word '*' | '*'

If reserved characters are included in the word part, then the entire word part (but not including the '*' character) must be delimited by double quotes.

General description

The word part condition uses wildcards ( * ) at the beginning, the end, or the beginning and end of the word part to be recognized. It may also be used by itself to represent a single word. A wildcard at the beginning allows any characters in front of the word part to be recognized; a wildcard at the end allows any characters after the word part to be recognized; the wildcard at both beginning and end allows any characters before and after the word part to be recognized. A wildcard by itself allows any whole word to be recognized.

For instance, when using *cat, at least one word ending with “cat” must be in the sentence for the condition to match. However, the word “cat” by itself is also a match.

Please note that words that are "captured" by the Word Part condition are fully recognized, not just the “part condition”. Besides, they will not be counted as part of the unrecognized word count. See the examples for more details.

The word part condition supports the Position Option and the Exact Option.

Logical behavior

The word part condition is true if and only if at least one match instance of the condition context exists so that

  • if the DFB flag is NOT activated, the word part matches one or more of the sentence words from range start of the match instance to sentence end.
  • if the DFB flag is activated, the word part matches the sentence word at and only at range start of the match instance.

Generated match data

The matching word is added to each MI in the condition context with a range start lower than or equal to (exactly equal to if the DFB flag is activated) the position of the matching word. All MIs with a range start higher than the positions of all matching words are dropped.

If the sentence contains multiple words which match the condition, a copy of the all the MIs will be created for each match (i.e. each match will have their own set of MIs); then each matching word will be added to the used words of their set of MIs.

  • Range start: next word after the matching sentence word
  • Used words: used words of the condition context match plus the matching sentence word
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

ConditionMatched User InputUnmatched User Input
Love*LoverBeloved
LoveGlove
ConditionMatched User InputUnmatched User Input
*loveGloveLover
CloveClover
Lovebeloved
ConditionMatched User InputUnmatched User Input
*love*BelovedLuv
Clover
love
ConditionMatched User InputUnmatched User Input
I+love+*I love tofuI love
I love catsIt’s you who I love
I love martial arts

Language Object condition

Official name: Language Object condition

Syntax

'%' language_object_name
language_object_name = word

General description

Language Objects (LOBs) can contain one condition of any type (atomic, compound, it may be even empty), LOB variables and NLU variables. The LOB is, in itself, a named condition so using a LOB effectively acts as a shortcut to the condition contained in it, making it easier to reuse.

Please note that even though the syntax of a Language Object name is a word (thus allows all possible Unicode characters), by convention it is written in UPPERCASE and cannot contain whitespace (spaces, tabs, newlines etc.) or any of the reserved_characters (see chapter Reserved Characters for a listing). This constraint is enforced by the Teneo Frontend application.

For a LOB condition to be fulfilled, the sentence must contain text fulfilling the condition contained in the LOB itself.

The condition of the referenced Language Object may set NLU variables, which are provided to optional Predicate or Propagation scripts attached to a Language Object condition. For more details, see section NLU variables and attached scripts.

The referenced Language Object may also set LOB variables on the generated matches. LOB variables have value type String and stick on the matches and are passed on during the condition evaluation. On condition top-level, the LOB variables are accessible with scripting API methods EngineAcess.getLangObjVariable(String) and EngineAcess.getLangObjVariables().

Script expressions embedded into a LOB variable value are replaced with their evaluation result at the time of evaluation of the Language Object condition referencing to this LOB. The special LOB variable value _USED_WORDS will be replaced with the used words of the particular match of the condition of the Language Object. The resulting value is the concatenation of the matching sentence words (with the exact spelling given in the original user input), separated by single whitespace characters.

Logical behavior

The Language Object condition is true if and only if the condition of the referenced Language Object itself is true. If the referenced Language Object doesn’t exist, then then Language Object condition is false.

Generated match data

The matches of a Language Object condition are generated by the condition of the referenced Language Object itself. If NLU scripts are attached to the Language Object condition, they will be added to these matches.

  • Range start: set by the condition of the Language Object
  • Used words: set by the condition of the Language Object
  • NLU variables: all NLU variables defined by the Language Object and set by propagation scripts in the condition of the Language Object. These variables are available in predicate and propagation scripts attached to Language Object condition.
  • NLU scripts data: the NLU scripts attached to the Language Object condition are appended
  • LOB variables: the LOB variables defined on the referenced Language Object are added to the set of LOB variables of the match. Existing LOB variables with the same name are overwritten.
  • Longest match data: set by the condition of the Language Object

Examples

In the following example, we'll assume there's already a Language Object named US_PRESIDENTS_LIVING, with the condition: "biden/trump/obama/clinton/bush/carter".

ConditionMatched User InputUnmatched User Input
%US_PRESIDENTS_LIVING.LISTCarterReagan
ClintonNixon
Obama
Biden

Annotation condition

Official name: Annotation condition
Alternative names: Input Annotation condition

Syntax

'%$' annotation_name
annotation_name = word

General description

Annotations follow the same naming conventions as Language Objects, thus names must be written in UPPERCASE and cannot contain whitespace (spaces, tabs, newlines etc.) or any of the reserved_characters (see chapter Reserved characters for a listing).

For an Annotation condition to be fulfilled, an annotation with the name given in the Annotation condition must exist on the sentence itself or one or more sentence words.

The variables of the matching annotation are provided to an optional predicate and propagation scripts attached to the annotation condition. For more details, see section NLU variables and attached scripts.

The platform generates two default collections of annotations:

  • System Annotations. Built-in, these two annotations depend on the session state and are set by Teneo Engine itself:

    _INIT If a dialogue has just begun
    _TIMEOUT If the current dialogue was restarted after being timed out

  • Standard Annotations. These annotations are set by the input processors of the Teneo Engine, according to the active language configuration. See the glossary for a listing of these annotations.

According to the active language configuration, input processors may set additional annotations, for example, part-of-speech annotations, or number/digit annotations.

Annotations may be created also by solution scripting.

Logical behavior

The annotation condition is true if and only if any of the following occurs:

  • if the current sentence itself has an annotation with the name given in the annotation condition (that is, the annotation is not assigned to any sentence word)
  • if the current sentence has a word with an annotation with the name given in the annotation condition, then if the DFB flag is NOT activated, the word with the annotation is in the sentence words from range start of a condition context match instance to sentence end
  • if the current sentence has a word with an annotation with the name given in the annotation condition, then if the DFB flag is activated, the word with the annotation is exactly at the sentence range start of a condition context match instance.

Note that an annotation instance can be assigned to multiple words. In this case the above logical rules are applied only to the left most of the words the annotation is assigned to. That is, such an annotation is not fulfilling the annotation condition if the left most word is to the left of the range start of a match instance, even if one or more of the other words are in the sentence words from range start to sentence end.

Generated match data

The matching word is added to each MI in the condition context with a range start lower than or equal to (exactly equal to if the DFB flag is activated) the position of the matching word. All MIs with a range start higher than the positions of all matching words are dropped.

If the sentence contains multiple words which match the condition, a copy of the all the MIs will be created for each match (i.e. each match will have their own set of MIs); then each matching word will be added to the used words of their set of MIs.

  • Range start: next word after the matching sentence word
  • Used words: used words of the condition context match plus the used words of the annotation
  • NLU variables: set to the variables attached to the annotation
  • NLU scripts data: the NLU scripts attached to the annotation condition are appended
  • LOB variables: not modified
  • Longest match data: not modified

Examples

ConditionMatched User InputUnmatched User Input
%$_QUESTIONWhat?Question
? huh ??
ConditionMatched User InputUnmatched User Input
%NN.POSA bookBook this
A nice playPlay louder

Dynamic condition

Official name: Dynamic condition
Alternative names: Dynamic word condition

Syntax

'#' variable_name
variable_name = word

General description

For a dynamic condition to be fulfilled, the sentence must contain the content of the specified variable; case, position, and frequency of that content within the sentence are irrelevant. The dynamic condition matches a sentence word if the simplified form of the variable content is exactly the same as the final word form of the sentence word. The “variable content” is the result of Java method toString() called on the variable content object.

Remember that variable names are case sensitive.

The dynamic condition supports the Position Option and the Exact Option.

Logical behavior

The word part condition is true if and only if at least one match instance of the condition context exists so that:

  • if the DFB flag is NOT activated, the word part matches one or more of the sentence words from range start of the match instance to sentence end
  • if the DFB flag is activated, the word part matches the sentence word at and only at range start of the match instance

The dynamic condition is false if:

  • the variable doesn’t exist, or
  • the variable content is null, or
  • the call to method toString() on the variable content object caused an exception

Generated match data

The matching word is added to each MI in the condition context with a range start lower than or equal to (exactly equal to if the DFB flag is activated) the position of the matching word. All MIs with a range start higher than the positions of all matching words are dropped.

If the sentence contains multiple words which match the condition, a copy of the all the MIs will be created for each match (i.e. each match will have their own set of MIs); then each matching word will be added to the used words of their set of MIs.

  • Range start: next word after the matching sentence word
  • Used words: Used words of the condition context match plus the matching sentence word
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

In the following example, we'll assume there's a variable called User_City with the value "Memphis".

ConditionMatched User InputUnmatched User Input
#User_CityMephisMemphisGrizzlies
MEMPHISTennessee

Topic condition

Official name: Topic condition
Alternative names: N/A

Syntax

'@' variable_name
variable_name = word

General description

For a topic condition to be fulfilled, a scripting variable with the given name must be set to a value which is true (remember that variable names are case-sensitive.) The topic condition neither takes sentence words into account nor adds the used words of the resulting matches.

The set of available scripting variables depends on the location of the topic condition. In conditions of global listeners, only session variables are accessible; otherwise session and Flow variables are accessible. Session variables can be assigned a certain value for a specified number of turns, after which they revert to their default values. The life span of a session variable assignment can be set by solution scripting but is, by default, the entire session.

See section Glossary – Concept reference for the definition of Studio concepts such as Flows, listeners and variables.

Logical behavior

The topic condition is true if and only if the variable content:

  • has a Boolean type and the value is true, or
  • has a number type and the value is neither zero nor NaN (“not a number”), or
  • is a character and the character code is not zero, or
  • is a character sequence (e.g. a string) and the sequence is not empty

If the variable value doesn’t have any of the types listed above or is null, then the topic condition is false.

Generated match data

The matches of the condition context are not changed and passed on as is.

  • Range start: not modified
  • Used words: not modified
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

In the following example, we'll assume there's a global Boolean variable called fish in the solution.

ConditionMatched User InputUnmatched User Input
@fishAll input is recognized as long as the variable fish has a value that returns true.No input is recognized if the variable fish has a value that returns false.

Script condition

Official name: Script condition
Alternative names: N/A

Syntax

'{' script_expression '}'
script_expression = ( unicode_chars – '}' | '\}' )*

A script condition is formed by a script expression enclosed in braces. A right brace within the script expression text must be escaped by prefixing it with a backslash: '\}'. All other reserved characters of the condition syntax can be used in the script expression text without escaping.

In summary, the effective script expression text results from stripping off the braces and removing the backslash in front of escaped right braces; backslashes appearing elsewhere in the text are kept.

General description

The script expression is evaluated with the Groovy scripting engine.

For a Script condition to be fulfilled, the result of the expression evaluation has to have a Boolean value of true. If the result type is not a Boolean, then it is converted to Boolean according to Groovy’s type conversion rules.

The script condition does not take sentence words into account, nor is it adding to the used words of the resulting matches.

Logical behavior

The script condition is true if and only if the script expression result

  • has a Boolean type and the value is true or
  • has a number type and the value is neither zero nor NaN (“not a number”), or
  • is a character and the character code is not zero, or
  • is a character sequence (e.g. a string) and the sequence is not empty

If the script expression result doesn’t have any of the types listed above or is null, then the script condition is false.

Generated match data

The matches of the condition context are not changed and passed on as it is.

  • Range start: not modified
  • Used words: not modified
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

In the following example, we'll assume that a User_Age variable has been set, with a value equal to the user's age.

ConditionMatched User InputUnmatched User Input
{User_Age > 21}All input is recognized as long as User_Age is greater than 21.No input is recognized if the User_Age is less than or equal to 21.

Compound conditions

Compound Conditions consist of two or more Atomic Conditions put together in formulas with the use of Operators. There are several Operators, and they can be organized by the use of parentheses. Note that parentheses are only necessary when more than one Operator is being used in a Condition.

The following operators are possible for compound conditions:

  • AND (&) - Operator
  • SAME MATCH (&=) - Operator
  • BIGGER MATCH (&>) - Operator
  • SMALLER MATCH (&<) - Operator
  • OVERLAP MATCH (&~) - Operator
  • DIFFERENT MATCH (&^) - Operator
  • NOT SAME MATCH (!&=) - Operator
  • NOT BIGGER MATCH (!&>) - Operator
  • NOT SMALLER MATCH (!&<) - Operator
  • NOT OVERLAP MATCH (!&~) - Operator
  • NOT DIFFERENT MATCH (!&^) - Operator
  • FOLLOWED BY (+) - Operator
  • DIRECTLY FOLLOWED BY (>>) - Operator (slow, complete)
  • NOT DIRECTLY FOLLOWED BY (!>>) - Operator (slow, complete)
  • OR (/) - Operator
  • NOT (!) - Operator
  • MAYBE (~) - Operator
  • Compound (|) - Operator
  • Parentheses

The following operand binding groups are defined:

Operator binding groups
Stronger bindingNOT (!), Compound (|)
Weaker bindingOR (/), AND (&), SAME MATCH (&=), BIGGER MATCH (&>), SMALLER MATCH (&<), OVERLAP MATCH (&~), DIFFERENT MATCH (&^), NOT SAME MATCH (!&=), NOT BIGGER MATCH (!&>), NOT SMALLER MATCH (!&<), NOT OVERLAP MATCH (!&~), NOT DIFFERENT MATCH (!&^), FOLLOWED BY (+), DIRECTLY FOLLOWED BY (>>), NOT DIRECTLY FOLLOWED BY (!>>), MAYBE (~)

The evaluation order of compound conditions containing different operators of equal binding strength is unspecified, therefore it needs to be clarified by using parentheses.

The And operators

The And Operators section refers to the set of compound operators (&, &=, &>, &<, &~, &^) which have a very similar behavior.

Syntax

left_condition whitespace* and_operator whitespace* right_condition

and_operator = '&' | '&=' | '&>' | '&<' | '&~' | '&^'

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The And Operators are binary operators, that is, they take two operands with the and_operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The And Operators define a Boolean AND condition on the two operand conditions; for this AND condition to be fulfilled, both operand conditions must be met.

Logical behavior

The AND Condition is true if and only if both operand conditions are true.

If the DFB flag is active in the passed-in condition context, then the operand conditions are evaluated twice:

  • Once with the DFB flag passed only to the left condition (evaluation 1)
  • And again, with the DFB flag passed only to the right condition (evaluation 2)

This is done to ensure that the AND condition is fulfilled also if only one of the many operand conditions matches at the range start position of the passed-in MIs.

Generated match data

Both operand conditions are evaluated independently of each other, by using a copy of the condition context passed in to the AND condition. The evaluation and MI updates of one operand condition are not affecting the evaluation and MI updates of the other operand condition.

After the evaluation of the operand conditions, left and right output MIs are “multiplied” to generate the output of the AND condition: each possible pair of a left and right output MI, both originating from the same input MI and fulfilling the operator’s used word constraint, is merged into a final MI. This multiplication is “left-heavy”; that is, it begins with the first left-side MI to generate mergers with right-side MIs in their order, followed by mergers of the second left-side MI with the right-side MIs, and so forth. If two or more generated MIs have the same used words, then only the first one is kept and the others are dropped.

If the DFB flag is activated in the passed-in condition context, and both operand conditions are fulfilled in both evaluations (see above), then the MIs generated by multiplication of the MIs of the first evaluation are followed by the MIs generated by multiplication of the MIs of the second evaluation.

The MI merging is carried out by inserting data of the right-side MI into the left-side MI. This effects that, if both MIs have NLU scripts attached, then the left-side scripts are executed before the right-side scripts. Furthermore, if both MIs have LOB variables with the same name, then for each of these conflicting variables the value from the right-side MI gets precedence.

  • Range start: range start max from left-side and right-side MI
  • Used words: aggregation of used words from left-side and right-side MI
  • NLU scripts data: left-side NLU scripts, followed by the right-side NLU scripts
  • LOB variables: aggregation of LOB variables from left-side and right-side MI (right-side one taking precedence in case of variables with same name)
  • Longest match data: left-side longest match data, followed by the right-side longest match data.

And operator

Official name: And operator
Alternative names: And condition
Representation: &

Syntax

left_condition whitespace* '&' whitespace* right_condition*

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The & Operator is the simplest of the And Operators family. It does not impose a constraint on the used words of the matches from each operand.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of section The And operators.

Examples

This first example illustrates how the condition only requires that the words are used, regardless of the order.

ConditionMatched User InputUnmatched User Input
I & love & youI love youEveryone loves you
Your parents love you, but I don’t

This other example shows that the condition applies not only to unique words but lists or other constructions.

ConditionMatched User InputUnmatched User Input
%CITIES.LIST & %CITIES.LISTBarcelonaAndorra
LondonPortugal
Tokyo and Kyoto

The Extended And operators

General description

Same as the simple And Operator, all Extended And Operators define a Boolean AND condition, but with an additional requirement: the used words of at least one pair of MI consisting of one left operand MI and one right operand MI must fulfill an extra constraint in order to meet the overall AND condition.

Logical behavior

The Extended AND Condition is true if and only if

  • both operand conditions are true, and
  • the used word constrain is fulfilled. The used word constraint varies depending on the operator and is met when at least one pair of MI, formed by of a left-side operand match and a right-side operand match which origin from the same MI in the condition context, comply with the required used word restriction.

Same Match operator

Official name: Same Match operator
Alternative names: Same Match condition, Same Match extended and condition
Representation: &=

Syntax

left_condition whitespace* '&=' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Same Match Operator is an enhanced member of the And Operators family; therefore, for this condition to be fulfilled, both operand conditions must be met. Since this is an Extended Operator, it also requires an additional used word constraint. In this case, the condition is fulfilled if and only if at least a pair of a left-side operand match and a right-side operand match exists in which both matches have the same used words, at the same positions.

This operator is particularly useful when working with annotations, although it may also be applied with any type of coding.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of section The And operators.

Examples

The first example only matches synonyms of the verb "run" in past tense:

ConditionMatched User InputUnmatched User Input
%RUN.VB.SYN &= %MST_PAST.ANNOTI ran homeI am jogging
He bolted outI race

This other example only matches if “hello” is the first word in a sentence:

ConditionMatched User InputUnmatched User Input
%HELLO.FW.LEX &= %FIRST_WORD.SCRIPTHello to youI said hello
Hello and good morning

Bigger Match operator

Official name: Bigger Match operator
Alternative names: Bigger Match condition, Bigger Match extended and condition
Represenation: &>

Syntax

left_condition whitespace* '&>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Bigger Match Operator is an enhanced member of the And Operators family. This operator defines an AND condition that imposes an additional constraint on the used words of the operand matches; this condition is fulfilled if and only if at least one pair of a left-side operand match and a right-side operand match exists so that the left-side match contains the same or additional used words, at the same sentence positions, as the right-side match, or the right-side match has no used words. In other words, the left-side match must be a superset – same or bigger – of the right-side match.

This operator is particularly useful when working with annotations, although it may also be applied with any type of coding.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of section The And operators.

Examples

The operator '&>' matches if the operand on the left matches on all words in the input that the operand on the right matches on, but the operand on the left can optionally match on more words as well.

This is useful, for example, when you only want a subset of a list to match.

ConditionMatched User InputUnmatched User Input
%SUPPORTED_PRINTERS.LIST &> EpsonI need the user documentation for Epson 202XPWere do I download a driver for the HP202XXL
Where do I download a driver for Epson SSLX?
ConditionMatched User InputUnmatched User Input
%CAR_BRANDS.LIST &> hybridHonda Accord HybridSubaru Forester
Ford Fusion Hybrid

Smaller Match operator

Official name: Smaller Match operator
Alternative names: Smaller Match condition, Smaller Match extended and condition
Representation: &<

Syntax

left_condition whitespace* '&<' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Smaller Match Operator is an enhanced member of the And Operators family. This operator defines an AND condition that imposes an additional constraint on the used words of the operand matches; this condition is fulfilled if and only if at least one pair of a left-side operand match and a right-side operand match exists so that the right-side match contains the same or additional used words, at the same sentence positions, as the left-side match, or the left-side match has no used words. In other words, the left-side match must be a subset – same or smaller – of the right-side match.

This operator is particularly useful when working with annotations, although it may also be applied with any type of coding.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of section The And operators.

Examples

For the condition to evaluate to true, both operands must match in the input, and the right operand must match on at least all the words matched by the left operand.

For instance, we may be searching for movies that only contain USA cities:

ConditionMatched User InputUnmatched User Input
%CITIES_UNITED_STATES.LIST &< %MOVIE_TITLES.LISTThe movie Fear and Loathing in Las VegasI like going around loathing in Las Vegas
I went to see Crocodile Dundee in Los AngelesI went to the zoo and saw a crocodile in Los Angeles
Have you ever seen Escape from New York?The Lord of the Rings is a great film
Chicago is a great musicalI don’t like Vicky Cristina Barcelona

Overlap Match operator

Official name: Overlap Match operator
Alternative names: Overlap Match condition, Overlap Match extended and condition
Representation: &~

Syntax

left_condition whitespace* '&~' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Overlap Match Operator is an enhanced member of the And Operators family. This operator defines an AND condition that imposes an additional constraint on the used words of the operand matches; this condition is fulfilled if and only if at least one pair of a left-side operand match and a right-side operand match exists so that the matches share at least one used word at the same sentence position. Thus, the condition is not fulfilled if a match has no used words.

This operator is particularly useful when working with annotations, although it may also be applied with any type of coding.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The And operators section.

Examples

The operator matches when both operands overlap, i.e. they share at least one used word in the input.

It is useful when the left and right operand share some or all used words.

ConditionMatched User InputUnmatched User Input
%COUNTRIES.LIST &~ (the >> united >> *)I am a citizen of the United States of AmericaI shop at the United Colors of Benetton
I travel to the United Kingdom quite often

Different Match operator

Official name: Different Match operator
Alternative names: Different Match condition, Different Match extended and condition
Representation: &^

Syntax

left_condition whitespace* '&^' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Different Match Operator is an enhanced member of the And Operators family. This operator defines an AND condition that imposes an additional constraint on the used words of the operand matches; this condition is fulfilled if and only if at least one pair of a left-side operand match and a right-side operand match exists so that the matches share no used word at the same sentence position.

This operator is particularly useful when working with annotations, although it may also be applied with any type of coding.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The And operators section.

Examples

'&^' matches if both operands do not overlap, i.e. they do not share any word in the input.

For example, this example matches if the input contains two different cities:

ConditionMatched User InputUnmatched User Input
%CITIES.LIST &^ %CITIES.LISTParis and LondonLondon
Barcelona and New York City
ConditionMatched User InputUnmatched User Input
(%MY.FW.LEX >> %NATIONALITY.NN.LEX) &^ %NATIONALITIES.LIST &^ %NATIONALITIES.LISTMy nationality is French and CanadianMy nationality is Norwegian
My nationality is Chinese and Italian

The Negated And operators

The Negated And Operators section refers to the set of compound operators (!&=, !&>, !&<, !&~, !&^) which have a very similar behavior.

Syntax

left_condition whitespace* negated_and_operator whitespace* right_condition

negated_and_operator = '!&=' | '!&>' | '!&<' | '!&~' | '!&^'
left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Negated And Operators are binary operators, that is, they take two operands with the negated_and_operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Negated And Operators define a logical interconnection condition on the two operand conditions. For a Negated And Operator to be fulfilled, at least the left-side operand must be fulfilled. If the right-side operand is fulfilled as well, then the total operator condition is met only if none of the matches of the right-side condition comply with the used word constraint, which depends on the specific operator being used.

Note that the right-side condition is always evaluated on the entire sentence, with the DFB flag deactivated, regardless of the condition context.

The Negated And Operators are particularly useful when working with annotations, although they may also be applied with any type of coding.

Logical behavior

The Negated And Operator is true if and only if

  • the left-side operand is true and the right-side operand is false, or
  • both operand conditions are true and no pair formed by a left-side match and a right-side match exists so that the operator’s used word constraint is fulfilled

Generated match data

The condition context is passed only to the left-side condition. The right-side condition is always evaluated with an initial condition context, that is, it’s being tested on the entire sentence, with the DFB flag deactivated.

The resulting MIs are all the MIs generated by the left-side operand that do not match any MIs of the right-side operand, in an operator specific way. That is, the right-side operand MIs are used to drop certain MIs of the left-side operand; otherwise they do not contribute in any way to the final MIs.

  • Range start: as set by the left-side condition
  • Used words: as set by the left-side condition
  • NLU scripts data: as set by the left-side condition
  • LOB variables: as set by the left-side condition
  • Longest match data: as set by the left-side condition.

Not Same Match operator

Official name: Not Same Match operator
Alternative names: Not Same Match condition, Not Same Match extended and condition
Representation: !&=

Syntax

left_condition whitespace* '!&=' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Not Same Match Operator is a member of the Negated And Operators family. For condition to be fulfilled, at least the left-side condition must be fulfilled. If the right-side condition is also fulfilled, then the entire condition is fulfilled if and only if at least one match of the left-side condition does not have the exact same used words as any match of the right-side condition. Here matches of the right-side condition with no used words are not considered.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The Negated And operators section.

Examples

The following examples illustrate the behavior of the operator, which is very useful when to exclude an exact/specific pattern from a condition.

For instance, the first example will only match if nothing in the current sentence ends in ing.

ConditionMatched User InputUnmatched User Input
%WRITE.VB.SYN !&= *ingI like to writeI like writing
He writesShe is into scribbling
I digress in writings

In this example, the user input “play” matches as long as it doesn’t appear as the first word in the matched sentence.

ConditionMatched User InputUnmatched User Input
PLAY !&= *:1I want to play guitarPlay me a song!

Here, the user input “play” matches as long as it isn’t annotated as a noun.

ConditionMatched User InputUnmatched User Input
PLAY !&= %NN.POSI want to play some musicI am going to see a play in the theatre

In this case, the user input matches if it contains any of the synonyms for change, except for the ones ending with ing.

ConditionMatched User InputUnmatched User Input
%CHANGE.VB.SYN !&= *ingI want to change my ticketI am changing tickets
I need to swap seatsI was swapping seats

Finally, in this example any user input simplified to “meta” matches, except the exact user input “Metà”.

ConditionMatched User InputUnmatched User Input
Meta !&= Metà:EIt is a meta questionWe attended the Metà conference
It is a META question

Not Bigger Match operator

Official name: Not Bigger Match operator
Alternative names: Not Bigger Match condition, Not Bigger Match extended and condition
Representation: !&>

Syntax

left_condition whitespace* '!&>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Not Bigger Match Operator is a member of the Negated And Operators family. For its condition to be fulfilled, at least the left-side condition must be fulfilled. If the right-side condition is also fulfilled, then the entire condition is fulfilled if and only if at least one match of the left-side condition does not have the same or more used words as/than any match of the right-side condition. Here matches of the right-side condition with no used words are not considered.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The Negated And operators section.

Examples

This condition is useful when you want to exclude a smaller part of a condition or pattern from an existing condition.

For example, this case only matches when the user only has a single issue, and no more.

ConditionMatched User InputUnmatched User Input
%I_HAVE_A_PROBLEM.PHR !&> *sI have a problemI have several problems
I have one issue with thisI have two issues
I have a problem seeing startsI has a problem

This case only matches on synonyms of “buy” that are not in the past tense (we use not bigger match, as some of the synonyms may be longer than one word).

ConditionMatched User InputUnmatched User Input
%BUY.VB.SYN !&> $PAST.POSI am buying a ticketI bought a new car
I am shopping for shoes

Here, all variants of “how do I install” match, except for the ones containing “add/adding etc.” (as %ADD.VB.LEX is a synonym in INSTALL.VB.SYN).

ConditionMatched User InputUnmatched User Input
%HOW_DO_I_INSTALL.PHR !&> %ADD.VB.LEXHow do I install the driver?How can I add this gizmo?
Can you help me installing the plugging?

This example will match as long as what is matched by * isn’t also matched by COLORS.LIST.

ConditionMatched User InputUnmatched User Input
(%I_NEED.PHR >> %NUMBERS.LIST >> * >> %MY_PRODUCTS.LIST) !&> %COLORS.LISTI need 5 new bracketsI need five green brackets
I really need 7 new shelves

This case will match on all variants of “turn down”, “bring down” etc. except for “lower”.

ConditionMatched User InputUnmatched User Input
%TURN_DOWN.VB.SYN !&> %LOWER.VB.LEXTurn down the musicMay you lower the music?
Bring down the volume

Finally, this case will match as long as none of the words matched by the PHR is the first word in the input sentence.

ConditionMatched User InputUnmatched User Input
%HOW_DO_I_CANCEL.PHR !&> %FIRST_WORD.SCRIPTHello, can you help me cancel…How do I cancel…
Please, help me to cancel this!

Not Smaller Match operator

Official name: Not Smaller Match operator
Alternative names: Not Smaller Match condition, Smaller Match extended and condition
Representation !&<

Syntax

left_condition whitespace* '!&<' whitespace* right_condition

left_conditon = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Not Smaller Match operator is an enhanced member of the Negated And Operators family. For its condition to be fulfilled, the left-side condition must match on the user input. The right-side condition does not have to match, but if it does, it cannot consume all of the used words that the left-side condition consumed. The left-side condition has to be smaller or equal to the right-side condition (consume less or the same amount of used words).

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The Negated And operators section.

Examples

The first example matches user inputs with "worry"/"worried", etc., as long as it doesn't also match on "don't worry", etc.

ConditionMatched User InputUnmatched User Input
(%WORRY.VB.LEX !&< (%DO_NOT.VB.LEX >> %WORRY.VB.LEX))I worry oftenDon't worry!
I am worried

The following example matches user inputs with the word "great", as long as the input doesn't also match on "Great Britain".

ConditionMatched User InputUnmatched User Input
(%GREAT.ADJ.LEX !&< %GREAT_BRITAIN.NN.MUL)Great day!Great Britain
Great to see you

The next example matches on user inputs with the word "nice", as long as it doesn't also match on "To Nice", "Via Nice", etc.

ConditionMatched User InputUnmatched User Input
(%NICE.ADJ.LEX !&< ((%TO.FW.LEX / %FROM.FW.LEX / %VIA.FW.LEX / %BY.FW.LEX / %OVER.FW.LEX) >> %NICE.NN.LEX))A nice day!I am flying from Nice
Nice to see you.I go via Nice.

This example matches on user inputs with the word "love", as long as it doesn't also match on the sentence "for the love of..."

ConditionMatched User InputUnmatched User Input
(%LOVE.VB.LEX !&< (%FOR.FW.LEX >> %THE.FW.LEX >> %LOVE.VB.LEX >> %OF.FW.LEX))I love it!For the love of God!
Love is in the air

Not Overlap Match operator

Official name: Not Overlap Match operator
Alternative names: Not Overlap Match condition, Not Overlap Match extended and condition
Representation: !&~

Syntax

left_condition whitespace* '!&~' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Not Overlap Match Operator is a member of the Negated And Operators family. For its condition to be fulfilled, at least the left-side condition must be fulfilled. If the right-side condition is also fulfilled, then the entire condition is fulfilled if and only if at least one match of the left-side condition does not share any used words with any match of the right-side condition.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The Negated And operators section.

Examples

This is useful when you want a condition to match in general, except in a specific context which may contain both more or less used words than the condition.

For example, the user wants to match countries which not contain cardinal points.

ConditionMatched User InputUnmatched User Input
%COUNTRIES.LIST !&~ %COMPASS_POINTS.LISTI’ve been east of Papua New GuineaI’m visiting the South Sandwich Islands
Spain is south of FranceThe capital of North Korea is Pyongyang
In Canada English and French are spokenEast Timor has 8 airports
I live in PortugalThe West Bank is a territory, not a state

In the following example, the input “smart phone” etc. matches as long as none of the used words are part of the objects annotated as “device”.

ConditionMatched User InputUnmatched User Input
%SMART_PHONE.NN.SYN !&~ %$DEVICEMy smartphone received a notificationJohn’s iPhone
A smartphone just rangThe phone is in the kitchen

For instance, we may want to match requests to make a phone call while keeping out constructions like “call me X”.

ConditionMatched User InputUnmatched User Input
(%CAN_YOU_PHONE.PHR !&~ %MY_NAME_IS.PHR) + %NAMES.LISTPlease call AnnaPlease call me Paul
Can you call Pete?Can you call me Paul from now on?

Finally, this example does not match the question in the exact sequence “Did I open”.

ConditionMatched User InputUnmatched User Input
%I_OPEN.PHR !&~ %DID_I.VB.MULI openDid I open? (due to the overlapping “I”)
I open, don’t I?

Not Different Match operator

Official name: Not Different Match operator
Alternative names: Not Different Match condition, Not Different Match extended and condition
Representation: !&^

Syntax

left_condition whitespace* '!&^' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

General description

The Not Different Match Operator is a member of the Negated And Operators family. For its condition to be fulfilled, at least the left-side condition must be fulfilled. If the right-side condition is also fulfilled, then the entire condition is fulfilled if and only if at least one match of the left-side condition exists that does not share no used words with any match of the right-side condition (that is, at least one left-side match shares used words with every right-side match). Here matches of the right-side condition with no used words are not considered.

For more information on this operator’s Logical Behavior and Generated Match Data please refer to the beginning of The Negated And operators section.

Examples

An obvious use case is aiming for a match unless the input sentence contains a specific word. Another use case can be when you want to allow a word/word pattern to match if it occurs once in the sentence, but not if it occurs twice.

For example:

ConditionMatched User InputUnmatched User Input
(%FLOWERS.LIST &^ %POSITIVE_ADJECTIVES.LIST) !&^ (*flower & super*)The windflower is supernice!When a superhero marries they beflower his wife with wonderful rose petals
The mayflower is superbDandelions are beautiful when they reflower but I find them superficial
The sunflower is beautiful but too large for a jarI heard a supermodel say that tulips are excellent and they taste like cauliflower!
I heard that tulips are tasty, just like cauliflower
Roses are pretty
ConditionMatched User InputUnmatched User Input
(%HOW_DO_I_OPEN.PHR & %ACCOUNT.NN.LEX) !&^ %SAVING.NN.LEXHow do I open an account?How do I open a savings account?
How do I open an account for savings?
ConditionMatched User InputUnmatched User Input
(%I_LIKE.PHR &^ %FRUIT.LIST) !&^ %FRUIT.LISTI like applesI like apples and pears
I like pears

Other Compound operators

Followed By operator

Official name: Followed By operator
Alternative names: Followed By condition
Representation: +

Syntax

left_condition whitespace* '+' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Followed By Operator is a binary operator, that is, it takes two operands with the + operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Followed By Operator defines a Boolean condition on the two operand conditions; for this condition to be fulfilled, both operand conditions must be met so that the right operand condition is fulfilled somewhere within the sentence range of a left operand MI. That is, the used words of a right operand match must follow the used words of a left operand match, directly or with a gap.

Note: this does not take into account the used words generated by the right operand of a Maybe Condition within the operands of the Followed By Condition. See section Maybe-operator for details.

Logical behavior

The Followed By Condition is true if and only if

  • the left-side condition is true, and
  • the right-side condition is true on one or more of the MIs of the left-side condition.

Generated match data

The condition context is passed as it is to the left-side condition, then the DFB flag is deactivated and the condition context (with the MIs of the left-side condition) is passed to the right-side condition. Thus, the right-side condition either drops MIs or adds data to them. The MIs returned by the right-side condition are the final MIs generated by the Followed By Condition.

  • Range start: range start of the right-side MI
  • Used words: aggregation of used words from left-side and right-side MI
  • NLU scripts data: left-side NLU scripts, followed by the right-side NLU scripts
  • LOB variables: aggregation of LOB variables from left-side and right-side MI (right-side one taking precedence in case of variables with same name)
  • Longest match data: left-side longest match data, followed by the right-side longest match data

Examples

ConditionMatched User InputUnmatched User Input
i+love+youI love youYour parents love you, but I don’t
I don’t love youYou love the same person I do

Directly Followed By operator

Official name: Directly Followed By operator
Alternative names: Directly Followed By condition
Representation: >>

Syntax

left_condition whitespace* '>>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Directly Followed By Operator is a binary operator, that is, it takes two operands with the >> operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Directly Followed By Operator defines a Boolean condition on the two operand conditions; for this condition to be fulfilled, both operand conditions must be met so that the right operand condition is fulfilled at the begin of the sentence range of a left operand MI. That is, the first used word of a right operand match must directly follow the last used word of a left operand match, with no gap.

Note: this does not take into account the used words generated by the right operand of a Maybe Condition within the operands of the Directly Followed By Condition. See section Maybe-operator for details.

Logical behavior

The Directly Followed By Condition is true if and only if

  • the left-side condition is true, and
  • the right-side condition is true on one or more of the MIs of the left-side condition, with DFB flag activated

Generated match data

The condition context is passed as it is to the left-side condition, then the DFB flag is activated and the condition context (with the MI of the left-side condition) is passed to the right-side condition. Thus, the right-side condition either drops MIs or adds data to them. The MIs returned by the right-side condition are the final MIs generated by the Followed By Condition.

  • Range start: range start of the right-side MI
  • Used words: aggregation of used words from left-side and right-side MI
  • NLU scripts data: left-side NLU scripts, followed by the right-side NLU scripts
  • LOB variables: aggregation of LOB variables from left-side and right-side MI (right-side one taking precedence in case of variables with same name)
  • Longest match data: left-side longest match data, followed by the right-side longest match data.

Examples

ConditionMatched User InputUnmatched User Input
Big>>manThat’s a big manThat’s a big fat man
That’s a big big man
Directly Followed By operator

The Directly Followed By Operator > is deprecated and will be removed in a future release. Therefore, it should not be used anymore in newly written conditions. If it is being used in existing conditions, it should be replaced with the Directly Followed By Operator >>.

Syntax

left_condition whitespace* '>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Directly Followed By Operator is a binary operator, that is, it takes two operands with the > operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The behavior of the Directly Followed By Operator > is identical to the Directly Followed By Operator >>.

Not Directly Followed By operator

Official name: Not Directly Followed By operator
Alternative names: Not Directly Followed By condition
Representation: >

Syntax

left_condition whitespace* '!>>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Not Directly Followed By Operator is a binary operator, that is, it takes two operands with the !>> operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Not Directly Followed By Operator defines a logical interconnection condition on the two operand conditions; for this condition to be fulfilled, at least the left-side operand condition must be met. If the right-side operand condition is fulfilled too, then the entire condition is fulfilled if a left-side condition match exists so that its used words are not directly followed by the used words of a right-side condition match.

Note: this does not take into account the used words generated by the right operand of a Maybe Condition within the operands of the Not Directly Followed By Condition. See section Maybe-operator for details.

Logical behavior

The Not Directly Followed By Condition is true if and only if

  • the left-side condition is true and the right-side condition is false, or
  • both conditions are true and at least one MI of the left-side condition exists so that the right-side condition on this MI, with DFB flag activated, is false.

Generated match data

The condition context is passed only to the left-side condition. The right-side condition is always evaluated with a condition context with exactly one of the left-side MIs and the DFB flag activated.

The resulting MIs are all the MIs generated by the left-side operand that do not allow a match of the right-side operand. That is, the right-side condition is used to drop certain MIs of the left-side operand; otherwise it does not contribute in any way to the final MIs.

  • Range start: as set by the left-side condition
  • Used words: as set by the left-side condition
  • NLU scripts data: as set by the left-side condition
  • LOB variables: as set by the left-side condition
  • Longest match data: as set by the left-side condition

Examples

ConditionMatched User InputUnmatched User Input
Big!>>manThat’s a big womanThat’s a big man
That’s a big big man
Not Directly Followed By operator

The Directly Followed By Operator > is deprecated and will be removed in a future release. Therefore, it should not be used anymore in newly written conditions. If it is being used in existing conditions, it should be replaced with the Directly Followed By Operator >>.

Syntax

left_condition whitespace* '!>' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Not Directly Followed By Operator is a binary operator, that is, it takes two operands with the !> operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The behavior of the Not Directly Followed By Operator !> is identical to Not Directly Followed By Operator !>>.

Or operator

Official name: Or operator
Alternative names: Or condition
Representation: /

Syntax

left_condition whitespace* '/' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Or Operator is a binary operator, that is, it takes two operands with the / operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Or Operator defines a Boolean OR condition on the two operand conditions; for this OR condition to be fulfilled, at least one of the operand conditions must be met.

Logical behavior

The OR Condition is true if and only if at least one of the operand conditions is true.

Generated match data

Both operand conditions are evaluated independently of each other, by using a copy of the condition context passed in to the OR condition. The evaluation and MI updates of one operand condition are not affecting the evaluation and MI updates of the other operand condition.

The condition’s result is the collection of the MIs of both operand conditions, in which the left-side MIs are followed by the right-side MIs (that is, in “condition order”). A right-side operand MI is dropped if it has the same used words as a left-side operand MI.

  • Range start: as generated by the particular operand condition
  • Used words: as generated by the particular operand condition
  • NLU scripts data: as generated by the particular operand condition
  • LOB variables: as generated by the particular operand condition
  • Longest match data: as generated by the particular operand condition

Examples

ConditionMatched User InputUnmatched User Input
dog/cat/hamster/parakeet/goldfishI have a dogI don’t like cats or dogs
I used to have a cat
I don’t have a parakeet

Not operator

Official name: Not operator
Alternative names: Not condition
Representation: !

Syntax

'!' whitespace* condition

condition = atomic_condition | compound_condition

The Not Operator is a unary operator, that is, it takes the one operand that follows after the ! operator symbol.

General description

The Not Operator defines a Boolean NOT condition. For this condition to be fulfilled, the operand condition must not be met.

Conditions can be strengthened by using the Not operator to screen out sense-reversing words, such as "not" and "don't".

Logical behavior

The Not Condition is true if and only if at least one MI of the condition context exists for which the operand condition is false.

Generated match data

The operand condition is re-evaluated separately for each MI of the condition context. The resulting MIs are those for which the operand condition does not match. That is, the operand condition is used to drop certain MIs of the condition context; otherwise it does not contribute in any way to the final MIs.

  • Range start: not modified
  • Used words: not modified
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

ConditionMatched User InputUnmatched User Input
!catI have a dogI don’t have a cat
I love catsAre you a cat?
ConditionMatched User InputUnmatched User Input
Bird!dogI have a birdI don’t have a dog
I have a bird and hate dogsI have a bird, but no dog

See additional examples of using the Not (!) – operator in the section on parentheses.

Maybe operator

Official name: Maybe operator
Alternative names: Maybe condition
Representation: ~

Syntax

left_condition whitespace* '~' whitespace* right_condition

left_condition = atomic_condition | compound_condition
right_condition = atomic_condition | compound_condition

The Maybe Operator is a binary operator, that is, it takes two operands with the ~ operator symbol separating them. The left and right operands can be atomic or compound conditions.

General description

The Maybe Operator defines a condition that is fulfilled if the left operand condition is fulfilled. The right operand condition may be fulfilled also, but it doesn't have to. The left operand condition is evaluated in the condition context, while the right operand condition is always evaluated on the entire sentence.

The data (notably the used words) of all matches of the right operand condition is accumulated and then added to all matches of the left operand condition.

The most appropriate use of the Maybe Condition is in conditions that have limited the count of unused words to a low number. This limit allows to specify how many words besides those which have explicitly been specified in the condition may be contained within the sentence and still satisfy the total condition.

Logical behavior

The Maybe Condition is true if the left-side condition is true. The logical result of the right-side condition is not considered.

Generated match data

The condition context is passed only to the left-side condition. The right-side condition is always evaluated with an initial condition context, that is, it’s being tested on the entire sentence, with the DFB flag deactivated.

The resulting MIs are all the MIs generated by the left-side operand, merged with the accumulated data of all right-side condition MIs (if any).

Note: The range start of the final MIs is defined only by the left-side condition, even if the MI data merged in from right-side MIs contains used words after that range start. In other words, the MIs of the right-side condition do not change the sentence test range.

  • Range start: as set by left-side condition
  • Used words: used words of left-side MI plus used words of all right-side MIs
  • NLU scripts data: NLU scripts of left-side MI, followed by NLU scripts of all right-side MIs
  • LOB variables: aggregation of LOB variables from left-side MI and all right-side MIs (left-side one taking precedence in case of variables with same name)
  • Longest match data: left-side MI longest match data, followed by longest match data of all right-side MIs

Examples

This example shows how the Maybe Operator can trigger the right condition. In this case, the condition is matched if the phrase WHAT_IS_THE_PRICE.PHR occurs with 0 (no) other words not annotated as nouns.

Unused Words LimitConditionMatched User InputUnmatched User Input
0%WHAT_IS_THE_PRICE_OF.PHR ~ (* !&= %POS_NOUN.ANNOT)What is the price of it?What is the price of the car?
What is the cost then?What is the cost of the ticket?
What is the cost?This iPhone, what is the price of it?

Compound operator

Official name: Compound operator
Alternative names: Compound condition
Representation: |

Syntax

left_condition whitespace* compound_operator whitespace* right_condition

compound_operator = '|' | '§'
left_condition = word_condition
right_condition = word_condition

The Compound Operator is a binary operator, that is, it takes two operands with the | (or §) operator symbol separating them. The left and right operands can only be word conditions, without any condition options.

The two different operator symbols have no functional difference; they solely exist for convenient usage on most western language keyboards.

General description

The Compound Operator defines a condition that allows to recognize compound terms in a variety of forms. It may only be used to separate two words; it will not work with word parts or parenthetical expressions. The Compound Operator will recognize the two words if they appear as a compound word, if separated by a hyphen, or if used as two distinct words. In the latter case, however, the first word must appear directly before the second in the sentence, as if the Directly Followed By operator >> had been used. No words may appear between the two words.

More formally, the Compound Condition word1 | word2 is functionally equivalent to this condition:

word1word2 / ( word1 >> word2 ) / ( word1 >> "-" >> word2 )

Logical behavior

The Compound Condition is true if and only if its functionally equivalent condition (see above) is true.

Generated match data

The match data is generated as by evaluation of the above functionally equivalent condition.

  • Range start: as set by functionally equivalent condition
  • Used words: as set by functionally equivalent condition
  • NLU scripts data: as set by functionally equivalent condition
  • LOB variables: as set by functionally equivalent condition
  • Longest match data: as set by functionally equivalent condition

Examples

ConditionMatched User InputUnmatched User Input
*Doghouse*We have a doghouse
We have a dog-houseWe have a house and a dog
We have a dog and a house

Bracketed condition

Official name: Bracketed condition
Alternative names: Parentheses
Representation: ( )

Syntax

'(' whitespace* condition whitespace* ')'

condition = atomic_condition | compound_condition

General description

Parentheses do not define a condition in their own but are used to group and organize condition parts. They separate sets of individual operators as terms in their own right.

A Bracketed Condition also allows to attach optional NLU scripts and to apply condition options to condition parts as a whole. It supports the Longest Match Option and the Optional Match Option.

The result of a Bracketed Condition is the result of the entire condition wrapped by the parentheses.

Logical behavior

The logical result of a Bracketed Condition is the same as the logical result of the condition within the parentheses.

Generated match data

The match data is generated as by the wrapped condition.

  • Range start: as set by the wrapped condition
  • Used words: as set by the wrapped condition
  • NLU variables: as set by the wrapped condition
  • NLU scripts data: NLU scripts of the wrapped condition followed by the NLU scripts attached to the brackets
  • LOB variables: as set by the wrapped condition
  • Longest match data: as set by the wrapped condition

Examples

ConditionMatched User InputUnmatched User Input
I+like+my+ (dog/cat/ hamster/parakeet/goldfish)I like my dogI like cats
I like my catI like my dogs

The long list of pet names separated by the OR operator (/) becomes just one more term in the string of FOLLOWED-BY terms. I.e.

The term I
Followed by LIKE
Followed by MY
Followed by DOG OR CAT OR HAMSTER OR PARAKEET OR GOLDFISH

ConditionMatched User InputUnmatched User Input
((dogs/cats) + make + (good/great)+pets) &!(don’t / don’t / (do+not))Dogs make really good petsDogs do not make great pets
Cats make great pets when they’re happyCats don’t make good pets
Great pets, dogs make
Cats make great pets when they don’t scratch the coach
Cats do make great pets but not great guardians

This is:

The term DOGS OR CATS
Followed by MAKE
Followed by GOOD OR GREAT
Followed by PETS
AND
Not including DONT
OR DON’T
OR DO FOLLOWED BY NOT

When the AND, FOLLOWED-BY, OR, and MAYBE operators are used by themselves, parentheses are not necessary. Acceptable conditions would be:

i&like&my&dog
my+dog+is+english+sheepdog
dog/cat/bird/mouse/gerbil/hamster/frog
sheepdog~english

The NOT and COMPOUND operators "bind" stronger than the other operators. They may be combined with one of the other operators without the use of parentheses. Acceptable conditions would be:

i&like&my&!cat
my+dog+is+english+sheep|dog

Condition options

Condition options may be attached to conditions and serve to modify a certain aspect of the condition behavior. Condition options are not conditions in themselves, thus they cannot stand alone.

Syntax

condition ( ':' option )*

option = position_option | exact_option | longest_match_option | candidate_search_option

An option is separated from the condition (or the previous option) by a colon, without any whitespace. If the condition itself (e.g. a word condition) contains a colon, then the condition must be embedded into double quotes.

Multiple options may be applied to the same condition, in arbitrary order, but they may not be repeated. Depending on the particular condition only certain options may be applied; this is detailed in the following sections.

Position option

Official name: Position Option
Alternative names: Position modifier/flag

Syntax

word_testing_condition other_option* position_option other_option*

position_option = ':' [ '-' ] word_position
word_position = ( '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' )+
word_testing_condition = word_condition | word_part_condition | dynamic_condition
other_option = exact_option

The Position option can be applied to a word condition, word part condition or dynamic condition.

General description

In order for the constrained condition to be fulfilled, the sentence has to contain the word matched by the condition at the specified word_position. The first word on the sentence has position 1. A position relative to the sentence end may be specified by giving a negative number; the last word on the sentence having position -1.

Please note that position value 0 is invalid.

The Position Option may be combined with the Exact Option.

Logical behavior

The condition with an attached position option is true if and only if the sentence contains the condition at the specified word_position.

Generated match data

The Position option does not modify the match data generated by the constrained condition.

  • Range start: not modified
  • Used words: not modified
  • NLU scripts data: not modified
  • LOB variables: not modified
  • Longest match data: not modified

Examples

ConditionMatched User InputUnmatched User Input
name:3name:-3What’s my name?What is my name?
Her name is SmithHer name used to be…

Exact option

Official name: Exact Option
Alternative names: Exact modifier/flag

Syntax

word_testing_condition other_option* exact_option other_option*

exact_option = ':' ( 'E' | 'e' )
word_testing_condition = word_condition | wort_part_condition | dynamic_condition
other_option = position_option

The Exact Option can be applied to a Word Condition, Word Part Condition or Dynamic Condition.

General description

In order for the constrained condition to be fulfilled, the sentence has to contain the word exactly as spelled in the condition or scripting variable; thus, no normalization, spelling tolerance, auto-correction or simplification is applied.

Please note:

  • The Exact Option cannot be used directly on Language Objects; this means that a condition like %LANGUAGE_OBJECT:E is syntactically wrong. However, the Exact Option is applicable to words within Language Objects.
  • Furthermore, the Exact Option is not applicable to bracketed conditions: e.g. a condition like (one/two):E is invalid syntax and should be coded as (one:E/two:E).

The Exact Option may be combined with the Position Option.

Logical behavior

The condition with an attached Exact Option is true if and only if the sentence contains the specified word exactly as spelled in the condition or scripting variable.

Generated match data

The Exact Option does not modify the match data generated by the constrained condition.

  • Range start: Not modified
  • Used words: Not modified
  • NLU scripts data: Not modified
  • LOB variables: Not modified
  • Longest match data: Not modified

Examples

ConditionMatched User InputUnmatched User Input
horse:EhorseHorse
hoarse
ConditionMatched User InputUnmatched User Input
*house:EBoathouseBOATHOUSE
DogHouse
ConditionMatched User InputUnmatched User Input
Love*:ELovedloved
beloved

And if the variable Pet has a current value of Sheepdog:

ConditionMatched User InputUnmatched User Input
#Pet:ESheepdogsheep-dog
sheepdog

Longest Match option

Official name: Longest Match Option
Alternative names: Longest Match modifier/flag

Syntax

bracketed_condition other_option* longest_match_option other_option*

longest_match_option = ':' ( 'L' | 'l' )
other_option = optional_match_option

The Longest Match Option can only be applied to bracketed conditions.

General description

The Longest Match Option modifies the way the Engine selects the final matching instance when returning the final result (see the section Obtaining the final result).

When using the Longest Match Option, the Engine will first evaluate the full condition, and then will select the match instance with the maximum amount of used words among the MIs generated by the wrapped condition. This is called deferred Longest Match selection.

The Longest Match Option is mostly useful for the Or Operator, in case more than one of its alternatives matches.

The Longest Match Option may be combined with the Optional Match Option.

Logical behavior

The condition with an attached Longest Match Option is true if and only if its wrapped condition is true. The Longest Match Option only enforces the selection of the match with the maximum amount of used words among all matching instances of the wrapped condition.

Generated match data

The Longest Match Option does not modify the match data generated by the wrapped condition.

  • Range start: Not modified
  • Used words: Not modified
  • NLU scripts data: Not modified
  • LOB variables: Not modified
  • Longest match data: Longest match data is added when evaluating, and it is used for selecting the final match instance

Examples

ConditionUser inputUsed words
joe / (joe+doe)Joe Doe.Joe
(joe / joe+doe)):LJoe Doe.Joe Doe

Candidate Search option

Official name: Candidate Search Option
Alternative names: Candidate Search modifier/flag, Complete Evaluation option/modifier/flag

This option is deprecated and has no effect anymore because candidate search is always applied. It should be removed from existing conditions and not be used in new conditions.

Syntax

bracketed_condition other_option* candidate_search_option other_option*

candidate_search_option = ':' ( 'C' | 'c' )

The Candidate Search Option can only be applied to bracketed conditions.

General description

Since Teneo version 4.1 this condition option has no effect anymore and is deprecated. It should not be used in new conditions since it will be removed in a future version, thus users are encouraged to remove it from existing conditions.

Optional Match option

Official name: Optional Match Option
Alternative names: Optional modifier/flag

Syntax

bracketed_condition other_option* optional_match_option other_option*

optional_match_option = ':' ( 'O' | 'o' )
other_option = longest_match_option

The Optional Match Option can only be applied to bracketed conditions.

General description

The Optional Match Option marks the wrapped condition to be optional in the surrounding condition. Please, refer to the Optionality section (next) for full description of the effects of this option.

Examples

ConditionUser inputUsed words
%I_AM.PHR >> (%REALLY.ADV.SYN):O >> %HAPPY.ADJV.SYNI am happyI, am, happy
I am really happy.I, am, really, happy
(%I_WOULD_LIKE_TO.PHR + %TRAVEL.VB.SYN) &^ (%TO.FW.LEX >> %CITIES.LIST):O &^ (%FROM.FW.LEX >> %CITIES.LIST):OI want to travel.I, want, to, travel
I want to travel to York.I, want, to, travel, to, york
I want to travel to New York.I, want, to, travel, to, new, York
I want to travel from BarcelonaI, want, to, travel, from, Barcelona
I want to travel to Barcelona from Madrid.I, want, to, travel, to, Barcelona, from, Madrid.
%I_WANT_TO_ORDER.PHR + (%SOFT_DRINKS.LIST):OI want to order.I, want, to, order
I want to order a Pepsi.I, want, to, order, pepsi
I want to order a Pepsi max.I, want, to, order, pepsi, max

Optionality

By use of the Optional Match Option a condition part can be marked as optional. An optional condition part may match the sentence, but it doesn’t have to.

Optionality does not change the behavior of a condition part that’s marked as optional, but rather changes the behavior of a condition operator that has an optional condition as operand. This is expressed as a condition expansion rule that depends on the particular condition operator.

In order to ensure that the final condition match includes sentence words that are matched by an optional condition part, the Longest Match Option is implicitly applied by the expansion rules.

Condition expansion rules

A condition expansion rule expresses the behavior of a condition operator with optional operand(s). This expansion is applied during condition evaluation, and the condition AST is not changed.

Certain expansion rules propagate the optionality from an operand of the unexpanded condition to the total condition resulting from the expansion. Therefore, the expansion rules are applied recursively until further expansion is not possible anymore.

Whole condition

If optionality is applied to the entire condition, then the result either is the longest match of the non-optional condition, or a true but empty (no used words) match. That is, the total condition result is always true.

Note: This does not apply for the condition of a Language Object. See next rule.

OriginalExpanded
(optional_condition):O(optional_condition / {true}):L

Language Object condition

If optionality is applied to the entire condition of a Language Object, then the optionality is just propagated to all Language Object conditions that refer to this Language Object.

OriginalExpanded
%LOBLOB condition = (optional_condition):O(%LOB):OLOB condition = optional_condition

Operator /

If optionality is applied to only one operand of the Or operator, then the optionality is redundant. If optionality is applied to both operands then it is propagated to the condition, and the Longest Match Option is applied too.

OriginalExpanded
obligatory_condition / (optional_condition):Oobligatory_condition / optional_condition
(optional_condition1):O / (optional_condition2):O((optional_condition1 / optional_condition2):L):O

Operators &, +, >>, &=, &<, &>, &~, &^

If optionality is applied to only one operand of these operators, then the result is the matches of the non-optional condition plus the matches of the non-conditional operand. If optionality is applied to both operands, then it is propagated to the condition, and the condition result is the matches of the non-optional condition plus the matches of each operand alone. In all cases the Longest Match Option is applied too.

OriginalExpanded
(optional_condition):O OP obligatory_condition((optional_condition OP obligatory_condition) / obligatory_conditon):L
obligatory_condition OP (optional_conditon):O((obligatory_condition OP Optional_condition) / obligatory_condition):L
(optional_condition1):O OP (optional_condition2):O(( (optional_condition1 OP optional_condition2) / optional_condition1 / optional_condition2 ):L):O

Operators ~, !>>, !&=, !&<, !&>, !&~, !&^

Optionality applied to the right operand is redundant and therefore ignored. Optionality applied to the left operand is propagated to the condition, and the Longest Match Option is applied too.

OriginalExpanded
(optional_condition):O OP obligatory_condition((optional_condition OP obligatory_condition):L):O
obligatory_condition OP (optional_condition):Oobligatory_condition OP optional_condition
(optional_condition1):O OP (optional_condition2):O((optional_condition1 OP optional_condition2):L):O

Operator !

Optionality applied to the operand of the Not operator is redundant and therefore ignored.

OriginalExpanded
!(optional_condition):O!optional_condition

Bracketed condition

Optionality applied to a bracketed condition is just propagated outside of the parentheses.

OriginalExpanded
… ( (optional_condition):O) …… ( (optional_condition):O …

Examples

The following examples try to show how the optionality expansion rules are applied.

Original ConditionExpanded condition (applied)
(a/b/(c):O) !>> (d):O(a/b/(c):O) !>> (d):OInitial condition
(a/b/c) !>> (d):ORedundant optionality in the last operand of the Or operator removed
(a/b/c) !>> dRedundant optionality in the Not Directly Followed by operator removed
(a + (b):O ) &= c(a + (b):O ) &= cInitial condition
((a + b) / a):L &= cOptionality expanded for the Followed By operator
((a):O & b) >> c((a):O & b) >> cInitial condition
((a & b) / b):L >> cExpanding the optionality following the rule for the And operator
((a):O/(b):O) !&> c((a):O/(b):O) !&> c*Initial condition
((a/b):L):O !&> cOptionality propagated to operator level and longest match added as both operands of the Or are optional
(((a/b):L !&> c):L):OOptionality propagated to operator level and longest match added according to the expansion rules of the Not Bigger Match operator
(((a/b):L !&> c):L{true}):LOptionality expanded according to the whole condition rule
(a + (b):O ) &= c(a + (b):O ) &= cInitial condition
((a + b) / a):L &= cOptionality expanded for the Followed By operator
(a):O & (b):O(a):O & (b):OInitial condition
(((a & b)/a/b):L):OOptionality expanded according to the expansion rules for the And operator with optional operands
(((a & b)/a/b):L{true}):LOptionality expanded using the whole condition rule

NLU variables and attached scripts

Natural Language Understanding (NLU) variables and attached scripts are a way of capturing and/or condition on information from inputs.

There are two types of attached scripts:

  • Propagation scripts which are regular scripts, but with a dynamic script context that depends on where the script is defined. They allow users to assign values to NLU variables and propagate up NLU variables through the LOB/Entity hierarchy.
  • Predicate scripts which allow users to attach NLU/annotation variable value dependent constraints to conditions.

NLU variables are defined in Language Objects (LOB), entities and propagation scripts, and are explicitly propagated up through the LOB/Entity hierarchy by propagation scripts. From top-level conditions (which are those located in listeners, triggers and transitions) the NLU variables can be assigned to session and Flow variables through propagation scripts NLU variables can also be used by predicate scripts as variable value dependent constraints. Variable assignment, testing and propagation happens only after a successful full match of a condition.

Using NLU variables and attached scripts has several benefits. First, it eliminates the need to use listeners for capturing information in many common use cases. With NLU variables and propagation scripts, it is also possible to assign different values to a variable from within the same Language Object or Entity. In addition, each LOB/Entity condition instance has its own private NLU variable space, making it possible to collect information from several occurrences of the same Language Object/Entity in the same input in a predictable and efficient way. Finally, predicate scripts enrich the condition language with yet another fine-tuning level, making it possible to only match a condition if a variable fulfils a specified criterion.

NLU variable representation

Each Language Object or Entity can have a list of NLU variables (in addition to LOB variables for Language Objects). This list holds the NLU variables defined for the Language Object or Entity, together with a default value for each variable.

Unlike LOB variables, which can only hold a string, an NLU variable can have any type of object as a value. Just like with Flow variables or session variables, the default value is a script expression which is evaluated by the system; if the default value is empty, the script will evaluate to null.

An NLU variable cannot be named lob or _USED_WORDS, since it would conflict with special variables which hold that name (please see the following sections).

Propagation scripts

Syntax

Propagation_script = '^{' Propagation_script_text '}'

Propagation_script_text = ( any_char_but_right_brace | '\}' )*

Description

Unlike Language Object variables, NLU variables need to be explicitly propagated to the top level condition. This means that, even if a Language Object or Entity is matched during condition testing, its NLU variables are not automatically available in the condition matching result.

The variable propagation is handled by propagation scripts. Propagation scripts are not mandatory and can be attached to bracketed condition parts, Language Object references, Entity references, input annotation references or directly after an attached predicate script. They are attached to conditions with the caret symbol and embedded inside braces, like this:

tlml

1(new>>York)^{city="new_york"}
2

tlml

1%CITY^{city="new_york"}
2

Script Context

Propagation scripts are regular scripts, but the script context is dynamic and depends on where the script is defined.

There are two different types of context:

  • Top level conditions, which are those conditions that are not referred to by another condition, i.e. those attached to triggers, listeners and transitions
  • LOB/Entity conditions and Annotation conditions

Examples

In top-level conditions, NLU variable values are propagated to Flow/session variables.

ConditionResult
%I_WANT_TO_GO.PHR + (to >> %HAMBURG.NN.LEX)^{dest="Hamburg"}“Hamburg” would be propagated to the flow/session variable dest
%I_WANT_TO_GO.PHR + to >> (%CITIES.LIST^{dest=lob.city}):LThe CITIES.LIST NLU variable city would be propagated to the flow/session variable dest
%MY_NAME_IS.PHR >> (Tom/Dick/Harry)^{user_name = _USED_WORDS}“Tom”, “Dick” or “Harry” would be propagated to the flow/session variable user_name

In LOB conditions, values are propagated to NLU variables of that Language Object instead of Flow/session variables.

For instance, given the Language Object named CITIES.LIST, with the NLU variable city, we could write the following condition and script to propagate the city name:

tlml

1%HAMBURG.NN.LEX^{city="hamburg"} /
2%LOS_ANGELES.NN.LEX^{city="los_angeles"} /
3%ROME.NN.LEX^{city="rome"}
4

Access Rules for propagation scripts

The Access Rules for propagation scripts are described below.

Flow and session variables

  • Propagation scripts which are part of a Language Object/Entity condition do not have access to Flow or session variables. In order to assign the value of an NLU variable in a Language Object/Entity to a Flow or session variable, the value needs to be propagated up from the Language Object/Entity, via a top-level condition.
  • Propagation scripts which are part of a top-level condition have read and write access to the Flow variables which are in scope, all top-level conditions except for global listeners belong to a certain Flow and have access to that Flow’s Flow variables.
  • Propagation scripts which are part of a top-level condition have read and write access to session variables.

Language Object variables

  • Propagation scripts don’t have access to Language Object variables.

NLU variables

  • Propagation scripts attached directly to a Language Object/Entity reference in any condition have access to a special read-only variable called lob. This lob variable is a read-only map containing the NLU variable values for that Language Object instance.
  • Propagation scripts which are part of a Language Object/Entity condition have read and write access to the NLU variables of that Language Object/Entity.

Input Annotation variables

  • Propagation scripts attached directly to an input annotation reference in a condition have access to the input annotation variables via the lob variable, just like they would access NLU variables if attached to a Language Object/Entity.
  • The special input annotation variable value “_USED_WORDS” is mapped to a string containing the original form of the sentence words specified by the word indices attached to the input annotation, concatenated with a single space character.

Used words

  • All propagation scripts have access to the special variable _USED_WORDS, which holds a string representation of the original form of the words that make up the match, separated by whitespace.
  • The variable _USED_WORDS contains the used words of the sub-condition (e.g. bracket condition part, LOB condition, Entity condition or Annotation condition) to which the script is attached, not the used words of the entire condition. To get the used words of the entire match, _USED_WORDS can be used as an NLU variable default value (if it is a Language Object condition) or the entire condition needs to be embedded into brackets.
  • When using the used-words-related engine scripting API methods from propagation scripts, they return the used words that make up the match of the condition the propagation script is attached to.

Static methods

  • Just like any other script, all propagation scripts have access to globally defined classes (e.g. defined in the OnSolutionLoaded script).

Engine scripting API

  • All propagation scripts have read only access to engine scripting API.

Predicate scripts

Syntax

predicate_script = ':{' predicate_script_text '}'

Description

Predicate scripts enrich the condition language with yet another fine-tuning level, making it possible to attach NLU/annotation variable value dependent constraints to conditions, for instance: only match on an annotation if its variable value lies within a given range or only match on an Entity if a given NLU variable contains a specific value.

Predicate scripts are syntactically attached to conditions with the colon symbol and embedded inside braces, like this:

tlml

1%CITY.ENTITY:{lob.sCity=="New York"}
2

Just like propagation scripts, predicate scripts can be attached to bracketed condition parts, Language Object references, Entity references or input annotation references.

Script Context

A predicate script runs with its own local variables space that does not have access to session or Flow variables. Furthermore, can a predicate not propagate values, but the propagation will happen inside a LOB/Entity to which the predicate script is attached. A propagation script can however be attached in conjunction with the predicate script, but must follow after the predicate script, like this:

tlml

1%$NUMBER:{lob.numericValue>100}^{number=lob.numericValue}
2

The predicate script will be executed first. If it is evaluated to false, the match is disregarded, and the predicate script won't be executed. Since the predicate script is executed first it won't have access to the NLU variables of the current condition context.

Examples

ConditionMatched User InputUnmatched User Input
(*):{_USED_WORDS!="Hello"}Hi Welcome ThanksHello
ANIMALS.LIST:{lob.sAnimalType=="Pet"}Cat Dog KittenTiger Bull Wasp
%CITY.ENTITY:{lob.sCity=="New York"}New YorkLos Angeles Paris Barcelona
%NUMBER:{lob.numericValue>100}131 150 130099 4 0.4

Access Rules for predicate scripts

Flow and session variables

  • Predicate scripts don’t have access to Flow or session variables.

Language Object variables

  • Predicate scripts don’t have access to Language Object variables.

NLU variables

  • Predicate scripts attached directly to a Language Object/Entity reference in any condition have access to a special read-only variable called lob. This lob variable is a read-only map containing the NLU variable values for that Language Object/Entity instance.

Input Annotation variables

  • Predicate scripts attached directly to an input annotation reference in a condition have access to the input annotation variables via the lob variable, just like they would access NLU variables if attached to a Language Object/Entity.

Used words

  • All Predicate scripts have read access to the special variable _USED_WORDS, much like propagation scripts.

Attached script execution

Evaluation

The variable propagation occurs while the condition is being evaluated if required for the evaluation of a predicate script. Otherwise it occurs after the condition is fully matched.

Variables of the Script Context

For the top-level condition as well as for the condition of each Language Object/Entity, a separate script context is generated that provides a certain set of variables.

  • In the top-level context, session and Flow variables are visible for propagation script. Predicate scripts do not have access to session or Flow variables.
  • In a Language Object/Entity context, the NLU variables defined for the Language Object/Entity are visible for propagation scripts, but not the session nor Flow variables. Predicate scripts do not have access to the variables in this context.
  • In both types of context, the special variable _USED_WORDS is available and provides the used words for a Language Object reference, an Entity reference, an input annotation reference, or a bracketed expression.
  • Also in both contexts, the special variable lob is available, but only for the propagation/predicate scripts attached direct on Language Object/Entity references or input annotation reference. This variable refers to the context of the Language Object, Entity or input annotation to which the script is attached, and it contains the NLU variables generated in that context (note: a reference to an unknown NLU variable evaluates to null). Using the lob variable, the propagation script forwards NLU variables and used words from the Language Object, Entity or input annotation context to the context of the condition that contains the Language Object/Entity reference. The predicate script doesn’t forward the NLU variables but makes them available for evaluation within the script.

Attached script execution

Only the parts of the condition which had a match in the sentence are used for initialization of NLU variables and execution of attached scripts. This recursively applies to all Language Object/Entity conditions that were referred from the matching condition parts.

A script context is shared for all attached scripts within the same top-level, Language Object or Entity condition instance. A predicate script will be executed first if present. If it is evaluated to false/null, the match is disregarded, and the propagation script won't be executed. Propagation scripts are executed in an order that ensures that default values of the NLU variables of a referenced Language Object/Entity are evaluated first, followed by execution of all propagation scripts in the Language Object/Entity condition. This applies recursively, thus default values and propagation scripts are executed in a bottom-up manner. Finally, all the propagation scripts of the top-level condition are executed in order to forward NLU variables into session and Flow variables. Note: the top-level condition does not have default values for NLU variables.

The default values of the NLU variables of a Language Object/Entity are evaluated first, but in an unspecified order. Next the propagation scripts of the Language Object/Entity condition are executed, mostly in an unspecified order. It is however guaranteed that all propagation scripts within a bracketed expression are executed so that they are not interleaved with the execution of propagation scripts within other bracketed expressions or in the condition itself. In general, users should not implement scripts that rely on the execution order within a same condition.

If a Language Object/Entity reference doesn’t have a propagation script, nor a predicate script, then propagation processing for this Language Object/Entity is skipped. Thus, neither the default values of this Language Object’s/Entity's NLU variables nor any attached scripts that may exist in the Language Object/Entity condition are evaluated. This applies recursively for any Language Object/Entity reference in the Language Object/Entity condition.

Comments

Syntax

'==' ( any_text – '==' )* '=='

A comment is any text between a pair of comment delimiter symbols: two equal (=) characters; note that the text cannot contain the comment delimiter itself. Comments are ignored during parsing of the condition text and behave like whitespace, thus they may be placed anywhere between condition operators and their operands, but not within an atomic condition or between a condition and its condition options or attached scripts.

General description

Comments allow to place any text, like editing hints, within conditions. Comments are ignored by the Teneo Engine and have no effect on the condition behavior.

Example

tlml

1'(i&like&my&cat ==to be revised== ) / (my+dog+is+english+sheepdog)'
2

Reserved characters

The following characters are reserved in Conditions:

+/~(:§|"{^
&!\)#%@>}=

If reserved characters need to be used in conditions as a part of the sentence, in order to recognize them the condition text containing the reserved characters must be put into quotation marks (") .

Example

An & within a condition text not to be recognized as an operator:

tlml

1Roberts+"&"+Son
2

Glossary – Concept reference

Concept nameConcept description
ConditionConditions describe word patterns the system needs to recognize in sentences, in order to produce a match, which results in the system triggering a Flow, selecting a transition, etc.
Used WordsThe words in the sentence that matched the condition.
Sentence RangeThe part of the sentence that will be tested against the condition.
Range StartPointer to the first word of the sentence range.
OperatorIt defines the relationship between conditions.
Longest match dataData used by Engine if Longest Match Option is applied, for selecting the MI with the maximum amount of used words
FlowA Simple Flow consists of Language Code that will match the sentence and the answer to give to said input. It contains at least one transition and one node in sequence. A Complex Flow consists of more than one transition.
TransitionA transition is the representation of the move from one node to another and contains the condition that determines whether or not it is possible to move along that edge in the Flow.
ListenersListeners are a special construct that allows Teneo to listen to input in a transition, Flow or elsewhere and execute a script when a certain language condition is fulfilled.
Global ListenerGlobal Listeners are always active and are defined for use within one or more Flows.
Flow ListenerFlow Listeners are used in Flows.
Local ListenerLocal Listeners are used in a specific transition.
VariableVariables are normal groovy variables that store data or information that can be entered / computed and be referenced to from scripts.
Session VariableSession variables are accessible from all Flows.
Flow VariableFlow variables are defined as belonging to one Flow and can only be accessed when the Flow is active.
Standard AnnotationsWith all language configurations, standard annotations are set by the input processors of the Teneo Engine. See the input processor documentation for more details._QUESTION (a question mark (?) appears in the input)_EXCLAMATION (an exclamation point (!)appears in the input)_DBLQUOTE (a quotation mark (") appears in the input)_QUOTE (single quotation mark (') appear in the input)_BRACKETPAIR (a pair of brackets - ( ) or [ ] - appear in the input)_NONSENSE (the input contains nonsense text, such as 'asdf', wgwgwwgg', 'xxxxx')_EMPTY (the input contain no text)_BINARY (the input consists of only 0s and 1s)_QT3 (triple question marks (???) appear in the input)_EM3 (triple exclamation marks (!!!) appear in the input)
NLUNatural Language Understanding
LOBLanguage Object. A Language Object is a named condition that usually represents a semantic meaning of a word or combination of words in a sentence.
ASTAbstract Syntax Tree.
MIMatch Instance