relationalai 0.13.0.dev0__py3-none-any.whl → 0.13.1__py3-none-any.whl

relationalai/early_access/dsl/orm/relationships.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+from typing import Optional, Any, Union
+
+import re
+import relationalai.semantics as qb
+from relationalai.semantics.internal.internal import RelationshipFieldRef, Field
+from relationalai.early_access.dsl.core.utils import generate_stable_uuid
+from relationalai.early_access.dsl.orm.utils import generate_rai_way_name
+
+##########
+# Utility functions for parsing RelationshipReading patterns
+#
+
+def leading_text_of(reading: RelationshipReading):
+    pattern = r"^([^{]*).*$"
+    return re.findall(pattern, reading._madlib)[0].strip()
+
+# Returns the dictionary of texts following a role (empty string if not present)
+# indexed by the role position
+#
+def roles_data_from(reading: RelationshipReading):
+    # This pattern capture the player name (with optional role name) and the following text for each
+    # role in the madlib string
+    # \{([^{}]*)\}   Player or role_name:Player
+    # ([^{]*)       Following text
+    pattern = r"\{([^{}]*)\}([^{]*)"
+
+    matches = re.findall(pattern, reading._madlib)
+    following_texts = dict()
+
+    for i, (_, follows) in enumerate(matches):
+        following_texts[i] = follows.strip()
+    return following_texts
+
+# Analyzes a substring of relationship-reading pattern text that contains
+# no role occurrences and refines it into a triple of 3 optional strings:
+#
+#  - post: is a substring of text that post-binds to the role occurrence
+#    that this text follows
+#  - inter: is a substring that is not part of any post or pre bound text
+#  - pre: is a substring that pre-binds the role occurrence that follows
+#    this text sequence in the original reading pattern.
+#
+# Any of these sequences could be empty on return.
+#
+def refine_reading_text(text):
+    found_prefix = False
+    post = None
+    inter = None
+    pre = None
+
+    inter_seq = []
+    pre_seq = []
+
+    tokens = text.split()
+    for v in tokens:
+        if v.startswith('-'):
+            if found_prefix:
+                raise Exception(f"Malformed reading text {text} has prefix text preceding postfix text")
+            inter_seq.append(v[1:])
+            post = " ".join(inter_seq)
+            inter_seq = []
+        elif v.endswith('-'):
+            if found_prefix:
+                raise Exception(f"Malformed reading text {text} has multple postfix text delimeters")
+            found_prefix = True
+            pre_seq = [ v[0:len(v)-1] ]
+        else:
+            if found_prefix:
+                pre_seq.append(v)
+            else:
+                inter_seq.append(v)
+
+    if len(pre_seq) > 0:
+        pre = " ".join(pre_seq)
+    if len(inter_seq) > 0:
+        inter = " ".join(inter_seq)
+
+    return (post, inter, pre)
+
+
+class Relationship(qb.Relationship):
+
+    def __init__(self, model, madlib:Any, short_name:str="", fields:Optional[list[Field]]=None):
+        super().__init__(madlib, short_name=short_name, model=model.qb_model(), fields=fields)
+        self._dsl_model = model
+        self._rel_roles = {field.name: self.__getitem__(field.name) for field in self._fields}
+        self._readings[0] = RelationshipReading(self._dsl_model, madlib, self, short_name)
+
+    def __getitem__(self, arg:Union[str, int, qb.Concept]) -> Any:
+        rel_field_ref = super().__getitem__(arg)
+        field_name = rel_field_ref._field_ref._name
+        if hasattr(self, "_rel_roles"):
+            if field_name in self._rel_roles:
+                return self._rel_roles[field_name]
+            else:
+                raise ValueError(f"{arg} is undefined for {self._name}")
+        return Role._from_field(rel_field_ref)
+
+    def _guid(self):
+        return generate_stable_uuid(str(self._id))
+
+    def alt(self, madlib:Any, short_name:str = "", reading:qb.RelationshipReading|None = None) -> qb.RelationshipReading:
+        return super().alt(madlib, short_name=short_name,
+                           reading=RelationshipReading(self._dsl_model, madlib, self, short_name))
+
+    def _unary(self):
+        return self._arity() == 1
+
+    def _binary(self):
+        return self._arity() == 2
+
+    def _first(self):
+        return self.__getitem__(0)
+
+    def _roles(self):
+        return [self._rel_roles[field.name] for field in self._fields]
+
+
+class RelationshipReading(qb.RelationshipReading):
+
+    def __init__(self, model, madlib:Any, alt_of:Relationship, short_name:str):
+        super().__init__(madlib, alt_of, short_name, model=model.qb_model())
+        self._dsl_model = model
+        self._prepare()
+
+    def __getitem__(self, arg:Union[str, int, qb.Concept]) -> Any:
+        return Role._from_field(super().__getitem__(arg))
+
+    def _guid(self):
+        return generate_stable_uuid(str(self._id))
+
+    def _unary(self):
+        return self._arity() == 1
+
+    def _binary(self):
+        return self._arity() == 2
+
+    def _first(self):
+        return self.__getitem__(0)
+
+    def _last(self):
+        roles = self._roles()
+        return roles[len(roles) - 1]
+
+    def _roles(self):
+        return [self._alt_of._rel_roles[field.name] for field in self._fields]
+
+    def rai_way_name(self):
+        return generate_rai_way_name(self)
+
+    def _sample_fact(self) -> str:
+        verb = []
+        for idx in range(len(self._role_in_reading)):
+            verb.append(str(self._role_in_reading[idx]))
+            follows = self._follows[idx]
+            if follows is not None:
+                verb.append(follows)
+        return ' '.join(verb)
+
+    # Analyzes the reading pattern supplied with this reading to compute:
+    #  - the leading text (or None)
+    #  - the sequence of role occurrences in this reading order, and
+    #  - the sequence of text fragments that follow each role occurrence
+    #    in this reading order
+    #
+    def _prepare(self):
+
+        self._follows: list[Optional[str]] = []
+        self._role_in_reading: list[RoleOccurrence] = []
+
+        (post, self._leading_text, pre) = refine_reading_text(leading_text_of(self))
+        pre_seq = {0: pre}
+        role_seq = self._roles()
+
+        idx = 0
+        dict = roles_data_from(self)
+        for v in dict.values():
+            (post, inter, pre) = refine_reading_text(v)
+            self._role_in_reading.append(RoleOccurrence(role_seq[idx], pre_seq[idx], post))
+            self._follows.append(inter)
+            pre_seq[idx + 1] = pre
+            idx += 1
+
+
+class Role(RelationshipFieldRef):
+    _sibling: Optional[Role] = None
+
+    def __init__(self, parent:Any, part_of, pos):
+        super().__init__(parent, part_of, pos)
+
+    def _guid(self):
+        return generate_stable_uuid(f"{self._field_ix}_{self._part_of()._guid()}")
+
+    def player(self) -> qb.Concept:
+        return self._concept
+
+    def sibling(self):
+        if self._relationship._arity() == 2 and not self._sibling:
+            first_role = self._relationship[0]
+            sibling = self._relationship[1] if self._id == first_role._id else first_role
+            self._sibling = sibling
+        return self._sibling
+    
+    def siblings(self):
+        return [self._relationship[i] for i in range(self._relationship._arity()) if i != self._field_ix]
+
+    def _part_of(self):
+        return self._relationship
+
+    @staticmethod
+    def _from_field(field:RelationshipFieldRef):
+        return Role(field._parent, field._relationship, field._field_ix)
+
+    def __hash__(self):
+        return hash(f"Role({self._guid()})")
+
+    def __eq__(self, other):
+        if not isinstance(other, Role):
+            return False
+        return self._guid() == other._guid() and self._part_of() == other._part_of()
+
+# A RoleOccurrence objectifies the occurrence of a Role in some RelationshipReading
+# to account for any pre- and/or post-bound text around the Role occurrence in
+# that reading. For instance, in the RelationshipReading with this reading pattern:
+#
+#     "{Person} has personal- {Vehicle}"
+#
+# the RoleOccurrences for the roles verbalize as
+#
+#     "Person" and
+#     "personal Vehicle"
+#
+class RoleOccurrence:
+
+    def __init__(self, role: Role, pre: Optional[str], post: Optional[str]):
+        self._prefix: Optional[str] = pre
+        self._postfix: Optional[str] = post
+        self._role: Role = role
+        self._verbalizes_as: Optional[str] = None
+
+    def __str__(self):
+        if self._verbalizes_as is None:
+            verb_seq = []
+            if self._prefix is not None:
+                verb_seq.append(self._prefix)
+            verb_seq.append(str(self._role.player()))
+            if self._postfix is not None:
+                verb_seq.append(self._postfix)
+            self._verbalizes_as = " ".join(verb_seq)
+        return self._verbalizes_as

relationalai/early_access/dsl/orm/types.py

@@ -0,0 +1,42 @@
+from typing import Any, Union
+
+import relationalai.semantics as qb
+from relationalai.semantics.internal.internal import python_types_to_concepts
+from relationalai.early_access.dsl.core.utils import generate_stable_uuid
+from relationalai.early_access.dsl.orm.relationships import Relationship
+
+
+class Concept(qb.Concept):
+
+    def __init__(self, model, name: str, extends: list[Any] = [], identify_by:dict[str, Any]={}):
+        self._dsl_model = model
+        # create an orm Relationship for each Concept to be able to refer to them in DSL model
+        identify_args = {}
+        if identify_by:
+            for k, v in identify_by.items():
+                if python_types_to_concepts.get(v):
+                    v = python_types_to_concepts[v]
+                if isinstance(v, qb.Concept):
+                    identify_args[k] = Relationship(self._dsl_model, f"{{{name}}} has {{{k}:{v._name}}}", short_name=k)
+                elif isinstance(v, type) and issubclass(v, self._dsl_model.Enum): #type: ignore
+                    identify_args[k] = Relationship(self._dsl_model, f"{{{name}}} has {{{k}:{v._concept._name}}}", short_name=k)
+                elif isinstance(v, qb.Relationship):
+                    identify_args[k] = v
+                else:
+                    raise ValueError(f"identify_by must be either a Concept or Relationship: {k}={v}")
+        super().__init__(name, extends, model.qb_model(), identify_args)
+        self._dsl_model._add_concept(self)
+        self._dsl_model.reasoner().new_concept(self)
+        if identify_by:
+            # once concept is added, add constraints required for reference schema
+            self._dsl_model._ref_scheme_constraints(*identify_args.values())
+
+    def identify_by(self, *relations:Union[qb.Relationship, qb.RelationshipReading]):
+        super().identify_by(*relations)
+        self._dsl_model._ref_scheme_constraints(*relations)
+
+    def __repr__(self):
+        return f"Concept({self._name})"
+
+    def _guid(self):
+        return generate_stable_uuid(f"{self._id}")

relationalai/early_access/dsl/orm/utils.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import keyword
+from relationalai.early_access.dsl.core.utils import camel_to_snake, to_rai_way_string
+import relationalai.early_access.dsl.orm.relationships as orm_qb
+
+
+# This method generates a string containing a standard abbreviated name for the given reading, generated according
+# to the rai way conventions.
+def generate_rai_way_name(reading: orm_qb.RelationshipReading):
+    # These two dict and the roles array are indexed in same way, using the role position in the madlib
+    roles = reading._roles()
+
+    # A role name must be different from player and player_i (used for multiple occurrences of the same player)
+    def get_role_name(idx: int):
+        player = roles[idx].player()._name.lower()
+        role_name = reading._fields[idx].name
+        if role_name != player and ("_" not in role_name or not role_name.split("_")[1].isdigit()):
+            return role_name
+        return ""
+
+    # We invoke this method with an index to compose together the textual parts of a single role (prefix, role/player
+    # name, postfix and following text.
+    def compose_role_textual_parts(idx: int, drop_is_has=True, drop_role_name=False):
+        textual_parts = []
+        role = roles[idx]
+        role_occurrence = reading._role_in_reading[idx]
+        role_name = get_role_name(idx)
+        if role_occurrence._prefix and (not role_name or drop_role_name):
+            textual_parts.append(camel_to_snake(role_occurrence._prefix))
+        if idx > 0:
+            textual_parts.append(camel_to_snake(role_name) if role_name and not drop_role_name
+                                 else camel_to_snake(role.player()._name))
+        if role_occurrence._postfix and (not role_name or drop_role_name):
+            textual_parts.append(camel_to_snake(role_occurrence._postfix))
+        follows = reading._follows[idx]
+        if follows:
+            rai_way_string = to_rai_way_string(follows, drop_is_has)
+            if rai_way_string:
+                textual_parts.append(rai_way_string)
+        return '_'.join(textual_parts).replace(" ", "_")
+
+    # Generate the rai way name for the binary case, when most of the role data in not present.
+    def generate_simple_binary_name():
+        follows = reading._follows[0]
+        if follows:
+            simple_name = to_rai_way_string(follows)
+            if (simple_name and not reading._follows[1] and not keyword.iskeyword(simple_name) and
+                not reading._role_in_reading[0]._prefix and not reading._role_in_reading[0]._postfix and
+                not reading._role_in_reading[1]._prefix and not reading._role_in_reading[1]._postfix):
+                return simple_name
+        return None
+
+    # Unary case
+    if len(roles) == 1:
+        return compose_role_textual_parts(0)
+    # Binary case
+    elif len(roles) == 2:
+        # If there exists a role name for the second player, use it as rai way name
+        if get_role_name(1):
+            return camel_to_snake(get_role_name(1))
+        else:
+            simple_binary_name = generate_simple_binary_name()
+            if simple_binary_name:
+                return simple_binary_name
+            # General case: process all the components of both roles
+            else:
+                first_role_component = compose_role_textual_parts(0)
+                second_role_component = compose_role_textual_parts(1, False)
+                rel_name = f"{first_role_component}_{second_role_component}" if first_role_component != "" else second_role_component
+                return rel_name
+    # Ternary case and beyond
+    else:
+        all_roles_components = []
+        for i, role in enumerate(roles):
+            role_component = compose_role_textual_parts(i,False, True)
+            all_roles_components.append(role_component)
+        rel_name = "_".join(all_roles_components)
+        return rel_name

relationalai/early_access/dsl/orm/verb.py

@@ -0,0 +1,204 @@
+from typing import List
+from relationalai.early_access.dsl.orm.models import Model, Relationship, Role
+from relationalai.early_access.dsl.orm.reasoners import Multiplicity
+
+# Decapitalizes (lowers first character of) a string
+def decapitalize(text: str) -> str: return text[:1].lower() + text[1:]
+
+class Verbalizer:
+    def __init__(self, model: Model):
+        self._model = model
+
+        # We cache incrementally maintainable RelationshipVerbaliers to prevent
+        # unnecessary recalculation while users are actively editing a model.
+        self._rel_verbs = {}
+
+    def verbalize(self, rel: Relationship) -> str:
+        if rel._id not in self._rel_verbs:
+            self._rel_verbs[rel._id] = RelationshipVerbalizer(rel, self._model)
+        return str(self._rel_verbs[rel._id])
+
+
+# PointMultiplicityVerbalizers are used to verbalize constraints on the
+# Roles of some Relationship using some specific RelationshipReading of
+# that Relationship. We verbalize these constraints in the language of
+# point multiplicities of a given Role
+#
+class PointMultiplicityVerbalizer:
+
+    def __init__(self, reading, model: Model):
+        self._model = model
+        self._reading = reading
+
+    # Use this reading to verbalize the multiplicity of *role* in a context
+    # in which players for all of the other roles have been fixed.
+    #
+    def multiplicity_of(self, role: Role) -> str:
+        arity = role._part_of()._arity()
+        if arity == 1:
+            return self._multiplicity_of_unary(role)
+        if arity == 2:
+            return self._multiplicity_of_binary(role)
+        else:
+            return self._multiplicity_of_nary(role)
+
+    def sample_fact(self): return self._reading._sample_fact()
+
+    # Binary relationships admit much more readable multiplicity verbalizations
+    # than the more general n-ary relationships; so we handle them separately.
+    #
+    def _multiplicity_of_binary(self, role: Role):
+        reading = self._reading
+
+        role1_text = str(reading._role_in_reading[0])
+        pos1_text = str(role1_text) if reading._follows[0] is None else str(role1_text) + " " + reading._follows[0]
+        role2_text = str(reading._role_in_reading[1])
+        pos2_text = role2_text if reading._follows[1] is None else str(role2_text) + " " + reading._follows[1]
+
+        reasoner = self._model.reasoner()
+        mult = reasoner.point_multiplicity(role)
+        mult_verb = mult.qualifier()
+        leads = reading._leading_text
+
+        if role._id == reading._last()._id:
+            # When the role with multiplicity is the second in this reading,
+            # the reading is natural
+            if mult.many():
+                if leads is None:
+                    return f"It is possible that some {pos1_text} {mult_verb} {pos2_text}"
+                else:
+                    return f"It is possible that {decapitalize(leads)} some {pos1_text} {mult_verb} {pos2_text}"
+            else:
+                if leads is None:
+                    return f"Each {pos1_text} {mult_verb} {pos2_text}"
+                else:
+                    return f"{leads.capitalize()} each {pos1_text} {mult_verb} {pos2_text}"
+
+
+        else:
+            # The role with multiplicity is the first in this reading
+            if mult.many():
+                if leads is None:
+                    return f"It is possible that for some {role2_text}, {mult_verb} {pos1_text} that {pos2_text}"
+                else:
+                    return f"It is possible that for some {role2_text}, {decapitalize(leads)} {mult_verb} {pos1_text} that {pos2_text}"
+            else:
+                if leads is None:
+                    return f"For each {role2_text}, {mult_verb} {pos1_text} that {pos2_text}"
+                else:
+                    return f"For each {role2_text}, {decapitalize(leads)} {mult_verb} {pos1_text} that {pos2_text}"
+
+    def _multiplicity_of_unary(self, role: Role) -> str:
+        reading = self._reading
+        point_variable = str(role.player())
+        mult_verb = []
+        if reading._leading_text is not None:
+            mult_verb.append(decapitalize(reading._leading_text))
+        mult_verb.append("that " + str(reading._role_in_reading[0]))
+        follows = reading._follows[0]
+        if follows is not None:
+            mult_verb.append(reading._follows[0])
+
+        return f"It is possible that for some {point_variable}, " + " ".join(mult_verb)
+
+    def _multiplicity_of_nary(self, role: Role) -> str:
+
+        def point_var_seq(pvars: List[str]) -> str:
+            if len(pvars) == 1:
+                return pvars[0]
+            else:
+                length = len(pvars) - 1
+                return ", ".join(pvars[0:length]) + " and " + pvars[length]
+
+        reading = self._reading
+
+        point_variables = []
+        mult_verb = []
+        if reading._leading_text is not None:
+            mult_verb.append(decapitalize(reading._leading_text))
+        idx = 0
+        role_verb = None
+        for r in reading._roles():
+            if role._id == r._id:
+                qualifier = Multiplicity.qualifier(self._model.reasoner().point_multiplicity(role))
+                role_verb = qualifier + " " + str(reading._role_in_reading[idx])
+            else:
+                role_verb = "that " + str(reading._role_in_reading[idx])
+                point_variables.append(str(r.player()))
+            follows = reading._follows[idx]
+            if follows is None:
+                mult_verb.append(role_verb)
+            else:
+                mult_verb.append(role_verb + " " + follows)
+            idx += 1
+    
+        return "It is possible that for some " + point_var_seq(point_variables) + ", " + " ".join(mult_verb)
+
+
+# RelationshipVerbalizers verbalize information about a Relationship in
+# natural language, including a sample fact and a verbalization of its
+# constraints in the form of a point multiplicity verbalization of each
+# of its roles.
+# 
+# Generating good point multiplicity verbalizations is tricky because:
+#   - the most natural way for a human to understand a point multiplicity
+#     is when it is verbalized on the last role of some RelationshipReading,
+#     but the model may not contain a reading in which a given role appears
+#     last.
+#   - mandatory and uniqueness constraints on the all of the Roles of the
+#     Relationship can influence the point multiplicity of any given Role.
+#  
+class RelationshipVerbalizer:
+
+    def __init__(self, relationship: Relationship, model: Model):
+        self._relationship = relationship
+        self._model = model
+
+        # Number of readings of this relationship
+        self._number_of_readings = 0   # Forces a sync with the model on first use
+
+        # Maps the last role of a RelationshipReading to the PointMultiplicityVerbalizer
+        #   for that reading. Used to simplify the choice of readings to use when
+        #   verbalizing the point multiplicity of a Role, as the best ones are when
+        #   the role appears last.
+        self._role_to_verb = {}
+
+        # Default verbalizer to use when verbalizing a point multiplicity of this
+        #   Relationship when there is no better choice. Also used to verbalize
+        #   sample facts of this Relationship because it is specific to a Reading.
+        self._default_verb = None
+
+    def __str__(self):
+        default_reading = self.verbalizer_for()
+        verb = [default_reading.sample_fact()]
+        for role in self._relationship._rel_roles.values():
+            reading_verb = self.verbalizer_for(role)
+            verb.append(reading_verb.multiplicity_of(role))
+        return "\n".join(verb)
+
+    # Returns a verbalizer that is good for verbalizing the point multiplicity
+    # of a given role of this Relationship. If no role is provided, returns
+    # a default verbalizer.
+    def verbalizer_for(self, role=None) -> PointMultiplicityVerbalizer:
+        num_readings = len(self._relationship._readings)
+        if self._number_of_readings < num_readings:
+            # Then update the reading verbalizations to include those of any
+            # newly added RelationshipReadings.
+            #
+            self._number_of_readings = num_readings
+            self._role_to_verb = {}
+
+            for reading in self._relationship._readings:
+                reading_verb = PointMultiplicityVerbalizer(reading, self._model)
+                self._role_to_verb[reading._last()._id] = reading_verb
+                if self._default_verb is None:
+                    self._default_verb = reading_verb
+
+        if self._default_verb is None:
+            raise Exception(f"Could not find a default reading for Relationship {self._relationship}")
+
+        if role is not None and role._id in self._role_to_verb:
+            return self._role_to_verb[role._id]
+        
+        # Otherwise choose an arbitary reading verbalization
+        return self._default_verb