jaimeteb/chatto repository overview

⁠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

1. Installation⁠
2. How does it work?⁠
3. Classifier⁠
4. Finite State Machine⁠
5. Extensions⁠
6. Slots⁠
7. Redis⁠
8. HTTP Endpoint⁠
9. CLI⁠
10. Telegram⁠
11. Examples⁠

⁠1. Installation

Run go get -u github.com/jaimeteb/chatto.

⁠2. How does it work?

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

⁠3. Classifier

Currently, chatto uses a Naïve-Bayes classifier⁠ to take the user input and decide a command to execute on the finite-state-machine. The training text for the classifier is provided in the clf.yml file:

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

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

Under classification you can list the commands and their respective training data under texts.

⁠4. Finite State Machine

The FSM (finite-state-machine) is based on the one shown in this article⁠. The states, commands, default messages and transitions are described in the fsm.yml file:

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."
  unsure: "???"

Under functions you can list the transitions available for the FSM. The object transition describes the states of the transition (from one state into another) if command is executed; message is the message (or messages) to send to the user.

The special state any can help you go from any state into another, if the command is executed. You don't have to declare the any state in the states list.

⁠5. Extensions

The extensions in chatto are pieces of code that can be executed instead of messages. The extensions names must begin by "ext_" and they must be placed in the ext/ext.go file. The format for a chatto extension is as follows:

package main

import (
	"log"

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

func greetFunc(req *fsm.Request) (res *fsm.Response) {
	return &fsm.Response{
		FSM: req.FSM,
		Res: "Hello Universe",
	}
}

var myExtMap = fsm.ExtensionMap{
	"ext_any": greetFunc,
}

func main() {
	if err := fsm.ServeExtension(myExtMap); err != nil {
		log.Fatalln(err)
	}
}

You must use the fsm.ServeExtension(fsm.ExtensionMap) in the main function in order to run the extension server and pass your own fsm.ExtensionMap, which maps the extension names to their respective functions.

The extension server runs on port 42586 by default but you can specify it with the EXTENSION_PORT environment variable. Furthermore, you can run the extension server elsewhere, in which case you have to ser the EXTENSION_HOST environment variable.

The extension functions must have the func(*fsm.Request) *fsm.Response interface{} signature, where:

• Request contains:
  • The current FSM
  • The requested extension
  • The input text from the user
  • The Domain
• Response must contain:
  • The resulting FSM
  • The message to be sent to the user

In this example, ext_any simply returns "Hello Universe" and does not modify the current FSM.

⁠6. Slots

You can save information from the user's input by using slots:

  - transition:
      from: ask_name
      into: ask_age
    command: say_name
    slot:
      name: name
      mode: whole_text
    message: "How old are you?"

In this example, in the transition from ask_name to ask_age, when say_name is executed, a slot called name will be saved, in other words, the user's message is stored in memory.

At the time, only whole_text mode is supported, which saves the entire input in the slot.

⁠7. Redis

You can store the FSMs in memory or in Redis. In order to use the Redis Store, set the REDIS_HOST and REDIS_PASS environment variables.

⁠8. HTTP Endpoint

To enable the HTTP endpoint, simply run chatto on the same directory as your clf.yml and fsm.yml files, or specify a path to them with the --path flag. A service will run on port 4770 of your localhost.

Send a POST request to /endpoint with the following body structure:

{
    "sender": "foo",
    "text": "bar"
}

The bot will respond as such:

{
    "sender": "botto",
    "text": "some answer"
}

⁠9. CLI

Alternatively, run chatto on a command line interface using the --cli flag.

⁠10. Telegram

You can connect your chatto bot to Telegram⁠ by setting the TELEGRAM_BOT_KEY environment variable. You must set the bot's webhook to the /endpoints/telegram endpoint in order to receive messages.

⁠11. Examples

I have provided some config files unnder examples. Run chatto with the --path of your desired example to test them out.

1. Mood Bot⁠ - Greet the bot to start the conversation.
2. Engineering Flowchart⁠ - Tell the bot you want to repair something.
3. Echo⁠ - The bot will ask for your name and age (beta).
4. Trivia Quiz⁠ - Type start to take a quick trivia quiz.