lateral_recommender 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 30f817bfa2c49f5b662223f53679499fef6f4343
-  data.tar.gz: 4882d70fdf91115eb50ba45dc766e781853f2dac
+  metadata.gz: 6ef7a043d9d6945e21428e2afe94f637d41d9ba4
+  data.tar.gz: c527e7dca6487d9d098cf7b90851ad0e201ee5ad
 SHA512:
-  metadata.gz: eaa4b721f15177afae07bd0e651b551f97e55766b25cc5a315ac9082897298d58e83a1d2ff6d952517e18c3a68350670146e37da85035e93d43e808d0e65387b
-  data.tar.gz: 2734b5bd4b4e992d2ca9dba15d83e92ee8ce7e8362b71a7ea7730d83ef88eaba5fa7a70aa5848506fbd792eb720476a9ea939be9de59a021d9d22704117b60eb
+  metadata.gz: 9f64c85dd58161f6b912b8f2f5556c8b756341d014448bfe9b4433c591ea9d33c3f15d398594e5705108631bd1ca309554449922862ea2bdc0e733a2691e4a16
+  data.tar.gz: 8409c4294b9b381ea9b8c8f25ae0484633dab2134fbc80a8940369ca72cde6e960500a6d79e904519c3a618ca78312654816dd974c4ca10a5a544aa810bcd2d4

data/.editorconfig

@@ -0,0 +1,27 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+
+[*]
+
+# Change these settings to your own preference
+indent_style = spaces
+indent_size = 2
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.config]
+indent_style = space
+
+[*.yml]
+indent_style = space

data/.gitignore

@@ -20,4 +20,5 @@ tmp
 *.o
 *.a
 mkmf.log
-spec/env_vars.rb
+spec/env_vars.rb
+vendor/

data/.rubocop.yml

@@ -0,0 +1,21 @@
+AllCops:
+  Include:
+    - Rakefile
+    - config.ru
+  Exclude:
+    - db/**/*
+    - vendor/**/*
+    - bin/**/*
+    - lib/rack/*
+
+LineLength:
+  Max: 100
+
+RescueModifier:
+  Enabled: false
+
+AndOr:
+  Enabled: false
+
+ClassAndModuleChildren:
+  Enabled: false

data/.travis.yml

@@ -12,4 +12,4 @@ rvm:
   - jruby-19mode
 env:
   global:
-  - secure: Ri31ozxBLZ9/lzvejfgdtM9LVFdB7kKITRwCSZ9KvSKocy+msPUxND9t8G9cqr6fKU0yzSrYcGdBYP8S3SXOUI+a9Ev5UeQPU8lcZWIg9Bqe4RaIif/anKeCyamoCunReHQ9sxziVSMfg+yn0yoNS8epUA9BbBpqZDeeVMSW9qY=
+  - secure: "G2F3imFzu0RK7aRKe5UMBkjpmKxRWPfCluBQ0sHIzxcV7/haWuIgs2hh6/lA/z7HtcAvq0yPPJIzcuCenvYBgui19/TT4WeteKKtopwPwGElkXar5ch5PVee96kcwCTeQP/UNQZcdZW9AZjog2FaqKaxiKB9P+cVpkRMSRHBDjw="

data/README.md

@@ -2,27 +2,25 @@
 
 [![Build Status](https://travis-ci.org/lateral/recommender-gem.svg?branch=master)](https://travis-ci.org/lateral/recommender-gem)
 
-This is a Ruby wrapper around the [Lateral API](https://lateral.io/api). It currently supports `add` and `near_text` from the [Recommender API](https://developers.lateral.io/docs/services/546b2cc23705a70f4cd2766d/operations/546b2e053705a70f4cd2766e) and the complete (experimental) [Personalisation API](https://developers.lateral.io/docs/services/54b7f0923705a712c0f43836/operations/54b7f3753705a712c0f4383f). Over time the missing API methods will be added and this will become a fully featured wrapper around the Lateral API.
-
-*For the full API specification please see the [documentation here](https://developers.lateral.io/docs/services/).*
+This is a Ruby wrapper around the [Lateral](https://lateral.io/) [Conceptual text-matching API](https://lateral.io/docs/text-matching). At the moment it only supports [/add](https://lateral.io/docs/text-matching/api-reference#add-document-post), [/recommend-by-text](https://lateral.io/docs/text-matching/api-reference#recommend-by-text-post), [/recommend-by-id](https://lateral.io/docs/text-matching/api-reference#recommend-by-id-post) and our [pre-populated recommenders](https://lateral.io/docs/text-matching/pre-populated-recommenders). You can find the full API reference [here](https://lateral.io/docs/text-matching/api-reference).
 
 ## Installation
 
-Until the gem is more complete, it will not be available on rubygems.org. So to add it, add this line to your application's Gemfile:
+Add this line to your application's Gemfile:
 
-	gem 'lateral_recommender', github: 'lateral/recommender-gem'
+```ruby
+gem 'lateral_recommender'
+```
 
 And then execute:
 
-    $ bundle install
-
-Or you can [install it manually](https://stackoverflow.com/questions/2577346/how-to-install-gem-from-github-source).
+	$ bundle install
 
 ## Usage
 
 ### Get an API key
 
-An API key is required in order to use our API. To do this, [sign up here](https://developers.lateral.io/signup/) then visit your [profile](https://developers.lateral.io/developer) and click 'Show' next to where it says `Primary key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`.
+An API key is required in order to use our API. To do this go to our [docs page](https://lateral.io/docs) and click the 'Get Access' button in the top right. Choose the 'Conceptual text-matcher' API and you'll get emailed details of how to get your key.
 
 ### Use the API
 
@@ -32,6 +30,8 @@ Initialize `LateralRecommender` with your API key by running:
 api = LateralRecommender::API.new YOUR_API_KEY
 ```
 
+#### Add a document
+
 To add a document to the API call:
 
 ```ruby
@@ -40,69 +40,58 @@ api.add document_id: 'document_id', text: 'document text'
 
 Please be aware that if you don't send enough meaningful text the API will return an error. So please ensure there is at least 100 or so words in the document you're adding.
 
-To get recommendations for some text, use `near_text`:
+#### Recommend by text
+
+To get recommendations for some text, use `recommend_by_text`:
 
 ```ruby
-api.near_text 'document text'
+api.recommend_by_text 'document text'
 ```
 
-To get recommendations for a document that's in the API, use `near_id`:
+#### Recommend by ID
+
+To get recommendations for a document that's in the API, use `recommend_by_id`:
 
 ```ruby
-api.near_id 'document_id'
+api.recommend_by_id 'document_id'
 ```
-
 This returns an array of Hashes containing a `document_id` and `distance`.
 
-#### Querying our pre-populated data
+#### Pre-populated recommenders
 
-If you don't want to insert your own documents to the API, you can query one of our pre-filled data sets:
+If you don't want to insert your own documents to the API, you can query one of our pre-populated recommenders:
 
-* **[Movies](https://www.freebase.com/film/film?instances)** (experimental) - Movies listed on [Freebase](https://www.freebase.com/) with plots from [Wikipedia](https://en.wikipedia.org)
-* **News** (experimental) - News from multiple outlets updated every 15 minutes
-* **[arXiv](http://arxiv.org/)** - Academic papers in Physics, Mathematics, Computer Science, Quantitative Biology, Quantitative Finance and Statistics
-* **[PubMed](http://www.ncbi.nlm.nih.gov/pubmed)** - Medical journals
-* **[Wikipedia](https://en.wikipedia.org)** - General knowledge
+* **[arXiv](https://lateral.io/docs/text-matching/pre-populated-recommenders#arxiv)** - 1M+ academic papers in Physics, Mathematics and Computer Science (updated daily)
+* **[News](https://lateral.io/docs/text-matching/pre-populated-recommenders#news)** - 250,000+ curated news articles (updated every 15mins)
+* **[PubMed](https://lateral.io/docs/text-matching/pre-populated-recommenders#pubmed)** - Medical journals
+* **[SEC Data](https://lateral.io/docs/text-matching/pre-populated-recommenders#sec-data)** - 6,000+ yearly financial reports / 10-K filings (from 2014)
+* **[Wikipedia](https://lateral.io/docs/text-matching/pre-populated-recommenders#wikipedia)** - 463,000 Wikipedia pages (which had 20+ page views in 2013)
 
-To use these, simply initialize `LateralRecommender` with a second argument containing the corpus:
+To use one of these, initialize `LateralRecommender` with a second argument containing the corpus:
 
 ```ruby
 api = LateralRecommender::API.new YOUR_API_KEY, 'news'
 ```
 
-The available values are `movies`, `news`, `arxiv`, `pubmed` or `wikipedia`. We plan to add more in the near future.
-
-Now you can query the API using `near_text` or `near_user` without the need for populating the API with your own content:
-
-```ruby
-api.near_text 'document text'
-```
-
-#### Managing users
-
-A feature of the API is to be able to add a representation of a user. The user is able to have many documents and when querying the API for recommendations you can specify the user and each of these documents will be used to get recommendations for that user.
-
-*Note: This is an experimental feature of the API*
-
-To add a user:
+The available values are `arxiv`, `news`, `pubmed`, `sec` or `wikipedia`. These allow you to query the recommender using `recommend_by_text` or `recommend_by_id` without the need for adding your own documents. By text:
 
 ```ruby
-api.add_user 'user_id'
+api.recommend_by_text 'document text'
 ```
 
-To add a document to that user:
+Or with a document ID:
 
 ```ruby
-api.add_user_document 'user_id', 'document_id', 'document text'
+api.recommend_by_id 'arxiv-http://arxiv.org/abs/1403.2165'
 ```
 
-You can do this as many times as you want to build a more complete picture of the user. Then, to query for recommendations for that user:
+Note: For the SEC data, you need to set a collections array:
 
 ```ruby
-api.near_user 'user_id'
+api.recommend_by_text 'document text', collections: '["item1a"]'
 ```
 
-The response will be the same format as a `near_text`.
+Read the [Pre-populated-recommenders documentation](https://lateral.io/docs/text-matching/pre-populated-recommenders#top) for more.
 
 ## Contributing
 
@@ -115,4 +104,4 @@ The response will be the same format as a `near_text`.
 
 ### Testing
 
-To test the gem, run `bundle exec rspec`. Note: your API key must be un-used.
+To test the gem, run `bundle exec rspec`. Note: your API key must be un-used.

data/lateral_recommender.gemspec

@@ -16,15 +16,13 @@ Gem::Specification.new do |spec|
   spec.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'awesome_print'
-  spec.add_development_dependency 'bundler', '~> 1.6'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'vcr'
-  spec.add_development_dependency 'webmock'
-  spec.add_development_dependency 'yard'
+  spec.add_development_dependency 'awesome_print', '~> 1.6', '>= 1.6.1'
+  spec.add_development_dependency 'rake', '~> 10.4', '>= 10.4.2'
+  spec.add_development_dependency 'rspec', '~> 3.2', '>= 3.2.0'
+  spec.add_development_dependency 'vcr', '~> 2.9', '>= 2.9.3'
+  spec.add_development_dependency 'webmock', '~> 1.21', '>= 1.21.0'
+  spec.add_development_dependency 'yard', '~> 0.8', '>= 0.8.7.6'
 
-  spec.add_runtime_dependency 'httpclient'
-  spec.add_runtime_dependency 'json'
-  spec.add_runtime_dependency 'activesupport'
+  spec.add_runtime_dependency 'httparty', '~> 0.13', '>= 0.13.4'
+  spec.add_runtime_dependency 'json', '~> 1.8', '>= 1.8.2'
 end

data/lib/lateral_recommender/version.rb

@@ -1,3 +1,3 @@
 module LateralRecommender
-  VERSION = "0.0.2"
+  VERSION = '0.0.3'
 end

data/lib/lateral_recommender.rb

@@ -1,17 +1,18 @@
 require 'lateral_recommender/version'
-require 'httpclient'
-require 'active_support/core_ext/hash'
+require 'httparty'
 require 'json'
 
 module LateralRecommender
   class API
+    EXTERNAL_CORPORA = %w(arxiv news pubmed sec wikipedia)
+
     # @param [String] key The Lateral API key
-    # @param [String] corpora The corpora to recommend from e.g. movies, news, wikipedia, arxiv or pubmed
-    def initialize(key, corpora = 'recommender')
-      @corpora = %w(movies news wikipedia arxiv pubmed).include?(corpora) ? "collections/#{corpora}" : corpora
-      @uri = 'https://api.lateral.io/'
+    # @param [String] corpus The corpora to recommend from e.g. arxiv, sec, pubmed, wikipedia, news
+    def initialize(key, corpus = 'recommender')
+      corpus = EXTERNAL_CORPORA.include?(corpus) ? corpus : 'recommender'
+      @endpoint = "https://#{corpus}-api.lateral.io/"
       @key = key
-      @client = HTTPClient.new
+      # @client = HTTPClient.new
     end
 
     # Add a document to the recommender
@@ -22,7 +23,7 @@ module LateralRecommender
     # @option params [String] :meta A JSON object containing any metadata
     # @return [Hash] the document object that was added.
     def add(params)
-      post "#{@corpora}/add", params.stringify_keys
+      post 'add', params
     end
 
     # Get recommendations for the provided text
@@ -32,107 +33,19 @@ module LateralRecommender
     # @option opts [Integer] :results (20) How many results to return
     # @option opts [Array] :select_from An array of IDs to return results from
     # @return [Array] An array of Hashes containing the recommendations
-    def near_text(text, opts = {})
-      post "#{@corpora}/recommend", { text: text }.merge(opts)
+    def recommend_by_text(text, opts = {})
+      post 'recommend-by-text', { text: text }.merge(opts)
     end
 
     # Get recommendations for the provided id
     #
-    # @param [String] text The ID of the document to get recommendations for.
-    # @param [Hash] opts Additional options for the request.
-    # @option opts [Integer] :results (20) How many results to return
-    # @option opts [Array] :select_from An array of IDs to return results from
-    # @return [Array] An array of Hashes containing the recommendations
-    def near_id(id, opts = {})
-      post "#{@corpora}/recommend", { document_id: id }.merge(opts)
-    end
-
-    # Get recommendations for the provided text
-    #
-    # @param [String] id The ID of the user to return recommendations for
+    # @param [String] id The ID of the document to get recommendations for.
     # @param [Hash] opts Additional options for the request.
     # @option opts [Integer] :results (20) How many results to return
     # @option opts [Array] :select_from An array of IDs to return results from
     # @return [Array] An array of Hashes containing the recommendations
-    def near_user(id, opts = {})
-      if @corpora != 'recommender'
-        opts = opts.merge corpus: @corpora.gsub('collections/', '')
-      end
-      post 'personalisation/recommend', { user_id: id }.merge(opts)
-    end
-
-    # Get all users
-    #
-    # @return [Array] An array of all user Hashes
-    def users
-      get 'personalisation/users'
-    end
-
-    # Get one user
-    #
-    # @param [String] id The ID of the user to return
-    # @return [Hash] A user Hash
-    def get_user(id)
-      get 'personalisation/users', id: id
-    end
-
-    # Add a user
-    #
-    # @param [String] id The ID of the user to add
-    # @return [Hash] The user Hash
-    def add_user(id)
-      post 'personalisation/users', id: id
-    end
-
-    # Delete a user
-    #
-    # @param [String] id The ID of the user to add
-    # @return [Hash] The user Hash
-    def delete_user(id)
-      delete 'personalisation/users', id: id
-    end
-
-    # Get all user documents
-    #
-    # @return [Array] An array of all document Hashes
-    def user_documents
-      get 'personalisation/documents'
-    end
-
-    # Get all user documents for a specified user
-    #
-    # @param [String] user_id The ID of the user
-    # @return [Array] An array of document Hashes that belong to the user
-    def user_documents(user_id)
-      get 'personalisation/documents/by-user', user_id: user_id
-    end
-
-    # Get one document that belongs to a specified user
-    #
-    # @param [String] user_id The ID of the user
-    # @param [String] document_id The ID of the document
-    # @return [Hash] An document Hash
-    def user_document(user_id, document_id)
-      get 'personalisation/documents/by-id', user_id: user_id, id: document_id
-    end
-
-    # Add a document to a user
-    #
-    # @param [String] user_id The ID of the user
-    # @param [String] document_id The ID of the document
-    # @param [String] body The contents of the document
-    # @return [Hash] The documents Hash
-    def add_user_document(user_id, document_id, body, opts = {})
-      post 'personalisation/documents', { user_id: user_id, id: document_id, body: body }.merge(opts)
-    end
-
-    # Delete a users document
-    #
-    # @param [String] user_id The ID of the user
-    # @param [String] document_id The ID of the document
-    # @return [Hash] The documents Hash
-    def delete_user_document(user_id, document_id)
-      delete 'personalisation/documents', user_id: user_id, id: document_id
+    def recommend_by_id(id, opts = {})
+      post 'recommend-by-id', { document_id: id }.merge(opts)
     end
 
     # Takes two result arrays and using the specified key merges the two
@@ -152,31 +65,26 @@ module LateralRecommender
     private
 
     def req(request)
-      return { error: error(request) } if request.status != 200 && request.status != 201
+      return { error: error(request) } if request.code != 200 && request.code != 201
       JSON.parse(request.body)
     end
 
     def error(request)
-      begin
-        message = JSON.parse(request.body)['message']
-      rescue
-        message = request.header.reason_phrase
-      end
-      return { status_code: request.status } unless message
-      { status_code: request.status, message: message }
+      { status_code: request.code, message: JSON.parse(request.body)['message'] }
+    rescue JSON::ParserError
+      { status_code: request.code }
     end
 
     def url(path)
-      "#{@uri}#{path}/?subscription-key=#{@key}"
+      "#{@endpoint}#{path}/?subscription-key=#{@key}"
     end
 
     def post(path, params)
-      req @client.post url(path), params.stringify_keys
+      req HTTParty.post url(path), body: params
     end
 
     def get(path, params)
-      req @client.get url(path), params.stringify_keys
+      req HTTParty.get url(path), body: params
     end
   end
 end
-