public class DialogFlowApi extends IntentRecognitionProvider
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.
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 EntityType s 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 Intent s 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 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 . |
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
Context s 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.
|
getIntent, setPostProcessors, setPreProcessors
public static String PROJECT_ID_KEY
Configuration
key to store the unique identifier of the DialogFlow project.DialogFlowApi(XatkitCore, Configuration)
public static String LANGUAGE_CODE_KEY
Configuration
key to store the code of the language processed by DialogFlow.DialogFlowApi(XatkitCore, Configuration)
public static String GOOGLE_CREDENTIALS_PATH_KEY
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.
DialogFlowApi(XatkitCore, Configuration)
public static String DEFAULT_LANGUAGE_CODE
public static String CLEAN_AGENT_ON_STARTUP_KEY
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).
public static String ENABLE_INTENT_LOADING_KEY
Configuration
key to store whether to initialize the registeredIntents
Map
with
the Intent
s 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.
public static String ENABLE_ENTITY_LOADING_KEY
Configuration
key to store whether to initialize the registeredEntityTypes
Map
with the EntityType
s 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.
public static String ENABLE_LOCAL_CONTEXT_MERGE_KEY
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
XatkitSession
s 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 XatkitSession
s may
generate consistency issues and unexpected behaviors (such as unmatched intents and context value overwriting).
public static String CUSTOM_FOLLOWUP_LIFESPAN
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.
public static String CONFIDENCE_THRESHOLD_KEY
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.
public DialogFlowApi(XatkitCore xatkitCore, Configuration configuration)
DialogFlowApi
with the provided configuration
.
This constructor is a placeholder for DialogFlowApi(XatkitCore, Configuration, RecognitionMonitor)
with a null
RecognitionMonitor
.
xatkitCore
- the XatkitCore
instance managing the DialogFlowApi
configuration
- the Configuration
holding the DialogFlow project ID and language codeNullPointerException
- if the provided xatkitCore
, configuration
or one of the
mandatory configuration
value is null
.DialogFlowException
- if the client failed to start a new sessionDialogFlowApi(XatkitCore, Configuration, RecognitionMonitor)
public DialogFlowApi(XatkitCore xatkitCore, Configuration configuration, @Nullable RecognitionMonitor recognitionMonitor)
DialogFlowApi
with the provided configuration
.
The provided configuration
must provide values for the following keys:
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 XatkitSession
s. Disabling this
option for a bot implementation that manipulates local XatkitSession
s may generate consistency issues
and unexpected behaviors (such as unmatched intents and context value overwriting).
xatkitCore
- the XatkitCore
instance managing the DialogFlowApi
configuration
- the Configuration
holding the DialogFlow project ID and language coderecognitionMonitor
- the RecognitionMonitor
instance storing intent matching informationNullPointerException
- if the provided xatkitCore
, configuration
or one of the mandatory
configuration
value is null
.DialogFlowException
- if the client failed to start a new sessionPROJECT_ID_KEY
,
LANGUAGE_CODE_KEY
,
GOOGLE_CREDENTIALS_PATH_KEY
,
ENABLE_INTENT_LOADING_KEY
,
ENABLE_LOCAL_CONTEXT_MERGE_KEY
public String getProjectId()
public String getLanguageCode()
public void registerEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition)
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
EntityDefinition
s 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.
registerEntityDefinition
in class IntentRecognitionProvider
entityDefinition
- the EntityDefinition
to register to the DialogFlow projectDialogFlowException
- if the DialogFlowApi
is shutdown, or if the EntityType
already
exists in the DialogFlow projectIntentRecognitionProvider.trainMLEngine()
public void registerIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition)
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
IntentDefinition
s 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.
registerIntentDefinition
in class IntentRecognitionProvider
intentDefinition
- the IntentDefinition
to register to the DialogFlow projectDialogFlowException
- if the DialogFlowApi
is shutdown, or if the Intent
already exists in
the DialogFlow projectcreateInContextNames(IntentDefinition)
,
createOutContexts(IntentDefinition)
,
createParameters(List)
protected com.google.cloud.dialogflow.v2.Intent.TrainingPhrase createTrainingPhrase(String trainingSentence, List<com.xatkit.intent.Context> outContexts)
Intent.TrainingPhrase
from the provided trainingSentence
and outContexts
.
This method splits the provided trainingSentence
into DialogFlow's
Intent.TrainingPhrase.Part
s.
Intent.TrainingPhrase.Part
s corresponding to output context parameters
are bound to the corresponding DialogFlow entities using the entityMapper
.
trainingSentence
- the IntentDefinition
's training sentence to create a
Intent.TrainingPhrase
fromoutContexts
- the IntentDefinition
's output Context
s
associated to the provided training sentenceIntent.TrainingPhrase
NullPointerException
- if the provided trainingSentence
or outContexts
List
is
null
, or if one of the ContextParameter
's name from the provided
outContexts
is null
protected List<String> createInContextNames(com.xatkit.intent.IntentDefinition intentDefinition)
Context
names from the provided intentDefinition
.
This method iterates the provided intentDefinition
's in Context
s, and
maps them to their concrete DialogFlow String
identifier. The returned String
can be used to
refer to existing DialogFlow's Context
s.
intentDefinition
- the IntentDefinition
to create the DialogFlow input Context
s fromList
of DialogFlow Context
identifiersNullPointerException
- if the provided intentDefinition
is null
IntentDefinition.getInContexts()
protected List<com.google.cloud.dialogflow.v2.Context> createOutContexts(com.xatkit.intent.IntentDefinition intentDefinition)
Context
s from the provided intentDefinition
.
This method iterates the provided intentDefinition
's out Context
s, and
maps them to their concrete DialogFlow implementations.
intentDefinition
- the IntentDefinition
to create the DialogFlow output Context
s fromList
of DialogFlow Context
sNullPointerException
- if the provided intentDefinition
is null
EventDefinition.getOutContexts()
protected List<com.google.cloud.dialogflow.v2.Intent.Parameter> createParameters(List<com.xatkit.intent.Context> contexts)
contexts
.
This method iterates the provided Context
s, and maps their contained
parameter's entities to their concrete DialogFlow implementation.
contexts
- the List
of Xatkit Context
s to create the parameters
fromList
of DialogFlow context parametersNullPointerException
- if the provided contexts
List
is null
, or if one of the
provided ContextParameter
's name is null
public void deleteEntityDefinition(com.xatkit.intent.EntityDefinition entityDefinition)
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
EntityDefinition
s have been deleted from the underlying intent recognition provider use
IntentRecognitionProvider.trainMLEngine()
to train the ML engine.
deleteEntityDefinition
in class IntentRecognitionProvider
entityDefinition
- the EntityDefinition
to delete from the underlying intent recognition providerDialogFlowException
- if the DialogFlowApi
is shutdownIntentRecognitionProvider.trainMLEngine()
public void deleteIntentDefinition(com.xatkit.intent.IntentDefinition intentDefinition)
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
IntentDefinition
s have been deleted from the underlying intent recognition provider use
IntentRecognitionProvider.trainMLEngine()
to train the ML engine.
deleteIntentDefinition
in class IntentRecognitionProvider
intentDefinition
- the IntentDefinition
to delete from the underlying intent recognition providerDialogFlowException
- if the DialogFlowApi
is shutdownIntentRecognitionProvider.trainMLEngine()
public void trainMLEngine()
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.
trainMLEngine
in class IntentRecognitionProvider
DialogFlowException
- if the DialogFlowApi
is shutdownpublic XatkitSession createSession(String sessionId)
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)
.
createSession
in class IntentRecognitionProvider
sessionId
- the identifier to create a session fromXatkitSession
for the provided sessionId
DialogFlowException
- if the DialogFlowApi
is shutdownpublic void mergeLocalSessionInDialogFlow(DialogFlowSession dialogFlowSession)
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.
dialogFlowSession
- the local DialogFlowSession
to merge in the remote oneXatkitException
- if at least one of the local context values' type is not supportedNullPointerException
- if the provided dialogFlowSession
is null
IntentRecognitionProvider.getIntent(String, XatkitSession)
public com.xatkit.intent.RecognizedIntent getIntentInternal(String input, XatkitSession session)
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)
.
RecognizedIntent
s 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.
getIntentInternal
in class IntentRecognitionProvider
input
- the textual input to process and extract the intent fromsession
- the XatkitSession
used to access context informationRecognizedIntent
extracted from the provided input
and session
NullPointerException
- if the provided input
or session
is null
IllegalArgumentException
- if the provided input
is emptyDialogFlowException
- if the DialogFlowApi
is shutdown or if an exception is thrown by the
underlying DialogFlow engineENABLE_LOCAL_CONTEXT_MERGE_KEY
protected String convertParameterValueToString(com.google.protobuf.Value value)
value
into a String
.
This method converts protobuf's Value
s returned by DialogFlow into String
s that can be
assigned to ContextParameterValue
s.
value
- the protobuf Value
to convertString
representation of the provided value
.public void shutdown()
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.
shutdown
in class IntentRecognitionProvider
@Nullable public RecognitionMonitor getRecognitionMonitor()
RecognitionMonitor
associated to this intent recognition provider.getRecognitionMonitor
in class IntentRecognitionProvider
RecognitionMonitor
, or null
if analytics monitoring is disabled.public boolean isShutdown()
isShutdown
in class IntentRecognitionProvider
true
if the intent recognition provider client is shutdown, false
otherwiseCopyright © 2020 SOM Research Lab. All rights reserved.