A Diatheke model is a directory that contains a file named “model_config.yaml” and the following subdirectories:
| Directory | Description |
|---|---|
| chosun | The files in this directory are used at runtime by Chosun, Cobalt’s NLU engine. They are generated by model build tools and are not meant to be edited manually. |
| commands | Contains command definitions, with one command per file. |
| entities | Contains entity definitions, with one entity per file. |
| intents | Contains intent definitions, with one intent per file. |
| replies | Contains reply definitions, with one reply per file. |
| stories | Contains story definitions, with one story per file. This directory must contain at least the main story, “main.yaml”. |
A model template, with descriptions of all possible required and optional fields for each type of file may be downloaded here.
The name of each file in a model subdirectory (minus the extension) also doubles as the name/ID of the thing it represents. For example, if there is a file named “do_something_awesome.yaml” in the commands directory, the ID for that command is “do_something_awesome”. Similary, if there is a file named “Fruit.yaml” in the entities directory, the name of that entity is “Fruit”. Note that the id and filename must match exactly, including case.
There are two reasons for deriving the name from the file name:
The examples in the tutorial follow a logical naming convention so that pieces of the model that relate to each other are named similarly (e.g. apply_filter_story, apply_filter_intent, apply_filter_command, etc). This is recommended to make it easier to keep track of how the model fits together, but the actual names are arbitrary. Diatheke does not enforce the naming convention except to ensure that there is a file with the expected name for every command, entity, intent, reply, or story referenced in any of the model files.
Main.yaml defines the main story. This file is required because it represents the root state of the dialog. This is where everything begins. There are a couple special behaviors for the main story: This story cannot be re-used by other stories. init actions may be specified, which are run only once when Diatheke first starts, before the start_actions. Instead of returning to the parent story, the main story will return to the start actions when the end of the main story is reached.
An entity (a.k.a. a slot) appears in an utterance. It represents a value in an intent that can change between utterances or even be omitted entirely in some cases. Many entity properties are language specific; see Multi-lingual models for details. Formats Entities can be defined using several formats: value_list, regular_expression, fst, or alias. value_list A simple list of allowable values. value_list Properties Property Required? Description Language-specific? partial Optional If true, the list does not represent all possible values this entity is allowed to take, merely a subset of them.
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.
A command action instructs the client application to perform a task. It defines the API for communication between Diatheke and the code that performs the business logic. For example, in a story for calling another user in the system, Diatheke may first return a lookup command with the name the user specified as an input parameter. The client application would query its own back-end to determine whether the person with that name is an available user, and would return the result of that lookup as an output parameter.
A conditional action checks the value of any parameter in the session’s memory to see if it matches an expected value (the condition). A conditional action may specify several conditions along with the actions that should be taken when the condition is satisfied. Diatheke will evaulate the conditions in the order they are listed in the conditional action until it finds one that is satisfied. If it reaches the end of the list without matching a condition, it will use the default actions if they are specified.
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 or if the intent is invalid for this input action. Properties of an input action Property Required?
To allow the same model to be used for multiple languages, intents, entities, and replies require the language and country code to be specified. Since stories and commands refer to the ids of the intents, entities, and replies, they are language-independent.