Language Data¶
Language resources are defined separately from Intent
and
Entity
classes. They are stored as plain YAML files in a language/
folder, aside Agent Python modules; this is to be flexible in the relationship
with designers and translators, as well as to allow some degree of automation
when downloading cloud changes back to the local Agent definition (this feature
is currently not implemented).
Your language/ folder will contain one subfloder per language (i.e. language/en/, language/it/, …); each of these will contain
one YAML file per Intent (e.g. my_module.my_intent_class.yaml). Intent language resources are specified in
intents.language.intent_language
one YAML file per entity (e.g. ENTITY_MyEntityClass.yaml). Entity language resources are specified in
intents.language.entity_language
Tip
It may be useful to look at The Example Agent code and language resources (https://github.com/dariowho/intents/tree/master/example_agent/language) to get more insight on the format and naming conventions of language files.
Intents¶
Intent language files have the following structure:
examples:
- an example utterance
- another example utterance
- an example utterance with $foo{42} as a numeric parameter
slot_filling_prompts:
foo:
- Tell me the value for "foo"
responses:
default:
- text:
- A plain text response
- An alternative response
- Another alternative, referencing $foo as a paramneter
rich:
- text:
- A text response for rich clients
- quick_replies:
- a reply chip
- another reply chip
Let’s look at the sections of this file.
examples contain example utterances that will be used to predict the given intent. If your intent has a parameter, it can be referenced as $parameter_name{example value}. You can omit this section if your intent is not meant to be predicted (some intents are trigger-only)
slot_filling_prompt are used when your intent has a mandatory parameter, and this parameter could not be matched in the user message. These prompts will be used to ask the User about that parameter. You can omit this section if your intent has no mandatory parameters, or if you don’t want to define custom prompts.
responses contain messages that Agent will send to User in response to the Intent. Two response groups are available:
default can only contain plain-text messages. It is good practice to always provide text-only response for situations where rich ones can’t be rendered, such as vocal assistants, smartphone notifications and such. The text response type is specified in
TextIntentResponse
rich responses allow some extra types:
QuickRepliesIntentResponse
,ImageIntentResponse
,CardIntentResponse
andCustomPayloadIntentResponse
-
class
CardIntentResponse
(title, subtitle=None, image=None, link=None)[source]¶ A simple content card that can be rendered on many platforms.
In the YAML, this is defined as
Or an object with the image URL and a title, as in
rich: - card: title: The card title subtitle: An optional subtitle image: https://example.com/image.jpeg link: https://example.com/
- Parameters
title (
str
) – The card titlesubtitle (
Optional
[str
]) – A short subtitleimage (
Optional
[str
]) – URL of an image to be used as coverlink (
Optional
[str
]) – A link to follow if User taps the card
-
class
CustomPayloadIntentResponse
(name, payload)[source]¶ Custom Payloads are objects with arbitrary fields, they are supported by Dialogflow in every response group, including “Default”. Currently they can only be defined in the YAML as free form payloads; support for marshalling or generation from code is expected in future developments.
- Parameters
name (
str
) – A name that identifies the payload typepayload (
dict
) – Any JSON-serializable object
-
classmethod
from_yaml
(data)[source]¶ In the YAML definition a custom payload is defined as follows
rich: - custom: custom_location: latitude: 45.484907 longitude: 9.203299 name: Piazza Duca D'Aosta, Milano
NOTE: while not currently enforced, consistency is expected between payload names and their fields. Future versions of the library will marshal custom payloads against dataclass schemas.
- Parameters
data (
Dict
[str
,dict
]) –
-
class
EntityUtteranceChunk
(entity_cls, parameter_name, parameter_value)[source]¶ An Utterance Chunk that is a matched entity (i.e. references a NLU Parameter)
- Parameters
entity_cls (
Type
[EntityMixin
]) –parameter_name (
str
) –parameter_value (
str
) –
-
class
ExampleUtterance
(example, intent_cls)[source]¶ One of the example Utterances of a given Intent.
- Parameters
example (
str
) –intent_cls (
Type
[Intent
]) –
-
chunks
()[source]¶ Return the Utterance as a sequence of
UtteranceChunk
. Each chunk is either a plain text string, or a mapped Entity.>>> utterance = ExampleUtterance("My name is $user_name{Guido}!", intents.user_gives_name) >>> utterance.chunks() [ TextUtteranceChunk(text="My name is "), EntityUtteranceChunk(entity_cls=Sys.Person, parameter_name="user_name", parameter_value="Guido"), TextUtteranceChunk(text="!") ]
Warning
This method doesn’t handle escaping yet.
- Return type
List
[UtteranceChunk
]
-
class
ImageIntentResponse
(url, title=None)[source]¶ A simple image, defined by its URL and an optional title
In the YAML definition an image response can either be a string with the image URL, as in
rich: - image: https://example.com/image.png
Or an object with the image URL and a title, as in
rich: - image: url: https://example.com/image.png title: An example image
- Parameters
url (
str
) – A publicly accessible image URLtitle (
Optional
[str
]) – A title for the image
-
classmethod
from_yaml
(data)[source]¶ Instantiate an IntentResponse from language data, as it’s found in its YAML file. Typically, IntentResponse is a dataclass and data is a dict of fields; however specific subclasses may override with custom parameters.
- Parameters
data (
Union
[str
,List
[str
]]) – A response object, as it is read from the YAML file
-
class
IntentLanguageData
(example_utterances=<factory>, slot_filling_prompts=<factory>, responses=<factory>)[source]¶ Language data for an Intent consists of three resources:
Example Utterances
Slot Filling Prompts
Responses
Example Utterances are the messages that Agent will be trained on to recognize the Intent.
Responses, intuitively, are the Agent’s response messages that will be sent to User once the Intent is recognized. They are divided in groups: a
IntentResponseGroup.DEFAULT
group (mandatory) can only contain plain text responses. AIntentResponseGroup.RICH
group can provide intent responses that include cards, images and quick replies.Slot Filling Promps are used to solve parameters that couldn’t be tagged in the original message. For instance a OrderPizza intent may have a pizza_type parameter. When User asks “I’d like a pizza” we want to fill the slot by asking “What type of pizza?”. slot_filling_prompts will map parameters to their prompts: {“pizza_type”: [“What type of pizza?”]}
- Parameters
example_utterance – A list of User utterances that should be associated with the intent
slot_filling_prompts (
Dict
[str
,List
[str
]]) – A map of prompts to use when required parameters are missingresponses (
Dict
[IntentResponseGroup
,List
[IntentResponse
]]) – The Responses that Agent will send to User when the intent is predictedexample_utterances (
List
[ExampleUtterance
]) –
-
class
IntentResponse
[source]¶ One of the Response Utterances of a given Intent.
-
classmethod
from_yaml
(data)[source]¶ Instantiate an IntentResponse from language data, as it’s found in its YAML file. Typically, IntentResponse is a dataclass and data is a dict of fields; however specific subclasses may override with custom parameters.
- Parameters
data (
dict
) – A response object, as it is read from the YAML file
-
render
(intent)[source]¶ Render the Response object by replacing parameter references with values from the give
Intent
instance. This is done on every member of the Response class.As IntentResponse objects are frozen, self won’t change. Instead a new object will be returned, with rendered members.
Warning
This function currently doesn’t handle escaping.
>>> intent = OrderCoffee(roast="dark") # This typically comes from a Prediction >>> response = TextIntentResponse(choices=["I like $roast roasted coffee as well", "$roast roast, good choice!"] >>> response.render(intent) TextIntentResponse(choices=["I like dark roasted coffee as well", "dark roast, good choice!"])
- Parameters
intent (
Intent
) – The Intent instance that will be used to read parameter values
-
classmethod
-
class
IntentResponseDict
[source]¶ This is dict of Intent responses, divided by group (Dict[IntentResponseGroup, List[IntentResponse]]):
IntentResponseDict({ IntentResponseGroup.DEFAULT: [ TextIntentResponse(choices=["An anternative", "Another alternative]) ], IntentResponseGroup.RICH: [ TextIntentResponse(choices=["Text response for Rich group"]), QuickRepliesIntentResponse(replies=["A reply", "Another reply"]) ] })
In addition to a standard dict, a
for_group()
convenience method is provided, to select the most suitable messages for a given group.-
for_group
(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
IntentResponseGroup
(value)[source]¶ Intent responses are divided in groups. The same intent can be answered with a set of plain-text responses (
IntentResponseGroup.DEFAULT
), or with rich content (IntentResponseGroup.RICH
) that includes cards, images and quick replies.
-
class
QuickRepliesIntentResponse
(replies)[source]¶ A set of Quick Replies that can be used to answer the Intent. Each reply must be shorter than 20 characters.
In the YAML definition a quick replies response can either be a string, as in
rich: - quick_replies: Order Pizza
Or a list of replies, that will be rendered as separate chips
rich: - quick_replies: - Order Pizza - Order Beer
- Parameters
replies (
List
[str
]) – A list of possible User replies to the current intent
-
classmethod
from_yaml
(data)[source]¶ Instantiate an IntentResponse from language data, as it’s found in its YAML file. Typically, IntentResponse is a dataclass and data is a dict of fields; however specific subclasses may override with custom parameters.
- Parameters
data (
Union
[str
,List
[str
]]) – A response object, as it is read from the YAML file
-
class
TextIntentResponse
(choices)[source]¶ A plain text response. The actual response is picked randomly from a pool of choices.
In the YAML definition a text response can either be a string, as in
responses: default: - text: This is a response
Or a list of choices (the output fulfillment message will be chosen randomly among the different options)
responses: default: - text: - This is a response - This is an alternative response
- Parameters
choices (
List
[str
]) – A list of equivalent responses. One will be chosen at random at prediction time
-
classmethod
from_yaml
(data)[source]¶ Instantiate an IntentResponse from language data, as it’s found in its YAML file. Typically, IntentResponse is a dataclass and data is a dict of fields; however specific subclasses may override with custom parameters.
- Parameters
data (
Union
[str
,List
[str
]]) – A response object, as it is read from the YAML file
-
random
()[source]¶ Pick one of the available choices. It is recommended to
render()
the response first.>>> intent = OrderCoffee(roast="dark") # This typically comes from a Prediction >>> response = TextIntentResponse(choices=["I like $roast roasted coffee as well", "$roast roast, good choice!"] >>> response.render(intent).random() "dark roast, good choice!"
-
class
TextUtteranceChunk
(text)[source]¶ An Utterance Chunk that is a static, plain text string.
- Parameters
text (
str
) –
-
class
UtteranceChunk
[source]¶ An Example Utterance can be seen as a sequence of Chunks, where each Chunk is either a mapped Entity, or a plain text string.
-
intent_language_data
(agent_cls, intent_cls, language_code=None)[source]¶ Return Language Data for the given Intent.
- Parameters
agent_cls (
ForwardRef
) – The Agent class that registered the Intentintent_cls (
Type
[Intent
]) – The Intent to load language data forlanguage_code (
Optional
[LanguageCode
]) – A specific language code to load. If not present, all available languages will be returned
- Return type
Dict
[LanguageCode
,IntentLanguageData
]
-
render_responses
(intent, language_data)[source]¶ Return a copy of responses in language_data where intent parameter references are replaced with their values from the given
Intent
instance.- Parameters
intent (
Intent
) – The intent to read parameters fromlanguage_data (
IntentLanguageData
) – A collection of responses for the given intent
- Return type
Tuple
[IntentResponseDict
,str
]- Returns
Intent responses, and plaintext version
Entities¶
Each of your Entity classes is supposed to define language data in a language/<LANGUAGE-CODE>/ENTITY_MyEntityClass.yaml YAML file.
An Entity language file simply contains a list of entries and their synonyms. For instance, this is the content of example_agent/language/en/ENTITY_PizzaType.yaml:
entries:
Margherita:
- normal
- standard
Diavola:
- spicy
- pepperoni
Capricciosa:
- with olives and artichokes
Check out example_agent.restaurant
for a hands-on example with custom entities.
-
class
EntityEntry
(value, synonyms)[source]¶ Model Language entry for a Custom Entity. EntityEntry objects are produced by
entity_language_data()
as a result of parsing YAML language resources.- Parameters
value (
str
) – The canonical value of the entry (e.g. “Diavola”)synonyms (
List
[str
]) – A set of synonyms that refer to the same entry (e.g. “spicy”, “pepperoni”, …)
-
entity_language_data
(agent_cls, entity_cls, language_code=None)[source]¶ Return language data for a given Entity.
- Parameters
agent_cls (
AgentType
) – The Agent class that registered the Entityentity_cls (
EntityType
) – The Entity class to load language resources forlanguage_code (
Optional
[LanguageCode
]) – A specific Language to load. If not present, all available languages will be returned
- Return type
Dict
[LanguageCode
,List
[EntityEntry
]]
-
make_language_data
(entries)[source]¶ Synthesize entity language data for an Entity from a list of entries. Each entry can just be a string, or a list where the first element is the value, and the remaining ones are synonyms.
This function is mostly for internal use: it is recommended that you store language data in YAML files instead.
- Parameters
entries (
List
[Union
[str
,List
[str
]]]) – A list of entity entries to build language data- Return type
List
[EntityEntry
]