Dialog Manager

this page describes dialogmanager 2.0.0. Use the History button above to check older documentation

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

It can be seen as a sort of program. The basic syntax is json, the higher level syntax is defined by the DialogSpecification and its contents. The advantage of the dialogmanager over a straight program is that everything is json-serializable, allowing the program itself plus the current execution state to be put into a file for storage, archivation, inspection and later continuation. It also helps to separate the dialog specification from dialog presentation, flow handling and to decouple it from all kind of client-server considerations. It makes the whole dialog testable. There is never any native code in this "program", only json, thus avoiding any security issues.

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 ​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 DialogPhases.

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 UpdateFunctions 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 UpdateFunctions, 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.

Note that this does not define exactly HOW the user is going to give the answer. There may be a text prompt, a set of buttons, a touch screen, a web browser, a text to speech/speech to text system at the other end handling the cases. The dialogmanager does not care about the presentation. As long as "something" fills in the parameters as needed.

UpdateFunction

An UpdateFunction is a "function call" that manipulates the parameters.

An UpdateFunction is can be called from the preparation or evaliation part of the DialogPhase.

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 val1... provided here are the CONSTRUCTOR arguments for NameOfFunction. Typically these are names of parameters.

But the update function can also contain other elements, eg a Condition object or list of Conditions. In the end the json layout is specified in by the implementation of the update function.

Technically, the function call(Parameters parameters) is called to evaluate the function, and that call updates the Parameters. 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.

The following are available in the library:

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

Condition

A number of UpdateFunctions contain a condition. There are a number of variants. The return value here is what is returned from getTruth(params). 1 if condition totally holds, 0 if condition is completely false,and somewhere in between when condition is partially true, eg when the values are close to expected.

And	returns product of all argument truth values	condition: list if Condition
Or	returns 1-((1-truth of c1) * (1-truth of c2)...) where c1... are the contained conditions	condition: list if Condition
Not	returns 1-the truth value of the contained condition	condition: one Condition
ContainsWord	returns 1 if the word is contained.	parameter: the parameter name, value:the {@link ParameterValue} to compare with, tolerance: the tolerance to weigh with.
Equal	returns (1-distance to the given value )/ tolerance.	parameter, value, tolerance
Less	returns 1 if the parameter value is less than given value, else 0.	parameter name (string), value (ParameterValue)
Maybe	returns the given value	value: number in [0,1]

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.