Repository files navigation

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 fromFlottbot and my experience usingRasa.

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

go get -u github.com/jaimeteb/chatto

Via Docker:

docker pull jaimeteb/chatto:latest

See theDocumentation forexamples,configuration guides andreference.

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 thedata directory as well as the YAML files.

mkdir datatouch data/clf.yml data/fsm.yml

Theclf.yml file defines how the user messages will be classified intocommands (intents). Start with this very simple configuration:

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

Thefsm.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."

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

To interact with your bot, run:

chatto cli

That's it! Now you can sayturn on oron to go into theon state, andturn off oroff to go back intoinitial. However, you cannot go fromon intoon, or frominitial intoinitial either.

Here is a diagram for this simple Finite State Machine:

You can integrate your bot withTelegram, Twilio, Slack andanything you like

Runchatto 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

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

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

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

version:"3"services:chatto:image:jaimeteb/chatto:${CHATTO_VERSION}env_file:.envports:      -"4770:4770"volumes:      -${CHATTO_DATA}:/datadepends_on:      -ext      -redisext:image:odise/busybox-curl# Busy box with certificatescommand:ext/extexpose:      -8770volumes:      -${CHATTO_DATA}/ext:/extredis:image:bitnami/redis:6.0environment:      -REDIS_PASSWORD=${STORE_PASSWORD}expose:      -6379

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

# Chatto configurationCHATTO_VERSION=latestCHATTO_DATA=./your/data# Extension configurationCHATTO_BOT_EXTENSIONS_EXTENSION_NAME_URL=http://ext:8770# RedisCHATTO_BOT_STORE_HOST=redisCHATTO_BOT_STORE_PASSWORD=pass# LogsCHATTO_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 extdocker-compose up -d chatto

Theextensions server has to be executed according to its language.

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

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

Theextensions server has to be running before Chatto initializes.

Under thedeploy/kubernetes directory you can find an example deployment:

Run the following command to deploy on Kubernetes:

kubectl apply -f ./deploy/kubernetes/

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

To embed the server:

package mainimport ("flag""github.com/jaimeteb/chatto/bot")funcmain() {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 myserviceimport ("log""github.com/jaimeteb/chatto/bot")typeMyServicestruct {chatto bot.Client}funcNewMyService(urlstring,portint)*MyService {return&MyService{chatto:bot.NewClient(url,port)}}func (s*MyService)Submit(question*query.Question)error {answers,err:=s.chatto.Submit(question)iferr!=nil {returnerr}// Print answers to stdoutfor_,answer:=rangeanswers {fmt.Println(answer.Text)}returnnil}

I have provided some config files underexamples. Clone the repository and runchatto 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 theDocumentation

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