wit 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20bcf5fae1df0ea0fe610b69f059f21dbe12f5e1
-  data.tar.gz: 9784d136f7e6dcd658dd5f902ac882a38f294b2b
+  metadata.gz: 8346c258aff676710321e7452750f3ea6eff3a56
+  data.tar.gz: 625b24dc2223fef2500303d98c409deea91b3f43
 SHA512:
-  metadata.gz: bcc746f4aa7fe8e71ec4e5f0c4aff56b6c61b968f0bff398a3de3280e7698b50073ce4f0c9e953e485f96c983809373015e88027272cfe75160af3fb9a760e29
-  data.tar.gz: 6ec24766a8061ab26d2530c1631f84c30d352ee87c7ca51fb70eeb8ec0a06714657570a9c925d4a87b6baa5c58b27a0ccd7bd6e8a19a0877951991685a5d4af0
+  metadata.gz: fe28aba17bdb04e4a4614edc99bad441434c7c6f5056273e9c0092e6f1d38783202d74e7c040a199cc47314cfcd98fd4b8291b0395a4f7f17dd4dd98979147a4
+  data.tar.gz: d4b6ee270ca08b5f0f367bd06dae05e9e4eb3d5aa4b9d8e35cb085ab184dd9a12069e5baaeab50d9cf97f18ade9e7042cf4ee2bc501231339acce9c5a6974263

data/.gitignore

@@ -1,3 +1,4 @@
 *.gem
 *.swo
 *.swp
+Gemfile.lock

data/CHANGES.md

@@ -1,3 +1,8 @@
+## v3.1
+
+- allows for custom logging
+- better error message
+
 ## v3.0
 
 Bot Engine integration

data/Gemfile

@@ -0,0 +1 @@
+gemspec

data/README.md

@@ -22,13 +22,109 @@ See the `examples` folder for 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
+* `message` - the Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link)
+* `converse` - the low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link)
 * `run_actions` - a higher-level method to the Wit converse API
 
+### 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 `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:
+```ruby
+actions = {
+  :say => -> (session_id, msg) {
+    p msg
+  },
+  :merge => -> (context, entities) {
+    return context
+  },
+  :error => -> (session_id, msg) {
+    p 'Oops I don\'t know what to do.'
+  },
+}
+```
+
+A custom action takes one parameter:
+* `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
+```
+See the [Logger class](http://ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html) docs for more information.
+
+### message
+
+The Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link).
+
+Takes the following parameters:
+* `msg` - the text you want Wit.ai to extract the information from
+
+Example:
+```ruby
+resp = client.message 'what is the weather in London?'
+p "Yay, got Wit.ai response: #{resp}"
+```
+
+### run_actions
+
+A higher-level method to the Wit converse API.
+
+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:
+```ruby
+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](https://wit.ai/docs/http/20160330#converse-link).
+
+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
+
+Example:
+```ruby
+resp = client.converse 'my-user-session-42', 'what is the weather in London?', {}
+p "Yay, got Wit.ai response: #{resp}"
+```
+
+
 See the [docs](https://wit.ai/docs) for more information.
 
+
 ## Thanks
 
 Thanks to [Justin Workman](http://github.com/xtagon) for releasing a first version in October 2013. We really appreciate!

data/lib/wit.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'logger'
 require 'net/http'
 
 WIT_API_HOST = ENV['WIT_URL'] || 'https://api.wit.ai'
@@ -20,7 +21,9 @@ def req(access_token, meth_class, path, params={}, payload={})
   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.parse rsp.body
+    json = JSON.parse rsp.body
+    raise WitException.new "Wit responded with an error: #{json['error']}" if json.has_key? 'error'
+    json
   end
 end
 
@@ -42,11 +45,26 @@ def validate_actions(actions)
 end
 
 class Wit
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= begin
+        $stdout.sync = true
+        Logger.new(STDOUT)
+      end.tap { |logger| logger.level = Logger::INFO }
+    end
+  end
+
   def initialize(access_token, actions)
     @access_token = access_token
     @actions = validate_actions actions
   end
 
+  def logger
+    self.class.logger
+  end
+
   def message(msg)
     params = {}
     params[:q] = msg unless msg.nil?
@@ -72,28 +90,28 @@ class Wit
     if type == 'msg'
       raise WitException.new 'unknown action: say' unless @actions.has_key? :say
       msg = rst['msg']
-      p "Executing say with: #{msg}"
+      logger.info "Executing say with: #{msg}"
       @actions[:say].call session_id, msg
     elsif type == 'merge'
       raise WitException.new 'unknown action: merge' unless @actions.has_key? :merge
-      p 'Executing merge'
+      logger.info 'Executing merge'
       context = @actions[:merge].call context, rst['entities']
       if context.nil?
-        p 'WARN missing context - did you forget to return it?'
+        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
-      p "Executing action #{action}"
+      logger.info "Executing action #{action}"
       context = @actions[action].call context
       if context.nil?
-        p '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
-      p 'Executing error'
+      logger.info 'Executing error'
       @actions[:error].call session_id, 'unknown action: error'
     else
       raise WitException.new "unknown type: #{type}"

data/wit.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'wit'
-  s.version = '3.0.0'
+  s.version = '3.1.0'
   s.date = '2014-12-05'
   s.summary = 'Ruby SDK for Wit.ai'
   s.description = 'Ruby SDK for Wit.ai'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wit
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - The Wit Team
@@ -18,6 +18,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - CHANGES.md
+- Gemfile
 - LICENSE
 - README.md
 - examples/joke.rb