botdispatch-ccastro v1.1.13

Dispatch Command Line tool

Dispatch is a tool to create and evaluate LUIS models used to dispatch intent across multiple bot modules such as LUIS models, QnA knowledge bases and others (added to dispatch as a file type).

Use the Dispatch model in cases when: 1. Your bot consists of multiple modules and you need assistance in routing user's utterances to these modules and evaluate the bot integration. 2. Evaluate quality of intents classification of a single LUIS model. 3. Create a text classification model from text files.

Prerequisite

• Node.js version 8.5 or higher
• For installation on Linux, please pre-install .NET Core runtime by following instructions on this page: https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x.

Installation

To install:

npm install -g botdispatch

This will install dispatch into your global path.

Usage

Initializing dispatch

To initialize dispatch:

dispatch init [options]

It will ask for the name of the dispatch, LUIS authoring key and region needed to create a LUIS application. This commands then creates {dispatchName}.dispatch file. To bypass the prompts, values could be passed in via arguments below.

Arguments:

Example:

dispatch init -n TestDispatch --luisAuthoringKey "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" --luisAuthoringRegion westus 
dispatch init --bot c:\src\bot\testbot.bot

Adding source to dispatch

This step is not needed if you have a .bot file already connected with services (i.e., LUIS/QnA). Dispatch will take the services in .bot file and add each of the services it can dispatch to .dispatch file. Currently, a maximum of 500 dispatch sources could be added to a Dispatch model.

dispatch add -t luis -i xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -n TestLuisApp -v 0.1 -k xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
dispatch add -t luis -i xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -n TestLuisApp --intentName foo -v 0.1 -k xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
dispatch add -t qna -i xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -n Faq -k xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
dispatch add -t file -n TestModule -f c:\src\testmodule.tsv
dispatch add -t file -n TestModule2 -f c:\src\testmodule2.txt
dispatch add -t file -n TestModule3 -f c:\src\testmodule3.json

Arguments

Supported file types:

Removing dispatch source

To remove one of the services from .dispatch file, run

dispatch remove -t luis -i xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 
dispatch remove -t qna -i xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 
dispatch remove -t file -f c:\src\testmodule.json

Arguments

Creating your dispatch model

To create, train and publish your new dispatch model:

dispatch create [options]
dispatch create --bot c:\src\bot\testbot.bot --secret <your_bot_file_secret>

Options:

This command creates a brand new LUIS application.

Refreshing your dispatch model

To train and publish your existing dispatch model after modification:

dispatch refresh [options]
dispatch refresh --bot c:\src\bot\testbot.bot --secret <your_bot_file_secret>

With the following options

This command updates existing LUIS application in .dispatch file.

Evaluating your dispatch model

This command will run cross validation evaluation on the dispatch model and generate a summary of the evaluation:

dispatch eval [options]

Options:

If no options are supplied, the tool will prompt for the required information it needs to run model evaluation.

Testing your dispatch model

To test your dispatch model against test set:

dispatch test [options]

Options:

Run prediction using your dispatch model

To run prediction against your new dispatch model, run

dispatch predict [options]

With the following options

You'll then be prompted to enter the utterance you'd like to run prediction on.

Print dispatch configuration to console

To print your current dispatch configuration, run

dispatch list [options]

With the following options

Common Tasks

Create bot dispatch using bot file

If you have a .bot file containing one or more LUIS model(s) and/or one or more QnA Maker knowledge base(s), you could create Dispatch model without having to initialize Dispatch and add all of the sources separately. Running the eval command is optional but it provides insight into how well the newly created or updated Dispatch model will perform. In addition, it provides suggestions for improving the bot components.

dispatch create --bot c:\src\bot\testbot.bot --secret <your_bot_file_secret>
dispatch eval --luisSubscriptionKey <azure_luis_key> --luisSubscriptionRegion <azure_luis_region>

If any of your LUIS/QnA Maker models have changed or if you have added more LUIS/QnA maker component(s) to your bot, update your Dispatch model with refresh command.

dispatch refresh --bot c:\src\bot\testbot.bot --secret <your_bot_file_secret>
dispatch eval --luisSubscriptionKey <azure_luis_key> --luisSubscriptionRegion <azure_luis_region>

Create and evaluate bot dispatch

End-to-end example of a bot consisting of a LUIS module and a QnA Maker knowledge base module:

dispatch init -n mybot_dispatch --luisAuthoringKey <luis_authoring_key> --luisAuthoringRegion <region>
dispatch add -t luis -i <luis_app_id> -n <luis_app_name> -v <luis_app_version> -k <luis_app_authoring_key>
dispatch add -t qna -i <qna_kb_id> -n <kb_name> -k <qna_maker_key>
dispatch create
dispatch eval --luisSubscriptionKey <azure_luis_key> --luisSubscriptionRegion <azure_luis_region>

The output is Summary.html file located in local file system directory where the commands were issued. It includes all the evaluation results and suggestions for improving the bot components.

Evaluate single LUIS model

Evaluate a LUIS model performing cross validation:

dispatch init -n mybot_dispatch --luisAuthoringKey <luis_authoring_key> --luisAuthoringRegion <region>
dispatch add -t luis -i <luis_app_id> -n <luis_app_name> -v <luis_app_version> -k <luis_app_authoring_key>
dispatch create --hierarchical false
dispatch eval --luisSubscriptionKey <azure_luis_key> --luisSubscriptionRegion <azure_luis_region>

The output, Summary.html, contains all the evaluation results. The file is located in local file system directory where the commands were issued.

Test a LUIS model using test utterances

Suppose the dispatcher model was already created following the steps of one of the above tasks. To test this model with a tab-delimited text file run these commands:

dispatch test --testFilePath <text_file>

The output, Summary.html, contains all the evaluation results. The file is located in the location of the test file.

Sample Code and Tutorial

C# Sample: https://github.com/Microsoft/BotBuilder-Samples/tree/master/samples/csharp_dotnetcore/14.nlp-with-dispatch

JS Sample: https://github.com/Microsoft/BotBuilder-Samples/tree/master/samples/javascript_nodejs/14.nlp-with-dispatch

Tutorial: https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-dispatch

Nightly builds

Nightly builds are based on the latest development code which means they may or may not be stable and probably won't be documented. These builds are better suited for more experienced users and developers although everyone is welcome to give them a shot and provide feedback.

You can get the latest nightly build of MSBot from the BotBuilder MyGet feed. To install the nightly -

npm config set registry https://botbuilder.myget.org/F/botbuilder-tools-daily/npm/

Install using npm:

npm i -g botdispatch

To reset registry:

npm config set registry https://registry.npmjs.org/