Service Connector Interface¶
Connectors allow Intents Agent definitions to operate with real cloud services
such as Dialogflow, Lex or Azure Bot Services. Currently, only one connector is
provided with this library, and this is for Dialogflow ES:
intents.connectors.dialogflow_es.connector
.
Note
Details about the Connector interface are only useful if you need to develop your own Service Connector (please consider raising a pull request if this is the case). If you just need to use the included Dialogflow Connector you can jump to its documentation page right away: intents.connectors.dialogflow_es.connector
Connectors are used to operate with the cloud version of the Agent, and specifically to:
Export an
intents.Agent
in a format that is natively readable by the ServicePredict User messages on the Cloud Agent
Trigger Intents on the Cloud Agent
More details can be found in the Connector
interface.
-
class
Connector
(agent_cls, default_session=None, default_language='en')[source]¶ Connect the given Agent to a Prediction Service.
- Parameters
agent_cls (
_AgentMetaclass
) – The Agent to connectdefault_session (
Optional
[str
]) – A default session ID (conversation channel) for predictionsdefault_language (
str
) – A default language for predictions
-
abstract property
entity_mappings
¶ A Service Connector must know the Entity Mappings of its Prediction Service. They will be used to lookup entity names during export.
- Return type
-
abstract
export
(destination)[source]¶ Export the connected Agent in a format that can be read and imported natively by the Prediction service. For instance, the Dialogflow service will produce a ZIP export that can be imported from the Dialogflow console.
Note that you can also directly upload the Agent with
upload()
.- Parameters
destination (
str
) – destination path of the exported Agent
-
abstract
predict
(message, session=None, language=None)[source]¶ Predict the given User message in the given session using the given language. When session or language are None, predict will use the default values that are specified in
__init__()
.predict will return an instance of
Prediction
, representing the service response.>>> from intents.connectors import DialogflowEsConnector >>> from example_agent import ExampleAgent >>> df = DialogflowEsConnector('/path/to/service-account.json', ExampleAgent) >>> prediction = df.predict("Hi, my name is Guido") >>> prediction.intent UserNameGive(user_name='Guido') >>> prediction.intent.user_name "Guido" >>> prediction.fulfillment_text "Hi Guido, I'm Bot" >>> prediction.confidence 0.86
- Parameters
message (
str
) – The User message to predictsession (
Optional
[str
]) – Any string identifying a conversationlanguage (
Optional
[str
]) – A ISO 639-1 language code (e.g. “en”)
- Return type
-
abstract
trigger
(intent, session=None, language=None)[source]¶ Trigger the given Intent in the given session using the given language. When session or language are None, predict will use the default values that are specified in
__init__()
.>>> from intents.connectors import DialogflowEsConnector >>> from example_agent import ExampleAgent, smalltalk >>> df = DialogflowEsConnector('/path/to/service-account.json', ExampleAgent) >>> prediction = df.trigger(smalltalk.AgentNameGive(agent_name='Alice')) >>> prediction.intent AgentNameGive(agent_name='Alice') >>> prediction.fulfillment_text "Howdy Human, I'm Alice" >>> prediction.confidence 1.0
- Parameters
intent (
Intent
) – The Intent instance to triggersession (
Optional
[str
]) – Any string identifying a conversationlanguage (
Optional
[str
]) – A ISO 639-1 language code (e.g. “en”)
- Return type
-
class
EntityMapping
[source]¶ An Entity Mapping is a (de-)serializer for predicted Entities.
Most of the times a Mapping is not needed as the Entity can be mapped directly to its type (e.g. “3” -> Number(3)). However, prediction services such as Dialogflow may define system entities of structured types; a notable example is Dialogflow’s sys.person entity, which is returned as {“name”: “John”} and therefore needs custom logic to be mapped to Person(“John”). This is modelled in
intents.connectors.dialogflow_es.entities.PersonEntityMapping
.Another notable scenario is Date/Time objects. A mapping can be used to convert time strings from the Service format to python objects. For Dialogflow ES, this is modelled in
intents.connectors.dialogflow_es.entities.DateTimeEntityMapping
.-
abstract property
entity_cls
¶ This is the internal entity type that is being mapped.
>>> mapping = StringEntityMapping(Sys.Integer, 'sys.number-integer') >>> mapping.entity_cls Sys.Integer
- Return type
_EntityMetaclass
-
abstract
from_service
(service_data)[source]¶ De-serialize the Service representation of an Entity (typically the value that is returned at prediction time) to an instance of one of the internal Entity classes in
intents.model.entities
>>> date_mapping.from_service("2021-07-11") Sys.Date(2021, 7, 11)
- Parameters
service_data (
Any
) – A parameter value, as it is returned by the Service in a prediction/trigger response- Return type
- Returns
the parameter value, modelled as one of the System Entity classes
-
abstract property
service_name
¶ This is the name of the Entity in the Prediction Service domain.
>>> mapping = StringEntityMapping(Sys.Integer, 'sys.number-integer') >>> mapping.service_name 'sys.number-integer'
- Return type
str
-
abstract
to_service
(entity)[source]¶ Serialize a System Entity instance into a Service representation (typically, to be sent as a parameter of a trigger request)
>>> date_mapping.to_service(Sys.Date(2021, 7, 11)) "2021-07-11"
- Parameters
entity (
SystemEntityMixin
) – The System Entity to serialize- Return type
Any
- Returns
The serialized Entity that can be sent to Service (e.g. in a trigger request)
-
abstract property
-
class
Prediction
(intent, confidence, fulfillment_message_dict, fulfillment_text=None)[source]¶ One of the core uses of Service Connectors is to predict user utterances, or programmatically trigger intents. This class models the result of such predictions and triggers.
You will typically obtain Prediction objects from
Connector
methodspredict()
andtrigger()
.- Parameters
intent (
Intent
) – An instance of the predicted Intentconfidence (
float
) – A confidence value on the service predictionfulfillment_message_dict (
Dict
[IntentResponseGroup
,List
[IntentResponse
]]) – A map of Intent Responses, as they were returned by the Service. Consider usingPrediction.fulfillment_messages()
for conveniencefulfillment_text (
Optional
[str
]) – A plain-text version of the response
-
fulfillment_messages
(response_group=<IntentResponseGroup.RICH: 'rich'>)[source]¶ Return a list of fulfillment messages that are suitable for the given Response Group. The following scenarios may happen:
language.IntentResponseGroup.DEFAULT
is requested -> Message in the DEFAULT group will be returnedlanguage.IntentResponseGroup.RICH
is requestedRICH messages are defined -> RICH messages are returned
No RICH message is defined -> DEFAULT messages are returned
If present, messages in the “rich” group will be returned:
>>> prediction.fulfillment_messages() [TextIntentResponse(choices=['I like travelling too! How can I help?']), QuickRepliesIntentResponse(replies=['Recommend a hotel', 'Send holiday photo', 'Where the station?'])]
Alternatively, I can ask for plain-text default messages:
>>> from intents.language import IntentResponseGroup >>> prediction.fulfillment_messages(IntentResponseGroup.DEFAULT) [TextIntentResponse(choices=['Nice, I can send you holiday pictures, or recommend an hotel'])]
- Parameters
response_group (
IntentResponseGroup
) – The Response Group to fetch responses for- Return type
List
[IntentResponse
]
-
class
ServiceEntityMappings
[source]¶ Models a list of entity mappings, in the form of a dict where the key is a System entity class (inherits from
SystemEntityMixin
) and the value is aEntityMapping
. In addition to a standard dict, these features are added:Instantiate from a list of mappings with
from_list()
Consistency check: a mapping list must cover all the entities defined in the framework (TODO)
Shortcut to define StringEntityMappings like (Sys.Integer, ‘sys.number-integer’) (TODO)
-
class
StringEntityMapping
(entity_cls, service_name)[source]¶ This is a basic
EntityMapping
that reads values as they are sent by the prediction service (e.g. “3” -> Sys.Integer(“3”)), and serializes by simple string conversion (e.g. Sys.Integer(3) -> “3”).The System Entity to use must be defined when instantiating the mapping, for instance:
>>> StringEntityMapping(Sys.Integer, "sys.number-integer")
- Parameters
entity_cls (
_EntityMetaclass
) –service_name (
str
) –
-
from_service
(service_data)[source]¶ De-serialize the Service representation of an Entity (typically the value that is returned at prediction time) to an instance of one of the internal Entity classes in
intents.model.entities
>>> date_mapping.from_service("2021-07-11") Sys.Date(2021, 7, 11)
- Parameters
service_data (
Any
) – A parameter value, as it is returned by the Service in a prediction/trigger response- Return type
- Returns
the parameter value, modelled as one of the System Entity classes
-
to_service
(entity)[source]¶ Serialize a System Entity instance into a Service representation (typically, to be sent as a parameter of a trigger request)
>>> date_mapping.to_service(Sys.Date(2021, 7, 11)) "2021-07-11"
- Parameters
entity (
SystemEntityMixin
) – The System Entity to serialize- Return type
Any
- Returns
The serialized Entity that can be sent to Service (e.g. in a trigger request)
-
deserialize_intent_parameters
(service_parameters, intent_cls, mappings)[source]¶ Cast parameters from Service format to Intents format according to the given schema. Typically this happens when a Connector has to turn prediction parameters into Intents entities.
- Parameters
service_parameters (
Dict
[str
,Any
]) – The parameters dict, as it is returned by a Prediction Serviceintent_cls (
_IntentMetaclass
) – The Intent parameters will be matched againstmappings (
ServiceEntityMappings
) – The Service Entity Mappings, to deserialize parameter values
- Return type
Dict
[str
,EntityMixin
]