WS-3151: add record similarity top level object and example

Author: Adam Soos

examples/record_similarity.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""
+Example code to call Rosette API to get similarity score between a list of records
+"""
+
+import argparse
+import json
+import os
+
+from rosette.api import API, RecordSimilarityParameters, RosetteException
+
+
+def run(key, alt_url='https://api.rosette.com/rest/v1/'):
+    """ Run the example """
+    # Create an API instance
+    api = API(user_key=key, service_url=alt_url)
+
+    fields = {
+        "primaryName": {
+            "type": "rni_name",
+            "weight": 0.5
+        },
+        "dob": {
+            "type": "rni_date",
+            "weight": 0.2
+        },
+        "addr": {
+            "type": "rni_address",
+            "weight": 0.5
+        },
+        "dob2": {
+            "type": "rni_date",
+            "weight": 0.1
+        }
+    }
+    properties = {
+        "threshold": 0.1,
+        "includeExplainInfo": False
+    }
+    records = {
+        "left": [
+            {
+                "primaryName": {
+                    "text": "Ethan R",
+                    "entityType": "PERSON",
+                    "language": "eng",
+                    "languageOfOrigin": "eng",
+                    "script": "Latn"
+                },
+                "dob": "1993-04-16",
+                "addr": "123 Roadlane Ave",
+                "dob2": {
+                    "date": "1993/04/16"
+                }
+            },
+            {
+                "dob": {
+                    "date": "1993-04-16"
+                },
+                "primaryName": {
+                    "text": "Evan R"
+                }
+            }
+        ],
+        "right": [
+            {
+                "dob": {
+                    "date": "1993-04-16"
+                },
+                "primaryName": {
+                    "text": "Seth R",
+                    "language": "eng"
+                }
+            },
+            {
+                "primaryName": "Ivan R",
+                "dob": {
+                    "date": "1993-04-16"
+                },
+                "addr": {
+                  "address": "123 Roadlane Ave"
+                },
+                "dob2": {
+                    "date": "1993/04/16"
+                }
+            }
+        ]
+    }
+    params = RecordSimilarityParameters()
+    params["fields"] = fields
+    params["properties"] = properties
+    params["records"] = records
+
+    #params["parameters"] = {"conflictScore": "0.9", "deletionScore": "0.2"}
+
+    try:
+        return api.record_similarity(params)
+    except RosetteException as exception:
+        print(exception)
+
+
+PARSER = argparse.ArgumentParser(formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                 description='Calls the ' +
+                                 os.path.splitext(os.path.basename(__file__))[0] + ' endpoint')
+PARSER.add_argument('-k', '--key', help='Rosette API Key', required=True)
+PARSER.add_argument('-u', '--url', help="Alternative API URL",
+                    default='https://api.rosette.com/rest/v1/')
+
+if __name__ == '__main__':
+    # ARGS = PARSER.parse_args()
+    RESULT = run("key", "http://localhost:8181/rest/v1/")
+    print(RESULT)

rosette/api.py

@@ -344,6 +344,27 @@ def validate(self):
                 "Required Name De-Duplication parameter is missing: names",
                 repr("names"))
 
+class RecordSimilarityParameters(_RequestParametersBase):
+    """Parameter object for C{record-similarity} endpoint.
+    Required:
+    C{records} A list of C{record} objects
+    C{properties} A C{property} object
+    C{fields} A dictionary of C{field} objects
+    """
+
+    def __init__(self):
+        self.use_multipart = False
+        _RequestParametersBase.__init__(self, ("fields", "properties", "records"))
+
+    def validate(self):
+        """Internal. Do not use."""
+        for option in "fields", "properties", "records":  # required
+            if self[option] is None:
+                raise RosetteException(
+                    "missingParameter",
+                    "Required Name Similarity parameter is missing: " + option,
+                    repr(option))
+
 
 class EndpointCaller(object):
     """L{EndpointCaller} objects are invoked via their instance methods to obtain results
@@ -592,7 +613,8 @@ def __init__(
             'TOKENS': 'tokens',
             'TOPICS': 'topics',
             'TRANSLITERATION': 'transliteration',
-            'EVENTS': 'events'
+            'EVENTS': 'events',
+            'RECORD_SIMILARITY': 'record-similarity'
         }
 
     def __del__(self):
@@ -966,6 +988,15 @@ def name_deduplication(self, parameters):
         @return: A python dictionary containing the results of de-duplication"""
         return EndpointCaller(self, self.endpoints['NAME_DEDUPLICATION']).call(parameters, NameDeduplicationParameters)
 
+    def record_similarity(self, parameters):
+        """
+        Create an L{EndpointCaller} to get similarity core between a list of records and call it.
+        @param parameters: An object specifying the data,
+        and possible metadata, to be processed by the record matcher.
+        @type parameters: L{RecordSimilarityParameters}
+        @return: A python dictionary containing the results of record matching."""
+        return EndpointCaller(self, self.endpoints['RECORD_SIMILARITY']).call(parameters, RecordSimilarityParameters)
+
     def text_embedding(self, parameters):
         """ deprecated
         Create an L{EndpointCaller}  to identify text vectors found in the texts