Konversation

Konversation is a tool to generate rich and diversified responses to the user of a voice application. You can support multiple platforms and different output devices at once, as watches, speaker, smart displays and TVs. Multiple languages are also supported.
This library can be used in Kotlin, Java, node.js and in the browser. You can define your intent model in ksv files. Which you can export directly to the Alexa Developer console, together with the ASK SDK you can deploy it directly to Amazon if you like.

Konversation has integrations for multiplatform Voice Assistant and Chatbot libraries like Dialog for JVM languages like Kotlin and Java and ChatbotBase for script languages like TypeScript or JavaScript.

Code usage
Usage Export
Components
Roadmap
Want to help?

Code usage

Here is a sample how a help intent can be implemented with Konversation and Dialog or ChatbotBase.

Konversation file (*.kvs)

In this sample you will see how a diversified output can be generated with Konversation. If you want to know the full syntax please check the file format documentation.

@AlexaName("Amazon.HelpIntent")
HelpIntent:
- I can tell you about
- What do you want to know?
+
- Jokes, Offers or Payment.
- Offers, Jokes or Payment.
- Payment, Offers or Jokes.
+
- Please {choose|select} one topic.
?1 In which topic are you intersted in?
[Jokes] [Offers] [Payment]

This small sample above will create one of those random outputs:

I can tell you about Jokes, Offers or Payment. Please choose one topic.
I can tell you about Offers, Jokes or Payment. Please choose one topic.
I can tell you about Payment, Offers or Jokes. Please choose one topic.
I can tell you about Jokes, Offers or Payment. Please select one topic.
I can tell you about Offers, Jokes or Payment. Please select one topic.
I can tell you about Payment, Offers or Jokes. Please select one topic.
What do you want to know? Jokes, Offers or Payment. Please choose one topic.
What do you want to know? Offers, Jokes or Payment. Please choose one topic.
What do you want to know? Payment, Offers or Jokes. Please choose one topic.
What do you want to know? Jokes, Offers or Payment. Please select one topic.
What do you want to know? Offers, Jokes or Payment. Please select one topic.
What do you want to know? Payment, Offers or Jokes. Please select one topic.

Dialog

Here is a sample how a help intent can be implemented in kotlin with Dialog:

@IntentHandler
class HelpIntentHandler : MultiPlatformIntentHandler {
    override val intentNames: List<String>
        get() = listOf(AMAZON_HELP, HELP)

    override fun handleDialogflow(input: DialogflowHandler): DialogflowResponseBuilder {
        val output = input.loadKonversation("HelpIntent").createOutput()
        return input.responseBuilder
            .withGoogleSimpleResponse(output)
            .withGoogleReprompts(output)
            .withGoogleSuggestions(output)
            .expectUserAnswer(true)
    }

    override fun handleAlexa(input: HandlerInput): ResponseBuilder {
        val output = input.loadKonversation("HelpIntent").createOutput()
        return input.responseBuilder
            .withSpeech(output)
            .withReprompt(output)
            .expectUserAnswer(true)
    }
}

ChatbotBase

The same sample as above when you use ChatbotBase:

export class HelpIntent implements IntentHandler {
    createOutput(input: Input, translations: TranslationProvider): Output | Promise<Output> {
        return new Reply(input, translations).addReply("HelpIntent");
    }

    isSupported(input: Input): boolean {
        return input.intent == "HelpIntent" || input.intent == "Amazon.HelpIntent";
    }
}

Please note that ChatbotBase has currently no support to apply the suggestions or reprompts.

Usage export

The export required the command line interface or the gradle plugin (the gradle plugin can currently export only Alexa).

Example project

Here is a fictive shop interaction model without the prompts, repromts and suggestions:
Shop.kvs:

ProductSearch:
! {|I want to} buy a 
! I need  

BuyIntent:
! {|Buy|Select|Order} {product|number|article|thing|gadget} 

This will generate 2 Intents with in total 23 utterances. In single brackets are alternatives which are divided by the pipe symbol. In the BuyIntent are two permutations which define 4*5=20 utterances; just written in one single line and still readable. Here are some samples:

Product 1
Buy article 2
Select number 3

In the utterance I need are two slot values (Amazon naming) or entities (Google naming). Those variables are marked by double brackets and have a optional name in the front of the type. In the sample is the name “count” with the data type “number” used amd the custom slot type/entity “product”.

The required product.values definition could look like this:

Google Home Mini
Google Home
Nest Hub
Echo Dot
Echo Show
...

For more details check the file format documentation.

Export to Amazon

To export the intent schema for a skill named “Test” into the file “schema.json” you need to execute:

$ konversation --export-alexa schema.json -invocation "Test" shop.kvs product.values

Please note that the order of the commands are not important you can also use wildcards as *.kvs or slots/*.values.

Export to Dialogflow

To export the intents to Dialogflow for a skill named “Test” you need to execute:

$ konversation --export-dialogflow . -invocation "Test" shop.kvs product.values

This will generate a dialogflow-.zip file in the current (.) directory containing all the intents, utterances and entities. We are aware that the naming of the output file is suboptimal and will change until the final release of the cli version 1.1.0.

Components

This Projects consists of a lot of modules, some parts are still in early development and not yet pushed.

CLI

The command line interface (CLI) has the task to generate the from the supported input formats (kvs, grammar and values) to the output formats (kson, txt, json, and zip) depending on the arguments and use cases.
Konversation can be installed with brew (for Linux and MacOS) and with chocolaty for Windows. For detailed instructions check the readme file.
In version 1.1 will be added the export for Dialogflow with zip files.
In version 1.2 provisioning will follow, that will allow you to integrate konversation into your CI/CD flow to automatically update your Alexa or Dialogflow project.

Runtime

The runtime has 3 modules: a shared module for base classes which are used in the cli and each one module for JVM and JavaScript usage. So you can use Konveration in JVM languages like Kotlin and Java and JavaScript languages like ECMAScript or TypeScript. To keep the JS interface as simple as possible there is also a small facade to use the runtime in a more natural way without using the kotlin classes.

Gradle plugin

The gradle plugin create some hooks into the gradle build to create the required kson files for the runtime and add them to your resources directory. So you don’t need to use the cli if you are using gradle as build system.

Roadmap

Version 1.0

Create diverse outputs
Suggestions
Repompts
Voice only blocks

Version 1.1

Dialogflow exporter
Annotations (for fallbacks, list parameters, platform specific renamings, …)

Version 2.0

Provisioning
Refactoring of the cli (to make it easier to use for the gradle plugin)
Extensions of the gradle plugin to configure the credentials and multiple targets
Breaking changes for the gradle plugin and CLI

Version 2.1

Contextual fallback support

IntelliJ Plugin

Syntax Highlighting
Refactoring
Warnings for too many utterances
Errors for usage of not defined konversations
Jump to definition

Want to help?

Great!
You found a bug? Please open a new issue and tag it with the problematic component.
You want to contribute? Please check the open issues and feel free to add a pull request ;-)

This site is open source. Improve this page.

Konversation

Konversation

Table of contents

Code usage

Konversation file (*.kvs)

Dialog

ChatbotBase

Usage export

Example project

Export to Amazon

Export to Dialogflow

Components

CLI

Runtime

Gradle plugin

Roadmap

Version 1.0

Version 1.1

Version 2.0

Version 2.1

IntelliJ Plugin

Want to help?