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 Objects

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.

get_incomplete_version

 | get_incomplete_version() -> "DialogueLabel"

Get the incomplete version of the label.

__str__

 | __str__()

Get the string representation.

from_str

 | @classmethod
 | from_str(cls, obj: str) -> "DialogueLabel"

Get the dialogue label from string representation.

Dialogue Objects

class Dialogue(ABC)

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

Rules Objects

class Rules()

This class defines the rules for the dialogue.

__init__

 | __init__(initial_performatives: FrozenSet[Message.Performative], terminal_performatives: FrozenSet[Message.Performative], valid_replies: Dict[Message.Performative, FrozenSet[Message.Performative]]) -> None

Initialize a dialogue.

Arguments:

  • initial_performatives: the set of all initial performatives.
  • terminal_performatives: the set of all terminal performatives.
  • valid_replies: the reply structure of speech-acts.

Returns:

None

initial_performatives

 | @property
 | initial_performatives() -> FrozenSet[Message.Performative]

Get the performatives one of which the terminal message in the dialogue must have.

Returns:

the valid performatives of an terminal message

terminal_performatives

 | @property
 | terminal_performatives() -> FrozenSet[Message.Performative]

Get the performatives one of which the terminal message in the dialogue must have.

Returns:

the valid performatives of an terminal message

valid_replies

 | @property
 | valid_replies() -> Dict[Message.Performative, FrozenSet[Message.Performative]]

Get all the valid performatives which are a valid replies to performatives.

Returns:

the full valid reply structure.

get_valid_replies

 | get_valid_replies(performative: Message.Performative) -> FrozenSet[Message.Performative]

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

Role Objects

class Role(Enum)

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

__str__

 | __str__()

Get the string representation.

EndState Objects

class EndState(Enum)

This class defines the end states of a dialogue.

__str__

 | __str__()

Get the string representation.

__init__

 | __init__(dialogue_label: DialogueLabel, message_class: Optional[Type[Message]] = None, agent_address: Optional[Address] = None, role: Optional[Role] = None, rules: Optional[Rules] = 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
  • rules: the rules of the dialogue

Returns:

None

dialogue_label

 | @property
 | dialogue_label() -> DialogueLabel

Get the dialogue label.

Returns:

The dialogue label

incomplete_dialogue_label

 | @property
 | incomplete_dialogue_label() -> DialogueLabel

Get the dialogue label.

Returns:

The incomplete dialogue label

dialogue_labels

 | @property
 | dialogue_labels() -> Set[DialogueLabel]

Get the dialogue labels (incomplete and complete, if it exists)

Returns:

the dialogue labels

agent_address

 | @property
 | agent_address() -> Address

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

Returns:

the agent address

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

 | @property
 | role() -> "Role"

Get the agent's role in the dialogue.

Returns:

the agent's role

role

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

Set the agent's role in the dialogue.

Arguments:

  • role: the agent's role

Returns:

None

rules

 | @property
 | rules() -> "Rules"

Get the dialogue rules.

Returns:

the rules

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' belongs to dialogue and is valid.

Arguments:

  • message: a message to be added

Returns:

True if message successfully added, false otherwise

ensure_counterparty

 | ensure_counterparty(message: Message) -> None

Ensure the counterparty is set (set if not) correctly.

Arguments:

  • message: a message

Returns:

None

is_belonging_to_dialogue

 | is_belonging_to_dialogue(message: Message) -> bool

Check if the message is belonging to the dialogue.

Arguments:

  • message: the message

Returns:

Ture if message is part of the dialogue, False otherwise

reply

 | reply(target_message: Message, performative, **kwargs) -> Message

Reply to the 'target_message' in this dialogue with a message with 'performative', and contents from kwargs.

Arguments:

  • target_message: the message to reply to.
  • performative: the performative of the reply message.
  • kwargs: the content of the reply message.

Returns:

the reply message if it was successfully added as a reply, None 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.

update_dialogue_label

 | update_dialogue_label(final_dialogue_label: DialogueLabel) -> None

Update the dialogue label of the dialogue.

Arguments:

  • final_dialogue_label: the final dialogue label

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

DialogueStats Objects

class DialogueStats(ABC)

Class to handle statistics on default dialogues.

__init__

 | __init__(end_states: FrozenSet[Dialogue.EndState]) -> None

Initialize a StatsManager.

Arguments:

  • end_states: the list of dialogue endstates

self_initiated

 | @property
 | self_initiated() -> Dict[Dialogue.EndState, int]

Get the stats dictionary on self initiated dialogues.

other_initiated

 | @property
 | other_initiated() -> Dict[Dialogue.EndState, int]

Get the stats dictionary on other initiated dialogues.

add_dialogue_endstate

 | add_dialogue_endstate(end_state: Dialogue.EndState, is_self_initiated: bool) -> None

Add dialogue endstate stats.

Arguments:

  • end_state: the end state of the dialogue
  • is_self_initiated: whether the dialogue is initiated by the agent or the opponent

Returns:

None

Dialogues Objects

class Dialogues(ABC)

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

__init__

 | __init__(agent_address: Address, end_states: FrozenSet[Dialogue.EndState], message_class: Optional[Type[Message]] = None, dialogue_class: Optional[Type[Dialogue]] = None, role_from_first_message: Optional[Callable[[Message], Dialogue.Role]] = None) -> None

Initialize dialogues.

Arguments:

  • agent_address: the address of the agent for whom dialogues are maintained
  • end_states: the list of dialogue endstates

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.

dialogue_stats

 | @property
 | dialogue_stats() -> DialogueStats

Get the dialogue statistics.

Returns:

dialogue stats object

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

create

 | create(counterparty: Address, performative: Message.Performative, **kwargs, ,) -> Tuple[Message, Dialogue]

Create a dialogue with 'counterparty', with an initial message whose performative is 'performative' and contents are from 'kwargs'.

Arguments:

  • counterparty: the counterparty of the dialogue.
  • performative: the performative of the initial message.
  • kwargs: the content of the initial message.

Returns:

the initial message and the dialogue.

update

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

Update the state of dialogues with a new incoming 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.

get_dialogue

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

Retrieve the dialogue 'message' belongs to.

Arguments:

  • message: a message

Returns:

the dialogue, or None in case such a dialogue does not exist

get_latest_label

 | get_latest_label(dialogue_label: DialogueLabel) -> DialogueLabel

Retrieve the latest dialogue label if present otherwise return same label.

Arguments:

  • dialogue_label: the dialogue label :return dialogue_label: the dialogue label

get_dialogue_from_label

 | get_dialogue_from_label(dialogue_label: DialogueLabel) -> Optional[Dialogue]

Retrieve a dialogue based on its label.

Arguments:

  • dialogue_label: the dialogue label

Returns:

the dialogue if present

create_dialogue

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

THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN THE NEXT VERSION. USE THE NEW CONSTRUCTOR ARGUMENTS INSTEAD.

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