scml.scml2019.agent =================== .. py:module:: scml.scml2019.agent .. autoapi-nested-parse:: The base class agent needed for all SCML agents. Classes ------- .. autoapisummary:: scml.scml2019.agent.SCML2019Agent Module Contents --------------- .. py:class:: SCML2019Agent(name: Optional[str] = None, ufun: Optional[negmas.UtilityFunction] = None) Bases: :py:obj:`negmas.situated.Agent` The base for all SCM Agents .. py:attribute:: line_profiles :type: Dict[int, scml.scml2019.common.ManufacturingProfileCompiled] A mapping specifying for each `Line` index, all the profiles used to run it in the factory .. py:attribute:: process_profiles :type: Dict[int, scml.scml2019.common.ManufacturingProfileCompiled] A mapping specifying for each `Process` index, all the profiles used to run it in the factory .. py:attribute:: producing :type: Dict[int, List[scml.scml2019.common.ProductManufacturingInfo]] Mapping from a product to all manufacturing processes that can generate it .. py:attribute:: consuming :type: Dict[int, List[scml.scml2019.common.ProductManufacturingInfo]] Mapping from a product to all manufacturing processes that can consume it .. py:attribute:: compiled_profiles :type: List[scml.scml2019.common.ManufacturingProfileCompiled] :value: [] All the profiles to be used by the factory belonging to this agent compiled to use indices .. py:attribute:: immediate_negotiations :value: False Whether or not negotiations start immediately upon registration (default is to start on the next production step) .. py:attribute:: negotiation_speed_multiple :type: int :value: 1 The number of negotiation rounds (steps) conducted in a single production step .. py:attribute:: transportation_delay :type: int :value: 0 Transportation delay in the system. Default is zero .. py:attribute:: products :type: List[scml.scml2019.common.Product] :value: [] List of products in the system .. py:attribute:: processes :type: List[scml.scml2019.common.Process] :value: [] List of processes in the system .. py:property:: awi :type: scml.scml2019.awi.SCMLAWI Returns the Agent-SCML2020World-Interface through which the agent does all of its actions in the world. A single excption is request_negotiation for which it is recommended to actually call the helper method on the agent itself instead of directly calling the AWI version. .. py:method:: reset() .. py:method:: is_clean() -> bool .. py:method:: init_() The initialization function called by the world directly. It does the following actions by default: 1. copies some of the static world settings to the agent to make them available without calling the AWI. 2. prepares production related properties like producing, consuming, line_profiles, compiled_profiles, etc. 3. registers interest in all products that the agent can produce or consume in its factory. 4. finally it calls any custom initialization logic implemented in `init`() .. seealso:: `init`, `step` .. py:method:: can_expect_agreement(cfp: scml.scml2019.common.CFP, margin: int) Checks if it is possible in principle to get an agreement on this CFP by the time it becomes executable :param margin: :param cfp: Returns: .. py:method:: _create_annotation(cfp: scml.scml2019.common.CFP, partner: str = None) Creates full annotation based on a cfp that the agent is receiving :param cfp: The call for proposal to create annotation about :param partner: The partner who requested the negotiation Remarks: - If the annotation is to be created for a CFP that was published by self, partner must be passed .. py:method:: _respond_to_negotiation_request(initiator: str, partners: List[str], issues: List[negmas.outcomes.Issue], annotation: Dict[str, Any], mechanism: negmas.common.NegotiatorMechanismInterface, role: Optional[str], req_id: Optional[str]) -> Optional[negmas.negotiators.Negotiator] Called by the mechanism to ask for joining a negotiation. The agent can refuse by returning a None :param initiator: The ID of the agent that initiated the negotiation request :param partners: The partner list (will include this agent) :param issues: The list of issues :param annotation: Any annotation specific to this negotiation. :param mechanism: The mechanism that started the negotiation :param role: The role of this agent in the negotiation :param req_id: The req_id passed to the AWI when starting the negotiation (only to the initiator). :returns: None to refuse the negotiation or a `Negotiator` object appropriate to the given mechanism to accept it. Remarks: - It is expected that world designers will introduce a better way to respond and override this function to call it .. py:method:: request_negotiation(cfp: scml.scml2019.common.CFP, negotiator: negmas.negotiators.Negotiator = None, ufun: negmas.UtilityFunction = None) -> bool Requests a negotiation from the AWI while keeping track of available negotiation requests :param cfp: :param negotiator: :param ufun: :returns: Whether the negotiation request was successful indicating that the partner accepted the negotiation .. py:method:: on_contract_executed(contract: negmas.situated.Contract) -> None :abstractmethod: Called after successful contract execution for which the agent is one of the partners. .. py:method:: on_contract_breached(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach], resolution: Optional[negmas.situated.Contract]) -> None :abstractmethod: Called after complete processing of a contract that involved a breach. :param contract: The contract :param breaches: All breaches committed (even if they were resolved) :param resolution: The resolution contract if re-negotiation was successful. None if not. .. py:method:: confirm_loan(loan: scml.scml2019.common.Loan, bankrupt_if_rejected: bool) -> bool :abstractmethod: called by the world manager to confirm a loan if needed by the buyer of a contract that is about to be breached .. py:method:: on_contract_nullified(contract: negmas.situated.Contract, bankrupt_partner: str, compensation: float) -> None :abstractmethod: Will be called whenever a contract the agent is involved in is nullified because another partner went bankrupt .. py:method:: on_agent_bankrupt(agent_id: str) -> None :abstractmethod: Will be called whenever any agent goes bankrupt :param agent_id: The ID of the agent that went bankrupt Remarks: - Agents can go bankrupt in two cases: 1. Failing to pay one installments of a loan they bought and refusing (or being unable to) get another loan to pay it. 2. Failing to pay a penalty on a sell contract they failed to honor (and refusing or being unable to get a loan to pay for it). - All built-in agents ignore this call and they use the bankruptcy list ONLY to decide whether or not to negotiate in their `on_new_cfp` and `respond_to_negotiation_request` callbacks by pulling the bulletin-board using the helper function `is_bankrupt` of their AWI. .. py:method:: confirm_partial_execution(contract: negmas.situated.Contract, breaches: List[negmas.situated.Breach]) -> bool :abstractmethod: Will be called whenever a contract cannot be fully executed due to breaches by the other partner. :param contract: The contract that was breached :param breaches: A list of all the breaches committed. Remarks: - Will not be called if both partners committed breaches. .. py:method:: confirm_contract_execution(contract: negmas.situated.Contract) -> bool :abstractmethod: Called before executing any agreement .. py:method:: respond_to_negotiation_request(cfp: scml.scml2019.common.CFP, partner: str) -> Optional[negmas.negotiators.Negotiator] :abstractmethod: Called when a prospective partner requests a negotiation to start .. py:method:: on_new_cfp(cfp: scml.scml2019.common.CFP) :abstractmethod: Called when a new CFP for a product for which the agent registered interest is published .. py:method:: on_remove_cfp(cfp: scml.scml2019.common.CFP) :abstractmethod: Called when a new CFP for a product for which the agent registered interest is removed .. py:method:: on_new_report(report: scml.scml2019.common.FinancialReport) :abstractmethod: Called whenever a financial report is published. :param report: The financial report giving details of the standing of an agent at some time (see `FinancialReport`) Remarks: - Agents must opt-in to receive these calls by calling `receive_financial_reports` on their AWI .. py:method:: on_inventory_change(product: int, quantity: int, cause: str) -> None :abstractmethod: Received whenever something moves in or out of the factory's storage :param product: Product index. :param quantity: Negative value for products moving out and positive value for products moving in :param cause: The cause of the change. Possibilities include: - contract: Contract execution - insurance: Received from insurance company - bankruptcy: Liquidated due to bankruptcy - transport: Arrival of goods (when transportation delay in the system is > 0). .. py:method:: on_cash_transfer(amount: float, cause: str) -> None :abstractmethod: Received whenever money is transferred to the factory or from it. :param amount: Amount of money (negative for transfers out of the factory, positive for transfers to it). :param cause: The cause of the change. Possibilities include: - contract: Contract execution - insurance: Received from insurance company - bankruptcy: Liquidated due to bankruptcy - transfer: Arrival of transferred money (when transfer delay in the system is > 0).