= 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.0.1</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 containing all processed information given by the user (see below)

This can be saved and later restored to pick up a dialog.


== Parameters
* The user's answers, current dialog state label, and other parameters relevant for the dialog are stored in a set of parameters. This is just a map with keys and values both strings. The keys are called the "variable name" and the values the "variable value". 
* Distance between two parameters is the euclidean distance (sqrt of the sum of squares) of the difference between the two parameter values, on a per-key basis. Only values for which both parameters have the 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. 
* The Keywords parameters 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 minimu distance of any of the words to any of the keywords. Here the Levenshtein distance is used to determine the distance between a word and a keyword.
* 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  DialogPhases. 
* DialogPhase. Each dialog phase represents a situation where we want the user to answer some question. Each has a unique label.  
In each phase, a number of similar questions called DialogOption are available. Also the DialogPhase defines the NestPhase which can determine what is the next DialogPhase to go.
*  A DialogOption is one of multiple ways to proceed in a given {@link DialogPhase}. It consists of a simulation (something presented to the user, eg a question) and the answer type expected from the user (eg, a number between 0 and 10).
* Dialog state. The current state of the dialogL the DialogSpecification, a set of Parameters comprising the culmination of the user's answers so far, and the (randomly) chosen DialogOption for the current Phase. 
* The Evaluation is a list of UpdateFunction s.



* All data structures can be (de)serialized to JSON.
* Various datastructures available to store key elements for dialog management
 * a DialogState represent the entire dialog state plus the entire dialog specification in a single file. Useful to store/recover the entire user state in one single file
 * A DialogSpecification represents all possible dialog phases. Useful to storethe entire dialog tree but without the user's answers so far
 * Parameters that store the user's answers so far
 * The NextPhase mechanism determines the next phase, based on the current parameter settings. The GoToIf selects the phase that has parameters that are smallest distance to the current state ++. The GoTo unconditionally jumps to the given state.  
 * A DialogPhase can have multiple options, from which the one with the smallest distance to the current state++  is chosen.
 * Parameters can be manipulated programmatically, eg to update fields or incorporate data external to the dialog system such as system time, network state, database fields, etc.
 * Parameters can be used directly in the sentences and the available answers 
 * The sentences can contain HTML code.

++picks one at raodom from the list of nearest

== AnswerType
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.