registry#

Registry system for roles, events and relationships.

Provides global lookup for all registered roles, events, and relationships in the BAM Engine. Registration happens automatically via __init_subclass__ hooks, eliminating manual registration boilerplate.

Design Notes#

Thread-safe read-only access (registries populated at import time)
No dynamic registration after initialization
Clear error messages with suggestions for misspellings
List functions for discovery (list_roles, list_events, list_relationships)

Usage Pattern#

Automatic registration (happens at import):

>>> from dataclasses import dataclass
>>> from bamengine.core import Role
>>> from bamengine import Float
>>>
>>> @dataclass(slots=True)
... class MyRole(Role):
...     field: Float
>>> # MyRole is now automatically registered!

Retrieval:

>>> from bamengine.core.registry import get_role
>>> role_cls = get_role("MyRole")
>>> import numpy as np
>>> instance = role_cls(field=np.array([1.0, 2.0, 3.0]))

Discovery:

>>> from bamengine.core.registry import list_roles
>>> all_roles = list_roles()
>>> print(all_roles)
['Borrower', 'Consumer', 'Employer', 'Lender', 'MyRole', 'Producer', 'Worker']

Error Handling#

If a role/event is not found, registry functions raise KeyError with helpful message listing all available options:

>>> get_role("Producter")  # Typo in name
Traceback (most recent call last):
    ...
KeyError: Role 'Producter' not found in registry.
Available roles: Borrower, Consumer, Employer, Lender, Producer, Worker

Functions#

`get_role`	Retrieve a role class from the registry by name.
`get_event`	Retrieve an event class from the registry by name.
`get_relationship`	Retrieve a relationship class from the registry by name.
`list_roles`	Return sorted list of all registered role names.
`list_events`	Return sorted list of all registered event names.
`list_relationships`	Return sorted list of all registered relationship names.
`clear_registry`	Clear all registrations (useful for testing).