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

To enable filling up $context.nBest, add the following section to the chatbot.yaml configuration file:

nlp:
  nbest: 3

tip

In the nlp.nbest value, specify the required number of activation rules you need to access from the script. The default value is 1.

Array contents

After setting up the configuration file, the nBest key becomes available in the current execution $context object.

tip

The value of $context.nBest is an array of nlp.nbest objects representing state activation rules with the highest probability score.

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

Situations where the score of the second rule is higher than that of the first are therefore possible.

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
    // ...
  }
]