Language Generation

APPLIES TO: SDK v4

Language Generation (LG) allows developers to extract embedded strings from their code and resource files and manage them through a LG runtime and file format. With LG, developers can create a more natural conversation experience by defining multiple variations on a phrase, executing simple expressions based on context, and referring to conversational memory.

LG can be used by developers to:

  • achieve a coherent personality, tone of voice for their bot
  • separate business logic from presentation
  • include variations and sophisticated composition based resolution for any of their bot's replies
  • construct speak .vs. display adaptations
  • construct cards, suggested actions and attachments

At the core of LG lies template expansion and entity substitution. You can provide one-of variation for expansion as well as conditionally expand a template. The output from LG can be a simple text string, multi-line response, or a complex object payload that a layer above LG will use to construct an activity.

The following is a simple greeting LG template. Notice that all of the greetings reference the user's name in memory with the variable ${user.name}.

# greetingTemplate
- 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?

LG in action

You can use LG in a variety of ways when developing bots. To start, create one or more .lg file(s) to cover all possible scenarios where you would use the language generation sub-system with your bot's replies to a user.

Make sure you include the language Generation library Microsoft.Bot.Builder.LanguageGeneration. Then parse and load templates in your .lg file by adding the following:

    _templates = Templates.ParseFile(fullPath);

When you need template expansion, use Evaluate and pass in the relevant template name.

    var lgOutput = _templates.Evaluate(<TemplateName>);

If your template needs specific properties to be passed for resolution/expansion, you can pass them when calling Evaluate.

    var lgOutput = _templates.Evaluate("WordGameReply", new { GameName = "MarcoPolo" } );

Multilingual generation and language fallback policy

Your bot might target more than one spoken or display language. You can manage separate instances of the TemplateEngine, one per target language. For an example of how to add multiple languages, also known as language fallback, to your bot, see the multi-turn prompt with language fallback sample in C# or JavaScript.

Expand API

To get all possible expansions of a template, you can use ExpandTemplate.

    var results = lgTemplates.ExpandTemplate("WordGameReply", { GameName = "MarcoPolo" } )

For example, given this LG content:

# Greeting
- Hi
- Hello

#TimeOfDay
- Morning
- Evening

# FinalGreeting
- ${Greeting()} ${TimeOfDay()}

# TimeOfDayWithCondition
- IF: ${time == 'morning'}
    - ${Greeting()} Morning
- ELSEIF: ${time == 'evening'}
    - ${Greeting()} Evening
- ELSE:
    - ${Greeting()} Afternoon

The call ExpandTemplate("FinalGreeting") results in four evaluations:

  • Hi Morning
  • Hi Evening
  • Hello Morning
  • Hello Evening

The call ExpandTemplate("TimeOfDayWithCondition", new { time = "evening" }) with scope, results in two expansions:

  • Hi Evening
  • Hello Evening

Additional resources