predictionio 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a0cd7b4e99c6db76f57ca47d07b96c3c53820e8
-  data.tar.gz: d46e42deee2a425b7fdd9bc77f146ef6ed722a21
+  metadata.gz: dc02d867a2b406fd1b936187c0cc13a3ca3352cb
+  data.tar.gz: 4b29fa04ca835cfe1294080f3f40e3d5a83b6af4
 SHA512:
-  metadata.gz: 39451eb1e6eb960b0213d88e3f3c46b6f6ba99117ad2be4c012e63451c6a993d53520535703c015db0c2043948bd1b23d5b9e80f7c54423723cd37bc8e416923
-  data.tar.gz: 1c5e961a5933288e91af6616cd53376811dc5d4b62f27b469e6fa929f138cc5748a0fd9618ab117d29db228103f4d352d7055164bffdfd07b5f3c746a44fba7d
+  metadata.gz: fd0f40e0dcf0492fbb2c74af5c104ccd07d66832a416bb39fec3ed52525bddbf8636a0879f9034b7d489832747aa10fd3b6f6206e88d36c4f047c4e470caca83
+  data.tar.gz: 934022684046923e653e5f13ae6ce395c6e921f60242a36d221d69689f39e93e7958f416d6585d46fd9e482ddf1874781e935fe986e5e53941f0a271045b98bb

data/lib/predictionio.rb

@@ -1 +1,38 @@
-require "predictionio/client"
+require 'predictionio/client'
+require 'predictionio/event_client'
+require 'predictionio/engine_client'
+
+# The PredictionIO module contains classes that provide convenient access of
+# PredictionIO Event API and Engine Instance over HTTP/HTTPS.
+#
+# To create an app and perform predictions, please download the PredictionIO
+# suite from http://prediction.io.
+#
+# Most functionality is provided by PredictionIO::EventClient and
+# PredictionIO::EngineClient classes.
+#
+# == Deprecation Notice
+#
+# Pre-0.7.x series support is now deprecated. All existing users are strongly
+# encouraged to migrate to 0.8.x.
+#
+# The old Client interface is retained in case of any accidental Gem upgrade.
+# It will be removed in the next minor version.
+#
+# == High-performance Asynchronous Backend
+#
+# All REST request methods come in both synchronous and asynchronous flavors.
+# Both flavors accept the same set of arguments. In addition, all synchronous
+# request methods can instead accept a PredictionIO::AsyncResponse object
+# generated from asynchronous request methods as its first argument. In this
+# case, the method will block until a response is received from it.
+#
+# Any network reconnection and request retry is automatically handled in the
+# background. Exceptions will be thrown after a request times out to avoid
+# infinite blocking.
+#
+# == Installation
+# The easiest way is to use RubyGems:
+#     gem install predictionio
+module PredictionIO
+end

data/lib/predictionio/async_request.rb

@@ -1,5 +1,6 @@
 module PredictionIO
-  # This class contains the URI path and query parameters that is consumed by PredictionIO::Connection for asynchronous HTTP requests.
+  # This class contains the URI path and query parameters that is consumed by
+  # PredictionIO::Connection for asynchronous HTTP requests.
   class AsyncRequest
 
     # The path portion of the request URI.
@@ -8,7 +9,8 @@ module PredictionIO
     # Query parameters, or form data.
     attr_reader :params
 
-    # Populates the package with request URI path, and optionally query parameters or form data.
+    # Populates the package with request URI path, and optionally query
+    # parameters or form data.
     def initialize(path, params = {})
       @params = params
       @path = path

data/lib/predictionio/client.rb

@@ -11,13 +11,7 @@ require 'predictionio/async_request'
 require 'predictionio/async_response'
 require 'predictionio/connection'
 
-# The PredictionIO module contains classes that provide convenient access of the PredictionIO output API over HTTP/HTTPS.
-#
-# To create an app and perform predictions, please download the PredictionIO suite from http://prediction.io.
-#
-# Most functionality is provided by the PredictionIO::Client class.
 module PredictionIO
-
   # This class contains methods that access PredictionIO via REST requests.
   #
   # Many REST request methods support optional arguments.
@@ -505,8 +499,8 @@ module PredictionIO
     # See #aget_itemrec_top_n for a description of special argument handling.
     #
     # call-seq:
-    # aget_itemrec_top_n(engine, n, params = {})
-    # aget_itemrec_top_n(async_response)
+    # get_itemrec_top_n(engine, n, params = {})
+    # get_itemrec_top_n(async_response)
     def get_itemrec_top_n(*args)
       uid_or_res = args[0]
       if uid_or_res.is_a?(PredictionIO::AsyncResponse)
@@ -565,8 +559,8 @@ module PredictionIO
     # See #aget_itemrank_ranked for a description of special argument handling.
     #
     # call-seq:
-    # aget_itemrank_ranked(engine, n, params = {})
-    # aget_itemrank_ranked(async_response)
+    # get_itemrank_ranked(engine, n, params = {})
+    # get_itemrank_ranked(async_response)
     def get_itemrank_ranked(*args)
       uid_or_res = args[0]
       if uid_or_res.is_a?(PredictionIO::AsyncResponse)
@@ -633,8 +627,8 @@ module PredictionIO
     # See #aget_itemsim_top_n for a description of special argument handling.
     #
     # call-seq:
-    # aget_itemsim_top_n(engine, iid, n, params = {})
-    # aget_itemsim_top_n(async_response)
+    # get_itemsim_top_n(engine, iid, n, params = {})
+    # get_itemsim_top_n(async_response)
     def get_itemsim_top_n(*args)
       uid_or_res = args[0]
       if uid_or_res.is_a?(PredictionIO::AsyncResponse)

data/lib/predictionio/connection.rb

@@ -34,29 +34,34 @@ module PredictionIO
                   request = package[:request]
                   response = package[:response]
                   case package[:method]
-                  when "get"
+                  when 'get'
                     http_req = Net::HTTP::Get.new("#{uri.path}#{request.qpath}")
                     begin
                       response.set(http.request(http_req))
                     rescue Exception => details
                       response.set(details)
                     end
-                  when "post"
-                    http_req = Net::HTTP::Post.new("#{uri.path}#{request.path}")
-                    http_req.set_form_data(request.params)
+                  when 'post'
+                    if request.params.is_a?(Hash)
+                      http_req = Net::HTTP::Post.new("#{uri.path}#{request.path}")
+                      http_req.set_form_data(request.params)
+                    else
+                      http_req = Net::HTTP::Post.new("#{uri.path}#{request.path}", initheader = {'Content-Type' => 'application/json'})
+                      http_req.body = request.params
+                    end
                     begin
                       response.set(http.request(http_req))
                     rescue Exception => details
                       response.set(details)
                     end
-                  when "delete"
+                  when 'delete'
                     http_req = Net::HTTP::Delete.new("#{uri.path}#{request.qpath}")
                     begin
                       response.set(http.request(http_req))
                     rescue Exception => details
                       response.set(details)
                     end
-                  when "exit"
+                  when 'exit'
                     @counter_lock.synchronize do
                       @connections -= 1
                     end
@@ -96,17 +101,17 @@ module PredictionIO
 
     # Shortcut to create an asynchronous GET request with the response object returned.
     def aget(areq)
-      request("get", areq)
+      request('get', areq)
     end
 
     # Shortcut to create an asynchronous POST request with the response object returned.
     def apost(areq)
-      request("post", areq)
+      request('post', areq)
     end
 
     # Shortcut to create an asynchronous DELETE request with the response object returned.
     def adelete(areq)
-      request("delete", areq)
+      request('delete', areq)
     end
   end
 end

data/lib/predictionio/engine_client.rb

@@ -0,0 +1,127 @@
+# Ruby SDK for convenient access of PredictionIO Output API.
+#
+# Author::    PredictionIO Team (support@prediction.io)
+# Copyright:: Copyright (c) 2014 TappingStone, Inc.
+# License::   Apache License, Version 2.0
+
+require 'predictionio/async_request'
+require 'predictionio/async_response'
+require 'predictionio/connection'
+
+module PredictionIO
+  # This class contains methods that interface with PredictionIO Engine
+  # Instances that are trained from PredictionIO built-in Engines.
+  #
+  # Many REST request methods support optional arguments. They can be supplied
+  # to these methods as Hash'es. For a complete reference, please visit
+  # http://prediction.io.
+  #
+  # == Synopsis
+  # In most cases, using synchronous methods. If you have a special performance
+  # requirement, you may want to take a look at asynchronous methods.
+  #
+  # === Instantiate an EngineClient
+  #     # Include the PredictionIO SDK
+  #     require 'predictionio'
+  #
+  #     client = PredictionIO::EngineClient.new
+  #
+  # === Send a Query to Retrieve Predictions
+  #     # PredictionIO call to record the view action
+  #     begin
+  #       result = client.query('uid' => 'foobar')
+  #     rescue NotFoundError => e
+  #       ...
+  #     rescue BadRequestError => e
+  #       ...
+  #     rescue ServerError => e
+  #       ...
+  #     end
+  class EngineClient
+    # Raised when an event is not created after a synchronous API call.
+    class NotFoundError < StandardError; end
+
+    # Raised when the query is malformed.
+    class BadRequestError < StandardError; end
+
+    # Raised when the Engine Instance returns a server error.
+    class ServerError < StandardError; end
+
+    # Create a new PredictionIO Event Client with defaults:
+    # - 1 concurrent HTTP(S) connections (threads)
+    # - API entry point at http://localhost:7070 (apiurl)
+    # - a 60-second timeout for each HTTP(S) connection (thread_timeout)
+    def initialize(apiurl = 'http://localhost:8000', threads = 1,
+                   thread_timeout = 60)
+      @http = PredictionIO::Connection.new(URI(apiurl), threads, thread_timeout)
+    end
+
+    # Returns the number of pending requests within the current client.
+    def pending_requests
+      @http.packages.size
+    end
+
+    # Returns PredictionIO's status in string.
+    def get_status
+      status = @http.aget(PredictionIO::AsyncRequest.new('/')).get
+      begin
+        status.body
+      rescue
+        status
+      end
+    end
+
+    protected
+
+    # Internal helper method. Do not call directly.
+    def sync_events(sync_m, *args)
+      if args[0].is_a?(PredictionIO::AsyncResponse)
+        response = args[0].get
+      else
+        response = send(sync_m, *args).get
+      end
+      return JSON.parse(response.body) if response.is_a?(Net::HTTPOK)
+      begin
+        msg = response.body
+      rescue
+        raise response
+      end
+      if response.is_a?(Net::HTTPBadRequest)
+        fail BadRequestError, msg
+      elsif response.is_a?(Net::HTTPNotFound)
+        fail NotFoundError, msg
+      elsif response.is_a?(Net::HTTPServerError)
+        fail ServerError, msg
+      else
+        fail msg
+      end
+    end
+
+    public
+
+    # :category: Asynchronous Methods
+    # Asynchronously sends a query and returns PredictionIO::AsyncResponse
+    # object immediately. The query should be a Ruby data structure that can be
+    # converted to a JSON object.
+    #
+    # Corresponding REST API method: POST /
+    #
+    # See also #send_query.
+    def asend_query(query)
+      @http.apost(PredictionIO::AsyncRequest.new('/queries.json',
+                                                 query.to_json))
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously sends a query and block until predictions are received.
+    #
+    # See also #asend_query.
+    #
+    # call-seq:
+    # send_query(data)
+    # send_query(async_response)
+    def send_query(*args)
+      sync_events(:asend_query, *args)
+    end
+  end
+end

data/lib/predictionio/event_client.rb

@@ -0,0 +1,340 @@
+# Ruby SDK for convenient access of PredictionIO Output API.
+#
+# Author::    PredictionIO Team (support@prediction.io)
+# Copyright:: Copyright (c) 2014 TappingStone, Inc.
+# License::   Apache License, Version 2.0
+
+require 'predictionio/async_request'
+require 'predictionio/async_response'
+require 'predictionio/connection'
+require 'date'
+
+module PredictionIO
+  # This class contains methods that interface with the PredictionIO Event
+  # Server via the PredictionIO Event API using REST requests.
+  #
+  # Many REST request methods support optional arguments. They can be supplied
+  # to these methods as Hash'es. For a complete reference, please visit
+  # http://prediction.io.
+  #
+  # == High-performance Asynchronous Backend
+  #
+  # All REST request methods come in both synchronous and asynchronous flavors.
+  # Both flavors accept the same set of arguments. In addition, all synchronous
+  # request methods can instead accept a PredictionIO::AsyncResponse object
+  # generated from asynchronous request methods as its first argument. In this
+  # case, the method will block until a response is received from it.
+  #
+  # Any network reconnection and request retry is automatically handled in the
+  # background. Exceptions will be thrown after a request times out to avoid
+  # infinite blocking.
+  #
+  # == Installation
+  # The easiest way is to use RubyGems:
+  #     gem install predictionio
+  #
+  # == Synopsis
+  # In most cases, using synchronous methods. If you have a special performance
+  # requirement, you may want to take a look at asynchronous methods.
+  #
+  # === Instantiate an EventClient
+  #     # Include the PredictionIO SDK
+  #     require 'predictionio'
+  #
+  #     client = PredictionIO::EventClient.new(<app_id>)
+  #
+  # === Import a User Record from Your App (with asynchronous/non-blocking
+  #     requests)
+  #
+  #     #
+  #     # (your user registration logic)
+  #     #
+  #
+  #     uid = get_user_from_your_db()
+  #
+  #     # PredictionIO call to create user
+  #     response = client.aset_user(uid)
+  #
+  #     #
+  #     # (other work to do for the rest of the page)
+  #     #
+  #
+  #     begin
+  #       # PredictionIO call to retrieve results from an asynchronous response
+  #       result = client.set_user(response)
+  #     rescue PredictionIO::EventClient::NotCreatedError => e
+  #       log_and_email_error(...)
+  #     end
+  #
+  # === Import a User Action (Rate) from Your App (with synchronous/blocking
+  #     requests)
+  #     # PredictionIO call to record the view action
+  #     begin
+  #       result = client.record_user_action_on_item('rate', 'foouser',
+  #                                                  'baritem',
+  #                                                  'pio_rating' => 4)
+  #     rescue PredictionIO::EventClient::NotCreatedError => e
+  #       ...
+  #     end
+  class EventClient
+    # Raised when an event is not created after a synchronous API call.
+    class NotCreatedError < StandardError; end
+
+    # Create a new PredictionIO Event Client with defaults:
+    # - 1 concurrent HTTP(S) connections (threads)
+    # - API entry point at http://localhost:7070 (apiurl)
+    # - a 60-second timeout for each HTTP(S) connection (thread_timeout)
+    def initialize(app_id, apiurl = 'http://localhost:7070', threads = 1,
+                   thread_timeout = 60)
+      @app_id = app_id
+      @http = PredictionIO::Connection.new(URI(apiurl), threads, thread_timeout)
+    end
+
+    # Returns the number of pending requests within the current client.
+    def pending_requests
+      @http.packages.size
+    end
+
+    # Returns PredictionIO's status in string.
+    def get_status
+      status = @http.aget(PredictionIO::AsyncRequest.new('/')).get
+      begin
+        status.body
+      rescue
+        status
+      end
+    end
+
+    protected
+
+    # Internal helper method. Do not call directly.
+    def sync_events(sync_m, *args)
+      if args[0].is_a?(PredictionIO::AsyncResponse)
+        response = args[0].get
+      else
+        response = send(sync_m, *args).get
+      end
+      return response if response.is_a?(Net::HTTPCreated)
+      begin
+        msg = response.body
+      rescue
+        raise NotCreatedError, response
+      end
+      fail NotCreatedError, msg
+    end
+
+    public
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to create an event and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #create_event.
+    def acreate_event(event, entity_type, entity_id, optional = {})
+      h = optional
+      h.key?('eventTime') || h['eventTime'] = DateTime.now.to_s
+      h['appId'] = @app_id
+      h['event'] = event
+      h['entityType'] = entity_type
+      h['entityId'] = entity_id
+      @http.apost(PredictionIO::AsyncRequest.new('/events.json', h.to_json))
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to create an event and block until a response is
+    # received.
+    #
+    # See also #acreate_event.
+    #
+    # call-seq:
+    # create_event(event, entity_type, entity_id, optional = {})
+    # create_event(async_response)
+    def create_event(*args)
+      sync_events(:acreate_event, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to set properties of a user and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #set_user.
+    def aset_user(uid, optional = {})
+      acreate_event('$set', 'pio_user', uid, optional)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to set properties of a user and block until a
+    # response is received.
+    #
+    # See also #aset_user.
+    #
+    # call-seq:
+    # set_user(uid, optional = {})
+    # set_user(async_response)
+    def set_user(*args)
+      sync_events(:aset_user, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to unset properties of a user and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # properties must be a non-empty Hash.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #unset_user.
+    def aunset_user(uid, optional)
+      optional.key?('properties') ||
+        fail(ArgumentError, 'properties must be present when event is $unset')
+      optional['properties'].empty? &&
+        fail(ArgumentError, 'properties cannot be empty when event is $unset')
+      acreate_event('$unset', 'pio_user', uid, optional)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to unset properties of a user and block until a
+    # response is received.
+    #
+    # See also #aunset_user.
+    #
+    # call-seq:
+    # unset_user(uid, optional)
+    # unset_user(async_response)
+    def unset_user(*args)
+      sync_events(:aunset_user, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to delete a user and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #delete_user.
+    def adelete_user(uid)
+      acreate_event('$delete', 'pio_user', uid)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to delete a user and block until a response is
+    # received.
+    #
+    # See also #adelete_user.
+    #
+    # call-seq:
+    # delete_user(uid)
+    # delete_user(async_response)
+    def delete_user(*args)
+      sync_events(:adelete_user, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to set properties of an item and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #set_item.
+    def aset_item(iid, optional = {})
+      acreate_event('$set', 'pio_item', iid, optional)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to set properties of an item and block until a
+    # response is received.
+    #
+    # See also #aset_item.
+    #
+    # call-seq:
+    # set_item(iid, properties = {}, optional = {})
+    # set_item(async_response)
+    def set_item(*args)
+      sync_events(:aset_item, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to unset properties of an item and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # properties must be a non-empty Hash.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #unset_item.
+    def aunset_item(iid, optional)
+      optional.key?('properties') ||
+        fail(ArgumentError, 'properties must be present when event is $unset')
+      optional['properties'].empty? &&
+        fail(ArgumentError, 'properties cannot be empty when event is $unset')
+      acreate_event('$unset', 'pio_item', iid, optional)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to unset properties of an item and block until a
+    # response is received.
+    #
+    # See also #aunset_item.
+    #
+    # call-seq:
+    # unset_item(iid, properties, optional = {})
+    # unset_item(async_response)
+    def unset_item(*args)
+      sync_events(:aunset_item, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to delete an item and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #delete_item.
+    def adelete_item(uid)
+      acreate_event('$delete', 'pio_item', uid)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to delete an item and block until a response is
+    # received.
+    #
+    # See also #adelete_item.
+    #
+    # call-seq:
+    # delete_item(uid)
+    # delete_item(async_response)
+    def delete_item(*args)
+      sync_events(:adelete_item, *args)
+    end
+
+    # :category: Asynchronous Methods
+    # Asynchronously request to record an action on an item and return a
+    # PredictionIO::AsyncResponse object immediately.
+    #
+    # Corresponding REST API method: POST /events.json
+    #
+    # See also #record_user_action_on_item.
+    def arecord_user_action_on_item(action, uid, iid, optional = {})
+      optional['targetEntityType'] = 'pio_item'
+      optional['targetEntityId'] = iid
+      acreate_event(action, 'pio_user', uid, optional)
+    end
+
+    # :category: Synchronous Methods
+    # Synchronously request to record an action on an item and block until a
+    # response is received.
+    #
+    # See also #arecord_user_action_on_item.
+    #
+    # call-seq:
+    # record_user_action_on_item(action, uid, iid, optional = {})
+    # record_user_action_on_item(async_response)
+    def record_user_action_on_item(*args)
+      sync_events(:arecord_user_action_on_item, *args)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: predictionio
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - The PredictionIO Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-10 00:00:00.000000000 Z
+date: 2014-09-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   PredictionIO is a prediction server for building smart applications. This gem
@@ -19,13 +19,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/predictionio.rb
 - lib/predictionio/async_request.rb
 - lib/predictionio/async_response.rb
 - lib/predictionio/client.rb
 - lib/predictionio/connection.rb
-- lib/predictionio.rb
+- lib/predictionio/engine_client.rb
+- lib/predictionio/event_client.rb
 homepage: http://prediction.io
-licenses: []
+licenses:
+- Apache-2.0
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -33,17 +36,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: PredictionIO Ruby SDK