snowman

README

⛄️ Snowman

WIP

Snowman provides facilities for building chat-bots in Go.

A bot consists of UI to interact with users, and Handler to understand the intent, figure out the action and finally generate response. Handler follows the familiar http.Handler approach and allows for all the standard patterns used ( e.g., middlewares).

Usage

As Library

Refer cmd/snowman/main.go for usage example.

As Binary

1. Install using go get -u -v github.com/spy16/snowman/cmd/snowman
2. Run using snowman --name=snowy --slack=<token>

TODO

• Support for channels / independent conversations.
• Slack RTM
• Socket UI implementations.
• NLP with prose
• An intent classifier with FFNet.

Documentation

Overview

Package snowman provides basic building blocks required to build a chat bot.

A bot consists of a `UI` to interact with users and a `Responder` to generate actions/response to the user based on the intent detected.

Index

• type Bot
  • func (bot *Bot) Run(ctx context.Context) error
• type ConsoleUI
  • func (cui *ConsoleUI) Listen(ctx context.Context, handle func(msg Msg)) error
  • func (cui *ConsoleUI) Say(_ context.Context, msg Msg) error
• type Dialogue
• type Fn
  • func (fn Fn) Handle(msg *Msg, di Dialogue) error
• type Handler
• type Intent
  • func (intent Intent) Clone(mergeCtx ...map[string]interface{}) Intent
  • func (intent Intent) String() string
• type Logger
• type Msg
  • func (m Msg) Context() context.Context
  • func (m Msg) String() string
• type NoOpLogger
  • func (n NoOpLogger) Debugf(string, ...interface{})
  • func (n NoOpLogger) Errorf(string, ...interface{})
  • func (n NoOpLogger) Infof(string, ...interface{})
  • func (n NoOpLogger) Warnf(string, ...interface{})
• type SlackUI
  • func (sui *SlackUI) Listen(ctx context.Context, handle func(msg Msg)) error
  • func (sui *SlackUI) Say(ctx context.Context, msg Msg) error
• type StdLogger
  • func (s StdLogger) Debugf(msg string, args ...interface{})
  • func (s StdLogger) Errorf(msg string, args ...interface{})
  • func (s StdLogger) Infof(msg string, args ...interface{})
  • func (s StdLogger) Warnf(msg string, args ...interface{})
• type UI
• type User
  • func (u User) String() string

Types

type Bot

type Bot struct {
	UI      UI
	Self    User
	Logger  Logger
	Handler Handler
	// contains filtered or unexported fields
}

Bot represents an instance of the bot. A bot runs continuously blocking the host goroutine and generates messages or actions in response to scheduled intents or user messages.

func (*Bot) Run

func (bot *Bot) Run(ctx context.Context) error

Run starts all the workers. Run blocks the current goroutine until the ctx is cancelled or inputs is closed.

type ConsoleUI

type ConsoleUI struct {
	Prompt string
	// contains filtered or unexported fields
}

ConsoleUI implements a console based UI. Stdin is used for reading input from the user and Stdout is used for output.

func (*ConsoleUI) Listen

func (cui *ConsoleUI) Listen(ctx context.Context, handle func(msg Msg)) error

func (*ConsoleUI) Say

func (cui *ConsoleUI) Say(_ context.Context, msg Msg) error

type Dialogue

type Dialogue interface {
	ID() string
	Self() User
	Say(ctx context.Context, body string) error
}

Dialogue holds the conversational context of bot with a specific user.

type Fn

type Fn func(msg *Msg, di Dialogue) error

Fn is an adaptor to implement Handler using simple Go func values.

func (Fn) Handle

func (fn Fn) Handle(msg *Msg, di Dialogue) error

Handle simply dispatches the args to the wrapped function.

type Handler

type Handler interface {
	Handle(msg *Msg, di Dialogue) error
}

Handler represents the message Handler that can process the message to generate response or to append additional context to the message.

type Intent

type Intent struct {
	Tag        string                 `json:"tag" yaml:"tag"`
	Context    map[string]interface{} `json:"context" yaml:"context"`
	Response   string                 `json:"response" yaml:"response"`
	Confidence float64                `json:"confidence" yaml:"confidence"`
}

Intent represents the intent of a message along with context extracted from the message.

func (Intent) Clone

func (intent Intent) Clone(mergeCtx ...map[string]interface{}) Intent

Clone returns a clone of the intent with the given context maps merged into the base context from the intent. Given maps act as overrides on the base.

func (Intent) String

func (intent Intent) String() string

type Logger

type Logger interface {
	Debugf(msg string, args ...interface{})
	Infof(msg string, args ...interface{})
	Warnf(msg string, args ...interface{})
	Errorf(msg string, args ...interface{})
}

Logger is responsible for providing logging facilities to bot instance.

type Msg

type Msg struct {
	At      time.Time `json:"at"`
	To      User      `json:"to"`
	From    User      `json:"from"`
	Body    string    `json:"body"`
	Intents []Intent  `json:"intents"`
	// contains filtered or unexported fields
}

Msg represents a message from the user/bot. Msg can contain additional context in terms of intents that may be used by handler to generate response.

func (Msg) Context

func (m Msg) Context() context.Context

Context returns the context associated with the message.

func (Msg) String

func (m Msg) String() string

type NoOpLogger

type NoOpLogger struct{}

NoOpLogger implements a Logger that simply ignores all the log entries.

func (NoOpLogger) Debugf

func (n NoOpLogger) Debugf(string, ...interface{})

func (NoOpLogger) Errorf

func (n NoOpLogger) Errorf(string, ...interface{})

func (NoOpLogger) Infof

func (n NoOpLogger) Infof(string, ...interface{})

func (NoOpLogger) Warnf

func (n NoOpLogger) Warnf(string, ...interface{})

type SlackUI

type SlackUI struct {
	Logger

	Token         string
	Options       []slack.Option
	EnableChannel bool
	ThreadDirect  bool
	// contains filtered or unexported fields
}

SlackUI implements snowman SlackUI using Slack RTM based API.

func (*SlackUI) Listen

func (sui *SlackUI) Listen(ctx context.Context, handle func(msg Msg)) error

func (*SlackUI) Say

func (sui *SlackUI) Say(ctx context.Context, msg Msg) error

Say sends a message to the user/channel on Slack identified using the UserID in the msg.To field.

type StdLogger

type StdLogger struct{}

StdLogger implements the Logger using standard library log package.

func (StdLogger) Debugf

func (s StdLogger) Debugf(msg string, args ...interface{})

func (StdLogger) Errorf

func (s StdLogger) Errorf(msg string, args ...interface{})

func (StdLogger) Infof

func (s StdLogger) Infof(msg string, args ...interface{})

func (StdLogger) Warnf

func (s StdLogger) Warnf(msg string, args ...interface{})

type UI

type UI interface {
	// Say should display the message to the user as if the bot said it.
	// Target user that should receive the message should be identified
	// using the 'msg.To' value.
	Say(ctx context.Context, msg Msg) error

	// Listen should listen for messages from user and deliver them to the
	// Handler. Listen should block until UI reaches a terminal state or
	// until context is cancelled.
	Listen(ctx context.Context, receive func(msg Msg)) error
}

UI represents the interface used for interactions between the bot and the user.

type User

type User struct {
	ID      string                 `json:"id"`
	Name    string                 `json:"name"`
	Attribs map[string]interface{} `json:"attribs"`
}

User represents a user that is interacting with snowman.

func (User) String

func (u User) String() string