Stories and action lists

Stories define dialog paths, which consist of one or more actions in a list that Diatheke should take.

A story groups together several related actions that help accomplish a particular goal. This is where the desired dialog flow is defined as sequences of actions, with a definitive start and end to the story.

Actions

Diatheke supports the following types of actions:

Action type Description ID
input Waits for the user (via the client app) to send input to Diatheke. This is a branching action. The name of the input action to use, as defined under input_actions in the story file.
command Requests the client app to perform a specific, named task. Filename (without extension) in the commands folder
reply Sends a reply back to the user (via the client app). Filename (without extension) in the replies folder
conditional Checks whether parameters in a session’s memory satisfy a particular condition. This is a branching action. The name of the conditional action to use, as defined under conditional_actions in the story file.
memory Manipulates the session’s memory by clearing or setting parameters. One of 4 memory actions as specified below under Memory Action
story Runs a different story from start to finish as though it were a single action in the story where it is used. This makes it easy to re-use common bits of functionality in the dialog. Filename (without extension) in the stories folder
named Runs a story-specific set of actions that is defined in the same story file as where it is used. Either the name of a named-actions list defined under named_actions in the story file, or the special names “start” or “end”, which will move the dialog to the start or end of the current story.

Actions in a list are executed in the order specified. Unless the last action in the list has the type named, input, or conditional, the end of the story is implied with the end of the action list. If an input action is last, the dialog waits for input then branches according to its intents. If a conditional action is last, the dialog branches according to its conditions. If a named action is last, that set of actions is executed. There must be at least one path through the story that allows the story to end, otherwise Diatheke will return an error when the model is loaded.

Story Start

Every story begins with the start_actions list. The actions in the list will be executed when the story begins. Often this list will end with an input or conditional action, but that is not a requirement. It is possible to define simple stories (like the first zoom example in the tutorial) that only execute the actions in the start list, then end the story.

It is also possible to return back to the start of the story by using the “named” action type with an id of “start” in other action lists.

Story End

The end of the story is implied when the end of an action list is reached, provided the last action in the list does not lead to other actions (e.g., branching actions). To make the end explicit, the last action in a list may have the “named” type, with an id of “end”.

Named Actions

Named actions group together action lists so they can be used multiple times in the story (for example, in response to different conditions in a Conditional Action). The same thing could be achieved by creating a separate story for the action list, but Named Actions allow the definition to refer to other story-specific actions.

Branching Actions

There are two types of actions that effectively cause the dialog flow to branch in different directions.

  1. Input action, where Diatheke waits for input from the user.
  2. Conditional action, which execute different actions depending on the values of parameters.

Defaults

Stories may specify defaults that apply to the current story and the actions specified within it. Most of them apply to input actions. The precedence for using default behavior is as follows:

  1. Use the behavior defined in a specific action.
  2. If the behavior is not defined by the current action, use the behavior defined by the current story’s defaults.
  3. If undefined in the current story, use the behavior defined by the parent story’s defaults. In this case, the current story will end early and control will return to the parent story.
  4. If undefined in the parent story, use the defaults defined by an ancestor. This will end all of the stories that are descendants of that ancestor, and control will return to the ancestor with default behavior defined. Diatheke may go all the way back to the main story to find such an ancestor.
  5. If undefined in the main story, do nothing.

Session Memory

A Diatheke session keeps track of all the parameters defined during the dialog. A parameter is a simple name-value pair. Both the name and the value are always strings. Parameters are defined in one of four ways:

  1. Slots recognized by the NLU from user input. The resulting parameter has the same name as the slot.
  2. Return values defined by the client as the result of a command action.
  3. Parameters defined specifically by the model using the memory action.
  4. Parameters defined automatically by Diatheke (such as the last_confidence_low parameter, which is set when an intent is recognized with a low confidence).

Unless specifically instructed to do so by a memory action in the model, Diatheke will not clear parameters from the session’s memory, so it is very important that modelers decide when and which parameters should be cleared from memory during dialog execution.

Memory Action

The memory action may specify one of the following for the action id:

ID Description
reset_all Clear all parameters from memory.
reset_all_except Clear all parameters from memory except for those named by the action.
reset Clear only the named parameters from memory.
set Set parameters to specific values. If not already defined in memory, this will define them.

Examples of each are shown below: 

    
actions:
  # Clear all parameters from session memory.
  - type: memory
    id: reset_all

  # Clear all parameters except those listed.
  - type: memory
    id: reset_all_except
    param_list:
      - fruit

  # Clear only the parameters listed
  - type: memory
    id: reset
    param_list:
      - vegetable

  # Set new parameters to specific values. This example
  # defines and sets the parameter "foo" to the
  # value "wonderful", and the parameter "bar" to the
  # value "chocolate".
  - type: memory
    id: set
    param_map:
      foo: wonderful
      bar: chocolate