Using Microsoft LUIS in Digital DNA Studio

This section describes how you can use Microsoft's Language Understanding Intelligence Service (LUIS) natural language processing tool in Digital DNA Studio. To use MS LUIS, you need to build a conversational Bot and deploy it to the Microsoft Azure Cloud. The Digital Person Server connects to your MS Azure Bot to provide conversational content and dynamic data during its interaction with your end-users.

Building your Corpus (MS Azure Bot)

This process is not the same as building a Corpus using Watson or Dialogflow NLPs because you need to build it locally in your machine and then deploy/publish to the MS Azure Cloud. It also requires some code to implement.

Soul Machines recommends using Microsoft Bot Framework Composer for creating your Bot. Composer is a desktop application for authoring, testing and managing conversational content and experiences. This visual tool is similar to the Dialogflow console and provides controls that enable you to train your Bot in recognizing intents and their matching responses.

Create your Bot with MS Bot Framework Composer

1. Download and install the Microsoft Bot Framework Composer Desktop Application. Follow the steps outlined in the Microsoft documentation website:
   https://docs.microsoft.com/en-us/composer/install-composer

2. Use the sample Bot template provided by Soul Machines to create your conversation Bot (corpus).
   The template contains two extra intents for setting context variables:

   1. SetConversationContext - enables the corpus writer to set their own context variables. 

   2. SMContextVariables Event received - processes the Soul Machines context variables sent by the SDK (custom Soul Machines functionality). 

Saving Conversation States

To support getting and setting conversation context properties, there are some changes that need to be made to the Bot logic.

Setting Context Properties

Context properties/variables can be used to save conversation state to be used at a later point in the conversation, e.g. for card info. The Bot should set context variables in the conversation scope and return the conversation object in responses to share this with the SDK. 

For example, to set a component to be shown in a @showcards() function the component needs to be set using the same naming convention as with other conversation providers (prefixed with conversation.public-) and the conversation needs to be returned in the Value field of the response:

Receiving and Saving Soul Machines Context Variables

The Soul Machines SDK sends a dialog event named SMContextVariables with a map of context variables in the Value field to the Bot. These variables may be utilized in the Corpus responses (see code snippet below for an example of how to handle this event in the Bot). For more information, please contact your customer support representative.

{
    "$kind": "Microsoft.OnEventActivity",
    "$designer": {
        "id": "7OkzsH",
        "name": "SetSMContextVariables"
    },
    "actions": [
        {
            "$kind": "Microsoft.IfCondition",
            "$designer": {
                "id": "jPFLPr"
            },
            "condition": "=exists(turn.activity.value)",
            "actions": [],
            "elseActions": [
                {
                    "$kind": "Microsoft.EndDialog",
                    "$designer": {
                        "id": "BOiCih"
                    }
                }
            ]
        },
        {
            "$kind": "Microsoft.SetProperty",
            "$designer": {
                "id": "l7AsSb"
            },
            "property": "dialog.tempContextArray",
            "value": "=indicesAndValues(turn.activity.value)"
        },
        {
            "$kind": "Microsoft.Foreach",
            "$designer": {
                "id": "rU9Yvr"
            },
            "index": "dialog.foreach.index",
            "value": "dialog.foreach.value",
            "actions": [
                {
                    "$kind": "Microsoft.SetProperty",
                    "$designer": {
                        "id": "a168CY"
                    },
                    "property": "conversation.${dialog.foreach.value.index}",
                    "value": "${dialog.foreach.value.value}"
                }
            ],
            "itemsProperty": "dialog.tempContextArray"
        }
    ],
    "condition": "=turn.activity.name==\"SMContextVariables\""
}

Building Bot Responses

It is recommended to build the Bot to respond to all possible inputs from the user. For example, if processing an if/else condition based on user input, both the true and false branches should result in a response from the Bot. This ensures that the conversation doesn’t appear to have stalled from the user’s perspective (if the persona does not respond).

Publishing from Composer

Note that there are multiple ways of publishing a Bot, e.g. via command line, using the Azure Portal, etc., the following are two options that are known to work:

Option 1: Create the resources and resource group from Composer

Ensure that you have write access to the subscription before using this option, otherwise the publish step will fail with an authorization error.

Option 2: Publish to Existing Resources

Create the following resources in Azure Portal:

• Web App Bot

• Language Understanding - enable both prediction and authoring

In the “Bot management and configurations” tab of Composer, fill out the App ID/Password and LUIS fields with the keys/endpoints/names copied from the Azure Portal.

Create a publish profile that includes the fields hostname and luisResource - these don’t get added automatically and need to be added by toggling the “Advanced Settings View (json)” or by manually editing the appsettings.json file in the “settings” folder.

Obtaining Your Azure Bot Secret Keys

To configure your Digital Person in DDNA Studio, enter the Microsoft Bot Direct Line API 3.0 secret key in the LUIS NLP secret key field. Two of these keys are found under Settings > Channels > Direct Line in the Web App Bot resource of  the Azure Portal (see screenshots below).

The MS Azure Bot Secret Keys must be entered in Digital DNA Studio when you have selected to use the MS LUIS NLP for the conversation platform in your Digital Person project.  Two keys are available and either one of them can be used.

The Secret Key is used to access the MS Azure Bot which enables the Soul Machines SDK to make or send requests to the MS Azure Bot.

Useful Links

• Initial creation of Bot/LUIS resources: Publish a bot to Azure - Bot Composer 

• To format Bot responses: .lg file format - Bot Service 

• To obtain Azure Bot key for use in Soul file: Authentication - Bot Service