ADD: intersections API

indicoio/utils/multi.py

@@ -11,19 +11,59 @@ AVAILABLE_APIS = {
     'image': IMAGE_APIS
 }
 
+def invert_dictionary(d):
+    return {
+        element: key for key, values in d.iteritems()
+        for element in values
+    }
+
+API_TYPES = invert_dictionary(AVAILABLE_APIS)
+
+
+def intersections(data, apis = None, **kwargs):
+    """
+    Helper to make multi requests of different types.
+
+    :param data: Data to be sent in API request
+    :param type: String type of API request
+    :rtype: Dictionary of api responses
+    """
+    # Client side api name checking
+
+    # remove auto-inserted batch param
+    kwargs.pop('batch', None)
+
+    if not isinstance(apis, list) or len(apis) != 2:
+        raise IndicoError("Argument 'apis' must be of length 2")
+    if isinstance(data, list) and len(data) < 3:
+        raise IndicoError(
+            "At least 3 examples are required to use the intersections API"
+        )
+
+    api_types = map(API_TYPES.get, apis)
+    if api_types[0] != api_types[1]:
+        raise IndicoError(
+            "Both `apis` must accept the same kind of input to use the intersections API"
+        )
+
+    cloud = kwargs.get("cloud", None)
+
+    url_params = {
+        'batch': False,
+        'api_key': kwargs.pop('api_key', None),
+        'apis': apis
+    }
+
+    return api_handler(data, cloud=cloud, api="apis/intersections", url_params=url_params, **kwargs)
 
 def multi(data, datatype, apis, batch=False, **kwargs):
     """
     Helper to make multi requests of different types.
 
-    :param data: data to be sent in JSON.
-    :param type: String type of API request
+    :param data: Data to be sent in API request
+    :param datatype: String type of API request
     :param apis: List of apis to use.
-    :param apis: List of apis available for use.
-    :type data: str or image
-    :type type: str or unicode
-    :type apis: list of str
-    :type available: list of str
+    :param batch: Is this a batch request?
     :rtype: Dictionary of api responses
     """
     # Client side api name checking - strictly only accept func name api
@@ -36,13 +76,12 @@ def multi(data, datatype, apis, batch=False, **kwargs):
         )
 
     # Convert client api names to server names before sending request
-    apis = map(CLIENT_SERVER_MAP.get, apis)
     cloud = kwargs.pop("cloud", None)
     api_key = kwargs.pop('api_key', None)
     result = api_handler(
         data,
         cloud=cloud,
-        api='apis',
+        api='apis/multiapi',
         url_params={
             "apis":apis,
             "batch":batch,
@@ -55,11 +94,11 @@ def multi(data, datatype, apis, batch=False, **kwargs):
 
 def handle_response(result):
     # Parse out the results to a dicionary of api: result
-    return dict((SERVER_CLIENT_MAP[api], parsed_response(api, res))
+    return dict((api, parsed_response(api, res))
         for api, res in result.iteritems())
 
 
-def predict_text(input_text, apis=TEXT_APIS, **kwargs):
+def analyze_text(input_text, apis=TEXT_APIS, **kwargs):
     """
     Given input text, returns the results of specified text apis. Possible apis
     include: [ 'text_tags', 'political', 'sentiment', 'language' ]
@@ -70,8 +109,8 @@ def predict_text(input_text, apis=TEXT_APIS, **kwargs):
 
        >>> import indicoio
        >>> text = 'Monday: Delightful with mostly sunny skies. Highs in the low 70s.'
-       >>> results = indicoio.text(data = text, apis = ["language", "sentiment"])
-       >>> language_results = results["langauge"]
+       >>> results = indicoio.analyze_text(data = text, apis = ["language", "sentiment"])
+       >>> language_results = results["language"]
        >>> sentiment_results = results["sentiment"]
 
     :param text: The text to be analyzed.
@@ -96,7 +135,7 @@ def predict_text(input_text, apis=TEXT_APIS, **kwargs):
     )
 
 
-def predict_image(image, apis=IMAGE_APIS, **kwargs):
+def analyze_image(image, apis=IMAGE_APIS, **kwargs):
     """
     Given input image, returns the results of specified image apis. Possible apis
     include: ['fer', 'facial_features', 'image_features']
@@ -108,7 +147,7 @@ def predict_image(image, apis=IMAGE_APIS, **kwargs):
        >>> import indicoio
        >>> import numpy as np
        >>> face = np.zeros((48,48)).tolist()
-       >>> results = indicoio.image(image = face, apis = ["fer", "facial_features"])
+       >>> results = indicoio.analyze_image(image = face, apis = ["fer", "facial_features"])
        >>> fer = results["fer"]
        >>> facial_features = results["facial_features"]