relationship

bamengine.core.decorators.relationship(cls=None, *, source=None, target=None, cardinality='many-to-many', name=None, **dataclass_kwargs)

Decorator to define a Relationship with automatic inheritance and registration.

This decorator dramatically simplifies Relationship definition by: 1. Making the class inherit from Relationship (if not already) 2. Applying @dataclass(slots=True) 3. Setting source/target roles as class variables 4. Setting cardinality 5. Registering the relationship in the global registry

Parameters:

• cls (type | None) – The class to decorate (provided automatically when used without parens)

• source (type[Role], optional) – Source role type (e.g., Borrower)

• target (type[Role], optional) – Target role type (e.g., Lender)

• cardinality ({"many-to-many", "one-to-many", "many-to-one"}, default "many-to-many") – Relationship cardinality

• name (str, optional) – Custom name for the relationship. If None, uses the class name.

• **dataclass_kwargs (Any) – Additional keyword arguments to pass to @dataclass. By default, slots=True is set.

Returns:

The decorated class or a decorator function

Return type:

type | Callable

Examples

Simplest usage:

>>> from bamengine import get_role
>>> from bamengine.typing import Float, Int
>>> @relationship(source=get_role("Borrower"), target=get_role("Lender"))
... class LoanBook:
...     principal: Float
...     rate: Float
...     interest: Float
...     debt: Float

With custom name and cardinality:

>>> @relationship(
...     source=get_role("Worker"),
...     target=get_role("Employer"),
...     cardinality="many-to-many",
...     name="MultiJobEmployment",
... )
... class Employment:
...     wage: Float
...     contract_duration: Int