v3.3.0 - updating action parameters

CHANGES.md

@@ -1,3 +1,11 @@
+## v3.3.0
+
+### breaking
+
+- the `merge` action now takes 4 parameters: `session_id`, `context`, `entities`, `msg`
+- the `error` action now takes `context` as second parameter
+- custom actions now take 2 parameters: `session_id`, `context`
+
 ## v3.2
 
 - Fixed request keyword arguments issue

README.md

@@ -42,10 +42,10 @@ A minimal `actions` dict looks like this:
 def say(session_id, msg):
     print(msg)
 
-def merge(context, entities):
+def merge(session_id, context, entities, msg):
     return context
 
-def error(session_id, msg):
+def error(session_id, context):
     print('Oops, I don\'t know what to do.')
 
 actions = {
@@ -55,7 +55,8 @@ actions = {
 }
 ```
 
-A custom action takes one parameter:
+A custom action takes the following parameters:
+* `session_id` - a unique identifier describing the user session
 * `context` - the dictionary representing the session state
 
 Example:
@@ -85,7 +86,7 @@ Takes the following parameters:
 * `session_id` - a unique identifier describing the user session
 * `message` - the text received from the user
 * `context` - the dict representing the session state
-* max_steps` - (optional) the maximum number of actions to execute (defaults to 5)
+* `max_steps` - (optional) the maximum number of actions to execute (defaults to 5)
 
 Example:
 ```python

examples/joke.py

@@ -34,7 +34,7 @@ def say(session_id, msg):
     print(msg)
 
 
-def merge(context, entities):
+def merge(session_id, context, entities, msg):
     new_context = dict(context)
     if 'joke' in new_context:
         del new_context['joke']
@@ -49,11 +49,11 @@ def merge(context, entities):
     return new_context
 
 
-def error(session_id, msg):
+def error(session_id, context):
     print('Oops, I don\'t know what to do.')
 
 
-def select_joke(context):
+def select_joke(session_id, context):
     new_context = dict(context)
     jokes = all_jokes[new_context['cat'] or 'default']
     shuffle(jokes)

examples/quickstart.py

@@ -19,19 +19,19 @@ def say(session_id, msg):
     print(msg)
 
 
-def merge(context, entities):
+def merge(session_id, context, entities, msg):
     new_context = dict(context)
     loc = first_entity_value(entities, 'location')
     if loc:
         new_context['loc'] = loc
     return new_context
 
 
-def error(session_id, msg):
+def error(session_id, context):
     print('Oops, I don\'t know what to do.')
 
 
-def fetch_weather(context):
+def fetch_weather(session_id, context):
     new_context = dict(context)
     new_context['forecast'] = 'sunny'
     return new_context

examples/template.py

@@ -7,11 +7,11 @@ def say(session_id, msg):
     print(msg)
 
 
-def merge(context, entities):
+def merge(session_id, context, entities, msg):
     return context
 
 
-def error(session_id, msg):
+def error(session_id, context):
     print('Oops, I don\'t know what to do.')
 
 actions = {

setup.py

@@ -31,7 +31,7 @@
 
 setup(
     name='wit',
-    version='3.2',
+    version='3.3.0',
     description='Wit SDK for Python',
     author='The Wit Team',
     author_email='[email protected]',

wit/wit.py

@@ -21,7 +21,8 @@ def req(access_token, meth, path, params, **kwargs):
         **kwargs
     )
     if rsp.status_code > 200:
-        raise Exception('Wit responded with status: ' + str(rsp.status_code) + ' (' + rsp.reason + ')')
+        raise WitError('Wit responded with status: ' + str(rsp.status_code) +
+                       ' (' + rsp.reason + ')')
     json = rsp.json()
     if 'error' in json:
         raise WitError('Wit responded with an error: ' + json['error'])
@@ -34,10 +35,12 @@ def validate_actions(actions):
         raise WitError('The second parameter should be a dictionary.')
     for action in ['say', 'merge', 'error']:
         if action not in actions:
-            raise WitError('The \'' + action + '\' action is missing. ' + learn_more)
+            raise WitError('The \'' + action + '\' action is missing. ' +
+                           learn_more)
     for action in actions.keys():
         if not hasattr(actions[action], '__call__'):
-            raise TypeError('The \'' + action + '\' action should be a function.')
+            raise TypeError('The \'' + action +
+                            '\' action should be a function.')
     return actions
 
 
@@ -61,8 +64,8 @@ def converse(self, session_id, message, context={}):
             params['q'] = message
         return req(self.access_token, 'POST', '/converse', params, json=context)
 
-    def run_actions(self, session_id, message, context={},
-                    max_steps=DEFAULT_MAX_STEPS):
+    def __run_actions(self, session_id, message, context, max_steps,
+                      user_message):
         if max_steps <= 0:
             raise WitError('max iterations reached')
         rst = self.converse(session_id, message, context)
@@ -79,23 +82,30 @@ def run_actions(self, session_id, message, context={},
             if 'merge' not in self.actions:
                 raise WitError('unknown action: merge')
             print('Executing merge')
-            context = self.actions['merge'](context, rst['entities'])
+            context = self.actions['merge'](session_id, context,
+                                            rst['entities'], user_message)
             if context is None:
                 print('WARN missing context - did you forget to return it?')
                 context = {}
         elif rst['type'] == 'action':
             if rst['action'] not in self.actions:
                 raise WitError('unknown action: ' + rst['action'])
             print('Executing action {}'.format(rst['action']))
-            context = self.actions[rst['action']](context)
+            context = self.actions[rst['action']](session_id, context)
             if context is None:
                 print('WARN missing context - did you forget to return it?')
                 context = {}
         elif rst['type'] == 'error':
             if 'error' not in self.actions:
                 raise WitError('unknown action: error')
             print('Executing error')
-            self.actions['error'](session_id, 'unknown action: error')
+            self.actions['error'](session_id, context)
         else:
             raise WitError('unknown type: ' + rst['type'])
-        return self.run_actions(session_id, None, context, max_steps - 1)
+        return self.__run_actions(session_id, None, context, max_steps - 1,
+                                  user_message)
+
+    def run_actions(self, session_id, message, context={},
+                    max_steps=DEFAULT_MAX_STEPS):
+        return self.__run_actions(session_id, message, context, max_steps,
+                                  message)