Intent Matching

Overview

As we discussed in Data Model section the processing logic of the data model is encoded in intents and their callbacks. Sections below will explain how to declare an intent and how to develop a callback method when its intent is matched.

Intent-Based Matching

The intent matching is based on an idea of defining one or more templates for user input and let the algorithm choose the best matching one given the user input. Such template is called an intent. Each intent defines a pattern of the user input and associated action to take when that pattern is detected and selected as a best match. While selecting the best matching intent NLPCraft uses sophisticated NLP algorithms. When more than one intent matches the user input - the system selects the most specific one as its best match.

In NLPCraft intents are specified using the following Java annotations:

Here's a couple of examples of intent declarations to illustrate the basics of intent declaration and usage.

An intent from Light Switch Scala example:

            @NCIntent("intent=act conv=false term(act)={groups @@ 'act'} term(loc)={trim(id) == 'ls:loc'}*")
            @NCIntentSample(Array(
                "Turn the lights off in the entire house.",
                "Switch on the illumination in the master bedroom closet.",
                "Get the lights on.",
                "Please, put the light out in the upstairs bedroom.",
                "Set the lights on in the entire house.",
                "Turn the lights off in the guest bedroom.",
                "Could you please switch off all the lights?",
                "Dial off illumination on the 2nd floor.",
                "Please, no lights!",
                "Kill off all the lights now!",
                "No lights in the bedroom, please."
            ))
            def onMatch(
                @NCIntentTerm("act") actTok: NCToken,
                @NCIntentTerm("loc") locToks: List[NCToken]
            ): NCResult = {
                ...
            }
        

NOTES:

• The intent is defined in-place using @NCIntent annotation.
• A term match is defined as one or more tokens. Term can be optional if its min quantifier is zero.
• A non-conversational intent act has one mandatory term and another that can match zero or more tokens with method onMatch(...) as its callback.
• Method onMatch(...) will be called when this intent is selected as the best match.
• Note that terms have min=1, max=1 quantifiers by default, i.e. one and only one.
• First term defines any single token that belongs to the group act. Note that model elements can belong to multiple groups.
• Second term would match zero or more tokens with ID ls:loc. Note that we use function trim on the token ID.
• Note that both terms have IDs (act and loc) that are used in onMatch(...) method parameters to automatically assign terms' tokens to the formal method parameters using @NCIntentTerm annotations.

In the following Alarm Clock Java example the intent is defined in JSON model definition and referenced in Java code using @NCIntentTerm annotation:

            {
                "id": "nlpcraft.alarm.ex",
                "name": "Alarm Example Model",
                "version": "1.0",
                "enabledBuiltInTokens": [
                    "nlpcraft:num"
                ],
                "elements": [
                    {
                        "id": "x:alarm",
                        "description": "Alarm token indicator.",
                        "synonyms": [
                            "{ping|buzz|wake|call|hit} {me|up|me up|*}",
                            "{set|*} {my|*} {wake|wake up|*} {alarm|timer|clock|buzzer|call} {up|*}"
                        ]
                    }
                ],
                "intents": [
                    "intent=alarm term={id=='x:alarm'} term(nums)={id=='nlpcraft:num' && ~nlpcraft:num:unittype=='datetime' && ~nlpcraft:num:isequalcondition==true}[0,7]"
                ]
            }
        

            @NCIntentRef("alarm")
            @NCIntentSample({
                "Ping me in 3 minutes",
                "Buzz me in an hour and 15mins",
                "Set my alarm for 30s"
            })
            private NCResult onMatch(
               NCIntentMatch ctx,
               @NCIntentTerm("nums") List<NCToken> numToks
            ) {
               ...
            }
        

NOTES:

• Intent is defined in the external JSON model declaration (see line 19 in JSON file).
• This intent is referenced by annotation @NCIntentRef("alarm") with method onMatch(...) as its callback.
• This example defines a non-conversational intent with two terms both of which have to found for the intent to match.
• Method onMatch(...) will be called when this intent is the best match detected.
• Note that terms have min=1, max=1 quantifiers by default.
• First term is defined as a single mandatory (min=1, max=1) user token with ID x:alarm whose element is defined in the model.
• Second term is defined as a zero or up to seven numeric built-in nlpcraft:num tokens that have unit type of datetime and are single numbers. Note that Alarm Clock model allows zero tokens in this term which would mean the current time.
• Given data model definition above the following sentences will be matched by this intent:
  • Ping me in 3 minutes
  • Buzz me in an hour and 15mins
  • Set my alarm for 30s

Matching Logic

In order to understand the intent matching logic lets review the overall user request processing workflow:

• Step: 0
  

  Server receives REST call /ask or /ask/sync that contains the text of the sentence that needs to be processed.

• Step: 1
  

  At this step the server attempts to find additional variations of the input sentence by substituting certain words in the original text with synonyms from Google's BERT dataset. Note that server will not use the synonyms that are already defined in the model itself - it only tries to compensate for the potential incompleteness of the model. The result of this step is one or more sentences that all have the same meaning as the original text.

• Step: 2
  

  At this step the server takes one or more sentences from the previous step and tokenizes them. This process involves converting the text into a sequence of enriched tokens representing named entities. This step also performs the initial server-side enrichment and detection of the built-in named entities.

  The result of this step is a sequence of converted texts, where each element is in itself a sequence of tokens with each token representing a named entity. These sequences are send down to the data probe that has requested data model deployed.

• Step: 3
  

  This is the first step of the probe-side processing. At this point the data probe receives one or more sequences of tokens. Probe then takes each sequence and performs the final enrichment by detecting user-defined elements additionally to the built-in tokens that were detected on the server during step 2 above.

• Step: 4
  

  This is an important step for understanding intent matching logic. At this step the data probe takes sequences of tokens generated at the last step and comes up with a definitive parsing variants. A parsing variant is a sequence of tokens that is free from overlapping and parsing ambiguity. Typically, a single sequence of tokens can produce one (always) or more parsing variants.

  Let's consider the input text 'A B C D' and the following elements defined in our model:

                  "elements": [
                      {
                          "id": "elm1",
                          "synonyms": ["A B"]
                      },
                      {
                          "id": "elm2",
                          "synonyms": ["B C"]
                      },
                      {
                          "id": "elm3",
                          "synonyms": ["D"]
                      }
                  ],
                  

  All of these elements will be detected but since two of them are overlapping (elm1 and elm2) there should be two parsing variants at the output of this step:

  1. elm1('A', 'B') freeword('C') elm3('D')
  2. freeword('A') elm2('B', 'C') elm3('D')

  Note that at this point the system cannot determine which of these variants is the best - there's simply not enough information at this stage. It can only be determined when matched against model's intents - which will happen in the next step.

• Step: 5
  

  At this step the actual matching between intents and variants happens. Each parsing variant from the previous step is matched against each intent. Each matching pair of a variant and an intent produce a match with a certain weight. If there are no matches at all - an error is returned. If there are matches, the match with the biggest weight is selected as a winning match. The intent's callback from the winning match is than called.

  Although details on exact algorithm on weight calculation are too complex, here's the general guidelines on what determines the weight of the match between a parsing variant and the intent:

  • A match that captures more tokens has more weight than a match with less tokens. As a corollary, the match with less free words (i.e. unused words) has bigger weight than a match with more free words.
  • Tokens for user-defined elements are more important than built-in tokens.
  • A more specific match has bigger weight. In other words, a match that uses token from the conversation context (an STM) has less weight than a match that only uses tokens from the current request. In the same way older tokens from the conversation produce less weight than the younger ones.

Intent DSL

Regardless of how intent is defined - directly in @NCIntent annotation or in external model declaration - it follow the exactly the same syntax (here's a full ANTRL4 grammar).

Intent DSL grammar can be informally described using the following example (order of individual declarations is important):

             intent=my_intent
                conv=true
                ordered=true
                flow='id* >> (id2|id3)[2,3]'
                term(term1)={group @@ 'my_group'}?
                term(term2)={trim(partId.partAlias.id) == 'token1:id'}[1,3]
        

intent=my_intent

Mandatory intent ID. Any arbitrary unique string matching the following template: (UNDERSCORE|[a-z]|[A-Z])+([a-z]|[A-Z]|[0-9]|COLON|MINUS|UNDERSCORE)*

conv=true

Optional. Whether or not this intent supports conversation. Default is true.

ordered=true

Optional. Whether or not this intent is ordered. Default is false. For ordered intent the specified order of terms is important for matching this intent. If intent is unordered its terms can be found anywhere in the input text and in any order. Note that ordered intent significantly limits the user input it can match. In most cases the ordered intent is only applicable to processing formal strict grammar (like a programming language) and unsuitable for natural language processing.

flow='id* >> (id2|id3)[2,3]'

Optional. Dialog flow is a history of previously matched intents to match on. If provided, the intent will match not only on the current user input but also on the history of the previously matched intents.

Dialog flow pattern consists of one of multiple intent IDs separated by >> symbol ordered from most recent to the oldest. Multiple IDs should be placed in ( ) brackets and separated by | symbol. Each group of IDs can have an optional quantifier (e.g. [2,3]) for how many times this intent should appear in matching history:

• [n,m] - intent should appear at least n times and at most m times.
• * is equal to [0,∞]
• + is equal to [1,∞]
• ? is equal to [0,1]
• No quantifier defaults to [1,1]

For the dialog flow to match the history of the matched intents (for given user and the data model) should match the dialog flow pattern. Note that if dialog flow is defined and it doesn't match the history the terms of the intent won't be tested at all.

term(term1)={group @@ 'my_group'}?
term(term2)={trim(partId.partAlias.id) == 'token1:id'}[1,3]

Term, also known as a slot, is a building block of the intent. Term has optional ID, predicate and quantifiers. It can represent one or more tokens, sequential or not, detected in the user input. Intent has a list of terms (always at least one) that all have to be found in the user input for the intent to match. Note that term can be optional if its min quantifier is zero. Whether or not the order of the terms is important for matching is governed by ordered=true parameter.

Term ID (term1 and term2) is optional, and when provided, is used by @NCIntentTerm annotation to link term's tokens to a formal parameter of the callback method. Note that term ID follows the same lexical rules as intent ID.

Inside of curly brackets { } is a token DSL expression: group @@ 'my_group' and trim(partId.partAlias.id) == 'token1:id'. Note that exactly the same syntax is used for token DSL as well as for intent DSL for defining a token predicate. Consult token DSL documentation for details on its syntax.

? and [1,3] define an inclusive quantifier for that term (how many time this term should appear for it to be considered found). You cal also use the following abbreviations:

• * is equal to [0,∞]
• + is equal to [1,∞]
• ? is equal to [0,1]
• No quantifier defaults to [1,1]

Intent Callback

Whether the intent is defined directly in @NCIntent annotation or indirectly via @NCIntentRef annotation - it is always attached to a callback method:

• Callback can only be an instance method on the class implementing NCModel interface.
• Method must have return type of NCResult.
• Method can have zero or more parameters:
  • Parameter of type NCIntentMatch, if present, must be first.
  • Any other parameters (other than the first optional NCIntentMatch) must have @NCIntentTerm annotation.
• Method must support reflection-based invocation.

@NCIntentTerm annotation marks callback parameter to receive term's tokens. This annotations can only be used for the parameters of the callbacks, i.e. methods that are annotated with @NCIntnet or @NCIntentRef. @NCIntentTerm takes a term ID as its only mandatory parameter and should be applied to callback method parameters to get the tokens associated with that term (if and when the intent was matched and that callback was invoked).

Depending on the term quantifier the method parameter type can only be one of the following types:

For example:

            @NCIntent("intent=id term(termId)={id == 'my_token'}?")
            private NCResult onMatch(
               @NCIntentTerm("termId") Optional<NCToken> myTok
            ) {
               ...
            }
        

NOTES:

• Term termId has [0,1] quantifier (it's optional).
• The formal parameter on the callback has a type of Optional<NCToken> because the term's quantifier is [0,1].
• Note that callback doesn't have an optional NCIntentMatch parameter.

NCRejection and NCIntentSkip Exceptions

There are two exceptions that can be used by intent callback logic to control intent matching process.

When NCRejection exception is thrown by the callback it indicates that user input cannot be processed as is. This exception typically indicates that user has not provided enough information in the input string to have it processed automatically. In most cases this means that the user's input is either too short or too simple, too long or too complex, missing required context, or is unrelated to the requested data model.

NCIntentSkip is a control flow exception to skip current intent. This exception can be thrown by the intent callback to indicate that current intent should be skipped (even though it was matched and its callback was called). If there's more than one intent matched the next best matching intent will be selected and its callback will be called.

This exception becomes useful when it is hard or impossible to encode the entire matching logic using just declarative intent DSL. In these cases the intent definition can be relaxed and the "last mile" of intent matching can happen inside of the intent callback's user logic. If it is determined that intent in fact does not match then throwing this exception allows to try next best matching intent, if any.

Note that there's a significant difference between NCIntentSkip exception and model's onMatchedIntent(...) callback. Unlike this callback, the exception does not force re-matching of all intents, it simply picks the next best intent from the list of already matched ones. The model's callback can force a full reevaluation of all intents against the user input.

NCIntentMatch Interface

NCIntentMatch interface can be passed into intent callback as its first parameter. This interface provide runtime information about the intent that was matched (i.e. the intent with which this callback was annotated with). Note also that intent context can only be the 1st parameter in the callback, and if not declared as such - it won't be passed in.

Intent Examples

Here's number of intent examples with explanations. These intents can be defined directly in @NCIntent annotation or in external JSON or YAML mode definition.

Example 1:

            intent=id1
                term={id == 'x:id'}
                term(nums)={id == 'nlpcraft:num' && lowercase(~nlpcraft:num:unittype) == 'datetime'}[0,2]
        

NOTES:

• Intent has ID id1.
• Intent uses default conversational support (true) and default order (false).
• Intent has two terms that have to be found for the intent to match. Note that second term is optional as it has [0,2] quantifier.
• First term matches any single token with ID x:id.
• Second term can appear zero, once or two times and it matches token with ID nlpcraft:num with nlpcraft:num:unittype metadata property equal to 'datetime' string.
• Function lowercase used on nlpcraft:num:unittype metadata property value. Note that built-in functions can only be used on left values.
• Note that since second term has ID (nums) it can be references by @NCIntentTerm annotation by the callback formal parameter.
• Read more on built-in functions and token metadata properties in Token DSL section.

Example 2:

            intent=id2
                conv=false
                flow='id1* >> (id1|id2)[1,2]'
                term={id == 'mytok' && signum(~score['best']) != -1}
                term={(groups @@ 'actors' || groups @@ 'owners') && size(partAlias.~text) > 10}
        

NOTES:

• Intent has ID id2.
• Intent overrides default conversational support via conv=false and uses default order (false).
• Intent has dialog flow pattern to match: 'id1* >> (id1|id2)[1,2]'. It expect zero or more intents id1 to matched immediately prior to this one and either one or two of id1 or id2 intents before that.
• Intent has two terms. Both terms have to be present only once (their implicit quantifiers are [1,1]).
• First term should be a token with ID mytok and have metadata property score of type map. This map should have a value with the string key 'best'. signum of this map value should not equal -1. Note that built-in functions (i.e. signum) can only be used on the left values.
• Second term should be a token that belongs to either actors or owners group. It should have a part token whose Token DSL expression should have alias partAlias. That part token should have metadata property text of type string or collection. The length of this string or collection should be greater than 10.
• Read more on built-in functions and token metadata properties in Token DSL section.