A Java framework for building bot brains. Heavily inspired by Amazon Echo's natural language understanding model.
Implements:
- Templated and/or machine learning based identification of a user's intent based on their utterance. Support out of the box for OpenNLP or Facebook's fastText.
- Templated and/or machine learning based (NER) extraction of data from the user's utterance
- State management to support complex conversations, using either:
- a state machine
- Inkle's narrative scripting engine Ink
- Pluggable intent matching, named entity extraction and conversation state management so you can use our own implementations.
The following is the code for a simple Taxi ordering bot. It uses OpenNLP machine learning to identify what the user is asking and to extract street addresses:
public class TaxiInkBot
extends InkBot<TaxiInkBotConfiguration>
{
public TaxiInkBot(TaxiInkBotConfiguration config)
{
super(config);
}
}
Which uses a configuration class to set up the NLP, Ink Story and functions that are used by the bot:
public class TaxiInkBotConfiguration
implements InkBotConfiguration
{
@Override
public IntentMatcher getIntentMatcher()
{
// model was built with OpenNLP whitespace tokenizer
OpenNLPTokenizer tokenizer = new OpenNLPTokenizer(WhitespaceTokenizer.INSTANCE);
// use OpenNLP NER for slot matching
OpenNLPSlotMatcher slotMatcher = new OpenNLPSlotMatcher(tokenizer);
slotMatcher.addSlotModel("Address", "models/en-ner-address.bin");
// create intent matcher
OpenNLPIntentMatcher matcher = new OpenNLPIntentMatcher("models/en-cat-taxi-intents.bin", tokenizer, slotMatcher);
Intent intent = new Intent("OrderTaxi");
intent.addSlot(new LiteralSlot("Address"));
matcher.addIntent(intent);
intent = new Intent("CancelTaxi");
matcher.addIntent(intent);
intent = new Intent("WhereTaxi");
matcher.addIntent(intent);
intent = new Intent("GaveAddress");
intent.addSlot(new LiteralSlot("Address"));
matcher.addIntent(intent);
intent = new Intent("Stop");
matcher.addIntent(intent);
intent = new Intent("Help");
matcher.addIntent(intent);
intent = new Intent("FavColor");
matcher.addIntent(intent);
return matcher;
}
@Override
public String getStoryJson()
{
return StoryUtils.loadStoryJsonFromClassPath("taxibot.ink.json");
}
@Override
public List<InkBotFunction> getInkFunctions()
{
List<InkBotFunction> functions = new ArrayList<>();
functions.add(new InkBotFunction()
{
@Override
public void execute(CurrentResponse currentResponse, Session session, IntentMatch intentMatch,
Story story, String param)
{
try
{
// generate a fake order number based on address for demo
story.getVariablesState().set("taxiNo",
Integer
.toHexString(SessionUtils
.getStringFromSlotOrSession(intentMatch, session, "address", "").hashCode())
.substring(0, 4));
}
catch (Exception e)
{
throw new RuntimeException("Unable to set taxi no", e);
}
}
@Override
public String getFunctionName()
{
return "ORDER_TAXI";
}
});
return functions;
}
@Override
public List<GlobalIntent> getGlobalIntents()
{
List<GlobalIntent> globalIntents = new ArrayList<GlobalIntent>();
globalIntents.add(new GlobalIntent("Stop", "stop"));
globalIntents.add(new GlobalIntent("Help", "help"));
return globalIntents;
}
// ...
}
Here is a snippet of the training data used to train the intents that the bot understands:
OrderTaxi Order me a cab
OrderTaxi Book a cab
OrderTaxi Order me a taxi
OrderTaxi Book a taxi
OrderTaxi Get me a cab
OrderTaxi Order a cab
OrderTaxi Get me a taxi
OrderTaxi Order a taxi
OrderTaxi Send a cab to 123 Mountain Drive
OrderTaxi Pick me up at 456 Queen Street
CancelTaxi Cancel my taxi
CancelTaxi Cancel my cab
CancelTaxi Cancel my order
WhereTaxi Where is my taxi ?
WhereTaxi Where is my cab ?
WhereTaxi How far away is my taxi ?
WhereTaxi How far away is my cab ?
WhereTaxi How long until my cab is here ?
WhereTaxi How long until my taxi is here ?
GaveAddress My address is 173 Essex Drive
GaveAddress The address is 1407 Graymalkin Lane , Salem Center
GaveAddress 52 Festive Road
GaveAddress it's 6151 Richmond Street
GaveAddress The pick up is at 740 Evergreen Terrace
GaveAddress 890 Fifth Avenue
GaveAddress The address is 13 China Ave
GaveAddress 136 River Road
And some of the training data to teach the bot how to identify street addresses:
Send a cab to <START:address> 123 Mountain Drive <END>
The Whitehouse can be found at <START:address> 1600 Pennsylvania Avenue <END> . In the United Kingdom , the official residence of the Prime Minister can be found at <START:address> 10 Downing Street <END> .
In New Zealand , The Beehive can be found in <START:address> Molesworth St <END> .
Pick me up at <START:address> 456 Queen Street <END>
Some other famous addresses include : <START:address> 263 Prinsengracht , Amsterdam <END> , the Home of Anne Frank in her diary and <START:address> 1060 West Addison Street , Chigaco <END> the location of Wrigley Field .
In Seinfield , Newman lives at <START:address> Apartment 5E , 129 West 81st Street <END> .
Lastly here are some snippets from the Ink file that is used to manage the conversation:
== start ==
[OrderTaxi] -> order_taxi
[CancelTaxi] -> cancel_taxi
[WhereTaxi] -> where_taxi
VAR address=""
VAR taxiNo = ""
== order_taxi ==
- (order_taxi_loop)
{
- address == "": -> request_address
- else: -> order_the_taxi
}
= request_address
What is the pick up address ?
::SET_REPROMPT Where would you like to be picked up ?
::SET_HINT 123 Someplace Rd
[GaveAddress]
- -> order_taxi_loop
= order_the_taxi
::ORDER_TAXI
Taxi {taxiNo} is on its way
::ADD_ATTACHMENT type::link url::http:\/\/trackcab.example.com/t/{taxiNo} title::Track your taxi here
::ADD_QUICK_REPLY Where is my taxi?
::ADD_QUICK_REPLY Cancel my taxi
-> END
If you are using Gradle you can pull (for the example above) the latest release with:
repositories {
mavenCentral()
}
dependencies {
compile 'com.rabidgremlin:mutters-ink-bot:7.1.0'
compile 'com.rabidgremlin:mutters-opennlp-intent:7.1.0'
compile 'com.rabidgremlin:mutters-opennlp-ner:7.1.0'
compile 'com.rabidgremlin:mutters-slots:7.1.0'
}
Currently SNAPSHOT builds are available in the Sonatype OSSRH repository.
Using Gradle you can pull the snapshot using:
repositories {
mavenCentral()
maven {
url "https://oss.sonatype.org/content/repositories/snapshots/"
}
}
dependencies {
compile 'com.rabidgremlin:mutters-ink-bot:7.1.0-SNAPSHOT'
compile 'com.rabidgremlin:mutters-opennlp-intent:7.1.0-SNAPSHOT'
compile 'com.rabidgremlin:mutters-opennlp-ner:7.1.0-SNAPSHOT'
compile 'com.rabidgremlin:mutters-slots:7.1.0-SNAPSHOT'
}
Mutters is packaged into multiple jars to reduce dependencies and improve plugability.
Package | Description |
---|---|
mutters-core | Contains core classes, interfaces and utility classes |
mutters-fasttext-intent | Intent matcher that uses the fastText document classifier |
mutters-ink-bot | Implementation of a Bot that uses Inkle's Ink engine for conversation scripting |
mutters-opennlp-intent | Intent matcher that uses OpenNLP's document classifier |
mutters-opennlp-ner | Slot matcher that uses OpenNLP's named entity recognition framework |
mutters-slots | Implementation of a number of generic Slots |
mutters-statemachine-bot | Implementation of a Bot that uses a state machine for conversation flows |
mutters-templated-intent | Intent matcher that uses templates for matching |