wit 3.4.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b70a97f9ec0b2c9b01f49983870ae7981cd0ca9a
-  data.tar.gz: a575cf16cc6fd9ae10ce374617364c6edc6ea80a
+  metadata.gz: 8238be41a9a6f12e9b5ca05aa47e2df2bb174de7
+  data.tar.gz: 2cb886d831857aaffa697a17443714db24a38214
 SHA512:
-  metadata.gz: 2f8a5583c0e72f940c9b7eff2c2cbcf31103b309ba040049b6f68bef599df4b14264fe99a5c18314c5202db928408157ad7d1bb38cef47bedce0bd46830bac09
-  data.tar.gz: 58496e8a8bcb1f0c3183e00a611f713740932b2afbb2418534e244596dc303a1265a5681dbcb711907265283681e460c42094ba474573a27351d95369ba422e3
+  metadata.gz: 0777a1f0a9ca34416275ac36080a2caf8563edba3960d8e269a193106e5c03b1c5b18e21b9f6de01a806b884f65ac11d70a2fd4858343e1659f61baadc79f150
+  data.tar.gz: 7612bc8d01ba0499ea9a374251fbe2d9a8b1f884d9f1dde14d4fd64b90024585880ac49e6ebfee02afc0fedd10952f62b69a5a654d04cdc6ade03f1b4a2bc831

data/CHANGES.md

@@ -1,6 +1,20 @@
+## v4.0.0
+
+After a lot of internal dogfooding and bot building, we decided to change the API in a backwards-incompatible way. The changes are described below and aim to simplify user code and accommodate upcoming features.
+
+See `./examples` to see how to use the new API.
+
+### Breaking changes
+
+- `say` renamed to `send` to reflect that it deals with more than just text
+- Removed built-in actions `merge` and `error`
+- Actions signature simplified with `request` and `response` arguments
+- INFO level replaces LOG level
+
 ## v3.4
 
 - allows for overriding API version, by setting `WIT_API_VERSION`
+- `interactive()` mode
 - warns instead of throwing when validating actions
 
 ### breaking

data/README.md

@@ -38,50 +38,30 @@ See the `examples` folder for more examples.
 
 ### Wit class
 
-The Wit constructor takes the following parameters:
-* `access_token` - the access token of your Wit instance
-* `actions` - the `Hash` with your actions
+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`).
-You need to provide at least an implementation for the special actions `:say`, `:merge` and `:error`.
 
-A minimal `actions` `Hash` looks like this:
+A minimal example looks like this:
 ```ruby
+require 'wit'
+
 actions = {
-  :say => -> (session_id, context, msg) {
-    p msg
+  send: -> (request, response) {
+    puts("sending... #{response['text']}")
   },
-  :merge => -> (session_id, context, entities, msg) {
-    return context
-  },
-  :error => -> (session_id, context, error) {
-    p error.message
+  my_action: -> (request) {
+    return request['context']
   },
 }
-```
-
-A custom action takes the following parameters:
-* `session_id` - a unique identifier describing the user session
-* `context` - the `Hash` representing the session state
-
-Example:
-```ruby
-require 'wit'
-client = Wit.new access_token, actions
-```
-
-### Logging
-
-Default logging is to `STDOUT` with `INFO` level.
 
-You can setup your logging level as follows:
-```ruby
-Wit.logger.level = Logger::WARN
+client = Wit.new(access_token: access_token, actions: actions)
 ```
-See the [Logger class](http://ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html) docs for more information.
 
-### message
+### .message()
 
 The Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link).
 
@@ -90,11 +70,11 @@ Takes the following parameters:
 
 Example:
 ```ruby
-resp = client.message 'what is the weather in London?'
-p "Yay, got Wit.ai response: #{resp}"
+rsp = client.message('what is the weather in London?')
+puts("Yay, got Wit.ai response: #{rsp}")
 ```
 
-### run_actions
+### .run_actions()
 
 A higher-level method to the Wit converse API.
 
@@ -108,13 +88,13 @@ Example:
 ```ruby
 session = 'my-user-session-42'
 context0 = {}
-context1 = client.run_actions session, 'what is the weather in London?', 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
+context2 = client.run_actions(session, 'and in Brussels?', context1)
 p "The session state is now: #{context2}"
 ```
 
-### converse
+### .converse()
 
 The low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link).
 
@@ -125,12 +105,11 @@ Takes the following parameters:
 
 Example:
 ```ruby
-resp = client.converse 'my-user-session-42', 'what is the weather in London?', {}
-p "Yay, got Wit.ai response: #{resp}"
+rsp = client.converse('my-user-session-42', 'what is the weather in London?', {})
+puts("Yay, got Wit.ai response: #{rsp}")
 ```
 
-
-### interactive
+### .interactive()
 
 Starts an interactive conversation with your bot.
 
@@ -141,6 +120,15 @@ client.interactive
 
 See the [docs](https://wit.ai/docs) for more information.
 
+### Logging
+
+Default logging is to `STDOUT` with `INFO` level.
+
+You can setup your logging level as follows:
+```ruby
+Wit.logger.level = Logger::WARN
+```
+See the [Logger class](http://ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html) docs for more information.
 
 ## Thanks
 

data/examples/basic.rb

@@ -0,0 +1,18 @@
+require 'wit'
+
+if ARGV.length == 0
+  puts("usage: #{$0} <wit-access-token>")
+  exit 1
+end
+
+access_token = ARGV[0]
+ARGV.shift
+
+actions = {
+  send: -> (request, response) {
+    puts("sending... #{response['text']}")
+  },
+}
+
+client = Wit.new(access_token: access_token, actions: actions)
+client.interactive

data/examples/joke.rb

@@ -1,10 +1,16 @@
 require 'wit'
 
+if ARGV.length == 0
+  puts("usage: #{$0} <wit-access-token>")
+  exit 1
+end
+
+access_token = ARGV[0]
+ARGV.shift
+
 # Joke example
 # See https://wit.ai/patapizza/example-joke
 
-access_token = 'YOUR_ACCESS_TOKEN'
-
 def first_entity_value(entities, entity)
   return nil unless entities.has_key? entity
   val = entities[entity][0]['value']
@@ -27,27 +33,28 @@ all_jokes = {
 }
 
 actions = {
-  :say => -> (session_id, context, msg) {
-    p msg
+  send: -> (request, response) {
+    puts("sending... #{response['text']}")
   },
-  :merge => -> (session_id, context, entities, msg) {
+  merge: -> (request) {
+    context = request['context']
+    entities = request['entities']
+
     context.delete 'joke'
     context.delete 'ack'
-    category = first_entity_value entities, 'category'
+    category = first_entity_value(entities, 'category')
     context['category'] = category unless category.nil?
-    sentiment = first_entity_value entities, 'sentiment'
+    sentiment = first_entity_value(entities, 'sentiment')
     context['ack'] = sentiment == 'positive' ? 'Glad you liked it.' : 'Hmm.' unless sentiment.nil?
     return context
   },
-  :error => -> (session_id, context, error) {
-    p error.message
-  },
-  :'select-joke' => -> (session_id, context) {
-    context['joke'] = all_jokes[context['cat'] || 'default'].sample
+  :'select-joke' => -> (request) {
+    context = request['context']
+
+    context['joke'] = all_jokes[context['category'] || 'default'].sample
     return context
   },
 }
-client = Wit.new access_token, actions
 
-session_id = 'my-user-id-42'
-client.run_actions session_id, 'tell me a joke about tech', {}
+client = Wit.new(access_token: access_token, actions: actions)
+client.interactive

data/examples/quickstart.rb

@@ -1,14 +1,16 @@
 require 'wit'
 
-# Quickstart example
-# See https://wit.ai/l5t/Quickstart
-
-access_token = ARGV.shift
-unless access_token
-  puts 'usage: ruby examples/quickstart.rb <access-token>'
-  exit
+if ARGV.length == 0
+  puts("usage: #{$0} <wit-access-token>")
+  exit 1
 end
 
+access_token = ARGV[0]
+ARGV.shift
+
+# Quickstart example
+# See https://wit.ai/ar7hur/Quickstart
+
 def first_entity_value(entities, entity)
   return nil unless entities.has_key? entity
   val = entities[entity][0]['value']
@@ -17,21 +19,24 @@ def first_entity_value(entities, entity)
 end
 
 actions = {
-  :say => -> (session_id, context, msg) {
-    p msg
+  send: -> (request, response) {
+    puts("sending... #{response['text']}")
   },
-  :merge => -> (session_id, context, entities, msg) {
-    loc = first_entity_value entities, 'location'
-    context['loc'] = loc unless loc.nil?
-    return context
-  },
-  :error => -> (session_id, context, error) {
-    p error.message
-  },
-  :'fetch-weather' => -> (session_id, context) {
-    context['forecast'] = 'sunny'
+  getForecast: -> (request) {
+    context = request['context']
+    entities = request['entities']
+
+    loc = first_entity_value(entities, 'location')
+    if loc
+        context['forecast'] = 'sunny'
+    else
+        context['missingLocation'] = true
+        context.delete('forecast')
+    end
+
     return context
   },
 }
-client = Wit.new access_token, actions
+
+client = Wit.new(access_token: access_token, actions: actions)
 client.interactive

data/lib/wit.rb

@@ -6,149 +6,195 @@ require 'securerandom'
 WIT_API_HOST = ENV['WIT_URL'] || 'https://api.wit.ai'
 WIT_API_VERSION = ENV['WIT_API_VERSION']  || '20160516'
 DEFAULT_MAX_STEPS = 5
+LEARN_MORE = 'Learn more at https://wit.ai/docs/quickstart'
 
 class WitException < Exception
 end
 
-def req(access_token, meth_class, path, params={}, payload={})
+def req(logger, access_token, meth_class, path, params={}, payload={})
   uri = URI(WIT_API_HOST + path)
-  uri.query = URI.encode_www_form params
+  uri.query = URI.encode_www_form(params)
 
-  request = meth_class.new uri
+  logger.debug("#{meth_class} #{uri}")
+
+  request = meth_class.new(uri)
   request['authorization'] = 'Bearer ' + access_token
   request['accept'] = 'application/vnd.wit.' + WIT_API_VERSION + '+json'
   request.add_field 'Content-Type', 'application/json'
   request.body = payload.to_json
 
-  Net::HTTP.start uri.host, uri.port, {:use_ssl => uri.scheme == 'https'} do |http|
-    rsp = http.request request
-    raise WitException.new "HTTP error code=#{rsp.code}" unless rsp.code.to_i <= 200
-    json = JSON.parse rsp.body
-    raise WitException.new "Wit responded with an error: #{json['error']}" if json.has_key? 'error'
+  Net::HTTP.start(uri.host, uri.port, {:use_ssl => uri.scheme == 'https'}) do |http|
+    rsp = http.request(request)
+    if rsp.code.to_i != 200
+      raise WitException.new("HTTP error code=#{rsp.code}")
+    end
+    json = JSON.parse(rsp.body)
+    if json.has_key?('error')
+      raise WitException.new("Wit responded with an error: #{json['error']}")
+    end
+    logger.debug("#{meth_class} #{uri} #{json}")
     json
   end
 end
 
-def validate_actions(actions)
-  learn_more = 'Learn more at https://wit.ai/docs/quickstart'
-  Wit.logger.warn 'The second parameter should be a Hash' unless actions.is_a? Hash
-  [:say, :merge, :error].each do |action|
-    Wit.logger.warn "The #{action} action is missing. #{learn_more}" unless actions.has_key? action
+def validate_actions(logger, actions)
+  [:send].each do |action|
+    if !actions.has_key?(action)
+      logger.warn "The #{action} action is missing. #{LEARN_MORE}"
+    end
   end
   actions.each_pair do |k, v|
-    Wit.logger.warn "The '#{k}' action name should be a symbol" unless k.is_a? Symbol
-    Wit.logger.warn "The '#{k}' action should be a lambda function" unless v.respond_to? :call and v.lambda?
-    Wit.logger.warn "The \'say\' action should take 3 arguments: session_id, context, msg. #{learn_more}" if k == :say and v.arity != 3
-    Wit.logger.warn "The \'merge\' action should take 4 arguments: session_id, context, entities, msg. #{learn_more}" if k == :merge and v.arity != 4
-    Wit.logger.warn "The \'error\' action should take 3 arguments: session_id, context, error. #{learn_more}" if k == :error and v.arity != 3
-    Wit.logger.warn "The '#{k}' action should take 2 arguments: session_id, context. #{learn_more}" if k != :say and k != :merge and k != :error and v.arity != 2
+    if !k.is_a?(Symbol)
+      logger.warn "The '#{k}' action name should be a symbol"
+    end
+    if !(v.respond_to?(:call) && v.lambda?)
+      logger.warn "The '#{k}' action should be a lambda function"
+    end
+    if k == :send && v.arity != 2
+      logger.warn "The \'send\' action should take 2 arguments: request and response. #{LEARN_MORE}"
+    end
+    if k != :send && v.arity != 1
+      logger.warn "The '#{k}' action should take 1 argument: request. #{LEARN_MORE}"
+    end
   end
   return actions
 end
 
 class Wit
-  class << self
-    attr_writer :logger
+  def initialize(opts = {})
+    @access_token = opts[:access_token]
 
-    def logger
-      @logger ||= begin
-        $stdout.sync = true
-        Logger.new(STDOUT)
-      end.tap { |logger| logger.level = Logger::INFO }
+    if opts[:logger]
+      @logger = opts[:logger]
     end
-  end
 
-  def initialize(access_token, actions)
-    @access_token = access_token
-    @actions = validate_actions actions
+    if opts[:actions]
+      @actions = validate_actions(logger, opts[:actions])
+    end
   end
 
   def logger
-    self.class.logger
+    @logger ||= begin
+      x = Logger.new(STDOUT)
+      x.level = Logger::INFO
+      x
+    end
   end
 
   def message(msg)
-    logger.debug "Message request: msg=#{msg}"
     params = {}
     params[:q] = msg unless msg.nil?
-    res = req @access_token, Net::HTTP::Get, '/message', params
-    logger.debug "Message response: #{res}"
+    res = req(logger, @access_token, Net::HTTP::Get, '/message', params)
     return res
   end
 
   def converse(session_id, msg, context={})
-    logger.debug "Converse request: session_id=#{session_id} msg=#{msg} context=#{context}"
-    raise WitException.new 'context should be a Hash' unless context.is_a? Hash
+    if !context.is_a?(Hash)
+      raise WitException.new('context should be a Hash')
+    end
     params = {}
     params[:q] = msg unless msg.nil?
     params[:session_id] = session_id
-    res = req @access_token, Net::HTTP::Post, '/converse', params, context
-    logger.debug "Converse response: #{res}"
+    res = req(logger, @access_token, Net::HTTP::Post, '/converse', params, context)
     return res
   end
 
-  def run_actions_(session_id, message, context, max_steps, user_message)
-    raise WitException.new 'max iterations reached' unless max_steps > 0
+  def __run_actions(session_id, message, context, i)
+    if i <= 0
+      raise WitException.new('Max steps reached, stopping.')
+    end
+    json = converse(session_id, message, context)
+    if json['type'].nil?
+      raise WitException.new('Couldn\'t find type in Wit response')
+    end
 
-    rst = converse session_id, message, context
-    raise WitException.new 'couldn\'t find type in Wit response' unless rst.has_key? 'type'
+    logger.debug("Context: #{context}")
+    logger.debug("Response type: #{json['type']}")
 
-    type = rst['type']
+    # backwards-compatibility with API version 20160516
+    if json['type'] == 'merge'
+      json['type'] = 'action'
+      json['action'] = 'merge'
+    end
 
-    return context if type == 'stop'
-    if type == 'msg'
-      raise WitException.new 'unknown action: say' unless @actions.has_key? :say
-      msg = rst['msg']
-      logger.info "Executing say with: #{msg}"
-      @actions[:say].call session_id, context.clone, msg
-    elsif type == 'merge'
-      raise WitException.new 'unknown action: merge' unless @actions.has_key? :merge
-      logger.info 'Executing merge'
-      context = @actions[:merge].call session_id, context.clone, rst['entities'], user_message
-      if context.nil?
-        logger.warn 'missing context - did you forget to return it?'
-        context = {}
-      end
-    elsif type == 'action'
-      action = rst['action'].to_sym
-      raise WitException.new "unknown action: #{action}" unless @actions.has_key? action
-      logger.info "Executing action #{action}"
-      context = @actions[action].call session_id, context.clone
+    if json['type'] == 'error'
+      raise WitException.new('Oops, I don\'t know what to do.')
+    end
+
+    if json['type'] == 'stop'
+      return context
+    end
+
+    request = {
+      'session_id' => session_id,
+      'context' => context.clone,
+      'text' => message,
+      'entities' => json['entities']
+    }
+    if json['type'] == 'msg'
+      throw_if_action_missing(:send)
+      response = {
+        'text' => json['msg'],
+        'quickreplies' => json['quickreplies'],
+      }
+      @actions[:send].call(request, response)
+    elsif json['type'] == 'action'
+      action = json['action'].to_sym
+      throw_if_action_missing(action)
+      context = @actions[action].call(request)
       if context.nil?
-        logger.warn 'missing context - did you forget to return it?'
+        logger.warn('missing context - did you forget to return it?')
         context = {}
       end
-    elsif type == 'error'
-      raise WitException.new 'unknown action: error' unless @actions.has_key? :error
-      logger.info 'Executing error'
-      @actions[:error].call session_id, context.clone, WitException.new('Oops, I don\'t know what to do.')
     else
-      raise WitException.new "unknown type: #{type}"
+      raise WitException.new("unknown type: #{json['type']}")
     end
-    return run_actions_ session_id, nil, context, max_steps - 1, user_message
+
+    return __run_actions(session_id, nil, context, i - 1)
   end
 
   def run_actions(session_id, message, context={}, max_steps=DEFAULT_MAX_STEPS)
-    raise WitException.new 'context should be a Hash' unless context.is_a? Hash
-    return run_actions_ session_id, message, context, max_steps, message
+    if !@actions
+      throw_must_have_actions
+    end
+    if !context.is_a?(Hash)
+      raise WitException.new('context should be a Hash')
+    end
+    return __run_actions(session_id, message, context, max_steps)
   end
 
   def interactive(context={}, max_steps=DEFAULT_MAX_STEPS)
-    session_id = SecureRandom.uuid
+    if !@actions
+      throw_must_have_actions
+    end
 
+    session_id = SecureRandom.uuid
     while true
       print '> '
       msg = gets.strip
+      if msg == ''
+        next
+      end
 
       begin
         context = run_actions(session_id, msg, context, max_steps)
       rescue WitException => exp
-        p exp.message
+        logger.error("error: #{exp.message}")
       end
     end
   rescue Interrupt => _exp
     puts
   end
 
-  private :run_actions_
+  def throw_if_action_missing(action_name)
+    if !@actions.has_key?(action_name)
+      raise WitException.new("unknown action: #{action_name}")
+    end
+  end
+
+  def throw_must_have_actions()
+    raise WitException.new('You must provide the `actions` parameter to be able to use runActions. ' + LEARN_MORE)
+  end
+
+  private :__run_actions
 end

data/wit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'wit'
-  s.version = '3.4.0'
+  s.version = '4.0.0'
   s.date = Date.today.to_s
   s.summary = 'Ruby SDK for Wit.ai'
   s.description = 'Ruby SDK for Wit.ai'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wit
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 4.0.0
 platform: ruby
 authors:
 - The Wit Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-23 00:00:00.000000000 Z
+date: 2016-06-28 00:00:00.000000000 Z
 dependencies: []
 description: Ruby SDK for Wit.ai
 email: help@wit.ai
@@ -21,9 +21,9 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- examples/basic.rb
 - examples/joke.rb
 - examples/quickstart.rb
-- examples/template.rb
 - lib/wit.rb
 - wit.gemspec
 homepage: https://wit.ai
@@ -46,7 +46,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for Wit.ai

data/examples/template.rb

@@ -1,19 +0,0 @@
-require 'wit'
-
-access_token = 'YOUR_ACCESS_TOKEN'
-
-actions = {
-  :say => -> (session_id, context, msg) {
-    p msg
-  },
-  :merge => -> (session_id, context, entities, msg) {
-    return context
-  },
-  :error => -> (session_id, context, error) {
-    p error.message
-  },
-}
-client = Wit.new access_token, actions
-
-session_id = 'my-user-id-42'
-client.run_actions session_id, 'your message', {}