Manual

Manual

This document describes the Behaviour Selection system found in Flipper. This system enables the user to specify XML-Templates which, based on an Information State (IS) of the current situation, can modify this Information State and execute behaviour. The Templates specify what to do when.

This document will first describe the structure of the Templates, and how to create new templates. Then it describes how the system works, and it will describe the general structure of the system. Finally it shows how the system can be build in your own project.

Creating Templates

Every ECA needs rules that specify how to behave; for example, rules that specify that if the user greets the agent, the agent should greet back. This manual describes a format to describe these rules. The rules are meant for a system that uses an Information State to keep track of the dialogue.

Every rule consists of three parts:

• Preconditions – this part describes which preconditions must be fulfilled to fire the rule. It checks the current Information State to verify whether the specified preconditions hold.
• Effects – this part describes updates and changes to the Information State when the rule is fired. This can include adding, changing or removing variables in the Information State, or calling Java functions that do something (unspecified in these rules).
• Behaviour – this part describes what behaviour to perform when the rule is fired, and what arguments are passed to the class that is responsible for performing that behaviour.

Preconditions

Preconditions specify what must be fulfilled to fire the rule. They check the current Information State to verify whether the specified preconditions hold.

The most simple precondition available is a simple comparison of two values. Usually, one of these variables is a variable from the Information State (referenced using a $-sign).
This line of code verifies whether the variable name has the value value.

<compare value1="$name" value2="value" />

To check whether to variables have the same value, just specify both variable-names:

<compare value1="$name" value2="$name2" />

Atomic value types
There are three different types of atomic values that can be specified: integers (whole numbers), doubles (decimal numbers) and strings (lists of characters). They can be specified as follows:

<compare value1="$name" value2="56" />			// an integer
<compare value1="$name" value2="48.2" />		// a double
<compare value1="$name" value2="a string" />	// a string

Arithmetics
When using numbers, it is also possible to use arithmetic operations, namely +, –, *, and /. You can use only one operation at a time, but it is possible to use them in any field. An example:

<compare value1="$name+8" value2="$name2/2" />

Value comparison
Of course, only checking if two values are equal is not very flexible. To make more kinds of comparisons, use the comparator attribute. An example:

<compare value1="$name" comparator="smaller_than" value2="value" />

The following comparators are possible:

• equals – checks if the name and the value are equal (the same as specifying no comparator)
• not_equals – checks if the name and the value are not equal (also returns FALSE when the two types are not equals)
• greater_than – checks if the name is greater than the value (only works for Integer and Doubles)
• greater_equals – checks if the name is greater or equal to the value (only works for Integer and Doubles)
• smaller_than – checks if the name is smaller than the value (only works for Integer and Doubles)
• smaller_equals – checks if the name is smaller or equal to the value (only works for Integer and Doubles)
• exists – checks if the name exists in the Information State (no value is necessary)
• not_exists – checks if the name does not exists in the Information State (no value necessary)
• contains – checks if the list in the name contains the value
• not_contains – checks if the list in the name does not contain the value (also returns FALSE when the two types are not equals)

Data types
The two last comparator stated check if a list contains a certain value or not. There are three different data types possible in this template: an atomic value (as in every previous example), a record (a dynamic set with a name which contains one or more variables of any type), and a list (a dynamic list of variables of a certain type). A record-element can be checked in the following manner:

<compare value1="$record1.name" value2="value" />

The elements in a list can be checked in a following manner:

<compare value1="$listname._first" value2="value" />
<compare value1="$listname._last" value2="value" />
<compare value1="$listname.23" value2="value" />
<compare value1="$listname" comparator="contains" value2="value" />

Of course, these data-types can be nested as well, to create, for example, the following statement (in which list1 contains records, and each record contains a list named list2):

<compare value1="$list1._first.list2._last" value2="value" />

Indicators
A special precondition is the Indicator. An indicator checks if there is enough proof (enough indication) for a certain feature. This proof is calculated by a number of Compares, which can influence this proof.

The proof is coded as a number (Integer or Double), and this proof-value is given a start-value. Each Compare-element inside the Indicator can influence the proof by modifying the proof-value: if the Compare is valid, then the specified modifier is applied on the proof-value. When every Compare is checked and all modifiers are applied, then the current proof-value is checked (with the given comparator) with the given end-value. If the comparison is valid, then the indicator is valid too.

As an example, in the next fragment an indicator is specified which tries to find proof for an angry user (eyebrows down, high energy in the speech, and very important, a high detected arousal):

<indicator startvalue="1" comparator="greater_equals" endvalue="2">
   <icompare value1="$eyebrows" value2="down" modifier="+1" />
   <icompare value1="$speechenergy" comparator="greater_than" value2="0.7" modifier="+1" />
   <icompare value1="$arousal" comparator="greater_equals" value2="0.6" modifier="+2" />
</indicator>

Some notes on Indicators:

• Compares that are used within an Indicator are called icompare (to differentiate them from normal Compares).
• An ICompare contains the same attributes as a normal Compare, plus a modifier-attribute, which specifies how to modify the proof-value.
• A modifier contains an arithmetic operator (modifier) (+, –, *, or /) and a number.

Triggers
Another special precondition is the Trigger. A trigger is exactly the same as a normal precondition (except an indicator), only it starts with <trigger instead of <compare. The main difference is that a trigger is something the agent waits for before choosing the rule (for example, AgentIntention=take_turn). When all other preconditions but the triggers are fulfilled, then the agent is waiting for the right moment to fire the rule. This means it can start preparing the rule, and when the right moment is there it can immediately fire it.

Effects

Effects update and change the information state when the rule is fired. This can include adding, changing or removing atomic variables in the Information State, or calling functions that do something (unspecified in these rules).

Adding, removing, changing atomic variables
The most simple effect is changing or adding a new variable in the Information State, by specifying the name and the new value:

<update name="$name" value="value" />

Of course, arithmetic operations can be used in the value-field too, just as references to other variables. To delete a variable from the Information State, instead of using update, use remove, and specify the name of the variable to remove from the IS

<remove name="$name"/>

Data types
A value in a record is removed, added or updated in exactly the same way as an atomic variable:

<update name="record.name" value="value" />

In a list, there are four options. It is possible to add a new value to the front of the list and to the end of the list, and it is possible to change or remove the first or the last value of the list:

<update name="list._addlast" value="value" />
<update name="list._addfirst" value="value" />
<update name="list._last" value="value" />
<update name="list._first" value="value" />

Functions
To make the templates even more powerful, it is possible to implement custom functions (written in Java). These functions can do anything you want, and can then be called in the templates. When doing this, the name of the function plus any arguments should be specified. An example:

<function name="functionname">
  <argument value="argument 1" />
</function>

Behaviour

A Behaviour block describes what behaviour to perform when the rule is fired and what arguments are passed to the class that is responsible for performing that behaviour. The block contains a link to the class (a Java object) that is responsible for performing the desired behaviour, and a value for the quality of this behaviour. Quality says something about how strong the result of the rule is. The quality-attribute is optional, but if it is not specified it gets a default value of 0.5.

Inside the behaviour block arguments can be specified, which are send to the stated behaviour-class. An argument contains an argument-name (a string or a reference to a string variable), and a value (which can be anything, even records, lists, arithmetic operations and references to other variables).

An example:

<behaviour class="poppy.behaviour" quality="0.6">
   <argument name="name" value="value" />
</behaviour>

###Optional effects and behaviours To make it possible to have different results in the same template, it is possible to add probabilistic effects and behaviours by creating a optional element. An optional-element contains option-elements, and each option-element has a certain chance of being chosen. Of each optional-element, exactly 1 option-element will be selected and executed (based on the specified probabilities).
An example:

<optional>
   <option probability="0.5">
      <c_effects>
         <c_update name="target_character" value="Poppy" />
      </c_effects>
   </option>
   <option probability="0.5">
      <c_effects>
         <c_update name="target_character" value="Spike" />
      </c_effects>
   </option>
</optional>

In this example, there is a 50% chance that the IS-variable target_character is set to Poppy, and 50% that it is set to Spike. By creating multiple optional-elements it is possible to create multiple probabilistic events. By creating an empty option-element it is possible to have a do_nothing-option.

To differentiate between Effects and Behaviours inside an Optional-element, every element inside an Option starts with c_ (c as in choice).

An example script

This is an example of how a complete template could look like. The Template-element has 2 attributes, an obligatory ID (which has to be unique for the template), and an optional Name (in which you can write down a readable name of the template.

<template id="id_21" name="An example template">
   <preconditions>
      <compare value1="$speech.energy" comparator="greater_than" value2="$speech.prev.energy*2" />
      <indicator startvalue="1" comparator="greater_equals" endvalue="2">
         <icompare value1="$eyebrows" value2="down" modifier="+1" />
         <icompare value1="$speech.energy" comparator="greater_than" value2="0.7" modifier="+1" />
         <icompare value1="$arousal" comparator="greater_equals" value2="0.6" modifier="+2" />
      </indicator>
      <trigger value1="$agent_intention" value2="take_turn" />
   </preconditions>

   <effects>
      <update name="agent_speaking_state" value="speaking" />
      <update name="user_state" value="angry"/>
      <function name="notify_modules">
        <argument value="user_state" />
        <argument value="$user_state" />
      </function>
   </effects>

   <behaviour class="poppy.behaviour" quality="0.6">
      <argument name="response" value="calm_down" />
      <argument name="politeness" value="$agent_politeness – 0.1" />
   </behaviour>
</template>

Behaviour Selection

The most important task of the system is to select the templates to execute. This selection is done each time the Templates are evaluated. How often this is done depends on the user. When evaluating the Templates, the system will take the Information State and check the preconditions of all stored Templates. Based on the results, it will take the following actions:

• Templates without a Behaviour element (which only update the IS) are always executed.
• If there are 0 Templates with a Behaviour:
• Templates with a Behaviour that fulfill all preconditions except a trigger will be prepared.
• No behaviour is executed at this moment.
• If there is 1 Template with a Behaviour, then this Template is executed and no behaviours are prepared.
• If there are multiple Templates with a Behaviour:
• First the history is used to modify the quality-values of these behaviours. Recently performed behaviours will get a decreased quality-value.
• Next, the Behaviour with the highest quality-value will be executed.
• If there are multiple Behaviours with the highest quality-value, then 1 is chosen randomly.

Integrating the system

When integrating this system into your own project, the following steps have to be taken:

• Write your templates in XML, and put those files in the 'templates' directory.
• Write BehaviourClasses that perform the behaviours you specified in the Templates, and put them in the 'behaviourselection/behaviours' directory.
• Write the functions you specified in the Templates, and put them in the 'behaviourselection/functions' directory.

In your project:

• Create a new TemplateController, give it the names of the Template-files, and give it the classes that contain your functions.
• Create an InformationState and keep it up-to-date.
• Every time you want to evaluate the Templates (which could result in executed Behaviour), call the CheckTemplates(InformationState is) method of the TemplateController.