@christopheranderson/botbuilder-lg v4.7.0-a0-b6513caa

Language Generation PREVIEW

Learning from our customers experiences and bringing together capabilities first implemented by Cortana and Cognition teams, we are introducing Language Generation; which allows the developer to extract the embedded strings from their code and resource files and manage them through a Language Generation runtime and file format. Language Generation enable customers to define multiple variations on a phrase, execute simple expressions based on context, refer to conversational memory, and over time will enable us to bring additional capabilities all leading to a more natural conversational experience.

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

Language generation is achieved through:

• markdown based .lg file that describes the templates and their composition. See here for the .lg file format.
• full access to current bots memory so you can data bind language to the state of memory.
• parser and runtime libraries that help achieve runtime resolution. See here for API-reference.

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

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 based resolution for any of your bot's replies
• construct speak .vs. display adaptations
• construct cards, suggested actions and attachments.

Speak .vs. display adaptation

By design, the .lg file format does not explicitly support the ability to provide speak .vs. display adaptation. The file format supports simple constructs that are composable and supports resolution on multi-line text and so you can have syntax and semantics for speak .vs. display adaptation, cards, suggested actions etc that can be interpreted as simple text and transformed into the Bot Framework activity by a layer above language generation.

Bot Builder SDK supports a short hand notation that can parse and transform a piece of text separated by displayText||spokenText into speak and display text.

# greetingTemplate
- hi || hi there
- hello || hello, what can I help with today

You can use the TextMessageActivityGenerator.CreateActityFromText method to transform the command into a Bot Framework activity to post back to the user.

Using Chatdown style cards

Chatdown introduced a simple markdown based way to write mock conversations. Also introduced as part of the .chat file format was the ability to express different message commands via simple text representation. Message commands include cards, Attachments and suggested actions.

You can include message commands via multi-line text in the .lg file format and use the TextMessageActivityGenerator.CreateActityFromText method to transform the command into a Bot Framework activity to post back to the user.

See here for examples of how different card types are represented in .chat file format.

Here is an example of a card definition.

    # HeroCardTemplate(buttonsCollection)
    - ```
    [Herocard
        title=@{TitleText())}
        subtitle=@{SubText())}
        text=@{DescriptionText())}
        images=@{CardImages())}
        buttons=@{join(buttonsCollection, '|')]
    ```

    # TitleText
    - Here are some [TitleSuffix]

    # TitleSuffix
    - cool photos
    - pictures
    - nice snaps

    # SubText
    - What is your favorite?
    - Don't they all look great?
    - sorry, some of them are repeats

    # DescriptionText
    - This is description for the hero card

    # CardImages
    - https://picsum.photos/200/200?image=100
    - https://picsum.photos/300/200?image=200
    - https://picsum.photos/200/200?image=400

Language Generation in action

When building a bot, you can use language generation in several different ways. To start with, examine your current bot's code (or the new bot you plan to write) and create .lg file to cover all possible scenarios where you would like to use the language generation sub-system with your bot's replies to user.

Then make sure you include the platform specific language generation library.

For C#, add Microsoft.Bot.Builder.LanguageGeneration. For NodeJS, add botbuilder-lg

Load the template manager with your .lg file(s)

    // multi lg files
    let lgEngine = new TemplateEngine.addFiles(filePaths, importResolver?);

    // single lg file
    let lgEngine = new TemplateEngine.addFile(filePath, importResolver?);

When you need template expansion, call the templateEngine and pass in the relevant template name

    await turnContext.sendActivity(lgEngine.evaluateTemplate("<TemplateName>", entitiesCollection));

If your template needs specific entity values to be passed for resolution/ expansion, you can pass them in on the call to evaluateTemplate

    await turnContext.sendActivity(lgEngine.evaluateTemplate("WordGameReply", { GameName = "MarcoPolo" } ));

Multi-lingual generation and language fallback policy

Quite often your bot might target more than one spoken/ display language. To help with resource management as well as implement a default language fall back policy, you can either use MultiLanguageGenerator or ResourceMultiLanguageGenerator. See here for an example.

Grammar check and correction

The current library does not include any capabilities for grammar check or correction.