Language generation in Composer

APPLIES TO: Composer v1.x and v2.x

Language generation lets you define multiple variations of a phrase, execute simple expressions based on context, and refer to conversational memory. At the core of language generation lies template expansion and entity substitution. You can provide variations for expansion and conditionally expand templates. The output from language generation can be a simple text string, multi-line response, or a complex object payload that a layer above language generation will use to construct a complete activity. Bot Framework Composer natively supports language generation to produce output activities using the LG templating system.

You can use Language generation to:

• Achieve a coherent personality, tone of voice for your bot.
• Separate business logic from presentation.
• Include variations and sophisticated composition for any of your bot's replies.
• Construct cards, suggested actions and attachments using a structured response template.

Language generation is achieved through:

• A Markdown based .lg file that contains the templates and their composition.
• Full access to the current bot's memory so you can data bind language to the state of memory.
• Parser and runtime libraries that help achieve runtime resolution.

Tip

You can read the composer best practices article for some suggestions using language generation in Composer.

Templates

Templates are functions that return one of the variations of the text and fully resolve any other references to templates for composition. You can define one or more text responses in a template. When multiple responses are defined in the template, a single response will be selected at random.

You can also define one or more expressions using adaptive expressions. When it's a conditional template, those expressions control which particular collection of variations get picked. Templates can be parameterized, meaning that different callers to the template can pass in different values for use in expansion resolution. For additional information, see .lg file format.

Composer currently supports three types of templates: simple response, conditional response, and structured response. You can read define language generation templates to learn how to define each of them.

You can split language generation templates into separate files and refer to them from one another. You can use Markdown-style links to import templates defined in another file, like [description text](file/uri path). Make sure your template names are unique across files.

Anatomy of a template

A template usually consists of the name of the template, denoted with the # character, and one of the following:

• A list of text values defined using "-"
• A collection of conditions, each with a:
  • conditional expression, expressed using adaptive expressions and
  • list of text values per condition
• A structure that contains:
  • structure-name
  • properties

Below is an example of a simple language generation template with text values and variations.

> this is a comment
# nameTemplate
- Hello ${user.name}, how are you?
- Good morning ${user.name}. It's nice to see you again.
- Good day ${user.name}. What can I do for you today?  

Define language generation templates

When you want to determine how your bot should respond to user input, you can define language generation templates to generate responses. For example, you can define a welcome message to the user in the Send a response action. To do this, select the Send a response action node. You'll see the inline response editor where you can define LG templates.

To define language generation templates in Composer, you'll need to know:

• the aforementioned language generation concepts
• .lg file format
• adaptive expressions

You can define LG templates either in the inline response editor in the Properties panel or in the Bot Responses view, which lists all templates. Below is a screenshot of the response editor.

Composer v2.x

Composer v1.x

Tip

When prompting the user for information, you can enter in a plain text string, seen above, or you can use any of the three insert buttons. Each results in a drop-down list containing relevant options to choose from:

Reference an existing item in your Bot Responses template.

Reference a property in memory

Reference a pre-built adaptive expressions function.

All entries made in the inline response editor in the properties pane will automatically be added to the Bot Responses page. To see them, select the Bot Responses icon (or the bot icon when collapsed) in the bot explorer to see all the LG templates defined in the bot categorized by dialog.

The Common entry in the list isn't associated with a specific dialog. The common language generation template is created by Composer, and is designed to be shared by other dialogs in your bot. To enable a dialog to see the templates it contains, select Show code on the upper right corner of the Bot Responses page to enable editing, then add [import](common.lg) in that dialog's template (See screenshot below). This tells that dialog's template to import all the items in the common template. For additional information on importing templates, see Importing external references in the .lg file format article.

Composer v2.x

Composer v1.x

Composer currently supports definitions of the following three types of templates: simple, conditional, and structured response.

Simple response template

A simple response template generates a simple text response. A simple response template can be a single line response, a text with memory, or a response of multiline texts. Use the - character before the response text or expression to returns. Here are a few examples of simple response templates from the Responding with Text sample.

Here is an example of a single line text response:

- Here is a simple text message.

This is an example of a single line response using a variable:

- ${user.message}

Variables and expressions are enclosed in curly brackets ${}.

Select a property reference using the Insert property reference drop-down in the inline response editor:

Here is an example of a multi-line response. It includes multiple lines of text enclosed in ```.

# multilineText
- ``` you have such alarms
      alarm1:  7:am
      alarm2: 9:pm
  ```

Conditional response template

For all conditional templates, all conditions are expressed in Adaptive expressions. Condition expressions are enclosed in curly brackets ${}. Here are two conditional response template examples.

If-else

> time of day greeting reply template with conditions.
# timeOfDayGreeting
- IF: ${timeOfDay == 'morning'}
  - good morning
- ELSE:
  - good evening

Switch

# TestTemplate
- SWITCH: ${condition}
- CASE: ${case-expression-1}
  - output1
- CASE: ${case-expression-2}
  - output2
- DEFAULT:
  - final output

Structured response template

Structured response templates let users define a complex structure that supports all the benefits of language generation (templating, composition, substitution) while leaving the interpretation of the structured response up to the bot developer. It provides an easier way to define an outgoing activity in a simple text format. Composer currently support structured language generation templates to define cards and SuggestedActions.

The definition of a structured response template is as follows:

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression> 
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

Below is an example of SuggestedActions from the Interruption Sample:

- Hello, I'm the interruption demo bot! \n \[Suggestions=Get started | Reset profile]

Below is an example of a Thumbnail card from the Responding With Cards Sample:

# ThumbnailCard
[ThumbnailCard
    title = BotFramework Thumbnail Card
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever
    they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    image = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Get Started
]

References

• .lg file format
• Structured response template
• Adaptive expressions

Next steps

• Language understanding