open_calais 0.0.1

data/.gitignore

@@ -0,0 +1,19 @@
+*.gem
+*.rbc
+.bundle
+.config
+.key
+.rbenv-version
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in open_calais.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Andrew Kuklewicz
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# OpenCalais
+
+Ruby gem to access the OpenCalaid API, using the new-ish REST API, and JSON responses.
+It uses Faraday to abstract HTTP library (defaults to use excon because ot is excellent), and multi_json to abstract JSON parsing.
+
+It returns a parsed version of the response, but the response contains the raw response (converted from json to hashes/arrays/string/etc).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'open_calais'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install open_calais
+
+## Usage
+
+OpenCalais has one main method, 'enrich', and so does the gem:
+
+    require 'open_calais'
+
+    # you can configure for all calls
+    OpenCalais.configure do |c|
+      c.api_key = "this is a test key"
+    end
+
+    # or you can configure for a single call
+    open_calais = OpenCalais::Client.new(:api_key=>'an api key')
+
+    # it returns a OpenCalais::Response instance
+    response = open_calais.enrich('Ruby on Rails is a fantastic web framework. It uses MVC, and the Ruby programming language invented by Matz in Japan.')
+
+    # which has the 'raw' response
+    response.raw
+
+    # and has been parsed a bit to get :language, :topics, :tags, :entities, :relations, :locations
+    # as lists of hashes
+    response.tags.each{|t| puts t[:name] }
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.libs.push 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/open_calais.rb

@@ -0,0 +1,51 @@
+# -*- encoding: utf-8 -*-
+
+require 'rubygems'
+require 'open_calais/version'
+require 'open_calais/configuration'
+require 'open_calais/client'
+
+module OpenCalais
+  extend Configuration
+
+  HEADERS = {
+    :license_id                    => 'x-calais-licenseID',
+    :content_type                  => 'Content-Type',
+    :output_format                 => 'outputFormat',
+    :reltag_base_url               => 'reltagBaseURL',
+    :calculate_relevance_score     => 'calculateRelevanceScore',
+    :enable_metadata_type          => 'enableMetadataType',
+    :doc_rdf_accessible            => 'docRDFaccessible',
+    :discard_metadata              => 'discardMetadata',
+    :omit_outputting_original_text => 'omitOutputtingOriginalText',
+    :allow_distribution            => 'allowDistribution',
+    :allow_search                  => 'allowSearch',
+    :external_id                   => 'externalID',
+    :submitter                     => 'submitter'
+  }
+
+  CONTENT_TYPES = {
+    :xml     => 'TEXT/XML',
+    :html    => 'TEXT/HTML',
+    :htmlraw => 'TEXT/HTMLRAW',
+    :raw     => 'TEXT/RAW'
+  }
+
+  OUTPUT_FORMATS = {
+    :rdf          => 'XML/RDF',
+    :simple       => 'Text/Simple',
+    :microformats => 'Text/Microformats',
+    :json         => 'Application/JSON'
+  }
+
+  METADATA_SOCIAL_TAGS = 'SocialTags'
+  METADATA_GENERIC_RELATIONS = 'GenericRelations'
+  METADATA_TYPES  = [METADATA_GENERIC_RELATIONS, METADATA_SOCIAL_TAGS]
+
+  TOPICS          = ['Business_Finance', 'Disaster_Accident', 'Education', 'Entertainment_Culture', 'Environment', 'Health_Medical_Pharma', 'Hospitality_Recreation', 'Human Interest', 'Labor', 'Law_Crime', 'Politics', 'Religion_Belief', 'Social Issues', 'Sports', 'Technology_Internet', 'Weather', 'War_Conflict', 'Other']
+  ENTITY_TYPES    = %w(Anniversary City Company Continent Country Currency EmailAddress EntertainmentAwardEvent Facility FaxNumber Holiday IndustryTerm MarketIndex MedicalCondition MedicalTreatment Movie MusicAlbum MusicGroup NaturalFeature OperatingSystem Organization Person PhoneNumber PoliticalEvent Position Product ProgrammingLanguage ProvinceOrState PublishedMedium RadioProgram RadioStation Region SportsEvent SportsGame SportsLeague Technology TVShow TVStation URL)
+  GEO_TYPES       = %w(City Continent Country NaturalFeature ProvinceOrState Region)
+
+  DISAMBUGUATIONS = %w(er/Company er/Geo er/Product)
+
+end

data/lib/open_calais/client.rb

@@ -0,0 +1,49 @@
+require 'open_calais/configuration'
+require 'open_calais/connection'
+require 'open_calais/response'
+
+module OpenCalais
+  class Client
+
+    include Connection
+
+    attr_reader *OpenCalais::Configuration.keys
+
+    attr_accessor :current_options
+
+    class_eval do
+      OpenCalais::Configuration.keys.each do |key|
+        define_method "#{key}=" do |arg|
+          self.instance_variable_set("@#{key}", arg)
+          self.current_options.merge!({:"#{key}" => arg})
+        end
+      end
+    end
+
+    def initialize(options={}, &block)
+      setup(options)
+      yield(self) if block_given?
+    end
+
+    def setup(options={})
+      options = OpenCalais.options.merge(options)
+      self.current_options = options
+      Configuration.keys.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+    def enrich(text, opts={})
+      raise 'Specify a value for the text' unless (text && text.length > 0)
+
+      response = connection.post do |request|
+        request.body = text
+        OpenCalais::HEADERS.each do |k,v|
+          request.headers[v] = opts[k] if opts.key?(k)
+        end
+      end
+      OpenCalais::Response.new(response)
+    end
+  end
+
+end

data/lib/open_calais/configuration.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+module OpenCalais
+  module Configuration
+
+    VALID_OPTIONS_KEYS = [
+      :api_key,
+      :adapter,
+      :endpoint,
+      :user_agent
+    ].freeze
+
+    # this you need to get from open calais - go register!
+    DEFAULT_API_KEY = nil
+
+    # Adapters are whatever Faraday supports - I like excon alot, so I'm defaulting it
+    DEFAULT_ADAPTER = :excon
+
+    # The api endpoint to get REST info from opencalais
+    DEFAULT_ENDPOINT = 'http://api.opencalais.com/tag/rs/enrich'.freeze
+
+    # The value sent in the http header for 'User-Agent' if none is set
+    DEFAULT_USER_AGENT = "OpenCalais Ruby Gem #{OpenCalais::VERSION}".freeze
+
+    attr_accessor *VALID_OPTIONS_KEYS
+
+    # Convenience method to allow for global setting of configuration options
+    def configure
+      yield self
+    end
+
+    def self.extended(base)
+      base.reset!
+    end
+
+    class << self
+      def keys
+        VALID_OPTIONS_KEYS
+      end
+    end
+
+    def options
+      options = {}
+      VALID_OPTIONS_KEYS.each { |k| options[k] = send(k) }
+      options
+    end
+
+    # Reset configuration options to their defaults
+    def reset!
+      self.api_key       	    = DEFAULT_API_KEY     
+      self.adapter            = DEFAULT_ADAPTER
+      self.endpoint           = DEFAULT_ENDPOINT
+      self.user_agent         = DEFAULT_USER_AGENT
+      self
+    end
+
+  end
+end

data/lib/open_calais/connection.rb

@@ -0,0 +1,57 @@
+require 'faraday_middleware'
+
+module OpenCalais
+  module Connection
+
+    ALLOWED_OPTIONS = [
+      :headers,
+      :url,
+      :params,
+      :request,
+      :ssl
+    ].freeze
+
+    def add_default_options(opts={})
+      headers = opts.delete(:headers) || {}
+      options = {
+        :headers => {
+          # generic http headers
+          'User-Agent'   => user_agent,
+          'Accept'       => "#{OpenCalais::OUTPUT_FORMATS[:json]};charset=utf-8",
+
+          # open calais default headers
+          OpenCalais::HEADERS[:license_id]                    => api_key,
+          OpenCalais::HEADERS[:content_type]                  => OpenCalais::CONTENT_TYPES[:raw],
+          OpenCalais::HEADERS[:output_format]                 => OpenCalais::OUTPUT_FORMATS[:json],
+          OpenCalais::HEADERS[:calculate_relevance_score]     => 'false',
+          OpenCalais::HEADERS[:enable_metadata_type]          => 'SocialTags',
+          OpenCalais::HEADERS[:doc_rdf_accessible]            => 'false',
+          OpenCalais::HEADERS[:omit_outputting_original_text] => 'TRUE' # case matters here, actually
+        },
+        :ssl => {:verify => false},
+        :url => endpoint
+      }.merge(opts)
+      options[:headers] = options[:headers].merge(headers)
+      options
+    end
+
+    def connection(options={})
+      opts = add_default_options(options)
+      Faraday::Connection.new(opts) do |connection|
+        connection.request :url_encoded
+        connection.response :mashify
+        connection.response :logger if ENV['DEBUG']
+
+        if opts[:headers][OpenCalais::HEADERS[:output_format]] == OpenCalais::OUTPUT_FORMATS[:json]
+          connection.response :json
+        else
+          connection.response :xml
+        end
+
+        connection.adapter(adapter)
+
+      end
+
+    end
+  end
+end

data/lib/open_calais/response.rb

@@ -0,0 +1,70 @@
+module OpenCalais
+  class Response
+    attr_accessor :raw, :language, :topics, :tags, :entities, :relations, :locations
+
+    def initialize(response)
+      @raw  = response
+
+      @language = 'English'
+      @topics    = []
+      @tags      = []
+      @entities  = []
+      @relations = []
+      @locations = []
+
+      parse(response)
+    end
+
+    def humanize_topic(topic)
+      topic.gsub('_', ' and ')
+    end
+
+    def importance_to_score(imp)
+      case imp
+      when 1 then 0.9
+      when 2 then 0.7
+      else 0.5
+      end
+    end
+
+    def parse(response)
+      r = response.body
+      @language = r.doc.meta.language rescue nil
+      @language = nil if @language == 'InputTextTooShort'
+
+      r.each do |k,v|
+        case v._typeGroup
+        when 'topics'
+          self.topics << {:name => humanize_topic(v.categoryName), :score => v.score, :original => v.categoryName}
+        when 'socialTag'
+          self.tags << {:name => v.name, :score => importance_to_score(v.importance)}
+        when 'entities'
+          item = {:guid => k, :name => v.name, :type => v._type}
+
+          instances = Array(v.instances).select{|i| i.exact.downcase != item[:name].downcase }
+          item[:matches] = instances if instances && instances.size > 0
+
+          if OpenCalais::GEO_TYPES.include?(v._type)
+            if (v.resolutions && v.resolutions.size > 0)
+              r = v.resolutions.first
+              item[:name]      = r.shortname
+              item[:latitude]  = r.latitude
+              item[:longitude] = r.longitude
+              item[:country]   = r.containedbycountry if r.containedbycountry
+              item[:state]     = r.containedbystate if r.containedbystate
+            end
+            self.locations << item
+          else
+            self.entities << item
+          end
+        when 'relations'
+          item = v.reject_if{|k,v| k[0] == '_' || k == 'instances'}
+          item[:type] = v._type
+          self.relations << item
+        end
+      end
+
+      #  remove social tags which are in the topics list already
+    end
+  end
+end

data/lib/open_calais/version.rb

@@ -0,0 +1,3 @@
+module OpenCalais
+  VERSION = "0.0.1"
+end

data/open_calais.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'open_calais/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "open_calais"
+  gem.version       = OpenCalais::VERSION
+  gem.authors       = ["Andrew Kuklewicz"]
+  gem.email         = ["andrew@prx.org"]
+  gem.summary       = %q{This is a gem to call the OpenCalais improved REST API.}
+  gem.description   = %q{This is a gem to call the OpenCalais improved REST API. http://www.opencalais.com/ http://www.opencalais.com/documentation/calais-web-service-api/api-invocation/rest}
+  gem.homepage      = "https://github.com/PRX/open_calais"
+
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_runtime_dependency('faraday', ['>= 0.7.4', '< 0.9'])
+  gem.add_runtime_dependency('faraday_middleware', '~> 0.9')
+  gem.add_runtime_dependency('multi_json', '>= 1.0.3', '~> 1.0')
+  gem.add_runtime_dependency('multi_xml')
+  gem.add_runtime_dependency('excon')
+  gem.add_runtime_dependency('hashie',  '>= 0.4.0')
+
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('minitest')
+end

data/test/client_test.rb

@@ -0,0 +1,26 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+describe OpenCalais::Client do
+
+  it "is initialized with defaults" do
+    oc = OpenCalais::Client.new
+    oc.current_options.wont_be_nil
+    oc.current_options.must_equal OpenCalais.options
+  end
+
+  it "is initialized with specific values" do
+    oc = OpenCalais::Client.new(:api_key => 'current')
+    oc.current_options.wont_be_nil
+    oc.current_options.wont_equal OpenCalais.options
+    oc.current_options[:api_key].must_equal 'current'
+    oc.api_key.must_equal 'current'
+  end
+
+  it "gets tags for text" do
+    oc = OpenCalais::Client.new(:api_key => ENV['OPEN_CALAIS_KEY'])
+    response = oc.enrich("Ruby on Rails is a fantastic web framework. It uses MVC, and the ruby programming language invented by Matz")
+    response.wont_be_nil
+    response.raw.wont_be_nil
+  end
+
+end

data/test/configuration_test.rb

@@ -0,0 +1,15 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+module TestConfig
+  extend OpenCalais::Configuration
+end
+
+describe OpenCalais::Configuration do
+
+  it "can be configured" do
+    TestConfig.configure do |c|
+      c.must_be_kind_of OpenCalais::Configuration
+    end
+  end
+
+end

data/test/open_calais_test.rb

@@ -0,0 +1,25 @@
+require File.expand_path(File.dirname(__FILE__) + '/test_helper')
+
+describe OpenCalais do
+
+  it "has default configuration options" do
+    OpenCalais.options.wont_be_nil
+    OpenCalais.options[:adapter].must_equal OpenCalais::Configuration::DEFAULT_ADAPTER
+  end
+
+  it "can be configured" do
+    OpenCalais.must_respond_to(:configure)
+
+    OpenCalais.api_key.must_be_nil
+
+    OpenCalais.configure do |c|
+      c.must_equal OpenCalais
+      c.api_key = "this is a test key"
+    end
+
+    OpenCalais.api_key.must_equal "this is a test key"
+
+    OpenCalais.options[:api_key].must_equal "this is a test key"
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+require 'minitest/spec'
+require 'minitest/autorun'
+
+require 'open_calais'

metadata

@@ -0,0 +1,207 @@
+--- !ruby/object:Gem::Specification
+name: open_calais
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andrew Kuklewicz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+    - - <
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.7.4
+    - - <
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: multi_json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.3
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.3
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: multi_xml
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This is a gem to call the OpenCalais improved REST API. http://www.opencalais.com/
+  http://www.opencalais.com/documentation/calais-web-service-api/api-invocation/rest
+email:
+- andrew@prx.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/open_calais.rb
+- lib/open_calais/client.rb
+- lib/open_calais/configuration.rb
+- lib/open_calais/connection.rb
+- lib/open_calais/response.rb
+- lib/open_calais/version.rb
+- open_calais.gemspec
+- test/client_test.rb
+- test/configuration_test.rb
+- test/open_calais_test.rb
+- test/test_helper.rb
+homepage: https://github.com/PRX/open_calais
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: This is a gem to call the OpenCalais improved REST API.
+test_files:
+- test/client_test.rb
+- test/configuration_test.rb
+- test/open_calais_test.rb
+- test/test_helper.rb
+has_rdoc: