rosette_api 1.14.4 → 1.37.0

data/examples/record_similarity.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'rosette_api'
+
+api_key, url = ARGV
+
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
+
+begin
+  # Field names
+  primary_name_field = 'primaryName'
+  dob_field = 'dob'
+  dob2_field = 'dob2'
+  addr_field = 'addr'
+  str_field = 'jobTitle'
+  number_field = 'age'
+  bool_field = 'isRetired'
+
+  dob_hyphen = '1993-04-16'
+
+  # Request fields definition
+  fields = {
+    primary_name_field => { type: 'rni_name', weight: 0.5 },
+    dob_field => { type: 'rni_date', weight: 0.2 },
+    dob2_field => { type: 'rni_date', weight: 0.1 },
+    addr_field => { type: 'rni_address', weight: 0.5 },
+    str_field => { type: 'rni_string', weight: 0.2 },
+    number_field => { type: 'rni_number', weight: 0.4 },
+    bool_field => { type: 'rni_boolean', weight: 0.05 }
+  }
+
+  # Request properties
+  properties = {
+    threshold: 0.7,
+    includeExplainInfo: true
+  }
+
+  # Records payload. This shape mirrors the Java example's left/right lists.
+  #
+  # NOTE: The exact record field object schemas are API-specific. This example
+  # uses descriptive hashes that are intended to serialize cleanly to JSON.
+  records = {
+    left: [
+      {
+        primary_name_field => {
+          text: 'Ethan R',
+          entityType: 'PERSON',
+          language: 'eng',
+          languageOfOrigin: 'eng',
+          script: 'Latn'
+        },
+        dob_field => dob_hyphen,
+        dob2_field => {
+          date: '04161993',
+          format: 'MMddyyyy'
+        },
+        addr_field => '123 Roadlane Ave',
+        str_field => 'software engineer'
+      },
+      {
+        primary_name_field => {
+          text: 'Evan R'
+        },
+        dob_field => {
+          date: dob_hyphen
+        },
+        number_field => 47,
+        bool_field => false
+      }
+    ],
+    right: [
+      {
+        primary_name_field => {
+          text: 'Seth R',
+          language: 'eng'
+        },
+        dob_field => {
+          date: dob_hyphen
+        },
+        str_field => 'manager',
+        bool_field => true
+      },
+      {
+        primary_name_field => 'Ivan R',
+        dob_field => {
+          date: dob_hyphen
+        },
+        dob2_field => {
+          date: '1993/04/16'
+        },
+        addr_field => {
+          houseNumber: '123',
+          road: 'Roadlane Ave',
+          cityDistrict: 'Alpha'
+        },
+        number_field => 72,
+        bool_field => true
+      }
+    ]
+  }
+
+  params = RecordSimilarityParameters.new(fields, records, properties)
+  response = analytics_api.get_record_similarity(params)
+  puts JSON.pretty_generate(response)
+rescue RosetteAPIError => e
+  printf('Rosette API Error (%<status_code>s): %<message>s',
+         status_code: e.status_code,
+         message: e.message)
+end

data/examples/relationships.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 relationships_text_data = 'FLIR Systems is headquartered in Oregon and produces thermal imaging, night vision, and infrared cameras and sensor systems.  According to the SEC\'s order instituting a settled administrative proceeding, FLIR entered into a multi-million dollar contract to provide thermal binoculars to the Saudi government in November 2008.  Timms and Ramahi were the primary sales employees responsible for the contract, and also were involved in negotiations to sell FLIR\'s security cameras to the same government officials.  At the time, Timms was the head of FLIR\'s Middle East office in Dubai.'
 
 begin
   params = DocumentParameters.new(content: relationships_text_data)
-  response = rosette_api.get_relationships(params)
+  response = analytics_api.get_relationships(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/semantic_vectors.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 semantic_vectors_data = 'Cambridge, Massachusetts'
 begin
   params = DocumentParameters.new(content: semantic_vectors_data)
-  response = rosette_api.get_semantic_vectors(params)
+  response = analytics_api.get_semantic_vectors(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/sentences.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 sentences_data = 'This land is your land. This land is my land, from California to the New York island; from the red wood forest to the Gulf Stream waters. This land was made for you and Me. As I was walking that ribbon of highway, I saw above me that endless skyway: I saw below me that golden valley: This land was made for you and me.'
 
 begin
   params = DocumentParameters.new
   params.content = sentences_data
-  response = rosette_api.get_sentences(params)
+  response = analytics_api.get_sentences(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/sentiment.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
-require 'tempfile'
+require 'json'
 require 'rosette_api'
+require 'tempfile'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 file = Tempfile.new(%w[foo .html])
 sentiment_file_data = '<html><head><title>New Ghostbusters Film</title></head><body><p>Original Ghostbuster Dan Aykroyd, who also co-wrote the 1984 Ghostbusters film, couldn\'t be more pleased with the new all-female Ghostbusters cast, telling The Hollywood Reporter, "The Aykroyd family is delighted by this inheritance of the Ghostbusters torch by these most magnificent women in comedy."</p></body></html>'
@@ -17,7 +18,7 @@ file.write(sentiment_file_data)
 file.close
 begin
   params = DocumentParameters.new(file_path: file.path, language: 'eng')
-  response = rosette_api.get_sentiment(params)
+  response = analytics_api.get_sentiment(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/similar_terms.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 similar_terms_data = 'spy'
 begin
   params = DocumentParameters.new(content: similar_terms_data)
   params.rosette_options = { 'resultLanguages' => %w[spa deu jpn] }
-  response = rosette_api.get_similar_terms(params)
+  response = analytics_api.get_similar_terms(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/syntax_dependencies.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 syntax_dependencies_data = 'Yoshinori Ohsumi, a Japanese cell biologist, was awarded the Nobel Prize in Physiology or Medicine on Monday.'
 
 begin
   params = DocumentParameters.new(content: syntax_dependencies_data)
-  response = rosette_api.get_syntax_dependencies(params)
+  response = analytics_api.get_syntax_dependencies(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/tokens.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 tokens_data = '北京大学生物系主任办公室内部会议'
 begin
   params = DocumentParameters.new(content: tokens_data)
-  response = rosette_api.get_tokens(params)
+  response = analytics_api.get_tokens(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/topics.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 topics_data = 'Lily Collins is in talks to join Nicholas Hoult in Chernin Entertainment and Fox Searchlight\'s J.R.R. Tolkien biopic Tolkien. Anthony Boyle, known for playing Scorpius Malfoy in the British play Harry Potter and the Cursed Child, also has signed on for the film centered on the famed author. In Tolkien, Hoult will play the author of the Hobbit and Lord of the Rings book series that were later adapted into two Hollywood trilogies from Peter Jackson. Dome Karukoski is directing the project.'
 
 begin
   params = DocumentParameters.new(content: topics_data)
-  response = rosette_api.get_topics(params)
+  response = analytics_api.get_topics(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/examples/transliteration.rb

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
+require 'json'
 require 'rosette_api'
 
 api_key, url = ARGV
 
-rosette_api = if url
-                RosetteAPI.new(api_key, url)
-              else
-                RosetteAPI.new(api_key)
-              end
+analytics_api = if url
+                  RosetteAPI.new(api_key, url)
+                else
+                  RosetteAPI.new(api_key)
+                end
 
 transliteration_content_data = 'ana r2ye7 el gam3a el sa3a 3 el 3asr'
 
 begin
   params = DocumentParameters.new
   params.content = transliteration_content_data
-  response = rosette_api.get_transliteration(params)
+  response = analytics_api.get_transliteration(params)
   puts JSON.pretty_generate(response)
 rescue RosetteAPIError => e
   printf('Rosette API Error (%<status_code>s): %<message>s',

data/lib/address_parameter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# This class represents an address in Rosette API.
+# This class represents an address in Analytics API.
 class AddressParameter
   # house (optional)
   attr_accessor :house
@@ -39,7 +39,7 @@ class AddressParameter
   # po_box (optional)
   attr_accessor :po_box
 
-  def initialize(options = {}) #:notnew:
+  def initialize(options = {}) # :notnew:
     options = {
       house: nil,
       house_number: nil,
@@ -85,8 +85,7 @@ class AddressParameter
   # Returns the new Hash.
   def load_param
     to_hash.select { |_key, value| value }
-           .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-           .to_h
+           .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.

data/lib/address_similarity_parameters.rb

@@ -4,16 +4,20 @@ require_relative 'bad_request_error'
 require_relative 'address_parameter'
 
 # This class encapsulates parameters that are needed for address-similarity in
-# Rosette API.
+# Analytics API.
 class AddressSimilarityParameters
   # Address to be compared to address2
   attr_accessor :address1
   # Address to be compared to address1
   attr_accessor :address2
 
-  def initialize(address1, address2) #:notnew:
+  # Parameters map sent to the API (optional, should be a hash)
+  attr_accessor :parameters
+
+  def initialize(address1, address2, address_parameters = nil) # :notnew:
     @address1 = address1
     @address2 = address2
+    @parameters = address_parameters
   end
 
   # Validates the parameters by checking if address1 and address2 are instances
@@ -24,6 +28,9 @@ class AddressSimilarityParameters
 
     a2_msg = 'address2 option can only be an instance of an AddressParameter or a String'
     raise BadRequestError.new(a2_msg) if [String, AddressParameter].none? { |clazz| @address2.is_a? clazz }
+
+    opt_msg = 'parameters can only be an instance of a Hash'
+    raise BadRequestError.new(opt_msg) if @parameters && !(@parameters.is_a? Hash)
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -32,9 +39,8 @@ class AddressSimilarityParameters
   def load_params
     validate_params
     to_hash
-      .reject { |_key, value| value.nil? }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .compact
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.
@@ -43,7 +49,8 @@ class AddressSimilarityParameters
   def to_hash
     {
       address1: @address1.is_a?(AddressParameter) ? @address1.load_param : @address1,
-      address2: @address2.is_a?(AddressParameter) ? @address2.load_param : @address2
+      address2: @address2.is_a?(AddressParameter) ? @address2.load_param : @address2,
+      parameters: @parameters
     }
   end
 end

data/lib/bad_request_error.rb

@@ -2,9 +2,9 @@
 
 require_relative 'rosette_api_error'
 
-# This class represents Rosette API errors with badRequest status_code.
+# This class represents Analytics API errors with badRequest status_code.
 class BadRequestError < RosetteAPIError
-  def initialize(message) #:notnew:
-    super 'badRequest', message
+  def initialize(message) # :notnew:
+    super('badRequest', message)
   end
 end

data/lib/bad_request_format_error.rb

@@ -2,9 +2,9 @@
 
 require_relative 'rosette_api_error'
 
-# This class represents Rosette API errors with badRequestFormat status_code.
+# This class represents Analytics API errors with badRequestFormat status_code.
 class BadRequestFormatError < RosetteAPIError
-  def initialize(message) #:notnew:
-    super 'badRequestFormat', message
+  def initialize(message) # :notnew:
+    super('badRequestFormat', message)
   end
 end

data/lib/document_parameters.rb

@@ -17,12 +17,12 @@ class DocumentParameters
   attr_accessor :genre
   # ISO 639-3 language code of the provided content (optional)
   attr_accessor :language
-  # Rosette API options (optional, should be a hash)
+  # API options (optional, should be a hash)
   attr_accessor :rosette_options
-  # custom Rosette API headers
+  # custom API headers
   attr_accessor :custom_headers
 
-  def initialize(options = {}) #:notnew:
+  def initialize(options = {}) # :notnew:
     options = {
       content: nil,
       content_uri: nil,
@@ -45,18 +45,18 @@ class DocumentParameters
   # set or no content provided at all.
   def validate_params
     content_msg = 'The format of the request is invalid: multiple content ' \
-      'sources; must be one of an attachment, an inline "content" field, or ' \
-      'an external "contentUri"'
+                  'sources; must be one of an attachment, an inline "content" field, or ' \
+                  'an external "contentUri"'
     no_content_msg = 'The format of the request is invalid: no content ' \
-      'provided; must be one of an attachment, an inline "content" field, or ' \
-      'an external "contentUri"'
+                     'provided; must be one of an attachment, an inline "content" field, or ' \
+                     'an external "contentUri"'
     opt_msg = 'rosette_options can only be an instance of a Hash'
     if [@content, @content_uri, @file_path].compact.length > 1
       raise BadRequestFormatError.new(content_msg)
     elsif [@content, @content_uri, @file_path].all?(&:nil?)
       raise BadRequestFormatError.new(no_content_msg)
-    elsif @rosette_options
-      raise BadRequestError.new(opt_msg) unless @rosette_options.is_a? Hash
+    elsif @rosette_options && !@rosette_options.is_a?(Hash)
+      raise BadRequestError.new(opt_msg)
     end
   end
 
@@ -67,8 +67,7 @@ class DocumentParameters
     validate_params
     to_hash
       .select { |_key, value| value }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.
@@ -79,7 +78,6 @@ class DocumentParameters
       content: @content,
       content_uri: @content_uri,
       file_path: @file_path,
-      genre: @genre,
       language: @language,
       options: @rosette_options,
       custom_headers: @custom_headers

data/lib/name_deduplication_parameters.rb

@@ -4,16 +4,16 @@ require_relative 'bad_request_error'
 require_relative 'name_parameter'
 
 # This class encapsulates parameters that are needed for name-deduplication in
-# Rosette API.
+# Analytics API.
 class NameDeduplicationParameters
-  # Rosette API options (optional, should be a hash)
+  # API options (optional, should be a hash)
   attr_accessor :rosette_options
   # List of Name objects to be de-duplicated
   attr_accessor :names
   # Threshold for determining cluster size
   attr_accessor :threshold
 
-  def initialize(names, threshold, options = {}) #:notnew:
+  def initialize(names, threshold, options = {}) # :notnew:
     options = {
       rosette_options: nil
     }.update options
@@ -35,9 +35,7 @@ class NameDeduplicationParameters
       raise BadRequestError.new(thresh_msg) if @threshold.negative? || @threshold > 1
     end
     opt_msg = 'rosette_options can only be an instance of a Hash'
-    if @rosette_options
-      raise BadRequestError.new(opt_msg) unless @rosette_options.is_a? Hash
-    end
+    raise BadRequestError.new(opt_msg) if @rosette_options && !(@rosette_options.is_a? Hash)
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -47,8 +45,7 @@ class NameDeduplicationParameters
     validate_params
     to_hash
       .select { |_key, value| value }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.

data/lib/name_parameter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# This class represents an entity name in Rosette API.
+# This class represents an entity name in Analytics API.
 class NameParameter
   # Name's entity type (PERSON, LOCATION, ORGANIZATION) (optional)
   attr_accessor :entity_type
@@ -8,19 +8,36 @@ class NameParameter
   attr_accessor :language
   # ISO 15924 code of the name's script (optional)
   attr_accessor :script
+  # Name's gender (male, female, nonbinary) (optional)
+  attr_accessor :gender
   # Name to be analyzed
   attr_accessor :text
 
-  def initialize(text, options = {}) #:notnew:
+  VALID_GENDERS = %w[male female nonbinary].freeze
+
+  def initialize(text, options = {}) # :notnew:
     options = {
       entity_type: nil,
       language: nil,
-      script: nil
+      script: nil,
+      gender: nil
     }.update options
     @text = text
     @entity_type = options[:entity_type]
     @language = options[:language]
     @script = options[:script]
+    @gender = options[:gender]
+
+    validate_gender
+  end
+
+  def validate_gender
+    return if @gender.nil?
+
+    normalized = @gender.to_s.downcase
+    return if VALID_GENDERS.include?(normalized)
+
+    raise ArgumentError.new("gender must be one of: #{VALID_GENDERS.join(', ')}")
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -29,8 +46,7 @@ class NameParameter
   def load_param
     to_hash
       .select { |_key, value| value }
-      .map { |key, value| [key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase), value] }
-      .to_h
+      .transform_keys { |key| key.to_s.split('_').map(&:capitalize).join.sub!(/\D/, &:downcase) }
   end
 
   # Converts this class to Hash.
@@ -41,6 +57,7 @@ class NameParameter
       entity_type: @entity_type,
       language: @language,
       script: @script,
+      gender: @gender,
       text: @text
     }
   end