Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/RocketChat/hubot-natural

Natural Language Processing Chatbot for RocketChat
https://github.com/RocketChat/hubot-natural

chatbot coffeescript hubot hubot-natural nlp nodejs rocketchat rocketchat-hubot

Last synced: about 2 months ago
JSON representation

Natural Language Processing Chatbot for RocketChat

Host: GitHub
URL: https://github.com/RocketChat/hubot-natural
Owner: RocketChat
License: mit
Created: 2017-05-01T17:41:06.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2022-12-13T03:45:35.000Z (about 2 years ago)
Last Synced: 2024-10-07T06:57:17.721Z (3 months ago)
Topics: chatbot, coffeescript, hubot, hubot-natural, nlp, nodejs, rocketchat, rocketchat-hubot
Language: CoffeeScript
Homepage: https://open.rocket.chat/channel/hubot-natural
Size: 470 KB
Stars: 144
Watchers: 21
Forks: 44
Open Issues: 21
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

# Hubot Natural

[![Build Status](https://travis-ci.org/RocketChat/hubot-natural.svg?branch=master)](https://travis-ci.org/RocketChat/hubot-natural)

## Natural Language ChatBot

Hubot is one of the most famous bot creating framework on the web, that's because github made it easy to create. If you can define your commands in a RegExp param, basically you can do anything with Hubot. That's a great contribution to ChatOps culture.

Inspired by that, we wanted to provide the same simplicity to our community to develop chatbots that can actually process natural language and execute tasks, as easy as building RegExp oriented bots.

So, we've found a really charming project to initiate from, the [Digital Ocean's Heartbot](https://github.com/digitalocean/heartbot) _a shot of love to for your favorite chat client_ =)

Based on Heartbot, we introduced some NLP power from [NaturalNode](https://github.com/NaturalNode/natural) team, an impressive collections of Natural Language Processing libs made to be used in NodeJS.

And so, the _magic_ happens...

Welcome to *HubotNatural*, a new an exciting chatbot framework based in Hubot and NaturalNode libs, with an simple and extensible architecture designed by Digital Ocean's HeartBot Team, made with love and care by Rocket.Chat Team.

We hope you enjoy the project and find some time to contribute.

## How it Works

HubotNatural is made to be easy to train and extend. So what you have to understand basically is that it has an YAML corpus, where you can design your chatbot interactions using nothing but YAML's notation.

All YAML interactions designed in corpus can have it's own parameters, which will be processed by an event class.

Event classes give the possibility to extend HubotNatural. By writing your own event classes you can give your chatbot the skills to interact with any services you need.

### YAML corpus

The YAML file is loaded in `scripts/index.js`, parsed and passed to chatbot bind, which will be found in `scripts/bot/index.js`, the cortex of the bot, where all information flux and control are programmed.

The YAML corpus is located in `training_data/corpus.yml` and it's basic structure looks like this:

```yaml
trust: .85
interactions:
- name: salutation
expect:
- hi there
- hello everyone
- what's up bot
- good morning
answer:
- - Hello there $user, how are you?
- Glad to be here...
- Hey there, nice to see you!
event: respond
```

What this syntax means:

- `trust`: the minimum level of certain that must be returned by the classifier in order to run this interaction. Value is 0 to 1 (0% to 100%). If a classifier returns a value of certainty minor than `trust`, the bots responds with and error interaction node.
- `interactions`: An vector with lots of interaction nodes that will be parsed. Every interaction designed to your chatbot must be under an interaction.node object structure.
- `name`: that's the unique name of the interaction by which it will be identified. Do not create more than one interaction with the same `node.name` attribute.
- `expect`: Those are the sentences that will be given to the bots training. They can be strings or keywords vectors, like `['consume','use']`.
- `answer`: the messages that will be sent to the user, if the classifiers get classified above the trust level. The `node.message` will be parsed and sent by event class. In order to use multiline strings inside your YAML, you must follow the [YAML Multiline Strings](http://yaml-multiline.info/) syntax. You can specify variables in message. By default HubotNatural comes with `$user`, `$bot` and `$room` variables.
- `event`: is the name of the CoffeeScript or JavaScript Class inside `scripts/events`, without the file extension.

### Event Coffee Classes

Event classes can be written to extend the chatbot skills. They receives the interaction object and parse the message, like this:

```yaml
class respond
constructor: (@interaction) ->
process: (msg) =>
sendMessages(stringElseRandomKey(@interaction.answer), msg)

module.exports = respond
```

It's base constructor is the `@interaction` node so you can have access to all attributes inside an interaction just using `@interaction.attribute`. Here you can parse texts, call APIs, read files, access databases, and everything else you need.
You may want to use the function `stringElseRandomKey` to get a random element of a list, if it's parameter is a list, and use the function `sendMessages` to send messages to an user.

#### Logistic Regression Classifier

The NaturalNode library comes with two kinds of classifiers, the Naive Bayes classifier known as the `BayesClassifier` and the `LogisticRegressionClassifier` functions. By default, HubotNatural uses the `LogisticRegressionClassifier`. It just came with better results in our tests.

#### PorterStemmer

There is also more than one kind of stemmer. You should set the stemmer to define your language. By default we use the PorterStemmerPt for portuguese, but you can find english, russian, italian, french, spanish and other stemmers in NaturalNode libs, or even write your own based on those.

Just check inside `node_modules/natural/lib/natural/stemmers/`.

To change the stemmers language, just set the environment variable `HUBOT_LANG` as `pt`, `en`, `es`, and any other language termination that corresponds to a stemmer file inside the above directory.

## Deploy with Docker

We have a Dockerfile that builds a lightweight image based in Linux Alpine with all the repository content so you can upload that image to a docker registry and deploy your chatbot from there. It is located on `docker` folder.

You also can use `docker-compose.yml` file to load a local instance of Rocket.Chat, MongoDB and HubotNatural services, where you can change the parameters if you must.

The docker-compose file looks like this:

```yaml
version: '2'

services:
rocketchat:
image: rocketchat/rocket.chat:latest
restart: unless-stopped
volumes:
- ./uploads:/app/uploads
environment:
- PORT=3000
- ROOT_URL=http://localhost:3000
- MONGO_URL=mongodb://mongo:27017/rocketchat
- MONGO_OPLOG_URL=mongodb://mongo:27017/local
- MAIL_URL=smtp://smtp.email
# - HTTP_PROXY=http://proxy.domain.com
# - HTTPS_PROXY=http://proxy.domain.com
depends_on:
- mongo
ports:
- 3000:3000

mongo:
image: mongo:3.2
restart: unless-stopped
volumes:
- ./data/db:/data/db
#- ./data/dump:/dump
command: mongod --smallfiles --oplogSize 128 --replSet rs0

mongo-init-replica:
image: mongo:3.2
command: 'mongo mongo/rocketchat --eval "rs.initiate({ _id: ''rs0'', members: [ { _id: 0, host: ''localhost:27017'' } ]})"'
depends_on:
- mongo

hubot-natural:
build: .
restart: unless-stopped
environment:
- HUBOT_ADAPTER=rocketchat
- HUBOT_NAME='Hubot Natural'
- HUBOT_OWNER=RocketChat
- HUBOT_DESCRIPTION='Hubot natural language processing'
- HUBOT_LOG_LEVEL=debug
- HUBOT_CORPUS=corpus.yml
- HUBOT_LANG=pt
- RESPOND_TO_DM=true
- RESPOND_TO_LIVECHAT=true
- RESPOND_TO_EDITED=true
- LISTEN_ON_ALL_PUBLIC=false
- ROCKETCHAT_AUTH=password
- ROCKETCHAT_URL=rocketchat:3000
- ROCKETCHAT_ROOM=GENERAL
- ROCKETCHAT_USER=botnat
- ROCKETCHAT_PASSWORD=botnatpass
- HUBOT_NATURAL_DEBUG_MODE=true
volumes:
- ./scripts:/home/hubotnat/bot/scripts
- ./training_data:/home/hubotnat/bot/training_data
depends_on:
- rocketchat
ports:
- 3001:8080
```

You can change the attributes of variables and volumes to your specific needs and run `docker-compose up` in terminal to start the rocketchat service at `http://localhost:3000`.
*ATTENTION:* You must remember that hubot must have a real rocketchat user created to login with. So by the first time you run this, you must first go into rocketchat and create a new user for hubot, change the `ROCKETCHAT_USER` and `ROCKETCHAT_PASSWORD` variables in the docker-compose.yml file, and then reload the services using `docker-compose stop && docker-compose up` to start it all over again.

If you want to run only the hubot-natural service to connect an already running instance of Rocket.Chat, you just need to remember to set the `ROCKETCHAT_URL` to a correct value, like `https://open.rocket.chat`.

## Bot configuration

In order to correctly use Hubot Natural, after running `docker-compose up` command, it is necessary to do some configuration steps. To do that, there are two main options:

The first one is to do manually the steps described at [bot config documentation](docs/config_bot.md).

The second option is to execute the script `bot_config.py`, located at root directory on project. That will automatically configure bot based on following variables defined on script: `admin_name, admin_password, bot_name` and `bot_password`. It is important to remember of properly set the values of this variables according to the context. The values used on `bot_name` and `bot_password` must be the same defined on docker-compose.yml, on the variables `ROCKETCHAT_USER` and `ROCKETCHAT_PASSWORD` respectively. And the values defined at `admin_name` and `admin_password` variables must be the credentials of an pre existent user on rocketchat, that has admin permissions.

To create an admin user automatically, before executing the services, just define the variables `ADMIN_USERNAME` and `ADMIN_PASS` for rocketchat service on `docker-compose.yml`.

## Deploy with Hubot

To deploy HubotNatural, first you have to install yo hubot-generator:

```shell
npm install -g yo generator-hubot
```

Then you will clone HubotNatural repository:

```shell
git clone https://github.com/RocketChat/hubot-natural.git mybot
```

Change 'mybot' in the git clone command above to whatever your bot's name will be, and install hubot binaries, without overwitting any of the files inside the folder:

```shell
cd mybot
npm install
yo hubot

_____________________________
/ \
//\ | Extracting input for |
////\ _____ | self-replication process |
//////\ /_____\ \ /
======= |[^_/\_]| /----------------------------
| | _|___@@__|__
+===+/ /// \_\
| |_\ /// HUBOT/\\
|___/\// / \\
\ / +---+
\____/ | |
| //| +===+
\// |xx|

? Owner Diego
? Bot name mybot
? Description A simple helpful chatbot for your Company
? Bot adapter rocketchat
create bin/hubot
create bin/hubot.cmd
conflict Procfile
? Overwrite Procfile? do not overwrite
skip Procfile
conflict README.md
? Overwrite README.md? do not overwrite
skip README.md
create external-scripts.json
create hubot-scripts.json
conflict .gitignore
? Overwrite .gitignore? do not overwrite
skip .gitignore
conflict package.json
? Overwrite package.json? do not overwrite
skip package.json
create scripts/example.coffee
create .editorconfig
```

Now, to run your chatbot in shell, you should run:

```shell
bin/hubot
```

wait a minute for the loading process, and then you can talk to mybot.

Take a look to adapters to run your bot in other platafforms.

## Configure Live Transfer

It's possible to configure Hubot Natural to redirect conversation to a real person, in moments when the bot can not help users as much as needed.
To activate and configure `Live Transfer` feature, follow the steps described on [live transfer config documentation](docs/config_live_transfer.md).

## Env Variables:

In your terminal window, run:

```shell
export HUBOT_ADAPTER=rocketchat
export HUBOT_OWNER=RocketChat
export HUBOT_NAME='Bot Name'
export HUBOT_DESCRIPTION='Description of your bot'
export ROCKETCHAT_URL=https://open.rocket.chat
export ROCKETCHAT_ROOM=GENERAL
export LISTEN_ON_ALL_PUBLIC=false
export RESPOND_TO_DM=true
export RESPOND_TO_LIVECHAT=true
export ROCKETCHAT_USER=catbot
export ROCKETCHAT_PASSWORD='bot password'
export ROCKETCHAT_AUTH=password
export HUBOT_LOG_LEVEL=debug
export HUBOT_CORPUS='corpus.yml'
export HUBOT_LANG='en'
bin/hubot -a rocketchat --name $HUBOT_NAME
```

You can check [hubot-rocketchat](https://github.com/RocketChat/hubot-rocketchat) adapter project for more details.

### PM2 Json File

As NodeJS developers we learned to love [Process Manager PM2](http://pm2.keymetrics.io), and we really encourage you to use it.

```shell
npm install pm2 -g
```

Create a `mybot.json` file and jut set it's content as:

```json
{
"apps": [{
"name": "mybot",
"interpreter": "/bin/bash",
"watch": true,
"ignore_watch" : ["client/img"],
"script": "bin/hubot",
"args": "-a rocketchat",
"port": "3001",
"env": {
"ROCKETCHAT_URL": "https://localhost:3000",
"ROCKETCHAT_ROOM": "general",
"RESPOND_TO_DM": true,
"ROCKETCHAT_USER": "mybot",
"ROCKETCHAT_PASSWORD": "12345",
"ROCKETCHAT_AUTH": "password",
"HUBOT_LOG_LEVEL": "debug"
}
}
]
}
```

You can also instantiate more than one process with PM2, if you want for example to run more than one instance of your bot:

```json
{
"apps": [{
"name": "mybot.0",
"interpreter": "/bin/bash",
"watch": true,
"ignore_watch" : ["client/img"],
"script": "bin/hubot",
"args": "-a rocketchat",
"port": "3001",
"env": {
"ROCKETCHAT_URL": "https://localhost:3000",
"ROCKETCHAT_ROOM": "general",
"RESPOND_TO_DM": true,
"ROCKETCHAT_USER": "mybot",
"ROCKETCHAT_PASSWORD": "12345",
"ROCKETCHAT_AUTH": "password",
"HUBOT_LOG_LEVEL": "debug"
}
}, {
"name": "mybot.1",
"interpreter": "/bin/bash",
"watch": true,
"ignore_watch" : ["client/img"],
"script": "bin/hubot",
"args": "-a rocketchat",
"port": "3002",
"env": {
"ROCKETCHAT_URL": "https://mycompany.rocket.chat",
"ROCKETCHAT_ROOM": "general",
"RESPOND_TO_DM": true,
"ROCKETCHAT_USER": "mybot",
"ROCKETCHAT_PASSWORD": "12345",
"ROCKETCHAT_AUTH": "password",
"HUBOT_LOG_LEVEL": "debug"
}
}
]
}
```

And of course, you can go nuts setting configs for different plataforms, like facebook mensenger, twitter or telegram ;P.

## Hubot Adapters

Hubot comes with at least 38 adapters, including Rocket.Chat addapter of course.
To connect to your Rocket.Chat instance, you can set env variables, our config pm2 json file.

Checkout other [hubot adapters](https://github.com/github/hubot/blob/master/docs/adapters.md) for more info.

## Thanks to

In Rocket.Chat we are so in love by what we do that we couldn't forget to thanks everyone that made it possible!

### Github Hubot Team

Thanks guys for this amazing framework, hubots lives in the heart of Rocket.Chat, and we recommend everyone to checkout https://hubot.github.com and find much much more about hubot!

### Natural Node Project

To the NaturalNode Team our most sincere "THAK YOU VERY MUCH!! We loved your project and we are excited to contribute!".
Checkout https://github.com/NaturalNode/natural and let your mind blow!

### Digital Ocean's Heartbot

We can not thanks Digital Ocean enough, not only for this beautifull [HeartBot project](https://github.com/digitalocean/heartbot), but also for all the great tutorials and all the contributions to OpenSource moviment.

### Thanks to Our Community

And for last but not least, thanks to our big community of contributors, testers, users, partners, and everybody who loves Rocket.Chat and made all this possible.