upgrade for bot engine v1

Author: Martin Raison

CHANGES.md

@@ -1,3 +1,16 @@
+## 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`

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
 

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

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 @@ def first_entity_value(entities, entity)
 }
 
 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

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