scml.oneshot.agents

Submodules

• scml.oneshot.agents.aspiration
• scml.oneshot.agents.greedy
• scml.oneshot.agents.nothing
• scml.oneshot.agents.rand

Package Contents

Classes

SingleAgreementAspirationAgent	Uses a time-based strategy to accept a single agreement from the set
GreedyOneShotAgent	A greedy agent based on OneShotAgent
GreedySyncAgent	A greedy agent based on OneShotSyncAgent
GreedySingleAgreementAgent	A greedy agent based on OneShotSingleAgreementAgent
OneshotDoNothingAgent	An agent that does nothing.
Placeholder	An agent that always raises an exception if called to negotiate. It is useful as a placeholder (for example for RL and MARL exposition)
RandomOneShotAgent	An agent that randomly leaves the negotiation, accepts or counters with random outcomes
RandDistOneShotAgent	An agent that distributes its needs over its partners randomly.
EqualDistOneShotAgent	Same as RandDistOneShotAgent but defaulting to equal distribution of needs
SyncRandomOneShotAgent	An agent that distributes its needs over its partners randomly.
SingleAgreementRandomAgent	A controller that agrees randomly to one offer

Attributes

__all__

class scml.oneshot.agents.SingleAgreementAspirationAgent(*args, **kwargs)

Bases: scml.oneshot.agent.OneShotSyncAgent

Uses a time-based strategy to accept a single agreement from the set it is considering.

before_step()

Called at the beginning of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

counter_all(offers, states)

Calculate a response to all offers from all negotiators (negotiator ID is the key).

Parameters:

• offers – Maps negotiator IDs to offers

• states – Maps negotiator IDs to offers AT the time the offers were made.

Returns:

A dictionary mapping negotiator ID to an SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.

Remarks:

• The response type CANNOT be WAIT.

• If the system determines that a loop is formed, the agent may

receive this call for a subset of negotiations not all of them.

choose_agents(offers, outcome)

Selects an appropriate way to distribute this outcome to agents with given IDs.

first_proposals() → Dict[str, negmas.Outcome | None]

Gets a set of proposals to use for initializing the negotiation.

Returns:

A dictionary mapping each negotiator (in self.negotiators dict) to an outcome to be used as the first proposal if the agent is to start a negotiation.

class scml.oneshot.agents.GreedyOneShotAgent(*args, concession_exponent=None, acc_price_slack=float('inf'), step_price_slack=None, opp_price_slack=None, opp_acc_price_slack=None, range_slack=None, **kwargs)

Bases: scml.oneshot.agent.OneShotAgent

A greedy agent based on OneShotAgent

Parameters:

• concession_exponent – A real number controlling how fast does the agent concede on price.

• acc_price_slack – The allowed slack in price limits compared with best prices I got so far

• step_price_slack – The allowed slack in price limits compared with best prices I got this step

• opp_price_slack – The allowed slack in price limits compared with best prices I got so far from a given opponent in this step

• opp_acc_price_slack – The allowed slack in price limits compared with best prices I got so far from a given opponent so far

• range_slack – Always consider prices above (1-range_slack) of the best possible prices good enough.

Remarks:

• A concession_exponent greater than one makes the agent concede super linearly and vice versa

init()

Initialize the quantities and best prices received so far

before_step()

Initialize the quantities and best prices received for next step

on_negotiation_success(contract, mechanism)

Record sales/supplies secured

propose(negotiator_id: str, state, source=None) → negmas.Outcome | None

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.

respond(negotiator_id, state, source=None) → negmas.ResponseType

Responds to an offer from one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

best_offer(negotiator_id)

_needed(negotiator_id)

_is_selling(nmi)

_is_good_price(nmi, state, price)

Checks if a given price is good enough at this stage

_find_good_price(nmi, state)

Finds a good-enough price conceding linearly over time

_price_range(nmi)

Limits the price by the best price received

_th(step, n_steps)

calculates a descending threshold (0 <= th <= 1)

class scml.oneshot.agents.GreedySyncAgent(*args, threshold=None, **kwargs)

Bases: scml.oneshot.agent.OneShotSyncAgent, GreedyOneShotAgent

A greedy agent based on OneShotSyncAgent

before_step()

Called at the beginning of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

first_proposals()

Decide a first proposal on every negotiation. Returning None for a negotiation means ending it.

counter_all(offers, states) → dict

Respond to a set of offers given the negotiation state of each.

_needs()

Returns both input and output needs

propose(negotiator_id, state)

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.

respond(negotiator_id, state, source='')

Responds to an offer from one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

class scml.oneshot.agents.GreedySingleAgreementAgent(*args, **kwargs)

Bases: scml.oneshot.agent.OneShotSingleAgreementAgent

A greedy agent based on OneShotSingleAgreementAgent

before_step()

Called at the beginning of every step.

Remarks:

• Use this for any proactive code that needs to be done every simulation step.

is_acceptable(offer, source, state) → bool

Should decide if the given offer is acceptable

Parameters:

• offer – The offer being tested

• source – The ID of the negotiator that received this offer

• state – The state of the negotiation handled by that negotiator

Remarks:

• If True is returned, this offer will be accepted and all other negotiations will be ended.

best_offer(offers)

Return the ID of the negotiator with the best offer

Parameters:

offers – A mapping from negotiator ID to the offer it received

Returns:

The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.

is_better(a, b, negotiator, state)

Compares two outcomes of the same negotiation

Parameters:

• a – “Outcome”

• b – “Outcome”

• negotiator – The negotiator for which the comparison is to be made

• state – Current state of the negotiation

Returns:

True if utility(a) > utility(b)

class scml.oneshot.agents.OneshotDoNothingAgent(owner=None, ufun: scml.oneshot.OneShotUFun | None = None, name=None)

Bases: scml.oneshot.agent.OneShotAgent

An agent that does nothing.

Remarks:

Note that this agent will lose money whenever it is at the edges (i.e. it is an input or an output agent trading in raw material or final product).

propose(negotiator_id, state)

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.

respond(negotiator_id, state, source=None)

Responds to an offer from one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

class scml.oneshot.agents.Placeholder(*args, **kwargs)

Bases: scml.oneshot.policy.OneShotPolicy

An agent that always raises an exception if called to negotiate. It is useful as a placeholder (for example for RL and MARL exposition)

act(state)

The main policy. Generates an action given a state

class scml.oneshot.agents.RandomOneShotAgent(*args, p_accept=PROB_ACCEPTANCE, p_end=PROB_END, **kwargs)

Bases: scml.oneshot.agent.OneShotAgent

An agent that randomly leaves the negotiation, accepts or counters with random outcomes

_random_offer(negotiator_id: str)

propose(negotiator_id, state) → negmas.outcomes.Outcome | None

Proposes an offer to one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

an outcome to offer.

respond(negotiator_id, state, source=None) → negmas.ResponseType

Responds to an offer from one of the partners.

Parameters:

• negotiator_id – ID of the negotiator (and partner)

• state – Mechanism state including current step

Returns:

A response type which can either be reject, accept, or end negotiation.

Remarks:

default behavior is to accept only if the current offer is the same or has a higher utility compared with what the agent would have proposed in the given state and reject otherwise

class scml.oneshot.agents.RandDistOneShotAgent(*args, **kwargs)

Bases: SyncRandomOneShotAgent

An agent that distributes its needs over its partners randomly.

Parameters:

• equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible

• overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.

• overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.

• overordering_exp – Controls how fast does the over-ordering quantity go from max to min.

• concession_exp – Controls how fast does the agent concedes on matching its needs exactly.

• mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).

class scml.oneshot.agents.EqualDistOneShotAgent(*args, **kwargs)

Bases: SyncRandomOneShotAgent

Same as RandDistOneShotAgent but defaulting to equal distribution of needs

Parameters:

• equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible

• overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.

• overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.

• overordering_exp – Controls how fast does the over-ordering quantity go from max to min.

• concession_exp – Controls how fast does the agent concedes on matching its needs exactly.

• mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).

class scml.oneshot.agents.SyncRandomOneShotAgent(*args, equal: bool = False, overordering_max: float = 0.2, overordering_min: float = 0.0, overordering_exp: float = 0.4, mismatch_exp: float = 4.0, mismatch_max: float = 0.3, **kwargs)

Bases: scml.oneshot.agent.OneShotSyncAgent

An agent that distributes its needs over its partners randomly.

Parameters:

• equal – If given, it tries to equally distribute its needs over as many of its suppliers/consumers as possible

• overordering_max – Maximum fraction of needs to over-order. For example, it the agent needs 5 items and this is 0.2, it will order 6 in the first negotiation step.

• overordering_min – Minimum fraction of needs to over-order. Used in the last negotiation step.

• overordering_exp – Controls how fast does the over-ordering quantity go from max to min.

• concession_exp – Controls how fast does the agent concedes on matching its needs exactly.

• mismatch_max – Maximum mismtach in quantity allowed between needs and accepted offers. If a fraction, it is will be this fraction of the production capacity (n_lines).

init()

Called once after the AWI is set.

Remarks:

• Use this for any proactive initialization code.

distribute_needs(t: float) → dict[str, int]

Distributes my needs randomly over all my partners

first_proposals()

Gets a set of proposals to use for initializing the negotiation.

Returns:

A dictionary mapping each negotiator (in self.negotiators dict) to an outcome to be used as the first proposal if the agent is to start a negotiation.

counter_all(offers, states)

Calculate a response to all offers from all negotiators (negotiator ID is the key).

Parameters:

• offers – Maps negotiator IDs to offers

• states – Maps negotiator IDs to offers AT the time the offers were made.

Returns:

A dictionary mapping negotiator ID to an SAOResponse. The response per agent consist of a tuple. In case of acceptance or ending the negotiation the second item of the tuple should be None. In case of rejection, the second item should be the counter offer.

Remarks:

• The response type CANNOT be WAIT.

• If the system determines that a loop is formed, the agent may

receive this call for a subset of negotiations not all of them.

_allowed_mismatch(r: float)

_overordering_fraction(t: float)

_step_and_price(best_price=False)

Returns current step and a random (or max) price

class scml.oneshot.agents.SingleAgreementRandomAgent(*args, p_accept: float = PROB_ACCEPTANCE, **kwargs)

Bases: scml.oneshot.agent.OneShotSingleAgreementAgent

A controller that agrees randomly to one offer

is_acceptable(offer: negmas.outcomes.Outcome, source: str, state: negmas.sao.SAOState) → bool

Should decide if the given offer is acceptable

Parameters:

• offer – The offer being tested

• source – The ID of the negotiator that received this offer

• state – The state of the negotiation handled by that negotiator

Remarks:

• If True is returned, this offer will be accepted and all other negotiations will be ended.

best_offer(offers: dict[str, negmas.outcomes.Outcome]) → str | None

Return the ID of the negotiator with the best offer

Parameters:

offers – A mapping from negotiator ID to the offer it received

Returns:

The ID of the negotiator with best offer. Ties should be broken. Return None only if there is no way to calculate the best offer.

is_better(a: negmas.outcomes.Outcome | None, b: negmas.outcomes.Outcome | None, negotiator: str, state: negmas.sao.SAOState) → bool

Compares two outcomes of the same negotiation

Parameters:

• a – “Outcome”

• b – “Outcome”

• negotiator – The negotiator for which the comparison is to be made

• state – Current state of the negotiation

Returns:

True if utility(a) > utility(b)

scml.oneshot.agents.__all__