Intent

An intent is a categorical representation of the User intention in a single conversation turn. For instance, utterances like “I want a pizza”, “I’d like to order a pizza” and such, could be mapped to a single OrderPizza intent.

Your agent will typically define a number of intents, representing all the types of messages the Agent can understand and answer to. This is done by defining Intent sub-classes and their language resources (see intents.language), and registering them to an intents.Agent class with intents.Agent.register().

class Intent

This is a base class for user defined intents, which are the fundamental building blocks of your Agent.

In its simplest form, an Intent can be defined as follows:

from intents import Intent

class UserSaysHello(Intent):
    """A little docstring for my Intent"""

Intents will then look for language resources in the folder where your Agent class is defined, and specifically in language/<LANGUAGE-CODE>/smalltalk.UserSaysHello.yaml. Note that the name of the module where the Intent is defined (smalltalk.py) is used as a prefix. More details in intents.language.

Intents can be more complex than this, for instance:

from dataclasses import dataclass
from intents import Intent, Sys

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

    user_name: Sys.Person

    name = "hello_custom_name"
    lifespan = 10

This Intent has a custom name, so it will appear as “hello_custom_name” when exported to prediction services such as Dialogflow, and its language file will just be hello_custom_name.yaml, without module prefix. See check_name() for more details on the rules that intent names must follow.

This intent has a lifespan member. This is used in intents.model.relations to determine how long should the Intent stay in the conversation context after it is predicted.

Most importantly, this intent has a user_name parameter of type Sys.Person (check out intents.model.entity.Sys for available system entities). With adequate examples in its language file, it will be able to match utterances like “Hello, my name is John”, tagging “John” as an Entity. When a connector is instantiated, predictions will look like this:

>>> predicted = connector.predict("My name is John")
>>> predicted.intent
UserSaysHello(user_name="John")
>>> predicted.intent.user_name
"John"
>>> predicted.fulfillment_text
"Hi John, I'm Agent"

Warning

Parameter names are meant to be unique within an Agent. That is, the same parameter must always be defined with the same type. This is because 1) Some services (e.g. Alexa) require so. 2) Predictions overwrite parameters in context based on their name: better make sure they are compatible.

Last, we notice the @dataclass decorator. We require it to be added explicitly, this way IDEs will recognize the Intent class as a dataclass and provide correct hints for names and types.

fulfill(context, **kwargs)

Override this method to define a custom procedure that will be invoked when the Intent is predicted, possibly triggering another intent as a result. For instance:

@dataclass
class UserConfirmsPayment(Intent):

    parent_order: UserOrdersSomething = follow()

    def fulfill(self, context):
        if shop_api.is_item_available(parent_order.item_id):
            shop_api.make_order(parent_order.item_id)
            return OrderSuccessResponse()
        else:
            return OrderFailedResponse()

In the example, when UserConfirmsPayment is predicted, it will run some business logic, and choose a different response depending on the result. Note that response objects are full-fledged Intents, and even though they probably won’t include example utterances, they can define parameters, relations, and their own fulfillment() implementation, that will be executed recursively.

More details about fulfillments can be found in the fulfillment module documentation.

Parameters

context (FulfillmentContext) – Context information about the fulfillment request (confidence, language, …)

Return type

Intent

Returns

A FulfillmentResult object, that can contain a followup intent to trigger, or just some responses to post back to user.

parameter_dict()

Return the Intent parameters and their values as a dict.

Return type

Dict[str, IntentParameter]

Returns

A dict of parameters

classmethod parent_intents()

Return a list of the Intent parent classes. This wraps cls.mro() filtering out non-Intent parents (e.g. object), Intent and cls itself.

>>> AskEspresso.parent_intents()
[AskCoffee, AskDrink]

Return type

List[Type[Intent]]

Returns

A list of parent Intent classes

replace(*, lifespan=None, **kwargs)

Return a copy of the given intent object replacing the given field values

>>> OrderPizza(pizza_type="margherita").replace(lifespan=3, pizza_type="marinara")
OrderPizza(pizza_type="marinara")

This method is meant for internal use. Changing lifespans and parameters will most likely have an impact on session and contexts that have to be dealt with separately.

Parameters

lifespan (int, optional) – Intent lifespan. Defaults to None.

Return type

~T

Returns

An Intent of the same type, with updated fields

class NluIntentParameter(name, required, default, is_list, entity_cls)

These are IntentParameters that are tagged in User utterances (e.g. a pizza_type parameter can be tagged in the message of a user that is ordering pizza).

Every member of an Intent dataclass that is annotated with an Entity type will be recognized as a NLU Parameter.

Parameters

• name (str) – Parameter name

• entity_cls (EntityType) – Parameter type

• is_list (bool) – Parameter will match multiple values in the User utterance

• required (bool) – If True, user will be prompted for parameter value when that can’t be tagged in his utterance

• default (Any) – If set, this value will be used when parameter value can’t be tagged in the User’s utterance

class FulfillmentContext(session, confidence, fulfillment_text, fulfillment_messages, language)

FulfillmentContext objects are produced by Connectors and are input arguments to Intent.fulfill().

Parameters

• session (FulfillmentSession) –

• confidence (float) –

• fulfillment_text (str) –

• fulfillment_messages (IntentResponseDict) –

• language (LanguageCode) –

class FulfillmentResult(trigger=None, fulfillment_text=None, fulfillment_messages=None)

FulfillmentResult are produced by Intent.fulfill, and then converted by Connectors into Service-actionable responses.

Note

At the moment this class is only used internally. It is safe to return simple Intent instances in Intent.fulfill()

Parameters

• trigger (Optional[Intent]) –

• fulfillment_text (Optional[List[str]]) –

• fulfillment_messages (Optional[List[ForwardRef]]) –

static ensure(fulfill_return_value)

Convert the given object to a FulfillmentResult instance, if it is not already one.

Parameters

fulfill_return_value (Union[FulfillmentResult, Intent]) – An object, as it is returned by Intent.fulfill()

Raises

ValueError – If input object is not a valid return value for Intent.fulfill()

Returns

A FulfillmentResult object representing input

Return type

FulfillmentResult