Merge pull request #1 from auroraapi/feature/conversation-flow

Feature/conversation flow

Author: nkansal96

README.md

@@ -224,3 +224,61 @@ for speech in continuously_listen(silence_len=0.5):
     # do something to actually turn off the lamp
     print("Turning off the lamp")
 ```
+
+### Dialog Builder
+
+You can create a high-level outline of a conversation using the Dialog Builder, available in the Aurora Dashboard. Once you have create the dialog, its ID will be available to you in the "Conversation Details" sidebar (under "Conversation ID"). You can use this ID to create and run the entire conversation in just a few lines of code:
+
+```python
+# Import the package
+import auroraapi as aurora
+from auroraapi.dialog import Dialog
+
+# Set your application settings
+aurora.config.app_id    = "YOUR_APP_ID"     # put your app ID here
+aurora.config.app_token = "YOUR_APP_TOKEN"  # put your app token here
+
+# Create the Dialog with the ID from the Dialog Builder
+dialog = Dialog("DIALOG_ID")
+
+# Run the dialog
+dialog.run()
+```
+
+If you've used a UDF (User-Defined Function) in the Dialog Builder, you can write the corresponding function and register it to the dialog using the `set_function` function. The UDF must take one argument, which is the dialog context. You can use it to retrieve data from other steps in the dialog and set custom data for future use (both in UDFs and in the builder).
+
+If the UDF in the dialog builder has branching enabled, then you can return `True` or `False` to control which branch is taken.
+
+```python
+from auroraapi.dialog import Dialog
+
+def udf(context):
+  # get data for a particular step
+  data = context.get_step_data("step_id")
+  # set some custom data
+  context.set_user_data("id", "some data value")
+  # return True to take the upward branch in the dialog builder
+  return True
+
+dialog = Dialog("DIALOG_ID")
+dialog.set_function("udf_id", udf)
+dialog.run()
+```
+
+Here, `step_id` is the ID of a step in the dialog builder and `udf_id` is the ID of the UDF you want to register a function for. `id` is an arbitrary string you can use to identify the data you are setting.
+
+You can also set a function when creating the `Dialog` that lets you handle whenever the current step changes or context is changed.
+
+```python
+from auroraapi.dialog import Dialog
+
+def handle_update(context):
+  # this function is called whenever the current step is changed or
+  # whenever the data in the context is updated
+  # you can get the current dialog step like this
+  step = context.get_current_step()
+  print(step, context)
+
+dialog = Dialog("DIALOG_ID", on_context_update=handle_update)
+dialog.run()
+```

auroraapi/api.py

@@ -3,9 +3,11 @@
 from auroraapi.audio import AudioFile
 
 BASE_URL = "https://api.auroraapi.com"
+# BASE_URL = "http://localhost:3000"
 TTS_URL = BASE_URL + "/v1/tts/"
 STT_URL = BASE_URL + "/v1/stt/"
 INTERPRET_URL = BASE_URL + "/v1/interpret/"
+DIALOG_URL = BASE_URL + "/v1/dialog/"
 
 class APIException(Exception):
 	""" Raise an exception when querying the API """
@@ -48,8 +50,8 @@ def get_tts(text):
 	r.raw.read = functools.partial(r.raw.read, decode_content=True)
 	return AudioFile(r.raw.read())
 
-def get_interpret(text):
-	r = requests.get(INTERPRET_URL, params=[("text", text)], headers=get_headers())
+def get_interpret(text, model):
+	r = requests.get(INTERPRET_URL, params=[("text", text), ("model", model)], headers=get_headers())
 	handle_error(r)
 	return r.json()
 
@@ -63,3 +65,8 @@ def get_stt(audio, stream=False):
 	r = requests.post(STT_URL, data=d, headers=get_headers())
 	handle_error(r)
 	return r.json()
+
+def get_dialog(id):
+	r = requests.get(DIALOG_URL + id, headers=get_headers())
+	handle_error(r)
+	return r.json()

auroraapi/dialog/__init__.py

@@ -0,0 +1 @@
+from auroraapi.dialog.dialog import *

auroraapi/dialog/context.py

@@ -0,0 +1,32 @@
+class DialogContext(object):
+	def __init__(self, on_update = lambda ctx: None):
+		self.step = {}
+		self.user = {}
+		self.udfs = {}
+		self.current_step = None
+		self.on_update = on_update
+	
+	def set_step_data(self, key, value):
+		self.step[key] = value
+		self.on_update(self)
+
+	def get_step_data(self, key, default=None):
+		if not key in self.step:
+			return default
+		return self.step[key]
+	
+	def set_user_data(self, key, value):
+		self.user[key] = value
+		self.on_update(self)
+	
+	def get_user_data(self, key, default=None):
+		if not key in self.user:
+			return default
+		return self.user[key]
+    
+	def set_current_step(self, step):
+		self.current_step = step
+		self.on_update(self)
+	
+	def get_current_step(self):
+		return self.current_step

auroraapi/dialog/dialog.py

@@ -0,0 +1,35 @@
+import json
+from auroraapi.api import get_dialog
+from auroraapi.dialog.context import DialogContext
+from auroraapi.dialog.graph import Graph
+from auroraapi.dialog.util import assert_callable, parse_date
+
+class DialogProperties(object):
+	def __init__(self, id, name, desc, appId, dateCreated, dateModified, graph, **kwargs):
+		self.id = id
+		self.name = name
+		self.desc = desc
+		self.app_id = appId
+		self.date_created = parse_date(dateCreated)
+		self.date_modified = parse_date(dateModified)
+		self.graph = Graph(graph)
+
+class Dialog(object):
+	def __init__(self, id, on_context_update=None):
+		self.dialog = DialogProperties(**get_dialog(id)["dialog"])
+		self.context = DialogContext()
+		if on_context_update != None:
+			assert_callable(on_context_update, "The 'on_context_update' parameter must be a function that accepts one argument")
+			self.context.on_update = on_context_update
+
+	def set_function(self, id, func):
+		assert_callable(func, "Function argument to 'set_function' for ID '{}' must be callable and accept one argument".format(id))
+		self.context.udfs[id] = func
+
+	def run(self):
+		curr = self.dialog.graph.start
+		while curr != None and curr in self.dialog.graph.nodes:
+			step = self.dialog.graph.nodes[curr]
+			edge = self.dialog.graph.edges[curr]
+			self.context.set_current_step(step)
+			curr = step.execute(self.context, edge)

auroraapi/dialog/graph.py

@@ -0,0 +1,21 @@
+from auroraapi.dialog.step import DIALOG_STEP_MAP
+
+class GraphEdge(object):
+  def __init__(self, left = "", right = "", prev = ""):
+    self.left = left if len(left) > 0 else None
+    self.right = right if len(right) > 0 else None
+    self.prev = prev if len(prev) > 0 else None
+  
+  def next(self):
+    if self.left != None:
+      return self.left
+    return self.right
+  
+  def next_cond(self, cond):
+    return self.left if cond else self.right
+
+class Graph(object):
+  def __init__(self, graph):
+    self.start = graph["start"]
+    self.edges = { node_id: GraphEdge(**edges) for (node_id, edges) in graph["edges"].items() }
+    self.nodes = { node_id: DIALOG_STEP_MAP[node["type"]](node) for (node_id, node) in graph["nodes"].items() }

auroraapi/dialog/step/__init__.py

@@ -0,0 +1,9 @@
+from auroraapi.dialog.step.speech import SpeechStep
+from auroraapi.dialog.step.listen import ListenStep
+from auroraapi.dialog.step.udf import UDFStep
+
+DIALOG_STEP_MAP = {
+  "speech": SpeechStep,
+  "listen": ListenStep,
+  "udf":    UDFStep,
+}

auroraapi/dialog/step/listen.py

@@ -0,0 +1,25 @@
+from auroraapi.text import Text
+from auroraapi.speech import listen_and_transcribe
+
+from auroraapi.dialog.step.step import Step
+from auroraapi.dialog.util import parse_optional
+
+class ListenStep(Step):
+  def __init__(self, step):
+    super().__init__(step)
+    data = step["data"]
+    self.model = data["model"]
+    self.interpret = data["interpret"]
+    self.step_name = data["stepName"]
+    self.listen_settings = {
+      "length": parse_optional(data["length"], float, 0),
+      "silence_len": parse_optional(data["silenceLen"], float, 0.5),
+    }
+
+  def execute(self, context, edge):
+    text = Text()
+    while len(text.text) == 0:
+      text = listen_and_transcribe(**self.listen_settings)
+    res = text.interpret(model=self.model) if self.interpret else text
+    context.set_step_data(self.step_name, res)
+    return edge.next()

auroraapi/dialog/step/speech.py

@@ -0,0 +1,44 @@
+import re, functools
+from auroraapi.text import Text
+from auroraapi.dialog.step.step import Step
+from auroraapi.dialog.util import is_iterable
+
+def resolve_path(context, path):
+  step, *components = path.split(".")
+  obj = None
+  if step == "user":
+    obj = context.user
+  elif step in context.step:
+    obj = context.step[step].context_dict()
+  if not is_iterable(obj):
+    return None
+  
+  while len(components) > 0:
+    curr = components.pop(0)
+    # TODO: handle arrays
+    if not is_iterable(obj) or curr not in obj:
+      return None
+    obj = obj[curr]
+  return obj
+
+
+class SpeechStep(Step):
+  def __init__(self, step):
+    super().__init__(step)
+    self.text = step["data"]["text"]
+    self.step_name = step["data"]["stepName"]
+
+  def execute(self, context, edge):
+    # upon execution, first find all templates and replace them with
+    # the collected value in the conversation
+    replacements = []
+    for match in re.finditer(r'(\${(.+?)})', self.text):
+      val = resolve_path(context, match.group(2))
+      # TODO: do something on data not found
+      replacements.append({ "original": match.group(1), "replacement": val })
+
+    text = functools.reduce(lambda t, r: t.replace(r["original"], r["replacement"]), replacements, self.text)
+    sp = Text(text).speech()
+    context.set_step_data(self.step_name, sp)
+    sp.audio.play()
+    return edge.next()

auroraapi/dialog/step/step.py

@@ -0,0 +1,13 @@
+import json
+
+class Step(object):
+  def __init__(self, step):
+    self.id = step["id"]
+    self.type = step["type"]
+    self.raw = step
+  
+  def __repr__(self):
+    return json.dumps(self.raw, indent=2)
+  
+  def execute(self, context, edge):
+    raise NotImplementedError()