Nodes - dialogos-project/dialogos GitHub Wiki
This chapter describes the different node types available for use in a dialog flow. Each node type possesses specific functionality along with a fixed number of exit arrows which allow the dialog to continue to the next state.
You can define a variety of general parameters for each node, including the name and color of the node, as well as node-specific comments. There are, moreover, a number of specific parameters that affect the behavior of nodes. All parameters can be edited by double-clicking on the node.
Start
Each graph or subgraph is automatically supplied with exactly one Start node which marks the point from which every dialog or sub-dialog is executed. Start nodes only ever have one exit arrow and this exit is where the dialog begins. It is not permitted to delete this node or add more to the canvas, as there can only be one Start node per graph. It is possible, however, to insert a directed edge from one node to the start node by dragging an exit arrow over it and releasing. In this way, you can create a loop such that a dialog sequence will be played repeatedly.
Start nodes have no parameter options.
End
End nodes mark the end of a dialog within the main graph. Once the End node has been reached, the entire dialog has completed its execution. For this reason, End nodes have no exit arrows. Unlike Start nodes, however, a single graph may have several End nodes present, each representing different possible conditions for ending the dialog.
There are various kinds of End nodes, depending on the type of graph employing them.
End nodes have no parameter options.
End Node
The End node is only available in the main graph, but there can be more than one present. Once an End node is reached, the execution of the dialog is effectively complete.
Continue
The Continue node is only available in the context of Global Input Handlers. Once a new input handler is added, the Continue node will become available for use within the handler graph. When a new Continue node is added to the handler graph, it will create its own exit arrow, visible on all Input nodes in the main and sub dialogs, and the dialog will continue along that edge. There can be one or more Continue nodes present in an input handler graph, allowing each input node to have several exits. Different exits arising from the Continue node can be determined by their name, which can be viewed by mousing over the exit arrows on the Input node.
Loop
The Loop node is similar to Continue in that it can only be used within a Global Input Handler graph. The main difference here is that this node simply returns from the Input Handler graph to the Input node. No new exit is created.
Return
The Return node is available in Subgraphs and Procedures. It behaves similarly to Continue in that it creates a new exit arrow from the Subgraph node or from every call to the Procedure which uses it. In this way, new edges can be made, allowing the main graph to call a sub-dialog, and then return to its course in the main dialog. There can be several Return nodes in a Subgraph or Procedure, each representing a different condition for leaving that state. The course of the dialog will follow the edge from which it exited and then continue along that path in the main dialog.
Condition
The Condition node produces branching edges depending on a given condition. The condition must be defined as a parameter of the node and can be any boolean expression, which is evaluated at runtime.
The Condition node only ever has two exits: 'true' and 'false'. The dialog will continue along the edge corresponding to the evaluation of the expression.
Wait
The Wait node can be used to add pauses or delays within a dialog sequence. The delay period should be set as a parameter in the node and can be an expression, provided it evaluates to an integer value representing milliseconds.
The Wait node only ever has one exit.
Output
Output Node
The Output node provides a means of communication with external devices. From one output node, you can simultaneously send output to several devices or several outputs to a single device. Each device has its own editable list of expressions. Each expression will be evaluated sequentially and the restult send to the respective device. The output list is executed in parallel for each device.
To see the list of outputs for each device, simply click on the device on the left-hand side of the options panel. To create a new output expression and append it to the current list, click New. You can edit an output expression by double-clicking on that line. You can also change the order of expressions by dragging them with the mouse up or down through the list.
Output nodes have only one exit edge from which the dialog will continue. In addition to the output values, you can also configure various options for output:
Reset devices first:
Activating this option will terminate any running output (i.e. an audio file playing in the background), before the output of the current node is sent to a device.
Wait until output completed:
Normally the dialog will continue playing as soon as the output value has been sent to the device. In this way, the actual output (audio file playback, text-to-speech audio, etc.) can continue in the background. However, it may be necessary to synchronize the dialog flow with the exact length of the output. Activating this option will suspend the execution of the rest of the dialog until the output node gets a return call from all devices after the completion of each respective task.
Speech Output Node
The Speech Output node serves to produce speech via the built-in synthesis module in DialogOS. The output speech may be generated from plain text or from complex expressions similar to the more general Output node. To make use of plain text, simply choose Output Type Text and enter the text in the output field. To use complex expressions, choose the option Expression and enter the corresponding expression in the output field. You can also enter a Groovy expression if you choose the option "Groovy Script".
In the menu Voices, you can choose from a list of installed voices in DialogOS to produce the speech. After selecting all these options, you can click Listen to hear how the text will be produced as speech with the chosen voice.
Unless the option "Wait until output completed" is selected, the dialog will immediately continue its course even as the speech is taking place.
Input
Input
The Input node can be used to process input from external devices. The input can be the result of a speech recognition system which returns the content of user input to the dialog. Another example is the output of a database query which can provide dynamic content to your dialog.
The processing takes place through pattern matching. A list of patterns is included as the parameters of the Input node, and these patterns can be added, deleted, or edited to correspond with expected input. Each pattern will result in an additional exit arrow from the Input node, representing the path that the dialog will take if the pattern matches successfully. In this way, the dialog can branch out along different paths depending on the input from the external device. Additionally, input values can be assigned to variables in the graph directly in the pattern, so that the assignment and pattern matching occur simultaneously. Lastly, pattern matching occurs by comparing input to each pattern in the list in a top-down manner until there is a successful match. If no patterns match the input, the dialog will ignore the current input and wait for more until it finds a successful match. To avoid this, you can use the wildcard pattern '_' to match any input. You can find out more about wildcards and other pattern matching expressions in the chapter on patterns.
Editing patterns is similar to that of the Output node: clicking the buttons New and Delete will add or remove patterns from the list, while double-clicking on a pattern will open the text field for editing. You can also change the order of patterns by drag-and-drop.
Input nodes have the following options:
Device:
The Input node has access to all devices. However, you can specify that only input from a specific device will be processed.
Discard previous input:
An external device may send input while the dialog management system is not currently within an Input node. This input is not lost, but is stored in a queue for later processing. When the dialog reaches an Input node, the first (oldest) element in the queue is processed and then removed. If this is not desired, you can activate this option which will empty the queue when the Input node is reached, allowing the system to wait for "new" input.
Timeout in ms:
This option adds a new output edge to the Input node representing the case of a timeout with no input. The timeout period must be specified in milliseconds. This option can be used to avoid having the dialog wait endlessly at a single node. The timeout may also be specified as a complex expression, evaluated once the dialog reaches that node. In this way, the timeout period can be modified at runtime.
Barge-In:
Barge-In denotes the possibility of handling user input while output is being processed. In the case of speech recognition, this means that the user can interrupt the system, even as the system is producing output. Speech recognition must be activated for use of this feature.
Another possible use of this option is in the case when the Input node both sends output and receives input. If a timeout period is set for user input which does not take into account the length of time needed to produce the output, then the dialog may not, in fact, receive any input. By activating this option, the timeout will only begin after all devices for which 'Wait' is checked have reported that the output is complete. In addition, once input is received, all devices for which 'Reset' is checked will get a signal to cancel the current output and remove everything from the queue.
Speech Recognition
The Speech Recognition node is a special variant of the Input node in which input from the built-in Speech Recognition plugin can be processed. The functionality of this node is, to a great extent, identical to the Input node. The unique properties of this node, however, include the possibility of selecting a grammar directly from a drop-down list. If you have a microphone connected, you can immediately test the grammar by clicking on the button Try and saying something which the grammar can recognize. If you do not want to specify a full-fledged grammar, you can also select '<Generate from patterns>' and enter possible inputs line by line. The dialog system will, at runtime, automatically generate the grammar formalisms of your pattern needed by the speech recognition engine. A grammar must in all cases be present.
If an automatically generated grammar, or one with no language information specified, is selected, you must also select a language from a drop-down list. The option '<Default Language>' under Dialog Settings is the default choice. If the selected grammar already contains information about the language, this option can be ignored.
A pop-up window will appear while testing or playing the speech recognition node, reporting all recognized words. Once the module has finished recognizing the input, the display panel with the recognized text will close and the node will be exited.
Global settings for the speech recognizer
Under the menu item Dialog -> Speech recognizer, you can edit the global settings for the speech recognizer. These settings will apply to all speech recognizer nodes.
You can edit the following settings:
- Default Language: This dropdown sets the language which will used in each speech recognition node that uses "<Default Language>" as its language.
- Silent mode: Normally, each speech recognizer node uses your computer's microphone to record the user's spoken utterances and map them to words. If you choose the option "Silent mode", DialogOS will instead open an input window when a speech recognizer node is executed. The user can then type their utterance in this input window. This can be useful when developing a dialog or when using DialogOS is a quiet environment.
- Edit pronunciation dictionary: The build-in speech recognizer contains a large dictionary of words for each language it supports, along with information on how these words are pronounced. If you would like to use words in your dialog that are not in this dictionary, you can add them to a pronunciation dictionary, which you can edit by clicking the "Edit" button here. You can find more information on pronunciation dictionaries here.
NXT nodes
Start NXT Program
The Start NXT Program starts a program on NXT which controls a LEGO Mindstorms robot. The only parameter to give is the name of the program. By clicking the button Choose, you can get an overview of the programs available, select one and upload it to the connected NXT. When the node is reached, it will cause the program to execute and the node will be exited immediately afterwards.
Stop NXT Program
The Stop NXT Program checks whether a program is currently in progress, and if there is, stops it. By default, this node has only one exit along which the dialog will continue, however, the option "Check first whether a program is running" will create a second edge to exit along if no other program is running.
Variables
DialogOS provides two kinds of variable nodes: one which creates new variables, and one which tests the values of variables.
Creating Variables
The Set Variable node has specific parameters for choosing a variable from a drop-down list and assigning a value to that variable. Once this node is reached during runtime, the new value is saved to the the designated variable. If no variable is selected or no expression defined as its value, then an error will occur during runtime and the execution of the dialog will end.
Testing Variables
The Test Variable node allows you to test a variable for different values. This node provides a list view for defining one or more values with which to test a specified variable. These values can be thought of as patterns which will be matched with the data stored in the variable, and each value will result in one new exit from the Test Variable node. The dialog will continue along the edge whose value evaluates to true in this node. The patterns will be matched with the variable in a top-down manner at runtime. The first pattern to provide a match will be chosen and the dialog will exit along the corresponding edge of the pattern.
Optionally, you can insert an additional edge along which the dialog can continue when no patterns match. You can do this by checking the box 'Add edge for all other values' at the bottom of the pattern list. If this option is not selected and no patterns are matched at runtime, an error will be produced and the dialog will be terminated.
Script
The Script node adds flexibility to the dialog model by giving you the possibility of implementing your own code, especially with respect to manipulating variables within a graph. Scripts can make use of built-in functions for added convenience.
The Script node has only one edge from which the dialog will continue after the script finishes execution.
Label
Label nodes can be placed within any graph or subgraph. They serve as the target to which the Goto node will jump. The Label node has only one edge along which the dialog will continue, if a Goto node has selected this label as its target. The Label node has no parameters.
Goto
The Goto node can be used to jump from one point in the dialog to another. It is designed to partner with a Label node as its destination target. The target label may be placed within the currently active graph or within higher-level graphs. The Goto node cannot jump to lower-level graphs (subgraphs within the current graph) or same-level graphs (subgraphs called on the same level as the current subgraph). All variables which were only active in the subgraph will be lost (along with their content) by jumping into a higher-level graph.
The Goto option is a special parameter of the Goto node and from it you can select a Label name from a drop-down list of all possible goto targets.
Subgraph
Subgraphs represent subdialogs of the main dialog and exist in separate graphs. Subgraphs have their own set of private variables and user-defined functions which are accessible only within that subgraph (similar to the concept if local variables and procedures in the programming language Pascal).
Double-clicking on the Subgraph node opens a new window with a canvas on which you can build a new subdialog. Subgraphs can contain other subgraphs, allowing the possibility for nesting subdialogs to an arbitrary depth.
You can change the name of a subgraph by selecting Subdialog -> Rename or by clicking once on the Subgraph node until the editable text field appears and entering the new name there.
The number of End nodes in a subgraph determines the number of edges from the Subgraph: each End node in the subgraph will create exactly one exit.
When a Subgraph node is reached during the course of the dialogue, the execution of the subgraph will immediately begin from the Start node of that subgraph. The dialogue will exit the subgraph along the edge representing the End node in the subgraph on which it finished.
Procedure
The Procedure node is similar to Subgraphs in that they represent subdialogs. The main difference is that Procedure nodes can take parameters and send return values. Procedures must be called via the Call node and in this way, can be linked to the dialog graph.
Procedure nodes are meant to be subdialogs which can be called from many different positions within the dialog graph. In this way, calls to a procedure will execute the subgraph, but then immediately jump back to the position in the main graph after completion. For this reason, the Procedure node has no edges itself and cannot be connected to other nodes. Typical uses of this node include modeling recurrent graph patterns such as confirmation or clarification dialogs.
Procedure nodes can take parameters which can be used as variables within the procedure graph. Procedures can also be called from a dialog graph with different parameters at each call, giving you more flexibility with the graphs you use most. Parameters can be edited by selecting Subdialog -> Parameters and double-clicking on the parameter name, or clicking New to add a new parameter.
Similarly, return variable types can be specified by selecting Subdialog -> Return Values. Variables in this list will be returned to the calling dialog, allowing their values to be used in further processing.
Call
The Call node is designed to function in relation to procedures. Namely, the Call node is paired with the label of a Procedure node and will execute the procedure with specified argument values. The parameter options of this node include the name of the procedure it will call, the values of the arguments it takes, and the variables which will store return values. Argument and return values may be entered as a complex expression; argument values will be evaluated when the procedure is called, and return values once the procedure has finished executing.
The number of edges is from the Call node is determined by the number of end nodes in the procedure. The execution of this node calls the Start node of the procedure, sending the given arguments as its parameters. The dialog will continue along the edge corresponding to the End node from which the procedure is exited.
Next page: Running a Dialogue