= Dialog Manager

NOTICE this page describes dialogmanager 1.4.1 (rev. 105). 
The latest dialogmanager 2.0.0 extends the evaluation functionality and json format is slightly different.



The dialog manager is a tool to create and execute dialogs  with a human user.

The basic dialog cycle as represented in DialogState and implemented in DemoApp is like this

{{{
while (!state.isFinal()) {
	state = state.withRandomOption();
	Stimulus stimulus = state.getOption().getStimulation()
		.substitute(state.getParameters());
	present stimulus
	String answer = get answer fitting state.getOption.getAnswerType();
	state = state.with(answer);
}}}

== Dependency
{{{
<dependency>
        <groupId>tudelft.utilities</groupId>
	<artifactId>dialogmanager</artifactId>
	<version>2.1.0</version>
</dependency>
}}}

also add
{{{
<repositories>
	<repository>
		<id>artifactory.ewi.tudelft.nl</id>
		<url>https://artifactory.ewi.tudelft.nl/artifactory/libs-release</url>
		<snapshots>
			<enabled>false</enabled>
		</snapshots>
	</repository>
</repositories>
}}}


== Dialog State
The DialogState contains the full description of the current situation of the dialog.

It contains two main components:
1. The DialogSpecification which is the map of the possible dialogs (see below)
2. The current Parameters which are variables that can be used to build messages and do computations  (see below)

The DialogState can be saved and later restored to resume up a dialog.


== Parameters
'Parameters' is a map of key-value pairs. The keys are a simple name String, the value is a ParameterValue, with various subtypes like BooleanValue, StringValue, VectorValue, DoubleValue.

A Parameter can be used in various ways
* Contain the user's answers, 
* Contain the current dialog state label, 
* Contain input and output values of computations

The distance between two parameters (the set of key-values) is the euclidean distance (sqrt of the sum of squares) of the difference between the two parameter values, on a per-parameter basis. Only values for which both parameters have the same key are compared. For non-numeric values, the difference is usually 0 if the values are equal, or else 1. The exact definition differes per implementation.
* The parameter values are BoolValue ("bool"), DoubleValue ("num"), KeywordsValue ("keywords"), StringValue ("txt") and VectorValue ("vector"). Check the javadocs for more details. 
* KeywordsValue is useful if you want to do keyword matching. It contains a list of (case-insensitive) keywords. The distance to a list of words (eg another Keywords parameter or the words in a StringParameter) is the [https://en.wikipedia.org/wiki/Levenshtein_distance Levenshtein distance] of any of the words to any of the keywords.
* The parameter named "phase" is special, it refers to the name of the current phase. If this variable is changed, the dialog jumps to the phase with the given name.

== Dialog specification
The dialog specification specifies the different states/phases of the dialog, and the set of questions (options) available at each phase. The following objects are used to represent this

* DialogSpecification. A kind of finite state machine. The nodes and edges are contained on  a per-node basis in {{{DialogPhase}}}s.  

The details of the DialogPhase are discussed below.

== Dialog state
The dialog state is the entire state of the dialog, which is the DialogSpecificatino plus the Parameters.

== Serialization
The entire DialogState, that is the Parameters and the DialogSpecification, including computation calls, are all json-serializable. All contained data structures can be (de)serialized to JSON. Parameters can be used to store the user's answers. But this is optional. The dialog can also proceed without storing any answers.


== DialogPhase
Each {{{DialogPhase}}} represents a situation where 
 * the user is asked a specific question
 * An answer of a specific type is retrieved
 * the next DialogPhase is determined based on the given answer. 

It contains specifically:
* a preparation which is a list of {{{UpdateFunction}}}s that allow preliminary computations to be done eg to prepare the stimulus
* a {{{Stimulus}}} which presents some sort of question to the user
* A {{{AnswerType}}} which defines how the user can specify his response
* An evaluuation which is again a list of {{{UpdateFunction}}}s, but these are typically used to determine the next {{{DialogPhase}}} by setting the "phase" parameter.

The following sections discuss elements of this

== AnswerType
The AnswerType specifies what type of answers the user can give. There are a number of AnswerTypes built in standard:
||type||description||extra parameters||
||BoolAnswer||this allows yes/no type answers.|| ||
||NumberAnswer||asks the user for a number. The valid range and step can be specified.||min, max, stepsize: Double||
||SelectFromListAnswer||user can answer from a given list of answers.||options: List<String>||
||TextAnswer: User can give a free text answer.|| ||

All answer types require a field "parameter" containing the name of the parameter that will be filled with the user's answer.

== UpdateFunction
An UpdateFunction is a function programmed in Java (extending UpdateFunction class) that can be called from the json dialog file to change parameter values.

Generally these functions look like this in json

{{{ {"NameOfFunction":[val1, val2, val3....] } }}}

NameOfFunction is the name of a java class that implements the UpdateFunction class.
The arguments provided here are the CONSTRUCTOR arguments for NameOfFunction.

To evaluate, the function {{{call(Parameters parameters) }}} is called, and that call returns an updated {{{Parameters}}} value. An update function has access to all parameters and can change any of them. But generally it is good practice to only use/change parameters provided in the constructor. In above case, it would use 



The incoming Parameters will be set to the current parameter values in the dialogstate .
The Parameters returned by the function will be put back into the parameter values of the dialogstate.

This mechanism allows the function to be called with different parameters as needed in the dialog. And it allows functions of arbitrary input and output arity. 




The following are available:
||UpdateFunction||description||Additional parameters||
||Set||Directly sets the parameter to a given value. ||value: ParameterValue||
||BlockSubstitute||Substitutes in given value all occurences if [X] where X is a known parameter with the value of parameter X. Unknown parameters are not substituted||value: ParameterValue||
||ValueWithCondition||Sets parameter to given value , iF the condition holds.||value:ParameterValue, condition: Parameters||
||SetBestMatch||sets a parameter to the value that has the best condition||valueconditions: List<ValueWithCondition>||
||SetFirstMatch||set parameter to the first value for which the condition holds, or the "orelse" value if no condition holds||
||SetIfElse||Sets parameter to the vtrue value if the condition holds, else to vfalse value||

Custom functions can be programmed in Java and then used in your json code. Of course make sure that your custom functions are properly attached to the json parser.


== DialogPhase
Each DialogPhase contains a list of UpdateFunctions that are executed in the given order. It allows computation of derived variable values.