Learn the Bot Builder Tools

For the people interested in Dispatch tool, that checked out the nlp-with-dispatch sample, and were overwhelmed with the amount of command line tools, this is the article where we introduce you to the Bot Builder Tools, without causing a mental stack overflow.

Getting Started

You can find a prepared sample for following along in the following repo:

git clone https://github.com/rinormaloku/car-rental-dispatch-bot.git

The first tool that we are getting introduced to is Ludown.

Ludown

Ludown is a simple way of representing the utterances, intents, entities of training a Luis or QnA Maker application.

Let’s take the example from car-rental.lu:

## CarRental
- I want to rent a {Car=Mercedes}?
- I want to rent a {Car=Mercedes} in munich?
- I am looking to rent a {CarType=caravan}

This section defines the CarRental intent with three utterances. These utterances have entities Car and CarType. Which are defined in the following section:

> # Entity definitions
$Car:simple
$CarType:simple

This format is easy for us to understand but cannot be imported in Luis and QnA Applications, so we need to transform it into a format which can be understood. That’s where Ludown comes in.

Installing the tools

Besides Ludown we will need all the following tools, to save time let’s install all in one run, and we’ll take a closer look at each one later.

npm i -g ludown msbot luis-apis qnamaker botdispatch

Parsing to the Luis format

With the tools installed let’s get started with ludown, from the base repository execute the following:

ludown parse toluis --in Resources/car-rental.lu -o CognitiveModels \ 
   --out car-rental.luis -n "Car Rental" -d "Car Rental Luis App" --verbose

This parses the car-rental.lu file and transforms it into the LUIS format and saves it in the directory CognetiveModels/car-rental.luis.

Parsing to the QnA format

Run the command below to generate the file in QnA format:

ludown parse toqna --in resources/car-qna.lu -o CognitiveModels \ 
    --out car-bot.qna -n "Car QnA" --verbose

Summary: Ludown is a CLI tool that transforms files to formats which can be used to import and train Luis and QnA cognitive services. This is our next section.

Fig 1. Generating LUIS and QnA files using Ludown

LUIS CLI

The LUIS CLI enables us to consume .luis files and create LUIS Applications out of them. Run the command below to create a Luis application out of the file car-rental.luis:

luis import application --in CognitiveModels/car-rental.luis \ 
    --authoringKey <AuthKey> --region <Region> 

Select the region you want (e.g. westus) and get your Authoring Key from the following page https://www.luis.ai/user/settings, where you need to be registered and logged in.

After executing that command, we get the LUIS application created from the .luis file.

Fig 2. The LUIS App created from the .luis file

Publish the LUIS application and let’s get to the next section. The MSBot command line tool.

MSBot CLI

The MSBot CLI tool maintains your Bot Configuration, but additionally, it has capabilities of bootstrapping the creation of the services to create your Bot Application. We will use it for maintaining the Bot Configuration.

Let's take a step back and see the bigger picture. We created the LUIS Service, but we need to update the .bot file so that our application can consume it. This is achieved with the following command:

msbot connect luis --name CarRental --appId <AppId> --version 0.1 \
    --authoringKey <AuthKey> -b CarRentalDispatchBot.bot

You can get the Application Id from your LUIS Applications for the CarRental application or find it by executing the command below luis list applications –authoringKey <AuthKey>

Tip: Executing luis init enables you to save the Authoring Key within a .luisrc file and then you don’t have to constantly use it in commands.

Fig. 3. Configuring the .bot file to use the LUIS Service

The msbot connect command will pick the important information for the consumption of the LUIS service and update the CarRentalDispatchBot.bot file (visually presented in Fig. 3). But it won’t add the region, which is as well important. So open the file CarRentalDispatchBot.bot and add the line in bold.

{
    // shortened for brevity
    "name": "CarRental",
    "region": "<REGION>",
    "id": "162"
},

QnAMaker CLI

The concept is the same as with the LUIS Cli this is built for the QnA Maker service. Basically, we consume a .qna file and create a knowledge base:

Fig. 4. Creating the QnA Maker Service from the .qna file

To get started you need to create a QnA Maker Service in Azure and pick the Keys as shown in the image below:

Fig. 5. QnA Service Subscription Key location

This represents your Subscription Key in the commands below, where we purposefully named it NotSubKey as not to confuse it with your Azure Subscription Key:

qnamaker create kb --in cognitiveModels/car-bot.qna \ 
    --subscriptionKey <NotSubKey> --wait

After this command completes, verify that the Knowledge Base is imported in our QnA Maker at qnamaker.ai.

Fig. 6. Data from QnA file are imported in the QnA Service KnowledgeBase

Publish the Knowledgebase and move on to the next section.

Configuring the .bot file with MSBot

Initially, we need the Knowledge Base Id, which we easily find by executing the command below:

qnamaker list kbs --subscriptionKey <NotSubKey>

With the Knowledge Base Id update and run the command below:

qnamaker get kb --kbId <kbId> \ 
    --subscriptionKey <NotSubKey> \ 
    --msbot | msbot connect qna --stdin

This command queries the details of the Knowledgebase Id and feeds the MSBot tool, which in consequence updates the .bot file with the correct details.

(Optionally) Executing the command below by manually finding and replacing the correct values:

msbot connect qna --name CarQnA --kbId <KbID> \ 
    --subscriptionKey <NotSubKey> --endpointKey <EndpointKey> \
    --hostname <Host> -b CarRentalDispatchBot.bot

Now the .bot file contains the information f both the Luis and QnA Maker services. And using the Ludown, QnAMaker, LUIS, and MSBot we got from the position of having two .lu files as starting point, to having two services configured in our Bot Configuration ready for usage, as shown on Fig:

Fig. 7. Big Picture of how we got from LU files to Creating the Services and Configuring the bot.

To complete this project, we have to use the Dispatch CLI. But that requires more information and for that read our next article “Introduction to the Dispatch CLI”.