Each story is defined in a yaml file under the stories folder. In the case of zoom story, we need to create a zoom_story.yaml file as shown below.
In this example zoom_story definition file, there is a list of two start actions. That means when the zoom story is called (in response to the zoom_intent) those two actions, the zoom_command action and zoom_reply action, will be executed by Diatheke in that order.
There are different action types that Diatheke can execute. This example introduces the command and reply actions: as the names suggest, the zoom_command is a command action and the zoom_reply is a reply action. Those two action types are explained in more detail below. The story returns a command to the calling application passing as parameters whatever entity values were specified, and gives a verbal reply describing what it’s doing.
start_actions:
- type: command
id: zoom_command
- type: reply
id: zoom_reply
A command specifies what parameters to pass back to the calling application (inputs), and what the calling application should pass back (outputs). Each command is defined in a yaml file under the commands directory with a file name matching the id of the command in the story file.
An example yaml file for the zoom_command is shown below. In the simplified example, the photo display app adjusts the zoom according to the parameters specified (if any) and doesn’t pass anything back. If the user didn’t specify a value for an entity, Diatheke will return an empty string for that parameter (unless the story specifies that it’s a required parameter, which we’ll demonstrate in the apply_filter story). The calling application code handles empty parameters.
inputs:
- zoom_direction
- zoom_amount
outputs:
The second action defined in the story file above is a reply action. Reply actions are used to play reply utterances to the user using text-to-speech. Each reply action is defined in a separate file in the reply folder in the Diatheke model. In our example, the zoom_reply action is defined in the zoom_reply.yaml file shown below.
In the zoom_reply definition file, there is a list of responses available. Which response will be used by Diatheke is determined by which slots have been filled and which parameters were returned by the command. For example, if the user says “zoom out by 50 percent”, then both zoom_direction and zoom_amount are specified and Diatheke will play “zooming out 50 percent”.
If the reply definition file contains multiple equally appropriate replies, Diatheke will choose one randomly to allow variety in the dialogues.
This example assumes that if zoom_direction is an empty string, the calling app will zoom in, so the reply if no entity values are specified is “Zooming in”.
language_data:
en_US:
- Zooming in.
- Zooming in ${zoom_amount}.
- Zooming ${zoom_direction}.
- Zooming ${zoom_direction} ${zoom_amount}.
Next we’ll extend the story to have Diatheke take different actions depending on different conditions.