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 and CustomPayloadIntentResponse

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 title
subtitle (Optional[str]) – A short subtitle
image (Optional[str]) – URL of an image to be used as cover
link (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 type
payload (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

Parameters

entity_cls (Type[EntityMixin]) –
parameter_name (str) –
parameter_value (str) –

class ExampleUtterance(example, intent)[source]¶

One of the example Utterances of a given Intent.

Parameters

example (str) –
intent (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.

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 URL
title (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. A IntentResponseGroup.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 missing
responses (Dict[IntentResponseGroup, List[IntentResponse]]) – The Responses that Agent will send to User when the intent is predicted
example_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

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 returned
language.IntentResponseGroup.RICH is requested
- RICH 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 (AgentType) – The Agent class that registered the Intent
intent_cls (Type[Intent]) – The Intent to load language data for
language_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 from
language_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 Entity
entity_cls (EntityType) – The Entity class to load language resources for
language_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]