negmas CLI

The negmas CLI provides a unified interface to all NegMAS commands including Genius setup, tournaments, documentation access, and more.

Installation

The negmas command is automatically available after installing NegMAS:

$ pip install negmas

Basic Usage

Run the main help to see all available subcommands:

$ negmas --help

Common subcommands include:

  • negmas genius-setup - Download and configure the Genius bridge

  • negmas genius - Start the Genius bridge for Java agent integration

  • negmas tournament - Run negotiation tournaments

Command Reference

negmas

Usage

negmas [OPTIONS] COMMAND [ARGS]...

docs

Opens negmas docs in the browser. Make sure to install the docs first using negmas docs-setup

Usage

negmas docs [OPTIONS]

docs-setup

Downloads and installs docs to ~/negmas/docs

Usage

negmas docs-setup [OPTIONS]

genius

Start the bridge to genius (to use GeniusNegotiator)

Usage

negmas genius [OPTIONS]

Options

-p, --path <path>
Path to geniusbridge.jar with embedded NegLoader. Use “auto” to read the path from ~/negmas/config.json

Config key is genius_bridge_jar

You can download this jar from: https://yasserfarouk.github.io/files/geniusbridge.jar

Default:

'auto'

-r, --port <port>

Port to run the NegLoader on. Pass 0 for the default value

Default:

25337

--debug, --no-debug

Run the bridge in debug mode if –debug else silently

Default:

False

--verbose, --silent

Verbose output

Default:

True

--save-logs, --no-logs

Save logs

Default:

False

--die-on-exit, --no-die-on-exit

Whether to kill the bridge on exit. For future use. Currently it does nothing.

Default:

False

--use-shell, --no-shell

Whether to start the new process in a shell

Default:

False

--force-timeout, --no-forced-timeout

Whether to force a timeout on the bridge

Default:

True

--timeout <timeout>

The timeout to pass. Zero or negative numbers to disable and use the bridge’s global timeout.

Default:

0

--log-path <log_path>

Directory to save logs within. Only used if –save-logs. If not given, ~/negmas/logs will be used

genius-setup

Downloads the genius bridge and updates your settings

Usage

negmas genius-setup [OPTIONS]

registry

Query the NegMAS registry for mechanisms, negotiators, and components.

Usage

negmas registry [OPTIONS] COMMAND [ARGS]...
filters

List available filter attributes for a registry type

Usage

negmas registry filters [OPTIONS] {mechanism|negotiator|component}

Arguments

REGISTRY_TYPE

Required argument

get

Get details about a specific registered item

Usage

negmas registry get [OPTIONS] NAME

Options

-t, --type <registry_type>

Registry type to search (default: auto-detect)

Default:

'auto'

Options:

mechanism | negotiator | component | scenario | auto

-o, --format <output_format>

Output format: ‘free’ (nicely formatted), ‘txt’ (plain text for piping), ‘json’

Default:

'free'

Options:

free | txt | json

Arguments

NAME

Required argument

list

List all registered items of a given type

Usage

negmas registry list [OPTIONS] {mechanisms|negotiators|components|scenarios}

Options

-t, --tag <tags_str>

Filter by tags - items must have ALL specified tags (comma-separated, e.g., ‘genius,anac-2019’)

Default:

''

-a, --any-tag <any_tags_str>

Filter by tags - items must have ANY of the specified tags (comma-separated)

Default:

''

-x, --exclude-tag <exclude_tags_str>

Exclude items with ANY of these tags (comma-separated)

Default:

''

--n-outcomes <n_outcomes>

Filter scenarios by n_outcomes (e.g., ‘100’, ‘100:500’, ‘:1000’)

Default:

''

--n-negotiators <n_negotiators>

Filter scenarios by n_negotiators (e.g., ‘2’, ‘2:4’)

Default:

''

--opposition-level <opposition_level>

Filter scenarios by opposition level (e.g., ‘0.3:0.7’)

Default:

''

-o, --format <output_format>

Output format: ‘free’ (nicely formatted), ‘txt’ (plain text for piping), ‘json’

Default:

'free'

Options:

free | txt | json

-v, --verbose

Show extra details

Default:

False

--show-tags

Include tags in output

Default:

False

-c, --count

Only show count of matching items

Default:

False

Arguments

REGISTRY_TYPE

Required argument

stats

Show summary statistics for all registries

Usage

negmas registry stats [OPTIONS]

Options

-t, --tag <tags_str>

Filter by tags - only count items with ALL specified tags (comma-separated)

Default:

''

-a, --any-tag <any_tags_str>

Filter by tags - only count items with ANY of the specified tags (comma-separated)

Default:

''

-x, --exclude-tag <exclude_tags_str>

Exclude items with ANY of these tags (comma-separated)

Default:

''

-o, --format <output_format>

Output format: ‘free’ (nicely formatted), ‘txt’ (plain text), ‘json’

Default:

'free'

Options:

free | txt | json

tags

List all tags used in the registries

Usage

negmas registry tags [OPTIONS]

Options

-t, --type <registry_type>

Registry/item type to list tags from. ‘all’/’any’ for all registries, or filter by specific type including component subtypes (acceptance, offering, model)

Default:

'all'

Options:

all | any | mechanisms | negotiators | components | scenarios | acceptance | offering | model

-o, --format <output_format>

Output format: ‘free’ (nicely formatted), ‘txt’ (plain text), ‘json’

Default:

'free'

Options:

free | txt | json

-c, --count

Show count of items per tag

Default:

False

tournament

Usage

negmas tournament [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options

--ignore-warnings, --show-warnings

Ignore/show runtime warnings

Default:

False

combine

Combine multiple tournaments at the given base path(s)

Usage

negmas tournament combine [OPTIONS] [PATH]...

Options

--verbose, --silent

Whether to be verbose

Default:

True

-d, --dest <dest>

The location to save the results

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

Arguments

PATH

Optional argument(s)

combine-results

Combine results from multiple tournaments

Usage

negmas tournament combine-results [OPTIONS] [PATH]...

Options

-d, --dest <dest>

The location to save the results

--metric <metric>

The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean

Default:

'truncated_mean'

--max-sources <max_sources>

Maximum number of sources to use. Default to all available

--significance, --no-significance

Whether to show significance table

Default:

False

--verbose, --silent

Whether to be verbose

Default:

True

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

Arguments

PATH

Optional argument(s)

create

Creates a tournament

Usage

negmas tournament create [OPTIONS]

Options

-n, --name <name>

The name of the tournament. The special value “random” will result in a random name

Default:

'random'

-t, --timeout <timeout>

Timeout the whole tournament after the given number of seconds (0 for infinite)

Default:

0

--configs <configs>

Number of unique configurations to generate.

Default:

5

--runs <runs>

Number of runs for each configuration

Default:

2

--max-runs <max_runs>

Maximum total number of runs. Zero or negative numbers mean no limit

Default:

-1

--steps-min <steps_min>

Minimum number of steps (only used if –steps was not passed

Default:

50

--steps-max <steps_max>

Maximum number of steps (only used if –steps was not passed

Default:

100

--agents <agents>

Number of agents per competitor

Default:

3

--competitors <competitors>

A semicolon (;) separated list of agent types to use for the competition.

Default:

Sentinel.UNSET

--non-competitors <non_competitors>

A semicolon (;) separated list of agent types to exist in the worlds as non-competitors (their scores will not be calculated).

Default:

Sentinel.UNSET

-l, --log <log>

Default location to save logs (A folder will be created under it)

Default:

PosixPath('/home/docs/negmas/logs/tournaments')

--world-config <world_config>

A file to load extra configuration parameters for world simulations from.

Default:

--verbosity <verbosity>

verbosity level (from 0 == silent to 1 == world progress)

Default:

1

--log-ufuns, --no-ufun-logs

Log ufuns into their own CSV file. Only effective if –debug is given

Default:

False

--log-negs, --no-neg-logs

Log all negotiations. Only effective if –debug is given

Default:

False

--compact, --debug

If True, effort is exerted to reduce the memory footprint whichincludes reducing logs dramatically.

Default:

True

--raise-exceptions, --ignore-exceptions

Whether to ignore agent exceptions

Default:

True

--path <path>

A path to be added to PYTHONPATH in which all competitors are stored. You can path a : separated list of paths on linux/mac and a ; separated list in windows

Default:

''

--config-generator <config_generator>

The full path to a configuration generator function that is used to generate all configs for the tournament. MUST be specified

Default:

''

--world-generator <world_generator>

The full path to a world generator function that is used to generate all worlds (given the assigned configs for the tournament. MUST be specified

Default:

''

--assigner <assigner>

The full path to an assigner function that assigns competitors to different configurations

Default:

''

--scorer <scorer>

The full path to a scoring function

Default:

''

--cw <cw>

Number of competitors to run at every world simulation. It must either be left at default or be a number > 1 and < the number of competitors passed using –competitors

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

eval

Evaluates a tournament and returns the results

Usage

negmas tournament eval [OPTIONS] PATH

Options

--metric <metric>

The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean

Default:

'truncated_mean'

--significance, --no-significance

Whether to show significance table

Default:

False

--compile, --show

Whether to recompile results from individual world runs or just show the already-compiled results

Default:

True

--verbose, --silent

Whether to be verbose

Default:

True

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

Arguments

PATH

Required argument

run

Runs/continues a tournament

Usage

negmas tournament run [OPTIONS]

Options

-n, --name <name>

The name of the tournament. When invoked after create, there is no need to pass it

Default:

''

-l, --log <log>

Default location to save logs

Default:

PosixPath('/home/docs/negmas/logs/tournaments')

--verbosity <verbosity>

verbosity level (from 0 == silent to 1 == world progress)

Default:

1

--parallel, --serial

Run a parallel/serial tournament on a single machine

Default:

True

--distributed, --single-machine

Run a distributed tournament using dask

Default:

False

--ip <ip>

The IP address for a dask scheduler to run the distributed tournament. Effective only if –distributed

Default:

'127.0.0.1'

--port <port>

The IP port number a dask scheduler to run the distributed tournament. Effective only if –distributed

Default:

8786

--compact, --debug

If True, effort is exerted to reduce the memory footprint whichincludes reducing logs dramatically.

Default:

True

--path <path>

A path to be added to PYTHONPATH in which all competitors are stored. You can path a : separated list of paths on linux/mac and a ; separated list in windows

Default:

''

--metric <metric>

The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean

Default:

'truncated_mean'

--significance, --no-significance

Whether to show significance table

Default:

False

--eval, --no-eval

Whether evaluate and show results after the tournament is run

Default:

False

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

winners

Finds winners of a tournament or a set of tournaments sharing a root

Usage

negmas tournament winners [OPTIONS]

Options

-n, --name <name>

The name of the tournament. When invoked after create, there is no need to pass it

Default:

''

-l, --log <log>

Default location to save logs

Default:

PosixPath('/home/docs/negmas/logs/tournaments')

--recursive, --no-recursive

Whether to recursively look for tournament results. –name should not be given if –recursive

Default:

True

--metric <metric>

The statistical metric used for choosing the winners. Possibilities are mean, median, std, var, sum, truncated_mean

Default:

'truncated_mean'

--verbose, --silent

Whether to be verbose

Default:

True

--significance, --no-significance

Whether to show significance table

Default:

False

--compile, --show

Whether to recompile results from individual world runs or just show the already-compiled results

Default:

True

--config <config>

Read configuration from FILE.

Default:

Sentinel.UNSET

version

Prints NegMAS version

Usage

negmas version [OPTIONS]