nBest

When several types of activation rules are used together in one script, they are triggered in the following order: patterns first, then intents.

In scripts requiring complex mechanics for picking the right activation rule, you can access the rules with the highest probability scores from any part of the script via $context.nBest.

Configuration file

By default, $context.nBest contains only one activation rule.

You can change the number of provided rules. Specify the number in the nlp.nbest parameter of the configuration chatbot.yaml file:

nlp:
  nbest: 3

Array contents

The nBest key is available in the $context object, which represents the current runtime context of the request. $context.nBest is an array of objects that represent the rules for transferring to states.

The first object in the $context.nBest array is chosen based on whether or not custom activation rule selection is enabled in the script via the selectNLUResult handler:

• If the handler is defined, the object assigned by the handler to $context.nluResults.selected will also appear first in $context.nBest.
• If not, the rule which triggered the transition to the target state will go first, according to the standard priority of patterns over intents.

The objects on the second and any subsequent places will be placed in descending order based on their score value.

caution

Therefore, the score of the second rule might be higher than that of the first one.

Activation rule type filter

If you want to have access only to activation rules of a specific type, add one or several of the following properties to chatbot.yaml:

nlp:
  nbestPatterns: 1
  nbestIntents: 2

nbestPatterns sets the length of $context.nBestPatterns — an array of activation rules only triggered by patterns. The array is unavailable if this property is omitted. nbestIntents works the same with respect to intents.

Script

Without selectNLUResult

Consider a simple script where both types of activation rules are used. The /hello intent is trained on the hello phrase:

init:
    bind("postProcess", function($context) {
        log(toPrettyString($context.nBest));
    });

theme: /

    state: Pattern
        q!: hello

    state: Intent
        intent!: /hello

In the init block, a postProcess handler prints the contents of $context.nBest to the log. Upon a request hello, the following array will be logged:

[
  // The first object is the pattern activation rule
  {
    "clazz": "/Pattern", // The path to the state that matched the request
    "score": 1, // The probability score of the triggered activation rule
    "pt": {
      // Alias for `parseTree`
    },
    "debugInfo": {
      // Technical information about the triggered rule
    },
    "ruleType": "pattern", // The type of the triggered rule
    "parseTree": {
      // Full request parse tree
    },
    "targetState": "/Pattern", // The state where the transition was made
  },
  // The first object is the intent activation rule
  {
    "clazz": "/Intent",
    "score": 1,
    "pt": {
      // ...
    },
    "debugInfo": {
      // ...
    },
    "ruleType": "intent",
    "parseTree": {
      // ...
    },
    "targetState": "/Intent"
  }
]

With selectNLUResult

Now let’s expand the init block with a handler which changes the order of triggering activation rules so that intents have maximum priority:

bind("selectNLUResult", function($context) {
    if ($context.nluResults.intents.length > 0) {
        $context.nluResults.selected = $context.nluResults.intents[0];
        return;
    }

    if ($context.nluResults.patterns.length > 0) {
        $context.nluResults.selected = $context.nluResults.patterns[0];
    }
});

If we now repeat the previous request, the order of elements in $context.nBest will change:

[
  {
    "clazz": "/Intent",
    "score": 1
    // ...
  },
  {
    "clazz": "/Pattern",
    "score": 1
    // ...
  }
]