README

JARVIS

A JARVIS for your team - your most powerful bot and loyal butler. Jarvis was originally built for GLOBAL_HACKERS as our smart, humorous and sentient team assistant.

The most popular and powerful features for us include todo, reminder, memes, search, and a machine learning module. See the design and all the features.

Installation

Clone this git repo:

git clone <the-url-of-this-repo>

Also available as an NPM package:

npm install jarvis-bot

Next, install the dependencies:

npm install

Then setup and deploy.

Tl;dr: If you're using Slack, just set bin/.env file, fill the bin/.env-jarvis with API tokens and run npm start.

forever

npm start runs app.js, which uses forever-monitor. This is for when you don't have sudo to install forever on the machine you're deploying on. This has the issue of nested processes not being terminated properly (a forever issue.)

Things are nicer if you use forever from the terminal, you can deploy/stop multiple instances (after specifying the right file in .env) like below:

forever start --killSignal=SIGTERM -a -l jarvis.log --uid "jarvis" run.js
forever start --killSignal=SIGTERM -a -l veronica.log --uid "veronica" run.js

Note that you must set --killSignal=SIGTERM to properly kill off hubot. You can kill like below:

# stop an instance
forever stop jarvis
# stop all instances
forever stopall

forever in npm

I'm a lazy person. So I save the forever commands above in the npm scripts. For example in package.json:

"scripts": {
    "start": "node app.js",
    "stop": "forever stopall",
    "jarvis": "forever start --minUptime=1000 --spinSleepTime=1000 --killSignal=SIGTERM -a -l jarvis.log --uid 'jarvis' app.js",
    "veronica": ...
},

So instead of typing that long command for forever, you can

# runs that long forever command
npm run jarvis

To stop all forever processes,

npm stop

Setup

.env

Jarvis uses many APIs, and some of them need tokens. Set the environment variables for each instance of your bot in bin/.env-<bot>. Most of them should be straightforward to obtain, others you can Google how to. Below is a few, explained:

HUBOT_SLACK_TOKEN: You have to add a bot integration under your Slack team setting, and generate a token to use.
HUBOT_REPOPATH: This is the bot's repo that you're syncing the memory with.
HUBOT_GHTOKEN: To sync memory (upload to Github), you need to allow access and generate a token from your account.
HUBOT_GOOGLE_API_KEY: You need a Google developer account, then create a project, choose the APIs to enable, and generate a "browser token" from the Google Developer Console.

Beware, don't expose your .env-<bot> files to other people. That's common sense.

admins

A few bot functions such as memory upload and twitter posts are restricted to admins. Specify their email addresses, comma separated, in bin/.env-<bot>. Note that the incoming user object from Slack has the email field, so if you're using a different adapter, you may need to hack around it from scripts/helper.coffee.

The reason for using email address is because username can be changed (in Slack) and thus be faked.

adapter

The default adapter is Slack. To change it, find them here. NPM uninstall hubot-slack, install your adapter, and specify it in bin/.env.

Since the text formatting are meant for Slack, you may need to hack the scripts a bit when you're using a different chat platform, especially with how the admin emails are recognized.

Deploy

If you're using Slack, then deployment is super simple. Simply set your API keys in bin/.env-<bot> and specify which bot to deploy in bin/.env, then you're ready. See Setup.

Deploy anywhere you want: Heroku, GCloud, AWS, your local Unix machines. There is no need to setup the bot environment variables yourself because app.js handles them for you. As long as npm install and npm start (which runs node app.js) are run, you're good.

Jarvis is quasi-immortal. He will never sleep (uses cron), and will resurrect upon death (uses forever-monitor).

Test-run locally with

npm start

Even though Jarvis is platform neutral, we deploy ours to Google Cloud, so the files .dockerignore, Dockerfile, app.yaml are needed. Remove and add any deployment config files as you need if you deploy somewhere else.

Design

We built Jarvis to be the smart assistant for our team. The design is based on hubot, and we have made significant improvements to its core but you probably won't notice. So, if you've had experience with hubot, you'll know how to extend Jarvis by writing your own scripts.

Jarvis' internal modules are different from the original hubot:

hubot-keep-alive is removed and replaced by the more elegant cron
external persistent memory in sync with the bot's Github
a more helpful help menu with categorization, under scripts/cmdhelp.coffee
several other internal modules are replaced by better ones

All the modules and hubot scripts are in node_modules and scripts, following the original hubot design. lib contains your non-hubot-interface scripts. In short, organize as you like, but the bot interface scripts shall be in the scripts folder.

Platform-neutral

Just like the original hubot, Jarvis is platform-neutral. We deploy our Jarvis on Slack, but you can choose your own platform by simply changing the adapter (see Setup).

The powerful thing is that you can access Jarvis from anywhere! We use Slack, so we can call Jarvis from the Slack apps for mobile, laptop, and web.

Features

We lost count on the number of features. There's currently over 30 modular scripts (some under node_modules). Feel free to remove/add any from your bot as you like. If you got a brilliant idea, suggest to us!

List of features
Minimal setup, quick deployment
Platform and deployment neutral
Quasi-immortality
Admins
Memory - persistent and synced with Github
Custom command help
User aliasing, serialization, recognition
User geolocation, time, weather, maps
Reminder, todo
Google search, image, translate, maps, directions, youtube
Hackers News
Twitter search/post
Machine learning/sentiment analysis
Lomath
Chatbot
Memes and jokes

Minimal setup, quick deployment

You don't have to do much to start using Jarvis. Just get your API keys/tokens for the APIs you wish to use to put in .env-jarvis under bin/. If you have several teams to deploy the bots for, you can have multiple .env-<bot> files. Before deploying, specify the bot you wish to deploy in .env.

This assumes you're using Slack of course. For more advanced tweaks, see Setup.

Platform and deployment neutral

Jarvis is designed to be deployed anywhere. All its internal environment variables are specified in .env-<bot> file, and it sets them automatically when run. This nicely prevents fragmentation of providing different env files per deployment, like app.yaml for Gcloud, and app.json for Heroku.

We use Slack, but you can just use pretty much anything else: Whatsapp, Telegram, FB chat, Skype. Just replace the hubot adapter by specifying it in package.json and .env.

The powerful thing is that you can access Jarvis from anywhere! We use Slack, so we can call Jarvis from the Slack apps for mobile, laptop, and web.

Quasi-immortality

My team likes to break things, and Jarvis was the obvious target.

Jarvis is quasi-immortal. He will never sleep (uses cron), and will resurrect upon death (uses forever-monitor). So, kill him as many times as you wish, he will always come back to live, unless if the server farm gets nuked of course.

Admins

There are things that should be accessible only to admins. One example is memory sync (below), where only admins can make Jarvis upload his memory. See .env-<bot> to set the admins for each bot.

Memory - persistent and synced with Github

We constantly improve Jarvis, thus the source code is kept on Github. However, when we redeploy Jarvis (due to death or new iteration), we want him to remember us.

Jarvis's hubot.brain.data persistent memory is kept under memory/braindata.json. You can get creative and make your own modular memory.

When deployed, Jarvis can sync its new memory with its Github, so before redeploying, you can just do git pull to update the local memory. Then the new Jarvis will remember.

It's scheduled to auto-upload its brain to Github every midnight, but admin can also manually tell Jarvis to do so. The commands for this module is hidden to prevent tampering, so dig into the source code. See scripts/memsync.coffee, where you can set a magic word to call, and if you're an admin, Jarvis will upload his brain.

Custom command help

You can organize all your help commands into types. See typedCmd in scripts/helper.coffee, where the JSON goes from type to module to the command regex of the module. Currently there are 3 types: fun, bot, util, and each has its own modules(named as you like). The array for each module contains its command regexs, which are used for preventing conflict in input-parsing.

Below is the help in action, going down the level of specificity. Furthermore, help <term> displays all the helps that match the <term>.

User aliasing, serialization, recognition

Jarvis recognizes users by their usernames; you can also add aliases.

With the recognition, Jarvis can serialize its functions such as weather and reminders to cater to individual users. You can call the functions using aliases too. Furthermore, Jarvis will recognize fuzzy usernames (lexicographically, so be careful).

User geolocation, time, weather, maps

Our team is global, so it's handy to know where someone is and the time there. User serialization is used here, so simply tell Jarvis where you are, and when you call the functions, Jarvis will use your location.

Reminder, todo

Jarvis can remind you of things at certain time, and keep a todo list for you. Of course you can have Jarvis remind your teammates of their tasks.

Reminder is time sensitive, and defaults to 1h if time is not specified: remind

Todo list is not time sensitive: todo

Google search, image, translate, maps, directions, youtube

Jarvis uses many Google APIs (you'll need your own Google developer API keys) to use them. google

Jarvis recognizes me or user aliases when using locations. directions

Hackers News

No hackers can do without Hackers News, so here it is:

Twitter search/post

Jarvis can search on Twitter, and post (admin only). tweet

Machine learning/sentiment analysis

This is the first stage of an AI Jarvis, and scripts/sentiment.coffee is its first machine learning module. This pulls search results from Twitter, feeds it to Indico.io, and returns the sentiment. This is especially handy for observing the trend of a topic on Twitter, say a stock.

Expect more AI/ML features to come soon, since the author is studying that.

Lomath

Lomath is a math library extended from lodash. You can evaluate a lomath function from Jarvis as you would code it, which also means you can use lodash.

Chatbot

To make Jarvis more human-like, we added a chatbot module to it. Whenever you say something that doesn't match a command regex of typedCmd in scripts/helper.coffee, it will be redirected to the chat module.

The chat module is serialized for each user, so Jarvis can keep the conversations separate. Here's our best picks:

Jarvis gone sentient: chat1

Jarvis gone sentient, confirmed: chat2

Memes and jokes

This is easily the most-used feature. Warning: this may cause dramatic swings in productivity, use with caution! Currently includes: meme generator, coding love, cat, pug, chuck norris, Shia Labeouf, Donald Trump, flirt, etc. meme

Roadmap

Generic scraper
wit.ai parsing, supplement command using single regex
Github project monitoring
more ML modules
IBM Bluemix
home-automation via Arduino
multi-instances, distributed deployment for backing up
personal scheduling
Integration with Google Now (waiting for Google to open source it)

Changelog

Sep 2

Now can save and call forever commands from npm

Aug 25

removed view window to allow for multiple instances to be deployed on the same machine.

Aug 8

√external universal set env
√request slack voice api
√fix ME regex
√change upload command
√genlize n export n unify cmdregex
√new meme: Shia Labeouf just do it
√donald trump
√username aliasing
√todolist
√rate-limiting on pugs/cats
√remove heroku app.json
√safeguard tokens for open-sourcing
√fix regex to catch first
√add user? cond to all
√serialize chatbot
√twitter
√indico
√isAdmin method
√fixed memsync, now reply to user

Usage no npm install needed!