Bot Basics with Articulate

Let’s go from installation to working bot with Articulate

One of the first Medium posts from Smart Platform Group was a tutorial on building a basic bot using Rasa for natural language understanding (NLU) and Node-RED. It was simple and only had a couple of capabilities: Chuck Norris jokes and providing questionable advice. For example it could respond to questions like the below:

• I want to hear a Chuck Norris joke.
• What does Chuck Norris have to say about love?
• I need advice.
• Can you give me some advice about love?

Now that we’ve released Articulate, a UI for conversational agents, it’s time to revisit that tutorial and create the same agent. For an introduction video to Articulate see our release post below, but don’t worry we’ll cover everything in that video and then some!

Introducing Articulate

Prerequisites and Installation

Articulate is a collection of services working together. It uses Rasa NLU for language understandning, Duckling for date/time parsing, and Redis for storage. We use docker-compose to package everything up nicely and give a single command for bringing all of those services up. Before we get started you’re going to need to make sure you have two tools installed:

• Docker — To test type docker -v in a terminal or command prompt. Your response should be something similar to Docker version 18.03.0-ce, build 0520e24

Docker RAM Consideration — If you are running this on linux then you shouldn’t have a problem, but if you are running on Mac or Windows you will need to increase the memory allocated to Docker to at least 4Gb.

• Docker-Compose — To test type docker-compose -v in a terminal or command prompt. You should get a response similar to this one: docker-compose version 1.20.1, build 5d8c71b

☞ Visit our Releases Page to Download the Latest .zip

You’re looking for a file that looks like articulate-vX.X.X.zip. Once you’ve found it click on it to download

☞ Unzip and Open that Folder in a Terminal or Command Prompt

This step is a little bit different for everyone. On a Mac the file is often unzipped for you. But on Windows or Linux you may need to extract it.

☞ Execute the Below Command

You should see Docker start downloading and installing images. If you don’t, make sure the directory you are in is the folder you just downloaded and unzipped. If you have trouble join us on our Gitter for help. If you’re on Linux you may need sudo

docker-compose up

None of the services take very long to start, once you see something like the below then you are ready to use Articulate:

ui_1        | webpack built 42cf798b396b7049f433 in 6607ms

☞ In your Browser go to http://localhost:3000

This is the default address for the Articulate UI. In the release that I am running for this tutorial here is what it looks like. (Image 1)

Image 1 —The Articulate welcome page.

For a breakdown of the functionality on each page check out our documentation. But for now we’re going to:

1. Create an Agent
2. Create a Domain
3. Create a few Intents

☞ Click the Create Agent button on the top of the page.

For more information on this page look here. But for the moment you only need to give your agent a name and a description. Once you are finished click the create button at the top of the screen. (Image 2)

Image 2 — The create Agent screen.

Now that you have an agent Articulate should have taken you to a screen for creating a domain. Domains are a special piece of Articulate and they influence how it handles classification and conversation.

What’s a domain —simply put: a domain is nothing more than a collection of similar intents. If you’re creating an enterprise agent they may be departments: sales, finance, operations, marketing. Or if you are creating a travel bot they may be grouped around travel methods or services: hotels, trains, planes, activities.

Let’s create our first domain. For us it is going to be the Small Talk domain. A place where we will handle the greet and goodbye intents.

☞ Click the Create Domain button on the top of the page.

For more information on this page look here. But for the moment you only need to name your domain Small Talk. Once you are finished click the create button at the top of the screen. (Image 3)

Image 3 — The create Domain screen.

Now for the first time in this tutorial you have 2 choices! Do you create an intent or an entity? This is an easy question to answer: Does your intent needs entities? If so you need to create those entities before creating that intent.

That being said the first intents we are going to create are simple ones with no entities. So let’s jump right in to defining our first intent.

☞ Click the Create Intent button on the top of the page.

This page is a little more complicated so let’s walk through the steps one at a time. The docs for this page are here. (Image 4)

• Select a domain from the dropdown list — For the moment you only have one to select from. This intent will be part of the Small Talk domain
• Give your intent a name — We’ll start by making the Greet intent.
• Provide some examples in the User Says section — This is really where the heart of Articulate is. You provide articulate with several (5–10) examples of how users would ask for something and it tries to generalize beyond those examples to gain understanding of the user would invoke this intent. See the below image for all of the examples I provided.

We’re skipping slots, but we’ll be back to them when we create the Chuck Norris intent.

• Create some Agent Response examples — When Articulate recognizes that a user has made a greeting, how should it respond? That is what agent responses are for.

See the image below for my completed intent.

Image 4 — Create Intent page in Articulate

☞ Once finished click the create button to create your intent

Once you do this you’ll see a spinning wheel show up on your screen. This wheel indicates that the model is training. It shouldn’t take to long (less than 30 seconds).

Once you’re first intent is finished training you’ll be redirected back to the intent list page. We need to create one more intent in the small talk domain to handle goodbyes. I’m going to leave this one up to you.

☞ Create the Goodbye Intent in the Small Talk Domain

This intent is on you, remember we’re trying to create the Goodbye intent in the Small Talk domain. See the image below for what I ended up with. Once you’re finished don’t forget to click the create button and wait for the training to finish. (Image 5)

Image 5 — The completed Goodbye intent.

Now we’re going to define an entity. If you worked through the original Rasa NLU tutorial series then you may remeber that both of the primary intents used an entity called topic. In the examples we mentioned at the start of the article the highlighed items are examples of the topic entity:

• What does Chuck Norris have to say about love?
• Can you give me some advice about love?

So let’s create the topic entity now.

☞ From the entity page click Create Entity

On the entity page you should start with proving a name: Topic. Then start adding different values. For this bot we don’t need to change the entity color or use synonyms. For more on those features see the drCocs here. The below image shows all of the values I provided. (Image 6)

Image 6 — Creating our only entity

Once you’re finished and click the create button you may notice that no training occured. That is because the entities have to get used in an intent before they are added to the machine learning model that Articulate creates.

On that note, let’s create our first intent that uses them. Since our bot is a very simple one I am going to leave these intents in the Small Talk domain, but we could just as easily have created a new domain for them.

☞ From the intent page click Create Intent

This time we are going to create the Chuck Norris intent. See the image below for all of the examples I provided. (Image 7)

Image 7 — The beginning of our Chuck Norris intent.

☞ Highlight the entities and select the topic entity

Now that we’ve told Articulate how users may ask for a Chuck Norris joke we also need to teach it how to recognize the topic entity. To do this we highlight each entity in the examples provided and tag it. See the gif below to see me tag the entities. (Image 8)

Image 8 — Highlighting entities in the user says examples.

Finally we need to create the agent’s response, but in this case it is a bit more complicated because we are going to use a webhook for fulfillment.

☞ Toggle the webhook functionality on

At the top of the intent page there is a slider to toggle the webhook on and off. Click on it to toggle them on. (Image 9)

Image 9 — Create intent page with the webhook toggled on.

Once you do this a new section will show up on the page where you can provide a method, url, and payload for creating webhooks. There are two URLs we are going to use for the Chuck Norris intent. Since this is our Chuck Norris joke intent we’ll be connecting it to the chuck norris api. In the case where we have a topic entity we’ll be using this url:

https://api.chucknorris.io/jokes/search?query={QUERY}

But in the case where we don’t have a query we’ll use this:

https://api.chucknorris.io/jokes/random

To accomplish the logic of which url to use we are going to use handlebars. We’re planning a whole post on advance usage of Handlebars with Articulate, but for now we’ll tell you exactly what you need to do.

☞ In the URL of the webhook section paste the below handlebar

Even with little to no coding experience hopefully the intent of this snippet is clear: if we have a topic use one URL, but if we don’t then we will use another. (Image 10)

{{#if slots.Topic}}
  https://api.chucknorris.io/jokes/search?query={{slots.Topic.value}}
{{else}}
  https://api.chucknorris.io/jokes/random
{{/if}}

☞ Create agent responses from the below snippets

For each URL that we used above the return webhook payload is slightly different. For that reason we have to provide two different agent responses. Below are the snippets, but to see the finished thing see (Image 10) The first one is easy and is the case where we don’t have a topic entity:

{{webhookResponse.value}}

In this case we can directly return the value from the webhook. But in the case of a topic entity we have to check and see if any jokes where found for that topic and then return a random one from the list. That agent response looks like:

{{#if (gt webhookResponse.total compare="0")}}
  {{#with (lookup webhookResponse.result (random 0 webhookResponse.total))}}
    {{value}}
  {{/with}}
{{else}}
  Sorry I couldn't find a Chuck Norris joke about {{slots.[Topic].value}}
{{/if}}

This small snippet from handlebars check if the total from the response is greater than 0 if it is it grabs a random item from the array. If it isn’t it apologizes for not being able tofind a joke about that topic.

Here is what my complted Webhook and Agent Responses look like:

Image 10 — Completed Webhook and agent response configuration for the Chuck Norris intent.

☞ Create the Advice Intent in the Small Talk Domain

This intent is on you, remember we’re trying to create the Advice intent in the Small Talk domain. This intent will be very similar to the Chuck Norris one and I will even provide the agent response snippets for you. (Image 11)

Though this intent is for you to tackle, here are the URLs we’re going to use for the API calls. If there is a topic we will call this one:

http://api.adviceslip.com/advice/search/{query

And here is the URL we will use when we don’t have a topic entity:

http://api.adviceslip.com/advice

You can use those to generate the URL just like we did in the Chuck Norris intent. Here is what my finished handlebars snippet looked like:

{{#if slots.Topic}}
  http://api.adviceslip.com/advice/search/{{slots.Topic.value}}
{{else}}
  http://api.adviceslip.com/advice
{{/if}}

And again in each case the returned payloads are slighty different so we need two agent responses. This first one is the case for when we don’t have a topic entity and use the URL that just returns random advice:

{{webhookResponse.slip.advice}}

And here is the slightly more involved agent response for when we search for a particular topic. The structure is exactly the same as above, but we’ve had to modify it for this new API.

{{#if (gt webhookResponse.total_results compare="0")}}
  {{#with (lookup webhookResponse.slips (random 0 webhookResponse.total_results))}}
    {{advice}}
  {{/with}}
{{else}}
  Sorry I couldn't find any advice about {{slots.[Topic].value}}
{{/if}}

Use the below image to see what my final Advice intent looks like.

Image 11 — The completed Advice intent with webhook and responses configured.

Okay now that we have all of our intents created and trained it’s time for the moment of truth. Can we interact with out bot? Go ahead and give it a try in the chat panel off to the right hand side of the screen.

Image 12 — Chatting with our bot.

Wrapping Up

That’s a pretty simple example and if you keep playing with it you will likely encounter several places where the bot misunderstands things. My bot was struggling with hello. When this happens you generally just need to provide more training examples. Go into the intent and add the phrase that failed (even if it is already there) and you will re-inforce it’s understanding for that intent.

We probably also need to provide more small talk intents (you’ll notice I added one for Gratitude). And we aren’t handling all of the cases the API can return; for example, errors.

Hopefully through the above you can see how Articulate reduces the effort required for making chatbots. Even ones connected to APIs for fulfillment. We’re rapidly adding more functionality and patching bugs. We’d love for you to join our community and help us grow Articulate into a platform for truely intelligent agents. Join us on Gitter, create an issue, or open a pull request: we’re looking forward to it!