io.spokestack.spokestack.dialogue

Class DialogueManager

java.lang.Object

io.spokestack.spokestack.dialogue.DialogueManager

All Implemented Interfaces:

Callback<NLUResult>

public final class DialogueManager
extends Object
implements Callback<NLUResult>

Spokestack's dialogue manager.

This component transforms intent and slot results from an NLUService into actions to be performed by the app, including both scene transitions and external requests for data. A system response to the user's request is also included; it can be synthesized and read to the user or printed in a text stream.

In order to translate between NLU results and dynamic app actions, the manager relies on a dialogue policy. An app may use Spokestack's rule-based policy by providing the path to a JSON file describing the policy's configuration under the "dialogue-policy-file" configuration key, or may use a different/custom policy by passing its class name under the "dialogue-policy-class" key. The class specified by the latter key must contain a single-argument constructor that accepts a SpeechConfig instance.

Dialogue management, like other Spokestack modules, is event-driven. Registered listeners will receive DialogueEvents when the system should make a change based on the user's last request. Events include changes to the app's visual context, prompts to be read or displayed to the user, and actions related to app features that must be executed outside the dialogue manager's control.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DialogueManager.Builder Dialogue manager builder API.

Field Summary

Fields

Modifier and Type	Field and Description
static String	SLOT_PREFIX The prefix used for storing data internal to a dialogue policy in the current data store.

Method Summary

Modifier and Type	Method and Description
void	addListener(DialogueListener listener) Add a new listener to receive events from the dialogue management module.
void	call(NLUResult arg) Call the callback with the specified argument.
void	completeTurn(boolean success) Complete the pending user turn.
String	dump() Dump the dialogue policy's current state to the currently registered data store.
FinalizedPrompt	finalizePrompt(Prompt prompt) Finalize a prompt, interpolating template strings using the current conversation data store.
ConversationData	getDataStore()
NLUResult	getLastTurn() Get the last user turn processed by the dialogue manager.
void	load(String state) Attempt to load a saved policy state from the currently registered data store.
void	onError(Throwable err) Call the callback with an error generated during an asynchronous task.
void	processTurn(NLUResult userTurn) Process a user turn, dispatching dialogue events when system responses are available.
void	removeListener(DialogueListener listener) Remove a dialogue listener, allowing it to be garbage collected.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SLOT_PREFIX

public static final String SLOT_PREFIX

The prefix used for storing data internal to a dialogue policy in the current data store.

See Also:

Constant Field Values

Method Detail

processTurn

public void processTurn(NLUResult userTurn)

Process a user turn, dispatching dialogue events when system responses are available.

Parameters:

userTurn - The user's request as classified by an NLU system.

completeTurn

public void completeTurn(boolean success)

Complete the pending user turn. Some dialogue policies may not require a signal for turn completion; see the documentation for your chosen policy for more information.

Parameters:

success - true if the user's request/desired action was fulfilled successfully; false otherwise.

getLastTurn

public NLUResult getLastTurn()

Get the last user turn processed by the dialogue manager.

Returns:

The last user turn processed by the dialogue manager.

getDataStore

public ConversationData getDataStore()

Returns:

The currently registered data store. Useful if no custom data store was supplied at build time but dialogue contents need to be persisted externally.

finalizePrompt

public FinalizedPrompt finalizePrompt(Prompt prompt)

Finalize a prompt, interpolating template strings using the current conversation data store.

Parameters:

prompt - The prompt to be finalized.

Returns:

The finalized prompt.

dump

public String dump()

Dump the dialogue policy's current state to the currently registered data store. This can be used in conjunction with load() to resume a dialogue in progress in the next app session.

Note that, depending on an app's requirements, truly resuming a session in progress may involve persisting and restoring the entire contents of the registered ConversationData instance, as the dialogue might be relying on data stored there as a result of actions it has instructed the app to perform or data expected by prompts and stored explicitly by the app, etc.

Returns:

The serialized state that was dumped to the data store.

load

public void load(String state)
          throws Exception

Attempt to load a saved policy state from the currently registered data store. Assumes that the registered data store contains data stored by calling dump() with the same policy as is currently in use.

Parameters:

state - A serialized conversation state from a previous conversation.

Throws:

Exception - if there is an error loading saved state.

call

public void call(@NonNull
                 NLUResult arg)

Description copied from interface: Callback

Call the callback with the specified argument.

Specified by:

call in interface Callback<NLUResult>

Parameters:

arg - The callback's argument.

onError

public void onError(@NonNull
                    Throwable err)

Description copied from interface: Callback

Call the callback with an error generated during an asynchronous task.

Specified by:

onError in interface Callback<NLUResult>

Parameters:

err - An error generated instead of the callback's intended result.

addListener

public void addListener(DialogueListener listener)

Add a new listener to receive events from the dialogue management module.

Parameters:

listener - The listener to add.

removeListener

public void removeListener(DialogueListener listener)

Remove a dialogue listener, allowing it to be garbage collected.

Parameters:

listener - The listener to remove.