lateral_recommender 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 651c7824ece60aa76af16f0db48e5a91969debba
-  data.tar.gz: 50232352c637633cd16e18dc3838b8e649949d25
+  metadata.gz: 30f817bfa2c49f5b662223f53679499fef6f4343
+  data.tar.gz: 4882d70fdf91115eb50ba45dc766e781853f2dac
 SHA512:
-  metadata.gz: d8b5a35a8c26b2fc30ed22173f6361755f23790ad27cd4dbe0cc37d9f5e44ac87b7821f78aafd28173d9449d33b30650b1721bc526cfa7d22d479aaf93b745ad
-  data.tar.gz: fb5f55f3a930690ee9ca0937c45cc0f27ce1d918d25f01cea3c87c1c0ea5d9c7b6ff443a38bc19d8aae8f13c415a3f392b1b9845f25ad4452234da49d9a0ee4a
+  metadata.gz: eaa4b721f15177afae07bd0e651b551f97e55766b25cc5a315ac9082897298d58e83a1d2ff6d952517e18c3a68350670146e37da85035e93d43e808d0e65387b
+  data.tar.gz: 2734b5bd4b4e992d2ca9dba15d83e92ee8ce7e8362b71a7ea7730d83ef88eaba5fa7a70aa5848506fbd792eb720476a9ea939be9de59a021d9d22704117b60eb

data/.rspec

@@ -0,0 +1 @@
+--color --format d --fail-fast --tty

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.1.1
+  - 2.1.2
+  - 2.1.3
+  - 2.1.4
+  - 2.1.5
+  - 2.2.0
+  - jruby-19mode
+env:
+  global:
+  - secure: Ri31ozxBLZ9/lzvejfgdtM9LVFdB7kKITRwCSZ9KvSKocy+msPUxND9t8G9cqr6fKU0yzSrYcGdBYP8S3SXOUI+a9Ev5UeQPU8lcZWIg9Bqe4RaIif/anKeCyamoCunReHQ9sxziVSMfg+yn0yoNS8epUA9BbBpqZDeeVMSW9qY=

data/README.md

@@ -1,22 +1,22 @@
 # LateralRecommender
 
+[![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/).*
 
 ## Installation
 
-Add this line to your application's Gemfile:
+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:
 
-	gem 'lateral_recommender'
+	gem 'lateral_recommender', github: 'lateral/recommender-gem'
 
 And then execute:
 
-    $ bundle
-
-Or install it yourself as:
+    $ bundle install
 
-    $ gem install lateral_recommender
+Or you can [install it manually](https://stackoverflow.com/questions/2577346/how-to-install-gem-from-github-source).
 
 ## Usage
 
@@ -37,16 +37,22 @@ To add a document to the API call:
 ```ruby
 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 a document, use `near_text`:
+To get recommendations for some text, use `near_text`:
+
+```ruby
+api.near_text 'document text'
+```
+
+To get recommendations for a document that's in the API, use `near_id`:
 
 ```ruby
-api.near_text text: 'document text'
+api.near_id 'document_id'
 ```
-	
-This returns an array of Hashes containing a `document_id` and `distance`. 
+
+This returns an array of Hashes containing a `document_id` and `distance`.
 
 #### Querying our pre-populated data
 
@@ -63,15 +69,15 @@ To use these, simply initialize `LateralRecommender` with a second argument cont
 ```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 text: 'document text'
+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.
@@ -83,13 +89,13 @@ To add a user:
 ```ruby
 api.add_user 'user_id'
 ```
-	
+
 To add a document to that user:
-	
+
 ```ruby
 api.add_user_document 'user_id', 'document_id', 'document text'
 ```
-	
+
 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:
 
 ```ruby
@@ -106,3 +112,7 @@ The response will be the same format as a `near_text`.
 4. Commit your changes (`git commit -am 'Add some feature'`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
+
+### Testing
+
+To test the gem, run `bundle exec rspec`. Note: your API key must be un-used.

data/lateral_recommender.gemspec

@@ -12,9 +12,6 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/lateral/recommender-gem'
   spec.license       = 'MIT'
 
-  # spec.files         = `git ls-files -z`.split("')
-  # spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
-  # spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
   spec.files = `git ls-files`.split("\n")
   spec.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
   spec.require_paths = ['lib']
@@ -28,5 +25,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard'
 
   spec.add_runtime_dependency 'httpclient'
+  spec.add_runtime_dependency 'json'
   spec.add_runtime_dependency 'activesupport'
 end

data/lib/lateral_recommender/version.rb

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

data/lib/lateral_recommender.rb

@@ -1,5 +1,7 @@
 require 'lateral_recommender/version'
+require 'httpclient'
 require 'active_support/core_ext/hash'
+require 'json'
 
 module LateralRecommender
   class API
@@ -34,6 +36,17 @@ module LateralRecommender
       post "#{@corpora}/recommend", { 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

data/spec/fixtures/tapes/add.yml

@@ -12,7 +12,7 @@ http_interactions:
       Accept:
       - '*/*'
       Date:
-      - Thu, 22 Jan 2015 12:10:15 GMT
+      - Thu, 05 Feb 2015 15:36:52 GMT
       Content-Type:
       - application/x-www-form-urlencoded
   response:
@@ -27,7 +27,7 @@ http_interactions:
       Server:
       - Microsoft-HTTPAPI/2.0
       Date:
-      - Thu, 22 Jan 2015 12:10:14 GMT
+      - Thu, 05 Feb 2015 15:37:01 GMT
     body:
       encoding: UTF-8
       string: '{"text": "Space exploration\nJump to: navigation , search\nSaturn V
@@ -508,8 +508,8 @@ http_interactions:
         with strong arguments both for and against. In particular, the making of national
         territorial claims in outer space and on celestial bodies has been specifically
         proscribed by the Outer Space Treaty , which had been, as of 2012 [update]
-        , ratified by all spacefaring nations . [46]", "created_at": "2015-01-22 12:08:28.488731",
+        , ratified by all spacefaring nations . [46]", "created_at": "2015-02-05 15:34:54.829682",
         "meta": "{}", "document_id": "doc_id"}'
     http_version: 
-  recorded_at: Thu, 22 Jan 2015 12:10:15 GMT
+  recorded_at: Thu, 05 Feb 2015 15:37:01 GMT
 recorded_with: VCR 2.9.3

data/spec/fixtures/tapes/add_user.yml

@@ -12,7 +12,7 @@ http_interactions:
       Accept:
       - '*/*'
       Date:
-      - Thu, 22 Jan 2015 12:13:03 GMT
+      - Thu, 05 Feb 2015 15:40:04 GMT
       Content-Type:
       - application/x-www-form-urlencoded
   response:
@@ -27,7 +27,7 @@ http_interactions:
       Content-Type:
       - application/json
       Etag:
-      - '"daea56294f0589e4a280ebcc12be18b2"'
+      - '"56d7ecacdee0e66f4ae2f2067dda5eab"'
       Vary:
       - Accept-Encoding
       Server:
@@ -41,16 +41,16 @@ http_interactions:
       Strict-Transport-Security:
       - max-age=31536000
       X-Request-Id:
-      - 9d65956e-3ca2-43ef-88cd-b61bdd86c7a2
+      - 9c7a3ee4-4c84-4655-ad1d-a8d4dc4fed0b
       X-Runtime:
-      - '0.020783'
+      - '0.035732'
       X-Powered-By:
       - Phusion Passenger 4.0.37
       Date:
-      - Thu, 22 Jan 2015 12:13:03 GMT
+      - Thu, 05 Feb 2015 15:40:04 GMT
     body:
       encoding: UTF-8
-      string: '{"id":"user_id","created_at":"2015-01-22T12:13:04.002Z","updated_at":"2015-01-22T12:13:04.002Z"}'
+      string: '{"id":"user_id","created_at":"2015-02-05T15:40:04.608Z","updated_at":"2015-02-05T15:40:04.608Z"}'
     http_version: 
-  recorded_at: Thu, 22 Jan 2015 12:13:04 GMT
+  recorded_at: Thu, 05 Feb 2015 15:40:04 GMT
 recorded_with: VCR 2.9.3

data/spec/fixtures/tapes/add_user_document.yml

@@ -12,7 +12,7 @@ http_interactions:
       Accept:
       - '*/*'
       Date:
-      - Thu, 22 Jan 2015 12:14:05 GMT
+      - Thu, 05 Feb 2015 15:40:05 GMT
       Content-Type:
       - application/x-www-form-urlencoded
   response:
@@ -27,7 +27,7 @@ http_interactions:
       Content-Type:
       - application/json
       Etag:
-      - '"821bf1908831fbb56e28280c8567bb43"'
+      - '"d522edd6b0412c73293c1e57b1a3cc10"'
       Vary:
       - Accept-Encoding
       Server:
@@ -41,13 +41,13 @@ http_interactions:
       Strict-Transport-Security:
       - max-age=31536000
       X-Request-Id:
-      - 2e731b72-640e-417a-9b33-febd72986af9
+      - 14df8fdc-4b6e-48f1-9c86-797e08d0e6f6
       X-Runtime:
-      - '0.486240'
+      - '0.791947'
       X-Powered-By:
       - Phusion Passenger 4.0.37
       Date:
-      - Thu, 22 Jan 2015 12:14:05 GMT
+      - Thu, 05 Feb 2015 15:40:06 GMT
     body:
       encoding: ASCII-8BIT
       string: !binary |-
@@ -873,7 +873,7 @@ http_interactions:
         bHkgcHJvc2NyaWJlZCBieSB0aGUgT3V0ZXIgU3BhY2UgVHJlYXR5ICwgd2hp
         Y2ggaGFkIGJlZW4sIGFzIG9mIDIwMTIgW3VwZGF0ZV0gLCByYXRpZmllZCBi
         eSBhbGwgc3BhY2VmYXJpbmcgbmF0aW9ucyAuIFs0Nl1cbiIsInRpbWUiOiIy
-        MDE1LTAxLTIyVDEyOjE0OjA2LjQ1MVoifQ==
+        MDE1LTAyLTA1VDE1OjQwOjA2LjI2NloifQ==
     http_version: 
-  recorded_at: Thu, 22 Jan 2015 12:14:06 GMT
+  recorded_at: Thu, 05 Feb 2015 15:40:07 GMT
 recorded_with: VCR 2.9.3

data/spec/fixtures/tapes/invalid_key.yml

@@ -5,14 +5,14 @@ http_interactions:
     uri: https://api.lateral.io/recommender/recommend/?subscription-key=no
     body:
       encoding: UTF-8
-      string: text=%7B%3Atext%3D%3E%22test%22%7D
+      string: text=test
     headers:
       User-Agent:
       - HTTPClient/1.0 (2.6.0.1, ruby 2.0.0 (2014-02-24))
       Accept:
       - '*/*'
       Date:
-      - Thu, 22 Jan 2015 12:08:48 GMT
+      - Thu, 05 Feb 2015 10:19:06 GMT
       Content-Type:
       - application/x-www-form-urlencoded
   response:
@@ -27,12 +27,12 @@ http_interactions:
       Server:
       - Microsoft-HTTPAPI/2.0
       Date:
-      - Thu, 22 Jan 2015 12:08:48 GMT
+      - Thu, 05 Feb 2015 10:19:06 GMT
     body:
       encoding: UTF-8
       string: '{ "statusCode": 401, "message": "Access denied due to invalid subscription
         key. Make sure you are subscribed to an API you are trying to call and provide
         the right key." }'
     http_version: 
-  recorded_at: Thu, 22 Jan 2015 12:08:49 GMT
+  recorded_at: Thu, 05 Feb 2015 10:19:06 GMT
 recorded_with: VCR 2.9.3

data/spec/fixtures/tapes/near_id.yml

@@ -0,0 +1,47 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.lateral.io/recommender/recommend/?subscription-key=<API_KEY>
+    body:
+      encoding: UTF-8
+      string: document_id=doc_id
+    headers:
+      User-Agent:
+      - HTTPClient/1.0 (2.6.0.1, ruby 2.0.0 (2014-02-24))
+      Accept:
+      - '*/*'
+      Date:
+      - Thu, 05 Feb 2015 15:39:26 GMT
+      Content-Type:
+      - application/x-www-form-urlencoded
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Content-Length:
+      - '952'
+      Content-Type:
+      - application/json; charset=utf-8
+      Server:
+      - Microsoft-HTTPAPI/2.0
+      Date:
+      - Thu, 05 Feb 2015 15:39:27 GMT
+    body:
+      encoding: UTF-8
+      string: '[{"distance": 0.000248, "document_id": "doc_id"}, {"distance": 0.03849,
+        "document_id": "16400"}, {"distance": 0.043243, "document_id": "21299"}, {"distance":
+        0.043754, "document_id": "6824"}, {"distance": 0.043945, "document_id": "11689"},
+        {"distance": 0.045342, "document_id": "433"}, {"distance": 0.045867, "document_id":
+        "8403"}, {"distance": 0.046243, "document_id": "13882"}, {"distance": 0.046285,
+        "document_id": "1391"}, {"distance": 0.046396, "document_id": "15333"}, {"distance":
+        0.046684, "document_id": "4236"}, {"distance": 0.046794, "document_id": "8443"},
+        {"distance": 0.047875, "document_id": "2422"}, {"distance": 0.048303, "document_id":
+        "22543"}, {"distance": 0.048475, "document_id": "11235"}, {"distance": 0.048584,
+        "document_id": "17475"}, {"distance": 0.049252, "document_id": "17266"}, {"distance":
+        0.049315, "document_id": "26815"}, {"distance": 0.049454, "document_id": "30270"},
+        {"distance": 0.049636, "document_id": "17836"}]'
+    http_version: 
+  recorded_at: Thu, 05 Feb 2015 15:39:27 GMT
+recorded_with: VCR 2.9.3

data/spec/fixtures/tapes/near_id_arxiv.yml

@@ -0,0 +1,68 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.lateral.io/collections/arxiv/recommend/?subscription-key=<API_KEY>
+    body:
+      encoding: UTF-8
+      string: document_id=arxiv-http%3A%2F%2Farxiv.org%2Fabs%2F1403.2165
+    headers:
+      User-Agent:
+      - HTTPClient/1.0 (2.6.0.1, ruby 2.0.0 (2014-02-24))
+      Accept:
+      - '*/*'
+      Date:
+      - Thu, 05 Feb 2015 15:55:22 GMT
+      Content-Type:
+      - application/x-www-form-urlencoded
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Content-Length:
+      - '2823'
+      Content-Type:
+      - application/json; charset=utf-8
+      Server:
+      - Microsoft-HTTPAPI/2.0
+      Date:
+      - Thu, 05 Feb 2015 15:55:23 GMT
+    body:
+      encoding: UTF-8
+      string: '[{"distance": 0.0, "title": "Set-valued sorting index and joint equidistributions",
+        "url": "http://arxiv.org/abs/1403.2165", "authors": ["Eu, Sen-Pen", "Lo, Yuan-Hsun",
+        "Wong, Tsai-Lien"], "date": "2015-02-05", "document_id": "arxiv-http://arxiv.org/abs/1403.2165"},
+        {"distance": 0.143046, "title": "The sorting index and set-valued joint equidistributions
+        of   $\\mathcal{B}_n$ and $\\mathcal{D}_n$", "url": "http://arxiv.org/abs/1403.2169",
+        "authors": ["Eu, Sen-Peng", "Lo, Yuan-Hsun", "Wong, Tsai-Lien"], "date": "2015-02-05",
+        "document_id": "arxiv-http://arxiv.org/abs/1403.2169"}, {"distance": 0.387619,
+        "title": "Creature forcing and five cardinal characteristics in Cicho\\''{n}''s   diagram",
+        "url": "http://arxiv.org/abs/1402.0367", "authors": ["Fischer, Arthur", "Goldstern,
+        Martin", "Kellner, Jakob", "Shelah, Saharon"], "date": "2015-02-05", "document_id":
+        "arxiv-http://arxiv.org/abs/1402.0367"}, {"distance": 0.47352, "title": "Corpus-based
+        Web Document Summarization using Statistical and Linguistic   Approach", "url":
+        "http://arxiv.org/abs/1304.2476", "authors": ["Hashem, M. M. A.", "Gope, Monika",
+        "Akter, Suraiya Rumana", "Shams, Rushdi", "Hossain, Afrina"], "date": "2015-02-05",
+        "document_id": "arxiv-http://arxiv.org/abs/1304.2476"}, {"distance": 0.485755,
+        "title": "Text as Statistical Mechanics Object", "url": "http://arxiv.org/abs/0810.3416",
+        "authors": ["Korutcheva, E.", "Koroutchev, K."], "date": "2015-02-05", "document_id":
+        "arxiv-http://arxiv.org/abs/0810.3416"}, {"distance": 0.491576, "title": "Text
+        Classification using Artificial Intelligence", "url": "http://arxiv.org/abs/1009.4964",
+        "authors": ["Kamruzzaman, S. M."], "date": "2015-02-05", "document_id": "arxiv-http://arxiv.org/abs/1009.4964"},
+        {"distance": 0.497958, "title": "Text Classification using Data Mining", "url":
+        "http://arxiv.org/abs/1009.4987", "authors": ["Hasan, Ahmed Ryadh", "Haider,
+        Farhana", "Kamruzzaman, S. M."], "date": "2015-02-05", "document_id": "arxiv-http://arxiv.org/abs/1009.4987"},
+        {"distance": 0.504628, "title": "Artex is AnotheR TEXt summarizer", "url":
+        "http://arxiv.org/abs/1210.3312", "authors": ["Torres-Moreno, Juan-Manuel"],
+        "date": "2015-02-05", "document_id": "arxiv-http://arxiv.org/abs/1210.3312"},
+        {"distance": 0.508608, "title": "Text Classification using Association Rule
+        with a Hybrid Concept of   Naive Bayes Classifier and Genetic Algorithm",
+        "url": "http://arxiv.org/abs/1009.4976", "authors": ["Hasan, Ahmed Ryadh",
+        "Haider, Farhana", "Kamruzzaman, S. M."], "date": "2015-02-05", "document_id":
+        "arxiv-http://arxiv.org/abs/1009.4976"}, {"distance": 0.516115, "title": "Comparative
+        Discourse Analysis of Parallel Texts", "url": "http://arxiv.org/abs/cmp-lg/9407022",
+        "authors": ["van der Eijk, Pim"], "date": "2015-02-05", "document_id": "arxiv-http://arxiv.org/abs/cmp-lg/9407022"}]'
+    http_version: 
+  recorded_at: Thu, 05 Feb 2015 15:55:23 GMT
+recorded_with: VCR 2.9.3