tac.agents.controller.base package

Submodules

tac.agents.controller.base.actions module

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

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

class tac.agents.controller.base.actions.OEFActions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, mailbox: aea.mail.base.MailBox, agent_name: str, tac_version_id: str)

Bases: tac.agents.controller.base.interfaces.OEFActionInterface

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

register_tac() → None

Register on the OEF as a TAC controller agent.

Returns

None.

tac.agents.controller.base.handlers module

This module contains the classes that implements the Controller agent behaviour.

The methods are split in three classes: - AgentMessageDispatcher: class to wrap the decoding procedure and dispatching the handling of the message to the right function. - GameHandler: handles an instance of the game. - TACMessageHandler: abstract class for a TACMessage handler. - RegisterHandler: class for a register handler. - UnregisterHandler: class for an unregister handler - TransactionHandler: class for a transaction handler. - GetStateUpdateHandler: class for a state update handler.

class tac.agents.controller.base.handlers.AgentMessageDispatcher(controller_agent: ControllerAgent)

Bases: object

Class to wrap the decoding procedure and dispatching the handling of the message to the right function.

handle_agent_message(envelope: aea.mail.base.Envelope) → None

Dispatch the TACMessage to the right handler.

If no handler is found for the provided type of TACMessage, return an “invalid TACMessage” error. If something bad happen, return a “generic” error.

Parameters

envelope – the envelope to handle

Returns

None

class tac.agents.controller.base.handlers.GameHandler(agent_name: str, crypto: aea.crypto.base.Crypto, mailbox: aea.mail.base.MailBox, monitor: tac.gui.monitor.Monitor, tac_parameters: tac.agents.controller.base.tac_parameters.TACParameters)

Bases: object

A class to manage a TAC instance.

property current_game

Get the game phase.

property game_phase

Get the game phase.

property is_game_running

Check if an instance of a game is already set up.

Returns

Return True if there is a game running, False otherwise.

notify_competition_cancelled()

Notify agents that the TAC is cancelled.

reset() → None

Reset the game.

simulation_dump() → None

Dump the details of the simulation.

Returns

None.

start_competition()

Create a game and send the game setting to every registered agent.

class tac.agents.controller.base.handlers.GetStateUpdateHandler(controller_agent: ControllerAgent)

Bases: tac.agents.controller.base.handlers.TACMessageHandler

Class for a state update handler.

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

Handle a ‘get agent state’ TACMessage.

If the public key is not registered, answer with an error message.

Parameters

• message – the ‘get agent state’ TACMessage.

• sender – the public key of the sender

Returns

None

class tac.agents.controller.base.handlers.OEFHandler(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, mailbox: aea.mail.base.MailBox, agent_name: str, tac_version: str)

Bases: tac.agents.controller.base.actions.OEFActions, tac.agents.controller.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

class tac.agents.controller.base.handlers.RegisterHandler(controller_agent: ControllerAgent)

Bases: tac.agents.controller.base.handlers.TACMessageHandler

Class for a register handler.

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

Handle a register message.

If the public key is already registered, answer with an error message.

Parameters

• message – the ‘get agent state’ TACMessage.

• sender – the public key of the sender

Returns

None

class tac.agents.controller.base.handlers.TACMessageHandler(controller_agent: ControllerAgent)

Bases: abc.ABC

Abstract class for a TACMessage handler.

abstract handle(message: tac.platform.protocols.tac.message.TACMessage, sender: str) → None

Handle a TACMessage from an OEF agent.

Parameters

• message – the ‘get agent state’ TACMessage.

• sender – the public key of the sender

Returns

None

class tac.agents.controller.base.handlers.TransactionHandler(controller_agent: ControllerAgent)

Bases: tac.agents.controller.base.handlers.TACMessageHandler

Class for a transaction handler.

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

Handle a transaction TACMessage message.

If the transaction is invalid (e.g. because the state of the game are not consistent), reply with an error.

Parameters

• message – the ‘get agent state’ TACMessage.

• sender – the public key of the sender

Returns

None

class tac.agents.controller.base.handlers.UnregisterHandler(controller_agent: ControllerAgent)

Bases: tac.agents.controller.base.handlers.TACMessageHandler

Class for an unregister handler.

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

Handle a unregister message.

If the public key is not registered, answer with an error message.

Parameters

• message – the ‘get agent state’ TACMessage.

• sender – the public key of the sender

Returns

None

tac.agents.controller.base.helpers module

This module contains the helpers methods for the controller agent.

tac.agents.controller.base.helpers.generate_good_pbk_to_name(nb_goods: int) → Dict[str, str]

Generate public keys for things.

Parameters

nb_goods – the number of things.

Returns

a dictionary mapping goods’ public keys to names.

tac.agents.controller.base.interfaces module

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

It cointains: - OEFReactionInterface: This interface contains the methods to react to events from the OEF. - OEFActionInterface: This interface contains the methods to interact with the OEF.

class tac.agents.controller.base.interfaces.OEFActionInterface

Bases: object

This interface contains the methods to interact with the OEF.

abstract register_tac() → None

Register tac to OEF Service Directory.

Returns

None

class tac.agents.controller.base.interfaces.OEFReactionInterface

Bases: object

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

abstract on_dialogue_error(dialogue_error: aea.mail.base.Envelope) → None

Handle a dialogue error message.

Parameters

dialogue_error_msg – the dialogue error message

Returns

None

abstract on_oef_error(oef_error: aea.mail.base.Envelope) → None

Handle an OEF error message.

Parameters

oef_error – the oef error

Returns

None

tac.agents.controller.base.reactions module

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

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

class tac.agents.controller.base.reactions.OEFReactions(crypto: aea.crypto.base.Crypto, liveness: aea.agent.Liveness, mailbox: aea.mail.base.MailBox, agent_name: str)

Bases: tac.agents.controller.base.interfaces.OEFReactionInterface

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

on_dialogue_error(envelope: aea.mail.base.Envelope) → None

Handle a dialogue error message.

Parameters

envelope – the dialogue error message

Returns

None

on_oef_error(envelope: aea.mail.base.Envelope) → None

Handle an OEF error message.

Parameters

envelope – the oef error

Returns

None

tac.agents.controller.base.states module

This module contains classes to represent the TAC game.

Classes:

• GameInitialization: a class to hold the initialization of a game. Immutable.

• Game: the class that manages an instance of a game (e.g. validate and settling transactions).

class tac.agents.controller.base.states.Game(configuration: tac.platform.game.base.GameConfiguration, initialization: tac.agents.controller.base.states.GameInitialization)

Bases: object

Class representing a game instance of TAC.

>>> version_id = '1'
>>> nb_agents = 3
>>> nb_goods = 3
>>> tx_fee = 1.0
>>> agent_pbk_to_name = {'tac_agent_0_pbk': 'tac_agent_0', 'tac_agent_1_pbk': 'tac_agent_1', 'tac_agent_2_pbk': 'tac_agent_2'}
>>> good_pbk_to_name = {'tac_good_0': 'Good 0', 'tac_good_1': 'Good 1', 'tac_good_2': 'Good 2'}
>>> money_amounts = [20, 20, 20]
>>> endowments = [
... [1, 1, 1],
... [2, 1, 1],
... [1, 1, 2]]
>>> utility_params = [
... [20.0, 40.0, 40.0],
... [10.0, 50.0, 40.0],
... [40.0, 30.0, 30.0]]
>>> eq_prices = [1.0, 2.0, 2.0]
>>> eq_good_holdings = [
... [1.0, 1.0, 1.0],
... [2.0, 1.0, 1.0],
... [1.0, 1.0, 2.0]]
>>> eq_money_holdings = [20.0, 20.0, 20.0]
>>> game_configuration = GameConfiguration(
...     version_id,
...     nb_agents,
...     nb_goods,
...     tx_fee,
...     agent_pbk_to_name,
...     good_pbk_to_name
... )
>>> game_initialization = GameInitialization(
...     money_amounts,
...     endowments,
...     utility_params,
...     eq_prices,
...     eq_good_holdings,
...     eq_money_holdings
... )
>>> game = Game(game_configuration, game_initialization)

Get the scores: >>> game.get_scores() {‘tac_agent_0_pbk’: 89.31471805599453, ‘tac_agent_1_pbk’: 93.36936913707618, ‘tac_agent_2_pbk’: 101.47867129923947}

property configuration

Get game configuration.

classmethod from_dict(d: Dict[str, Any]) → tac.agents.controller.base.states.Game

Get class instance from dictionary.

static generate_game(version_id: str, nb_agents: int, nb_goods: int, tx_fee: float, money_endowment: int, base_good_endowment: int, lower_bound_factor: int, upper_bound_factor: int, agent_pbk_to_name: Dict[str, str], good_pbk_to_name: Dict[str, str]) → tac.agents.controller.base.states.Game

Generate a game, the endowments and the utilites.

Parameters

• version_id – the version of the game.

• nb_agents – the number of agents.

• nb_goods – the number of goods.

• tx_fee – the fee to pay per transaction.

• money_endowment – the initial amount of money for every agent.

• base_good_endowment – the base amount of instances per good.

• lower_bound_factor – the lower bound of a uniform distribution.

• upper_bound_factor – the upper bound of a uniform distribution

• agent_pbk_to_name – the mapping of the public keys for the agents to their names.

• good_pbk_to_name – the mapping of the public keys for the goods to their names.

Returns

a game.

get_agent_state_from_agent_pbk(agent_pbk: str) → tac.agents.participant.v1.base.states.AgentState

Get agent state from agent pbk.

Parameters

agent_pbk – the agent’s pbk.

Returns

the agent state of the agent.

get_balances() → Dict[str, float]

Get the current balances.

get_equilibrium_summary() → str

Get equilibrium summary.

get_holdings_dict() → Dict[str, List[int]]

Get a dictionary of current holdings.

get_holdings_matrix() → List[List[int]]

Get the holdings matrix of shape (nb_agents, nb_goods).

Returns

the holdings matrix.

get_holdings_summary() → str

Get holdings summary.

>>> version_id = '1'
>>> nb_agents = 3
>>> nb_goods = 3
>>> tx_fee = 1.0
>>> agent_pbk_to_name = {'tac_agent_0_pbk': 'tac_agent_0', 'tac_agent_1_pbk': 'tac_agent_1', 'tac_agent_2_pbk': 'tac_agent_2'}
>>> good_pbk_to_name = {'tac_good_0': 'Good 0', 'tac_good_1': 'Good 1', 'tac_good_2': 'Good 2'}
>>> money_amounts = [20, 20, 20]
>>> endowments = [
... [1, 1, 1],
... [2, 1, 1],
... [1, 1, 2]]
>>> utility_params = [
... [20.0, 40.0, 40.0],
... [10.0, 50.0, 40.0],
... [40.0, 30.0, 30.0]]
>>> eq_prices = [1.0, 2.0, 2.0]
>>> eq_good_holdings = [
... [1.0, 1.0, 1.0],
... [2.0, 1.0, 1.0],
... [1.0, 1.0, 2.0]]
>>> eq_money_holdings = [20.0, 20.0, 20.0]
>>> game_configuration = GameConfiguration(
...     version_id,
...     nb_agents,
...     nb_goods,
...     tx_fee,
...     agent_pbk_to_name,
...     good_pbk_to_name
... )
>>> game_initialization = GameInitialization(
...     money_amounts,
...     endowments,
...     utility_params,
...     eq_prices,
...     eq_good_holdings,
...     eq_money_holdings
... )
>>> game = Game(game_configuration, game_initialization)
>>> print(game.get_holdings_summary(), end="")
tac_agent_0 [1, 1, 1]
tac_agent_1 [2, 1, 1]
tac_agent_2 [1, 1, 2]

Returns

a string representing the holdings for every agent.

get_initial_scores() → List[float]

Get the initial scores for every agent.

get_prices() → List[float]

Get the current prices.

get_scores() → Dict[str, float]

Get the current scores for every agent.

property initial_agent_states

Get initial state of each agent.

property initialization

Get game initialization.

is_transaction_valid(tx: tac.platform.game.base.Transaction) → bool

Check whether the transaction is valid given the state of the game.

Parameters

tx – the transaction.

Returns

True if the transaction is valid, False otherwise.

Raises

AssertionError: if the data in the transaction are not allowed (e.g. negative amount).

settle_transaction(tx: tac.platform.game.base.Transaction) → None

Settle a valid transaction.

>>> version_id = '1'
>>> nb_agents = 3
>>> nb_goods = 3
>>> tx_fee = 1.0
>>> agent_pbk_to_name = {'tac_agent_0_pbk': 'tac_agent_0', 'tac_agent_1_pbk': 'tac_agent_1', 'tac_agent_2_pbk': 'tac_agent_2'}
>>> good_pbk_to_name = {'tac_good_0': 'Good 0', 'tac_good_1': 'Good 1', 'tac_good_2': 'Good 2'}
>>> money_amounts = [20, 20, 20]
>>> endowments = [
... [1, 1, 1],
... [2, 1, 1],
... [1, 1, 2]]
>>> utility_params = [
... [20.0, 40.0, 40.0],
... [10.0, 50.0, 40.0],
... [40.0, 30.0, 30.0]]
>>> eq_prices = [1.0, 2.0, 2.0]
>>> eq_good_holdings = [
... [1.0, 1.0, 1.0],
... [2.0, 1.0, 1.0],
... [1.0, 1.0, 2.0]]
>>> eq_money_holdings = [20.0, 20.0, 20.0]
>>> game_configuration = GameConfiguration(
...     version_id,
...     nb_agents,
...     nb_goods,
...     tx_fee,
...     agent_pbk_to_name,
...     good_pbk_to_name,
... )
>>> game_initialization = GameInitialization(
...     money_amounts,
...     endowments,
...     utility_params,
...     eq_prices,
...     eq_good_holdings,
...     eq_money_holdings
... )
>>> game = Game(game_configuration, game_initialization)
>>> agent_state_0 = game.agent_states['tac_agent_0_pbk'] # agent state of tac_agent_0
>>> agent_state_1 = game.agent_states['tac_agent_1_pbk'] # agent state of tac_agent_1
>>> agent_state_2 = game.agent_states['tac_agent_2_pbk'] # agent state of tac_agent_2
>>> agent_state_0.balance, agent_state_0.current_holdings
(20, [1, 1, 1])
>>> agent_state_1.balance, agent_state_1.current_holdings
(20, [2, 1, 1])
>>> agent_state_2.balance, agent_state_2.current_holdings
(20, [1, 1, 2])
>>> tx = Transaction('some_tx_id', True, 'tac_agent_1_pbk', 15, {'tac_good_0': 1, 'tac_good_1': 0, 'tac_good_2': 0}, 'tac_agent_0_pbk')
>>> game.settle_transaction(tx)
>>> agent_state_0.balance, agent_state_0.current_holdings
(4.5, [2, 1, 1])
>>> agent_state_1.balance, agent_state_1.current_holdings
(34.5, [1, 1, 1])

Parameters

tx – the game transaction.

Returns

None

Raises

AssertionError if the transaction is not valid.

to_dict() → Dict[str, Any]

Get a dictionary from the object.

class tac.agents.controller.base.states.GameInitialization(initial_money_amounts: List[float], endowments: List[List[int]], utility_params: List[List[float]], eq_prices: List[float], eq_good_holdings: List[List[float]], eq_money_holdings: List[float])

Bases: object

Class containing the game initialization of a TAC instance.

property endowments

Get endowments of the agents.

property eq_good_holdings

Get theoretical equilibrium good holdings (a benchmark).

property eq_money_holdings

Get theoretical equilibrium money holdings (a benchmark).

property eq_prices

Get theoretical equilibrium prices (a benchmark).

classmethod from_dict(d: Dict[str, Any]) → tac.agents.controller.base.states.GameInitialization

Instantiate an object from the dictionary.

property initial_money_amounts

Get list of the initial amount of money of every agent.

to_dict() → Dict[str, Any]

Get a dictionary from the object.

property utility_params

Get utility parameter list of the agents.

tac.agents.controller.base.tac_parameters module

TACParameters: this class contains the parameters for the TAC.

class tac.agents.controller.base.tac_parameters.TACParameters(min_nb_agents: int = 5, money_endowment: int = 200, nb_goods: int = 5, tx_fee: float = 1.0, base_good_endowment: int = 2, lower_bound_factor: int = 1, upper_bound_factor: int = 1, start_time: datetime.datetime = datetime.datetime(2021, 2, 21, 20, 53, 29, 381831), registration_timeout: int = 10, competition_timeout: int = 20, inactivity_timeout: int = 10, whitelist: Optional[Set[str]] = None, data_output_dir: str = 'data', version_id: str = '9061')

Bases: object

This class contains the parameters for the TAC.

property base_good_endowment

Minimum endowment of each agent for each good.

property competition_timedelta

Time delta of the competition timeout.

property competition_timeout

Timeout of competition.

property data_output_dir

Get data output dir.

property end_time

TAC end time.

property inactivity_timedelta

Time delta of the inactivity timeout.

property inactivity_timeout

Timeout of agent inactivity from controller perspective (no received transactions).

property lower_bound_factor

Lower bound of a uniform distribution.

property min_nb_agents

Minimum number of agents required for a TAC instance.

property money_endowment

Money endowment per agent for a TAC instance.

property nb_goods

Good number for a TAC instance.

property registration_timedelta

Time delta of the registration timeout.

property registration_timeout

Timeout of registration.

property start_time

TAC start time.

property tx_fee

Transaction fee for a TAC instance.

property upper_bound_factor

Upper bound of a uniform distribution.

property version_id

Version id.

property whitelist

Whitelist of agent public keys allowed into the TAC instance.

Module contents

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