rosette_api 1.27.1 → 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

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.
@@ -42,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,7 +2,7 @@
 
 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)

data/lib/bad_request_format_error.rb

@@ -2,7 +2,7 @@
 
 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)

data/lib/document_parameters.rb

@@ -17,9 +17,9 @@ 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:
@@ -55,8 +55,8 @@ class DocumentParameters
       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
 
@@ -78,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,9 +4,9 @@ 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

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
 
+  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.
@@ -40,6 +57,7 @@ class NameParameter
       entity_type: @entity_type,
       language: @language,
       script: @script,
+      gender: @gender,
       text: @text
     }
   end

data/lib/name_similarity_parameters.rb

@@ -4,26 +4,28 @@ require_relative 'bad_request_error'
 require_relative 'name_parameter'
 
 # This class encapsulates parameters that are needed for name-similarity in
-# Rosette API.
+# Analytics API.
 class NameSimilarityParameters
   # genre to categorize the input data
   attr_accessor :genre
+  # Deprecated: Retained for backward compatibility. Use 'parameters' instead.
   # Rosette API options (optional, should be a hash)
   attr_accessor :rosette_options
+  # Parameters map sent to the API (optional, should be a hash)
+  attr_accessor :parameters
   # Name to be compared to name2
   attr_accessor :name1
   # Name to be compared to name1
   attr_accessor :name2
 
-  def initialize(name1, name2, options = {}) # :notnew:
-    options = {
-      genre: nil,
-      rosette_options: nil
-    }.update options
-    @genre = options[:genre]
+  def initialize(name1, name2, match_parameters = nil) # :notnew:
     @name1 = name1
     @name2 = name2
-    @rosette_options = options[:rosette_options]
+    @genre = nil
+    @parameters = nil
+    @rosette_options = nil
+
+    handle_match_parameters(match_parameters) if match_parameters
   end
 
   # Validates the parameters by checking if name1 and name2 are instances of
@@ -35,8 +37,11 @@ class NameSimilarityParameters
     n2_msg = 'name2 option can only be an instance of a String or NameParameter'
     raise BadRequestError.new(n2_msg) if [String, NameParameter].none? { |clazz| @name2.is_a? clazz }
 
-    opt_msg = 'rosette_options can only be an instance of a Hash'
-    raise BadRequestError.new(opt_msg) if @rosette_options && !(@rosette_options.is_a? Hash)
+    opt_msg = 'parameters can only be an instance of a Hash'
+    raise BadRequestError.new(opt_msg) if @parameters && !(@parameters.is_a? Hash)
+
+    rosette_opt_msg = 'rosette_options can only be an instance of a Hash'
+    raise BadRequestError.new(rosette_opt_msg) if @rosette_options && !(@rosette_options.is_a? Hash)
   end
 
   # Converts this class to Hash with its keys in lower CamelCase.
@@ -53,11 +58,39 @@ class NameSimilarityParameters
   #
   # Returns the new Hash.
   def to_hash
-    {
-      genre: @genre,
-      name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
-      name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
-      options: @rosette_options
-    }
+    if @parameters
+      {
+        name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
+        name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
+        parameters: @parameters
+      }
+    else
+      {
+        genre: @genre,
+        name1: @name1.is_a?(NameParameter) ? @name1.load_param : @name1,
+        name2: @name2.is_a?(NameParameter) ? @name2.load_param : @name2,
+        options: @rosette_options
+      }
+    end
+  end
+
+  private
+
+  # Processes the 3rd argument to determine if it is using the legacy 'options' signature
+  # or the new 'match_parameters' signature, and assigns instance variables accordingly.
+  def handle_match_parameters(match_parameters)
+    if legacy_options?(match_parameters)
+      warn 'DEPRECATION WARNING: Passing `options` dynamically via NameSimilarityParameters.new is deprecated. Please pass `parameters` instead.'
+      @genre = match_parameters[:genre] || match_parameters['genre']
+      @rosette_options = match_parameters[:rosette_options] || match_parameters['rosette_options']
+    else
+      @parameters = match_parameters
+    end
+  end
+
+  def legacy_options?(params)
+    return false unless params.is_a?(Hash)
+
+    params.key?(:genre) || params.key?('genre') || params.key?(:rosette_options) || params.key?('rosette_options')
   end
 end