User

class negmas.elicitation.User(cost=0.0, nmi=None, *args, **kwargs)[source]

Bases: Rational

Abstract base class for all representations of users used for elicitation

Parameters:

preferences – The real utility function of the user (pass either ufun or preferences).
ufun – The real utility function of the user (pass either ufun or preferences).
cost (float) – A cost to be added for every question asked to the user.
nmi – [Optional] The AgentMechanismInterface representing the negotiation session engaged in by this user using this ufun.

Attributes Summary

`crisp_ufun`	Returns the preferences if it is a CrispUtilityFunction else None
`has_cardinal_preferences`	Does the entity has an associated ufun?
`has_preferences`	Does the entity has an associated ufun?
`has_ufun`	Does the entity has an associated ufun?
`id`	The unique ID of this entity
`name`	A convenient name of the entity (intended primarily for printing/logging/debugging).
`preferences`	The utility function attached to that object
`prob_ufun`	Returns the preferences if it is a ProbUtilityFunction else None
`reserved_outcome`	Reserved outcome is the outcome that will be realized by default for this agent.
`reserved_value`	Reserved value is what the entity gets if no agreement is reached in the negotiation.
`short_type_name`
`type_name`
`ufun`	Gets a `UtilityFunction` representing the real utility_function of the user
`uuid`	The unique ID of this entity

Methods Summary

`ask`(q)	Query the user and get a response.
`checkpoint`(path[, file_name, info, ...])	Saves a checkpoint of the current object at the given path.
`checkpoint_info`(file_name)	Returns the information associated with a dump of the object saved in the given file
`cost_of_asking`([q, answer_id, ...])	Returns the cost of asking the given `Quers`.
`create`(args, *kwargs)	Creates an object and returns a proxy to it.
`elicited_queries`()	Returns a list of elicited queries.
`from_checkpoint`(file_name[, return_info])	Creates an object from a saved checkpoint
`is_satisfied`(constraint[, outcomes])	Checks if the given consgtraint is satisfied for the user utility fun and the given outocmes.
`on_preferences_changed`(changes)	Called to inform the entity that its ufun has changed.
`set`([preferences, cost])	Sets the ufun and/or cost for this user <`0:desc`>
`set_id`(id)	Sets the unique ID of this entity
`set_preferences`(value[, force, ...])	Sets the utility function/Preferences.
`spawn`([spawn_as, spawn_params])
`spawn_object`(args, *kwargs)

Attributes Documentation

crisp_ufun: Returns the preferences if it is a CrispUtilityFunction else None

has_cardinal_preferences: Does the entity has an associated ufun?

has_preferences: Does the entity has an associated ufun?

has_ufun: Does the entity has an associated ufun?

id: The unique ID of this entity

name: A convenient name of the entity (intended primarily for printing/logging/debugging).

preferences: The utility function attached to that object

prob_ufun: Returns the preferences if it is a ProbUtilityFunction else None

reserved_outcome

Reserved outcome is the outcome that will be realized by default for this agent.

Remarks:

Reserved outcomes are defined for OrdinalPreferences.

See also

reserved_value

reserved_value

Reserved value is what the entity gets if no agreement is reached in the negotiation.

The reserved value can either be explicity defined for the ufun or it can be the output of the ufun for None outcome.

short_type_name

type_name

ufun: Gets a UtilityFunction representing the real utility_function of the user

uuid: The unique ID of this entity

Methods Documentation

ask(q)[source]

Query the user and get a response.

Return type:: QResponse

checkpoint(path, file_name=None, info=None, exist_ok=False, single_checkpoint=True, step_attribs=('current_step', '_current_step', '_Entity__current_step', '_step'))

Saves a checkpoint of the current object at the given path.

Parameters:

path (PathLike) – Full path to a directory to store the checkpoint
file_name (str | None) – Name of the file to dump into. If not given, a unique name is created
info (dict[str, Any] | None) – Information to save with the checkpoint (must be json serializable)
exist_ok (bool) – If true, override existing dump
single_checkpoint (bool) – If true, keep a single checkpoint for the last step
step_attribs (tuple[str, ...]) – Attributes to represent the time-step of the object. Any of the given attributes will be used in the file name generated if single_checkpoint is False. If single_checkpoint is True, the filename will not contain time-step information

Return type:

Path

Returns:

full path to the file used to save the checkpoint

classmethod checkpoint_info(file_name)

Returns the information associated with a dump of the object saved in the given file

Parameters:: file_name (Path | str) – Name of the object
Return type:: dict[str, Any]

Returns:

cost_of_asking(q=None, answer_id=-1, estimate_answer_cost=True)[source]

Returns the cost of asking the given Quers.

Parameters:

q (Query | None) – The query
answer_id (int) – If >= 0, the answer expected. Used to add the specific cost of the answer if estimate_answer_cost is True
estimate_answer_cost – If True and answer_id >= 0, the specific cost of getting this answer is added.

Return type:

float

classmethod create(*args, **kwargs): Creates an object and returns a proxy to it.

elicited_queries()[source]

Returns a list of elicited queries.

For each elicited query, the following dataclass is returned: ElicitationRecord(query, cost, answer_index, step)

Return type:: list[ElicitationRecord]

classmethod from_checkpoint(file_name, return_info=False)

Creates an object from a saved checkpoint

Parameters:

file_name (Path | str)
return_info (bool) – If True, tbe information saved when the file was dumped are returned

Return type:

NamedObject | tuple[NamedObject, dict[str, Any]]

Returns:

Either the object or the object and dump-info as a dict (if return_info was true)

Remarks:

If info is returned, it is guaranteed to have the following members:

time: Dump time

type: Type of the dumped object

id: ID

name: name

is_satisfied(constraint, outcomes=list[tuple])[source]

Checks if the given consgtraint is satisfied for the user utility fun and the given outocmes.

Parameters:

constraint (Constraint) – The Constraint
outcome – A list of `Outcome`s to be passed to the constraint along with the user’s ufun.

Return type:

bool

on_preferences_changed(changes)

Called to inform the entity that its ufun has changed.

Parameters:: changes (list[PreferencesChange]) – An ordered list of changes that happened.

Remarks:

You MUST call the super() version of this function either before or after your code when you are overriding it.

The most general form of change is PreferencesChange.General which indicates that you cannot trust anything you knew about the ufun anymore

set(preferences=None, cost=None)[source]

Sets the ufun and/or cost for this user <0:desc>

Parameters:

preferences (Preferences | None) – The ufun if given
cost (float) – The cost if given

set_id(id): Sets the unique ID of this entity

set_preferences(value, force=False, ignore_exceptions=False)

Sets the utility function/Preferences.

Parameters:

value (Preferences | None) – The value to set to
force – If true, on_preferecnes_changed() will always be called even if value == self.preferences

Return type:

Preferences | None

classmethod spawn(spawn_as='object', spawn_params=None, *args, **kwargs)

classmethod spawn_object(*args, **kwargs)