Examples

Examples

This document shows a basic example as currently is found on the main branch (but its location is subject to change).

ExampleManagers

An example managers project that shows all the basic features used by the MMDS. It is based off a dialogue management system from the ARIA-VALUSPA project as developed at University of Nottingham by Andry Chowanda and Manon Plagnol.

Overview

To use FlipperMMDS you can used the pre-compiled sources and the run.bat file (no Linux run.sh available yet). The binary and its sources can be found here.

By default this will load all managers defined in the config/ folder. Also make sure all custom managers are put into modules/ and their (non-Flipper and non-FlipperMMDS) dependencies in modules/lib. Additional recommended folders are 'data/' and 'templates/' for storing data files and Flipper templates respectively.

The (slightly modified) configuration as found in v.0.0.1 can be found below, with additional comments. References are made to a Manager implementation, to explain the relation of the XML and the actual code that is being executed.

<managers>
	<manager id="001" name="IntentManager" interval="50">

Each manager has an interval. This is the interval in milliseconds at which all the manager's Flipper templates are processed and its process() function is called. The id is a unique required string, name is an optional non-unique descriptive name for the manager entry.

		<class classname="eu.aria.dialogue.managers.IntentManager">

The class element is an optional element that should be used for custom manager implementations. (implementing Manager or most often, extending DefaultManager). Provide the classname and make sure the .jar containing its definition is added to the modules/ folder and its dependencies in the modules\lib folder.

			<parameter name="rules_path" path="true" value="../data/rules.xml"/>
			<parameter name="stopwords_path" path="true" value="../data/stopwords.txt"/>
			<parameter name="synonyms_path" path="true" value="../data/synonyms.txt"/>
			<parameter name="pos_model_path" path="true" value="../data/english-left3words-distsim.tagger"/>
			<parameter name="user_utterance_is_path" value="$userstates.utterance"/>
			<parameterarray name="example_parameterarray"> 
				<item value="risotto"/>
				<item value="pizza"/>
				<item path="true" value="../relative/path/example"/>
			</parameterarray>

Each class can receive several parameters. They are used as "name"/"value" pairs. An additional optional path="true" (default false) can be given to resolve paths relative to the file.

Additionally parameterarray can be used to give an array or values. Again, this supports the path="true" option for relative paths.

The setParams() function found in Manager and DefaultManager will be called with the defined parameters and arrays.

		</class>
	</manager>

	<manager id="002" name="BehaviourGenerator" interval="100">
		<templates>
			<template path="../templates/responses.xml" />		
		</templates>

Templates define one or several Flipper templates that this manager will run on the defined interval basis. This is an easy way to provide functionality without creating a custom Manager implementation (and declaring it in a class element)

		<behaviours>
			<behaviour classname="eu.aria.dialogue.behaviours.BehaviourToGui" />
                </behaviours>

Behaviours are referenced by the previously mentioned Flipper templates. For FlipperMMDS they should implement the ManagableBehaviourClass interface. Flipper Behaviours are used to generate behaviour to be displayed by the agent. Like templates you can have several of these. You should put them in the modules/ folder.

	</manager>

	<manager id="003" name="GuiManager" interval="50">
		<class classname="eu.aria.dialogue.managers.GuiManager">
		</class>
		<templates>
			<template path="../templates/fake_example.xml" />		
		</templates>
		<functions>
			<function classname="example.fake.ExampleFunctions" />		
			<function classname="example.fake.ExampleFunctionsContinued" />		
		</functions>

Similar to the Behaviours, Functions referenced in the Flipper templates should be specified as well. It should implement the ManagableFunction interface. Again the modules/ folder is perfect for its jars.

	</manager>

	<manager id="004" name="IS Inspector" interval="1000">
		<class classname="eu.aria.dialogue.managers.utils.ISInspector">
		</class>
		<informationstate>
			<state name="$my.state" value="exampleValue" override="true"/>
		</informationstate>

You are able to set some states in the information state (IS). If this value already exists in the IS it is not overridden unless override=true is set.

	</manager>
</managers>

Example Modules

Intent Manager

The Intent Manager converts spoken text into a user intent.

In short (we are not too going to deep into the implementation of its functionality), it finds keywords in a sentence, and maps this to a user intent. (This intent is later used by another Manager decide on an agent response.)

GUI Manager

The Gui Manager creates a GUI that allows the user to type text and change emotions using sliders. It instantiates a GUI using a Singleton pattern. This allows the Behaviour Generator to retrieve the same GUI and show agent's textual responses on it.

Behaviour Generator

The Behaviour Generator implements the ManagableBehaviourClass to send agent behaviours to the GUI (Behaviour to GUI). This is done following Flipper templates which call the behaviour as defined in its class.

Information State Inspector

The IS Inspector shows the current IS on a GUI screen. This can be used for debugging your system.

This is implemented using a Singleton pattern (making sure only one instance of the GUI exists), making it very similar in its implementation to the GUI Manager. Therefore it will not be discussed further here.

Custom Manager Implementation

Below a skeleton of the IntentManager implementation can be found. This should explain several references made earlier on this page to functions and other functionality.

 public class IntentManager extends DefaultManager {
       
    public IntentManager(DefaultRecord is) {
        super(is);
        interval = 50; //fast default interval
    }
    
    @Override
    public void setParams(Map<String, String> params, Map<String, String[]> paramList){
        // This function is called during startup. This can be used to set some settings in the Manager.
    }    
    
    
    @Override
    public void process() {
        super.process();   //super.process() updates the time and running the Flipper Templates.
        // This function is called every 50 ms by default, or what was defined in the config file
    }
 }

Custom Function Implementation

A function should implement a ManagableFunction with the Manager getManager() and setManager(Manager manager) functions. This allows the function to retrieve (and alter) some Manager settings (such as the IS and interval).

Custom Behaviour Implementation

A function should implement a ManagableBehaviourClass with the Manager getManager() and setManager(Manager manager) functions. This allows the behaviour class to retrieve (and alter) some Manager settings (such as the IS and interval).