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.

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

go get -u github.com/jaimeteb/chatto

Via Docker:

docker pull jaimeteb/chatto:latest

See the Documentation for examples, configuration guides and reference.

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 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 defines the transitions between states, the commands that make these transitions, and the messages to be sent in them. Start with this file contents:

states:
  - "off"
  - "on"

commands:
  - "turn_on"
  - "turn_off"

functions:
 - transition:
      from: "off"
      into: "on"
    command: "turn_on"
    message: "Turning on."

  - transition:
      from: "on"
      into: "off"
    command: "turn_off"
    message:
      - "Turning off."
      - "❌"

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

To run your bot in a CLI, simply run:

chatto -cli -path data/

Or if you're using Docker, run:

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

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 off. However, you cannot go from on into on, or from off into off either.

Here is a diagram for this simple Finite State Machine:

You can integrate yout bot with Telegram and Twilio 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:/chatto/data \
  jaimeteb/chatto

You can set a log level with the environment variable LOG_LEVEL.

You can use Chatto in a CLI mode by adding the -cli flag.

chatto -cli -path ./your/data

On Docker:

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

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}:/chatto/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
EXTENSIONS_URL=http://ext:8770

# Redis
STORE_HOST=redis
STORE_PASSWORD=pass

# Logs
LOG_LEVEL=DEBUG

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.

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. Engineering Flowchart - Tell the bot you want to repair something.
3. Pokemon - Search for Pokémon by name or number.
4. Trivia Quiz - Type start to take a quick trivia quiz.