Skip to content

Getting Started

Gwendal Daniel edited this page Sep 5, 2019 · 6 revisions

This article presents the core concepts to define and run bots with Xatkit.

Objectives

  • Learn how to design simple intents with the Xatkit language
  • Learn how to bind intents to actions to create a bot execution scenario
  • Understand what is the configuration file and its contents
  • Extend the GreetingsBot with custom intents and execution scenario

Xatkit Tip: check your installation

To complete this tutorial you need to have a local installation of Xatkit as well as the Xatkit Eclipse plugins installed in your Eclipse IDE. You can check the installation instructions to know how to setup your Xatkit environment.

Open the GreetingsBot example

The GreetingsBot is a bot example embedded with Xatkit releases. You can open it in Eclipse by importing the Eclipse project located in xatkit/examples/GreetingsBot.

Once imported, Eclipse should show the following content in your Package Explorer:

Imported GreetingsBot Project

A Xatkit project is composed of 4 different types of file:

  • At least one .intent file containing the input matched by the bot
  • An .execution file describing the bot's execution logic
  • At least one .properties file containing execution-level configuration to deploy the bot
  • .xmi files that are compiled from .intent and .execution files and should not be updated manually

GreetingsBot Intent Library

Open GreetingsBot-Lib.intent. A pop-up may appear asking if you want to convert the project to a Xtext project. You can confirm it and the following editor will show up:

GreetingsBot Library

The first line defines the name of the intent library. The library name is used to identify the library, and provide useful auto-completion information in the other editors.

The rest of the file is composed of two intents that represent the user intentions the GreetingsBot responds to. Each intent contains a set of inputs which are examples of user input corresponding to the intent. Note that in this tutorial the bot is defined in English, but additional languages are also supported.

Xatkit Tip: the more input examples the better!

Xatkit uses the intent's inputs to train its underlying intent recognition engine. Increasing the number of input examples will improve the quality of the recognition, leading to smarter and more accurate bots!

GreetingsBot Execution Model

Open GreetingsBot-Ex.execution. The following editor will show up:

Greetings Bot Execution Model

Execution models contains 3 sections:

  • a set of library and platform imports that define what are the intent libraries and platforms used by the bot
  • at least one use provider clause that specifies what are the inputs the bot will listen to
  • a set of execution rules binding user intents to actions (execution rules also support additional constructs that are not covered in this tutorial)

Imports

Our example defines 2 library imports and 1 platform import

  • import library "GreetingsBot/GreetingsBot-Lib.xmi" tells Xatkit to use the intent library defined in the previous section. In the example the provided path is relative to the workspace (<project_name>/<file_name>), but absolute paths are also supported.
  • import library "CoreLibrary" specifies that the bot uses some intents defined in the Core Library, a set of intents bundled with Xatkit and providing generic, high-level intents that can be reused in multiple bots.
  • import platform "ChatPlatform" specifies that the bot uses the Chat Platform, a generic messaging platform that can be deployed on multiple messaging services like Slack or Discord, or our React-based web component.

Xatkit Tip: the alias mechanism

The as GreetingsBotLib clause is an optional alias that can be dynamically re-mapped to a path when deploying the bot. This is required for custom imports (i.e. not provided as part of Xatkit bundled platforms and libraries) when the bot is not deployed on the machine it has been developed on (for example, the GreetingsBot is developed by us but can be run on your machine without changing any path thanks to this alias). The alias mechanism is further detailed in the tutorial article on remote bot deployment.

Providers

The GreetingsBot uses a single provider: ChatPlatform.ChatProvider. This means that the bot will receive user intents from the generic ChatProvider defined in the ChatPlatform (the list of each platform's provider is defined in the corresponding wiki article).

Xatkit Tip: no need to parse user input

The intent providers take care of parsing and extracting the intents from the user input. The concrete technology used to perform such parsing is defined in the configuration file. You can forget about intent extraction and natural language parsing and focus on what really matters: the specification of your bot!

Execution Rules

Our example defines 3 execution rules:

  • The first two ones bind the intents defined in GreetingsBot-Lib.intent to ChatPlatform's Reply actions, that are simple actions allowing to post a message as a reply to a user input.
  • The third one is triggered when the Default_Fallback_Intent is received. This intent is defined in the CoreLibrary, and is returned when the underlying intent recognition engine does not find any intent corresponding to the user input. We also bind it to a Reply action, with the dedicated message "Sorry I didn't get it".

Xatkit Tip: multiple actions

You can bind multiple actions to a received intent.

Configuration

We now have defined the intents and the execution logic of our bot. The last step we need to perform is to deploy it. Open GreetingsBot.properties, this file contains the configuration elements required to deploy the developed bot:

Greetings Bot Properties File

Our configuration file contains 3 properties:

  • xatkit.execution.model is mandatory, and specifies the path of the compiled execution file to run. In our example the path is provided as a relative path, but absolute paths are also supported. Note that relative path are relative to the .properties location.
  • xatkit.libraries.custom.<alias_name> is mandatory for each library import with an alias. And specifies the path of the compiled intent library to bind to the alias. As for execution model, both relative and absolute paths are supported. Note that the alias mechanism is further detailed in the tutorial article on remote bot deployment, the key point for now is to make sure that all the aliases defined in your execution model are bound to concrete paths in your configuration.
  • xatkit.platforms.abstract.ChatPlatform = com.xatkit.plugins.react.platform.ReactPlatform specifies which concrete messaging service should be used to deploy the generic ChatPlatform. You can find the list of supported messaging services in this article. In this example we deploy our bot on the React Platform, allowing us to quickly test the bot locally. Different deployment options are covered in this tutorial.

Xatkit defined various properties that can be set in the configuration to customize the behavior and deployment of the bot. You can check the list of all the properties supported by the Xatkit Runtime component here, and find platform-specific properties in the corresponding platform's wiki article.

Start your bot

We now have all the pieces we need to deploy and test our bot! To do so, open a bash interpreter (for Windows users we recommend the one bundled with Git for Windows), navigate to your Xatkit installation's bin directory, and start your bot:

cd $XATKIT/bin
./start-xatkit-windows.sh <path to your GreetingsBot.properties file>

The console will log some initialization information, and after a few seconds you should see the following message:

You can test your chatbot here http://localhost:5000/admin (note that the bots behavior can be slightly different on the test page than when it is deployed on a server)

Open your browser and navigate to http://localhost:5000/admin to test your deployed chat bot!

Greetings Bot Chatbox

Note that in this tutorial we use Xatkit's default intent recognition that performs exact matches based on regular expressions. This means that you have to send messages that are strictly the same as the ones defined in your intents' inputs. The configuration of advanced intent recognition services is detailed in this tutorial article.

Extend the bot

We have now reviewed all the basic concepts to define and deploy bots with Xatkit, and it's time for you to do some homework!

Here are possible extensions that reuse the key points of this tutorial:

  • Extend the intents' input lists with new examples
  • Create new intents to enrich the conversation: for example the intents Fine and Sad could be added to handle the user response to the question "I am fine and you?
  • Use CoreLibrary's Help intent to provide some help information to the user

Xatkit Tip: test your changes

Xatkit doesn't automatically redeploy your bot when you update it. To test a new version of the bot you need to stop the current Xatkit application, and start it again.

If you prefer to check the extended GreetingsBot by yourself you can find it in your local Xatkit installation at this location: xatkit/examples/GreetingsBot-Extended.

What's next?

You can continue reading here to learn how to extract information from user input and how to create complex conversation flows with Xatkit. You can also check this tutorial article to see how to configure Xatkit to use an advanced intent recognition service like Google DialogFlow. If you want to learn more about other messaging services that can be used to deploy the bot you can check this tutorial article.

You can’t perform that action at this time.