chatto

Simple chatbot framework written in Go, with configurations in YAML. The aim of this project is to create very simple text-based chatbots using a few configuration files.

The inspiration for this project originally came from Flottbot and my experience using Rasa.

Contents

• Installation
• Documentation
• Your first bot
  • The clf.yml file
  • The fsm.yml file
  • Run your bot
  • Interact with your bot
• Usage
  • CLI
  • Docker Compose
  • Kubernetes
  • Import
• Examples

Installation

go get -u github.com/jaimeteb/chatto

Via Docker:

docker pull jaimeteb/chatto:latest

Documentation

See the Documentation for examples, configuration guides and reference.

Your first bot

Chatto combines the consistency of a finite-state-machine with the flexibility of machine learning. It has three main components: the classifier, the finite-state-machine and the extensions.

A very basic directory structure for Chatto would be the following:

.
└──data
   ├── clf.yml
   └── fsm.yml

Start by creating the data directory as well as the YAML files.

mkdir data
touch data/clf.yml data/fsm.yml

The clf.yml file

The clf.yml file defines how the user messages will be classified into commands (intents). Start with this very simple configuration:

classification:
  - command: "turn_on"
    texts:
      - "turn on"
      - "on"

  - command: "turn_off"
    texts:
      - "turn off"
      - "off"

The fsm.yml file

The fsm.yml file defines the transitions between states, the commands that make these transitions, and the answers to be sent in them. Start with this file contents:

transitions:
  - from:
      - "initial"
    into: "on"
    command: "turn_on"
    answers:
      - text: "Turning on."

  - from:
      - "on"
    into: "initial"
    command: "turn_off"
    answers:
      - text: "Turning off."
      - text: "❌"

defaults:
  unknown: "Can't do that."

Run your first bot

To start your bot, run:

chatto --path data/

If you're using Docker, run:

docker run \
    -it \
    -e CHATTO_DATA=./data \
    -v $PWD/data:/data \
    jaimeteb/chatto:latest \
    chatto --path data

Interact with your first bot

To interact with your bot, run:

chatto cli

That's it! Now you can say turn on or on to go into the on state, and turn off or off to go back into initial. However, you cannot go from on into on, or from initial into initial either.

Here is a diagram for this simple Finite State Machine:

Usage

You can integrate your bot with Telegram, Twilio, Slack and anything you like

Run chatto in the directory where your YAML files are located, or specify a path to them with the --path flag:

chatto --path ./your/data

To run on Docker, use:

docker run \
  -p 4770:4770 \
  -e CHATTO_DATA=./your/data \
  -v $PWD/your/data:/data \
  jaimeteb/chatto

CLI

You can use the Chatto CLI tool by downloading the chatto cli tool. The CLI makes it easy to test your bot interactions.

chatto cli --url 'http://mybot.com' -port 4770

Docker Compose

You can use Chatto on Docker Compose as well. A docker-compose.yml would look like this:

version: "3"

services:
  chatto:
    image: jaimeteb/chatto:${CHATTO_VERSION}
    env_file: .env
    ports:
      - "4770:4770"
    volumes:
      - ${CHATTO_DATA}:/data
    depends_on:
      - ext
      - redis

  ext:
    image: odise/busybox-curl # Busy box with certificates
    command: ext/ext
    expose:
      - 8770
    volumes:
      - ${CHATTO_DATA}/ext:/ext

  redis:
    image: bitnami/redis:6.0
    environment:
      - REDIS_PASSWORD=${STORE_PASSWORD}
    expose:
      - 6379

This requires a .env file to contain the necessary environment variables:

# Chatto configuration
CHATTO_VERSION=latest
CHATTO_DATA=./your/data

# Extension configuration
CHATTO_BOT_EXTENSIONS_EXTENSION_NAME_URL=http://ext:8770

# Redis
CHATTO_BOT_STORE_HOST=redis
CHATTO_BOT_STORE_PASSWORD=pass

# Logs
CHATTO_BOT_DEBUG=true

The directory structure with all the files would look like this:

.
├── data
│   ├── ext
│   │   ├── ext
│   │   └── ext.go
│   ├── bot.yml
│   ├── chn.yml
│   ├── clf.yml
|   └── fsm.yml
├── docker-compose.yml
└── .env

Finally, run:

docker-compose up -d redis ext
docker-compose up -d chatto

The extensions server has to be executed according to its language.

For this docker-compose.yml file, you'd have to build the Go extension first:

go build -o data/ext/ext data/ext/ext.go

The extensions server has to be running before Chatto initializes.

Kubernetes

Under the deploy/kubernetes directory you can find an example deployment:

Run the following command to deploy on Kubernetes:

kubectl apply -f ./deploy/kubernetes/

Import

An importable bot server and client package is provided to allow embedding into your own application.

To embed the server:

package main

import (
	"flag"

	"github.com/jaimeteb/chatto/bot"
)

func main() {
	port := flag.Int("port", 4770, "Specify port to use.")
	path := flag.String("path", ".", "Path to YAML files.")
	flag.Parse()

	server := bot.NewServer(*path, *port)

	server.Run()
}

To embed the client:

package myservice

import (
	"log"

	"github.com/jaimeteb/chatto/bot"
)

type MyService struct {
	chatto bot.Client
}

func NewMyService(url string, port int) *MyService {
	return &MyService{chatto: bot.NewClient(url, port)}
}

func (s *MyService) Submit(question *query.Question) error {
	answers, err := s.chatto.Submit(question)
	if err != nil {
		return err
	}

	// Print answers to stdout
	for _, answer := range answers {
		fmt.Println(answer.Text)
	}

	return nil
}

Examples

I have provided some config files under examples. Clone the repository and run chatto with the -path of your desired example to test them out (for the ones that use extensions, run their respective extensions first).

More about these examples in the Documentation

1. Mood Bot - A chatto version of Rasa's Mood Bot Greet the bot to start the conversation.
2. Pokemon Search - Search for Pokémon by name or number.
3. Trivia Quiz - Type start to take a quick trivia quiz.