Skip to content

aea.protocols.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.

InvalidDialogueMessage Objects

class InvalidDialogueMessage(Exception)

Exception for adding invalid message to a dialogue.

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.

_DialogueMeta Objects

class _DialogueMeta(type)

Metaclass for Dialogue.

Adds slot support forevery subclass Creates classlevvel Rules instance

__new__

 | __new__(cls, name: str, bases: Tuple[Type], dct: Dict)

Construct a new type.

Dialogue Objects

class Dialogue(, metaclass=_DialogueMeta)

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: Type[Message], self_address: Address, role: Role) -> None

Initialize a dialogue.

Arguments:

  • dialogue_label: the identifier of the dialogue
  • self_address: the address of the entity 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

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

self_address

 | @property
 | self_address() -> Address

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

Returns:

the address of this entity

role

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

Get the agent's role in the dialogue.

Returns:

the agent's role

rules

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

Get the dialogue rules.

Returns:

the rules

message_class

 | @property
 | message_class() -> Type[Message]

Get the message class.

Returns:

the message class

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

is_empty

 | @property
 | is_empty() -> bool

Check whether the dialogue is empty.

Returns:

True if empty, False otherwise

reply

 | reply(performative: Message.Performative, target_message: Optional[Message] = None, target: Optional[int] = None, **kwargs, ,) -> Message

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

Note if no target_message is provided, the last message in the dialogue will be replied to.

Arguments:

  • target_message: the message to reply to.
  • target: the id of 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.

__str__

 | __str__() -> str

Get the string representation.

Returns:

The string representation of the dialogue

DialogueStats Objects

class DialogueStats()

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

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

__init__

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

Initialize dialogues.

Arguments:

  • self_address: the address of the entity 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.

self_address

 | @property
 | self_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

message_class

 | @property
 | message_class() -> Type[Message]

Get the message class.

Returns:

the message class

dialogue_class

 | @property
 | dialogue_class() -> Type[Dialogue]

Get the dialogue class.

Returns:

the dialogue class

get_dialogues_with_counterparty

 | get_dialogues_with_counterparty(counterparty: Address) -> List[Dialogue]

Get the dialogues by address.

Arguments:

  • counterparty: the counterparty

Returns:

The dialogues with the counterparty.

new_self_initiated_dialogue_reference

 | @classmethod
 | new_self_initiated_dialogue_reference(cls) -> 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.

create_with_message

 | create_with_message(counterparty: Address, initial_message: Message) -> Dialogue

Create a dialogue with 'counterparty', with an initial message provided.

Arguments:

  • counterparty: the counterparty of the dialogue.
  • initial_message: 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 incoming 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