Entity

Entities are special chunks of text in the User utterances, that are recognized and extratcted as parameters during predictions. For instance, in an utterance like “My name is John” we most likely want to match “John” as a Person Entity.

Two types of Entities exist:

• System entities are built-in types that most chatbot frameworks will recognize (names, cities, numbers, emails, …). These are modelled in Sys.

• Custom entities are user-defined entity types, that typically consist in a list of possible values and their synonims. For instance, a PizzaType custom entity will have values like “margherita”, “marinara”, “diavola” and so on, and each of these may define some synonims; this way, in an utterance like “I want a pepperoni pizza”, the “pepperoni” chunk can be recognized as a PizzaType parameter, and mapped to its correct name, which is “diavola”. Custom entities are defined by extending the Entity base class.

class Entity

Bases: str, intents.model.entity.EntityMixin

Custom Entities are defined by users to match parameters that are specific to the Agent’s domain. This is done by extending this class:

from dataclasses import dataclass
from intents import Intent, Entity

class PizzaType(Entity):
    """One of the pizza types that a Customer can order"""

@dataclass
class CustomerOrdersPizza(Intent):
    """A little docstring for my Intent"""

    pizza_type: PizzaType

Language resources are expected for the PizzaType Entity. Like Intents, these will be looked up from the folder where the Agent main class is defined, and specifically in language/<LANGUAGE-CODE>/ENTITY_PizzaType.yaml. More details in intents.language.

class Meta(regex_entity=False, automated_expansion=False, fuzzy_matching=True)

Bases: object

This class is used to set user-controlled Entity parameters.

Warning

The use of Meta is strictly bound to Dialogflow; support may be dropped in the next releases of Intents

Parameters

• regex_entity (bool) – Whether to treat entity values as regular expressions

• automated_expansion (bool) – Service will try to match synonyms even if they are not explicitly declared

• fuzzy_matching (bool) – Service will ignore word order in matching

class EntityMixin

Bases: object

This is a mixin class for entities, that adds from_df_response(), to build the Entity object from the match data in Dialogflow Responses.

classmethod from_df_response(match)

Buid the Entity object from the match data from a Dialogflow Response. Specifically, match is the dict version of queryResult.parameters.<PARAMETER_NAME>.

Parameters

match (Any) –

class Sys

Bases: object

This is a container class, that defines all the system entities that are supported in the Intents framework. You can use system entities just like this:

from dataclasses import dataclass
from intents import Intent, Sys

@dataclass
class UserSaysName(Intent):
    """A little docstring for my Intent"""

    user_name: Sys.Person

System entities inherit from Python base types, so

>>> isinstance(Sys.Integer(42), int)
True
>>> from datetime import date
>>> isinstance(Sys.Date.from_py_date(date(2021, 7, 30)), date)
True

NOTE: This class can be expanded to contain more sophisticated entities, such as time intervals, amounts with measurement units and such. These may not be natively supported on every prediction service: some attention is needed to ensure portability.

class Color

Bases: str, intents.model.entity.SystemEntityMixin

Words describing colors

class Date

Bases: datetime.date, intents.model.entity.SystemEntityMixin

Matches a date as a Python datetime.date object

static from_py_date(py_date)

Clone the given datetime.date object into a Sys.Date object. This is mostly for internal use.

Parameters

py_date (date) – A Python date object

class Email

Bases: str, intents.model.entity.SystemEntityMixin

Any standard email address

class Integer

Bases: int, intents.model.entity.SystemEntityMixin

Matches integers only

class Language

Bases: str, intents.model.entity.SystemEntityMixin

Language names

class MusicArtist

Bases: str, intents.model.entity.SystemEntityMixin

Matches the name of a music artist

class MusicGenre

Bases: str, intents.model.entity.SystemEntityMixin

Matches a music genre (rock, pop, reggae, …)

class Person

Bases: str, intents.model.entity.SystemEntityMixin

Matches common given names, last names or their combinations.

Note that in Dialogflow this is returned as an Object (e.g. {“name”: “John”}), while here we define Person as a String. The Dialogflow module defines proper entity mappings to handle the conversion.

class PhoneNumber

Bases: str, intents.model.entity.SystemEntityMixin

Any standard phone number

class Time

Bases: datetime.time, intents.model.entity.SystemEntityMixin

Matches a time reference as a Python datetime.time object

static from_py_time(py_time)

Clone the given datetime.time object into a Sys.Time object. This is mostly for internal use.

Parameters

py_time (time) – A Python time object

class Url

Bases: str, intents.model.entity.SystemEntityMixin

Any standard URL

class SystemEntityMixin

Bases: intents.model.entity.EntityMixin

This is used to signal that the entity is one of the Dialogflow default entities and doesn’t need language resources.