relationalai 0.13.5__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

v0/relationalai/early_access/dsl/ontologies/python_printer.py

@@ -0,0 +1,303 @@
+import json
+import typing
+from collections import defaultdict
+from typing import TypeVar
+
+from v0.relationalai.early_access.dsl import Model, ExternalRelation, ValueType, ValueSubtype, Relationship
+from v0.relationalai.early_access.dsl.core.types import Type
+from v0.relationalai.early_access.dsl.core.types.standard import standard_value_types
+from v0.relationalai.early_access.dsl.ontologies.constraints import Mandatory, Unique, RoleValueConstraint
+from v0.relationalai.early_access.dsl.ontologies.roles import AbstractRole
+from v0.relationalai.early_access.dsl.ontologies.subtyping import SubtypeConstraint, SubtypeArrow, \
+    ExclusiveSubtypeConstraint, InclusiveSubtypeConstraint
+from v0.relationalai.early_access.dsl.types.concepts import Concept
+from v0.relationalai.semantics.metamodel.util import Printer, OrderedSet
+
+# Define a generic type variable constrained to SubtypeConstraint or its subclasses
+T = TypeVar("T", bound=SubtypeConstraint)
+
+class PythonPrinter(Printer):
+    _mandatory_roles: 'OrderedSet[AbstractRole]'
+    _single_unique_roles: 'OrderedSet[AbstractRole]'
+    _composite_preferred_identifiers: 'OrderedSet[Unique]'
+    _internal_preferred_identifier_roles: 'OrderedSet[AbstractRole]'
+    _relationship_uniqueness_constraints: 'dict[Relationship, OrderedSet[Unique]]'
+
+    def __init__(self, io: typing.Optional[typing.IO[str]] = None):
+        # Set the base class field (frozen)
+        object.__setattr__(self, 'io', io)
+
+        # Set all mutable fields using object.__setattr__
+        object.__setattr__(self, '_mandatory_roles', OrderedSet())
+        object.__setattr__(self, '_single_unique_roles', OrderedSet())
+        object.__setattr__(self, '_composite_preferred_identifiers', OrderedSet())
+        object.__setattr__(self, '_internal_preferred_identifier_roles', OrderedSet())
+        object.__setattr__(self, '_relationship_uniqueness_constraints', defaultdict(OrderedSet))
+
+    def to_python_string(self, model: Model) -> None:
+        self._process_constraints(model)
+
+        self._print_nl("import relationalai.early_access.dsl as rai")
+        self._nl()
+
+        self._print_nl(f"model = rai.Model(name='{model.name}', is_primary={model.is_primary})")
+        self._print_nl("Concept = model.concept")
+        self._print_nl("ValueType = model.value_type")
+        self._print_nl("ValueSubType = model.value_sub_type")
+        self._print_nl("EntityType = model.entity_type")
+        self._print_nl("SubtypeArrow = model.subtype_arrow")
+        self._print_nl("Relationship = model.relationship")
+        self._print_nl("RefScheme = model.ref_scheme")
+        self._print_nl("ExternalRelation = model.external_relation")
+        self._print_nl("Query = model.query")
+        self._print_nl("RoleValueConstraint = model.role_value_constraint")
+        self._print_nl("CsvTable = model.csv_table")
+
+        self._nl()
+        self._handle_value_types(model)
+
+        self._nl()
+        self._handle_entity_types(model)
+
+        self._nl()
+        self._handle_relationships(model)
+
+        self._handle_composite_reference_schemas()
+
+        self._nl()
+        self._handle_subtype_arrows(model)
+
+        self._nl()
+        self._handle_external_relations(model)
+
+        self._nl()
+        self._handle_role_value_constraints(model)
+
+    def _handle_value_types(self, model: Model) -> None:
+        for vt in model.value_types():
+            name = vt.display()
+            if isinstance(vt, ValueType):
+               self._print_nl(f"{name} = ValueType('{name}', {', '.join(self._get_type(t) for t in vt._types)})")
+            elif isinstance(vt, ValueSubtype) and vt.parent():
+                self._print_nl(f"{name} = ValueSubType('{name}', {self._get_type(vt.parent())})")
+            elif isinstance(vt, Concept):
+                self._print_nl(f"{name} = ValueType('{name}', {', '.join(self._get_type(t) for t in vt._types)})")
+
+    def _handle_entity_types(self, model: Model) -> None:
+        for name, et in model.entity_types_map().items():
+            self._print_nl(f"{name} = EntityType('{name}'{self._print_if_not_empty('ref_mode', et.ref_schema_name())})")
+
+    def _handle_relationships(self, model: Model) -> None:
+        for rel in model.relationships():
+            if not rel.is_subtype():
+                self._print_nl("with Relationship() as rel:")
+                self._handle_relationship_roles(rel)
+                self._handle_relationship_relations(rel)
+                self._handle_relationship_uniqueness_constraints(rel, self._relationship_uniqueness_constraints.get(rel, OrderedSet()))
+                self._nl()
+
+    def _handle_relationship_roles(self, rel):
+        for i, r in enumerate(rel.roles()):
+            self._indent_print_nl(1, f"rel.role({self._get_type(r.player())}"
+                                     f"{self._print_if_not_empty('name', r.name())}"
+                                     f"{self._print_if_true('unique', r in self._single_unique_roles)}"
+                                     f"{self._print_if_true('mandatory', r in self._mandatory_roles)}"
+                                     f"{self._print_if_true('primary_key', r in self._internal_preferred_identifier_roles)})")
+            if r.prefix or r.postfix:
+                elements = list(filter(None, [
+                    self._print_first_if_not_empty('prefix', r.prefix),
+                    self._print_first_if_not_empty('postfix', r.postfix)
+                ]))
+                self._indent_print_nl(1, f"rel.role_at({i}).verbalization({', '.join(elements)})")
+
+    def _handle_relationship_relations(self, rel):
+        for relation in rel.relations():
+            reading = relation.reading()
+            if reading:
+
+                num_roles = len(reading.roles)
+                num_texts = len(reading.text_frags)
+
+                elements = []
+
+                for i in range(num_texts):
+                    role = reading.role_at(i)
+                    elements.append(f"rel.role_at({rel.role_index(role)})")  # Role first
+                    elements.append(f"'{reading.text_frags[i]}'")  # Then text
+
+                if num_roles > num_texts:
+                    role = reading.role_at(num_texts)
+                    elements.append(f"rel.role_at({rel.role_index(role)})")  # Add last role if needed
+
+                self._indent_print_nl(1, f"rel.relation({', '.join(elements)}"
+                                         f"{self._print_if_not_empty('name', reading.rel_name)}"
+                                         f"{self._print_if_true('functional', relation.signature().functional())})")
+
+    def _handle_relationship_uniqueness_constraints(self, rel, constraints: OrderedSet[Unique]) -> None:
+        for c in constraints:
+            elements = [f"rel.role_at({rel.role_index(role)})" for role in c.roles()]
+            self._indent_print_nl(1, f"rel.unique({', '.join(elements)})")
+
+    def _handle_composite_reference_schemas(self) -> None:
+        for preferred_id in self._composite_preferred_identifiers:
+
+            elements = []
+
+            for role in preferred_id.roles():
+                relationship = role.part_of
+
+                relation = self._lookup_relation_by_second_role(relationship, role)
+
+                player_name = self._get_type(relation.first())
+                rel_name = relation.rel_name()
+                elements.append(f"{player_name}.{rel_name}")
+
+            self._print_nl(f"RefScheme({', '.join(elements)})")
+
+    def _handle_subtype_arrows(self, model:Model) -> None:
+        subtype_arrows_by_type = self._group_subtype_arrows_by_type(model)
+        inclusive_subtype_constraints_by_type = self._get_inclusive_subtype_constraints_by_type(model)
+        exclusive_subtype_constraints_by_type = self._get_exclusive_subtype_constraints_by_type(model)
+
+        for et in model.entity_types():
+
+            subtype_arrows = subtype_arrows_by_type.get(et, OrderedSet())
+            inclusive_subtype_constraints = inclusive_subtype_constraints_by_type.get(et, OrderedSet())
+            exclusive_subtype_constraints = exclusive_subtype_constraints_by_type.get(et, OrderedSet())
+
+            name = et.display()
+
+            # Common elements in both sets
+            common_constraints = [i for i in inclusive_subtype_constraints
+                                    for e in exclusive_subtype_constraints
+                                    if self.constraints_equal(i, e)]
+            if len(common_constraints) > 0:
+                for c in common_constraints:
+                    self._print_nl(f"SubtypeArrow({name}, [{', '.join(self._get_type(a.start) for a in c.arrows)}], "
+                                   f"exclusive=True, inclusive=True)")
+
+            # Only in inclusive (but not in exclusive)
+            only_inclusive_constraints = [i for i in inclusive_subtype_constraints
+                                            if not any(self.constraints_equal(i, e) for e in exclusive_subtype_constraints)]
+            if len(only_inclusive_constraints) > 0:
+                for c in only_inclusive_constraints:
+                    self._print_nl(f"SubtypeArrow({name}, [{', '.join(self._get_type(a.start) for a in c.arrows)}], "
+                                   f"inclusive=True)")
+
+            # Only in exclusive (but not in inclusive)
+            only_exclusive_constraints = [e for e in exclusive_subtype_constraints
+                                            if not any(self.constraints_equal(e, i) for i in inclusive_subtype_constraints)]
+            if len(only_exclusive_constraints) > 0:
+                for c in only_exclusive_constraints:
+                    self._print_nl(f"SubtypeArrow({name}, [{', '.join(self._get_type(a.start) for a in c.arrows)}], "
+                                   f"exclusive=True)")
+
+            # Get all arrows from both inclusive and exclusive constraints
+            all_arrows_in_constraints = OrderedSet.from_iterable(a for c in inclusive_subtype_constraints for a in c.arrows) | \
+                                        OrderedSet.from_iterable(a for c in exclusive_subtype_constraints for a in c.arrows)
+
+            # Subtract the arrows in constraints from subtype_arrows
+            remaining_subtype_arrows = subtype_arrows - all_arrows_in_constraints
+            if len(remaining_subtype_arrows) > 0:
+                self._print_nl(f"SubtypeArrow({name}, [{', '.join(self._get_type(a.start) for a in remaining_subtype_arrows)}])")
+
+    def _handle_external_relations(self, model: Model) -> None:
+        for relation in self._get_external_relations(model):
+            name = relation.rel_name()
+            type_args = ', '.join(self._get_type(t) for t in relation.signature().types())
+
+            if name == "output":
+                self._print_nl(f"Query({type_args})")
+            else:
+                self._print_nl(f"ExternalRelation('{name}', {type_args})")
+
+    def _handle_role_value_constraints(self, model: Model) -> None:
+        for c in self._get_role_value_constraints(model):
+            role = c.role()
+            relationship = role.part_of
+
+            relation = self._lookup_relation_by_second_role(relationship, role)
+
+            player_name = self._get_type(relation.first())
+            rel_name = relation.rel_name()
+
+            self._print_nl(f"RoleValueConstraint({player_name}.{rel_name}, {json.dumps(c.values())})")
+
+    def _process_constraints(self, model: Model) -> None:
+        for c in model.constraints():
+            if isinstance(c, Mandatory):
+                self._mandatory_roles.add(c.role)
+            elif isinstance(c, Unique):
+                if c.is_preferred_identifier:
+                    if len(c.roles()) == 1:
+                        self._internal_preferred_identifier_roles.add(c.roles()[0])
+                    else:
+                        self._composite_preferred_identifiers.add(c)
+                elif len(c.roles()) == 1:
+                    self._single_unique_roles.add(c.roles()[0])
+                else:
+                    self._relationship_uniqueness_constraints[c.roles()[0].part_of].add(c)
+
+    @staticmethod
+    def _group_subtype_arrows_by_type(model: Model) -> dict[Type, OrderedSet[SubtypeArrow]]:
+        subtype_arrows_by_type = defaultdict(OrderedSet)
+        for a in model.subtype_arrows():
+            subtype_arrows_by_type[a.end].add(a)
+        return dict(subtype_arrows_by_type)
+
+    @staticmethod
+    def _get_subtype_constraints_by_type(model: Model, constraint_type: typing.Type[T]) -> dict[Type, OrderedSet[SubtypeConstraint]]:
+        constraints_by_type: dict[Type, OrderedSet[SubtypeConstraint]] = defaultdict(OrderedSet)
+
+        for c in model.subtype_constraints():
+            if isinstance(c, constraint_type):
+                for a in c.arrows:
+                    constraints_by_type[a.end].add(c)
+
+        return dict(constraints_by_type)
+
+    def _get_exclusive_subtype_constraints_by_type(self, model: Model) -> dict[Type, OrderedSet[SubtypeConstraint]]:
+        return self._get_subtype_constraints_by_type(model, ExclusiveSubtypeConstraint)
+
+    def _get_inclusive_subtype_constraints_by_type(self, model: Model) -> dict[Type, OrderedSet[SubtypeConstraint]]:
+        return self._get_subtype_constraints_by_type(model, InclusiveSubtypeConstraint)
+
+    @staticmethod
+    def _get_role_value_constraints(model: Model) -> OrderedSet[RoleValueConstraint]:
+        return OrderedSet.from_iterable(c for c in model.constraints() if isinstance(c, RoleValueConstraint))
+
+    @staticmethod
+    def _get_external_relations(model: Model) -> OrderedSet[ExternalRelation]:
+        return OrderedSet.from_iterable(r for r in model.relations() if isinstance(r, ExternalRelation))
+
+    @staticmethod
+    def _lookup_relation_by_second_role(relationship, role):
+        # Find the matching relation where the 2nd role is `role`
+        relation = next(
+            (rel for rel in relationship.relations() if rel.reading().roles[1] == role),
+            None
+        )
+        if relation is None:
+            raise Exception(f"Could not find matching relation for role player {role.player().name()} "
+                            f"in relationship {relationship._name()}")
+        return relation
+
+    @staticmethod
+    def constraints_equal(a: SubtypeConstraint, b: SubtypeConstraint) -> bool:
+        return frozenset(a.arrows) == frozenset(b.arrows)
+
+    @staticmethod
+    def _get_type(t: Type) -> str:
+        return f"rai.{t.display()}" if t.display() in standard_value_types else t.display()
+
+    @staticmethod
+    def _print_if_not_empty(label: str, value: str) -> str:
+        return f", {label}='{value}'" if value else ""
+
+    @staticmethod
+    def _print_first_if_not_empty(label: str, value: str) -> str:
+        return f"{label}='{value}'" if value else ""
+
+    @staticmethod
+    def _print_if_true(label: str, value: bool) -> str:
+        return f", {label}=True" if value else ""

v0/relationalai/early_access/dsl/ontologies/readings.py

@@ -0,0 +1,60 @@
+from typing import List, Optional
+
+from v0.relationalai.early_access.dsl.core.types import Type
+from v0.relationalai.early_access.dsl.core.utils import generate_stable_uuid
+from v0.relationalai.early_access.dsl.ontologies.roles import AbstractRole
+from v0.relationalai.early_access.dsl.utils import build_relation_name, build_relationship_name
+
+
+class Reading:
+
+    # We initialize a Reading with a tuple that mixes text with Roles.
+    #
+    def __init__(self, *args, name: Optional[str] = None):
+        self.rel_name = name  # Local name of Relation that materializes this Reading
+        self.roles = []
+        self.text_frags = []
+        for i in range(len(args)):
+            a = args[i]
+            if isinstance(a, str):
+                self.text_frags.append(a)
+            else:
+                if isinstance(a, AbstractRole):
+                    self.roles.append(a)
+                else:
+                    raise Exception(f"Unknown Reading component {a} -- should be either text or a Role")
+
+    def guid(self):
+        return generate_stable_uuid(self.verbalize())
+
+    def types(self) -> List[Type]:
+        return [role.player() for role in self.roles]
+
+    def template(self):
+        temp_frags = []
+        for i in range(len(self.roles)):
+            temp_frags.append('{' + f"{i}" + '}')
+            if i in range(len(self.text_frags)):
+                temp_frags.append(self.text_frags[i])
+        return " ".join(temp_frags)
+
+    def verbalize(self):
+        temp_frags = []
+        for i in range(len(self.roles)):
+            temp_frags.append(self.roles[i].verbalize())
+            if i in range(len(self.text_frags)):
+                temp_frags.append(self.text_frags[i])
+        return " ".join(temp_frags)
+
+    def to_rel_name(self):
+        if self.rel_name:
+            return self.rel_name
+        return build_relation_name(self.roles, self.text_frags)
+
+    def to_relationship_name(self):
+        return build_relationship_name(self.roles, self.text_frags)
+
+    def role_at(self, idx):
+        if idx < 0 or idx >= len(self.roles):
+            raise Exception(f'Role index {idx} out of bounds for Reading {self.to_rel_name()}')
+        return self.roles[idx]

v0/relationalai/early_access/dsl/ontologies/relationships.py

@@ -0,0 +1,322 @@
+from collections import OrderedDict, defaultdict
+from typing import Optional
+
+from v0.relationalai.early_access.dsl import Relation
+from v0.relationalai.early_access.dsl.core.exprs import contextStack
+from v0.relationalai.early_access.dsl.core.namespaces import Namespace
+from v0.relationalai.early_access.dsl.core.types import Type
+from v0.relationalai.early_access.dsl.core.utils import generate_stable_uuid, camel_to_snake
+from v0.relationalai.early_access.dsl.ontologies.constraints import Unique, Mandatory
+from v0.relationalai.early_access.dsl.ontologies.readings import Reading
+from v0.relationalai.early_access.dsl.ontologies.roles import Role
+from v0.relationalai.early_access.dsl.types import AbstractConcept
+from v0.relationalai.early_access.dsl.utils import extract_relation_text_with_signature
+from v0.relationalai.semantics.metamodel.util import OrderedSet
+
+
+class Relationship:
+
+    def __init__(self, model, *args, relation_name: Optional[str] = None):
+        self._model = model
+        self._is_subtype = False
+        self._is_identifier = False
+        self._readings_map = OrderedDict()
+        self._rolemap = OrderedDict()
+        self._constraints = []
+        self._relations = OrderedSet()
+        if not contextStack.empty():
+            tp = contextStack.root_context()
+            if isinstance(tp, Namespace):
+                self._namespace = tp
+            else:
+                self._namespace = Namespace.top
+        else:
+            self._namespace = Namespace.top
+        if len(args) != 0:
+            reading = self._reading_from_args(*args, relation_name=relation_name)
+            for role in reading.roles:
+                self._add_role(role)
+            self._add_relation(reading)
+
+    def __call__(self, *args, **kwargs):
+        return self.relation(*args, **kwargs)
+
+    def __enter__(self):
+        contextStack.push(self)
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        contextStack.pop()
+        pass
+
+    def __getitem__(self, key):
+        return self._readings_map[key]
+
+    def __setitem__(self, key, value):
+        if key in self._readings_map:
+            raise Exception(
+                f'Cannot provide multiple Readings for the relation name {key} in Relationship {self._name()}')
+        else:
+            if not isinstance(value, Reading):
+                value = Reading(*value)
+
+            if value.rel_name is not None:
+                # [VAMI] TODO: check if we need this warning
+                # warn(f'Overriding rel_name of Reading "{value.verbalize()}" from "{value.rel_name}" to "{key}"')
+                pass
+            self._readings_map[key] = value
+            value.rel_name = key
+            return value
+
+    def __setattr__(self, key: str, value: Role) -> None:
+        if key.startswith('_') or key in self.__dict__:
+            super().__setattr__(key, value)
+        elif isinstance(value, Role):
+            value.part_of = self
+            self._add_role(value)
+            super().__setattr__(key, value)
+        else:
+            raise TypeError(f'Expected a Role instance for "{key}", got {type(value)}')
+
+    def __getattr__(self, key):
+        if key in self._rolemap:
+            return self._rolemap[key]
+        else:
+            raise AttributeError(f'Relationship {self._name()} has no Role named {key}')
+
+    def _reading_from_args(self, *args, relation_name: Optional[str] = None):
+        text_frags, sig = extract_relation_text_with_signature(*args)
+        grouped_sig = defaultdict(list)
+        for t in sig:
+            grouped_sig[t.display()].append(t)
+        reading_args = []
+        index_map = {}
+        # store indexes for roles player by the same Concept
+        for t_name in grouped_sig:
+            group_size = len(grouped_sig[t_name])
+            if group_size > 1:
+                index_map[t_name] = group_size
+        for idx, t in enumerate(sig):
+            reading_args.append(Role(t, self, idx, name=self._get_role_name(t, index_map)))
+            if idx < len(text_frags):
+                reading_args.append(text_frags[idx])
+        return Reading(*reading_args, name=relation_name)
+
+    def _get_role_name(self, t, index_map):
+        name = None
+        if t.display() in index_map:
+            idx = index_map.get(t.display())
+            index_map[t.display()] -= 1
+            name = f"{camel_to_snake(t.display())}{idx}"
+        return name
+
+    def _name(self):
+        return list(self._readings_map.values())[0].to_relationship_name()
+
+    def _set_subtype(self):
+        self._is_subtype = True
+        return self
+
+    def is_subtype(self):
+        return self._is_subtype
+
+    def _set_identifier(self):
+        self._is_identifier = True
+        return self
+
+    def is_identifier(self):
+        return self._is_identifier
+
+    def guid(self):
+        return generate_stable_uuid(self._name())
+
+    def role(self, concept, name: Optional[str] = None, unique: bool = False, primary_key: bool = False,
+             mandatory: bool = False) -> 'Relationship':
+        role = Role(concept, pos=self.arity(), name=name, rel=self)
+        self._add_role(role)
+        setattr(self, role.ref_name(), role)
+
+        # check constraints
+        if primary_key:
+            # takes care of implied mandatory and unique constraints
+            self.primary_key(role)
+        elif unique and not primary_key:
+            self.unique(role)
+        if mandatory:
+            self.mandatory(role)
+        return self
+
+    def role_at(self, idx):
+        if idx < 0 or idx >= self.arity():
+            raise Exception(f'Role index {idx} out of bounds for Relationship {self._name()}')
+        return list(self._rolemap.values())[idx]
+
+    def role_by_name(self, name: str):
+        if name not in self._rolemap:
+            raise AttributeError(f'Role `{name}` not found in Relationship {self._name()}, '
+                            f'possible candidates are: {self._rolemap.keys()}')
+        return self._rolemap[name]
+
+    def role_index(self, role: Role):
+        for idx, r in enumerate(self._rolemap.values()):
+            if r == role:
+                return idx
+        raise Exception(f'Role `{role.ref_name()}` not found in Relationship {self._name()}')
+
+    def roles(self):
+        return list(self._rolemap.values())
+
+    def arity(self):
+        return len(self._rolemap)
+
+    def relation(self, *args, name: Optional[str] = None, functional: bool=False) -> 'Relationship':
+        return self._add_relation(Reading(*args, name=name), functional=functional)
+
+    def _add_role(self, rol):
+        self._rolemap[rol.ref_name()] = rol
+        return self
+
+    def _add_reading(self, rdg):
+        if not isinstance(rdg, Reading):
+            raise Exception(f'Tried to add non-Reading {rdg} as a reading of Relationship {self._name()}')
+
+        self[rdg.to_rel_name()] = rdg
+
+    def _add_relation(self, reading: Reading, functional: bool=False) -> 'Relationship':
+        self._add_reading(reading)
+        first_player = reading.roles[0].player()
+        namespace = Namespace(camel_to_snake(first_player.display()), self._namespace)
+        relation = self._model._add_relation(Relation(namespace, reading, self, functional))
+        self._relations.add(relation)
+        # do not add relations to standard types like String, Date, Integer etc.
+        if isinstance(first_player, AbstractConcept):
+            first_player._add_relation(relation)
+        # sync relationship and roles with the model once relationship have at least 1 reading
+        if len(self._readings_map) == 1:
+            self._model._add_relationship(self)
+            for c in self._constraints:
+                self._model.constraint(c)
+        return self
+
+    def build_relation_variable(self, args, kwargs):
+        return self.new_role(args, kwargs)
+
+    def build_scalar_variable(self, args, kwargs):
+        return self.new_role(args, kwargs)
+
+    def new_role(self, args, kwargs):
+        if len(args) == 0:
+            raise Exception(f'Unexpected error in Relationship {self._name()}')
+
+        if len(args) > 2:
+            raise Exception(
+                f'Cannot declare role of Relationship {self._name()} by supplying more than a player type and a UUID')
+
+        if len(kwargs) != 0:
+            raise Exception(
+                f'Cannot use keyword arguments when instantiating a type parameter for Relationship {self._name()}')
+
+        type = args[0]
+
+        pre_bound_text = kwargs['pre_bound_text'] if 'pre_bound_text' in kwargs else None
+        post_bound_text = kwargs['post_bound_text'] if 'post_bound_text' in kwargs else None
+
+        if not isinstance(type, Type):
+            raise Exception('Can only instantiate a Role with a Type as its player')
+        role = Role(type, self, self.arity()).verbalization(pre_bound_text, post_bound_text)
+
+        self._add_role(role)
+        return role
+
+    def readings(self):
+        return list(self._readings_map.values())
+
+    def relations(self):
+        return self._relations
+
+    # Constraints
+
+    def unique(self, *roles):
+        """Add a uniqueness constraint on specified roles."""
+        self._add_constraint(Unique(*roles))
+        return self
+
+    def mandatory(self, *roles):
+        """Add a mandatory constraint on specified roles."""
+        self._add_constraint(Mandatory(*roles))
+        return self
+
+    def primary_key(self, role):
+        """Set the simple reference schema & uniqueness constraint."""
+        sibling = role.sibling()
+        if sibling is None:
+            raise ValueError(f"Cannot set primary key on '{role}': it has no sibling role.")
+
+        sibling_type = sibling.player()
+        sibling_domain = sibling_type.domain()
+        role_player = role.player()
+
+        if not sibling_domain:
+            sibling_domain.append(role_player)
+        elif sibling_domain[0] != role_player:
+            raise ValueError(
+                f"Cannot set primary key on '{role}': domain mismatch. "
+                f"Expected {sibling_domain[0]}, got {role_player}."
+            )
+
+        self._add_constraint(Unique(*[role], is_preferred_identifier=True))
+        self._add_constraint(Unique(*[sibling]))
+        self._add_constraint(Mandatory(sibling))
+
+        self._model._entity_to_identifier[sibling_type] = self
+
+        return self
+
+    def _add_constraint(self, con):
+        self._constraints.append(con)
+        if not self.is_empty():
+            self._model.constraint(con)
+
+    # pretty printing readings
+    def pprint(self):
+        return f'relationship {self._name()}[{", ".join([r.verbalize() for r in self.readings()])}]'
+
+    def is_empty(self):
+        return len(self.readings()) == 0
+
+class Attribute(Relationship):
+    def __init__(
+            self,
+            model,
+            concept,
+            attr,
+            mandatory: bool = False,
+            primary_key: bool = False,
+            reading_text: Optional[str] = None,
+            reverse_reading_text: Optional[str] = None
+    ):
+        if reading_text is None:
+            reading_text = 'has'
+
+        super().__init__(model, concept, reading_text, attr)
+        concept_role = self.role_at(0)
+        self.unique(concept_role)
+        if mandatory:
+            self.mandatory(concept_role)
+
+        attr_role = self.attr()
+        if primary_key:
+            self.primary_key(attr_role)
+
+        if reverse_reading_text is not None:
+            self.relation(attr_role, reverse_reading_text, concept_role)
+
+    def attr(self):
+        return self.role_at(1)
+
+def _reading_to_relationship_name(reading: str) -> str:
+    """
+    Takes a readable `reading` string and returns the middle part of the Relationship name.
+
+    This is done by removing spaces and converting the result to PascalCase."""
+    return ''.join(word.capitalize() for word in reading.split(' '))