negmas.registry¶

NegMAS Registry System for Mechanisms, Negotiators, Components, and Scenarios.

Overview¶

The registry system provides a centralized way to register, discover, and query negotiation-related classes and scenarios. It enables:

Discovery: Find all available implementations without knowing their locations
Querying: Filter implementations by properties (e.g., find all ANAC negotiators)
Extensibility: External libraries can register their own implementations
Metadata: Store and retrieve information about each implementation

Architecture¶

The registry consists of four separate registries, each for a different type:

mechanism_registry: Negotiation mechanisms (e.g., SAOMechanism, TAUMechanism)
negotiator_registry: Negotiation agents (e.g., AspirationNegotiator, NaiveTitForTatNegotiator)
component_registry: BOA components (acceptance strategies, offering strategies, opponent models)
scenario_registry: Negotiation scenarios (domain + utility function definitions)

Key Design: Registry Keys¶

For class registries (mechanisms, negotiators, components), keys work as follows:

Primary key: short_name - A human-readable name (e.g., “AspirationNegotiator”)
Fallback key: full_type_name - Fully qualified name (e.g., “negmas.sao.AspirationNegotiator”)

When registering a class:

If no short_name is provided, the class name (cls.__name__) is used
If the short_name already exists for a different class, the new class is registered under its full_type_name instead (to avoid silent overwrites)
Both names can be used to retrieve the class via get_class()

This design provides:

Convenience: Use short names like “SAOMechanism” for common lookups
Safety: No silent overwrites when names clash (e.g., two libraries both defining “MyNegotiator”)
Uniqueness: The full_type_name is always unique and can be used when short names are ambiguous

For scenario registries, keys are the resolved absolute path (always unique).

Usage Examples¶

Registering Classes¶

Using decorators (recommended):

from negmas import register_negotiator, register_mechanism

@register_negotiator(
    bilateral_only=True,
    learns=True,
    tags={"custom", "learning"},
)
class MyLearningNegotiator(SAONegotiator):
    '''A custom negotiator that learns.'''
    pass

@register_mechanism(requires_deadline=False, tags={"custom"})
class MyMechanism(Mechanism):
    pass

Using direct registration:

from negmas import negotiator_registry, NegotiatorInfo

class AnotherNegotiator(SAONegotiator):
    pass

negotiator_registry.register(
    AnotherNegotiator,
    short_name="another",  # Optional custom name
    tags={"experimental"},
)

Discovering and Querying¶

List all registered items:

from negmas import negotiator_registry, mechanism_registry

# List all negotiators
for name, info in negotiator_registry.items():
    print(f"{name}: {info.full_type_name}")

# List just the names
print(list(negotiator_registry.keys()))

Query by properties:

# Find negotiators that learn
learners = negotiator_registry.query(learns=True)

# Find ANAC 2019 negotiators
anac2019 = negotiator_registry.query(anac_year=2019)

# Find mechanisms that don't require a deadline
flexible = mechanism_registry.query(requires_deadline=False)

Query by tags:

# Find items with ALL specified tags
builtin_sao = negotiator_registry.query(tags=["builtin", "sao"])

# Find items with ANY of the specified tags
genius_or_builtin = negotiator_registry.query(any_tags=["genius", "builtin"])

# Exclude items with certain tags
no_genius = negotiator_registry.query(exclude_tags=["genius"])

# Combined tag filtering
results = negotiator_registry.query(
    tags=["sao"],  # Must have "sao"
    any_tags=["anac-2018", "anac-2019"],  # Must have one of these
    exclude_tags=["experimental"],  # Must not have this
)

Get a specific class:

from negmas import negotiator_registry

# By short name
cls = negotiator_registry.get_class("AspirationNegotiator")

# By full type name (useful when short names clash)
cls = negotiator_registry.get_class("negmas.sao.negotiators.AspirationNegotiator")

Working with Scenarios¶

from negmas import register_scenario

info = register_scenario(
    "/path/to/my/scenario",
    name="MyScenario",
    tags={"custom", "bilateral"},
    n_negotiators=2,
)

from negmas import register_all_scenarios

# Recursively find and register all loadable scenarios
scenarios = register_all_scenarios(
    "/path/to/scenarios",
    tags={"my-project"},
)
print(f"Registered {len(scenarios)} scenarios")

Query scenarios:

from negmas import scenario_registry

# Find bilateral scenarios
bilateral = scenario_registry.query(tags=["bilateral"])

# Find XML format scenarios
xml_scenarios = scenario_registry.query(format="xml")

# Get scenario by name (may return multiple if name is not unique)
camera_scenarios = scenario_registry.get_by_name("CameraB")

Built-in Registrations¶

NegMAS automatically registers:

Built-in mechanisms (SAOMechanism, TAUMechanism, etc.)
Built-in negotiators (AspirationNegotiator, NaiveTitForTatNegotiator, etc.)
Genius negotiators (imported from Genius library)
BOA components (acceptance, offering, opponent modeling strategies)
Built-in scenarios (CameraB, etc.)

These are registered when you import from negmas and can be discovered immediately:

from negmas import negotiator_registry

# See all registered negotiators
print(f"Total negotiators: {len(negotiator_registry)}")

# Filter by source
builtin = negotiator_registry.query(tags=["builtin"])
genius = negotiator_registry.query(tags=["genius"])
print(f"Built-in: {len(builtin)}, Genius: {len(genius)}")

CLI Access¶

The registry is also accessible via the command line:

# List all mechanisms
negmas registry list mechanisms

# List negotiators with filters
negmas registry list negotiators --tag genius --tag anac-2019

# Show registry statistics
negmas registry stats

# Search by name pattern
negmas registry search "Aspiration*"

# List all tags
negmas registry tags --count

class negmas.registry.ComponentInfo(key: str, short_name: str, full_type_name: str, cls: type, source: str = 'unknown', params: dict[str, ~typing.Any]=<factory>, tags: set[str] = <factory>, extra: dict[str, ~typing.Any]=<factory>, component_type: str = 'generic')[source]¶

Bases: RegistryInfo

Registration information for components.

component_type[source]¶

The type of component (e.g., ‘acceptance’, ‘offering’, ‘model’).

Type:: str

component_type: str = 'generic'[source]¶

class negmas.registry.MechanismInfo(key: str, short_name: str, full_type_name: str, cls: type, source: str = 'unknown', params: dict[str, ~typing.Any]=<factory>, tags: set[str] = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]¶

Bases: RegistryInfo

Registration information for mechanisms.

All mechanism properties are now expressed via tags: - “requires-deadline”: Mechanism requires n_steps or time_limit - “propose”: Requires negotiators to have propose capability - “respond”: Requires negotiators to have respond capability - “sao”, “gb”, “tau”, “st”: Protocol type tags

class negmas.registry.NegotiatorInfo(key: str, short_name: str, full_type_name: str, cls: type, source: str = 'unknown', params: dict[str, ~typing.Any]=<factory>, tags: set[str] = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]¶

Bases: RegistryInfo

Registration information for negotiators.

All negotiator properties are now expressed via tags: - “bilateral-only”: Only works in bilateral negotiations - “requires-opponent-ufun”: Requires access to opponent’s utility function - “learning”: Learns from repeated negotiations - “anac-YYYY”: ANAC competition year (e.g., “anac-2019”) - “supports-uncertainty”: Supports uncertain preferences - “supports-discounting”: Supports time-discounted utilities

class negmas.registry.Registry(info_class: type[T])[source]¶

Bases: Generic[T], dict[str, T]

A registry for storing and querying registered classes.

This is a dictionary subclass that provides additional query methods for finding classes by their properties.

Type Parameters:: T: The RegistryInfo subclass used for entries in this registry.

create(key_or_name: str, **override_params) → Any[source]¶

Create an instance of a registered class.

This method instantiates a class using its stored params, merged with any override parameters provided.

Parameters:

key_or_name – The unique key (e.g., ‘MyNegotiator#a1b2c3d4’), short name (e.g., ‘MyNegotiator’), or full type name.
**override_params – Parameters to override the stored params.

Returns:

An instance of the registered class.

Raises:

KeyError – If no registration is found for the given key or name.
TypeError – If the class cannot be instantiated with the params.

Example

# Register with default params key = registry.register(MyNegotiator, params={‘alpha’: 0.5})

# Create with stored params neg1 = registry.create(key) # uses alpha=0.5

# Create with overridden params neg2 = registry.create(key, alpha=0.9) # uses alpha=0.9

get_all_by_class(cls: type | str) → list[T][source]¶

Get all registration info for a class.

Parameters:: cls – The class to look up, or its full type name string.
Returns:: A list of all RegistryInfo objects for this class, or empty list if not registered.

get_by_class(cls: type | str) → T | None[source]¶

Get the first registration info for a class.

Parameters:: cls – The class to look up, or its full type name string.
Returns:: The first RegistryInfo for the class, or None if not registered. If the class has multiple registrations, returns the first one. Use get_all_by_class() to get all registrations.

get_by_short_name(short_name: str) → list[T][source]¶

Get all registrations with a given short name.

Since keys are now unique (with UUID suffix), multiple registrations can have the same short_name. This method returns all of them.

Parameters:: short_name – The short name to look up.
Returns:: A list of RegistryInfo objects with that short name (may be empty).

get_class(key_or_name: str) → type | None[source]¶

Get the class for a registered key or name.

Parameters:: key_or_name – The unique key (e.g., ‘MyNegotiator#a1b2c3d4’), short name (e.g., ‘MyNegotiator’), or full type name (e.g., ‘mymodule.MyNegotiator’).
Returns:: The class, or None if not found. If multiple registrations match a short name, returns the first one found.

is_registered(cls: type | str) → bool[source]¶

Check if a class is registered.

Parameters:: cls – The class to check, or its full type name string.
Returns:: True if the class has at least one registration, False otherwise.

list_all() → list[str][source]¶

List all registered keys.

Returns:: A list of all registered keys.

list_tags() → set[str][source]¶

List all unique tags used across all registered items.

Returns:: A set of all unique tags.

Query the registry for classes matching the given criteria.

Parameters:

tags – If provided, only return items that have ALL of these tags.
any_tags – If provided, only return items that have ANY of these tags.
exclude_tags – If provided, exclude items that have ANY of these tags.
**criteria – Attribute-value pairs to match exactly.

Returns:

A dictionary of matching entries (short_name -> info).

Example

# Find all genius negotiators from ANAC 2019 negotiator_registry.query(tags={“genius”}, anac_year=2019)

# Find any builtin or genius negotiators negotiator_registry.query(any_tags={“builtin”, “genius”})

# Find builtin negotiators that are not bilateral-only negotiator_registry.query(tags={“builtin”}, bilateral_only=False)

# Find all negotiators except genius ones negotiator_registry.query(exclude_tags={“genius”})

query_by_tag(tag: str) → dict[str, T][source]¶

Query the registry for classes with a specific tag.

This is a convenience method equivalent to query(tags={tag}).

Parameters:: tag – The tag to filter by.
Returns:: A dictionary of matching entries (short_name -> info).

Parameters:

cls – The class to register, or its full type name string (e.g., ‘negmas.sao.AspirationNegotiator’). If a string is provided, the class will be resolved using negmas helpers.
short_name – A human-readable name for this registration. Can differ from the class name to create “virtual” negotiators with different params. If None, uses the class name. Examples: - ‘AspirationNegotiator’ (same as class) - ‘AggressiveAspiration’ (virtual negotiator with specific params)
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
params – Constructor parameters for creating instances via create(). This enables “virtual” negotiators that share a class but have different default parameters.
tags – Optional set of tags for categorization and filtering.
**kwargs – Additional properties for the RegistryInfo. Deprecated boolean params are converted to tags automatically.

Returns:

The unique key assigned to this registration.

Note

The same class can be registered multiple times with different names and parameters (creating “virtual” negotiators). Each registration gets a unique key in the format ‘{short_name}#{uuid8}’.

Example

# Register with class key1 = registry.register(AspirationNegotiator)

# Register with full type name string key2 = registry.register(‘negmas.sao.AspirationNegotiator’)

# Create a “virtual” negotiator with custom params key3 = registry.register(

)

register_many(registrations: list[dict[str, Any]]) → list[str][source]¶

Parameters:: registrations – A list of dictionaries, each containing the arguments for a single registration. Each dict must have a ‘cls’ key with the class to register. Other keys are passed to register().
Returns:: A list of unique keys assigned to the registrations.

Example

keys = registry.register_many([: {‘cls’: MyNegotiator, ‘short_name’: ‘my_neg’, ‘source’: ‘mylib’}, {‘cls’: OtherNegotiator, ‘params’: {‘alpha’: 0.5}},

])

unregister(cls_or_key: type | str) → bool[source]¶

Remove a registration from the registry.

Parameters:: cls_or_key – Either the class itself, a full type name string, or a registered key. If a class or full type name is given and it has multiple registrations, ALL are removed. If a key is given, only that specific registration is removed.
Returns:: True if at least one registration was removed, False if none were found.

Example

# Unregister by key (removes only that registration) registry.unregister(“MyNegotiator#a1b2c3d4”)

# Unregister by class (removes ALL registrations of this class) registry.unregister(MyNegotiator)

# Unregister by full type name (removes ALL registrations) registry.unregister(“mymodule.MyNegotiator”)

unregister_many(keys_or_classes: list[str | type]) → int[source]¶

Remove multiple registrations in a single call.

Parameters:: keys_or_classes – A list of keys or classes to unregister.
Returns:: The number of registrations that were removed.

Example

count = registry.unregister_many([: ‘MyNegotiator#a1b2c3d4’, OtherNegotiator, # removes all registrations of this class

])

class negmas.registry.RegistryInfo(key: str, short_name: str, full_type_name: str, cls: type, source: str = 'unknown', params: dict[str, ~typing.Any]=<factory>, tags: set[str] = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]¶

Bases: object

Base class for registration information.

key[source]¶

The unique registry key (e.g., ‘AspirationNegotiator#a1b2c3d4’). This is automatically generated and guaranteed unique within the registry.

Type:: str

short_name[source]¶

A short, human-readable name for the class.

Type:: str

full_type_name[source]¶

The fully qualified class name (e.g., ‘negmas.sao.SAOMechanism’).

Type:: str

cls[source]¶

The actual class object.

Type:: type

source[source]¶

The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).

Type:: str

params[source]¶

Constructor parameters for creating instances via Registry.create().

Type:: dict[str, Any]

tags[source]¶

A set of string tags for categorization and filtering.

Type:: set[str]

extra[source]¶

Additional key-value pairs for custom properties.

Type:: dict[str, Any]

cls: type[source]¶

extra: dict[str, Any][source]¶

full_type_name: str[source]¶

has_all_tags(tags: set[str] | list[str] | tuple[str, ...]) → bool[source]¶

Check if this item has all of the specified tags.

Parameters:: tags – The tags to check for.
Returns:: True if all of the tags are present, False otherwise.

has_any_tag(tags: set[str] | list[str] | tuple[str, ...]) → bool[source]¶

Check if this item has any of the specified tags.

Parameters:: tags – The tags to check for.
Returns:: True if any of the tags is present, False otherwise.

has_tag(tag: str) → bool[source]¶

Check if this item has a specific tag.

Parameters:: tag – The tag to check for.
Returns:: True if the tag is present, False otherwise.

key: str[source]¶

params: dict[str, Any][source]¶

short_name: str[source]¶

source: str = 'unknown'[source]¶

tags: set[str][source]¶

class negmas.registry.ScenarioInfo(name: str, path: Path, source: str = 'unknown', tags: set[str] = <factory>, n_outcomes: int | None = None, n_negotiators: int | None = None, opposition_level: float | None = None, extra: dict[str, ~typing.Any]=<factory>)[source]¶

Bases: object

Registration information for negotiation scenarios.

Unlike other registry entries, scenarios are paths to files/folders rather than classes.

Boolean properties are now expressed via tags: - “normalized”: Utilities are normalized to [0, 1] - “anac”: From an ANAC competition - “file”: Single file scenario (vs folder) - “has-stats”: Has pre-computed statistics - “has-plot”: Has a pre-generated plot - “xml”, “json”, “yaml”: Format tags

name[source]¶

A short name for the scenario (may not be unique - typically folder/file name).

Type:: str

path[source]¶

The full path to the scenario file or folder.

Type:: pathlib.Path

source[source]¶

The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).

Type:: str

tags[source]¶

A set of string tags for categorization and filtering.

Type:: set[str]

n_outcomes[source]¶

The number of possible outcomes (if known).

Type:: int | None

n_negotiators[source]¶

The number of negotiators in the scenario (if known).

Type:: int | None

opposition_level[source]¶

The opposition level between negotiators (0=cooperative, 1=competitive).

Type:: float | None

extra[source]¶

Additional key-value pairs for custom properties.

Type:: dict[str, Any]

extra: dict[str, Any][source]¶

has_all_tags(tags: set[str] | list[str] | tuple[str, ...]) → bool[source]¶

Check if this scenario has all of the specified tags.

Parameters:: tags – The tags to check for.
Returns:: True if all of the tags are present, False otherwise.

has_any_tag(tags: set[str] | list[str] | tuple[str, ...]) → bool[source]¶

Check if this scenario has any of the specified tags.

Parameters:: tags – The tags to check for.
Returns:: True if any of the tags is present, False otherwise.

has_tag(tag: str) → bool[source]¶

Check if this scenario has a specific tag.

Parameters:: tag – The tag to check for.
Returns:: True if the tag is present, False otherwise.

n_negotiators: int | None = None[source]¶

n_outcomes: int | None = None[source]¶

name: str[source]¶

opposition_level: float | None = None[source]¶

path: Path[source]¶

source: str = 'unknown'[source]¶

tags: set[str][source]¶

class negmas.registry.ScenarioRegistry[source]¶

Bases: dict[str, ScenarioInfo]

A registry for storing and querying registered scenarios.

Unlike the regular Registry, this stores scenario paths rather than classes. Scenarios are identified by a unique key (typically the path string).

get_by_name(name: str) → list[ScenarioInfo][source]¶

Get all scenarios with a given name.

Note that scenario names are not unique, so this returns a list.

Parameters:: name – The scenario name to look up.
Returns:: A list of ScenarioInfo objects with that name (may be empty).

list_all() → list[str][source]¶

List all registered scenario paths.

Returns:: A list of all registered scenario paths (as strings).

list_names() → list[str][source]¶

List all unique scenario names.

Returns:: A list of all unique scenario names.

list_tags() → set[str][source]¶

List all unique tags used across all registered scenarios.

Returns:: A set of all unique tags.

load(key_or_name: str | Path) → Any[source]¶

Load a registered scenario.

This method loads the scenario from disk using its registered path.

Parameters:

key_or_name – The path (as registered) or scenario name. If a name is given and multiple scenarios have that name, loads the first one found.

Returns:

The loaded Scenario object.

Raises:

KeyError – If no registration is found for the given key or name.
Exception – If the scenario cannot be loaded.

Example

# Load by path (key) scenario = registry.load(‘/path/to/scenario’)

# Load by name scenario = registry.load(‘Laptop’)

Query the registry for scenarios matching the given criteria.

Parameters:

tags – If provided, only return items that have ALL of these tags.
any_tags – If provided, only return items that have ANY of these tags.
exclude_tags – If provided, exclude items that have ANY of these tags.
n_outcomes – Filter by number of outcomes. Can be exact value or (min, max) tuple.
n_negotiators – Filter by number of negotiators. Can be exact value or (min, max) tuple.
opposition_level – Filter by opposition level. Can be exact value or (min, max) tuple.
format – DEPRECATED. Use tags={‘xml’} or tags={‘json’} instead.
anac – DEPRECATED. Use tags={‘anac’} instead.
normalized – DEPRECATED. Use tags={‘normalized’} instead.
file – DEPRECATED. Use tags={‘file’} instead.
**criteria – Additional attribute-value pairs to match exactly.

Returns:

A dictionary of matching entries (path -> info).

query_by_tag(tag: str) → dict[str, ScenarioInfo][source]¶

Query the registry for scenarios with a specific tag.

This is a convenience method equivalent to query(tags={tag}).

Parameters:: tag – The tag to filter by.
Returns:: A dictionary of matching entries (path -> info).

Parameters:

path – The path to the scenario file or folder.
name – A short name for the scenario. If None, uses the file/folder name.
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
tags – Optional set of tags for categorization and filtering.
n_outcomes – The number of possible outcomes.
n_negotiators – The number of negotiators in the scenario.
opposition_level – The opposition level between negotiators (0-1).
normalized – DEPRECATED. Use tags={‘normalized’} instead.
anac – DEPRECATED. Use tags={‘anac’} instead.
has_stats – DEPRECATED. Use tags={‘has-stats’} instead.
has_plot – DEPRECATED. Use tags={‘has-plot’} instead.
**extra – Additional properties to store.

Returns:

The ScenarioInfo object that was created, or the existing one if already registered.

Note

If the path is already registered, returns the existing registration without modifying it. Registrations never overwrite existing entries.

register_many(registrations: list[dict[str, Any]]) → list[ScenarioInfo][source]¶

Parameters:: registrations – A list of dictionaries, each containing the arguments for a single registration. Each dict must have a ‘path’ key with the path to the scenario. Other keys are passed to register().
Returns:: A list of ScenarioInfo objects for the registered scenarios.

Example

infos = registry.register_many([: {‘path’: ‘/path/to/scenario1’, ‘source’: ‘mylib’, ‘tags’: {‘custom’}}, {‘path’: ‘/path/to/scenario2’, ‘n_negotiators’: 2},

])

unregister(path_or_name: str | Path) → bool[source]¶

Remove a scenario from the registry.

Parameters:: path_or_name – Either the path (as string or Path) or the scenario name. If a name is given and multiple scenarios have that name, all are removed.
Returns:: True if at least one scenario was removed, False if none were found.

Example

# Unregister by path registry.unregister(“/path/to/scenario”)

# Unregister by name (removes all with that name) registry.unregister(“Laptop”)

unregister_many(paths_or_names: list[str | Path]) → int[source]¶

Remove multiple scenarios in a single call.

Parameters:: paths_or_names – A list of paths or names to unregister. If a name is given and multiple scenarios have that name, all are removed.
Returns:: The number of scenarios that were removed.

Example

count = registry.unregister_many([: ‘/path/to/scenario1’, ‘MyScenario’, # removes all with this name

])

negmas.registry.clear_registry(*, include_mechanisms: bool = True, include_negotiators: bool = True, include_components: bool = True, include_scenarios: bool = True) → None[source]¶

Clear all global registries.

This removes all registrations from the specified registries.

Parameters:

include_mechanisms – Whether to clear the mechanism registry.
include_negotiators – Whether to clear the negotiator registry.
include_components – Whether to clear the component registry.
include_scenarios – Whether to clear the scenario registry.

Example

# Clear all registries clear_registry()

# Clear only negotiators clear_registry(

)

negmas.registry.get_registered_class(name: str, registry: Registry[MechanismInfo] | Registry[NegotiatorInfo] | Registry[ComponentInfo]) → type | None[source]¶

Get a registered class by name from a registry.

Parameters:

name – The short name or full type name.
registry – The registry to search.

Returns:

The class, or None if not found.

negmas.registry.load_registry(path: str | Path | None = None, *, include_mechanisms: bool = True, include_negotiators: bool = True, include_components: bool = True, include_scenarios: bool = True, clear_existing: bool = False) → dict[str, int][source]¶

Load registries from a folder.

This function loads previously saved registries from JSON files and adds them to the global registries.

Note: Class registrations require that the classes are importable. If a class cannot be imported, that registration is skipped with a warning.

Parameters:

path – The folder to load from. Defaults to ~/negmas/registry.
include_mechanisms – Whether to load the mechanism registry.
include_negotiators – Whether to load the negotiator registry.
include_components – Whether to load the component registry.
include_scenarios – Whether to load the scenario registry.
clear_existing – If True, clear existing registrations before loading.

Returns:

{‘mechanisms’: N, ‘negotiators’: N, ‘components’: N, ‘scenarios’: N}

Return type:

A dictionary with counts of loaded items

Raises:

FileNotFoundError – If the path does not exist.

Example

# Load from default location counts = load_registry() print(f”Loaded {counts[‘negotiators’]} negotiators”)

# Load from custom location, replacing existing load_registry(“/path/to/my/registry”, clear_existing=True)

# Load only scenarios load_registry(

)

This function recursively searches for valid negotiation scenarios in the given directory and registers them in the scenario registry. It attempts to load each folder as a scenario, and if that fails, searches for YAML files and subfolders that might be scenarios.

The function extracts all available information from each scenario: - n_outcomes: Number of possible outcomes - n_negotiators: Number of negotiators (from utility functions) - normalized: Whether utilities are normalized to [0, 1] - format: The scenario format (xml, json, yaml)

Scenarios are automatically tagged based on their properties: - “bilateral”: 2 negotiators - “multilateral”: 3+ negotiators - Format tag: “xml”, “json”, or “yaml”

Parameters:

path – The root directory to search for scenarios.
tags – Optional tags to add to all registered scenarios.
recursive – If True, recursively search subdirectories.
registry – The registry to use. If None, uses the global scenario_registry.

Returns:

A list of ScenarioInfo objects for successfully registered scenarios.

Raises:

ValueError – If the path does not exist or is not a directory.

Example

# Register all scenarios from a directory from negmas import register_all_scenarios

scenarios = register_all_scenarios(: “/path/to/scenarios”, tags={“custom”, “my-project”},

) print(f”Registered {len(scenarios)} scenarios”)

# Register without recursion scenarios = register_all_scenarios(

)

Decorator to register a component class.

Can be used with or without arguments:

@register_component class MyComponent(Component):

@register_component(component_type=”acceptance”, tags={“builtin”, “rational”}) class MyAcceptancePolicy(AcceptancePolicy):

Parameters:

cls – The class to register (when used without parentheses).
short_name – A short name for the component.
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
params – Default constructor parameters for creating instances.
component_type – The type of component (e.g., ‘acceptance’, ‘offering’, ‘model’).
tags – Set of tags for categorization (e.g., {“builtin”, “rational”}).
**extra – Additional properties to store.

Returns:

The decorated class (unchanged).

Decorator to register a mechanism class.

Can be used with or without arguments:

@register_mechanism class MyMechanism(Mechanism):

@register_mechanism(short_name=”my_mech”, requires_deadline=False, tags={“sao”}) class MyMechanism(Mechanism):

Parameters:

cls – The class to register (when used without parentheses).
short_name – A short name for the mechanism.
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
params – Default constructor parameters for creating instances.
requires_deadline – Whether the mechanism requires a deadline.
tags – Set of tags for categorization (e.g., {“sao”, “builtin”}).
**extra – Additional properties to store.

Returns:

The decorated class (unchanged).

negmas.registry.register_negotiator(cls: type | None = None, *, short_name: str | None = None, source: str = 'unknown', params: dict[str, Any] | None = None, bilateral_only: bool = False, requires_opponent_ufun: bool = False, learns: bool = False, anac_year: int | None = None, supports_uncertainty: bool = False, supports_discounting: bool = False, tags: set[str] | list[str] | tuple[str, ...] | None = None, **extra)[source]¶

Decorator to register a negotiator class.

Can be used with or without arguments:

@register_negotiator class MyNegotiator(Negotiator):

@register_negotiator(bilateral_only=True, learns=True, tags={“builtin”, “aspiration”}) class MyNegotiator(Negotiator):

Parameters:

cls – The class to register (when used without parentheses).
short_name – A short name for the negotiator.
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
params – Default constructor parameters for creating instances.
bilateral_only – Whether the negotiator only works bilaterally.
requires_opponent_ufun – Whether the negotiator needs opponent’s utility.
learns – Whether the negotiator learns from repeated negotiations.
anac_year – ANAC competition year (for Genius negotiators).
supports_uncertainty – Whether uncertain preferences are supported.
supports_discounting – Whether time-discounted utilities are supported.
tags – Set of tags for categorization (e.g., {“builtin”, “aspiration”}).
**extra – Additional properties to store.

Returns:

The decorated class (unchanged).

This function registers a negotiation scenario (a file or folder containing domain and utility definitions) so it can be discovered and used by name.

Parameters:

path – The path to the scenario file or folder.
name – A short name for the scenario. If None, uses the file/folder name.
source – The origin of this registration (‘negmas’ for built-in, library name for external, or ‘unknown’ if not specified).
tags – Optional set of tags for categorization and filtering.
normalized – Whether the scenario utilities are normalized.
n_outcomes – The number of possible outcomes.
n_negotiators – The number of negotiators in the scenario.
anac – Whether this scenario is from an ANAC competition.
has_stats – Whether the scenario has pre-computed statistics.
has_plot – Whether the scenario has a pre-generated plot.
**extra – Additional properties to store.

Returns:

The ScenarioInfo object that was created.

Example

# Register a scenario folder register_scenario(

)

# Register with auto-detection register_scenario(“/path/to/domain.xml”)

negmas.registry.save_registry(path: str | Path | None = None, *, include_mechanisms: bool = True, include_negotiators: bool = True, include_components: bool = True, include_scenarios: bool = True) → Path[source]¶

Save all registries to a folder.

This function serializes the global registries (mechanisms, negotiators, components, and scenarios) to JSON files in the specified folder.

Note: Only metadata is saved. Class registrations store the full type name, so the classes must be importable when loading. Scenario registrations store the path, so the scenario files must exist when loading.

Parameters:

path – The folder to save to. Defaults to ~/negmas/registry.
include_mechanisms – Whether to save the mechanism registry.
include_negotiators – Whether to save the negotiator registry.
include_components – Whether to save the component registry.
include_scenarios – Whether to save the scenario registry.

Returns:

The path where the registries were saved.

Example

# Save to default location save_registry()

# Save to custom location save_registry(“/path/to/my/registry”)

# Save only negotiators and scenarios save_registry(include_mechanisms=False, include_components=False)