ispras-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 77b155b56d3f5581f60222f3cce5871780b0699b
+  data.tar.gz: 2a9b25c10ce0ce99ad10bb442f41f86fa9d5811f
+SHA512:
+  metadata.gz: d78e6768b4bd2da6dd0b000159e57481c0bf6ff6826c9d2e69ba94dd335bbcb44cb8d3c3c969c7bd5d28d54fdba3f8aad46d0a94e31c1a9dc6572608ecc4199b
+  data.tar.gz: 43b53acf76cb4280b3e13f7921ca4ecaf2b726d15220f35187fdd45f3388488cb14888ef47ab3702ddd8e0c439655514a54a437414ba636e9067b4f8d0cf87a8

data/.gitignore

@@ -0,0 +1,36 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+.env

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.name = 'test:texterra'
+  t.libs << 'test'
+  t.test_files = ['test/test_texterra_api.rb'] 
+end
+
+Rake::TestTask.new do |t|
+  t.name = 'test:twitter'
+  t.libs << 'test'
+  t.test_files = ['test/test_twitter_api.rb'] 
+end
+
+task :test => ['test:texterra', 'test:twitter']
+
+desc "Run all tests"
+task :default => :test

data/ispapi.gemspec

@@ -0,0 +1,19 @@
+require "./lib/ispapi/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'ispras-api'
+  s.version     = Version.current
+  s.date        = Version.current_date
+  s.files       = `git ls-files`.split($\)
+  s.require_paths = ["lib"]
+  s.add_runtime_dependency 'httparty', '~> 0.13'
+  s.add_runtime_dependency 'nori', '~> 2.4'
+  s.add_development_dependency 'rake', '~> 10.4'
+  s.add_development_dependency 'minitest', '~> 5.5'
+  s.add_development_dependency 'dotenv', '~> 1.0'
+  s.summary     = "ISPRAS API Ruby SDK"
+  s.description     = "This is Ruby wrapper for REST API provided by ISPRAS. More info at https://api.ispras.ru/"
+  s.homepage = "https://github.com/alexlag/ispapi.ruby"
+  s.authors     = ["Alexey Laguta"]
+  s.email       = 'laguta@ispras.ru'
+end

data/lib/ispapi.rb

@@ -0,0 +1 @@
+require_relative 'ispapi/texterra_api'

data/lib/ispapi/api_error.rb

@@ -0,0 +1 @@
+ApiError = Class.new StandardError

data/lib/ispapi/ispras_api.rb

@@ -0,0 +1,41 @@
+require 'httparty'
+require 'nori'
+require_relative 'api_error'
+
+class IsprasAPI
+  include HTTParty
+  # debug_output $stdout
+  ROOT_URL = 'api.ispras.ru/%s/%s'
+  parser Proc.new { |data| data }
+
+  def initialize(key, name, ver)
+    if key && key.size == 40
+      self.class.base_uri ROOT_URL % [name, ver]
+      self.class.default_params apikey: key
+      @nori = Nori.new(parser: :rexml, convert_tags_to: lambda { |tag| tag.snakecase.to_sym })
+    else
+      raise ApiError, 'Please provide proper apikey'
+    end
+  end
+
+  def GET(path='', params={})
+    options = { query: params }
+    response = self.class.get "/#{path}", options
+    check_error response unless response.code == 200
+    hash = @nori.parse response.body
+  end
+
+  def POST(path='', params={}, form={})
+    options = { query: params, body: form }
+    response = self.class.post "/#{path}", options
+    check_error response unless response.code == 200
+    hash = @nori.parse response.body
+  end
+
+  private 
+
+    def check_error(response)
+      raise ApiError, "#{response.code} Error occured"
+    end
+
+end

data/lib/ispapi/texterra/kbm.rb

@@ -0,0 +1,170 @@
+require_relative './kbm_specs'
+
+module TexterraKBM
+  include TexterraKBMSpecs
+
+  # Determines if Knowledge base contains the specified term
+  #
+  # @param term [String] term
+  # @return [Hash] with :presence field
+  def term_presence(term)
+    presetKBM :termPresence, term
+  end
+
+  # Returns information measure for the given term. Information measure denotes, how often given term is used as link caption among all its occurences
+  #
+  # @param term [String] term
+  # @result [Hash] with :infomeasure field
+  def term_info_measure(term)
+    presetKBM :termInfoMeasure, term
+  end
+
+  # Return concepts resource from the Knowledge base corresponding to the found meanings of the given term
+  #
+  # @param term [String] term
+  # @result [Hash] with :elements field
+  def term_meanings(term)
+    presetKBM :termMeanings, term
+  end
+
+  # If concept isn't provided, returns concepts with their commonness, corresponding to the found meanings of the given term. Commonness denotes, how often the given term is associated with the given concept.
+  # With concept(format is {id}:{kbname}) returns commonness of given concept for the given term.
+  #
+  # @param term [String] term
+  # @param concept [String] concept as {id}:{kbname}
+  # @result [Hash] with :elements field
+  def term_commonness(term, concept='')
+    concept = "id=#{concept}" unless concept.empty?
+    presetKBM :termCommonness, [term, concept]
+  end
+
+  # Return neighbour concepts for the given concepts(list or single concept, each concept is {id}:{kbname}). 
+  # 
+  # @param concepts [String, Array<String>] either concept as {id}:{kbname} or array of such concepts
+  # @param traverse_params [Hash] optional
+  # @option traverse_params [String] :linkType searching for neightbour concepts only along these link types
+  # @option traverse_params [String] :nodeType searching for neightbour concepts only of these types
+  # @option traverse_params [Fixnum] :minDepth minimum distance from original to result concepts
+  # @option traverse_params [Fixnum] :maxDepth maximum distance from original to result concepts
+  #
+  # @result [Hash] with :elements field
+  # 
+  # If at least one traverse parameter(check REST Documentation for values) is specified, all other parameters should also be specified 
+  def neighbours(concepts, traverse_params={})
+    traverse = traverse_params.inject('') do |res, (name, value)|
+      res += ";#{name}=#{value}"
+    end unless traverse_params.empty?
+    presetKBM :neighbours, [wrap_concepts(concepts), traverse]
+  end
+
+  # Return neighbour concepts size for the given concepts(list or single concept, each concept is {id}:{kbname}).
+  # 
+  # @param concepts [String, Array<String>] either concept as {id}:{kbname} or array of such concepts
+  # @param traverse_params [Hash] optional
+  # @option traverse_params [String] :linkType searching for neightbour concepts only along these link types
+  # @option traverse_params [String] :nodeType searching for neightbour concepts only of these types
+  # @option traverse_params [Fixnum] :minDepth minimum distance from original to result concepts
+  # @option traverse_params [Fixnum] :maxDepth maximum distance from original to result concepts
+  #
+  # @result [Hash] with :size field
+  # 
+  # @note If at least one traverse parameter(check REST Documentation for values) is specified, all other parameters should also be specified  
+  def neighbours_size(concepts, traverse_params={})
+    traverse = traverse_params.inject('') do |res, (name, value)|
+      res += ";#{name}=#{value}"
+    end unless traverse_params.empty?
+    presetKBM :neighbours, [wrap_concepts(concepts), "#{traverse}/size"]
+  end
+
+  # Compute similarity for each pair of concepts(list or single concept, each concept is {id}:{kbname}). 
+  #
+  # @param [Array<String>] concepts Array of concepts as {id}:{kbname}
+  # @param [String] linkWeight Specifies method for computation of link weight in case of multiple link types - check REST Documentation for values
+  def similarity_graph(concepts, linkWeight='MAX')
+    presetKBM :similarityGraph, "#{wrap_concepts(concepts)}linkWeight=#{linkWeight}"
+  end
+
+  # Computes sum of similarities from each concepts(list or single concept, each concept is {id}:{kbname}) from the first list to all concepts(list or single concept, each concept is {id}:{kbname}) from the second one.
+  # 
+  # @param [Array<String>] first_concepts Array of concepts as {id}:{kbname}
+  # @param [Array<String>] second_concepts Array of concepts as {id}:{kbname}
+  # @param [String] linkWeight Specifies method for computation of link weight in case of multiple link types - check REST Documentation for values  
+  def all_pairs_similarity(first_concepts, second_concepts, linkWeight='MAX')
+    presetKBM :allPairsSimilarity, ["#{wrap_concepts(first_concepts)}linkWeight=#{linkWeight}", wrap_concepts(second_concepts)]
+  end
+
+  # Compute similarity from each concept from the first list to all concepts(list or single concept, each concept is {id}:{kbname}) from the second list as a whole. 
+  # Links of second list concepts(each concept is {id}:{kbname}) are collected together, thus forming a "virtual" article, similarity to which is computed.
+  # 
+  # @param [Array<String>] concepts Array of concepts as {id}:{kbname}
+  # @param [Array<String>] virtual_aricle Array of concepts as {id}:{kbname}
+  # @param [String] linkWeight Specifies method for computation of link weight in case of multiple link types - check REST Documentation for values  
+  def similarity_to_virtual_article(concepts, virtual_aricle, linkWeight='MAX')
+    presetKBM :similarityToVirtualArticle, ["#{wrap_concepts(concepts)}linkWeight=#{linkWeight}", wrap_concepts(virtual_aricle)]
+  end
+
+  # Compute similarity between two sets of concepts(list or single concept, each concept is {id}:{kbname}) as between "virtual" articles from these sets. 
+  # The links of each virtual article are composed of links of the collection of concepts. 
+  # 
+  # @param [Array<String>] first_virtual_aricle Array of concepts as {id}:{kbname}
+  # @param [Array<String>] second_virtual_article Array of concepts as {id}:{kbname}
+  # @param [String] linkWeight Specifies method for computation of link weight in case of multiple link types - check REST Documentation for values  
+  def similarity_between_virtual_articles(first_virtual_aricle, second_virtual_article, linkWeight='MAX')
+    presetKBM :similarityBetweenVirtualArticle, ["#{wrap_concepts(first_virtual_aricle)}linkWeight=#{linkWeight}", wrap_concepts(second_virtual_article)]
+  end
+
+  # Search for similar concepts among the first neighbours of the given ones(list or single concept, each concept is {id}:{kbname}).
+  # 
+  # @param [Array<String>] concepts Array of concepts as {id}:{kbname}
+  # @param [Hash] params 
+  # @option params [String] :linkWeight Specifies method for computation of link weight in case of multiple link types 
+  # @option params [Fixnum] :offset Provides a possibility to skip several concepts from the start of the result
+  # @option params [Fixnum] :limit Provides a possibility to limit size of result
+  #   
+  # @note check REST Documentation for values
+  def similar_over_first_neighbours(concepts, params={linkWeight:'MAX'})
+    presetKBM :similarOverFirstNeighbours, "#{wrap_concepts(concepts)};linkWeight=#{params[:linkWeight]}", params
+  end
+
+  # Search for similar concepts over filtered set of the first and the second neighbours of the given ones(list or single concept, each concept is {id}:{kbname}).
+  # 
+  # @param [Array<String>] concepts Array of concepts as {id}:{kbname}
+  # @param [Hash] params 
+  # @option params [String] :linkWeight Specifies method for computation of link weight in case of multiple link types 
+  # @option params [Fixnum] :offset Provides a possibility to skip several concepts from the start of the result 
+  # @option params [Fixnum] :limit Provides a possibility to limit size of result 
+  # @option params [String] :among Specifies how to filter neighbour concepts when searching for most similar
+  # 
+  # @note check REST Documentation for values
+  def similar_over_filtered_neighbours(concepts, params={linkWeight:'MAX'})
+    presetKBM :similarOverFilteredNeighbours, "#{wrap_concepts(concepts)};linkWeight=#{params[:linkWeight]}", params
+  end
+
+  # Get attributes for concepts(list or single concept, each concept is {id}:{kbname})
+  #  
+  # @param [String, Array<String>] concepts Either concept as {id}:{kbname} or array of such concepts
+  # @param [Array<String>] attributes Specifies attributes to be included into response
+  # @note check REST Documentation for supported attributes
+  def get_attributes(concepts, attributes=[])
+    presetKBM :getAttributes, wrap_concepts(concepts), attribute: attributes
+  end
+
+  private 
+
+    # Utility wrapper for matrix parameters
+    def wrap_concepts(concepts)
+      if concepts.is_a? Array
+        concepts.map { |c| "id=#{c};" }.join
+      else
+        "id=#{concepts};"
+      end
+    end
+
+    # Utility EKB part method
+    def presetKBM(methodName, pathParam, queryParam={})
+      specs = KBMSpecs[methodName]
+      queryParam.merge specs[:params]
+      GET(specs[:path] % pathParam, queryParam)
+    end
+
+end

data/lib/ispapi/texterra/kbm_specs.rb

@@ -0,0 +1,53 @@
+module TexterraKBMSpecs
+  # Path and parameters for preset KBM queries
+  KBMSpecs = {
+    termPresence: {
+      path: 'representation/%s/contained',
+      params: {}
+    },
+    termInfoMeasure: {
+      path: 'representation/%s/infomeasure',
+      params: {}
+    },
+    termMeanings: {
+      path: 'representation/%s/meanings',
+      params: {}
+    },
+    termCommonness: {
+      path: 'representation/%s/commonness/%s',
+      params: {}
+    },
+    neighbours: {
+      path: 'walker/%s/neighbours%s',
+      params: {}
+    },
+    similarityGraph: {
+      path: 'similarity/%s/graph',
+      params: {}
+    },
+    allPairsSimilarity: {
+      path: 'similarity/%s/summed/%s',
+      params: {}
+    },
+    similarityToVirtualArticle: {
+      path: 'similarity/%s/toVirtualArticle/%s',
+      params: {}
+    },
+    similarityBetweenVirtualArticle: {
+      path: 'similarity/%s/betweenVirtualArticles/%s',
+      params: {}
+    },
+    similarOverFirstNeighbours: {
+      path: 'similarity/%s/similar/neighbours',
+      params: {}
+    },
+    similarOverFilteredNeighbours: {
+      path: 'similarity/%s/similar/all',
+      params: {}
+    },
+    getAttributes: {
+      path: 'walker/%s',
+      params: {}
+    }
+  }
+end

data/lib/ispapi/texterra/nlp.rb

@@ -0,0 +1,153 @@
+require_relative './nlp_specs'
+
+module TexterraNLP
+  include TexterraNLPSpecs
+  # Detects language of given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def language_detection_annotate(text)
+    presetNLP(:languageDetection, text)
+  end
+
+  # Detects boundaries of sentences in a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def sentence_detection(text)
+    presetNLP(:sentenceDetection, text)
+  end
+
+  # Detects all tokens (minimal significant text parts) in a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def tokenization_annotate(text)
+    presetNLP(:tokenization, text)
+  end
+
+  # Detects lemma of each word of a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def lemmatization_annotate(text)
+    presetNLP(:lemmatization, text)
+  end
+
+  # Detects part of speech tag for each word of a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def pos_tagging_annotate(text)
+    presetNLP(:posTagging, text)
+  end
+
+  # Tries to correct disprints and other spelling errors in a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def spelling_correction_annotate(text)
+    presetNLP(:spellingCorrection, text)
+  end
+
+  # Finds all named entities occurences in a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def named_entities_annotate(text)
+    presetNLP(:namedEntities, text)
+  end
+
+  # Extracts not overlapping terms within a given text; term is a textual representation for some concept of the real world
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def term_detection_annotate(text)
+    presetNLP(:termDetection, text)
+  end
+
+  # Detects the most appropriate meanings (concepts) for terms occurred in a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def disambiguation_annotate(text)
+    presetNLP(:disambiguation, text)
+  end
+
+  # Key concepts are the concepts providing short (conceptual) and informative text description.
+  # This service extracts a set of key concepts for a given text
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def key_concepts_annotate(text)
+    presetNLP(:keyConcepts, text)
+  end
+
+  # Detects the most appropriate domain for the given text.
+  # Currently only 2 specific domains are supported: 'movie' and 'politics'
+  # If no domain from this list has been detected, the text is assumed to be no domain, or general domain
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def domain_detection_annotate(text)
+    presetNLP(:domainDetection, text)
+  end
+
+  # Detects whether the given text is subjective or not
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def subjectivity_detection_annotate(text)
+    presetNLP(:subjectivityDetection, text)
+  end
+
+  # Detects whether the given text has positive, negative or no sentiment
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def polarity_detection_annotate(text)
+    presetNLP(:polarityDetection, text)
+  end
+
+  # Detects whether the given text has positive, negative, or no sentiment, with respect to domain. 
+  # If domain isn't provided, Domain detection is applied, this way method tries to achieve best results.
+  # If no domain is detected general domain algorithm is applied
+  # 
+  # @param [String] text Text to process
+  # @param [String] domain Domain for polarity detection
+  # @return [Array] Texterra annotations
+  def domain_polarity_detection_annotate(text, domain='')
+    specs = NLPSpecs[:domainPolarityDetection]
+    domain = '(%s)' % domain unless domain.empty?
+    result = POST(specs[:path] % domain, specs[:params], {text: text})[:nlp_document][:annotations][:i_annotation] 
+    return [] if result.nil?
+    result = [].push result unless result.is_a? Array
+    result.each do |e| 
+      st, en  = e[:start].to_i, e[:end].to_i
+      e[:text] = e[:annotated_text] = text[st..en]
+    end
+  end
+
+  # Detects Twitter-specific entities: Hashtags, User names, Emoticons, URLs.
+  # And also: Stop-words, Misspellings, Spelling suggestions, Spelling corrections
+  # 
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def tweet_normalization(text)
+    presetNLP(:tweetNormalization, text)
+  end
+
+  private
+
+    # Utility NLP part method
+    def presetNLP(methodName, text)
+      specs = NLPSpecs[methodName]
+      result = POST(specs[:path], specs[:params], {text: text})[:nlp_document][:annotations][:i_annotation] 
+      return [] if result.nil?
+      result = [].push result unless result.is_a? Array
+      result.each do |e| 
+        st, en  = e[:start].to_i, e[:end].to_i
+        e[:text] = e[:annotated_text] = text[st..en]
+      end
+    end
+end

data/lib/ispapi/texterra/nlp_specs.rb

@@ -0,0 +1,126 @@
+module TexterraNLPSpecs
+  # Path and parameters for preset NLP queries
+  NLPSpecs = {
+    languageDetection: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.pipelines.LanguageDetectionPipeline',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.Language',
+          filtering: 'KEEPING'
+        }
+    },
+    sentenceDetection: {
+        path: 'nlp/sentence',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.Sentence',
+          filtering: 'KEEPING'
+        }
+    },
+    tokenization: {
+        path: 'nlp/token',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.Token',
+          filtering: 'KEEPING'
+        }
+    },
+    lemmatization: {
+        path: 'nlp/lemma',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.Lemma',
+          filtering: 'KEEPING'
+        }
+    },
+    posTagging: {
+        path: 'nlp/pos',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.pos.IPOSToken',
+          filtering: 'KEEPING'
+        }
+    },
+    spellingCorrection: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.annotators.spelling.SpellingCorrector',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.SpellingCorrection',
+          filtering: 'KEEPING'
+        }
+    },
+    namedEntities: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.pipelines.NETaggingPipeline',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.ne.NamedEntityToken',
+          filtering: 'KEEPING'
+        }
+    },
+    termDetection: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.pipelines.TermDetectionPipeline',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.Frame',
+          filtering: 'KEEPING'
+        }
+    },
+    disambiguation: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.pipelines.DisambiguationPipeline',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.DisambiguatedPhrase',
+          filtering: 'KEEPING'
+        }
+
+    },
+    keyConcepts: {
+        path: 'nlp/ru.ispras.texterra.core.nlp.pipelines.KeyConceptsPipeline',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.KeyconceptsSemanticContext',
+          filtering: 'KEEPING'
+        }
+
+    },
+    domainDetection: {
+        path: 'nlp/domain',
+        params: {
+          :class => 'domain',
+          filtering: 'KEEPING'
+        }
+
+    },
+    subjectivityDetection: {
+        path: 'nlp/subjectivity',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.SentimentSubjectivity',
+          filtering: 'KEEPING'
+        }
+
+    },
+    polarityDetection: {
+        path: 'nlp/polarity',
+        params: {
+          :class => 'ru.ispras.texterra.core.nlp.datamodel.SentimentPolarity',
+          filtering: 'KEEPING'
+        }
+
+    },
+    aspectExtraction: {
+        path: 'nlp/aspectsentiment',
+        params: {
+          :class => 'aspect-sentiment',
+          filtering: 'KEEPING'
+        }
+
+    },
+    domainPolarityDetection: {
+        path: 'nlp/domainpolarity%s',
+        params: {
+          :class => [ 'domain', 'sentiment-polarity' ],
+          filtering: 'KEEPING'
+        }
+
+    },
+    tweetNormalization: {
+        path: 'nlp/twitterdetection',
+        params: {
+          :class => ['sentence', 'language', 'token'],
+          filtering: 'REMOVING'
+        }
+
+    }
+  }
+ 
+end

data/lib/ispapi/texterra_api.rb

@@ -0,0 +1,86 @@
+require_relative './ispras_api'
+require_relative './texterra/nlp'
+require_relative './texterra/kbm'
+
+class TexterraAPI < IsprasAPI
+  # This class provides methods to work with Texterra REST via OpenAPI, including NLP and EKB methods and custom queriesю
+  # Note that NLP methods return annotations only
+  include TexterraNLP, TexterraKBM
+  disable_rails_query_string_format
+
+  def initialize(key, name, ver)
+    name='texterra' if name.nil? || name.empty?
+    ver='v3.1' if ver.nil? || ver.empty?
+    super(key, name, ver)
+  end
+
+  # Section of NLP methods
+  # NLP basic helper methods
+
+  # Key concepts are the concepts providing short (conceptual) and informative text description.
+  # This service extracts a set of key concepts for a given text
+  #
+  # @param [String] text Text to process
+  # @return [Array] Array of weighted key concepts
+  def key_concepts(text)
+    key_concepts = key_concepts_annotate(text)[0][:value][:concepts_weights][:entry] || []
+    key_concepts = [].push key_concepts unless key_concepts.is_a? Array
+    key_concepts.map { |kc| 
+      kc[:concept][:weight] = kc[:double] 
+      kc[:concept]
+    }
+  end
+
+  # Detects whether the given text has positive, negative or no sentiment
+  #
+  # @param [String] text Text to process
+  # @return [Array] Sentiment of the text
+  def sentiment_analysis(text)
+    begin
+      polarity_detection_annotate(text)[0][:value].to_s || 'NEUTRAL'
+    rescue NoMethodError
+      'NEUTRAL'
+    end
+  end
+
+  # Detects whether the given text has positive, negative, or no sentiment, with respect to domain. 
+  # If domain isn't provided, Domain detection is applied, this way method tries to achieve best results.
+  # If no domain is detected general domain algorithm is applied
+  #
+  # @param [String] text Text to process
+  # @param domain [String] domain to use. Can be empty
+  # @return [Hash] used :domain and detected :polarity
+  def domain_sentiment_analysis(text, domain='')
+    used_domain = 'general'
+    sentiment = 'NEUTRAL'
+    (domain_polarity_detection_annotate(text, domain) || []).each { |an|
+      sentiment = an[:value] if an[:@class].include? 'SentimentPolarity'
+      used_domain = an[:value] if an[:@class].include? 'DomainAnnotation'
+    }
+    {
+      domain: used_domain,
+      polarity: sentiment
+    }
+  end
+
+  # Detects the most appropriate meanings (concepts) for terms occurred in a given text
+  #
+  # @param [String] text Text to process
+  # @return [Array] Texterra annotations
+  def disambiguation(text)
+    disambiguation_annotate(text)
+  end
+
+  def custom_query(path, query, form=nil)
+    form.nil? ? GET(path, query) : POST(path, query, form)
+  end
+
+  private
+
+    def check_error(response)
+      hash = @nori.parse response.body
+      er_node = hash[:html][:body][:p].detect { |node| node.is_a? Hash and node[:b] == 'root cause' }
+      raise ApiError, er_node[:pre].gsub(/ru\.ispras.*:\s*/, '')
+    end
+
+end

data/lib/ispapi/twitter_api.rb

@@ -0,0 +1,39 @@
+require_relative './ispras_api'
+
+class TwitterAPI < IsprasAPI
+  #This class provides methods to work with Twitter NLP REST via OpenAPI
+  disable_rails_query_string_format
+
+  def initialize(key, name, ver)
+    name='twitter-nlp' if name.nil? || name.empty?
+    ver='1.0' if ver.nil? || ver.empty?
+    super(key, name, ver)
+  end
+
+  # Extracts demographic attributes from provided Twitter info. All info is required, but can be empty
+  #
+  # @param [Hash] params
+  # @option params [String] :lang Language of tweets
+  # @option params [String] :username Username of Twitter user
+  # @option params [String] :screenname Screen name of Twitter user
+  # @option params [String] :description Description of Twitter user
+  # @option params [String, Array<String>] :tweet User's tweets
+  # @return [Hash] Enriched user with attributes
+  def extract_dde(params)
+    params[:tweet] = params[:tweet].join(' ') if params[:tweet].is_a? Array
+    POST 'extract', {}, params
+  end
+
+  def custom_query(path, query, form=nil)
+    form.nil? ? GET(path, query) : POST(path, query, form)
+  end
+
+  private
+
+    def check_error(response)
+      hash = @nori.parse response.body
+      er_node = hash[:html][:body][:p].detect { |node| node.is_a? Hash and node[:b] == 'root cause' }
+      raise ApiError, er_node[:pre].gsub(/ru\.ispras.*:\s*/, '')
+    end
+
+end

data/lib/ispapi/version.rb

@@ -0,0 +1,34 @@
+module Version
+
+  MAJOR = 0
+  MINOR = 1
+  PATCH = 0
+  PRE = nil
+  
+  YEAR = "2015"
+  MONTH = "02"
+  DAY = "10"
+
+  def self.to_s
+    [MAJOR, MINOR, PATCH, PRE].compact.join(".")
+  end
+
+  def self.current
+    to_s
+  end
+  
+  def self.current_date
+    "#{YEAR}-#{MONTH}-#{DAY}"
+  end
+
+  def self.version_to_h(version)
+    version_array = version.split(/\./)
+    version_hash = {}
+    version_hash[:major] = version_array[0]
+    version_hash[:minor] = version_array[1]
+    version_hash[:patch] = version_array[2]
+    version_hash[:pre] = version_array[3]
+    version_hash
+  end
+
+end

data/test/test_texterra_api.rb

@@ -0,0 +1,143 @@
+require 'minitest/autorun'
+require 'dotenv'
+Dotenv.load
+require_relative '../lib/ispapi/texterra_api'
+
+class TestTexterraAPI < Minitest::Test
+
+  def setup
+    @texterra = TexterraAPI.new ENV['TEXTERRA_KEY'], ENV['TEXTERRA_SERVICE_NAME'], ENV['TEXTERRA_SERVICE_VERSION']
+    @en_text = 'Apple today updated iMac to bring numerous high-performance enhancements to the leading all-in-one desktop. iMac now features fourth-generation Intel Core processors, new graphics, and next-generation Wi-Fi. In addition, it now supports PCIe-based flash storage, making its Fusion Drive and all-flash storage options up to 50 percent faster than the previous generation'
+    @ru_text = 'Первые в этом году переговоры министра иностранных дел России Сергея Лаврова и госсекретаря США Джона Керри, длившиеся 1,5 часа, завершились в Мюнхене.'
+    @en_tweet = 'mentioning veterens care which Mccain has voted AGAINST - SUPER GOOOOD point Obama+1 #tweetdebate'
+    @ru_tweet = 'В мастерской готовят пушку и автомобили 1940-х годов, для участия в Параде Победы в Ново-Переделкино.'
+  end  
+
+  def test_key_concepts
+    assert_instance_of Array, @texterra.key_concepts(@en_text) 
+    assert_instance_of Array, @texterra.key_concepts(@ru_text) 
+    assert_instance_of Array, @texterra.key_concepts(@en_tweet) 
+    assert_instance_of Array, @texterra.key_concepts(@ru_tweet) 
+  end
+
+  def test_disambiguation
+    assert_instance_of Array, @texterra.disambiguation(@en_text) 
+    assert_instance_of Array, @texterra.disambiguation(@ru_text) 
+  end
+
+  def test_sentiment_analysis
+    assert_instance_of String, @texterra.sentiment_analysis(@en_text)
+    assert_instance_of String, @texterra.sentiment_analysis(@ru_text)
+    assert_instance_of String, @texterra.sentiment_analysis(@en_tweet)
+    assert_instance_of String, @texterra.sentiment_analysis(@ru_tweet)
+  end
+
+  def test_domain_sentiment_analysis
+    assert_instance_of Hash, @texterra.domain_sentiment_analysis(@en_text)
+    assert_instance_of Hash, @texterra.domain_sentiment_analysis(@ru_text)
+    res = @texterra.domain_sentiment_analysis(@en_tweet, 'politics')
+    assert_instance_of Hash, res
+    assert_equal 'politics', res[:domain]
+    assert_raises ApiError do 
+      @texterra.domain_sentiment_analysis(@ru_text, 'politics')
+    end
+  end
+
+  def test_tweet_normalization
+    assert_instance_of Array, @texterra.tweet_normalization(@en_tweet) 
+    assert_raises ApiError do 
+      @texterra.tweet_normalization(@ru_tweet) 
+    end
+  end
+
+  def test_language_detection_annotate
+    assert_instance_of Array, @texterra.language_detection_annotate(@en_text) 
+    assert_instance_of Array, @texterra.language_detection_annotate(@ru_text) 
+    assert_instance_of Array, @texterra.language_detection_annotate(@en_tweet) 
+    assert_instance_of Array, @texterra.language_detection_annotate(@ru_tweet) 
+  end
+
+  def test_named_entities_annotate
+    assert_instance_of Array, @texterra.named_entities_annotate(@en_text) 
+    assert_instance_of Array, @texterra.named_entities_annotate(@ru_text) 
+    assert_instance_of Array, @texterra.named_entities_annotate(@en_tweet) 
+    assert_instance_of Array, @texterra.named_entities_annotate(@ru_tweet) 
+  end
+
+  def test_subjectivity_detection_annotate
+    assert_instance_of Array, @texterra.subjectivity_detection_annotate(@en_text) 
+    assert_instance_of Array, @texterra.subjectivity_detection_annotate(@ru_text) 
+    assert_instance_of Array, @texterra.subjectivity_detection_annotate(@en_tweet) 
+    assert_instance_of Array, @texterra.subjectivity_detection_annotate(@ru_tweet) 
+  end
+
+  def test_term_presence
+    res = @texterra.term_presence('Anarchism')
+    assert_instance_of Hash, res
+    assert_equal true, res[:presence]
+  end
+
+  def test_term_info_measure
+    assert_instance_of Hash, @texterra.term_info_measure('Anarchism')
+  end
+
+  def test_term_meanings
+    assert_instance_of Hash, @texterra.term_meanings('android')
+  end
+
+  def test_term_commonness
+    assert_instance_of Hash, @texterra.term_commonness('android')
+    assert_instance_of Hash, @texterra.term_commonness('android', '713:enwiki')
+  end
+
+  def test_neignbours
+    assert_instance_of Hash, @texterra.neighbours('12:enwiki')
+    assert_instance_of Hash, @texterra.neighbours('12:enwiki', linkType: 'RELATED', nodeType: 'REGULAR', minDepth: 1, maxDepth: 3)
+    assert_instance_of Hash, @texterra.neighbours(['12:enwiki', '713:enwiki'])
+    assert_instance_of Hash, @texterra.neighbours(['12:enwiki', '713:enwiki'], linkType: 'RELATED', nodeType: 'REGULAR', minDepth: 1, maxDepth: 3)
+  end
+
+  def test_neignbours_size
+    assert_instance_of Hash, @texterra.neighbours_size('12:enwiki')
+    assert_instance_of Hash, @texterra.neighbours_size('12:enwiki', linkType: 'RELATED', nodeType: 'REGULAR', minDepth: 1, maxDepth: 3)
+    assert_instance_of Hash, @texterra.neighbours_size(['12:enwiki', '713:enwiki'])
+    assert_instance_of Hash, @texterra.neighbours_size(['12:enwiki', '713:enwiki'], linkType: 'RELATED', nodeType: 'REGULAR', minDepth: 1, maxDepth: 3)
+  end
+
+  def test_similarity_graph
+    assert_instance_of Hash, @texterra.similarity_graph(['12:enwiki','13137:enwiki','156327:enwiki'])
+    assert_instance_of Hash, @texterra.similarity_graph(['12:enwiki','13137:enwiki','156327:enwiki'], 'MIN')
+  end
+
+  def test_all_pairs_similarity
+    assert_instance_of Hash, @texterra.all_pairs_similarity(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'])
+    assert_instance_of Hash, @texterra.all_pairs_similarity(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'], 'MIN')
+  end
+
+  def test_similarity_to_virtual_article
+    assert_instance_of Hash, @texterra.similarity_to_virtual_article(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'])
+    assert_instance_of Hash, @texterra.similarity_to_virtual_article(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'], 'MIN')
+  end
+
+  def test_similarity_between_virtual_articles
+    assert_instance_of Hash, @texterra.similarity_between_virtual_articles(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'])
+    assert_instance_of Hash, @texterra.similarity_between_virtual_articles(['12:enwiki','13137:enwiki'], ['156327:enwiki', '15942292:enwiki', '1921431:enwiki'], 'MIN')
+  end
+
+  def test_similar_over_first_neighbours
+    assert_instance_of Hash, @texterra.similar_over_first_neighbours('12:enwiki')
+    assert_instance_of Hash, @texterra.similar_over_first_neighbours('12:enwiki', linkWeight: 'MIN', offset: 1, limit: 3)
+  end
+
+  def test_similar_over_filtered_neighbours
+    assert_instance_of Hash, @texterra.similar_over_filtered_neighbours('12:enwiki')
+    assert_instance_of Hash, @texterra.similar_over_filtered_neighbours('12:enwiki', linkWeight: 'MIN', offset: 1, limit: 3, among: 'PORTION(0.2)')
+  end
+
+  def test_get_attributes
+    assert_instance_of Hash, @texterra.get_attributes('12:enwiki')
+    assert_instance_of Hash, @texterra.get_attributes(['12:enwiki', '13137:enwiki'])
+    assert_instance_of Hash, @texterra.get_attributes('12:enwiki', ['url(en)', 'type'])
+    assert_instance_of Hash, @texterra.get_attributes(['12:enwiki', '13137:enwiki'], ['url(en)', 'title'])
+  end
+end

data/test/test_twitter_api.rb

@@ -0,0 +1,15 @@
+require 'minitest/autorun'
+require 'dotenv'
+Dotenv.load
+require_relative '../lib/ispapi/twitter_api'
+
+class TestTwitterAPI < Minitest::Test
+
+  def setup
+    @twitter = TwitterAPI.new ENV['DDE_KEY'], ENV['DDE_SERVICE_NAME'], ENV['DDE_SERVICE_VERSION']
+  end  
+
+  def test_extract_dde
+    @twitter.extract_dde lang: 'en', username: 'Ann', screenname: 'bob', description: 'I am Ann from NY', tweet:'Hi there, I am Ann fromNY'
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: ispras-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Laguta
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: nori
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: This is Ruby wrapper for REST API provided by ISPRAS. More info at https://api.ispras.ru/
+email: laguta@ispras.ru
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Rakefile
+- ispapi.gemspec
+- lib/ispapi.rb
+- lib/ispapi/api_error.rb
+- lib/ispapi/ispras_api.rb
+- lib/ispapi/texterra/kbm.rb
+- lib/ispapi/texterra/kbm_specs.rb
+- lib/ispapi/texterra/nlp.rb
+- lib/ispapi/texterra/nlp_specs.rb
+- lib/ispapi/texterra_api.rb
+- lib/ispapi/twitter_api.rb
+- lib/ispapi/version.rb
+- test/test_texterra_api.rb
+- test/test_twitter_api.rb
+homepage: https://github.com/alexlag/ispapi.ruby
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: ISPRAS API Ruby SDK
+test_files: []
+has_rdoc: