com.xatkit.core.recognition.dialogflow

Class DialogFlowApi

java.lang.Object

com.xatkit.core.recognition.IntentRecognitionProvider

com.xatkit.core.recognition.dialogflow.DialogFlowApi

public class DialogFlowApi
extends IntentRecognitionProvider

A concrete wrapper for the DialogFlow API client.

This class is used to easily setup a connection to a given DialogFlow agent. Note that in addition to the constructor parameters, the DialogFlow projectId (see PROJECT_ID_KEY), language code (see LANGUAGE_CODE_KEY), and the location of the DialogFlow project's key file ((see GOOGLE_CREDENTIALS_PATH_KEY) should be provided in the constructor's Configuration. The DialogFlow project's key file location can also be provided in the GOOGLE_APPLICATION_CREDENTIALS environment variable. See DialogFlow documentation for further information.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLEAN_AGENT_ON_STARTUP_KEY The Configuration key to store whether to clean the registeredIntents and registeredEntityTypes when initializing the DialogFlowApi.
static String	CONFIDENCE_THRESHOLD_KEY The Configuration key to store the DialogFlow confidence threshold.
static String	CUSTOM_FOLLOWUP_LIFESPAN The Configuration key to store the lifespan value to use when creating followup intents.
static String	DEFAULT_LANGUAGE_CODE The default language processed by DialogFlow.
static String	ENABLE_ENTITY_LOADING_KEY The Configuration key to store whether to initialize the registeredEntityTypes Map with the EntityTypes already stored in the DialogFlow project.
static String	ENABLE_INTENT_LOADING_KEY The Configuration key to store whether to initialize the registeredIntents Map with the Intents already stored in the DialogFlow project.
static String	ENABLE_LOCAL_CONTEXT_MERGE_KEY The Configuration key to store whether to merge the local XatkitSession in the DialogFlow one.
static String	GOOGLE_CREDENTIALS_PATH_KEY The Configuration key to store the path of the JSON credential file for DialogFlow.
static String	LANGUAGE_CODE_KEY The Configuration key to store the code of the language processed by DialogFlow.
static String	PROJECT_ID_KEY The Configuration key to store the unique identifier of the DialogFlow project.

Constructor Summary

Constructors

Constructor and Description
DialogFlowApi(XatkitCore xatkitCore, Configuration configuration) Constructs a DialogFlowApi with the provided configuration.
DialogFlowApi(XatkitCore xatkitCore, Configuration configuration, RecognitionMonitor recognitionMonitor) Constructs a DialogFlowApi with the provided configuration.

Method Summary

Modifier and Type	Method and Description
protected String	convertParameterValueToString(com.google.protobuf.Value value) Converts the provided value into a String.
protected List<String>	createInContextNames(com.xatkit.intent.IntentDefinition intentDefinition) Creates the DialogFlow input Context names from the provided intentDefinition.
protected List<com.google.cloud.dialogflow.v2.Context>	createOutContexts(com.xatkit.intent.IntentDefinition intentDefinition) Creates the DialogFlow output Contexts from the provided intentDefinition.
protected List<com.google.cloud.dialogflow.v2.Intent.Parameter>	createParameters(List<com.xatkit.intent.Context> contexts) Creates the DialogFlow context parameters from the provided Xatkit contexts.
XatkitSession	createSession(String sessionId) Creates a new XatkitSession from the provided sessionId.
protected com.google.cloud.dialogflow.v2.Intent.TrainingPhrase	createTrainingPhrase(String trainingSentence, List<com.xatkit.intent.Context> outContexts) Creates the DialogFlow's Intent.TrainingPhrase from the provided trainingSentence and outContexts.
void	deleteEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition) Deletes the provided entityDefinition from the underlying intent recognition provider.
void	deleteIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition) Deletes the provided intentDefinition from the underlying intent recognition provider.
protected void	finalize() Closes the DialogFlow session if it is not shutdown yet.
com.xatkit.intent.RecognizedIntent	getIntentInternal(String input, XatkitSession session) Returns the raw RecognizedIntent extracted from the provided input.
String	getLanguageCode() Returns the code of the language processed by DialogFlow.
String	getProjectId() Returns the DialogFlow project unique identifier.
RecognitionMonitor	getRecognitionMonitor() Returns the RecognitionMonitor associated to this intent recognition provider.
boolean	isShutdown() Returns whether the intent recognition provider client is shutdown.
void	mergeLocalSessionInDialogFlow(DialogFlowSession dialogFlowSession) Merges the local DialogFlowSession in the remote DialogFlow API one.
void	registerEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition) Registers the provided entityDefinition in the underlying intent recognition provider.
void	registerIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition) Registers the provided intentDefinition in the underlying intent recognition provider.
void	shutdown() Shuts down the intent recognition provider client and invalidates the remaining sessions.
void	trainMLEngine() Trains the underlying intent recognition provider.

Methods inherited from class com.xatkit.core.recognition.IntentRecognitionProvider

getIntent, setPostProcessors, setPreProcessors

Methods inherited from class java.lang.Object

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

Field Detail

PROJECT_ID_KEY

public static String PROJECT_ID_KEY

The Configuration key to store the unique identifier of the DialogFlow project.

See Also:

DialogFlowApi(XatkitCore, Configuration)

LANGUAGE_CODE_KEY

public static String LANGUAGE_CODE_KEY

The Configuration key to store the code of the language processed by DialogFlow.

See Also:

DialogFlowApi(XatkitCore, Configuration)

GOOGLE_CREDENTIALS_PATH_KEY

public static String GOOGLE_CREDENTIALS_PATH_KEY

The Configuration key to store the path of the JSON credential file for DialogFlow.

If this key is not set the DialogFlowApi will use the GOOGLE_APPLICATION_CREDENTIALS environment variable to retrieve the credentials file.

See Also:

DialogFlowApi(XatkitCore, Configuration)

DEFAULT_LANGUAGE_CODE

public static String DEFAULT_LANGUAGE_CODE

The default language processed by DialogFlow.

CLEAN_AGENT_ON_STARTUP_KEY

public static String CLEAN_AGENT_ON_STARTUP_KEY

The Configuration key to store whether to clean the registeredIntents and registeredEntityTypes when initializing the DialogFlowApi.

This property is disabled by default. Enabling it allows to easily re-deploy chatbots under development, but complete agent cleaning should not be done on production-ready bots (re-training such bots may take a long time).

ENABLE_INTENT_LOADING_KEY

public static String ENABLE_INTENT_LOADING_KEY

The Configuration key to store whether to initialize the registeredIntents Map with the Intents already stored in the DialogFlow project.

Intent loading is enabled by default, and should not be an issue when using the DialogFlowApi in development context. However, creating multiple instances of the DialogFlowApi (e.g. when running the Xatkit test suite) may throw RESOURCE_EXHAUSTED exceptions. This option can be set to false to avoid Intent loading, limiting the number of queries to the DialogFlow API.

Note that disabling Intent loading may create consistency issues between the DialogFlow agent and the local DialogFlowApi, and is not recommended in development environment.

ENABLE_ENTITY_LOADING_KEY

public static String ENABLE_ENTITY_LOADING_KEY

The Configuration key to store whether to initialize the registeredEntityTypes Map with the EntityTypes already stored in the DialogFlow project.

Entity loading is enabled by default, and should not be an issue when using the DialogFlowApi in development context. However, creating multiple instances of the DialogFlowApi (e.g. when running the Xatkit test suite) may throw RESOURCE_EXHAUSTED exceptions. This option can be set to false to avoid Entity loading, limiting the number of queries to the DialogFlow API.

Note that disabling EntityType loading may create consistency issues between the DialogFlow agent and the local DialogFlowApi, and is not recommended in development environment.

ENABLE_LOCAL_CONTEXT_MERGE_KEY

public static String ENABLE_LOCAL_CONTEXT_MERGE_KEY

The Configuration key to store whether to merge the local XatkitSession in the DialogFlow one.

This option is enabled by default to ensure consistency between the local XatkitSession and the DialogFlow's one. However, bot implementations that strictly rely on the DialogFlow API and do not use local XatkitSessions can disable this option to improve the bot's performances and reduce the number of calls to the remote DialogFlow API.

Note that disabling this option for a bot implementation that manipulates local XatkitSessions may generate consistency issues and unexpected behaviors (such as unmatched intents and context value overwriting).

CUSTOM_FOLLOWUP_LIFESPAN

public static String CUSTOM_FOLLOWUP_LIFESPAN

The Configuration key to store the lifespan value to use when creating followup intents.

This option is set to 2 by default (which corresponds to the DialogFlow default value). Changing it to a higher value allows to match followup intents after multiple inputs. Note that changing it to a smaller value may result in unmatched intents.

CONFIDENCE_THRESHOLD_KEY

public static String CONFIDENCE_THRESHOLD_KEY

The Configuration key to store the DialogFlow confidence threshold.

This threshold is used to accept/reject a matched intent based on its confidence. The default value is 0 (accept all intents).

Note: recognized intents that contain an any entity are never rejected based on the threshold, these entities typically have a low confidence value.

Constructor Detail

DialogFlowApi

public DialogFlowApi(XatkitCore xatkitCore,
                     Configuration configuration)

Constructs a DialogFlowApi with the provided configuration.

This constructor is a placeholder for DialogFlowApi(XatkitCore, Configuration, RecognitionMonitor) with a null RecognitionMonitor.

Parameters:

xatkitCore - the XatkitCore instance managing the DialogFlowApi

configuration - the Configuration holding the DialogFlow project ID and language code

Throws:

NullPointerException - if the provided xatkitCore, configuration or one of the mandatory configuration value is null.

DialogFlowException - if the client failed to start a new session

See Also:

DialogFlowApi(XatkitCore, Configuration, RecognitionMonitor)

DialogFlowApi

public DialogFlowApi(XatkitCore xatkitCore,
                     Configuration configuration,
                     @Nullable
                     RecognitionMonitor recognitionMonitor)

Constructs a DialogFlowApi with the provided configuration.

The provided configuration must provide values for the following keys:

• xatkit.dialogflow.projectId: the unique identifier of the DialogFlow project

The value xatkit.dialogflow.language is not mandatory: if no language code is provided in the Configuration the default one (DEFAULT_LANGUAGE_CODE will be used.

The value xatkit.dialogflow.credentials.path is not mandatory either: if no credential path is provided in the Configuration the DialogFlowApi will use the GOOGLE_APPLICATION_CREDENTIALS environment variable to retrieve the credentials file.

The value xatkit.dialogflow.intent.loading is not mandatory and allows to tune whether the DialogFlowApi should load registered DialogFlow Intent. This option is set to true by default. Disabling it will reduce the number of queries sent to the DialogFlow API, but may generate consistency issues between the DialogFlow agent and the local DialogFlowApi.

The vaule xatkit.dialogflow.context.merge is not mandatory and allows to tune whether the DialogFlowApi should merge the local XatkitSession in the DialogFlow one. This option is set to true by default, and may be set to false to improve the performances of bot implementations that strictly rely on the DialogFlow API, and do not manipulate local XatkitSessions. Disabling this option for a bot implementation that manipulates local XatkitSessions may generate consistency issues and unexpected behaviors (such as unmatched intents and context value overwriting).

Parameters:

xatkitCore - the XatkitCore instance managing the DialogFlowApi

configuration - the Configuration holding the DialogFlow project ID and language code

recognitionMonitor - the RecognitionMonitor instance storing intent matching information

Throws:

NullPointerException - if the provided xatkitCore, configuration or one of the mandatory configuration value is null.

DialogFlowException - if the client failed to start a new session

See Also:

PROJECT_ID_KEY, LANGUAGE_CODE_KEY, GOOGLE_CREDENTIALS_PATH_KEY, ENABLE_INTENT_LOADING_KEY, ENABLE_LOCAL_CONTEXT_MERGE_KEY

Method Detail

getProjectId

public String getProjectId()

Returns the DialogFlow project unique identifier.

Returns:

the DialogFlow project unique identifier

getLanguageCode

public String getLanguageCode()

Returns the code of the language processed by DialogFlow.

Returns:

the code of the language processed by DialogFlow

registerEntityDefinition

public void registerEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition)

Registers the provided entityDefinition in the underlying intent recognition provider.

Note: unless explicitly stated in subclasses, this method does not train the underlying machine learning engine, so multiple entity registrations does not generate multiple training calls. Once all the EntityDefinitions have been registered in the underlying intent recognition provider use IntentRecognitionProvider.trainMLEngine() to train the ML engine.

This method reuses the information contained in the provided EntityDefinition to create a new DialogFlow EntityType and add it to the current project.

Specified by:

registerEntityDefinition in class IntentRecognitionProvider

Parameters:

entityDefinition - the EntityDefinition to register to the DialogFlow project

Throws:

DialogFlowException - if the DialogFlowApi is shutdown, or if the EntityType already exists in the DialogFlow project

See Also:

IntentRecognitionProvider.trainMLEngine()

registerIntentDefinition

public void registerIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition)

Registers the provided intentDefinition in the underlying intent recognition provider.

Note: unless explicitly stated in subclasses, this method does not train the underlying machine learning engine, so multiple intent registrations does not generate multiple training calls. Once all the IntentDefinitions have been registered in the underlying intent recognition provider use IntentRecognitionProvider.trainMLEngine() to train the ML engine.

This method reuses the information contained in the provided IntentDefinition to create a new DialogFlow Intent and add it to the current project.

Specified by:

registerIntentDefinition in class IntentRecognitionProvider

Parameters:

intentDefinition - the IntentDefinition to register to the DialogFlow project

Throws:

DialogFlowException - if the DialogFlowApi is shutdown, or if the Intent already exists in the DialogFlow project

See Also:

createInContextNames(IntentDefinition), createOutContexts(IntentDefinition), createParameters(List)

createTrainingPhrase

protected com.google.cloud.dialogflow.v2.Intent.TrainingPhrase createTrainingPhrase(String trainingSentence,
                                                                                    List<com.xatkit.intent.Context> outContexts)

Creates the DialogFlow's Intent.TrainingPhrase from the provided trainingSentence and outContexts.

This method splits the provided trainingSentence into DialogFlow's Intent.TrainingPhrase.Parts. Intent.TrainingPhrase.Parts corresponding to output context parameters are bound to the corresponding DialogFlow entities using the entityMapper.

Parameters:

trainingSentence - the IntentDefinition's training sentence to create a Intent.TrainingPhrase from

outContexts - the IntentDefinition's output Contexts associated to the provided training sentence

Returns:

the created DialogFlow's Intent.TrainingPhrase

Throws:

NullPointerException - if the provided trainingSentence or outContexts List is null, or if one of the ContextParameter's name from the provided outContexts is null

createInContextNames

protected List<String> createInContextNames(com.xatkit.intent.IntentDefinition intentDefinition)

Creates the DialogFlow input Context names from the provided intentDefinition.

This method iterates the provided intentDefinition's in Contexts, and maps them to their concrete DialogFlow String identifier. The returned String can be used to refer to existing DialogFlow's Contexts.

Parameters:

intentDefinition - the IntentDefinition to create the DialogFlow input Contexts from

Returns:

the created List of DialogFlow Context identifiers

Throws:

NullPointerException - if the provided intentDefinition is null

See Also:

IntentDefinition.getInContexts()

createOutContexts

protected List<com.google.cloud.dialogflow.v2.Context> createOutContexts(com.xatkit.intent.IntentDefinition intentDefinition)

Creates the DialogFlow output Contexts from the provided intentDefinition.

This method iterates the provided intentDefinition's out Contexts, and maps them to their concrete DialogFlow implementations.

Parameters:

intentDefinition - the IntentDefinition to create the DialogFlow output Contexts from

Returns:

the created List of DialogFlow Contexts

Throws:

NullPointerException - if the provided intentDefinition is null

See Also:

EventDefinition.getOutContexts()

createParameters

protected List<com.google.cloud.dialogflow.v2.Intent.Parameter> createParameters(List<com.xatkit.intent.Context> contexts)

Creates the DialogFlow context parameters from the provided Xatkit contexts.

This method iterates the provided Contexts, and maps their contained parameter's entities to their concrete DialogFlow implementation.

Parameters:

contexts - the List of Xatkit Contexts to create the parameters from

Returns:

the List of DialogFlow context parameters

Throws:

NullPointerException - if the provided contexts List is null, or if one of the provided ContextParameter's name is null

deleteEntityDefinition

public void deleteEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition)

Deletes the provided entityDefinition from the underlying intent recognition provider.

Note: unless explicitly stated in subclasses, this method does not train the underlying machine learning engine, so multiple entity deletion does not generate multiple training calls. Once all the EntityDefinitions have been deleted from the underlying intent recognition provider use IntentRecognitionProvider.trainMLEngine() to train the ML engine.

Specified by:

deleteEntityDefinition in class IntentRecognitionProvider

Parameters:

entityDefinition - the EntityDefinition to delete from the underlying intent recognition provider

Throws:

DialogFlowException - if the DialogFlowApi is shutdown

See Also:

IntentRecognitionProvider.trainMLEngine()

deleteIntentDefinition

public void deleteIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition)

Deletes the provided intentDefinition from the underlying intent recognition provider.

Note: unless explicitly stated in subclasses, this method does not train the underlying machine learning engine, so multiple intent deletion does not generate multiple training calls. Once all the IntentDefinitions have been deleted from the underlying intent recognition provider use IntentRecognitionProvider.trainMLEngine() to train the ML engine.

Specified by:

deleteIntentDefinition in class IntentRecognitionProvider

Parameters:

intentDefinition - the IntentDefinition to delete from the underlying intent recognition provider

Throws:

DialogFlowException - if the DialogFlowApi is shutdown

See Also:

IntentRecognitionProvider.trainMLEngine()

trainMLEngine

public void trainMLEngine()

Trains the underlying intent recognition provider.

Note: this method returns once the intent recognition provider's training is complete. However, the propagation of the training information may not be complete when this method returns.

This method checks every second whether the underlying ML Engine has finished its training. Note that this method is blocking as long as the ML Engine training is not terminated, and may not terminate if an issue occurred on the DialogFlow side.

Specified by:

trainMLEngine in class IntentRecognitionProvider

Throws:

DialogFlowException - if the DialogFlowApi is shutdown

createSession

public XatkitSession createSession(String sessionId)

Creates a new XatkitSession from the provided sessionId.

The created session wraps the internal DialogFlow session that is used on the DialogFlow project to retrieve conversation parts from a given user.

The returned XatkitSession is configured by the global Configuration provided in DialogFlowApi(XatkitCore, Configuration).

Specified by:

createSession in class IntentRecognitionProvider

Parameters:

sessionId - the identifier to create a session from

Returns:

a new XatkitSession for the provided sessionId

Throws:

DialogFlowException - if the DialogFlowApi is shutdown

mergeLocalSessionInDialogFlow

public void mergeLocalSessionInDialogFlow(DialogFlowSession dialogFlowSession)

Merges the local DialogFlowSession in the remote DialogFlow API one.

This method ensures that the remote DialogFlow API stays consistent with the local XatkitSession by setting all the local context variables in the remote session. This allows to match intents with input contexts that have been defined locally, such as received events, custom variables, etc.

Local context values that are already defined in the remote DialogFlow API will be overridden by this method.

This method sets all the variables from the local context in a single query in order to reduce the number of calls to the remote DialogFlow API.

Parameters:

dialogFlowSession - the local DialogFlowSession to merge in the remote one

Throws:

XatkitException - if at least one of the local context values' type is not supported

NullPointerException - if the provided dialogFlowSession is null

See Also:

IntentRecognitionProvider.getIntent(String, XatkitSession)

getIntentInternal

public com.xatkit.intent.RecognizedIntent getIntentInternal(String input,
                                                            XatkitSession session)

Returns the raw RecognizedIntent extracted from the provided input.

This method is called after pre-processing of the input (i.e. the given input is already pre-processed), and does not apply any post-processing function (this is done by IntentRecognitionProvider.getIntent(String, XatkitSession)). Subclasses implementing this method should not take care of pre/post processing.

The returned RecognizedIntent is constructed from the raw Intent returned by the DialogFlow API, using the mapping defined in convertDialogFlowIntentToRecognizedIntent(QueryResult). RecognizedIntents are used to wrap the Intents returned by the Intent Recognition APIs and decouple the application from the concrete API used.

If the ENABLE_LOCAL_CONTEXT_MERGE_KEY property is set to true this method will first merge the local XatkitSession in the remote DialogFlow one, in order to ensure that all the local contexts are propagated to the recognition engine.

Specified by:

getIntentInternal in class IntentRecognitionProvider

Parameters:

input - the textual input to process and extract the intent from

session - the XatkitSession used to access context information

Returns:

the RecognizedIntent extracted from the provided input and session

Throws:

NullPointerException - if the provided input or session is null

IllegalArgumentException - if the provided input is empty

DialogFlowException - if the DialogFlowApi is shutdown or if an exception is thrown by the underlying DialogFlow engine

See Also:

ENABLE_LOCAL_CONTEXT_MERGE_KEY

convertParameterValueToString

protected String convertParameterValueToString(com.google.protobuf.Value value)

Converts the provided value into a String.

This method converts protobuf's Values returned by DialogFlow into Strings that can be assigned to ContextParameterValues.

Parameters:

value - the protobuf Value to convert

Returns:

the String representation of the provided value.

shutdown

public void shutdown()

Shuts down the intent recognition provider client and invalidates the remaining sessions.

Note: calling this method invalidates the intent recognition provider client connection, and thus this class cannot be used to access the intent recognition provider anymore.

Specified by:

shutdown in class IntentRecognitionProvider

getRecognitionMonitor

@Nullable
public RecognitionMonitor getRecognitionMonitor()

Returns the RecognitionMonitor associated to this intent recognition provider.

Specified by:

getRecognitionMonitor in class IntentRecognitionProvider

Returns:

the RecognitionMonitor, or null if analytics monitoring is disabled.

isShutdown

public boolean isShutdown()

Returns whether the intent recognition provider client is shutdown.

Specified by:

isShutdown in class IntentRecognitionProvider

Returns:

true if the intent recognition provider client is shutdown, false otherwise

finalize

protected void finalize()

Closes the DialogFlow session if it is not shutdown yet.

Overrides:

finalize in class Object