wit-ruby

wit-ruby is the Ruby SDK for Wit.ai.

Install

From RubyGems:

gem install wit

From source:

git clone https://github.com/wit-ai/wit-ruby
gem build wit.gemspec
gem install wit-*.gem

Quickstart

Run in your terminal:

ruby examples/quickstart.rb <your_token>

See the examples folder for more examples.

API

Overview

wit-ruby provides a Wit class with the following methods:

• message - the Wit message API
• converse - the low-level Wit converse API
• run_actions - a higher-level method to the Wit converse API
• interactive - starts an interactive conversation with your bot

Wit class

The Wit constructor takes a Hash with the following symbol keys:

• :access_token - the access token of your Wit instance
• :actions - the Hash with your actions

The actions Hash has action names as keys, and action implementations as values. Action names are symbols, and action implementations are lambda functions (not Proc).

A minimal example looks like this:

require 'wit'

actions = {
  send: -> (request, response) {
    puts("sending... #{response['text']}")
  },
  my_action: -> (request) {
    return request['context']
  },
}

client = Wit.new(access_token: access_token, actions: actions)

.message()

The Wit message API.

Takes the following parameters:

• msg - the text you want Wit.ai to extract the information from

Example:

rsp = client.message('what is the weather in London?')
puts("Yay, got Wit.ai response: #{rsp}")

.run_actions()

A higher-level method to the Wit converse API. run_actions resets the last turn on new messages and errors.

Takes the following parameters:

• session_id - a unique identifier describing the user session
• message - the text received from the user
• context - the Hash representing the session state
• max_steps - (optional) the maximum number of actions to execute (defaults to 5)

Example:

session = 'my-user-session-42'
context0 = {}
context1 = client.run_actions(session, 'what is the weather in London?', context0)
p "The session state is now: #{context1}"
context2 = client.run_actions(session, 'and in Brussels?', context1)
p "The session state is now: #{context2}"

.converse()

The low-level Wit converse API.

Takes the following parameters:

• session_id - a unique identifier describing the user session
• msg - the text received from the user
• context - the Hash representing the session state
• reset - (optional) whether to reset the last turn

Example:

rsp = client.converse('my-user-session-42', 'what is the weather in London?', {})
puts("Yay, got Wit.ai response: #{rsp}")

.interactive()

Starts an interactive conversation with your bot.

Example:

client.interactive

CRUD operations for entities

payload in the parameters is a hash containing API arguments

.get_entities()

Returns a list of available entities for the app.
See GET /entities

.post_entities(payload)

Creates a new entity with the given attributes.
See POST /entities

.get_entity(entity_id)

Returns all the expressions validated for an entity.
See GET /entities/:entity-id

.put_entities(entity_id, payload)

Updates an entity with the given attributes.
See PUT /entities/:entity-id

.delete_entities(entity_id)

Permanently remove the entity.
See DELETE /entities/:entity-id

.post_values(entity_id, payload)

Add a possible value into the list of values for the entity.
See POST /entities/:entity-id/values

.delete_values(entity_id, value)

Delete a canonical value from the entity.
See DELETE /entities/:entity-id/values/:value

post_expressions(entity_id, value, payload)

Create a new expression of the canonical value of the entity.
See POST /entities/:entity-id/values/:value/expressions

delete_expressions(entity_id, value, expression)

Delete an expression of the canonical value of the entity.
See DELETE /entities/:entity-id/values/:value/expressions/:expression

See the docs for more information.

Logging

Default logging is to STDOUT with INFO level.

You can setup your logging level as follows:

Wit.logger.level = Logger::WARN

See the Logger class docs for more information.

Thanks

Thanks to Justin Workman for releasing a first version in October 2013. We really appreciate!