|
| 1 | +# Language Generation ***_[PREVIEW]_*** |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +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][1]. |
| 6 | + |
| 7 | +Language generation is achieved through: |
| 8 | + |
| 9 | +- markdown based .lg file that describes the templates and their composition. See [here][3] for the .lg file format. |
| 10 | +- full access to current bots memory so you can data bind language to the state of memory. |
| 11 | +- parser and runtime libraries that help achieve runtime resolution. See [here][2] for API-reference. |
| 12 | + |
| 13 | +```markdown |
| 14 | +# greetingTemplate |
| 15 | +- Hello @{user.name}, how are you? |
| 16 | +- Good morning @{user.name}. It's nice to see you again. |
| 17 | +- Good day @{user.name}. What can I do for you today? |
| 18 | +``` |
| 19 | + |
| 20 | +You can use language generation to: |
| 21 | + |
| 22 | +- achieve a coherent personality, tone of voice for your bot |
| 23 | +- separate business logic from presentation |
| 24 | +- include variations and sophisticated composition based resolution for any of your bot's replies |
| 25 | +- construct speak .vs. display adaptations |
| 26 | +- construct cards, suggested actions and attachments. |
| 27 | + |
| 28 | +## Speak .vs. display adaptation |
| 29 | + |
| 30 | +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][1] by a layer above language generation. |
| 31 | + |
| 32 | +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. |
| 33 | + |
| 34 | +```markdown |
| 35 | +# greetingTemplate |
| 36 | +- hi || hi there |
| 37 | +- hello || hello, what can I help with today |
| 38 | +``` |
| 39 | + |
| 40 | +You can use the `TextMessageActivityGenerator.CreateActityFromText` method to transform the command into a Bot Framework activity to post back to the user. |
| 41 | + |
| 42 | +## Using Chatdown style cards |
| 43 | + |
| 44 | +[Chatdown][6] introduced a simple markdown based way to write mock conversations. Also introduced as part of the [.chat][7] file format was the ability to express different [message commands][9] via simple text representation. Message commands include [cards][10], [Attachments][11] and suggested actions. |
| 45 | + |
| 46 | +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. |
| 47 | + |
| 48 | +See [here][8] for examples of how different card types are represented in .chat file format. |
| 49 | + |
| 50 | +Here is an example of a card definition. |
| 51 | + |
| 52 | +```markdown |
| 53 | + # HeroCardTemplate(buttonsCollection) |
| 54 | + - ``` |
| 55 | + [Herocard |
| 56 | + title=@{TitleText())} |
| 57 | + subtitle=@{SubText())} |
| 58 | + text=@{DescriptionText())} |
| 59 | + images=@{CardImages())} |
| 60 | + buttons=@{join(buttonsCollection, '|')] |
| 61 | + ``` |
| 62 | + |
| 63 | + # TitleText |
| 64 | + - Here are some [TitleSuffix] |
| 65 | + |
| 66 | + # TitleSuffix |
| 67 | + - cool photos |
| 68 | + - pictures |
| 69 | + - nice snaps |
| 70 | + |
| 71 | + # SubText |
| 72 | + - What is your favorite? |
| 73 | + - Don't they all look great? |
| 74 | + - sorry, some of them are repeats |
| 75 | + |
| 76 | + # DescriptionText |
| 77 | + - This is description for the hero card |
| 78 | + |
| 79 | + # CardImages |
| 80 | + - https://picsum.photos/200/200?image=100 |
| 81 | + - https://picsum.photos/300/200?image=200 |
| 82 | + - https://picsum.photos/200/200?image=400 |
| 83 | +``` |
| 84 | + |
| 85 | + |
| 86 | +## Language Generation in action |
| 87 | + |
| 88 | +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][3] to cover all possible scenarios where you would like to use the language generation sub-system with your bot's replies to user. |
| 89 | + |
| 90 | +Then make sure you include the platform specific language generation library. |
| 91 | + |
| 92 | +For C#, add Microsoft.Bot.Builder.LanguageGeneration. |
| 93 | +For NodeJS, add botbuilder-lg |
| 94 | + |
| 95 | +Load the template manager with your .lg file(s) |
| 96 | + |
| 97 | +```typescript |
| 98 | + // multi lg files |
| 99 | + let lgEngine = new TemplateEngine.addFiles(filePaths, importResolver?); |
| 100 | + |
| 101 | + // single lg file |
| 102 | + let lgEngine = new TemplateEngine.addFile(filePath, importResolver?); |
| 103 | +``` |
| 104 | +
|
| 105 | +When you need template expansion, call the templateEngine and pass in the relevant template name |
| 106 | +
|
| 107 | +```typescript |
| 108 | + await turnContext.sendActivity(lgEngine.evaluateTemplate("<TemplateName>", entitiesCollection)); |
| 109 | +``` |
| 110 | +
|
| 111 | +If your template needs specific entity values to be passed for resolution/ expansion, you can pass them in on the call to `evaluateTemplate` |
| 112 | +
|
| 113 | +```typescript |
| 114 | + await turnContext.sendActivity(lgEngine.evaluateTemplate("WordGameReply", { GameName = "MarcoPolo" } )); |
| 115 | +``` |
| 116 | +
|
| 117 | +## Multi-lingual generation and language fallback policy |
| 118 | +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][25] for an example. |
| 119 | +
|
| 120 | +## Grammar check and correction |
| 121 | +
|
| 122 | +The current library does not include any capabilities for grammar check or correction. |
| 123 | +
|
| 124 | +
|
| 125 | +[1]:https://github.com/Microsoft/BotBuilder/blob/master/specs/botframework-activity/botframework-activity.md |
| 126 | +[2]:https://github.com/microsoft/BotBuilder-Samples/blob/master/experimental/language-generation/docs/api-reference.md |
| 127 | +[3]:https://github.com/microsoft/BotBuilder-Samples/blob/master/experimental/language-generation/docs/lg-file-format.md |
| 128 | +[6]:https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Chatdown |
| 129 | +[7]:https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Chatdown#chat-file-format |
| 130 | +[8]:https://github.com/Microsoft/botbuilder-tools/blob/master/packages/Chatdown/Examples/CardExamples.chat |
| 131 | +[9]:https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Chatdown#message-commands |
| 132 | +[10]:https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Chatdown#message-cards |
| 133 | +[11]:https://github.com/Microsoft/botbuilder-tools/tree/master/packages/Chatdown#message-attachments |
| 134 | +[25]:https://github.com/microsoft/botbuilder-dotnet/blob/d953d1b7fe548cdb1800f1c2e85fe35c34edf75c/tests/Microsoft.Bot.Builder.LanguageGeneration.Renderer.Tests/LGGeneratorTests.cs#L78 |
| 135 | +
|
0 commit comments