scml.std.agent
==============

.. py:module:: scml.std.agent


Classes
-------

.. autoapisummary::

   scml.std.agent.EndingNegotiator
   scml.std.agent.StdAgent
   scml.std.agent.StdSyncAgent


Module Contents
---------------

.. py:class:: EndingNegotiator(preferences: negmas.preferences.preferences.Preferences | None = None, ufun: negmas.preferences.base_ufun.BaseUtilityFunction | None = None, name: str | None = None, parent: negmas.negotiators.Controller | None = None, owner: negmas.situated.Agent | None = None, id: str | None = None, type_name: str | None = None, can_propose: bool = True, **kwargs)

   Bases: :py:obj:`negmas.sao.SAONegotiator`, :py:obj:`negmas.ControlledNegotiator`


   Base class for all SAO negotiators. Implemented by implementing propose() and respond() methods.

   :param name: Negotiator name
   :param parent: Parent controller if any
   :param preferences: The preferences of the negotiator
   :param ufun: The utility function of the negotiator (overrides preferences if given)
   :param owner: The `Agent` that owns the negotiator.

   Remarks:
       - The only method that **must** be implemented by any SAONegotiator is `propose`.
       - The default `respond` method, accepts offers with a utility value no less than whatever `propose` returns
         with the same mechanism state.
       - A default implementation of respond() is provided which simply accepts any offer better than the last
         offer I gave or the next one I would have given in the current state.

   .. seealso:: `SAOCallNegotiator`


   .. py:method:: propose(state)

      Propose an offer or None to refuse.

      :param state: `GBState` giving current state of the negotiation.

      :returns: The outcome being proposed or None to refuse to propose

      Remarks:
          - This function guarantees that no agents can propose something with a utility value




   .. py:method:: respond(state, source=None)

      Called to respond to an offer. This is the method that should be overriden to provide an acceptance strategy.

      :param state: a `SAOState` giving current state of the negotiation.
      :param source: The ID of the negotiator that gave this offer

      :returns: The response to the offer
      :rtype: ResponseType

      Remarks:
          - The default implementation never ends the negotiation
          - The default implementation asks the negotiator to `propose`() and accepts the `offer` if its utility was
            at least as good as the offer that it would have proposed (and above the reserved value).
          - The current offer to respond to can be accessed through `state.current_offer`




.. py:class:: StdAgent(owner=None, ufun: scml.oneshot.OneShotUFun | None = None, name=None)

   Bases: :py:obj:`scml.oneshot.agent.OneShotAgent`


   Base class for all agents in the standard game.

   Remarks:
       - You can access all of the negotiators associated with the agent using
         `self.negotiators` which is a dictionary mapping the `negotiator_id` to
         a tuple of two values: The `SAONegotiator` object and a key-value context
         dictionary.
       - The `negotiator_id` associated with a negotiation with some partner will
         be the same as the agent ID of that partner. This means that all negotiators
         engaged with some partner over all simulation steps will have the same ID
         which is useful if you are keeping information about past negotiations and
         partner behavior.


.. py:class:: StdSyncAgent(*args, **kwargs)

   Bases: :py:obj:`scml.oneshot.agent.OneShotSyncAgent`, :py:obj:`StdAgent`


   Base class for agents that negotiate synchronously by receiving all offers at once then responding to all of them at once.