@servisbot/npm-sb-intents

Contains Shared Logic Around the Handling of Intents from the Various NLP Providers

Usage no npm install needed!

<script type="module">
  import servisbotNpmSbIntents from 'https://cdn.skypack.dev/@servisbot/npm-sb-intents';
</script>

README

sb-npm-intents

Contains Shared Logic Around the Handling of Intents from the Various NLP Providers

Install

npm install @servisbot/npm-sb-intents

Validation

Supported Validators

  • Lex
  • DialogFlow

Adding a Validator

  • Add your validator class to src/validation
  • Add your validator to the validators object in src/index.js
    module.exports = {
    validators: {
        Lex,
        DialogFlow,
        YOUR_NEW_VALIDATOR
    }
};
  • Each validator in the SDK has the following methods in common, make sure your class implements these methods:
    • createAliasWarning(alias) - Creates a NLP specific warning for the alias
    • isValidAlias(alias) - Checks if the alias is valid for the specific NLP
    • sanitizeAlias(alias) - Sanitizes the alias to be accepted by the NLP
    • containsValidSlots(utterance) - Checks if the utterance contains slots valid for the specific NLP
    • isValidUtterance(utterance) - Checks if an utterance is valid for the specific NLP
    • sanitizeUtterance(utterance) - Sanitizes the utterance to be accepted by the NLP
    • validateUtterances(utterances) - Runs over all utterances, validates the utterances, and sanitizes invalid utterances and adds warnings about utterances with invalid characters

Validator Usage

To use a validator require it as shown below:

const { validators } = require('@servisbot/npm-sb-intents');

To create an instance of a validator do the following:

const lexValidator = new validators.Lex();
const dialogFlowValidator = new validators.DialogFlow();
const servisbotValidator = new validators.ServisBot();

Lex Validator

  • Alias must start with a letter and contain letters and non-consecutive underscores only.
  • Utterance must start with a letter, may only contain letters and white space (with the exception of slots)
    • Utterance can contain numbers but the will be converted to their word format. Example "hello 1 2 3" will be converted to "hello one two three"
  • Slots must be surrounded by curly braces and can contain alphabetic characters and underscores Sanitize Alias Sample:
const lexValidator = new validators.Lex();
const invalidAlias = 'i-am-invalid123';
const sanitizedAlias = lexValidator.sanitizeAlias(invalidAlias);
assert(sanitizedAlias, 'i_am_invalid')  // replaced hyphens with underscores, removed numbers

Sanitize Utterances Sample:

const lexValidator = new validators.Lex();
const utterances = [
    {
        text: 'i am valid'
    },
    {
        text: '1 2 3-invalid'
    }
];
const sanitizedUtterances = utterances.map((utterance) => lexValidator.sanitizeUtterance(utterance));

Expected:

[
    {
        text: 'i am valid'
    },
    {
        text: 'one two three invalid'  //removed hyphens replaced numbers with their word format, replaced hyphen with space and stripped consecutive white spaces
    }
]

Dialog Flow Validator

  • Alias may contain any UTF-8 character
  • Utterance may contain any UTF-8 character
  • Dialog Flow does not currently need to sanitize aliases or utterances

ServisBOT Validator

  • Intent alias must only contain letters, numbers, underscores and hyphens
  • Utterance may contain any UTF-8 character, but must have valid slots.
    • Valid slots a valid slot is letters, numbers, underscores, hyphens in between two curly braces
    • Invalid slots such as slots missing opening or closing curly brackets will have their curly brackets stripped fom the utterance.

Sanitize Alias Sample:

const lexValidator = new validators.Lex();
const invalidAlias = 'i-am-invalid123*{';
const sanitizedAlias = lexValidator.sanitizeAlias(invalidAlias);
assert(sanitizedAlias, 'i-am-invalid123')  // all characters that are not letters,numbers, underscores or hyphens

Sanitize Utterances Sample:

const servisbotValidator = new validators.ServisBot();
const utterances = [
    {
        text: 'i am valid'
    },
    {
        text: '1 2 3 {invalid'  // invalid slot in utterance
    }
];
const sanitizedUtterances = utterances.map((utterance) => servisbotValidator.sanitizeUtterance(utterance));

Expected:

[
    {
        text: 'i am valid'
    },
    {
        text: 'one two three invalid'  // removed invalid bracket for slot
    }
]

Lift & Shift

The module supports the ability to take nlp specific intent formats and convert them to sb intents.

Watson

To convert a watson skill to sb intents provide stringified JSON to the Watson lift and shift object and call the shift function e.g.

const { liftShift } = require('@servisbot/npm-sb-intents');
const watsonSkill = {
    intents: [
    {
        intent: 'queue_jump',
        examples: [
        {
            text: 'what is queue jump'
        },
        {
            text: 'what is queuejump'
        },
        {
            text: 'tell me about queue jump'
        }
        ],
        description: 'Queue Jump'
    },
    ],
    entities: [
    {
        entity: 'sys-number',
        values: []
    }
    ],
    dialog_nodes: [
    {
        type: 'standard',
        title: 'queue_jump',
        output: {
        generic: [
            {
            values: [
                {
                text: 'some text'
                }
            ],
            response_type: 'text',
            selection_policy: 'sequential'
            },
        ]
        },
        conditions: '#queue_jump',
        dialog_node: 'node_43_1584721497513',
        previous_sibling: 'node_42_1584721497513'
    }
    ],
    counterexamples: [],
    learning_opt_out: false,
    name: 'AskBotty',
    language: 'en',
    description: ''
};
const WatsonLiftShift = liftShift.watson;
const botName = 'botty';
const watsonLiftShift = new WatsonLiftShift(watsonSkill, botName);
const sbIntents = watsonLiftShift.shift();

Rasa

All intents must have at least one example in the nlu to be created. Intents that are the first in at least one story will be created as public, otherwise they will be created as private. To convert a rasa nlu.yml file to sb intents provide the nlu.yml file contents as a string to the Rasa lift and shift object and call the shift function. e.g.

const { liftShift } = require('@servisbot/npm-sb-intents');
const rasaNluYmlString = `
version: "2.0"

nlu:
- intent: car_rental
  examples: |
    - I would like to rent a car
    - can i rent a car
    - how much is it to rent a car

- intent: hotel_booking
  examples: |
    - can i book a hotel for the night
    - where can i book a hotel
    - can you suggest a hotel to book
`;
const rasaStoriesYmlString = `
version: "2.0"

stories:

- story: car rental path
  steps:
  - intent: car_rental
  - action: utter_greet

- story: hotel booking path
  steps:
  - intent: hotel_booking
  - action: utter_greet
`;
const RasaLiftShift = liftShift.rasa;
const botName = 'botty';
const rasaLiftShift = new RasaLiftShift({ stories: rasaStoriesYmlString, nlu: rasaNluYmlString}, botName);
const sbIntents = rasaLiftShift.shift();

DialogFlow

Converts DialogFlow formatted intents into ServisBOT intents. DialogFlow followup intents are scoped as "private", all other intents are scoped as "public".

To convert a DialogFlow intents to sb intents you must provide the list of DialogFlow intents to the DialogFlow lift and shift object and call the shift function. e.g.

const { liftShift } = require('@servisbot/npm-sb-intents');

const DialogFlowLiftShift = liftShift.dialogflow;
const dialogFlowIntents = [
    name: 'some-df-intent-name',
    responses: [
    {
      messages: [
        {
          speech: [
            'This is a response',
            'Response variant here',
            'One more response variant'
          ],
        }
      ]
    }
  ],
  utterances: [
      {
        data: [
          {
            text: 'auto claim new',
            userDefined: false
          }
    ]
    },
    {
        data: [
          {
            text: 'auto insurance claim',
            userDefined: false
          }
        ]
    },
  ]
]
const botName = 'botty';
const dialogFlowLiftShift = new DialogFlowLiftShift({ dialogFlowIntents }, botName);
const sbIntents = dialogFlowLiftShift.shift();

Please note that DialogFlow projects are formatted with an intent per file with the intent's utterances in it's own file too. The DialogFlow lift and shift class expects the client to have mapped the raw utterances from DialogFlow onto the raw intent definition that the utterances belong to. This can be seen in the example above, where the intent definition includes an utterances key which is an array of the raw DialogFlow utterances for that DialogFlow intent. It is up to the client to format the data correctly before passing it to lift and shift. The servisbot-cli handles formatting the input correctly for this class to use.