aea.helpers.dialogue.base

This module contains the classes required for dialogue management.

  • DialogueLabel: The dialogue label class acts as an identifier for dialogues.
  • Dialogue: The dialogue class maintains state of a dialogue and manages it.
  • Dialogues: The dialogues class keeps track of all dialogues.

DialogueLabel

class DialogueLabel()

The dialogue label class acts as an identifier for dialogues.

__init__

 | __init__(dialogue_reference: Tuple[str, str], dialogue_opponent_addr: Address, dialogue_starter_addr: Address) -> None

Initialize a dialogue label.

Arguments:

  • dialogue_reference: the reference of the dialogue.
  • dialogue_opponent_addr: the addr of the agent with which the dialogue is kept.
  • dialogue_starter_addr: the addr of the agent which started the dialogue.

Returns:

None

dialogue_reference

 | @property
 | dialogue_reference() -> Tuple[str, str]

Get the dialogue reference.

dialogue_starter_reference

 | @property
 | dialogue_starter_reference() -> str

Get the dialogue starter reference.

dialogue_responder_reference

 | @property
 | dialogue_responder_reference() -> str

Get the dialogue responder reference.

dialogue_opponent_addr

 | @property
 | dialogue_opponent_addr() -> str

Get the address of the dialogue opponent.

dialogue_starter_addr

 | @property
 | dialogue_starter_addr() -> str

Get the address of the dialogue starter.

__eq__

 | __eq__(other) -> bool

Check for equality between two DialogueLabel objects.

__hash__

 | __hash__() -> int

Turn object into hash.

json

 | @property
 | json() -> Dict

Return the JSON representation.

from_json

 | @classmethod
 | from_json(cls, obj: Dict[str, str]) -> "DialogueLabel"

Get dialogue label from json.

__str__

 | __str__()

Get the string representation.

Dialogue

class Dialogue(ABC)

The dialogue class maintains state of a dialogue and manages it.

Role

class Role(Enum)

This class defines the agent's role in a dialogue.

__str__

 | __str__()

Get the string representation.

EndState

class EndState(Enum)

This class defines the end states of a dialogue.

__str__

 | __str__()

Get the string representation.

__init__

 | __init__(dialogue_label: DialogueLabel, agent_address: Optional[Address] = None, role: Optional[Role] = None) -> None

Initialize a dialogue.

Arguments:

  • dialogue_label: the identifier of the dialogue
  • agent_address: the address of the agent for whom this dialogue is maintained
  • role: the role of the agent this dialogue is maintained for

Returns:

None

dialogue_label

 | @property
 | dialogue_label() -> DialogueLabel

Get the dialogue label.

Returns:

The dialogue label

agent_address

 | @agent_address.setter
 | agent_address(agent_address: Address) -> None

Set the address of the agent for whom this dialogues is maintained.

:param: the agent address

role

 | @role.setter
 | role(role: "Role") -> None

Set the agent's role in the dialogue.

Arguments:

  • role: the agent's role

Returns:

None

is_self_initiated

 | @property
 | is_self_initiated() -> bool

Check whether the agent initiated the dialogue.

Returns:

True if the agent initiated the dialogue, False otherwise

last_incoming_message

 | @property
 | last_incoming_message() -> Optional[Message]

Get the last incoming message.

Returns:

the last incoming message if it exists, None otherwise

last_outgoing_message

 | @property
 | last_outgoing_message() -> Optional[Message]

Get the last outgoing message.

Returns:

the last outgoing message if it exists, None otherwise

last_message

 | @property
 | last_message() -> Optional[Message]

Get the last message.

Returns:

the last message if it exists, None otherwise

get_message

 | get_message(message_id_to_find: int) -> Optional[Message]

Get the message whose id is 'message_id'.

Arguments:

  • message_id_to_find: the id of the message

Returns:

the message if it exists, None otherwise

is_empty

 | @property
 | is_empty() -> bool

Check whether the dialogue is empty

Returns:

True if empty, False otherwise

update

 | update(message: Message) -> bool

Extend the list of incoming/outgoing messages with 'message', if 'message' is valid

Arguments:

  • message: a message to be added

Returns:

True if message successfully added, false otherwise

is_valid_next_message

 | is_valid_next_message(message: Message) -> bool

Check whether 'message' is a valid next message in this dialogue.

The evaluation of a message validity involves performing several categories of checks. Each category of checks resides in a separate method.

Currently, basic rules are fundamental structural constraints, additional rules are applied for the time being, and more specific rules are captured in the is_valid method.

Arguments:

  • message: the message to be validated

Returns:

True if yes, False otherwise.

initial_performative

 | @abstractmethod
 | initial_performative() -> Enum

Get the performative which the initial message in the dialogue must have

Returns:

the performative of the initial message

get_replies

 | @abstractmethod
 | get_replies(performative: Enum) -> FrozenSet

Given a performative, return the list of performatives which are its valid replies in a dialogue

Arguments:

  • performative: the performative in a message

Returns:

list of valid performative replies

is_valid

 | @abstractmethod
 | is_valid(message: Message) -> bool

Check whether 'message' is a valid next message in the dialogue.

These rules capture specific constraints designed for dialogues which are instance of a concrete sub-class of this class.

Arguments:

  • message: the message to be validated

Returns:

True if valid, False otherwise.

__str__

 | __str__() -> str

Get the string representation.

Returns:

The string representation of the dialogue

outgoing_extend

 | outgoing_extend(message: Message) -> None

UNSAFE TO USE - IS DEPRECATED - USE update(message) METHOD INSTEAD Extend the list of outgoing messages with 'message'

Arguments:

  • message: a message to be added

Returns:

None

incoming_extend

 | incoming_extend(message: Message) -> None

UNSAFE TO USE - IS DEPRECATED - USE update(message) METHOD INSTEAD Extend the list of incoming messages with 'message'

Arguments:

  • message: a message to be added

Returns:

None

Dialogues

class Dialogues(ABC)

The dialogues class keeps track of all dialogues for an agent.

__init__

 | __init__(agent_address: Address = "") -> None

Initialize dialogues.

Arguments:

  • agent_address: the address of the agent for whom dialogues are maintained

Returns:

None

dialogues

 | @property
 | dialogues() -> Dict[DialogueLabel, Dialogue]

Get dictionary of dialogues in which the agent engages.

agent_address

 | @property
 | agent_address() -> Address

Get the address of the agent for whom dialogues are maintained.

new_self_initiated_dialogue_reference

 | new_self_initiated_dialogue_reference() -> Tuple[str, str]

Return a dialogue label for a new self initiated dialogue

Returns:

the next nonce

update

 | update(message: Message) -> Optional[Dialogue]

Update the state of dialogues with a new message.

If the message is for a new dialogue, a new dialogue is created with 'message' as its first message and returned. If the message is addressed to an existing dialogue, the dialogue is retrieved, extended with this message and returned. If there are any errors, e.g. the message dialogue reference does not exists or the message is invalid w.r.t. the dialogue, return None.

Arguments:

  • message: a new message

Returns:

the new or existing dialogue the message is intended for, or None in case of any errors.

create_dialogue

 | @abstractmethod
 | create_dialogue(dialogue_label: DialogueLabel, role: Dialogue.Role) -> Dialogue

Create a dialogue instance.

Arguments:

  • dialogue_label: the identifier of the dialogue
  • role: the role of the agent this dialogue is maintained for

Returns:

the created dialogue

role_from_first_message

 | @staticmethod
 | @abstractmethod
 | role_from_first_message(message: Message) -> Dialogue.Role

Infer the role of the agent from an incoming or outgoing first message

Arguments:

  • message: an incoming/outgoing first message

Returns:

the agent's role

is_belonging_to_registered_dialogue

 | is_belonging_to_registered_dialogue(msg: Message, agent_addr: Address) -> bool

DEPRECATED

Check whether an agent message is part of a registered dialogue.

Arguments:

  • msg: the agent message
  • agent_addr: the address of the agent

Returns:

boolean indicating whether the message belongs to a registered dialogue

is_permitted_for_new_dialogue

 | is_permitted_for_new_dialogue(msg: Message) -> bool

DEPRECATED

Check whether an agent message is permitted for a new dialogue.

Arguments:

  • msg: the agent message

Returns:

a boolean indicating whether the message is permitted for a new dialogue

get_dialogue

 | get_dialogue(msg: Message, address: Address) -> Dialogue

DEPRECATED

Retrieve dialogue.

Arguments:

  • fipa_msg: the fipa message
  • agent_addr: the address of the agent

Returns:

the dialogue

create_self_initiated

 | create_self_initiated(dialogue_opponent_addr: Address, role: Dialogue.Role) -> Dialogue

DEPRECATED

Create a self initiated dialogue.

Arguments:

  • dialogue_opponent_addr: the pbk of the agent with which the dialogue is kept.
  • role: the agent's role

Returns:

the created dialogue.

create_opponent_initiated

 | create_opponent_initiated(dialogue_opponent_addr: Address, dialogue_reference: Tuple[str, str], role: Dialogue.Role) -> Dialogue

DEPRECATED

Create an opponent initiated dialogue.

Arguments:

  • dialogue_opponent_addr: the address of the agent with which the dialogue is kept.
  • dialogue_reference: the reference of the dialogue.
  • role: the agent's role

Returns:

the created dialogue