wit 4.1.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 79a8e68599e29e35430b0cae7ed26691435dbd38
-  data.tar.gz: 5934e10cb348235ab7f619ef6030d5e1e4bce06d
+  metadata.gz: a8b09beea4b5f87b4ee4ac6db91a81e302d09415
+  data.tar.gz: 82cd100fe0cb84a361aa96afc8295e2e577afb0d
 SHA512:
-  metadata.gz: a61fc72b671a939e0970487825ee000743ba14d3537f002e9455fc9841ea965db400294c5f230aefa6d7aef288e4f883a38647ecc32ebd3d4bc4c59e3e760904
-  data.tar.gz: 1b9c4d937a90aafc671282e88a5444b463fc6c71e7f81235f5084c0543813cea1ebf9ec57abfd7f1162959c2b5d2e1d881f99fe4b76f1fa667c29ac7a6f4f486
+  metadata.gz: 13b1c151a243c6c6b3a6c1d2b4104cf8217279989360da423b625435781e04171e8ed848e7b66565438270ae25e9f66868f0e91dc8ca6487306f0bb20d55a464
+  data.tar.gz: 924f723edc7da68ceac7cd6287cdd229fee6763050cf754360b434ac2deedcee66f64dc988ab4557940b0cc7fad7be675bb6c1d3e37a1f9de2497c04b3df3ef2

data/CHANGES.md

@@ -1,3 +1,14 @@
+## v5.0.0
+
+- `converse` and `run_actions` are deprecated
+- `interactive` now calls `message`
+
+### Breaking changes
+- Renamed WitException to Wit::Error
+- Changed Wit::Error to inherit from StandardError instead of Exception
+- Moved constants inside Wit namespace
+- Moved #req and #validate_actions to private methods within Wit namespace
+
 ## v4.1.0
 
 - `converse` now takes `reset` as optional parameter.

data/README.md

@@ -32,33 +32,19 @@ See the `examples` folder for more examples.
 
 `wit-ruby` provides a Wit class with the following methods:
 * `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
 * `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:
 ```ruby
 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)
+client = Wit.new(access_token: access_token)
+client.message('set an alarm tomorrow at 7am')
 ```
 
 ### .message()
@@ -74,8 +60,19 @@ rsp = client.message('what is the weather in London?')
 puts("Yay, got Wit.ai response: #{rsp}")
 ```
 
+### .interactive()
+
+Starts an interactive conversation with your bot.
+
+Example:
+```ruby
+client.interactive
+```
+
 ### .run_actions()
 
+**DEPRECATED** See [our blog post](https://wit.ai/blog) for a migration plan.
+
 A higher-level method to the Wit converse API.
 `run_actions` resets the last turn on new messages and errors.
 
@@ -97,6 +94,8 @@ p "The session state is now: #{context2}"
 
 ### .converse()
 
+**DEPRECATED** See [our blog post](https://wit.ai/blog) for a migration plan.
+
 The low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link).
 
 Takes the following parameters:
@@ -111,14 +110,44 @@ rsp = client.converse('my-user-session-42', 'what is the weather in London?', {}
 puts("Yay, got Wit.ai response: #{rsp}")
 ```
 
-### .interactive()
+### CRUD operations for entities
+payload in the parameters is a hash containing API arguments
 
-Starts an interactive conversation with your bot.
+#### .get_entities()
+Returns a list of available entities for the app.  
+See [GET /entities](https://wit.ai/docs/http/20160526#get--entities-link)
 
-Example:
-```ruby
-client.interactive
-```
+#### .post_entities(payload)
+Creates a new entity with the given attributes.  
+See [POST /entities](https://wit.ai/docs/http/20160526#post--entities-link)
+
+#### .get_entity(entity_id)
+Returns all the expressions validated for an entity.  
+See [GET /entities/:entity-id](https://wit.ai/docs/http/20160526#get--entities-:entity-id-link)
+
+#### .put_entities(entity_id, payload)
+Updates an entity with the given attributes.  
+See [PUT /entities/:entity-id](https://wit.ai/docs/http/20160526#put--entities-:entity-id-link)
+
+#### .delete_entities(entity_id)
+Permanently remove the entity.  
+See [DELETE /entities/:entity-id](https://wit.ai/docs/http/20160526#delete--entities-:entity-id-link)
+
+#### .post_values(entity_id, payload)
+Add a possible value into the list of values for the entity.  
+See [POST /entities/:entity-id/values](https://wit.ai/docs/http/20160526#post--entities-:entity-id-values-link)
+
+#### .delete_values(entity_id, value)
+Delete a canonical value from the entity.  
+See [DELETE /entities/:entity-id/values/:value](https://wit.ai/docs/http/20160526#delete--entities-:entity-id-values-link)
+
+#### 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](https://wit.ai/docs/http/20160526#post--entities-:entity-id-values-:value-id-expressions-link)
+
+#### 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](https://wit.ai/docs/http/20160526#delete--entities-:entity-id-values-:value-id-expressions-link)
 
 See the [docs](https://wit.ai/docs) for more information.
 

data/examples/quickstart.rb

@@ -29,6 +29,7 @@ actions = {
     loc = first_entity_value(entities, 'location')
     if loc
         context['forecast'] = 'sunny'
+        context.delete('missingLocation')
     else
         context['missingLocation'] = true
         context.delete('forecast')

data/lib/wit.rb

@@ -3,64 +3,14 @@ require 'logger'
 require 'net/http'
 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(logger, access_token, meth_class, path, params={}, payload={})
-  uri = URI(WIT_API_HOST + path)
-  uri.query = URI.encode_www_form(params)
-
-  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
+class Wit
+  class Error < StandardError; end
 
-  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
+  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'
 
-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|
-    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
   def initialize(opts = {})
     @access_token = opts[:access_token]
 
@@ -69,6 +19,7 @@ class Wit
     end
 
     if opts[:actions]
+      logger.warn('Stories and POST /converse have been deprecated. This will break in February 2018!')
       @actions = validate_actions(logger, opts[:actions])
     end
 
@@ -92,7 +43,7 @@ class Wit
 
   def converse(session_id, msg, context={}, reset=nil)
     if !context.is_a?(Hash)
-      raise WitException.new('context should be a Hash')
+      raise Error.new('context should be a Hash')
     end
     params = {}
     params[:q] = msg unless msg.nil?
@@ -102,13 +53,131 @@ class Wit
     return res
   end
 
+  def run_actions(session_id, message, context={}, max_steps=DEFAULT_MAX_STEPS)
+    if !@actions
+      throw_must_have_actions
+    end
+    if !context.is_a?(Hash)
+      raise Error.new('context should be a Hash')
+    end
+
+    # Figuring out whether we need to reset the last turn.
+    # Each new call increments an index for the session.
+    # We only care about the last call to run_actions.
+    # All the previous ones are discarded (preemptive exit).
+    current_request = 1
+    if @_sessions.has_key?(session_id)
+      current_request = @_sessions[session_id] + 1
+    end
+    @_sessions[session_id] = current_request
+
+    context = __run_actions(session_id, current_request, message, context, max_steps)
+
+    # Cleaning up once the last call to run_actions finishes.
+    if current_request == @_sessions[session_id]
+      @_sessions.delete(session_id)
+    end
+
+    return context
+  end
+
+  def interactive(context={})
+    while true
+      print '> '
+      msg = STDIN.gets.strip
+      if msg == ''
+        next
+      end
+
+      begin
+        puts(message(msg))
+      rescue Error => exp
+        logger.error("error: #{exp.message}")
+      end
+    end
+  rescue Interrupt => _exp
+    puts
+  end
+
+  def throw_if_action_missing(action_name)
+    if !@actions.has_key?(action_name)
+      raise Error.new("unknown action: #{action_name}")
+    end
+  end
+
+  def throw_must_have_actions()
+    raise Error.new('You must provide the `actions` parameter to be able to use runActions. ' + LEARN_MORE)
+  end
+
+  def get_entities
+    req(logger, @access_token, Net::HTTP::Get, "/entities")
+  end
+
+  def post_entities(payload)
+    payload = payload.map {|k, v| [(k.to_sym rescue k), v]}.to_h.reject{ |k| ![:id, :doc, :values, :lookups].include?(k) }
+    validate_payload payload
+    req(logger, @access_token, Net::HTTP::Post, "/entities", {}, payload)
+  end
+
+  def get_entity(entity_id)
+    req(logger, @access_token, Net::HTTP::Get, "/entities/#{URI.encode(entity_id)}")
+  end
+
+  def put_entities(entity_id, payload)
+    payload = payload.map {|k, v| [(k.to_sym rescue k), v]}.to_h.reject{ |k| ![:id, :doc, :values].include?(k) }
+    validate_payload payload
+    req(logger, @access_token, Net::HTTP::Put, "/entities/#{URI.encode(entity_id)}", {}, payload)
+  end
+
+  def delete_entities(entity_id)
+    req(logger, @access_token, Net::HTTP::Delete, "/entities/#{URI.encode(entity_id)}")
+  end
+
+  def post_values(entity_id, payload)
+    payload = payload.map {|k, v| [(k.to_sym rescue k), v]}.to_h.reject{ |k| ![:value, :expressions, :metadata].include?(k) }
+    validate_payload payload
+    req(logger, @access_token, Net::HTTP::Post, "/entities/#{URI.encode(entity_id)}/values", {}, payload)
+  end
+
+  def delete_values(entity_id, value)
+    req(logger, @access_token, Net::HTTP::Delete, "/entities/#{URI.encode(entity_id)}/values/#{URI.encode(value)}")
+  end
+
+  def post_expressions(entity_id, value, payload)
+    payload = payload.map {|k, v| [(k.to_sym rescue k), v]}.to_h.reject{ |k| ![:expression].include?(k) }
+    validate_payload payload
+    req(logger,@access_token, Net::HTTP::Post, "/entities/#{URI.encode(entity_id)}/values/#{URI.encode(value)}/expressions", {}, payload)
+  end
+
+  def delete_expressions(entity_id, value, expression)
+    req(logger,@access_token, Net::HTTP::Delete, "/entities/#{URI.encode(entity_id)}/values/#{URI.encode(value)}/expressions/#{URI.encode(expression)}")
+  end
+
+  private
+
+  def validate_payload(payload)
+    key_types = {
+      id: String,
+      doc: String,
+      value: String,
+      values: Array,
+      lookups: Array,
+      expression: String,
+      expressions: Array,
+      metadata: String,
+    }
+    payload.each do |k, v|
+      raise Error.new("#{k.to_s} in request body must be #{key_types[k].to_s} type") unless key_types[k] == v.class
+    end
+  end
+
   def __run_actions(session_id, current_request, message, context, i)
     if i <= 0
-      raise WitException.new('Max steps reached, stopping.')
+      raise Error.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')
+      raise Error.new('Couldn\'t find type in Wit response')
     end
     if current_request != @_sessions[session_id]
       return context
@@ -124,7 +193,7 @@ class Wit
     end
 
     if json['type'] == 'error'
-      raise WitException.new('Oops, I don\'t know what to do.')
+      raise Error.new('Oops, I don\'t know what to do.')
     end
 
     if json['type'] == 'stop'
@@ -153,7 +222,7 @@ class Wit
         context = {}
       end
     else
-      raise WitException.new("unknown type: #{json['type']}")
+      raise Error.new("unknown type: #{json['type']}")
     end
 
     if current_request != @_sessions[session_id]
@@ -163,66 +232,52 @@ class Wit
     return __run_actions(session_id, current_request, nil, context, i - 1)
   end
 
-  def run_actions(session_id, message, context={}, max_steps=DEFAULT_MAX_STEPS)
-    if !@actions
-      throw_must_have_actions
-    end
-    if !context.is_a?(Hash)
-      raise WitException.new('context should be a Hash')
-    end
+  def req(logger, access_token, meth_class, path, params={}, payload={})
+    uri = URI(WIT_API_HOST + path)
+    uri.query = URI.encode_www_form(params)
 
-    # Figuring out whether we need to reset the last turn.
-    # Each new call increments an index for the session.
-    # We only care about the last call to run_actions.
-    # All the previous ones are discarded (preemptive exit).
-    current_request = 1
-    if @_sessions.has_key?(session_id)
-      current_request = @_sessions[session_id] + 1
-    end
-    @_sessions[session_id] = current_request
+    logger.debug("#{meth_class} #{uri}")
 
-    context = __run_actions(session_id, current_request, message, context, max_steps)
+    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
 
-    # Cleaning up once the last call to run_actions finishes.
-    if current_request == @_sessions[session_id]
-      @_sessions.delete(session_id)
+    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 Error.new("HTTP error code=#{rsp.code}")
+      end
+      json = JSON.parse(rsp.body)
+      if json.is_a?(Hash) and json.has_key?('error')
+        raise Error.new("Wit responded with an error: #{json['error']}")
+      end
+      logger.debug("#{meth_class} #{uri} #{json}")
+      json
     end
-
-    return context
   end
 
-  def interactive(context={}, max_steps=DEFAULT_MAX_STEPS)
-    if !@actions
-      throw_must_have_actions
+  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
-
-    session_id = SecureRandom.uuid
-    while true
-      print '> '
-      msg = gets.strip
-      if msg == ''
-        next
+    actions.each_pair do |k, v|
+      if !k.is_a?(Symbol)
+        logger.warn "The '#{k}' action name should be a symbol"
       end
-
-      begin
-        context = run_actions(session_id, msg, context, max_steps)
-      rescue WitException => exp
-        logger.error("error: #{exp.message}")
+      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
-  rescue Interrupt => _exp
-    puts
-  end
-
-  def throw_if_action_missing(action_name)
-    if !@actions.has_key?(action_name)
-      raise WitException.new("unknown action: #{action_name}")
-    end
+    return actions
   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 = '4.1.0'
+  s.version = '5.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: 4.1.0
+  version: 5.0.0
 platform: ruby
 authors:
 - The Wit Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-17 00:00:00.000000000 Z
+date: 2017-07-24 00:00:00.000000000 Z
 dependencies: []
 description: Ruby SDK for Wit.ai
 email: help@wit.ai
@@ -16,7 +16,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - CHANGES.md
 - Gemfile
 - LICENSE
@@ -36,17 +36,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.4.5
+rubygems_version: 2.0.14.1
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for Wit.ai