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[source]

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"""

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=False)[source]

Bases: object

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


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

  • 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[source]

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)[source]

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


match (Any) –

class Sys[source]

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

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)
>>> from datetime import date
>>> isinstance(Sys.Date.from_py_date(date(2021, 7, 30)), date)

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[source]

Bases: str, intents.model.entity.SystemEntityMixin

Words describing colors

class Date[source]

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

Matches a date as a Python datetime.date object

static from_py_date(py_date)[source]

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


py_date (date) – A Python date object

class Email[source]

Bases: str, intents.model.entity.SystemEntityMixin

Any standard email address

class Integer[source]

Bases: int, intents.model.entity.SystemEntityMixin

Matches integers only

class Language[source]

Bases: str, intents.model.entity.SystemEntityMixin

Language names

class MusicArtist[source]

Bases: str, intents.model.entity.SystemEntityMixin

Matches the name of a music artist

class MusicGenre[source]

Bases: str, intents.model.entity.SystemEntityMixin

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

class Person[source]

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[source]

Bases: str, intents.model.entity.SystemEntityMixin

Any standard phone number

class Time[source]

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

Matches a time reference as a Python datetime.time object

static from_py_time(py_time)[source]

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


py_time (time) – A Python time object

class Url[source]

Bases: str, intents.model.entity.SystemEntityMixin

Any standard URL

class SystemEntityMixin[source]

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.