rosette_api 1.27.1 → 1.37.0

data/lib/name_translation_parameters.rb

@@ -3,7 +3,7 @@
 require_relative 'rosette_api_error'
 
 # This class encapsulates parameters that are needed for name-translation in
-# Rosette API.
+# Analytics API.
 class NameTranslationParameters
   # Name's entity type (PERSON, LOCATION, ORGANIZATION) (optional)
   attr_accessor :entity_type
@@ -11,7 +11,7 @@ class NameTranslationParameters
   attr_accessor :genre
   # Name to translate
   attr_accessor :name
-  # Rosette API options (optional, should be a hash)
+  # API options (optional, should be a hash)
   attr_accessor :rosette_options
   # ISO 693-3 code of the name's native language the name originates in
   # (optional)
@@ -26,11 +26,14 @@ class NameTranslationParameters
   attr_accessor :target_scheme
   # ISO 15924 code of name's script (optional)
   attr_accessor :target_script
+  # Maximum number of results to return (optional)
+  attr_accessor :maximum_results
 
   def initialize(name, target_language, options = {}) # :notnew:
     options = {
       entity_type: nil,
       genre: nil,
+      maximum_results: nil,
       rosette_options: nil,
       source_language_of_origin: nil,
       source_language_of_use: nil,
@@ -41,6 +44,7 @@ class NameTranslationParameters
     @name = name
     @entity_type = options[:entity_type]
     @genre = options[:genre]
+    @maximum_results = options[:maximum_results]
     @rosette_options = options[:rosette_options]
     @source_language_of_origin = options[:source_language_of_origin]
     @source_language_of_use = options[:source_language_of_use]
@@ -55,6 +59,12 @@ class NameTranslationParameters
   def validate_params
     msg = 'rosette_options can only be an instance of a Hash'
     raise BadRequestError.new(msg) if @rosette_options && !(@rosette_options.is_a? Hash)
+
+    max_msg = 'maximum_results can only be an instance of an Integer'
+    raise BadRequestError.new(max_msg) if @maximum_results && !(@maximum_results.is_a? Integer)
+
+    max_range_msg = 'maximum_results must be greater than or equal to 0'
+    raise BadRequestError.new(max_range_msg) if @maximum_results&.negative?
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -73,7 +83,6 @@ class NameTranslationParameters
   def to_hash
     {
       entity_type: @entity_type,
-      genre: @genre,
       name: @name,
       options: @rosette_options,
       source_language_of_origin: @source_language_of_origin,
@@ -81,7 +90,8 @@ class NameTranslationParameters
       source_script: @source_script,
       target_language: @target_language,
       target_scheme: @target_scheme,
-      target_script: @target_script
+      target_script: @target_script,
+      maximum_results: @maximum_results
     }
   end
 end

data/lib/record_similarity_parameters.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'bad_request_error'
+
+# This class encapsulates parameters that are needed for record-similarity in
+# Analytics API.
+class RecordSimilarityParameters
+  # Records to be compared (required)
+  attr_accessor :records
+
+  # Field names/definitions used for similarity scoring (required)
+  attr_accessor :fields
+
+  # Optional properties map sent to the API (optional, should be a hash)
+  attr_accessor :properties
+
+  def initialize(fields, records, properties = nil) # :notnew:
+    @fields = fields
+    @records = records
+    @properties = properties
+  end
+
+  # Validates the parameters by checking if required fields are present and
+  # optional properties is a Hash if provided.
+  def validate_params
+    f_msg = 'fields option is required'
+    raise BadRequestError.new(f_msg) if @fields.nil?
+
+    f_type_msg = 'fields can only be an instance of a Hash'
+    raise BadRequestError.new(f_type_msg) unless @fields.is_a? Hash
+
+    f_empty_msg = 'fields must not be empty'
+    raise BadRequestError.new(f_empty_msg) if @fields.empty?
+
+    r_msg = 'records option is required'
+    raise BadRequestError.new(r_msg) if @records.nil?
+
+    r_type_msg = 'records can only be an instance of a Hash'
+    raise BadRequestError.new(r_type_msg) unless @records.is_a? Hash
+
+    r_empty_msg = 'records must not be empty'
+    raise BadRequestError.new(r_empty_msg) if @records.empty?
+
+    p_msg = 'properties can only be an instance of a Hash'
+    raise BadRequestError.new(p_msg) if @properties && !(@properties.is_a? Hash)
+  end
+
+  # Converts this class to Hash with its keys in lower CamelCase.
+  #
+  # Returns the new Hash.
+  def load_params
+    validate_params
+    to_hash
+      .compact
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
+  end
+
+  # Converts this class to Hash.
+  #
+  # Returns the new Hash.
+  def to_hash
+    {
+      fields: @fields,
+      records: @records,
+      properties: @properties
+    }
+  end
+end

data/lib/request_builder.rb

@@ -6,17 +6,45 @@ require 'json'
 require 'securerandom'
 require_relative 'rosette_api_error'
 
-# This class handles all Rosette API requests.
+# This class handles all Analytics API requests.
 class RequestBuilder
-  # Alternate Rosette API URL
+  CONNECTION_ERROR_CODE = 'connectionError'
+  CONNECTION_ERROR_MESSAGE = 'Failed to establish connection with Analytics server.'
+
+  INVALID_HEADER_CODE = 'invalidHeader'
+  INVALID_HEADER_MESSAGE = 'Custom header must begin with "X-RosetteAPI-" or "X-BabelStreetAPI-"'
+
+  READ_MULTIPART_ERROR_CODE = 'readMultipartError'
+
+  HEADER_API_KEY = 'X-BabelStreetAPI-Key'
+  HEADER_CONTENT_TYPE = 'Content-Type'
+  HEADER_ACCEPT = 'Accept'
+  HEADER_USER_AGENT = 'User-Agent'
+  HEADER_BINDING_LEGACY = 'X-RosetteAPI-Binding'
+  HEADER_BINDING = 'X-BabelStreetAPI-Binding'
+  HEADER_BINDING_VERSION_LEGACY = 'X-RosetteAPI-Binding-Version'
+  HEADER_BINDING_VERSION = 'X-BabelStreetAPI-Binding-Version'
+
+  BINDING_NAME = 'ruby'
+
+  CONTENT_TYPE_JSON = 'application/json'
+  CONTENT_TYPE_TEXT_PLAIN = 'text/plain'
+  ACCEPT_JSON = 'application/json'
+
+  MULTIPART_FORM_DATA = 'multipart/form-data'
+
+  CUSTOM_HEADER_PREFIX_ROSETTE = /^X-RosetteAPI-/
+  CUSTOM_HEADER_PREFIX_BABELSTREET = /^X-BabelStreetAPI-/
+
+  # Alternate API URL
   attr_reader :alternate_url
-  # Rosette API HTTP client
+  # API HTTP client
   attr_reader :http_client
   # Parameters to build the body of the request from
   attr_accessor :params
-  # Rosette API key
+  # API key
   attr_accessor :user_key
-  # Rosette API binding version
+  # API binding version
   attr_accessor :binding_version
   # User-Agent string
   attr_reader :user_agent
@@ -35,7 +63,7 @@ class RequestBuilder
     @alternate_url = "#{@alternate_url}?#{URI.encode_www_form(url_parameters)}"
   end
 
-  # Prepares a plain POST request for Rosette API.
+  # Prepares a plain POST request for Analytics API.
   #
   # ==== Attributes
   #
@@ -50,8 +78,8 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
 
@@ -60,30 +88,32 @@ class RequestBuilder
     if custom_headers
       keys_array = custom_headers.keys
       keys_array.each do |key|
-        if key.to_s =~ /^X-RosetteAPI-/
+        if key.to_s =~ CUSTOM_HEADER_PREFIX_ROSETTE || key.to_s =~ CUSTOM_HEADER_PREFIX_BABELSTREET
           request[key] = custom_headers[key]
         else
           raise RosetteAPIError.new(
-            'invalidHeader',
-            'Custom header must begin with "X-RosetteAPI-"'
+            INVALID_HEADER_CODE,
+            INVALID_HEADER_MESSAGE
           )
         end
       end
       params.delete 'customHeaders'
     end
 
-    request['X-RosetteAPI-Key'] = @user_key
-    request['Content-Type'] = 'application/json'
-    request['Accept'] = 'application/json'
-    request['User-Agent'] = @user_agent
-    request['X-RosetteAPI-Binding'] = 'ruby'
-    request['X-RosetteAPI-Binding-Version'] = @binding_version
+    request[HEADER_API_KEY] = @user_key
+    request[HEADER_CONTENT_TYPE] = CONTENT_TYPE_JSON
+    request[HEADER_ACCEPT] = ACCEPT_JSON
+    request[HEADER_USER_AGENT] = @user_agent
+    request[HEADER_BINDING_LEGACY] = BINDING_NAME
+    request[HEADER_BINDING] = BINDING_NAME
+    request[HEADER_BINDING_VERSION_LEGACY] = @binding_version
+    request[HEADER_BINDING_VERSION] = @binding_version
     request.body = params.to_json
 
     [@http_client, request]
   end
 
-  # Prepares a multipart/form-data POST request for Rosette API.
+  # Prepares a multipart/form-data POST request for Analytics API.
   #
   # ==== Attributes
   #
@@ -91,29 +121,25 @@ class RequestBuilder
   #
   # Returns a HTTP connection and the built POST request.
   def prepare_multipart_request(params)
-    begin
-      file = File.open params['filePath'], 'r'
-      text = file.read
-    rescue StandardError => e
-      raise RosetteAPIError.new('readMultipartError', e)
-    end
+    text = read_multipart_file params['filePath']
 
     boundary = SecureRandom.hex
     post_body = []
-    params.delete 'filePath'
-    request_file = params.to_json
 
     # Add the content data
     post_body << "--#{boundary}\r\n"
     post_body << 'Content-Disposition: form-data; name="content"; ' \
-                 "filename=\"#{File.basename(file)}\"\r\n"
-    post_body << "Content-Type: text/plain\r\n\r\n"
+                 "filename=\"#{File.basename(params['filePath'])}\"\r\n"
+    post_body << "#{HEADER_CONTENT_TYPE}: #{CONTENT_TYPE_TEXT_PLAIN}\r\n\r\n"
     post_body << text
 
     # Add the request data
+    params.delete 'filePath'
+    request_file = params.to_json
+
     post_body << "\r\n\r\n--#{boundary}\r\n"
     post_body << "Content-Disposition: form-data; name=\"request\"\r\n"
-    post_body << "Content-Type: application/json\r\n\r\n"
+    post_body << "#{HEADER_CONTENT_TYPE}: #{CONTENT_TYPE_JSON}\r\n\r\n"
     post_body << request_file
     post_body << "\r\n\r\n--#{boundary}--\r\n"
 
@@ -125,8 +151,8 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette API server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
 
@@ -134,30 +160,43 @@ class RequestBuilder
     unless params['customHeaders'].nil?
       keys_array = params['customHeaders'].keys
       keys_array.each do |k|
-        if k.to_s =~ /^X-RosetteAPI-/
+        if k.to_s =~ CUSTOM_HEADER_PREFIX_ROSETTE || k.to_s =~ CUSTOM_HEADER_PREFIX_BABELSTREET
           request.add_field k, params['customHeaders'][k]
         else
           raise RosetteAPIError.new(
-            'invalidHeader',
-            'Custom header must begin with "X-RosetteAPI-"'
+            INVALID_HEADER_CODE,
+            INVALID_HEADER_MESSAGE
           )
         end
       end
       params.delete 'customHeaders'
     end
 
-    request.add_field 'Content-Type',
-                      "multipart/form-data; boundary=#{boundary}"
-    request.add_field 'User-Agent', @user_agent
-    request.add_field 'X-RosetteAPI-Key', @user_key
-    request.add_field 'X-RosetteAPI-Binding', 'ruby'
-    request.add_field 'X-RosetteAPI-Binding-Version', @binding_version
+    request.add_field HEADER_CONTENT_TYPE,
+                      "#{MULTIPART_FORM_DATA}; boundary=#{boundary}"
+    request.add_field HEADER_USER_AGENT, @user_agent
+    request.add_field HEADER_API_KEY, @user_key
+    request.add_field HEADER_BINDING_LEGACY, BINDING_NAME
+    request.add_field HEADER_BINDING, BINDING_NAME
+    request.add_field HEADER_BINDING_VERSION_LEGACY, @binding_version
+    request.add_field HEADER_BINDING_VERSION, @binding_version
     request.body = post_body.join
 
     [@http_client, request]
   end
 
-  # Sends a GET request to Rosette API.
+  # Reads the content of a file given its path.
+  #
+  # Returns the content of the file or raises error if encountered.
+  def read_multipart_file(file_path)
+    File.open(file_path, 'r') do |f|
+      return f.read
+    end
+  rescue StandardError => e
+    raise RosetteAPIError.new(READ_MULTIPART_ERROR_CODE, e)
+  end
+
+  # Sends a GET request to Analytics API.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def send_get_request
@@ -168,17 +207,17 @@ class RequestBuilder
       # Not ideal.  Consider switching to a different library.
       # https://stackoverflow.com/a/11802674
       raise RosetteAPIError.new(
-        'connectionError',
-        'Failed to establish connection with Rosette API server.'
+        CONNECTION_ERROR_CODE,
+        CONNECTION_ERROR_MESSAGE
       )
     end
-    request['X-RosetteAPI-Key'] = @user_key
-    request['User-Agent'] = @user_agent
+    request[HEADER_API_KEY] = @user_key
+    request[HEADER_USER_AGENT] = @user_agent
 
     get_response @http_client, request
   end
 
-  # Sends a POST request to Rosette API.
+  # Sends a POST request to Analytics API.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def send_post_request
@@ -197,7 +236,7 @@ class RequestBuilder
   #
   # * +http+ - HTTP connection.
   #
-  # * +request+ - Prepared Rosette API request.
+  # * +request+ - Prepared API request.
   #
   # Returns JSON response or raises RosetteAPIError if encountered.
   def get_response(http, request)
@@ -210,8 +249,9 @@ class RequestBuilder
 
       JSON.parse(response.body).merge(response_headers)
     else
-      message = JSON.parse(response.body)['message']
-      code = JSON.parse(response.body)['code']
+      parsed_body = JSON.parse(response.body)
+      message = parsed_body['message']
+      code = parsed_body['code']
       raise RosetteAPIError.new code, message
     end
   end

data/lib/rosette_api.rb

@@ -5,67 +5,70 @@ require_relative 'document_parameters'
 require_relative 'name_deduplication_parameters'
 require_relative 'name_translation_parameters'
 require_relative 'name_similarity_parameters'
+require_relative 'record_similarity_parameters'
 require_relative 'address_similarity_parameters'
 require_relative 'rosette_api_error'
 require_relative 'bad_request_error'
 require_relative 'bad_request_format_error'
 require 'logger'
 
-# This class allows you to access all Rosette API endpoints.
+# This class allows you to access all Analytics API endpoints.
 class RosetteAPI
   # Version of Ruby binding
-  BINDING_VERSION = '1.27.1'
-  # Rosette API language endpoint
+  BINDING_VERSION = '1.37.0'
+  # API address-similarity endpoint
+  ADDRESS_SIMILARITY_ENDPOINT = '/address-similarity'
+  # API categories endpoint
+  CATEGORIES_ENDPOINT = '/categories'
+  # API entities endpoint
+  ENTITIES_ENDPOINT = '/entities'
+  # API events endpoint
+  EVENTS_ENDPOINT = '/events'
+  # API info endpoint
+  INFO = '/info'
+  # API language endpoint
   LANGUAGE_ENDPOINT = '/language'
-  # Rosette API morphology endpoint
+  # API morphology endpoint
   MORPHOLOGY_ENDPOINT = '/morphology'
-  # Rosette API entities endpoint
-  ENTITIES_ENDPOINT = '/entities'
-  # Rosette API categories endpoint
-  CATEGORIES_ENDPOINT = '/categories'
-  # Rosette API relationships endpoint
-  RELATIONSHIPS_ENDPOINT = '/relationships'
-  # Rosette API sentiment endpoint
-  SENTIMENT_ENDPOINT = '/sentiment'
   # Name Deduplication endpoint
   NAME_DEDUPLICATION_ENDPOINT = '/name-deduplication'
-  # Rosette API name-translation endpoint
-  NAME_TRANSLATION_ENDPOINT = '/name-translation'
-  # Rosette API name-similarity endpoint
+  # API name-similarity endpoint
   NAME_SIMILARITY_ENDPOINT = '/name-similarity'
-  # Rosette API address-similarity endpoint
-  ADDRESS_SIMILARITY_ENDPOINT = '/address-similarity'
-  # Rosette API tokens endpoint
-  TOKENS_ENDPOINT = '/tokens'
-  # Rosette API sentences endpoint
-  SENTENCES_ENDPOINT = '/sentences'
-  # Rosette API info endpoint
-  INFO = '/info'
-  # Rosette API ping endpoint
+  # API name-translation endpoint
+  NAME_TRANSLATION_ENDPOINT = '/name-translation'
+  # API ping endpoint
   PING = '/ping'
-  # Text Embedding endpoint (deprecated)
-  TEXT_EMBEDDING = '/text-embedding'
-  # Semantic Vectors endpoint (replaces /text-embedding)
+  # Record Similarity endpoint
+  RECORD_SIMILARITY_ENDPOINT = '/record-similarity'
+  # API relationships endpoint
+  RELATIONSHIPS_ENDPOINT = '/relationships'
+  # Semantic Vectors endpoint (replaces deprecated /text-embedding)
   SEMANTIC_VECTORS = '/semantics/vector'
+  # API sentences endpoint
+  SENTENCES_ENDPOINT = '/sentences'
+  # API sentiment endpoint
+  SENTIMENT_ENDPOINT = '/sentiment'
   # Similar Terms endpoint
   SIMILAR_TERMS_ENDPOINT = '/semantics/similar'
   # Syntactic Dependencies endpoint
   SYNTACTIC_DEPENDENCIES_ENDPOINT = '/syntax/dependencies'
-  # Transliteration endpoint
-  TRANSLITERATION_ENDPOINT = '/transliteration'
+  # API tokens endpoint
+  TOKENS_ENDPOINT = '/tokens'
   # Topics endpoint
   TOPICS_ENDPOINT = '/topics'
+  # Transliteration endpoint
+  TRANSLITERATION_ENDPOINT = '/transliteration'
 
-  # Rosette API key
+  # API key
   attr_accessor :user_key
-  # Alternate Rosette API URL
+  # Alternate API URL
   attr_accessor :alternate_url
-  # custom Rosette API headers
+  # custom API headers
   attr_accessor :custom_headers
   # URL query parameter(s)
   attr_accessor :url_parameters
 
-  def initialize(user_key, alternate_url = 'https://api.rosette.com/rest/v1')
+  def initialize(user_key, alternate_url = 'https://analytics.babelstreet.com/rest/v1')
     @log = Logger.new($stdout)
     @user_key = user_key
     @alternate_url = alternate_url
@@ -350,6 +353,26 @@ class RosetteAPI
                   .send_post_request
   end
 
+  # Compares records and returns similarity information.
+  #
+  # ==== Attributes
+  #
+  # * +params+ - RecordSimilarityParameters helps to build the request body in
+  #   RequestBuilder.
+  #
+  # Returns record similarity results.
+  def get_record_similarity(params)
+    check_params params,
+                 'Expects a RecordSimilarityParameters type as an argument',
+                 RecordSimilarityParameters
+
+    params = params.load_params
+
+    RequestBuilder.new(@user_key, @alternate_url + RECORD_SIMILARITY_ENDPOINT,
+                       @http_client, BINDING_VERSION, params, @url_parameters)
+                  .send_post_request
+  end
+
   # Divides the input into tokens.
   #
   # ==== Attributes
@@ -398,13 +421,8 @@ class RosetteAPI
   #
   # Returns the text embedding representation of the input.
   def get_text_embedding(params)
-    check_params params
-
-    params = params.load_params
-
-    RequestBuilder.new(@user_key, @alternate_url + TEXT_EMBEDDING, @http_client,
-                       BINDING_VERSION, params, @url_parameters)
-                  .send_post_request
+    @log.warn('get_text_embedding is deprecated. Please use get_semantic_vectors instead.')
+    get_semantic_vectors(params)
   end
 
   #
@@ -501,7 +519,25 @@ class RosetteAPI
                   .send_post_request
   end
 
-  # Gets information about the Rosette API, returns name, build number
+  # Returns the events of the input
+  #
+  # ==== Attributes
+  #
+  # * +params+ - DocumentParameters helps to build the request body in
+  #   RequestBuilder.
+  #
+  # Returns the events of the input
+  def get_events(params)
+    check_params params
+
+    params = params.load_params
+
+    RequestBuilder.new(@user_key, @alternate_url + EVENTS_ENDPOINT,
+                       @http_client, BINDING_VERSION, params, @url_parameters)
+                  .send_post_request
+  end
+
+  # Gets information about the API, returns name, build number
   # and build time.
   def info
     RequestBuilder.new(@user_key, @alternate_url + INFO, @http_client,
@@ -509,7 +545,7 @@ class RosetteAPI
                   .send_get_request
   end
 
-  # Pings the Rosette API for a response indicting that the service is
+  # Pings the API for a response indicting that the service is
   # available.
   def ping
     RequestBuilder.new(@user_key, @alternate_url + PING, @http_client,

data/lib/rosette_api_error.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# This class encapsulates all Rosette API server errors encountered during
+# This class encapsulates all API server errors encountered during
 # requests.
 class RosetteAPIError < StandardError
-  # Rosette API error's status code
+  # API error's status code
   attr_accessor :status_code
-  # Rosette API error's message
+  # API error's message
   attr_accessor :message
 
   def initialize(status_code, message) # :notnew: