Galaxy Communicator Documentation:

Turn Management

License / Documentation home / Help and feedback

MIT provides a way of controlling servers using Turn Management, a set of resources which was one of the initial inspirations for the Hub program files. The Galaxy library provides a dispatch function named turn_management which implements this toplevel control. We describe it briefly here. At least part of this documentation will take the form of server documentation, since this is a good deal of the behavior from the programmer's point of view.

Using Turn Management for Dialogue Control

Implement the Server Dialogue Control Functions
Create a Dialogue Control File

Command Line Arguments
Dialogue Control Script
Header File

Initialize Turn Management
Turn Management Message Set

turn_management

As an illustration of how to use Turn Management for dialogue control, we will use the pegasus server, a flight reservations server.

Implement the Server Dialogue Control Functions

Implement the functions to handle the dialogue control. All dialogue control functions are assumed to be of the form:

int function_name (GAL_DOMAIN_SVR *dc);

Valid return values are:

DIALOGUE_CONTINUE
DIALOGUE_STOP
DIALOGUE_RESTART

See below for an explanation of the implications of these return values.

The file containing the functions should be kept in the server directory. A header file, containing dialogue control function prototypes, will be automatically generated at compile time. (See below.)

As an example, pegasus has a function called default_action which handles the undefined case by replying with a "cant_handle" clause.

int default_action(GAL_DOMAIN_SVR *dc)
{
if (!dc->reply_frame)
dc->reply_frame = Gal_MakeFrame("cant_handle", GAL_CLAUSE);
return(DIALOGUE_STOP);
}

See below for an example rule which states the required conditions in order for default_action to be executed.

Another example is the need_destination function. A "need_destination" clause is created for the given topic and then added to the system initiative.

int need_destination(GAL_DOMAIN_SVR *dc)
{ Nframe topic;
topic = Gal_GetFrame(dc->request_frame, ":topic");
dc->reply_frame = Gal_MakeFrame("need_destination", GAL_CLAUSE);
fr_setsprop(dc->reply_frame, ":topic", make_tframe(copy_nframe(topic)));
Gal_AddSystemInitiative(dc, "destination", NULL);
return(DIALOGUE_STOP);
}

See below for an example rule which states the required conditions in order for need_destination to be executed.

Create a Dialogue Control File

The dialogue control file dictates the behavior of the dialogue control. It contains a single script of rules.

The default dialogue control file is assumed to be ../System/<server_name>.dctl. The dialogue control file can also be specified as a command line argument. If no file is specified and the default file does not exist, execution is aborted.

A header file, based on the dialogue control file, is automatically generated at compile time. This header file contains the function prototypes for each operation listed in the dialogue control file. See below for more details.

Command Line Arguments

The dialogue control flow is regulated via the dialogue script which can be provided as a command line argument. If not provided, the dialogue file defaults to "../System/<server_name>.dctl"

static char *oas[] = {
"-dialogue_script name", "script for dialogue control in domain server", NULL, NULL
};

This server also accepts the standard server arguments. See the oa library for details.

Dialogue Control Script

The dialogue control file contains a dialogue control script. The dialogue control script is similar to a Hub program in that it contains a script consisting of a set of rules. Each rule specifies conditions that must be satisfied in order for a given operation to be executed. When turn_management is called, each rule is evaluated, and the subsequent operations are called.

Each operation returns a value which has implications for the flow of control through the script.
Valid return values are:

DIALOGUE_CONTINUE --> resume flow of control immediately after operation was executed
DIALOGUE_STOP --> do not resume flow of control
DIALOGUE_RESTART --> resume flow of control at top of script

A rule in a dialogue control script is similar to a rule in a Hub program except that the RULE: identifier is not used. Otherwise, the syntax is identical:

<alphanumeric expression> --> <operation>
where the alphanumeric expression is ( [!] [X %] <key> [comparison] [<value>] [&] [|])

See the table of Valid Operators for Constructing Rules.

A dialogue control script can also contain comments. Any line beginning with a semicolon is interpreted as a comment.

Examples of Valid Rules

clause help --> give_help

clause

help

give_help

on_time which | departure_time %which | arrival_time %which --> mark_status
; on_time must be equal to which, or departure_time must contain which, or arrival_time must contain which in order for the mark_status operation to be called.

destination & filtered !% to --> filter_to_airport
; If destination exists and filtered does not contain to, then call execute filter_to_airport.

num_found >1 --> speak_multiple
; If num_found is greater than 1, execute speak_multiple.

!sql_query & !destination & !flight_number --> need_destination
; If there is no sql_query and no destination and no flight_number, execute need_destination.

--> default_action
; If no other rule's conditions have been satisfied, execute default_action. In order for this to work as the default, the rule has to be the last rule in the set.

The Header File

The new style for generating header files for dialogue control is described here. The old style is no longer supported. See the upgrade notes.

The new style

In the new style, the user creates a declarations file of this form:

GAL_DIALOGUE_FUNCTION(<op_name>)
GAL_DIALOGUE_FUNCTION(<op_name>)
...

with a GAL_DIALOGUE_FUNCTION declaration for each server dialogue control function. Then the user adds the following header information to exactly one of the server source files:

#define SERVER_FUNCTIONS_INCLUDE "<server_declaration_file_name>"
#include <galaxy/server_functions.h>
#include <domain_svr/domain_svr.h>
#define DIALOGUE_FUNCTIONS_INCLUDE "<dctl_declarations_file_name>"
#include <domain_svr/dialogue_functions.h>

where <server_declaration_file_name> and <dctl_declaration_file_name> are replaced with the appropriate names of the server declarations file and the file created here, respectively., As with the old style of server header generation, the server header file includes the appropriate behavior for the dialogue header file. Note that this new style works in conjunction with the new style of declaring server information; in particular, the GAL_SERVER_SW_PACKAGE() macro is used to incorporate the dialogue control module.

Here is an example of what the MIT pegasus server would look like if it used the new style of headers:

------ pegasus-dialogue.h
GAL_DIALOGUE_FUNCTION(give_help)
GAL_DIALOGUE_FUNCTION(repeat_response)
...
------ pegasus-server.h
GAL_SERVER_NAME(pegasus)
GAL_SERVER_PORT(11100)
GAL_SERVER_OP(turn_management)
GAL_SERVER_SW_PACKAGE(MITDialogue)
------ functions.c
...
#define SERVER_FUNCTIONS_INCLUDE "pegasus-server.h"
#include <galaxy/server_functions.h>
#include <domain_svr/domain_svr.h>
#define DIALOGUE_FUNCTIONS_INCLUDE "pegasus-dialogue.h"
#include <domain_svr/dialogue_functions.h>
...

Initialize Turn Management

In order to use turn management, your domain server must call an initialization function, Gal_DialogueInitServer , provided by the Galaxy library.

void *_GalSS_init_server(GalIO_ServerStruct *server, int argc, char **argv)

{

return(Gal_DialogueInitServer(GalIO_GetServerName(server), argc, argv));

}

void *Gal_DialogueInitServer(char *server_name, int argc, char **argv)
Initializes and returns the server specified by server_name. This function calls Gal_InitTM.

GAL_DOMAIN_SVR *Gal_InitTM(int argc, char **argv)
Initializes the domain server. The dialogue script may be specified by the -dialogue_script argument shown above; otherwise, the dialogue file defaults to "../System/<server_name>.dctl". If no dialogue script is provided and the default file is not found, the function returns a fatal error. This function is called by Gal_DialogueInitServer.

You can also add support for printing out usage information as follows:

void _GalSS_print_usage(int argc, char **argv)
{
Gal_DialoguePrintUsage(argc, argv);
}

void Gal_DialoguePrintUsage(int argc, char **argv)
Prints out usage information for turn management.

Turn Management Message Set

turn_management

turn_management runs the dialogue control tools (via the dialogue control file) and generates a domain-specific response.

parameter type optional depends on description/constraints

IN: :key_value string yes key/value paraphrase of input

:kv_lang string yes key/value paraphrase language; if not present in input, will be set from system's default key-value language, which is "dialogue"

:parse_frame frame parsed input string

:request_frame frame input plus context

:tm_state frame yes previous state of turn manager

OUT: :reply_frame frame will have the form {... :domain <string> :comment_tlist <list> :continuant <frame> :db_tlist <list> ...}

:list yes (no examples)

:map yes (no examples)

:image yes (no examples)

:tm_state frame yes previous dialogue state

:filter_list frame value is {... :Flist <list of strings> :Ftype <string> :Fcategory <string> :Fkey <string> ....}. Describes words which ought to be present in the :parse_frame. Used by a number of servers to provide preferences for choosing among frames.

:discourse_update frame yes frame for context tracking out to add to the discourse history

:system_initiative frame yes query to present to the user

Because many servers utilitize the Turn Management dialogue control capabilities, it is recommended that the dot notation be used for specific servers when the turn_management operation is included in a Hub program rule:

RULE: :request_frame & :key_value & :domain Pegasus --> pegasus.turn_management
RULE: :request_frame & :key_value & :domain Jupiter --> jupiter.turn_management