wit 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb6fd4fd673c2e0a4788d1f843d316fa925a7afd
-  data.tar.gz: f86c64544a7dd61b3b1f232c3a9a9e48e590d38b
+  metadata.gz: 20bcf5fae1df0ea0fe610b69f059f21dbe12f5e1
+  data.tar.gz: 9784d136f7e6dcd658dd5f902ac882a38f294b2b
 SHA512:
-  metadata.gz: f4de22f57f076e5946c600e45a2cd09e8fbe222bbe5ff6215bcdd7bb978e51a6224ca5f74bfe5a7013c37085d093c1b393aa8d34305c7635b55753ba2f6fd41c
-  data.tar.gz: aa5003e437f4716b8961d0d58f42449a3ce490bc09b7c891a144e1bd605bf55e206162f111422221b786533a97651a1d756100ea7a5325b0b6ad1d413f43ec06
+  metadata.gz: bcc746f4aa7fe8e71ec4e5f0c4aff56b6c61b968f0bff398a3de3280e7698b50073ce4f0c9e953e485f96c983809373015e88027272cfe75160af3fb9a760e29
+  data.tar.gz: 6ec24766a8061ab26d2530c1631f84c30d352ee87c7ca51fb70eeb8ec0a06714657570a9c925d4a87b6baa5c58b27a0ccd7bd6e8a19a0877951991685a5d4af0

data/CHANGES.md

@@ -1,3 +1,11 @@
+## v3.0
+
+Bot Engine integration
+
+### breaking
+
+- the `message` API is wrapped around a `Wit` class, and doesn't take the token as first parameter
+
 ## v2.0
 
 Rewrite in pure Ruby

data/README.md

@@ -1,40 +1,33 @@
 # wit-ruby
 
-`wit-ruby` is a Ruby client to easily use the [Wit.ai](http://wit.ai) HTTP API.
+`wit-ruby` is the Ruby SDK for [Wit.ai](http://wit.ai).
 
 ## Install
 
+From RubyGems:
 ```bash
 gem install wit
 ```
 
-## Usage
-
-```ruby
-require 'wit'
-p Wit.message('MY_ACCESS_TOKEN', 'turn on the lights in the kitchen')
-```
-
-See below for more examples.
-
-## Install from source
-
+From source:
 ```bash
 git clone https://github.com/wit-ai/wit-ruby
 gem build wit.gemspec
 gem install wit-*.gem
 ```
 
-## API
+## Usage
 
-```ruby
-require 'wit'
+See the `examples` folder for examples.
 
-access_token = 'MY_ACCESS_TOKEN'
+## API
 
-# GET /message to extract intent and entities from user request
-p Wit.message(access_token, 'turn on the lights in the kitchen')
-```
+`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
+
+See the [docs](https://wit.ai/docs) for more information.
 
 ## Thanks
 

data/examples/joke.rb

@@ -0,0 +1,55 @@
+require 'wit'
+
+# 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']
+  return nil if val.nil?
+  return val.is_a?(Hash) ? val['value'] : val
+end
+
+all_jokes = {
+  'chuck' => [
+    'Chuck Norris counted to infinity - twice.',
+    'Death once had a near-Chuck Norris experience.',
+  ],
+  'tech' => [
+    'Did you hear about the two antennas that got married? The ceremony was long and boring, but the reception was great!',
+    'Why do geeks mistake Halloween and Christmas? Because Oct 31 === Dec 25.',
+  ],
+  'default' => [
+    'Why was the Math book sad? Because it had so many problems.',
+  ],
+}
+
+actions = {
+  :say => -> (session_id, msg) {
+    p msg
+  },
+  :merge => -> (context, entities) {
+    new_context = context.clone
+    new_context.delete 'joke'
+    new_context.delete 'ack'
+    category = first_entity_value entities, 'category'
+    new_context['category'] = category unless category.nil?
+    sentiment = first_entity_value entities, 'sentiment'
+    new_context['ack'] = sentiment == 'positive' ? 'Glad you liked it.' : 'Hmm.' unless sentiment.nil?
+    return new_context
+  },
+  :error => -> (session_id, msg) {
+    p 'Oops I don\'t know what to do.'
+  },
+  :'select-joke' => -> (context) {
+    new_context = context.clone
+    new_context['joke'] = all_jokes[new_context['cat'] || 'default'].sample
+    return new_context
+  },
+}
+client = Wit.new access_token, actions
+
+session_id = 'my-user-id-42'
+client.run_actions session_id, 'tell me a joke about tech', {}

data/examples/quickstart.rb

@@ -0,0 +1,37 @@
+require 'wit'
+
+# Quickstart example
+# See https://wit.ai/l5t/Quickstart
+
+access_token = 'YOUR_ACCESS_TOKEN'
+
+def first_entity_value(entities, entity)
+  return nil unless entities.has_key? entity
+  val = entities[entity][0]['value']
+  return nil if val.nil?
+  return val.is_a?(Hash) ? val['value'] : val
+end
+
+actions = {
+  :say => -> (session_id, msg) {
+    p msg
+  },
+  :merge => -> (context, entities) {
+    new_context = context.clone
+    loc = first_entity_value entities, 'location'
+    new_context['loc'] = loc unless loc.nil?
+    return new_context
+  },
+  :error => -> (session_id, msg) {
+    p 'Oops I don\'t know what to do.'
+  },
+  :'fetch-weather' => -> (context) {
+    new_context = context.clone
+    new_context['forecast'] = 'sunny'
+    return new_context
+  },
+}
+client = Wit.new access_token, actions
+
+session_id = 'my-user-id-42'
+client.run_actions session_id, 'weather in London', {}

data/examples/template.rb

@@ -0,0 +1,19 @@
+require 'wit'
+
+access_token = 'YOUR_ACCESS_TOKEN'
+
+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.'
+  },
+}
+client = Wit.new access_token, actions
+
+session_id = 'my-user-id-42'
+client.run_actions session_id, 'your message', {}

data/lib/wit.rb

@@ -1,37 +1,103 @@
-module Wit
-  require 'json'
-  require 'net/http'
+require 'json'
+require 'net/http'
 
-  WIT_API_HOST = ENV['WIT_URL'] || 'https://api.wit.ai'
+WIT_API_HOST = ENV['WIT_URL'] || 'https://api.wit.ai'
+DEFAULT_MAX_STEPS = 5
 
-  class WitException < Exception
-  end
+class WitException < Exception
+end
 
-  def self.req(access_token, meth_class, path, params)
-    uri = URI(WIT_API_HOST + path)
-    uri.query = URI.encode_www_form(params)
+def req(access_token, meth_class, path, params={}, payload={})
+  uri = URI(WIT_API_HOST + path)
+  uri.query = URI.encode_www_form params
 
-    req = meth_class.new(uri)
-    req['authorization'] = 'Bearer ' + access_token
-    req['accept'] = 'application/vnd.wit.20160330+json'
+  request = meth_class.new uri
+  request['authorization'] = 'Bearer ' + access_token
+  request['accept'] = 'application/vnd.wit.20160330+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(req)
-      if rsp.code.to_i > 200
-        raise WitException.new('HTTP error code=' + rsp.code)
-      end
+  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
+  end
+end
 
-      JSON.parse(rsp.body)
-    end
+def validate_actions(actions)
+  learn_more = 'Learn more at https://wit.ai/docs/quickstart'
+  raise WitException.new 'The second parameter should be a Hash' unless actions.is_a? Hash
+  [:say, :merge, :error].each do |action|
+    raise WitException.new "The #{action} action is missing. #{learn_more}" unless actions.has_key? action
+  end
+  actions.each_pair do |k, v|
+    raise WitException.new "The '#{k}' action name should be a symbol" unless k.is_a? Symbol
+    raise WitException.new "The '#{k}' action should be a lambda function" unless v.respond_to? :call and v.lambda?
+    raise WitException.new "The \'say\' action should take 2 arguments: session_id, msg. #{learn_more}" if k == :say and v.arity != 2
+    raise WitException.new "The \'merge\' action should take 2 arguments: context, entities. #{learn_more}" if k == :merge and v.arity != 2
+    raise WitException.new "The \'error\' action should take 2 arguments: session_id, msg. #{learn_more}" if k == :error and v.arity != 2
+    raise WitException.new "The '#{k}' action should take 1 argument: context. #{learn_more}" if k != :say and k != :merge and k != :error and v.arity != 1
+  end
+  return actions
+end
+
+class Wit
+  def initialize(access_token, actions)
+    @access_token = access_token
+    @actions = validate_actions actions
   end
 
-  def self.message(access_token, msg)
+  def message(msg)
     params = {}
-    if msg
-      params[:q] = msg
+    params[:q] = msg unless msg.nil?
+    req @access_token, Net::HTTP::Get, '/message', params
+  end
+
+  def converse(session_id, msg, context={})
+    params = {}
+    params[:q] = msg unless msg.nil?
+    params[:session_id] = session_id
+    req @access_token, Net::HTTP::Post, '/converse', params, context
+  end
+
+  def run_actions(session_id, message, context={}, max_steps=DEFAULT_MAX_STEPS)
+    raise WitException.new 'max iterations reached' unless max_steps > 0
+
+    rst = converse session_id, message, context
+    raise WitException.new 'couldn\'t find type in Wit response' unless rst.has_key? 'type'
+
+    type = rst['type']
+
+    return context if type == 'stop'
+    if type == 'msg'
+      raise WitException.new 'unknown action: say' unless @actions.has_key? :say
+      msg = rst['msg']
+      p "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'
+      context = @actions[:merge].call context, rst['entities']
+      if context.nil?
+        p '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}"
+      context = @actions[action].call context
+      if context.nil?
+        p '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'
+      @actions[:error].call session_id, 'unknown action: error'
+    else
+      raise WitException.new "unknown type: #{type}"
     end
-    req(access_token, Net::HTTP::Get, '/message', params)
+    return run_actions session_id, nil, context, max_steps - 1
   end
 end

data/wit.gemspec

@@ -1,15 +1,15 @@
 Gem::Specification.new do |s|
-	s.name = 'wit'
-	s.version = '2.0.0'
-	s.date = '2014-12-05'
-	s.summary = 'Ruby SDK for Wit.ai'
-	s.description = 'Ruby SDK for Wit.ai'
-	s.authors = ['The Wit Team']
-	s.email = 'help@wit.ai'
-	s.homepage = 'https://wit.ai'
-	s.license = 'GPL-2.0'
-	s.platform = Gem::Platform::RUBY
-	s.required_ruby_version = '>= 1.9.3'
-	s.require_paths = ['lib']
-	s.files = `git ls-files`.split("\n")
+  s.name = 'wit'
+  s.version = '3.0.0'
+  s.date = '2014-12-05'
+  s.summary = 'Ruby SDK for Wit.ai'
+  s.description = 'Ruby SDK for Wit.ai'
+  s.authors = ['The Wit Team']
+  s.email = 'help@wit.ai'
+  s.homepage = 'https://wit.ai'
+  s.license = 'GPL-2.0'
+  s.platform = Gem::Platform::RUBY
+  s.required_ruby_version = '>= 1.9.3'
+  s.require_paths = ['lib']
+  s.files = `git ls-files`.split("\n")
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wit
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - The Wit Team
@@ -16,10 +16,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - CHANGES.md
 - LICENSE
 - README.md
+- examples/joke.rb
+- examples/quickstart.rb
+- examples/template.rb
 - lib/wit.rb
 - wit.gemspec
 homepage: https://wit.ai
@@ -32,17 +35,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14.1
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for Wit.ai