Refactor the model to make it usable without the server

Currently, we can only effectively use the `SemanticMatch` and
`EquivalenceTable` classes with the server. This creates a new
and improved `SemanticMatchDictStore`, which implements the
algorithm to search for matches. We then refactor the service
to use this new class.

Furthermore, we clean up the service to use it in a more pythonic
way, eliminating the need for the `service_model` module.

Author: s-heppner

semantic_matcher/model.py

@@ -1,4 +1,6 @@
-from typing import Dict, List
+import json
+import copy
+from typing import Dict, List, Set, Optional, Iterable
 
 from pydantic import BaseModel
 
@@ -8,13 +10,159 @@ class SemanticMatch(BaseModel):
     A semantic match, mapping two semanticIDs with a matching score. Can be imagined as a weighted graph with
     `base_semantic_id` ---`score`---> `match_semantic_id`
 
-    Todo: Think about static and TTL, but that is optimization
-    Todo: Maybe we want to have the matching method as debug information
+    :cvar base_semantic_id:
+    :cvar match_semantic_id:
+    :cvar score: The semantic similarity score, a float between 0 and 1
+    :cvar path: Optionally, if the `SemanticMatch` did not come from a source but is inferred by another `SemanticMatch`
+        the `path` stores the SemanticMatches it came from
+    :cvar meta_information: Optional meta_information, such as the source of the `SemanticMatch`
     """
     base_semantic_id: str
     match_semantic_id: str
     score: float
-    meta_information: Dict
+    path: Optional[List["SemanticMatch"]] = None
+    meta_information: Optional[Dict] = None
+
+    def __hash__(self):
+        return hash((
+            self.base_semantic_id,
+            self.match_semantic_id,
+            self.score,
+            self.path,
+            frozenset(self.meta_information.items())
+        ))
+
+    @classmethod
+    def combine_semantic_matches(cls, first: "SemanticMatch", second: "SemanticMatch") -> "SemanticMatch":
+        """
+        Construct a new `SemanticMatch` by combining two `SemanticMatch`es.
+
+        Given the following situation:
+            A --0.4--> B
+            B --0.5--> C
+        this constructs a new `SemanticMatch`:
+            A --(0.4*0.5)--> C
+        while updating the `path` information of the new `SemanticMatch`
+
+        :param first: First `SemanticMatch`
+        :param second: Second `SemanticMatch`. Note that `second.base_semantic_id` needs to be the same
+            as `first.match_semantic_id`
+        :return: The combined `SemanticMatch`
+        """
+        if not first.match_semantic_id == second.base_semantic_id:
+            raise KeyError(f"Cannot combine. `first.match_semantic_id` ({first.match_semantic_id}) does not "
+                           f"fit `second.base_semantic_id` ({second.base_semantic_id}).")
+        if second.path:
+            new_path = copy.copy(second.path)
+            new_path.insert(0, second)
+        else:
+            new_path = [second]
+        return SemanticMatch(
+            base_semantic_id=first.base_semantic_id,
+            match_semantic_id=second.match_semantic_id,
+            score=first.score*second.score,
+            path=new_path,
+        )
+
+class SemanticMatchDictStore:
+    """
+    A collection of `SemanticMatch`es, stored in a Dict, where the Key is the `base_semantic_id` and the Value is
+    the `SemanticMatch` object. This allows for efficient resolution of the `SemanticMatches` of the `base_semantic_id`.
+    """
+    def __init__(self, matches: Iterable[SemanticMatch]):
+        self._store: Dict[str, Set[SemanticMatch]] = {}
+        for x in matches:
+            self.add(x)
+
+    def add(self, match: SemanticMatch) -> None:
+        """
+        Add a `SemanticMatch` to the store
+        """
+        if match.base_semantic_id in self._store:
+            self._store[match.base_semantic_id].add(match)
+        else:
+            self._store[match.base_semantic_id] = {match}
+
+    def discard(self, match: SemanticMatch) -> None:
+        """
+        Discard a `SemanticMatch` from the store
+        """
+        # First we remove the `SemanticMatch` from the set of matches for that `base_semantic_id`
+        self._store[match.base_semantic_id].discard(match)
+        # Then, if there is no more `SemanticMatch`es for that `base_semantic_id`, we remove the Dict entry completely
+        if not len(self._store[match.base_semantic_id]):
+            self._store.pop(match.base_semantic_id)
+
+    def get_all_matches(self) -> Set[SemanticMatch]:
+        """
+        Return a set of all `SemanticMatch`es currently inside the store
+        """
+        all_matches: Set[SemanticMatch] = set()
+        for i in self._store.values():
+            all_matches.update(i)
+        return all_matches
+
+    def get_matches(self, semantic_id: str, min_score: Optional[float] = None) -> Set[SemanticMatch]:
+        """
+        Return all 'SemanticMatches' of a given semantic_id currently inside a store that have a higher or equal
+        score than the `min_score`.
+        This is a recursive function, that also queries the matches of the matches, as long as the multiplicative
+        scores of the matches is still higher or equal to the `min_score`.
+        """
+        matches: Set[SemanticMatch] = set()  # This is our return Set
+
+        # First, we check on the current level
+        current_matches_with_any_score = self._store.get(semantic_id, set())
+        current_matches = {
+            match for match in current_matches_with_any_score if min_score is None or match.score >= min_score
+        }
+        # We can already update our return Set, since we know that the `current_matches` will definitely be inside
+        matches.update(current_matches)
+
+        # Now we do the same query each of the current_matches that have a score larger or equal to min_score
+        # Todo: We currently have a loop in here that we need to break
+        for match in current_matches:
+            # We calculate the new minimal score
+            # Unified score is multiplied: score(A->B) * score(B->C)
+            # This score should be larger or equal than the requested min_score:
+            # score(A->B) * score(B->C) >= min_score
+            # score(A->B) is well known, as it is the `match.score`
+            # => score(B->C) >= (min_score/score(A->B))
+            if min_score:
+                new_min_score = min_score/match.score
+            else:
+                new_min_score = min_score
+            # Here's the recursive function call, we do the same thing again with the new matches and the
+            # updated `min_score`:
+            new_matches = self.get_matches(semantic_id=match.base_semantic_id, min_score=new_min_score)
+            # These new matches are now not relative to the original `base_semantic_id`, so we need to create new
+            # `SemanticMatch`es and somehow store the path.
+            for new_match in new_matches:
+                matches.add(SemanticMatch.combine_semantic_matches(
+                    first=match,
+                    second=new_match
+                ))
+
+        # In the end, we return our return Set
+        return matches
+
+    def to_file(self, filename: str) -> None:
+        matches: List[Dict] = [match.model_dump() for match in self.get_all_matches()]
+        with open(filename, "w") as file:
+            json.dump(matches, file, indent=4)
+
+    @classmethod
+    def from_file(cls, filename: str) -> "SemanticMatchDictStore":
+        with open(filename, "r") as file:
+            matches_data = json.load(file)
+        matches = [SemanticMatch(**match_dict) for match_dict in matches_data]
+        return cls(matches)
+
+    def __len__(self) -> int:
+        length = 0
+        for i in self._store.values():
+            length += len(i)
+        return length
 
 
 class EquivalenceTable(BaseModel):

semantic_matcher/service.py

@@ -1,9 +1,26 @@
-from typing import List
+from typing import Optional, List
 
+from pydantic import BaseModel
 import requests
 from fastapi import APIRouter
 
-from semantic_matcher import model, service_model
+from semantic_matcher import model
+
+
+class MatchRequest(BaseModel):
+    """
+    Request body for the :func:`service.SemanticMatchingService.get_match`
+
+    :ivar semantic_id: The semantic ID that we want to find matches for
+    :ivar local_only: If `True`, only check at the local service and do not request other services
+    :ivar name: Optional name of the resolved semantic ID for NLP matching
+    :ivar definition: Optional definition of the resolved semantic ID for NLP matching
+    """
+    semantic_id: str
+    score_limit: float
+    local_only: bool = True
+    name: Optional[str] = None
+    definition: Optional[str] = None
 
 
 class SemanticMatchingService:
@@ -27,7 +44,7 @@ class SemanticMatchingService:
     def __init__(
             self,
             endpoint: str,
-            equivalences: model.EquivalenceTable
+            matches: model.SemanticMatchDictStore
     ):
         """
         Initializer of :class:`~.SemanticMatchingService`
@@ -46,48 +63,42 @@ def __init__(
         self.router.add_api_route(
             "/get_matches",
             self.get_matches,
+            response_model=List[model.SemanticMatch],
             methods=["GET"]
         )
         self.router.add_api_route(
             "/post_matches",
             self.post_matches,
             methods=["POST"]
         )
-        self.router.add_api_route(
-            "/clear",
-            self.remove_all_matches,
-            methods=["POST"]
-        )
         self.endpoint: str = endpoint
-        self.equivalence_table: model.EquivalenceTable = equivalences
+        self.matches: model.SemanticMatchDictStore = matches
 
     def get_all_matches(self):
         """
         Returns all matches stored in the equivalence table-
         """
-        matches = self.equivalence_table.get_all_matches()
+        matches = self.matches.get_all_matches()
         return matches
 
-    def remove_all_matches(self):
-        self.equivalence_table.remove_all_semantic_matches()
 
     def get_matches(
             self,
-            request_body: service_model.MatchRequest
-    ) -> service_model.MatchesList:
+            request_body: MatchRequest
+    ) -> List[model.SemanticMatch]:
         """
         A query to match two SubmodelElements semantically.
 
         Returns a matching score
         """
         # Try first local matching
-        matches: List[model.SemanticMatch] = self.equivalence_table.get_local_matches(
+        matches: List[model.SemanticMatch] = list(self.matches.get_matches(
             semantic_id=request_body.semantic_id,
-            score_limit=request_body.score_limit
-        )
+            min_score=request_body.score_limit
+        ))
         # If the request asks us to only locally look, we're done already
         if request_body.local_only:
-            return service_model.MatchesList(matches=matches)
+            return matches
         # Now look for remote matches:
         additional_remote_matches: List[model.SemanticMatch] = []
         for match in matches:
@@ -97,7 +108,7 @@ def get_matches(
             remote_matching_service = self._get_matcher_from_semantic_id(match.match_semantic_id)
             if remote_matching_service is None:
                 continue
-            remote_matching_request = service_model.MatchRequest(
+            remote_matching_request = MatchRequest(
                 semantic_id=match.match_semantic_id,
                 # This is a simple "Ungleichung"
                 # Unified score is multiplied: score(A->B) * score(B->C)
@@ -112,20 +123,20 @@ def get_matches(
                 definition=request_body.definition
             )
             url = f"{remote_matching_service}/get_matches"
+            # Todo: Break recursion loop here
             new_matches_response = requests.get(url, json=remote_matching_request.model_dump_json())
-            match_response = service_model.MatchesList.model_validate_json(new_matches_response.text)
-            additional_remote_matches.extend(match_response.matches)
+            response_matches = [model.SemanticMatch(**match) for match in new_matches_response.json()]
+            additional_remote_matches.extend(response_matches)
         # Finally, put all matches together and return
         matches.extend(additional_remote_matches)
-        res = service_model.MatchesList(matches=matches)
-        return res
+        return matches
 
     def post_matches(
             self,
-            request_body: service_model.MatchesList
+            request_body: List[model.SemanticMatch]
     ) -> None:
-        for match in request_body.matches:
-            self.equivalence_table.add_semantic_match(match)
+        for match in request_body:
+            self.matches.add(match)
         # Todo: Figure out how to properly return 200
 
     def _get_matcher_from_semantic_id(self, semantic_id: str) -> str: