SCMLAWI

class scml.scml2019.SCMLAWI(world, agent)[source]

Bases: negmas.situated.awi.AgentWorldInterface

A single contact point between SCML agents and the world simulation.

The agent can access the world simulation in one of two ways:

  1. Attributes and methods available in this Agent-SCML2020World-Interface

  2. Attributes and methods in the FactoryManager object itself which provide handy shortcuts to the agent-world interface

Attributes

Simulation settings

  • current_step : Current simulation step

  • default_signing_delay : The grace period allowed between contract conclusion and signature by default (i.e. if not agreed upon during the negotiation)

  • n_steps : Total number of simulation steps.

  • relative_time : The fraction of total simulation time elapsed (it will be a number between 0 and 1)

Production Graph

  • products : A list of Product objects giving all products defined in the world simulation

  • processes : A list of Process objects giving all products defined in the world simulation

Agent Related

  • state : The current private state available to the agent. In SCML it is a FactoryState object.

Methods

Production Control

  • schedule_job : Schedules a Job for production sometime in the future

  • schedule_production : Schedules production using profile number instead of a Job object

  • cancel_production : Cancels already scheduled production (if it did not start yet) or stop a running production.

  • execute : A general function to execute any command on the factory. There is no need to directly call this function as the SCMLAWI provides convenient functions (e.g. schedule_job , hide_funds , etc) to achieve the same goal without having to worry about creating Action objects

Storage and Wallet Control

  • hide_funds : Hides funds from the view of the simulator. Note that when bankruptcy is considered, hidden funds are visible to the simulator.

  • hide_inventory : Hides inventory from the view of the simulator. Note that when bankruptcy is considered, hidden funds are visible to the simulator.

  • unhide_funds : Un-hides funds hidden earlier with a call to hide_funds

  • unhide_inventory : Un-hides inventory hidden earlier with a call to hide_inventory

Negotiation and CFP Control

  • register_cfp : Registers a Call-for-Proposals on the bulletin board.

  • remove_cfp : Removes a Call-for-Proposals from the bulletin board.

  • request_negotiation : Requests a negotiation based on the content of a CFP published on the bulletin-board. *It is recommended not to use this method directly and to request negotiations using the request_negotiation method of FactoryManager (i.e. use self.request_negotiation instead of self.awi.request_negotiation). This makes it possible for NegMAS to keep track of existing requested_negotiations and running_negotiations for you.

Notification Control

  • receive_financial_reports : Register/unregisters interest in receiving financial reports for an agent, a set of agents or all agents.

  • register_interest : registers interest in receiving CFPs about a set of products. By default all FactoryManager objects are registered to receive all CFPs for any product they can produce or need to consumer according to their line-profiles.

  • unregister_interest : unregisters interest in receiving CFPs about a set of products.

Information about Other Agents

  • is_bankrupt : Asks about the bankruptcy status of an agent

  • receive_financial_reports : Register/unregisters interest in receiving financial reports for an agent, a set of agents or all agents.

  • reports_at : reads all financial reports produced at a given time-step

  • reports_for : reads all financial reports of a given agent

Financial Control

  • evaluate_insurance : Asks for the premium to be paid for insuring against partner breaches for a given contract

  • buy_insurance : Buys an insurance against partner breaches for a given contract

Bulletin-Board

The bulletin-board is a key-value store. These methods allows the agent to interact with it. The `SCMLAWI` provides convenient functions for recording to the bulletin-board so you mostly need to use read/query functions.

  • bb_read : Reads a complete section or a single value from the bulletin-board

  • bb_query : Returns all records in the given section/sections of the bulletin-board that satisfy a query

  • bb_record : Registers a record in the bulletin-board.

  • bb_remove : Removes a record from the bulletin-board.

The following list of sections are available in the SCML Bulletin-Board (Use the exact string for the section parameter of any method starting with bb_):

  • cfps: All CFPs currently on the board. The key is the CFP ID

  • products: A list of all products. The key is the product index/ID

  • processes: A list of all processes. The key is the product index/ID

  • bankruptcy: The bankruptcy list giving names of all bankrupt agents.

  • reports_time: Financial reports indexed by time.

  • reports_agent: Financial reports indexed by agent

  • breaches: Breach-list indexed by breach ID giving all breaches committed in the system

  • settings: Static settings of the simulation.

    The following settings are currently available:

    • breach_penalty_society: Penalty of breaches paid to society (as a fraction of contract value). This is always paid for every breach whether or not there is a negotiated breach.

    • breach_penalty_victim: Penalty of breaches paid to victim (as a fraction of contract value). This is always paid for every breach whether or not there is a negotiated breach.

    • immediate_negotiations: Whether negotiations start immediately when registered (the other possibility – which is the default – is for them to start at the next production step).

    • negotiation_speed_multiple: Number of negotiation steps that finish in a single production step.

    • negotiation_n_steps: Maximum allowed number of steps (rounds) in any negotiation

    • negotiation_step_time_limit: The maximum real-time allowed for each negotiation step (round)

    • negotiation_time_limit: The time limit for a complete negotiation.

    • transportation_delay: Transportation delay when products are moved between factories. Default is zero.

    • transfer_delay: The delay in transferring funds between factories when executing a contract. Default is zero.

    • n_steps: Number of simulation steps

    • time_limit: Time limit for the complete simulation

  • stats: Global statistics about the simulation. Not available for SCML 2019 league.

Logging

  • logerror : Logs an error in the world simulation log file

  • logwarning : Logs a warning in the world simulation log file

  • loginfo : Logs information in the world simulation log file

  • logdebug : Logs debug information in the world simulation log file

Attributes Summary

accepted_negotiation_requests

A list of negotiation requests sent to this agent that are already accepted by it.

current_step

Current simulation step

default_signing_delay

rtype

int

initialized

Was the agent initialized (i.e.

n_steps

Number of steps in a simulation

negotiation_requests

A list of the negotiation requests sent by this agent that are not yet accepted or rejected.

params

Returns the basic parameters of the world

processes

Processes in the world

products

Products in the world

relative_time

Relative time of the simulation going from 0 to 1

requested_negotiations

The negotiations currently requested by the agent.

running_negotiations

The negotiations currently requested by the agent.

settings

state

Returns the private state of the agent in that world.

unsigned_contracts

All contracts that are not yet signed.

Methods Summary

bb_query(section, query[, query_keys])

Returns all records in the given section/sections of the bulletin-board that satisfy the query

bb_read(section, key)

Reads the value associated with given key from the bulletin board

bb_record(section, value[, key])

Records data in the given section of the bulletin board

bb_remove(section, *[, query, key, ...])

Removes a value or a set of values from the bulletin Board

buy_insurance(contract)

Buys insurance for the contract by the premium calculated by the insurance company.

cancel_production(line, step, contract[, ...])

Stops/cancels production scheduled at the given line at the given time.

evaluate_insurance(contract[, t])

Can be called to evaluate the premium for insuring the given contract against breaches committed by others

execute(action[, callback])

Executes an action in the world simulation

hide_funds(amount)

Hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.

hide_inventory(product, quantity)

Hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.

is_bankrupt(agent_id)

Checks whether the given agent is bankrupt

logdebug(msg)

Logs a WARNING message

logdebug_agent(msg)

Logs a WARNING message to the agent's log

logerror(msg)

Logs a WARNING message

logerror_agent(msg)

Logs a WARNING message to the agent's log

loginfo(msg)

Logs an INFO message

loginfo_agent(msg)

Logs an INFO message to the agent's log

logwarning(msg)

Logs a WARNING message

logwarning_agent(msg)

Logs a WARNING message to the agent's log

receive_financial_reports([receive, agents])

Registers/unregisters interest in receiving financial reports

register_cfp(cfp)

Registers a CFP

register_interest(products)

registers interest in receiving callbacks about CFPs related to these products

remove_cfp(cfp)

Removes a CFP

reports_at([step])

Gets all financial reports of all agents at a given step

reports_for(agent_id)

Gets all financial reports of an agent (in the order of their publication)

request_negotiation(cfp, req_id[, roles, ...])

Requests a negotiation with the publisher of a given CFP

request_negotiation_about(issues, partners, ...)

Overrides the method of the same name in the base class to disable it in SCM Worlds.

run_negotiation(issues, partners, negotiator)

Runs a negotiation until completion

run_negotiations(issues, partners, negotiators)

Requests to run a set of negotiations simultaneously.

schedule_job(job, contract)

Schedules production using a Job object.

schedule_production(profile, step[, ...])

Schedules production on the agent's factory

stop_production(line, step, contract[, override])

Stops/cancels production scheduled at the given line at the given time.

unhide_funds(amount)

Un-hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.

unhide_inventory(product, quantity)

Un-hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.

unregister_interest(products)

registers interest in receiving callbacks about CFPs related to these products

Attributes Documentation

accepted_negotiation_requests

A list of negotiation requests sent to this agent that are already accepted by it.

Remarks:
  • These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

Return type

list[NegotiationRequestInfo]

current_step

Current simulation step

Return type

int

default_signing_delay
Return type

int

initialized

Was the agent initialized (i.e. was init_() called)

Return type

bool

n_steps

Number of steps in a simulation

Return type

int

negotiation_requests

A list of the negotiation requests sent by this agent that are not yet accepted or rejected.

Remarks:
  • These negotiations did not start yet as they are still not accepted by all partners. Once that happens, they will be moved to running_negotiations

Return type

list[NegotiationRequestInfo]

params

Returns the basic parameters of the world

Return type

dict[str, Any]

processes

Processes in the world

Return type

List[Process]

products

Products in the world

Return type

List[Product]

relative_time

Relative time of the simulation going from 0 to 1

Return type

float

requested_negotiations

The negotiations currently requested by the agent.

Return type

list[NegotiationRequestInfo]

Returns

A list of negotiation request information objects (NegotiationRequestInfo)

running_negotiations

The negotiations currently requested by the agent.

Return type

list[RunningNegotiationInfo]

Returns

A list of negotiation information objects (RunningNegotiationInfo)

settings
state

Returns the private state of the agent in that world.

In the SCML world, that is a reference to its factory. You are allowed to read information from the returned Factory but not to modify it or call ANY methods on it that modify the state.

Return type

FactoryState

unsigned_contracts

All contracts that are not yet signed.

Return type

list[Contract]

Methods Documentation

bb_query(section, query, query_keys=False)

Returns all records in the given section/sections of the bulletin-board that satisfy the query

Parameters
  • section (str | list[str] | None) – Either a section name, a list of sections or None specifying ALL public sections (see remarks)

  • query (Any) – The query which is USUALLY a dict with conditions on it when querying values and a RegExp when

  • keys (querying) –

  • query_keys – Whether the query is to be applied to the keys or values.

Returns

value pairs giving all records that satisfied the given requirements.

Return type

  • A dictionary with key

Remarks:

  • A public section is a section with a name that does not start with an underscore

  • If a set of sections is given, and two records in different sections had the same key, only one of them will be returned

  • Key queries use regular expressions and match from the beginning using the standard re.match function

bb_read(section, key)

Reads the value associated with given key from the bulletin board

Parameters
  • section (str) – section name

  • key (str) – key

Return type

Optional[Any]

Returns

Content of that key in the bulletin-board

bb_record(section, value, key=None)

Records data in the given section of the bulletin board

Parameters
  • section (str) – section name (can contain subsections separated by ‘/’)

  • key (Optional[str]) – The key

  • value (Any) – The value

Return type

None

bb_remove(section, *, query=None, key=None, query_keys=False, value=None)

Removes a value or a set of values from the bulletin Board

Parameters
  • section (list[str] | str | None) – The section

  • query (Optional[Any]) – the query to use to select what to remove

  • key (Optional[str]) – the key to remove (no need to give a full query)

  • query_keys (bool) – Whether to apply the query (if given) to keys or values

  • value (Optional[Any]) – Value to be removed

Returns

Success of failure

Return type

bool

buy_insurance(contract)[source]

Buys insurance for the contract by the premium calculated by the insurance company.

Remarks:

The agent can call evaluate_insurance to find the premium that will be used.

Return type

bool

cancel_production(line, step, contract, override=True)

Stops/cancels production scheduled at the given line at the given time.

Parameters
  • line (int) – One of the factory lines (index)

  • step (int) – Step to stop/cancel production at

evaluate_insurance(contract, t=None)[source]

Can be called to evaluate the premium for insuring the given contract against breaches committed by others

Parameters
  • contract (Contract) – hypothetical contract

  • t (Optional[int]) – time at which the policy is to be bought. If None, it means current step

Return type

Optional[float]

execute(action, callback=None)

Executes an action in the world simulation

Return type

bool

hide_funds(amount)[source]

Hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.

Parameters

amount (float) – The amount of money to hide

Remarks:

  • if the current cash in the agent’s wallet is less than the amount to be hidden, all the cash is hidden.

  • hiding is always immediate

Return type

None

hide_inventory(product, quantity)[source]

Hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.

Parameters
  • product (int) – product index

  • quantity (int) – the amount of the product to hide

Remarks:

  • if the current quantity in storage of the product is less than the amount to be hidden, whatever quantity exists is hidden

  • hiding is always immediate

Return type

None

is_bankrupt(agent_id)[source]

Checks whether the given agent is bankrupt

Parameters

agent_id (str) – Agent ID

Return type

bool

Returns

The bankruptcy state of the agent

logdebug(msg)

Logs a WARNING message

Parameters

msg (str) – The message to log

Returns:

Return type

None

logdebug_agent(msg)

Logs a WARNING message to the agent’s log

Parameters

msg (str) – The message to log

Returns:

Return type

None

logerror(msg)

Logs a WARNING message

Parameters

msg (str) – The message to log

Returns:

Return type

None

logerror_agent(msg)

Logs a WARNING message to the agent’s log

Parameters

msg (str) – The message to log

Returns:

Return type

None

loginfo(msg)

Logs an INFO message

Parameters

msg (str) – The message to log

Returns:

Return type

None

loginfo_agent(msg)

Logs an INFO message to the agent’s log

Parameters

msg (str) – The message to log

Returns:

Return type

None

logwarning(msg)

Logs a WARNING message

Parameters

msg (str) – The message to log

Returns:

Return type

None

logwarning_agent(msg)

Logs a WARNING message to the agent’s log

Parameters

msg (str) – The message to log

Returns:

Return type

None

receive_financial_reports(receive=True, agents=None)[source]

Registers/unregisters interest in receiving financial reports

Parameters
  • receive (bool) – True to receive and False to stop receiving

  • agents (Optional[List[str]]) – If given reception is enabled/disabled only for the given set of agents.

Remarks:

  • by default financial reports are not sent to any agents. To opt-in to receive financial reports, call this method.

Return type

None

register_cfp(cfp)[source]

Registers a CFP

Return type

None

register_interest(products)[source]

registers interest in receiving callbacks about CFPs related to these products

Return type

None

remove_cfp(cfp)[source]

Removes a CFP

Return type

bool

reports_at(step=None)[source]

Gets all financial reports of all agents at a given step

Parameters

step (Optional[int]) – Step at which the reports are required. If None, the last set of reports is returned

Return type

Dict[str, FinancialReport]

Returns

A dictionary with agent IDs in keys and their financial reports at the given time as values

reports_for(agent_id)[source]

Gets all financial reports of an agent (in the order of their publication)

Parameters

agent_id (str) – Agent ID

Returns:

Return type

List[FinancialReport]

request_negotiation(cfp, req_id, roles=None, mechanism_name=None, mechanism_params=None)[source]

Requests a negotiation with the publisher of a given CFP

Parameters
  • cfp (CFP) – The CFP to negotiate about

  • req_id (str) – A string that is passed back to the caller in all callbacks related to this negotiation

  • roles (Optional[List[str]]) – The roles of the CFP publisher and the agent (in that order). By default no roles are passed (None)

  • mechanism_name (Optional[str]) – The mechanism type to use. If not given the default mechanism from the world will be used

  • mechanism_params (Optional[Dict[str, Any]]) – Parameters of the mechanism

Return type

bool

Returns

Success of failure of the negotiation request

Remarks:

  • The SCML2019Agent class implements another request_negotiation method that does not receive a req_id. This helper method is recommended as it generates the required req_id and passes it keeping track of requested negotiations (and later of running negotiations). Call this method direclty only if you do not intend to use the requested_negotiations and running_negotiations properties of the SCML2019Agent class

request_negotiation_about(issues, partners, req_id, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)[source]

Overrides the method of the same name in the base class to disable it in SCM Worlds.

Do not call this method

run_negotiation(issues, partners, negotiator, preferences=None, caller_role=None, roles=None, annotation=None, mechanism_name=None, mechanism_params=None)

Runs a negotiation until completion

Parameters
  • partners (Collection[str | Agent]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent or as a list containing a single string/Agent, then he caller will be added at the beginning of the list. This will only be done if roles was passed as None.

  • negotiator (Negotiator) – The negotiator to be used in the negotiation

  • preferences (Optional[Preferences]) – The preferences. Only needed if the negotiator does not already know it

  • caller_role (Optional[str]) – The role of the caller in the negotiation

  • issues (Collection[Issue]) – Negotiation issues

  • annotation (Optional[dict[str, Any]]) – Extra information to be passed to the partners when asking them to join the negotiation

  • partners – A list of partners to participate in the negotiation

  • roles (Optional[Collection[str]]) – The roles of different partners. If None then each role for each partner will be None

  • mechanism_name (Optional[str]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the

  • None (must also be) –

  • my_role (then roles and) –

  • None

  • mechanism_params (Optional[dict[str, Any]]) – A dict of parameters used to initialize the mechanism object

Return type

tuple[Contract, NegotiatorMechanismInterface] | None

Returns

A Tuple of a contract and the nmi of the mechanism used to get it in case of success. None otherwise

run_negotiations(issues, partners, negotiators, preferences=None, caller_roles=None, roles=None, annotations=None, mechanism_names=None, mechanism_params=None, all_or_none=False)

Requests to run a set of negotiations simultaneously. Returns after all negotiations are run to completion

Parameters
  • partners (list[list[str | Agent]]) – A list of partners to participate in the negotiation. Note that the caller itself may not be in this list which makes it possible for an agent to request a negotaition that it does not participate in. If that is not to be allowed in some world, override this method and explicitly check for these kinds of negotiations and return False. If partners is passed as a single string/Agent or as a list containing a single string/Agent, then he caller will be added at the beginning of the list. This will only be done if roles was passed as None.

  • issues (list[Issue] | list[list[Issue]]) – Negotiation issues

  • negotiators (list[Negotiator]) – The negotiator to be used in the negotiation

  • ufuns – The utility function. Only needed if the negotiator does not already know it

  • caller_roles (Optional[list[str]]) – The role of the caller in the negotiation

  • annotations (Optional[list[dict[str, Any] | None]]) – Extra information to be passed to the partners when asking them to join the negotiation

  • partners – A list of partners to participate in the negotiation

  • roles (Optional[list[list[str] | None]]) – The roles of different partners. If None then each role for each partner will be None

  • mechanism_names (Union[str, list[str], None]) – Name of the mechanism to use. It must be one of the mechanism_names that are supported by the

  • None (must also be) –

  • my_role (then roles and) –

  • None

  • mechanism_params (Union[dict[str, Any], list[dict[str, Any]], None]) – A dict of parameters used to initialize the mechanism object

  • all_or_none (bool) – If true, either no negotiations will be started execpt if all partners accepted

Returns

contract (None for failure) and nmi (The mechanism info [None if the corresponding partner refused to negotiation])

Return type

A list of tuples each with two values

schedule_job(job, contract)[source]

Schedules production using a Job object. This can be used to schedule any kind of job

Parameters
  • job (Job) – The job description

  • contract (Optional[Contract]) – The contract for which the job is scheduled (optional)

Remarks:

  • Notice that actions that require the profile member of Job (run) never use the line member and vice versa.

schedule_production(profile, step, contract=None, override=True)[source]

Schedules production on the agent’s factory

Parameters
  • profile (int) – Index of the profile in the agent’s compiled_profiles list

  • step (int) – The step to start production according to the given profile

  • contract (Optional[Contract]) – The contract for which the production is scheduled (optional)

  • override (bool) – Whether to override existing production jobs schedules at the same time.

Return type

None

stop_production(line, step, contract, override=True)[source]

Stops/cancels production scheduled at the given line at the given time.

Parameters
  • line (int) – One of the factory lines (index)

  • step (int) – Step to stop/cancel production at

  • contract (Optional[Contract]) – The contract for which the job is scheduled (optional)

  • override (bool) – Whether to override existing production jobs schedules at the same time.

unhide_funds(amount)[source]

Un-hides the given amount of money so that it is not accessible by the simulator and does not appear in reports etc.

Parameters

amount (float) – The amount of money to unhide

Remarks:

  • if the current cash in the agent’s wallet is less than the amount to be hidden, all the cash is hidden.

  • hiding is always immediate

Return type

None

unhide_inventory(product, quantity)[source]

Un-hides the given quantity of the given product so that it is not accessible by the simulator and does not appear in reports etc.

Parameters
  • product (int) – product index

  • quantity (int) – the amount of the product to hide

Remarks:

  • if the current quantity in storage of the product is less than the amount to be hidden, whatever quantity exists is hidden

  • hiding is always immediate

Return type

None

unregister_interest(products)[source]

registers interest in receiving callbacks about CFPs related to these products

Return type

None