tac.agents.participant.v1.base package¶

Submodules¶

tac.agents.participant.v1.base.actions module¶

This module contains the classes which define the actions of an agent.

ControllerActions: The ControllerActions class defines the actions of an agent towards the ControllerAgent.
OEFActions: The OEFActions class defines the actions of an agent towards the OEF.
DialogueActions: The DialogueActions class defines the actions of an agent in the context of a Dialogue.

class tac.agents.participant.v1.base.actions.ControllerActions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.interfaces.ControllerActionInterface

The ControllerActions class defines the actions of an agent towards the ControllerAgent.

request_state_update() → None¶

Request current agent state from TAC Controller.

Returns: None

class tac.agents.participant.v1.base.actions.DialogueActions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.interfaces.DialogueActionInterface

The DialogueActions class defines the actions of an agent in the context of a Dialogue.

class tac.agents.participant.v1.base.actions.OEFActions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.interfaces.OEFActionInterface

The OEFActions class defines the actions of an agent towards the OEF.

register_service() → None¶

Register to the OEF Service Directory.

In particular, register

as a seller, listing the goods supplied, or
as a buyer, listing the goods demanded, or
as both.

Returns: None

search_for_tac() → None¶

Search for active TAC Controller.

We assume that the controller is registered as a service with the ‘tac’ data model and with an attribute version = expected_version_id.

Returns: None

search_services() → None¶

Search on OEF Service Directory.

In particular, search

for sellers and their supply, or
for buyers and their demand, or
for both.

Returns: None

unregister_service() → None¶

Unregister service from OEF Service Directory.

Returns: None

update_services() → None¶

Update services on OEF Service Directory.

Returns: None

tac.agents.participant.v1.base.dialogues module¶

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.

class tac.agents.participant.v1.base.dialogues.Dialogue(dialogue_label: aea.helpers.dialogue.base.DialogueLabel, is_seller: bool)¶

Bases: aea.helpers.dialogue.base.Dialogue

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

property dialogue_label¶: Get the dialogue lable.

incoming_extend(messages: List[aea.protocols.base.message.Message]) → None¶

Extend the list of messages which keeps track of incoming messages.

Parameters: messages – a list of messages to be added
Returns: None

is_expecting_accept_decline() → bool¶

Check whether the dialogue is expecting an decline following an accept.

Returns: True if yes, False otherwise.

is_expecting_cfp_decline() → bool¶

Check whether the dialogue is expecting an decline following a cfp.

Returns: True if yes, False otherwise.

is_expecting_initial_accept() → bool¶

Check whether the dialogue is expecting an initial accept.

Returns: True if yes, False otherwise.

is_expecting_matching_accept() → bool¶

Check whether the dialogue is expecting a matching accept.

Returns: True if yes, False otherwise.

is_expecting_propose() → bool¶

Check whether the dialogue is expecting a propose.

Returns: True if yes, False otherwise.

is_expecting_propose_decline() → bool¶

Check whether the dialogue is expecting an decline following a propose.

Returns: True if yes, False otherwise.

property is_seller¶: Check whether the agent acts as the seller in this dialogue.

outgoing_extend(messages: List[aea.protocols.base.message.Message]) → None¶

Extend the list of messages which keeps track of outgoing messages.

Parameters: messages – a list of messages to be added
Returns: None

property role¶: Get role of agent in dialogue.

class tac.agents.participant.v1.base.dialogues.Dialogues¶

Bases: aea.helpers.dialogue.base.Dialogues

The dialogues class keeps track of all dialogues.

create_opponent_initiated(dialogue_opponent_pbk: str, dialogue_id: int, is_seller: bool) → tac.agents.participant.v1.base.dialogues.Dialogue¶

Save an opponent initiated dialogue.

Parameters

dialogue_opponent_pbk – the pbk of the agent with which the dialogue is kept.
dialogue_id – the id of the dialogue
is_seller – boolean indicating the agent role

Returns

the created dialogue

create_self_initiated(dialogue_opponent_pbk: str, dialogue_starter_pbk: str, is_seller: bool) → tac.agents.participant.v1.base.dialogues.Dialogue¶

Create a self initiated dialogue.

Parameters

dialogue_opponent_pbk – the pbk of the agent with which the dialogue is kept.
dialogue_starter_pbk – the pbk of the agent which started the dialogue
is_seller – boolean indicating the agent role

Returns

the created dialogue.

property dialogues_as_buyer¶: Get dictionary of dialogues in which the agent acts as a buyer.

property dialogues_as_seller¶: Get dictionary of dialogues in which the agent acts as a seller.

get_dialogue(message: aea.protocols.base.message.Message, sender: str, agent_pbk: str) → tac.agents.participant.v1.base.dialogues.Dialogue¶

Retrieve dialogue.

Parameters

message – the agent message
agent_pbk – the public key of the agent

Returns

the dialogue

is_belonging_to_registered_dialogue(message: aea.protocols.base.message.Message, agent_pbk: str, sender: str) → bool¶

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

Parameters

message – the agent message
agent_pbk – the public key of the agent

Returns

boolean indicating whether the message belongs to a registered dialogue

is_permitted_for_new_dialogue(message: aea.protocols.base.message.Message, known_pbks: List[str], sender: str) → bool¶

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

That is, the message has to - be a CFP, - have the correct msg id and message target, and - be from a known public key.

Parameters

message – the agent message
known_pbks – the list of known public keys

Returns

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

tac.agents.participant.v1.base.game_instance module¶

This class manages the state and some services related to the TAC for an agent.

class tac.agents.participant.v1.base.game_instance.GameInstance(agent_name: str, strategy: tac.agents.participant.v1.base.strategy.Strategy, mail_stats: aea.channels.oef.connection.MailStats, expected_version_id: str, services_interval: int = 10, pending_transaction_timeout: int = 10, dashboard: Optional[tac.gui.dashboards.agent.AgentDashboard] = None)¶

Bases: object

The GameInstance maintains state of the game from the agent’s perspective.

property agent_state¶: Get the agent state.

build_services_dict(is_supply: bool) → Optional[Dict[str, Sequence[str]]]¶

Build a dictionary containing the services demanded/supplied.

Parameters: is_supply – Boolean indicating whether the services are demanded or supplied.
Returns: a Dict.

build_services_query(is_searching_for_sellers: bool) → Optional[aea.protocols.oef.models.Query]¶

Build a query to search for services.

In particular, build the query to look for agents

which supply the agent’s demanded goods (i.e. sellers), or
which demand the agent’s supplied goods (i.e. buyers).

Parameters: is_searching_for_sellers – Boolean indicating whether the search is for sellers or buyers.
Returns: the Query, or None.

property dialogues¶: Get the dialogues.

property expected_version_id¶: Get the expected version id of the TAC.

property game_configuration¶: Get the game configuration.

property game_phase¶: Get the game phase.

generate_proposal(cfp_services: Dict[str, Union[bool, List[Any]]], is_seller: bool) → Optional[aea.protocols.oef.models.Description]¶

Wrap the function which generates proposals from a seller or buyer.

If there are locks as seller, it applies them.

Parameters

cfp_services – the query associated with the cfp.
is_seller – Boolean indicating the role of the agent.

Returns

a list of descriptions

get_goods_pbks(is_supply: bool) → Set[str]¶

Wrap the function which determines supplied and demanded good public keys.

Parameters: is_supply – Boolean indicating whether it is referencing the supplied or demanded public keys.
Returns: a list of good public keys

get_goods_quantities(is_supply: bool) → List[int]¶

Wrap the function which determines supplied and demanded good quantities.

Parameters: is_supply – Boolean indicating whether it is referencing the supplied or demanded quantities.
Returns: the vector of good quantities offered/requested.

get_service_description(is_supply: bool) → aea.protocols.oef.models.Description¶

Get the description of the supplied goods (as a seller), or the demanded goods (as a buyer).

Parameters: is_supply – Boolean indicating whether it is supply or demand.
Returns: the description (to advertise on the Service Directory).

init(game_data: tac.platform.game.base.GameData, agent_pbk: str) → None¶

Populate data structures with the game data.

Parameters

game_data – the game instance data
agent_pbk – the public key of the agent

Returns

None

property initial_agent_state¶: Get the initial agent state.

is_matching(cfp_services: Dict[str, Union[bool, List[Any]]], goods_description: aea.protocols.oef.models.Description) → bool¶

Check for a match between the CFP services and the goods description.

Parameters

cfp_services – the services associated with the cfp.
goods_description – a description of the goods.

Returns

Bool

is_profitable_transaction(transaction: tac.platform.game.base.Transaction, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → Tuple[bool, str]¶

Check if a transaction is profitable.

Is it a profitable transaction? - apply all the locks for role. - check if the transaction is consistent with the locks (enough money/holdings) - check that we gain score.

Parameters

transaction – the transaction
dialogue – the dialogue

Returns

True if the transaction is good (as stated above), False otherwise.

is_time_to_search_services() → bool¶

Check if the agent should search the service directory.

Returns: bool indicating the action

is_time_to_update_services() → bool¶

Check if the agent should update the service directory.

Returns: bool indicating the action

property last_search_time¶: Get the last services search time.

property last_update_time¶: Get the last services update time.

on_state_update(message: tac.platform.protocols.tac.message.TACMessage, agent_pbk: str) → None¶

Update the game instance with a State Update from the controller.

Parameters

state_update – the state update
agent_pbk – the public key of the agent

Returns

None

property search¶: Get the search.

property services_interval¶: Get the services interval.

state_after_locks(is_seller: bool) → tac.agents.participant.v1.base.states.AgentState¶

Apply all the locks to the current state of the agent.

This assumes, that all the locked transactions will be successful.

Parameters: is_seller – Boolean indicating the role of the agent.
Returns: the agent state with the locks applied to current state

stop()¶: Stop the services attached to the game instance.

property strategy¶: Get the strategy.

property world_state¶: Get the world state.

class tac.agents.participant.v1.base.game_instance.Search¶

Bases: object

This class deals with the search state.

get_next_id() → int¶

Generate the next search id and stores it.

Returns: a search id

property id¶: Get the search id.

tac.agents.participant.v1.base.handlers module¶

This module contains the message handler classes.

DialogueHandler: Handle the dialogue with another agent.
ControllerHandler: Handle the message exchange with the controller.
OEFHandler: Handle the message exchange with the OEF.

class tac.agents.participant.v1.base.handlers.ControllerHandler(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.actions.ControllerActions, tac.agents.participant.v1.base.reactions.ControllerReactions

Handle the message exchange with the controller.

handle_controller_message(envelope: aea.mail.base.Envelope) → None¶

Handle messages from the controller.

The controller does not expect a response for any of these messages.

Parameters: envelope – the controller message
Returns: None

class tac.agents.participant.v1.base.handlers.DialogueHandler(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.actions.DialogueActions, tac.agents.participant.v1.base.reactions.DialogueReactions

Handle the dialogue with another agent.

handle_dialogue_message(envelope: aea.mail.base.Envelope) → None¶

Handle messages from the other agents.

The agents expect a response.

Parameters: envelope – the envelope.
Returns: None

class tac.agents.participant.v1.base.handlers.OEFHandler(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str, rejoin: bool = False)¶

Bases: tac.agents.participant.v1.base.actions.OEFActions, tac.agents.participant.v1.base.reactions.OEFReactions

Handle the message exchange with the OEF.

handle_oef_message(envelope: aea.mail.base.Envelope) → None¶

Handle messages from the oef.

The oef does not expect a response for any of these messages.

Parameters: envelope – the OEF message
Returns: None

tac.agents.participant.v1.base.helpers module¶

This module contains helper methods for base agent implementations.

tac.agents.participant.v1.base.helpers.build_datamodel(good_pbks: List[str], is_supply: bool) → aea.protocols.oef.models.DataModel¶

Build a data model for supply and demand (i.e. for offered or requested goods).

Parameters

good_pbks – the list of good public keys
is_supply – Boolean indicating whether it is a supply or demand data model

Returns

the data model.

tac.agents.participant.v1.base.helpers.build_dict(good_pbks: Set[str], is_supply: bool) → Dict[str, Sequence[str]]¶

Build supply or demand services dictionary.

Parameters

good_pbks – the good public keys to put in the query
is_supply – Boolean indicating whether the services are for supply or demand.

Returns

the dictionary

tac.agents.participant.v1.base.helpers.build_query(good_pbks: Set[str], is_searching_for_sellers: bool) → aea.protocols.oef.models.Query¶

Build buyer or seller search query.

Specifically, build the search query

to look for sellers if the agent is a buyer, or
to look for buyers if the agent is a seller.

In particular, if the agent is a buyer and the demanded good public keys are {‘tac_good_0’, ‘tac_good_2’, ‘tac_good_3’}, the resulting constraint expression is:

tac_good_0 >= 1 OR tac_good_2 >= 1 OR tac_good_3 >= 1

That is, the OEF will return all the sellers that have at least one of the good in the query (assuming that the sellers are registered with the data model specified).

Parameters

good_pbks – the good public keys to put in the query
is_searching_for_sellers – Boolean indicating whether the query is for sellers (supply) or buyers (demand).

Returns

the query

tac.agents.participant.v1.base.helpers.dialogue_label_from_transaction_id(agent_pbk: str, transaction_id: str) → aea.helpers.dialogue.base.DialogueLabel¶

Recover dialogue label from transaction id.

Parameters

agent_pbk – the pbk of the agent.
transaction_id – the transaction id

Returns

a dialogue label

tac.agents.participant.v1.base.helpers.generate_transaction_id(agent_pbk: str, opponent_pbk: str, dialogue_label: aea.helpers.dialogue.base.DialogueLabel, agent_is_seller: bool) → str¶

Make a transaction id.

Parameters

agent_pbk – the pbk of the agent.
opponent_pbk – the public key of the opponent.
dialogue_label – the dialogue label
agent_is_seller – boolean indicating if the agent is a seller

Returns

a transaction id

tac.agents.participant.v1.base.helpers.get_goods_quantities_description(good_pbks: List[str], good_quantities: List[int], is_supply: bool) → aea.protocols.oef.models.Description¶

Get the TAC description for supply or demand.

That is, a description with the following structure: >>> description = { … “tac_good_0”: 1, … “tac_good_1”: 0, … #… … … } >>>

where the keys indicate the good_pbk and the values the quantity.

>>> desc = get_goods_quantities_description(['tac_good_0', 'tac_good_1', 'tac_good_2', 'tac_good_3'], [0, 0, 1, 2], True)
>>> desc.data_model.name == TAC_SUPPLY_DATAMODEL_NAME
True
>>> desc.values == {
...    "tac_good_0": 0,
...    "tac_good_1": 0,
...    "tac_good_2": 1,
...    "tac_good_3": 2}
...
True

Parameters

good_pbks – the public keys of the goods.
good_quantities – the quantities per good.
is_supply – True if the description is indicating supply, False if it’s indicating demand.

Returns

the description to advertise on the Service Directory.

tac.agents.participant.v1.base.interfaces module¶

This module defines the interfaces which a TAC compatible agent must implement.

class tac.agents.participant.v1.base.interfaces.ControllerActionInterface¶

Bases: object

This interface contains the methods to interact with the ControllerAgent.

abstract request_state_update() → None¶

Request a state update from the controller.

Returns: None

class tac.agents.participant.v1.base.interfaces.ControllerReactionInterface¶

Bases: object

This interface contains the methods to react to events from the ControllerAgent.

abstract on_cancelled() → None¶

Handle the cancellation of the competition from the TAC controller.

Returns: None

abstract on_dialogue_error(envelope: aea.mail.base.Envelope, sender: str) → None¶

Handle dialogue error event emitted by the controller.

Parameters

envelope – the dialogue error message
sender – the address of the sender

Returns

None

abstract on_start(message: aea.protocols.base.message.Message, sender: str) → None¶

On start of the competition, do the setup.

Parameters

message – the message
sender – the address of the sender

Returns

None

abstract on_state_update(message: aea.protocols.base.message.Message, sender: str) → None¶

On receiving the agent state update.

Parameters

message – the message
sender – the address of the sender

Returns

None

abstract on_tac_error(message: aea.protocols.base.message.Message, sender: str) → None¶

Handle error messages from the TAC controller.

Parameters

message – the message
sender – the address of the sender

Returns

None

abstract on_transaction_confirmed(message: aea.protocols.base.message.Message, sender: str) → None¶

On Transaction confirmed handler.

Parameters

message – the message
sender – the address of the sender

Returns

None

class tac.agents.participant.v1.base.interfaces.DialogueActionInterface¶

Bases: object

This interface contains the methods to interact with other agents.

class tac.agents.participant.v1.base.interfaces.DialogueReactionInterface¶

Bases: object

This interface contains the methods to react to events from other agents.

abstract on_existing_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to a message of an existing dialogue.

Parameters

message – the agent message
sender – the address of the sender

Returns

None

abstract on_new_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to a message for a new dialogue.

Given a new message, create a Dialogue object that specifies: - the protocol rules that messages must follow; - how the agent behaves in this dialogue.

Parameters

message – the agent message
sender – the address of the sender

Returns

None

abstract on_unidentified_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to a message of an unidentified dialogue.

Parameters

message – the agent message
sender – the address of the sender

Returns

None

class tac.agents.participant.v1.base.interfaces.OEFActionInterface¶

Bases: object

This interface contains the methods to interact with the OEF.

abstract register_service() → None¶

Register services to OEF Service Directory.

Returns: None

abstract search_for_tac() → None¶

Search for active TAC Controller.

Returns: None

abstract search_services() → None¶

Search services on OEF Service Directory.

Returns: None

abstract unregister_service() → None¶

Unregister service from OEF Service Directory.

Returns: None

abstract update_services() → None¶

Update services on OEF Service Directory.

Returns: None

class tac.agents.participant.v1.base.interfaces.OEFReactionInterface¶

Bases: object

This interface contains the methods to react to events from the OEF.

abstract on_dialogue_error(dialogue_error: aea.protocols.base.message.Message) → None¶

Handle a dialogue error message.

Parameters: dialogue_error_msg – the dialogue error message
Returns: None

abstract on_oef_error(oef_error: aea.protocols.base.message.Message) → None¶

Handle an OEF error message.

Parameters: oef_error – the oef error
Returns: None

abstract on_search_result(search_result: aea.protocols.base.message.Message) → None¶

Handle search results.

Parameters: search_result – the search result
Returns: None

tac.agents.participant.v1.base.negotiation_behaviours module¶

This module contains a class which implements the FIPA protocol for the TAC.

class tac.agents.participant.v1.base.negotiation_behaviours.FIPABehaviour(crypto: aea.crypto.base.Crypto, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, agent_name: str)¶

Bases: object

Specifies FIPA negotiation behaviours.

property agent_name¶: Get the agent name.

property crypto¶: Get the crypto.

property game_instance¶: Get the game instance.

on_accept(accept: aea.protocols.base.message.Message, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → List[aea.mail.base.Envelope]¶

Handle an Accept.

Parameters

accept – the message containing the Accept
dialogue – the dialogue

Returns

a Decline, or an Accept and a Transaction, or a Transaction (in a Message object)

on_cfp(cfp: aea.protocols.base.message.Message, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → aea.mail.base.Envelope¶

Handle a CFP.

Parameters

cfp – the message containing the CFP
dialogue – the dialogue

Returns

a Propose or a Decline

on_decline(decline: aea.protocols.base.message.Message, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → None¶

Handle a Decline.

Parameters

decline – the message containing the Decline
dialogue – the dialogue

Returns

None

on_match_accept(match_accept: aea.protocols.base.message.Message, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → List[aea.mail.base.Envelope]¶

Handle a matching Accept.

Parameters

match_accept – the envelope containing the MatchAccept
dialogue – the dialogue

Returns

a Transaction

on_propose(propose: aea.protocols.base.message.Message, dialogue: tac.agents.participant.v1.base.dialogues.Dialogue) → aea.mail.base.Envelope¶

Handle a Propose.

Parameters

propose – the message containing the Propose
dialogue – the dialogue

Returns

an Accept or a Decline

tac.agents.participant.v1.base.price_model module¶

A module containing a simple price model.

class tac.agents.participant.v1.base.price_model.GoodPriceModel¶

Bases: object

A class for a price model of a good.

get_price_expectation(constraint: float, is_seller: bool) → float¶

Get best price (given a constraint).

Parameters

constraint – the constraint on the price
is_seller – indicating whether the agent is a buyer or seller

Returns

the winning price

update(outcome: bool, price: float) → None¶

Update the respective bandit.

Parameters

price – the price to be updated
outcome – the negotiation outcome

Returns

None

class tac.agents.participant.v1.base.price_model.PriceBandit(price: float, beta_a: float = 1.0, beta_b: float = 1.0)¶

Bases: object

A class for a multi-armed bandit model of price.

sample() → float¶

Sample from the bandit.

Returns: the sampled value

update(outcome: bool) → None¶

Update the bandit.

Parameters: outcome – the outcome used for updating
Returns: None

tac.agents.participant.v1.base.reactions module¶

This module contains the classes which define the reactions of an agent.

ControllerReactions: The ControllerReactions class defines the reactions of an agent towards the ControllerAgent.
OEFReactions: The OEFReactions class defines the reactions of an agent towards the OEF.
DialogueReactions: The DialogueReactions class defines the reactions of an agent in the context of a Dialogue.

class tac.agents.participant.v1.base.reactions.ControllerReactions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.interfaces.ControllerReactionInterface

The ControllerReactions class defines the reactions of an agent towards the ControllerAgent.

on_cancelled() → None¶

Handle the cancellation of the competition from the TAC controller.

Returns: None

on_dialogue_error(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None¶

Handle dialogue error event emitted by the controller.

Parameters

message – the dialogue error message
sender – the address of the sender

Returns

None

on_start(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None¶

Handle the ‘start’ event emitted by the controller.

Parameters: game_data – the game data
Returns: None

on_state_update(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None¶

Handle ‘on state update’ event emitted by the controller.

Parameters: state_update – StateUpdate
Returns: None

on_tac_error(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None¶

Handle ‘on tac error’ event emitted by the controller.

Parameters: error – the error object
Returns: None

on_transaction_confirmed(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None¶

Handle ‘on transaction confirmed’ event emitted by the controller.

Parameters: tx_confirmation – the transaction confirmation
Returns: None

class tac.agents.participant.v1.base.reactions.DialogueReactions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str)¶

Bases: tac.agents.participant.v1.base.interfaces.DialogueReactionInterface

The DialogueReactions class defines the reactions of an agent in the context of a Dialogue.

on_existing_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to an existing dialogue.

Parameters: envelope – the agent message
Returns: None

on_new_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to a new dialogue.

Parameters: message – the agent message
Returns: None

on_unidentified_dialogue(message: aea.protocols.base.message.Message, sender: str) → None¶

React to an unidentified dialogue.

Parameters: message – agent message
Returns: None

class tac.agents.participant.v1.base.reactions.OEFReactions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, game_instance: tac.agents.participant.v1.base.game_instance.GameInstance, mailbox: aea.mail.base.MailBox, agent_name: str, rejoin: bool = False)¶

Bases: tac.agents.participant.v1.base.interfaces.OEFReactionInterface

The OEFReactions class defines the reactions of an agent towards the OEF.

on_dialogue_error(dialogue_error: aea.protocols.base.message.Message) → None¶

Handle a dialogue error message.

Parameters: dialogue_error – the dialogue error message
Returns: None

on_oef_error(oef_error: aea.protocols.base.message.Message) → None¶

Handle an OEF error message.

Parameters: oef_error – the oef error
Returns: None

on_search_result(search_result: aea.protocols.base.message.Message) → None¶

Split the search results from the OEF.

Parameters: search_result – the search result
Returns: None

tac.agents.participant.v1.base.states module¶

This module contains the classes which define the states of an agent.

AgentState: a class to hold the current state of an agent.
GoodState: a class to hold the current state of a good.
WorldState represent the state of the world from the perspective of the agent.

class tac.agents.participant.v1.base.states.AgentState(money: float, endowment: List[int], utility_params: List[float])¶

Bases: aea.helpers.state.base.AgentState

Represent the state of an agent during the game.

apply(transactions: List[tac.platform.game.base.Transaction], tx_fee: float) → tac.agents.participant.v1.base.states.AgentState¶

Apply a list of transactions to the current state.

Parameters: transactions – the sequence of transaction.
Returns: the final state.

check_transaction_is_consistent(tx: tac.platform.game.base.Transaction, tx_fee: float) → bool¶

Check if the transaction is consistent.

E.g. check that the agent state has enough money if it is a buyer or enough holdings if it is a seller. :return: True if the transaction is legal wrt the current state, false otherwise.

property current_holdings¶: Get current holding of each good.

get_score() → float¶

Compute the score of the current state.

The score is computed as the sum of all the utilities for the good holdings with positive quantity plus the money left. :return: the score.

get_score_diff_from_transaction(tx: tac.platform.game.base.Transaction, tx_fee: float) → float¶

Simulate a transaction and get the resulting score (taking into account the fee).

Parameters: tx – a transaction object.
Returns: the score.

update(tx: tac.platform.game.base.Transaction, tx_fee: float) → None¶

Update the agent state from a transaction.

Parameters

tx – the transaction.
tx_fee – the transaction fee.

Returns

None

property utility_params¶: Get utility parameter for each good.

class tac.agents.participant.v1.base.states.WorldState(opponent_pbks: List[str], good_pbks: List[str], initial_agent_state: tac.agents.participant.v1.base.states.AgentState)¶

Bases: aea.helpers.state.base.WorldState

Represent the state of the world from the perspective of the agent.

expected_price(good_pbk: str, marginal_utility: float, is_seller: bool, share_of_tx_fee: float) → float¶

Compute expectation of the price for the good given a constraint.

Parameters

good_pbk – the pbk of the good
marginal_utility – the marginal_utility from the good
is_seller – whether the agent is a seller or buyer
share_of_tx_fee – the share of the tx fee the agent pays

Returns

the expected price

update_on_cfp(query) → None¶: Update the world state when a new cfp is received.

update_on_declined_propose(transaction: tac.platform.game.base.Transaction) → None¶

Update the world state when a transaction (propose) is rejected.

Parameters: transaction – the transaction
Returns: None

update_on_initial_accept(transaction: tac.platform.game.base.Transaction) → None¶

Update the world state when a proposal is accepted.

Parameters: transaction – the transaction
Returns: None

update_on_proposal(proposal) → None¶: Update the world state when a new proposal is received.

tac.agents.participant.v1.base.stats_manager module¶

This module contains a class to handle statistics on the TAC.

class tac.agents.participant.v1.base.stats_manager.EndState¶

Bases: enum.Enum

This class defines the end states of a dialogue.

DECLINED_ACCEPT = 3¶

DECLINED_CFP = 1¶

DECLINED_PROPOSE = 2¶

SUCCESSFUL = 0¶

class tac.agents.participant.v1.base.stats_manager.StatsManager(mail_stats, dashboard, task_timeout: float = 2.0)¶

Bases: object

Class to handle statistics on the game.

add_dialogue_endstate(end_state: tac.agents.participant.v1.base.stats_manager.EndState, is_self_initiated: bool) → None¶

Add dialogue endstate stats.

Parameters

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

Returns

None

avg_search_result_counts() → float¶

Average the search result counts.

Returns: avg search result counts

avg_search_time() → float¶

Average the search timedeltas.

Returns: avg search time in seconds

property mail_stats¶: Get the mail stats.

negotiation_metrics_other() → numpy.ndarray¶

Get the negotiation metrics on other initiated dialogues.

Returns: an array containing the metrics

negotiation_metrics_self() → numpy.ndarray¶

Get the negotiation metrics on self initiated dialogues.

Returns: an array containing the metrics

property other_initiated_dialogue_stats¶: Get the stats dictionary on other initiated dialogues.

property self_initiated_dialogue_stats¶: Get the stats dictionary on self initiated dialogues.

start() → None¶

Start the stats manager.

Returns: None

stop() → None¶

Stop the stats manager.

Returns: None

update_stats_job() → None¶

Periodically update the dashboard.

Returns: None

tac.agents.participant.v1.base.strategy module¶

This module contains the abstract class defining an agent’s strategy for the TAC.

class tac.agents.participant.v1.base.strategy.RegisterAs¶

Bases: enum.Enum

This class defines the service registration options.

BOTH = 'both'¶

BUYER = 'buyer'¶

SELLER = 'seller'¶

class tac.agents.participant.v1.base.strategy.SearchFor¶

Bases: enum.Enum

This class defines the service search options.

BOTH = 'both'¶

BUYERS = 'buyers'¶

SELLERS = 'sellers'¶

class tac.agents.participant.v1.base.strategy.Strategy(register_as: tac.agents.participant.v1.base.strategy.RegisterAs = <RegisterAs.BOTH: 'both'>, search_for: tac.agents.participant.v1.base.strategy.SearchFor = <SearchFor.BOTH: 'both'>, is_world_modeling: bool = False)¶

Bases: object

This class defines an abstract strategy for the agent.

abstract demanded_good_pbks(good_pbks: List[str], current_holdings: List[int]) → Set[str]¶

Generate a set of good public keys which are demanded by the agent.

Parameters

good_pbks – a list of good public keys
current_holdings – a list of current good holdings

Returns

a set of public keys

abstract demanded_good_quantities(current_holdings: List[int]) → List[int]¶

Generate a list of quantities which are demanded by the agent.

Parameters: current_holdings – a list of current good holdings
Returns: a list of quantities

abstract get_proposals(good_pbks: List[str], current_holdings: List[int], utility_params: List[float], tx_fee: float, is_seller: bool, world_state: Optional[tac.agents.participant.v1.base.states.WorldState]) → List[aea.protocols.oef.models.Description]¶

Generate proposals from the agent in the role of seller/buyer.

Parameters

good_pbks – a list of good public keys
current_holdings – a list of current good holdings
utility_params – a list of utility params
tx_fee – the transaction fee
is_seller – Boolean indicating the role of the agent
world_state – the world state modelled by the agent

Returns

a list of proposals in Description form

is_acceptable_proposal(proposal_delta_score: float) → bool¶

Determine whether a proposal is acceptable to the agent.

Parameters: proposal_delta_score – the difference in score the proposal causes
Returns: a boolean indicating whether the proposal is acceptable or not

property is_registering_as_buyer¶: Check if the agent registers as a buyer on the OEF.

property is_registering_as_seller¶: Check if the agent registers as a seller on the OEF.

property is_searching_for_buyers¶: Check if the agent searches for buyers on the OEF.

property is_searching_for_sellers¶: Check if the agent searches for sellers on the OEF.

property is_world_modeling¶: Check if the world is modeled by the agent.

abstract supplied_good_pbks(good_pbks: List[str], current_holdings: List[int]) → Set[str]¶

Generate a set of good public keys which are supplied by the agent.

Parameters

good_pbks – a list of good public keys
current_holdings – a list of current good holdings

Returns

a set of public keys

abstract supplied_good_quantities(current_holdings: List[int]) → List[int]¶

Generate a list of quantities which are supplied by the agent.

Parameters: current_holdings – a list of current good holdings
Returns: a list of quantities

tac.agents.participant.v1.base.transaction_manager module¶

This module contains a class to manage transactions the agent has committed to at varying degrees.

class tac.agents.participant.v1.base.transaction_manager.TransactionManager(agent_name: str, pending_transaction_timeout: int = 30)¶

Bases: object

Class to handle pending transaction proposals/acceptances and locked transactions.

add_locked_tx(transaction: tac.platform.game.base.Transaction, as_seller: bool) → None¶

Add a lock (in the form of a transaction).

Parameters

transaction – the transaction
as_seller – whether the agent is a seller or not

Raises

AssertionError – if the transaction is already present.

Returns

None

add_pending_initial_acceptance(dialogue_label: aea.helpers.dialogue.base.DialogueLabel, proposal_id: int, transaction: tac.platform.game.base.Transaction) → None¶

Add an acceptance (in the form of a transaction) to the pending list.

Parameters

dialogue_label – the dialogue label associated with the proposal
proposal_id – the message id of the proposal
transaction – the transaction

Raises

AssertionError – if the pending acceptance is already present.

Returns

None

add_pending_proposal(dialogue_label: aea.helpers.dialogue.base.DialogueLabel, proposal_id: int, transaction: tac.platform.game.base.Transaction) → None¶

Add a proposal (in the form of a transaction) to the pending list.

Parameters

dialogue_label – the dialogue label associated with the proposal
proposal_id – the message id of the proposal
transaction – the transaction

Raises

AssertionError – if the pending proposal is already present.

Returns

None

cleanup_pending_transactions() → None¶

Remove all the pending messages (i.e. either proposals or acceptances) that have been stored for an amount of time longer than the timeout.

Returns: None

pop_locked_tx(transaction_id: str) → tac.platform.game.base.Transaction¶

Remove a lock (in the form of a transaction).

Parameters: transaction_id – the transaction id
Raises: AssertionError – if the transaction with the given transaction id has not been found.
Returns: the transaction

pop_pending_initial_acceptance(dialogue_label: aea.helpers.dialogue.base.DialogueLabel, proposal_id: int) → tac.platform.game.base.Transaction¶

Remove an acceptance (in the form of a transaction) from the pending list.

Parameters

dialogue_label – the dialogue label associated with the proposal
proposal_id – the message id of the proposal

Raises

AssertionError – if the pending acceptance is not present.

Returns

the transaction

pop_pending_proposal(dialogue_label: aea.helpers.dialogue.base.DialogueLabel, proposal_id: int) → tac.platform.game.base.Transaction¶

Remove a proposal (in the form of a transaction) from the pending list.

Parameters

dialogue_label – the dialogue label associated with the proposal
proposal_id – the message id of the proposal

Raises

AssertionError – if the pending proposal is not present.

Returns

the transaction

Module contents¶

This module contains the modules of a base implementation of an agent for TAC.

tac.agents.participant.v1.base package¶

Submodules¶

tac.agents.participant.v1.base.actions module¶

tac.agents.participant.v1.base.dialogues module¶

tac.agents.participant.v1.base.game_instance module¶

tac.agents.participant.v1.base.handlers module¶

tac.agents.participant.v1.base.helpers module¶

tac.agents.participant.v1.base.interfaces module¶

tac.agents.participant.v1.base.negotiation_behaviours module¶

tac.agents.participant.v1.base.price_model module¶

tac.agents.participant.v1.base.reactions module¶

tac.agents.participant.v1.base.states module¶

tac.agents.participant.v1.base.stats_manager module¶

tac.agents.participant.v1.base.strategy module¶

tac.agents.participant.v1.base.transaction_manager module¶

Module contents¶

Table of Contents

Related Topics