Intent Relations

The interpretation of an utterance may change depending on the context of the conversation. Context-dependant dynamics in the conversation are modeled by the relations intents have with each other. This module defines an API to specify them.

Note

Usage of relations is demonstrated in the example_agent.shop module of the Example Agent

Inheritance

Since we define intents as Python classes, we can reuse of one of the founding concepts of object oriented programming: inheritance.

@dataclass
class AskCoffee(Intent):
    """Hello, I'd like a light roast coffee"""
    roast_level: CoffeeRoastLevel = "medium"

@dataclass
class AskEspresso(AskCoffee):
    """Hello, I'd like a dark roast espresso."""

An intent should subclass another when its meaning includes and specifies the meaning of the other intent. When an intent is a subclass of another:

• It will inherit all parameters, types and default values of the parent intent

• It will inherit all the other relations of the parent intent

• It will be rendered as a separate, independent intent

  • It will not inherit language data such as example utterances and responses

Follow

The follow relation is a context constraint: an intent that follows another one can only be predicted after the followed one.

from intents import follow

@dataclass
class AddMilk(Intent):
    """With milk please"""
    parent_ask_coffee: AskCoffee = follow()

An intent should follow another when it only makes sense in the parent’s context. In the example, it doesn’t make sense to walk into a cafè and utter “With milk please”; however, it does make sense to say so after asking for a coffee.

Context parameters can be accessed with another OOP fundamental concept: composition.

>>> prediction = connector.predict("I want a dark roast espresso")
>>> prediction = connector.predict("With milk please")
>>> prediction.intent.parent_ask_coffee.roast_level
"dark"

This relation is implemented by looking at the lifespan of intents. AskCoffee starts with a lifespan of 5 (at the moment this is constant and can’t be configured). This value is decremented at each conversation turn; intents that follow AskCoffee can only be predicted while its lifespan is > 0.

It’s worth noting that the follow relation is inherited by subclasses:

• If intent AskEspresso is a subclass of AskCoffee, and AddMilk follows AskCoffe, then AddMilk also follows AskEspresso.

• If intent AskSkimmedMilk is a subclass of AskMilk, and AskMilk follows AskCoffee, then AskSkimmedMilk also follows AskCoffee (and AskEspresso in the example above)

class RelatedIntent(field_name, relation_type, intent_cls)

Represent one of the Intents that are related to the Relation subject. Along with the related intent’s class, this structure also stores its name as a parameter and the relation type.

This structure is produced by related_intents().

Parameters

• field_name (str) – Name of the field in the Relation subject

• relation_type (RelationType) – One of the supported Relation types

• intent_cls (_IntentMetaclass) – Class of the intent that is related to the subject

class RelatedIntents(follow=<factory>)

A map of an Intent’s relations, as it is produced by related_intents().

Parameters

follow (List[RelatedIntent]) – A list of intents that are followed by the Relation subject

class RelationType(value)

Currently, the only available type is RelationType.FOLLOW. If you want to define a follow relation, use follow().

follow()

This can be used as a value for an Intent Relation field, e.g.

@dataclass
class AddMilk(Intent):
    """With milk please"""
    parent_ask_coffee: AskCoffee = follow()

Internally, this is equivalent to calling dataclasses.field() with a custom set of metadata.

Warning

The returned field currently sets default=None as a workaround to some known limitations of dataclasses with inheritance. This behavior may be adjusted again before 1.0

Return type

Field

related_intents(intent)

Produce a map of all the intents that are related to the given relation subject.

Parameters

intent (Intent) – The relation subject

Return type

RelatedIntents