negmas.genius¶

The genius module manages connections to the Genius platform and provides both Java-bridge and Python-native negotiators based on the Genius BOA (Bidding, Opponent modeling, Acceptance) architecture.

Overview¶

This module provides three ways to use Genius agents in NegMAS:

GeniusNegotiator - Connect to Java-based Genius agents through the JVM bridge
Python-Native BOA Negotiators (G-prefix) - Pure Python implementations of classic Genius agents
BOA Components - Individual components (offering, acceptance, opponent modeling) for building custom negotiators

Python-Native BOA Negotiators (Recommended)¶

These negotiators are Python implementations of classic Genius agents that do NOT require the Java bridge. They use components from negmas.gb.components.genius and are recommended for most use cases due to better performance and simpler setup. All names are prefixed with G to distinguish them from Java versions.

Classic Time-Dependent Agents

Negotiator	Description
`GBoulware`	Conservative strategy (e=0.2), concedes slowly near deadline
`GConceder`	Accommodating strategy (e=2.0), concedes quickly early on
`GLinear`	Constant concession rate (e=1.0)
`GHardliner`	Never concedes (e=0), always offers best outcome

ANAC Competition Winners and Notable Agents

Negotiator	Year	Description
`GHardHeaded`	2011	Winner. Boulware-style with frequency-based opponent modeling
`GAgentK`	2010	Top performer. Time-dependent with combined acceptance conditions
`GAgentSmith`	2010	Notable. Time-dependent with constant threshold acceptance
`GNozomi`	2010	Competitive. Boulware-style with previous-offer acceptance
`GFSEGA`	2010	Faculty of CS agent. Conceder with constant threshold
`GCUHKAgent`	2012	Winner. Conservative time-dependent with frequency opponent model
`GAgentLG`	2012	Notable. Time-dependent with max-based combined acceptance
`GAgentX`	2015	Notable. Adaptive time-dependent with window-based acceptance
`GRandom`	—	Random offers and accepts everything (baseline agent)

Usage Example¶

from negmas.genius import GHardHeaded, GConceder
from negmas.sao import SAOMechanism
from negmas.preferences import LinearAdditiveUtilityFunction
from negmas.outcomes import make_issue

# Create a simple negotiation scenario
issues = [make_issue(10, "price"), make_issue(5, "quantity")]

# Create utility functions for each negotiator
ufun1 = LinearAdditiveUtilityFunction.random(issues=issues, reserved_value=0.0)
ufun2 = LinearAdditiveUtilityFunction.random(issues=issues, reserved_value=0.0)

# Create negotiators
n1 = GHardHeaded(name="buyer", ufun=ufun1)
n2 = GConceder(name="seller", ufun=ufun2)

# Run negotiation
mechanism = SAOMechanism(issues=issues, n_steps=100)
mechanism.add(n1)
mechanism.add(n2)
mechanism.run()

Java Bridge (GeniusNegotiator)¶

For access to the full ~200 Genius agents, you can use the Java bridge. This requires:

Java JRE 8 or higher installed
Running negmas genius-setup to download the bridge
Starting the bridge with negmas genius before using Java agents

class negmas.genius.GeniusNegotiator(preferences: UtilityFunction | None = None, name: str | None = None, parent: Controller | None = None, owner: Agent = None, java_class_name: str | None = None, domain_file_name: str | Path | None = None, utility_file_name: str | Path | None = None, can_propose=True, auto_load_java: bool = True, port: int = 25337, genius_bridge_path: str | None = None, strict: bool | None = None, none_offer_response: str = 'latest', id: str | None = None, **kwargs)[source]¶

Bases: SAOPRNegotiator

Encapsulates a Genius Negotiator

Parameters:

preferences – The ufun of the negotiator [optional]
name – Negotiator name [optional]
parent – Parent Controller
owner – The agent that owns the negotiator (if any)
java_class_name – The java class name of the Geinus underlying agent
domain_file_name – Optional domain file name (containing the negotiation issues or agenda)
utility_file_name – Optional ufun file name (xml) from which a ufun will be loaded for the agent
can_propose – The negotiator can propose
auto_load_java – Load the genius bridge if needed
port – The port to load the genius bridge to (or use if it is already loaded)
genius_bridge_path – The path to the genius bridge
strict – If True, raise exceptions if any exception is thrown by the agent or the bridge (or if the agent could not choose an action). If false, ignore these exceptions and assume a None return. If None use strict for n_steps limited negotiations and not strict for time_limit limited ones.
none_offer_response – How to respond when receiving a None offer. Options are: - “latest”: Respond with the latest offer made by this negotiator (default) - “best”: Respond with the best offer according to this negotiator’s ufun If “latest” is selected but no previous offer exists, falls back to “best”.

cancel(reason=None) → None[source]¶

Cancels the negotiation and notifies the Java-side agent.

Parameters:: reason – Optional explanation for why the negotiation was cancelled

destroy_java_counterpart(state=None) → None[source]¶

Destroys the Java-side Genius agent and cleans up temporary files.

Parameters:: state – The final mechanism state, used to report agreement if any

property is_connected[source]¶: Check if connected.

property java_name[source]¶: Returns the name of the underlying Java negotiator agent.

join(nmi, state, *, preferences=None, ufun=None, role='negotiator') → bool[source]¶

Joins a negotiation mechanism and initializes the Java-side agent.

Parameters:

nmi – The negotiation mechanism interface providing negotiation context
state – The current mechanism state at join time
preferences – Optional utility function for this negotiator
ufun – Alias for preferences (deprecated)
role – The role this negotiator plays in the mechanism

Returns:

True if successfully joined, False otherwise

classmethod negotiators(agent_based=True, party_based=True) → list[str][source]¶

Returns a list of all available agents in genius 8.4.0

Parameters:

agent_based – Old agents based on the Java class Negotiator
party_based – Newer agents based on the Java class AbstractNegotiationParty

Returns:

on_negotiation_end(state: MechanismState) → None[source]¶: called when a negotiation is ended

on_negotiation_start(state: MechanismState) → None[source]¶: Called when the info starts. Connects to the JVM.

on_none_offer(state: SAOState, source: str | None = None) → SAOResponse[source]¶

Called when the negotiator receives a None offer.

Override this method to customize behavior when a None offer is received. The default implementation uses none_offer_response setting to decide whether to respond with the latest offer or the best offer.

Parameters:

state – The current SAO negotiation state
source – The ID of the negotiator who made the None offer

Returns:

SAOResponse with the action and offer to respond with

parse(action: str) → tuple[ResponseType, tuple | None][source]¶

Parses an action into a ResponseType and an Outcome (if one is included) :param action:

Returns:

property port[source]¶: The TCP port used for the Genius bridge connection.

propose(state: GBState, dest: str | None = None) → tuple | None[source]¶

Generates a proposal for General Bargaining (GB) mechanisms.

Parameters:

state – The current GB negotiation state
dest – Optional target negotiator ID for the proposal

Returns:

The proposed outcome, or None if ending/accepting

propose_sao(state: SAOState, dest: str | None = None) → SAOResponse[source]¶

Generates a new proposal or response for SAO mechanisms.

Parameters:

state – The current SAO negotiation state
dest – Optional target negotiator ID for the proposal

Returns:

The response containing the action type and proposed outcome

classmethod random_negotiator(agent_based=True, party_based=True, port: int = 25337, domain_file_name: str | None = None, utility_file_name: str | None = None, auto_load_java: bool = False, can_propose=True, name: str | None = None) → GeniusNegotiator[source]¶

Returns an agent with a random class name

Parameters:

name – negotiator name
can_propose – Can this negotiator propose?
auto_load_java – load the JVM if needed
utility_file_name – Name of the utility xml file
domain_file_name – Name of the domain XML file
port – port number to use if the JVM is to be started
agent_based – Old agents based on the Java class Negotiator
party_based – Newer agents based on the Java class AbstractNegotiationParty

Returns:

GeniusNegotiator an agent with a random java class

classmethod random_negotiator_name(agent_based=True, party_based=True)[source]¶

Returns a randomly selected Genius negotiator class name.

Parameters:

agent_based – Include older agents based on the Java Negotiator class
party_based – Include newer agents based on AbstractNegotiationParty

property relative_time: float | None[source]¶

The relative negotiation time as reported by the Genius agent (0.0 to 1.0).

Returns:: The relative time between 0 and 1, or None if unavailable

respond(state: GBState, source: str | None = None) → ResponseType[source]¶

Responds to an offer in General Bargaining (GB) mechanisms.

Parameters:

state – The current GB negotiation state
source – The ID of the negotiator who made the offer (required)

Returns:

The response type (accept, reject, or end negotiation)

respond_sao(state: SAOState, source: str | None = None) → None[source]¶

Processes an incoming offer and prepares a response for SAO mechanisms.

Parameters:

state – The current SAO negotiation state containing the offer
source – The ID of the negotiator who made the current offer

classmethod robust_negotiators() → list[str][source]¶: Returns a list of genius agents that were tested and seem to be robustly working with negmas

property strict[source]¶: Whether to raise exceptions on errors instead of issuing warnings.

Bridge Management¶

class negmas.genius.GeniusBridge[source]¶

Bases: object

GeniusBridge implementation.

classmethod agent_exists(uuid: str, port: int = 25337) → bool[source]¶

Checks if a specific agent exists in the bridge.

Parameters:

uuid – The UUID of the agent to check
port – The port at which the bridge is listening in Java

Returns:

True if the agent exists, False otherwise

Remarks:

Thread-safe via ConcurrentHashMap on the Java side

classmethod clean(port=25337) → bool[source]¶: Removes all agents and runs garbage collection on the bridge

classmethod clean_all() → bool[source]¶: Removes all agents and runs garbage collection on all bridges.

classmethod close_gateway(port=25337)[source]¶

Closes the gateway.

Parameters:: port – The port the gateway is connected to. If None, DEFAULT_JAVA_PORT is used.

classmethod close_gateways()[source]¶: Closes all open gateways.

classmethod connect(port: int = 25337) → JavaObject[source]¶

Connects to a running genius-bridge

Parameters:: port – The port at which the bridge in listening in Java

Remarks:

The difference between this method and start() is that this one does not attempt to start a java bridge if one does not exist.

classmethod gateway(port=25337, force=False) → JavaGateway | None[source]¶

Finds and returns a gateway for a genius bridge on the given port

Parameters:

port – The port used by the Jave genius bridge.
force – If true, a new gateway is created even if one exists in the list of gateways available in GeniusBridge.gateways.

Returns:

The gateway if found otherwise an exception will be thrown

Remarks:

this method does NOT start a bridge. It only connects to a running bridge.

gateways: dict[int, Any] = {}[source]¶

classmethod get_active_agents(port: int = 25337) → list[str][source]¶

Gets all active agent UUIDs from the bridge.

Parameters:: port – The port at which the bridge is listening in Java
Returns:: A list of agent UUIDs currently active in the bridge

Remarks:

Thread-safe via ConcurrentHashMap on the Java side
Returns empty list if bridge is not running or connection fails

classmethod get_agent_count(port: int = 25337) → int[source]¶

Gets the number of active agents in the bridge.

Parameters:: port – The port at which the bridge is listening in Java
Returns:: The number of active agents, or 0 if bridge is not running

Remarks:

Thread-safe via ConcurrentHashMap on the Java side

classmethod is_installed() → bool[source]¶: Returns true if a geniusbridge.jar is available

classmethod is_running(port: int) → bool[source]¶: Returns true if a geniusbridge.jar is running on the given port

java_processes: dict[int, Any] = {}[source]¶

classmethod kill(port: int = 25337, wait: bool = True) → bool[source]¶: Kills the java bridge connected to this port by asking it to exit

classmethod kill_forced(port: int = 25337, wait: bool = True) → bool[source]¶

Kills the java bridge connected to this port forcibly.

Remarks:

The java bridge process must have been started by this process.

classmethod kill_threads(port: int = 25337, wait_time: float = 0.5) → bool[source]¶: kills all threads in the given java bridge

python_ports: dict[int, int] = {}[source]¶

classmethod restart(port: int = 25337, *args, **kwargs) → bool[source]¶

Starts or restarts the genius bridge

Parameters:: port – port number to use
Returns:: True if successful

classmethod shutdown(port: int = 25337, wait: bool = True) → bool[source]¶

Attempts to shutdown the bridge on that port.

Parameters:: port – The port to shutdown.

Remarks:

This is the cleanest way to close a java bridge and it simply sends a message to the bridge to shut itself down and cleanly shuts down the py4j bridge.

classmethod start(port: int = 25337, path: str | None = None, debug: bool = False, timeout: float = 0, force_timeout: bool = True, save_logs: bool = False, log_path: PathLike | None = None, die_on_exit: bool = False, use_shell: bool = False, verbose: bool = False, allow_agent_print: bool = False) → int[source]¶

Initializes a genius connection

Parameters:

port – port number to use. A value <= 0 means get any free tcp port.
path – The path to a JAR file that runs negloader
debug – If true, passes –debug to the bridge
timeout – If positive and nonzero, passes it as the global timeout for the bridge. Note that currently, the bridge supports only integer timeout values and the fraction will be truncated.
force_timeout – if false, no timeout will be forced by the bridge
save_logs – If false, the brige is instructed not to save any logs
log_path – the path to store logs from the bridge. Onle effective if save_logs If not given, defaults to ~/negmas/geniusbridge/logs/{port}-{datetime}.txt
die_on_exit – If given, the bridge will be closed when this process is ended
use_shell – If given, the bridge will be started in a subshell.

Returns:

The port number used by the java process. 0 for failure

Remarks:

if a bridge is running, it will return its port and it does not matter whether or not the bridge is started from this process or any other way.
it is recommended not to change the defaults for this function.

classmethod stop(port: int = 25337) → bool[source]¶

Stops a running bridge

Parameters:: port – port number to use
Returns:: True if successful

Remarks:

You should use this method to stop bridges.
It tries the following in order:
1. shutdown the java bridge by calling its shutdown() method.
2. killing the java bridge by calling its kill() method.
3. killing the java bridge forcibly by killing the process
This method always waits for a short time to allow each process to complete. If it returns True then the bridge is no longer listening on the given port.

classmethod wait_until_listening(port: int = 25337, timeout: float = 0.5) → bool[source]¶

waits until a genius bridge is listening to the given port

Parameters:

port – The port to test
timeout – Maximum time to wait before returning (in seconds)

Returns:

True if the genius bridge is running any more (success).

classmethod wait_until_not_listening(port: int = 25337, timeout: float = 0.5) → bool[source]¶

waits until the genius bridge is not listening to the given port

Parameters:

port – The port to test
max_sleep – Maximum time to wait before returning (in seconds)

Returns:

True if the genius bridge is NOT running any more (success).

negmas.genius.init_genius_bridge(path: Path | str | None = None, port: int = 25337, debug: bool = False, timeout: float = 0, force_timeout: bool = True, save_logs: bool = False, log_path: PathLike | None = None, die_on_exit: bool = False, use_shell: bool = False, verbose: bool = False, allow_agent_print: bool = False) → int[source]¶

Initializes a genius connection

Parameters:

path – The path to a JAR file that runs negloader
port – port number to use
debug – If true, passes –debug to the bridge
timeout – If positive and nonzero, passes it as the global timeout for the bridge. Note that currently, the bridge supports only integer timeout values and the fraction will be truncated.

Returns:

Port if started. -1 if a bridge is already running on this port. 0 if failed

negmas.genius.genius_bridge_is_running(port: int = 25337) → bool[source]¶

Checks whether a Genius Bridge is running. A genius bridge allows you to use GeniusNegotiator objects.

Remarks:

You can start a Genius Bridge in at least three ways:

execute the python function init_genius_bridge() in this module

run “negmas genius” on the terminal

execute GeniusBridge.start()

negmas.genius.genius_bridge_is_installed() → bool[source]¶: Checks if geniusbridge is available in the default path location