predictionio 0.3.1 → 0.5.0

data/lib/predictionio/client.rb

@@ -37,15 +37,15 @@ module PredictionIO
   # == Special Handling of Some Optional Arguments
   # Some optional arguments have additional special handling:
   # - For all requests that accept "itypes" as input, the value can be supplied as either an Array of String's, or a comma-delimited String.
-  # - For all requests that accept "latlng" as input, they will also accept "latitude" and "longitude".
-  #   When these are supplied, they will override any existing "latlng" value.
-  # - All time arguments (e.g. t, startT, endT, etc) can be supplied as either a Time or Float object.
+  # - For all requests that accept "pio_latlng" as input, they will also accept "pio_latitude" and "pio_longitude".
+  #   When these are supplied, they will override any existing "pio_latlng" value.
+  # - All time arguments (e.g. t, pio_startT, pio_endT, etc) can be supplied as either a Time or Float object.
   #   When supplied as a Float, the SDK will interpret it as a UNIX UTC timestamp in seconds.
   #   The SDK will automatically round to the nearest millisecond, e.g. 3.14159 => 3.142.
   #
   # == Installation
-  # Download the PredictionIO Ruby Gem from http://prediction.io
-  #     gem install predictionio-0.1.0.gem
+  # The easiest way is to use RubyGems:
+  #     gem install predictionio-0.5.0.gem
   #
   # == Synopsis
   # The recommended usage of the SDK is to fire asynchronous requests as early as you can in your code,
@@ -79,26 +79,28 @@ module PredictionIO
   #       log_and_email_error(...)
   #     end
   #
-  # === Import a User Action (View) form Your App (with synchronous/blocking requests)
+  # === Import a User Action (Rate) from Your App (with synchronous/blocking requests)
   #     # PredictionIO call to record the view action
   #     begin
-  #       result = client.user_view_item(4, 15)
+  #       client.identify("foouser")
+  #       result = client.record_action_on_item("rate", "baritem", "pio_rate" => 4)
   #     rescue U2IActionNotCreatedError => e
   #       ...
   #     end
   #
   # === Retrieving Top N Recommendations for a User
   #     # PredictionIO call to get recommendations
-  #     response = client.aget_recommendation(4, 10)
+  #     client.identify("foouser")
+  #     response = client.aget_itemrec_top_n("barengine", 10)
   #
   #     #
   #     # work you need to do for the page (rendering, db queries, etc)
   #     #
   #
   #     begin
-  #       result = client.get_recommendations(response)
+  #       result = client.get_itemrec_top_n(response)
   #       # display results, store results, or your other work...
-  #     rescue RecommendationsNotFoundError => e
+  #     rescue ItemRecNotFoundError => e
   #       # graceful error handling
   #     end
 
@@ -113,6 +115,9 @@ module PredictionIO
     # Only JSON is currently supported as API response format.
     attr_accessor :apiformat
 
+    # The UID used for recording user-to-item actions and retrieving recommendations.
+    attr_accessor :apiuid
+
     # Raised when a user is not created after a synchronous API call.
     class UserNotCreatedError < StandardError; end
 
@@ -171,10 +176,10 @@ module PredictionIO
     # See also #create_user.
     def acreate_user(uid, params = {})
       rparams = params
-      rparams["appkey"] = @appkey
-      rparams["uid"] = uid
-      if params["latitude"] != nil && params["longitude"] != nil then
-        rparams["latlng"] = "#{params["latitude"]},#{params["longitude"]}"
+      rparams["pio_appkey"] = @appkey
+      rparams["pio_uid"] = uid
+      if params["pio_latitude"] != nil && params["pio_longitude"] != nil then
+        rparams["pio_latlng"] = "#{params["pio_latitude"]},#{params["pio_longitude"]}"
       end
 
       @http.apost(PredictionIO::AsyncRequest.new(versioned_path("/users.#{@apiformat}"), rparams))
@@ -191,7 +196,6 @@ module PredictionIO
     def create_user(*args)
       uid_or_res = args[0]
       if uid_or_res.is_a?(PredictionIO::AsyncResponse) then
-        uid = uid_or_res.request.params["uid"]
         response = uid_or_res.get
       else
         uid = uid_or_res
@@ -219,8 +223,8 @@ module PredictionIO
     # See also #get_user.
     def aget_user(uid)
       @http.aget(PredictionIO::AsyncRequest.new(versioned_path("/users/#{uid}.#{@apiformat}"),
-                                            "appkey" => @appkey,
-                                            "uid" => uid))
+                                                "pio_appkey" => @appkey,
+                                                "pio_uid" => uid))
     end
 
     # :category: Synchronous Methods
@@ -243,12 +247,10 @@ module PredictionIO
       end
       if response.is_a?(Net::HTTPOK) then
         res = JSON.parse(response.body)
-        ct = Rational(res["ct"], 1000)
-        res["ct"] = Time.at(ct)
-        if res["latlng"] != nil then
-          latlng = res["latlng"]
-          res["latitude"] = latlng[0]
-          res["longitude"] = latlng[1]
+        if res["pio_latlng"] != nil then
+          latlng = res["pio_latlng"]
+          res["pio_latitude"] = latlng[0]
+          res["pio_longitude"] = latlng[1]
         end
         res
       else
@@ -269,8 +271,8 @@ module PredictionIO
     # See also #delete_user.
     def adelete_user(uid)
       @http.adelete(PredictionIO::AsyncRequest.new(versioned_path("/users/#{uid}.#{@apiformat}"),
-                                               "appkey" => @appkey,
-                                               "uid" => uid))
+                                                   "pio_appkey" => @appkey,
+                                                   "pio_uid" => uid))
     end
 
     # :category: Synchronous Methods
@@ -305,21 +307,21 @@ module PredictionIO
     # See also #create_item.
     def acreate_item(iid, itypes, params = {})
       rparams = params
-      rparams["appkey"] = @appkey
-      rparams["iid"] = iid
+      rparams["pio_appkey"] = @appkey
+      rparams["pio_iid"] = iid
       begin
-        rparams["itypes"] = itypes.join(",")
+        rparams["pio_itypes"] = itypes.join(",")
       rescue Exception
-        rparams["itypes"] = itypes
+        rparams["pio_itypes"] = itypes
       end
-      if params["latitude"] != nil && params["longitude"] != nil then
-        rparams["latlng"] = "#{params["latitude"]},#{params["longitude"]}"
+      if params["pio_latitude"] != nil && params["pio_longitude"] != nil then
+        rparams["pio_latlng"] = "#{params["pio_latitude"]},#{params["pio_longitude"]}"
       end
-      if params["startT"] != nil then
-        rparams["startT"] = ((params["startT"].to_r) * 1000).round(0).to_s
+      if params["pio_startT"] != nil then
+        rparams["pio_startT"] = ((params["pio_startT"].to_r) * 1000).round(0).to_s
       end
-      if params["endT"] != nil then
-        rparams["endT"] = ((params["endT"].to_r) * 1000).round(0).to_s
+      if params["pio_endT"] != nil then
+        rparams["pio_endT"] = ((params["pio_endT"].to_r) * 1000).round(0).to_s
       end
 
       @http.apost(PredictionIO::AsyncRequest.new(versioned_path("/items.#{@apiformat}"), rparams))
@@ -362,8 +364,8 @@ module PredictionIO
     # See also #get_item.
     def aget_item(iid)
       @http.aget(PredictionIO::AsyncRequest.new(versioned_path("/items/#{iid}.#{@apiformat}"),
-                                           "appkey" => @appkey,
-                                           "iid" => iid))
+                                                "pio_appkey" => @appkey,
+                                                "pio_iid" => iid))
     end
 
     # :category: Synchronous Methods
@@ -386,20 +388,18 @@ module PredictionIO
       end
       if response.is_a?(Net::HTTPOK) then
         res = JSON.parse(response.body)
-        ct = Rational(res["ct"], 1000)
-        res["ct"] = Time.at(ct)
-        if res["latlng"] != nil then
-          latlng = res["latlng"]
-          res["latitude"] = latlng[0]
-          res["longitude"] = latlng[1]
+        if res["pio_latlng"] != nil then
+          latlng = res["pio_latlng"]
+          res["pio_latitude"] = latlng[0]
+          res["pio_longitude"] = latlng[1]
         end
-        if res["startT"] != nil then
-          startT = Rational(res["startT"], 1000)
-          res["startT"] = Time.at(startT)
+        if res["pio_startT"] != nil then
+          startT = Rational(res["pio_startT"], 1000)
+          res["pio_startT"] = Time.at(startT)
         end
-        if res["endT"] != nil then
-          endT = Rational(res["endT"], 1000)
-          res["endT"] = Time.at(endT)
+        if res["pio_endT"] != nil then
+          endT = Rational(res["pio_endT"], 1000)
+          res["pio_endT"] = Time.at(endT)
         end
         res
       else
@@ -420,8 +420,8 @@ module PredictionIO
     # See also #delete_item.
     def adelete_item(iid)
       @http.adelete(PredictionIO::AsyncRequest.new(versioned_path("/items/#{iid}.#{@apiformat}"),
-                                               "appkey" => @appkey,
-                                               "iid" => iid))
+                                                   "pio_appkey" => @appkey,
+                                                   "pio_iid" => iid))
     end
 
     # :category: Synchronous Methods
@@ -448,32 +448,37 @@ module PredictionIO
       end
     end
 
+    # Set the user ID for use in all subsequent user-to-item action recording and user recommendation retrieval.
+    def identify(uid)
+      @apiuid = uid
+    end
+
     # :category: Asynchronous Methods
     # Asynchronously request to get the top n recommendations for a user from an ItemRec engine and return a PredictionIO::AsyncResponse object immediately.
     #
     # Corresponding REST API method: GET /engines/itemrec/:engine/topn
     #
     # See also #get_itemrec_top_n.
-    def aget_itemrec_top_n(engine, uid, n, params = {})
+    def aget_itemrec_top_n(engine, n, params = {})
       rparams = Hash.new
-      rparams["appkey"] = @appkey
-      rparams["uid"] = uid
-      rparams["n"] = n
-      if params["itypes"] != nil &&
-          params["itypes"].kind_of?(Array) &&
-          params["itypes"].length > 0 then
-        rparams["itypes"] = params["itypes"].join(",")
+      rparams["pio_appkey"] = @appkey
+      rparams["pio_uid"] = @apiuid
+      rparams["pio_n"] = n
+      if params["pio_itypes"] != nil &&
+          params["pio_itypes"].kind_of?(Array) &&
+          params["pio_itypes"].length > 0 then
+        rparams["pio_itypes"] = params["pio_itypes"].join(",")
       else
-        rparams["itypes"] = params["itypes"]
+        rparams["pio_itypes"] = params["pio_itypes"]
       end
-      if params["latitude"] != nil && params["longitude"] != nil then
-        rparams["latlng"] = "#{params["latitude"]},#{params["longitude"]}"
+      if params["pio_latitude"] != nil && params["pio_longitude"] != nil then
+        rparams["pio_latlng"] = "#{params["pio_latitude"]},#{params["pio_longitude"]}"
       end
-      if params["within"] != nil then
-        rparams["within"] = params["within"]
+      if params["pio_within"] != nil then
+        rparams["pio_within"] = params["pio_within"]
       end
-      if params["unit"] != nil then
-        rparams["unit"] = params["unit"]
+      if params["pio_unit"] != nil then
+        rparams["pio_unit"] = params["pio_unit"]
       end
       @http.aget(PredictionIO::AsyncRequest.new(versioned_path("/engines/itemrec/#{engine}/topn.#{@apiformat}"), rparams))
     end
@@ -484,8 +489,8 @@ module PredictionIO
     # See #aget_itemrec_top_n for a description of special argument handling.
     #
     # call-seq:
-    # get_recommendations(uid, n, params = {})
-    # get_recommendations(async_response)
+    # aget_itemrec_top_n(engine, n, params = {})
+    # aget_itemrec_top_n(async_response)
     def get_itemrec_top_n(*args)
       uid_or_res = args[0]
       if uid_or_res.is_a?(PredictionIO::AsyncResponse) then
@@ -495,7 +500,7 @@ module PredictionIO
       end
       if response.is_a?(Net::HTTPOK) then
         res = JSON.parse(response.body)
-        res["iids"]
+        res["pio_iids"]
       else
         begin
           msg = response.body
@@ -507,166 +512,40 @@ module PredictionIO
     end
 
     # :category: Asynchronous Methods
-    # Asynchronously request to record a user-rate-item action and return a PredictionIO::AsyncResponse object immediately.
-    #
-    # Corresponding REST API method: POST /actions/u2i/rate
-    #
-    # See also #user_rate_item.
-    def auser_rate_item(uid, iid, rate, params = {})
-      params["rate"] = rate
-      auser_action_item("rate", uid, iid, params)
-    end
-
-    # :category: Synchronous Methods
-    # Synchronously request to record a user-rate-item action and block until a response is received.
-    #
-    # See #auser_rate_item.
-    #
-    # call-seq:
-    # user_rate_item(uid, iid, rate, params = {})
-    # user_rate_item(async_response)
-    def user_rate_item(*args)
-      if !args[0].is_a?(PredictionIO::AsyncResponse) then
-        args.unshift("rate")
-        params = args[4]
-        if params == nil then
-          params = Hash.new
-        end
-        params["rate"] = args[3]
-        args[3] = params
-      end
-      user_action_item(*args)
-    end
-
-    # :category: Asynchronous Methods
-    # Asynchronously request to record a user-like-item action and return a PredictionIO::AsyncResponse object immediately.
-    #
-    # Corresponding REST API method: POST /actions/u2i/like
+    # Asynchronously request to record an action on an item and return a PredictionIO::AsyncResponse object immediately.
     #
-    # See also #user_like_item.
-    def auser_like_item(uid, iid, params = {})
-      auser_action_item("like", uid, iid, params)
-    end
-
-    # :category: Synchronous Methods
-    # Synchronously request to record a user-like-item action and block until a response is received.
+    # Corresponding REST API method: POST /actions/u2i
     #
-    # See also #auser_like_item.
-    #
-    # call-seq:
-    # user_like_item(uid, iid, params = {})
-    # user_like_item(async_response)
-    def user_like_item(*args)
-      if !args[0].is_a?(PredictionIO::AsyncResponse) then
-        args.unshift("like")
+    # See also #record_action_on_item.
+    def arecord_action_on_item(action, iid, params = {})
+      rparams = params
+      rparams["pio_appkey"] = @appkey
+      rparams["pio_action"] = action
+      rparams["pio_uid"] = @apiuid
+      rparams["pio_iid"] = iid
+      if params["pio_t"] != nil then
+        rparams["pio_t"] = ((params["pio_t"].to_r) * 1000).round(0).to_s
       end
-      user_action_item(*args)
-    end
-
-    # :category: Asynchronous Methods
-    # Asynchronously request to record a user-dislike-item action and return a PredictionIO::AsyncResponse object immediately.
-    #
-    # Corresponding REST API method: POST /actions/u2i/dislike
-    #
-    # See also #user_dislike_item.
-    def auser_dislike_item(uid, iid, params = {})
-      auser_action_item("dislike", uid, iid, params)
-    end
-
-    # :category: Synchronous Methods
-    # Synchronously request to record a user-dislike-item action and block until a response is received.
-    #
-    # See also #auser_dislike_item.
-    #
-    # call-seq:
-    # user_dislike_item(uid, iid, params = {})
-    # user_dislike_item(async_response)
-    def user_dislike_item(*args)
-      if !args[0].is_a?(PredictionIO::AsyncResponse) then
-        args.unshift("dislike")
+      if params["pio_latitude"] != nil && params["pio_longitude"] != nil then
+        rparams["pio_latlng"] = "#{params["pio_latitude"]},#{params["pio_longitude"]}"
       end
-      user_action_item(*args)
-    end
-
-    # :category: Asynchronous Methods
-    # Asynchronously request to record a user-view-item action and return a PredictionIO::AsyncResponse object immediately.
-    #
-    # Corresponding REST API method: POST /actions/u2i/view
-    #
-    # See also #user_view_item.
-    def auser_view_item(uid, iid, params = {})
-      auser_action_item("view", uid, iid, params)
+      @http.apost(PredictionIO::AsyncRequest.new(versioned_path("/actions/u2i.#{@apiformat}"), rparams))
     end
 
     # :category: Synchronous Methods
-    # Synchronously request to record a user-view-item action and block until a response is received.
+    # Synchronously request to record an action on an item and block until a response is received.
     #
-    # See also #auser_view_item.
+    # See also #arecord_action_on_item.
     #
     # call-seq:
-    # user_view_item(uid, iid, params = {})
-    # user_view_item(async_response)
-    def user_view_item(*args)
-      if !args[0].is_a?(PredictionIO::AsyncResponse) then
-        args.unshift("view")
-      end
-      user_action_item(*args)
-    end
-
-    # :category: Asynchronous Methods
-    # Asynchronously request to record a user-conversion-item action and return a PredictionIO::AsyncResponse object immediately.
-    #
-    # Corresponding REST API method: POST /actions/u2i/conversion
-    #
-    # See also #user_conversion_item.
-    def auser_conversion_item(uid, iid, params = {})
-      auser_action_item("conversion", uid, iid, params)
-    end
-
-    # :category: Synchronous Methods
-    # Synchronously request to record a user-conversion-item action and block until a response is received.
-    #
-    # See also #auser_conversion_item.
-    #
-    # call-seq:
-    # user_conversion_item(uid, iid, params = {})
-    # user_conversion_item(async_response)
-    def user_conversion_item(*args)
-      if !args[0].is_a?(PredictionIO::AsyncResponse) then
-        args.unshift("conversion")
-      end
-      user_action_item(*args)
-    end
-
-    # :nodoc: all
-    private
-
-    def versioned_path(path)
-      # disabled for now
-      # "/#{@apiversion}#{path}"
-      path
-    end
-
-    def auser_action_item(action, uid, iid, params = {})
-      rparams = params
-      rparams["appkey"] = @appkey
-      rparams["uid"] = uid
-      rparams["iid"] = iid
-      if params["t"] != nil then
-        rparams["t"] = ((params["t"].to_r) * 1000).round(0).to_s
-      end
-      if params["latitude"] != nil && params["longitude"] != nil then
-        rparams["latlng"] = "#{params["latitude"]},#{params["longitude"]}"
-      end
-      @http.apost(PredictionIO::AsyncRequest.new(versioned_path("/actions/u2i/#{action}.#{@apiformat}"), rparams))
-    end
-
-    def user_action_item(*args)
+    # record_action_on_item(action, uid, iid, params = {})
+    # record_action_on_item(async_response)
+    def record_action_on_item(*args)
       action_or_res = args[0]
       if action_or_res.is_a?(PredictionIO::AsyncResponse) then
         response = action_or_res.get
       else
-        response = auser_action_item(*args).get
+        response = arecord_action_on_item(*args).get
       end
       unless response.is_a?(Net::HTTPCreated) then
         begin
@@ -677,5 +556,14 @@ module PredictionIO
         raise U2IActionNotCreatedError, msg
       end
     end
+
+    # :nodoc: all
+    private
+
+    def versioned_path(path)
+      # disabled for now
+      # "/#{@apiversion}#{path}"
+      path
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: predictionio
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-25 00:00:00.000000000 Z
+date: 2013-07-20 00:00:00.000000000 Z
 dependencies: []
 description: ! 'PredictionIO is a prediction server for building smart applications.
   This gem