A Diatheke model describes the desired flow of a conversation between a human user and a computer. There are three participants in a Diatheke model:

1. The Diatheke server (Diatheke)
2. The client application (client)
3. The human end-user (user)

Based on input from the user, Diatheke performs one or more pre-defined actions, which may include commands for the client to execute and replies to give to the user in the form of text or audio. For example,

As the dialog we are trying to model grows more complex, the number and type of actions used will also grow. To help make the model more manageable, groups of related actions that work together to accomplish a particular task are put into a story, where sequences of actions define the dialog flow.

Actions

Diatheke supports the following basic actions:

In addition to these basic actions, a model may specify a group of actions to run as a single action. This makes it easy to re-use common bits of functionality in the dialog. There are two action types that allow this:

Branching Actions

There are two types of actions that effectively cause the dialog flow to branch in different directions. The first is the input action, where Diatheke waits for input from the user. An input action specifies the allowable intents that a user may give at this point in the dialog. It also specifies which actions should be taken in response to each intent, which is what effectively causes the dialog flow to branch. An input action may also specify what actions should be taken if no intent is recognized, if the intent is invalid for this input action, if there was a timeout, etc.

The second branching action is the conditional, which

Stories

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.

There are a few reasons for structuring the dialog this way:

1. It makes large dialogs much more manageable by breaking it up into smaller pieces.
2. It helps the modeler focus on the specific piece of functionality that the story implements without having to worry about other pieces of the model.
3. Having a clearly defined start and end allows the story to be self-contained.
4. A self-contained story may be re-used in many places in the model and treated as a single action by the other stories that use it.

Story-specific actions

Conditional and input actions are story-specific, meaning they are only named and defined within stories (unlike reply and command actions, which have their own files). This is mainly because it is very difficult to define these actions in a way that would not break the self-contained nature of stories. They are both branching actions, and the specific actions the intents and conditions use are very much tied to their story.

Named actions are also story-specific so that they can refer to conditional and input actions.

Action lists

The dialog flow in a story is defined by sequences of actions. Within the story file, these sequences are defined in lists, where each action in the list is executed in the order it is specified.

When another story is used as an action, it may appear anywhere in the action list. There is no requirement that it appear at the beginning or end. Because of their self-contained nature, a story action will end in a place that allows the next action in the list to continue without any problem.

Every action in an action list must specify a type and an id. Some actions may have additional fields (such as the memory action). The expected id value is described in the table below:

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 very simple stories 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”.

Defaults

Every story 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.

The Main Story

Every model begins with the main story. This is a special file in the stories directory of the model that is always named “main.yaml”. The main story is special because, unlike normal stories which return to a parent story when it reaches the end, the main story has no parent. Instead, it automatically returns to the start once the end of the main story is reached. This effectively keeps the dialog running in a loop where it always comes back to the main starting point, allowing the user to start over with new input.

The main story is also different in that it may optionally specify init_actions, which is an action list that will be run only once when a Diatheke session is initialized from a model.

Alerts

NOTE: This will require API changes to implement.

A model may specify one or more alerts. An alert is used when the client application wants to temporarily interrupt Diatheke’s current actions to execute a specific story. When that story is finished, Diatheke resumes processing its actions where it left off before the interruption. This functionality is useful for giving notifications to the user, or to handle situations where user input is immediately required.

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:

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

Language Support

To allow the same model to be used for multiple languages, some files require the language and country code to be specified. In such cases, the model uses ISO 693 for the language code and ISO 3166 for the country code. The language code is lowercase, the country code is uppercase, and they are separated by an underscore. For example: