lex-oscarbot

Oscar is a sassy, connected chatbot who enables you to easily interact with GitHub projects, all out of Slack!

Check the Quick Start Guide to get access to Oscar on our Slack Channel - oscar-bot.slack.com. Also check out The AWS Chatbot Challenge.

• Quick Start
• Developer Guide
  • Environment Setup
  • Useful Commands
  • Circle CI
  • Snappy Responses
  • Useful Reading

Quick Start

The fastest way to try out Oscar is to request an invite to the OscarBot Slack Channel. Then checkout the Quick Start Guide.

Oscar can provide all sorts of information about repositories, as well as doing things like opening issues. Some example interations are:

• "How many issues does {Repository} have?"
• "I would like to open an issue"
• "List the top issues for my project"

There's a more detailed list in the [Quick Start Guide](Quick Start Guide).

Developer Guide

The project structure is:

├── aws           # some aws resources used in setup
├── docs          # internal docs/images
├── lex           # slots and intent json files
├── oscar-cli     # the oscar cli
├── oscarbot      # lamba function and tests
└── scripts       # scripts used by the makefile

This diagram shows the key steps for setup and development:

Environment Setup

Install:

• The AWS CLI
• jq

Ensure you are logged into the AWS CLI as a user with permissions to create Lambda Functions, Buckets, Roles, Policies and Lex Models.

Set the following environment variables:

Variable	Usage
OSCAR_BUCKET	A name to use for the S3 bucket for Oscar. This must be unique across AWS, so try something like oscarbot-<your name>
OSCAR_GITHUB_USERNAME	The GitHub user to login as when performing queries.
OSCAR_GITHUB_PASSWORD	The GitHub password to login with when performing queries.
DEBUG=oscar	Optional. Enables debug output (we use the debug module.

You can now call:

make setup

Which will build the lambda function, bucket and policies.

Deploying Changes

If you change the lambda function, slots, intents or bot, just call:

make deploy

This will rebuild the lambda function and redeploy it. It will also rebuild and publish all slots, intents and the bot. ``

Useful Commands

Here are some commands you can run to help work with the project:

Command	Usage
make build	Builds the lamba function and zips it up locally.
make test	Runs the unit tests.
make lint	Lints the code.
make setup	Sets up your AWS resources. First time setup only.
make deploy	Deploys the code, slots and intents.
make utterances	Helper to print out all supported utterances. Useful when building docs.
npm run test:debug	Runs tests with the Chrome Inspector.
npm run coverage	Runs tests, generating a coverage report.

The CLI

If you have the AWS CLI setup with access to the bot, you can actually chat using the CLI. First, build and link the CLI with:

make cli

Then just run the oscar command to chat!

$ oscar
Hello, I am Oscar 🤖

You chat to me about your GitHub project!

oscar > Hi! What can I help you with?
me    > What projects am I working on?

Circle CI

circle.yml will build changes on master and deploy to AWS (make sure you have set the Circle AWS key in the console).

Testing

The bulk of the tests work by creating a chat event and passing it to the lambda function. This means it will test the intent but not the natural language understanding.

A good example test to get learn from is intentDescribeLastCommit.js.

Snappy Responses

If you want to provide some simple flavour text or a one-line response to a statement, you can use the snappyResponses.js file.

Please note that even a one-line response will still need an intent. Put these intents in the intents/conversational folder to distinguish them from functional intents.

It is possible that intents are limited, and it is the case that a large number of intents can actually make it harder to determine intent, so be careful to to add too many.

Useful Reading

• https://docs.aws.amazon.com/lex/latest/dg/slack-bot-association.html