RD-2427 related terms endpoint (#84)

* RD-2427 related terms endpoint

* RD-2427 missing newline

* RD-2427 related_terms -> similar_terms, add semantic_vectors

* RD-2427 similar terms unit test, checkstyle

Author: iredpath

examples/text_embedding.py examples/semantic_vectors.pyexamples/text_embedding.py renamed to examples/semantic_vectors.py

@@ -15,11 +15,19 @@ 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)
+
+    # Set selected API options.
+    # For more information on the functionality of these
+    # and other available options, see Rosette Features & Functions
+    # https://developer.rosette.com/features-and-functions#semantic-vectors
+
+    # api.set_option('perToken', 'true')
+
     embeddings_data = "Cambridge, Massachusetts"
     params = DocumentParameters()
     params["content"] = embeddings_data
     try:
-        return api.text_embedding(params)
+        return api.semantic_vectors(params)
     except RosetteException as exception:
         print(exception)
 

examples/similar_terms.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""
+Example code to call Rosette API to get similar terms for an input.
+"""
+from __future__ import print_function
+
+import argparse
+import json
+import os
+
+from rosette.api import API, DocumentParameters, 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)
+
+    # Set selected API options.
+    # For more information on the functionality of these
+    # and other available options, see Rosette Features & Functions
+    # https://developer.rosette.com/features-and-functions#similar-terms
+
+    api.set_option("resultLanguages", ['spa', 'deu', 'jpn'])
+
+    term = "spy"
+    params = DocumentParameters()
+    params["content"] = term
+    try:
+        return api.similar_terms(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(ARGS.key, ARGS.url)
+    print(json.dumps(RESULT, indent=2, ensure_ascii=False,
+                     sort_keys=True).encode("utf8"))

rosette/api.py

@@ -560,10 +560,12 @@ def __init__(
             'NAME_DEDUPLICATION': 'name-deduplication',
             'PING': 'ping',
             'RELATIONSHIPS': 'relationships',
+            'SEMANTIC_VECTORS': 'semantics/vector',
             'SENTENCES': 'sentences',
             'SENTIMENT': 'sentiment',
+            'SIMILAR_TERMS': 'semantics/similar',
             'SYNTAX_DEPENDENCIES': 'syntax/dependencies',
-            'TEXT_EMBEDDING': 'text-embedding',
+            'TEXT_EMBEDDING': 'semantics/vector',
             'TOKENS': 'tokens',
             'TOPICS': 'topics',
             'TRANSLITERATION': 'transliteration'
@@ -932,6 +934,14 @@ def text_embedding(self, parameters):
         @return: A python dictionary containing the results of text embedding."""
         return EndpointCaller(self, self.endpoints['TEXT_EMBEDDING']).call(parameters)
 
+    def semantic_vectors(self, parameters):
+        """
+        Create an L{EndpointCaller}  to identify text vectors found in the texts
+        to which it is applied and call it.
+        @type parameters: L{DocumentParameters} or L{str}
+        @return: A python dictionary containing the results of semantic vectors."""
+        return EndpointCaller(self, self.endpoints['SEMANTIC_VECTORS']).call(parameters)
+
     def syntax_dependencies(self, parameters):
         """
         Create an L{EndpointCaller} to identify the syntactic dependencies in the texts
@@ -954,3 +964,12 @@ def topics(self, parameters):
         @type parameters: DocumentParameters
         @return; A python dictionary containing the results"""
         return EndpointCaller(self, self.endpoints['TOPICS']).call(parameters)
+
+    def similar_terms(self, parameters):
+        """
+        Create an L{EndpointCaller} to identify terms most similar to the input in
+        the requested languages
+        :param parameters: DocumentParameters
+        :return: A python dictionary containing the similar terms and their similarity
+        """
+        return EndpointCaller(self, self.endpoints['SIMILAR_TERMS']).call(parameters)

tests/test_rosette_api.py

@@ -649,13 +649,13 @@ def test_for_name_translation_required_parameters(api, json_response):
     httpretty.reset()
 
 
-def test_the_text_embedded_endpoint(api, json_response, doc_params):
-    """Test text embedded endpoint"""
+def test_the_semantic_vectors_endpoint(api, json_response, doc_params):
+    """Test semantic vectors endpoint"""
     httpretty.enable()
-    httpretty.register_uri(httpretty.POST, "https://api.rosette.com/rest/v1/text-embedding",
+    httpretty.register_uri(httpretty.POST, "https://api.rosette.com/rest/v1/semantics/vector",
                            body=json_response, status=200, content_type="application/json")
 
-    result = api.text_embedding(doc_params)
+    result = api.semantic_vectors(doc_params)
     assert result["name"] == "Rosette API"
     httpretty.disable()
     httpretty.reset()
@@ -705,3 +705,18 @@ def test_the_topics_endpoint(api, json_response, doc_params):
     assert result["name"] == "Rosette API"
     httpretty.disable()
     httpretty.reset()
+
+
+# Test the similar-terms endpoint
+
+def test_the_similar_terms_endpoint(api, json_response, doc_params):
+    """Test the similar terms endpoint"""
+    httpretty.enable()
+    httpretty.register_uri(httpretty.POST, "https://api.rosette.com/rest/v1/semantics/similar",
+                           body=json_response, status=200, content_type="application/json")
+
+    api.set_option("resultLanguages", ["spa", "jpn", "deu"])
+    result = api.similar_terms(doc_params)
+    assert result["name"] == "Rosette API"
+    httpretty.disable()
+    httpretty.reset()