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
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 thisdocker-compose.ymlfile, 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:
| Kind | Name | Description |
|---|---|---|
| Secret | chatto-config-secrets |
Contains the tokens that Chatto will use for authorization |
| ConfigMap | chatto-config-envs |
Contains the environment variables for the bot.yml file |
| ConfigMap | chatto-config-files |
Contains the clf.yml and fsm.yml file |
| Deployment | chatto |
Chatto deployment based on the jaimeteb/chatto Docker image |
| Service | chatto-service |
Service for the chatto deployment |
| Ingress | chatto-ingress |
Ingress for the chatto-service service |
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
- Mood Bot - A chatto version of Rasa's Mood Bot Greet the bot to start the conversation.
- Pokemon Search - Search for Pokémon by name or number.
- Miscellaneous Bot - Weather forecast, random jokes and quotes, and more!
- Trivia Quiz - Type start to take a quick trivia quiz.
