.. _dialog_manager:

Dialog Manager (DM)
===================

The dialog manager `Pamini`_ provides a generalized description of human-agent 
interaction  structure. It needs events, e.g. speech recognition results, to decide 
how the agent should (re-)act and can deal with asynchronous events of the agent 
internal processes which can evoke specific dialog actions. At present we have 
one dialog flow configuration for each interaction island (``/citec/csra/home/kitchen/assistance`` , 
``/citec/csra/home/hallway/entrance``).

Related resources
-----------------

Component repository:
 - Browse component repository: `dialogflow <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/dialogflow/>`_.
 - ``git clone https://projects.cit-ec.uni-bielefeld.de/git/dialogflow.git/``

System startup:
 - The dialog flow can be found in ``lsp-csra-supplementary.sh`` on the ``default`` tab.
 - The component script is called ``component_dialogflow``

Related projects:
 - Browse repository `system-startup <https://projects.cit-ec.uni-bielefeld.de/projects/lsp-csra/repository/system-startup>`_.
 - Browse project `Pamini`_.

.. _Pamini: https://projects.cit-ec.uni-bielefeld.de/projects/agaispeechprocessing/repository/pamini

Interfaces
----------

Different dialog tasks (interaction pattern) can be invoked by sending 
task states to ``<location>/dialogtasks/<pattern_name>`` scopes, e.g. 
``rgreeting`` triggers a welcome initiated by the robot. 

======================================================= ======================================= 
Scope (Listener)                                        Type                                    
======================================================= ======================================= 
``<location>/dialogtasks/<pattern_name>``               `Task State`_
``<location>/pamini/action``                            `Dialog Manager Command`_        
``<location>/dialogact``                                `Dialog Act`_                                                   
======================================================= =======================================

The dialog manager gives feedback about the current state of requested dialog 
task via task states and informs about state changes of an active interaction 
pattern. Additionally the DM can also request a lot of system routines/scenarios
or can trigger system actions like say tasks directly.

======================================================= ========================================
Scope (Informer)                                        Type       
======================================================= ========================================
``<location>/dialogtasks/<pattern_name>``               `Task State`_
``<location>/pamini/patternstatus``                     `State Change`_
``<location>/state/request/<system_routines>``          `Task State`_
``<location>/saytask``                                  `Task State`_
======================================================= ========================================



.. _Task State: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-communicationpatterns.html#rst.communicationpatterns.TaskState
.. _String: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html?highlight=string#rst.generic.Value.string
.. _Dialog Manager Command: http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-dialog.html#rst.dialog.DialogManagerCommand
.. _Dialog Act: http://docs.cor-lab.de//rst-manual/trunk/html/generated/sandbox/package-rst-dialog.html#message-dialogact
.. _State Change: http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-statemachine.html#rst.statemachine.StateChange



.. _interaction_pattern_visualization:

Interaction pattern visualization
---------------------------------

The dialog manager provides a simple visualization of all configured interaction 
pattern instances including the corresponding rsb scops (if available).


.. figure:: /images/software/paminiGUI.png
  :figclass: align-center
  
It is possible to turn on the visualization on startup via the corresponding dialogflow
configuration:

  
.. code-block:: xml
   
   <PaminiProperty name="visualization" value="true" />


To start the visualization separately, you have to change the PaminiProperty of the visualizaiton to ``"false"`` and run the PatternVisualization in *pamini.visualization*.


If the visualization is started, it's send a 'PING' as a String on scope ``/pamini/patterninformer/request``. 
The Informer send on scope ``/pamini/patterninformer/info`` the information about the registered dialog tasks (interaction pattern) to the visualization. A interaction pattern is send as a `Dictionary <http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html#rst.generic.Dictionary>`_ and consists of `Key-Value-Pairs <http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html#rst.generic.KeyValuePair>`_. A Key-Value-pair consists of a key, e.g. ``Pattern Name`` and the correspondig value, e.g. ``h_Greeting``.


============================  ============
Scope (Listener)               Type
============================  ============
/pamini/patterninformer/info    `Dictionary <http://docs.cor-lab.de//rst-manual/trunk/html/generated/stable/package-rst-generic.html#rst.generic.Dictionary>`_
============================  ============ 

===============================  ============
Scope (Informer)                    Type
===============================  ============
/pamini/patterninformer/request      String
===============================  ============ 


Examples
--------

Trigger an interaction pattern (robot greeting in the hallway)
###############################################################

.. code-block:: java
   :emphasize-lines: 3
    
    // RSB Informer
    Informer<TaskStateType.TaskState> informer = Factory.getInstance().
        createInformer("/citec/csra/home/hallway/entrance/dialogtasks/rgreeting");
    informer.activate();
    
    // create a task state   
    TaskStateType.TaskState.Builder taskBuilder = TaskStateType.TaskState.newBuilder();
    taskBuilder.setOrigin(TaskStateType.TaskState.Origin.SUBMITTER);
    taskBuilder.setState(TaskStateType.TaskState.State.INITIATED);
    taskBuilder.setSerial(1);
    taskBuilder.setPayload(ByteString.EMPTY);
    taskBuilder.setWireSchema(ByteString.copyFromUtf8("utf-8-string"));
    
    // send the task state
    informer.send(taskBuilder.build());

Reset dialog (in the kitchen)
#############################

.. code-block:: java
   :emphasize-lines: 3,7,8
    
    // RSB Informer
    Informer<TaskStateType.TaskState> informer = Factory.getInstance().
        createInformer("/citec/csra/home/kitchen/assistance/pamini/action");
    informer.activate();  
    
    // create a dialog manager command 
    DialogMangerCommand.Builder dialogCommand = DialogMangerCommand.newBuilder();
    dialogCommand.setCommand(DialogMangerCommand.Command.RESET_INTERACTION);

    // send command
    informer.send(dialogCommand.build());