upgrade for bot engine v1

CHANGES.md

@@ -1,3 +1,15 @@
+## 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
 - adding verbose option for `message`, `converse` and `run_actions`
 
 ## v3.5

README.md

@@ -37,62 +37,30 @@ You can target a specific version by setting the env variable `WIT_API_VERSION`.
 ### Wit class
 
 The Wit constructor takes the following parameters:
-* `token` - the access token of your Wit instance
-* `actions` - the dictionary with your actions
+* `access_token` - the access token of your Wit instance
+* `actions` - (optional if you only use `message()`) the dictionary with your actions
 
 `actions` has action names as keys and action implementations as values.
-You need to provide at least an implementation for the special actions `say`, `merge` and `error`.
 
-A minimal `actions` dict looks like this:
-```python
-def say(session_id, context, msg):
-    print(msg)
-
-def merge(session_id, context, entities, msg):
-    return context
-
-def error(session_id, context, e):
-    print(str(e))
-
-actions = {
-    'say': say,
-    'merge': merge,
-    'error': error,
-}
-```
+A minimal example looks like this:
 
-A custom action takes the following parameters:
-* `session_id` - a unique identifier describing the user session
-* `context` - the dictionary representing the session state
-
-Example:
 ```python
 from wit import Wit
-client = Wit(token, actions)
-```
 
-### Logging
+def send(request, response):
+    print('Sending to user...', response['text'])
+def my_action(request):
+    print('Received from user...', request['text'])
 
-Default logging is to `STDOUT` with `INFO` level.
-
-You can set your logging level as follows:
-``` python
-from wit import Wit
-import logging
-client = Wit(token, actions)
-client.logger.setLevel(logging.WARNING)
-```
+actions = {
+    'send': send,
+    'my_action': my_action,
+}
 
-You can also specify a custom logger object in the Wit constructor:
-``` python
-from wit import Wit
-client = Wit(token, actions, logger=custom_logger)
+client = Wit(access_token=access_token, actions=actions)
 ```
 
-See the [logging module](https://docs.python.org/2/library/logging.html) and
-[logging.config](https://docs.python.org/2/library/logging.config.html#module-logging.config) docs for more information.
-
-### message
+### .message()
 
 The Wit [message API](https://wit.ai/docs/http/20160330#get-intent-via-text-link).
 
@@ -106,7 +74,7 @@ resp = client.message('what is the weather in London?')
 print('Yay, got Wit.ai response: ' + str(resp))
 ```
 
-### run_actions
+### .run_actions()
 
 A higher-level method to the Wit converse API.
 
@@ -127,7 +95,7 @@ context2 = client.run_actions(session_id, 'and in Brussels?', context1)
 print('The session state is now: ' + str(context2))
 ```
 
-### converse
+### .converse()
 
 The low-level Wit [converse API](https://wit.ai/docs/http/20160330#converse-link).
 
@@ -145,7 +113,7 @@ print('Yay, got Wit.ai response: ' + str(resp))
 
 See the [docs](https://wit.ai/docs) for more information.
 
-### interactive
+### .interactive()
 
 Starts an interactive conversation with your bot.
 
@@ -155,3 +123,24 @@ client.interactive()
 ```
 
 See the [docs](https://wit.ai/docs) for more information.
+
+### Logging
+
+Default logging is to `STDOUT` with `INFO` level.
+
+You can set your logging level as follows:
+``` python
+from wit import Wit
+import logging
+client = Wit(token, actions)
+client.logger.setLevel(logging.WARNING)
+```
+
+You can also specify a custom logger object in the Wit constructor:
+``` python
+from wit import Wit
+client = Wit(access_token=access_token, actions=actions, logger=custom_logger)
+```
+
+See the [logging module](https://docs.python.org/2/library/logging.html) and
+[logging.config](https://docs.python.org/2/library/logging.config.html#module-logging.config) docs for more information.

examples/basic.py

@@ -0,0 +1,17 @@
+import sys
+from wit import Wit
+
+if len(sys.argv) != 2:
+    print('usage: python ' + sys.argv[0] + ' <wit-token>')
+    exit(1)
+access_token = sys.argv[1]
+
+def send(request, response):
+    print(response['text'])
+
+actions = {
+    'send': send,
+}
+
+client = Wit(access_token=access_token, actions=actions)
+client.interactive()

examples/joke.py

@@ -2,21 +2,13 @@
 import sys
 from wit import Wit
 
-# Joke example
-# See https://wit.ai/patapizza/example-joke
-
 if len(sys.argv) != 2:
-    print("usage: python examples/joke.py <wit-token>")
+    print('usage: python ' + sys.argv[0] + ' <wit-token>')
     exit(1)
 access_token = sys.argv[1]
 
-def first_entity_value(entities, entity):
-    if entity not in entities:
-        return None
-    val = entities[entity][0]['value']
-    if not val:
-        return None
-    return val['value'] if isinstance(val, dict) else val
+# Joke example
+# See https://wit.ai/patapizza/example-joke
 
 all_jokes = {
     'chuck': [
@@ -32,10 +24,21 @@ def first_entity_value(entities, entity):
     ],
 }
 
-def say(session_id, context, msg):
-    print(msg)
+def first_entity_value(entities, entity):
+    if entity not in entities:
+        return None
+    val = entities[entity][0]['value']
+    if not val:
+        return None
+    return val['value'] if isinstance(val, dict) else val
+
+def send(request, response):
+    print(response['text'])
+
+def merge(request):
+    context = request['context']
+    entities = request['entities']
 
-def merge(session_id, context, entities, msg):
     if 'joke' in context:
         del context['joke']
     category = first_entity_value(entities, 'category')
@@ -48,22 +51,19 @@ def merge(session_id, context, entities, msg):
         del context['ack']
     return context
 
-def error(session_id, context, e):
-    print(str(e))
+def select_joke(request):
+    context = request['context']
 
-def select_joke(session_id, context):
     jokes = all_jokes[context['cat'] or 'default']
     shuffle(jokes)
     context['joke'] = jokes[0]
     return context
 
 actions = {
-    'say': say,
+    'send': send,
     'merge': merge,
-    'error': error,
     'select-joke': select_joke,
 }
-client = Wit(access_token, actions)
 
-session_id = 'my-user-id-42'
-client.run_actions(session_id, 'tell me a joke about tech', {})
+client = Wit(access_token=access_token, actions=actions)
+client.interactive()

examples/quickstart.py

@@ -1,14 +1,14 @@
 import sys
 from wit import Wit
 
-# Quickstart example
-# See https://wit.ai/l5t/Quickstart
-
 if len(sys.argv) != 2:
-    print("usage: python examples/quickstart.py <wit-token>")
+    print('usage: python ' + sys.argv[0] + ' <wit-token>')
     exit(1)
 access_token = sys.argv[1]
 
+# Quickstart example
+# See https://wit.ai/ar7hur/Quickstart
+
 def first_entity_value(entities, entity):
     if entity not in entities:
         return None
@@ -17,28 +17,27 @@ def first_entity_value(entities, entity):
         return None
     return val['value'] if isinstance(val, dict) else val
 
-def say(session_id, context, msg):
-    print(msg)
+def send(request, response):
+    print(response['text'])
+
+def get_forecast(request):
+    context = request['context']
+    entities = request['entities']
 
-def merge(session_id, context, entities, msg):
     loc = first_entity_value(entities, 'location')
     if loc:
-        context['loc'] = loc
-    return context
-
-def error(session_id, context, e):
-    print(str(e))
+        context['forecast'] = 'sunny'
+    else:
+        context['missingLocation'] = True
+        if context.get('forecast') is not None:
+            del context['forecast']
 
-def fetch_weather(session_id, context):
-    context['forecast'] = 'sunny'
     return context
 
 actions = {
-    'say': say,
-    'merge': merge,
-    'error': error,
-    'fetch-weather': fetch_weather,
+    'send': send,
+    'getForecast': get_forecast,
 }
 
-client = Wit(access_token, actions)
+client = Wit(access_token=access_token, actions=actions)
 client.interactive()

setup.py

@@ -31,7 +31,7 @@
 
 setup(
     name='wit',
-    version='3.5.0',
+    version='4.0.0',
     description='Wit SDK for Python',
     author='The Wit Team',
     author_email='help@wit.ai',