kempelen 1.0.0

data/lib/kempelen.rb

@@ -0,0 +1,35 @@
+require "kempelen/version"
+
+require "kempelen/API/client"
+
+require "kempelen/API/common/price"
+require "kempelen/API/common/assignment"
+require "kempelen/API/common/answers"
+require "kempelen/API/common/question_form_answers"
+
+require "kempelen/API/responses/base"
+require "kempelen/API/responses/error_response"
+require "kempelen/API/responses/empty_response"
+require "kempelen/API/responses/hit_response"
+require "kempelen/API/responses/account_balance_response"
+require "kempelen/API/responses/reviewable_hits_response"
+require "kempelen/API/responses/get_assignments_response"
+
+require "kempelen/API/operations/base"
+require "kempelen/API/operations/parameters"
+require "kempelen/API/operations/hit_operation"
+require "kempelen/API/operations/assignment_operation"
+require "kempelen/API/operations/create_hit"
+require "kempelen/API/operations/get_hit"
+require "kempelen/API/operations/get_reviewable_hits"
+require "kempelen/API/operations/get_account_balance"
+require "kempelen/API/operations/force_expire_hit"
+require "kempelen/API/operations/approve_assignment"
+require "kempelen/API/operations/reject_assignment"
+require "kempelen/API/operations/get_assignments_for_hit"
+require "kempelen/API/operations/set_hit_as_reviewing"
+require "kempelen/API/operations/register_hit_type"
+
+module Kempelen
+  # Your code goes here...
+end

data/lib/kempelen/API/client.rb

@@ -0,0 +1,45 @@
+module Kempelen
+  module API
+    class Client
+      # Amazon AWS access key.
+      attr_reader :access_key
+
+      # Secret key for AWS access key. Used to sign the requests.
+      attr_reader :secret_key
+
+      # Mechanical Turk environment to make API calls to - defaults to :production.
+      attr_reader :environment
+
+      # URLs for Mechanical Turk APIs, indexed by environment.
+      SERVICE_URLS = {
+        sandbox: 'https://mechanicalturk.sandbox.amazonaws.com'.freeze,
+        production: 'https://mechanicalturk.amazonaws.com'.freeze
+      }
+
+      # Service name of the Mechanical Turk API.
+      SERVICE_NAME = "AWSMechanicalTurkRequester".freeze
+
+      def initialize(access_key, secret_key, environment = :production) 
+        @access_key = access_key
+        @secret_key = secret_key
+
+        @environment = environment.to_sym
+
+        raise ArgumentError.new("Unknown environment".freeze) if SERVICE_URLS[@environment].nil?
+      end
+
+      def service_name
+        SERVICE_NAME
+      end
+
+      def service_url
+        SERVICE_URLS[@environment]
+      end
+
+      def perform_request(query_string, response_object)
+        response = HTTParty.get(query_string)
+        response.parsed_response[response_object]
+      end
+    end
+  end
+end

data/lib/kempelen/API/common/answers.rb

@@ -0,0 +1,34 @@
+module Kempelen
+  module API
+    module Common
+      class Answer
+        attr_accessor :question_identifier
+
+        def initialize(question_identifier)
+          @question_identifier = question_identifier
+        end
+      end
+
+      class FreeTextAnswer < Answer
+        attr_accessor :free_text
+
+        def initialize(question_identifier, free_text)
+          super(question_identifier)
+
+          @free_text = free_text
+        end
+      end
+
+      class MultipleChoiceAnswer < Answer
+        attr_accessor :selection_identifiers
+        attr_accessor :other_selection_text
+
+        def initialize(question_identifier)
+          super(question_identifier)
+
+          @selection_identifiers = []
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/common/assignment.rb

@@ -0,0 +1,37 @@
+module Kempelen
+  module API
+    module Common
+      class Assignment
+        attr_accessor :assignment_id
+        attr_accessor :worker_id
+        attr_accessor :hit_id
+        attr_accessor :status
+        attr_accessor :auto_approval_time
+        attr_accessor :accept_time
+        attr_accessor :submit_time
+        attr_accessor :answer
+
+        def self.create_from_response(response)
+          return nil if response.nil?
+
+          assignment = Assignment.new
+
+          assignment.assignment_id = response["AssignmentId"]
+          assignment.worker_id = response["WorkerId"]
+          assignment.hit_id = response["HITId"]
+          assignment.status = response["AssignmentStatus"]
+          assignment.auto_approval_time = DateTime.parse(response["AutoApprovalTime"]) rescue nil
+          assignment.accept_time = DateTime.parse(response["AcceptTime"]) rescue nil
+          assignment.submit_time = DateTime.parse(response["SubmitTime"]) rescue nil
+          assignment.answer = QuestionFormAnswers.new(response["Answer"])
+
+          assignment
+        end
+
+        def answer_question(question_identifier, index = 0)
+          @answer.get_answer(question_identifier, index)
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/common/price.rb

@@ -0,0 +1,26 @@
+module Kempelen
+  module API
+    module Common
+      class Price
+        attr_accessor :amount
+        attr_accessor :currency_code
+
+        def initialize(amount = 0.0, currency_code = "USD")
+          @amount = amount
+          @currency_code = currency_code
+        end
+
+        def self.create_from_response(response)
+          return nil if response.nil?
+
+          price = Price.new
+
+          price.amount = response["Amount"].to_f
+          price.currency_code = response["CurrencyCode"]
+
+          price
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/common/question_form_answers.rb

@@ -0,0 +1,57 @@
+require 'nori'
+
+module Kempelen
+  module API
+    module Common
+      class QuestionFormAnswers
+        attr_accessor :answers
+
+        def initialize(answer = nil)
+          @answers = []
+
+          load_from_answer(answer) unless answer.nil?
+        end
+
+        # <?xml version="1.0" encoding="UTF-8" standalone="no"?>
+        #<QuestionFormAnswers xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionFormAnswers.xsd">
+        #  <Answer>
+        #    <QuestionIdentifier>TranscriptionTexts</QuestionIdentifier>
+        #    <FreeText>This is the second test.</FreeText>
+        #  </Answer>
+        #</QuestionFormAnswers>
+
+        def load_from_answer(answer)
+          parser = Nori.new(:parser => :rexml)
+          parsed_data = parser.parse(answer)
+          answer_list = parsed_data["QuestionFormAnswers"]["Answer"]
+
+          unless answer_list.is_a?(Array)
+            answer_list = [answer_list]
+          end
+
+          answer_list.each do |answer_data|
+            if answer_data.has_key?("FreeText")
+              @answers << FreeTextAnswer.new(answer_data["QuestionIdentifier"].to_s, answer_data["FreeText"].to_s)
+            elsif answer_data.has_key?("SelectionIdentifier") or answer_data.has_key?("OtherSelectionText")
+              new_answer = MultipleChoiceAnswer.new(answer_data["QuestionIdentifier"].to_s)
+
+              selection = answer_data["SelectionIdentifier"]
+              if selection.is_a?(Array)
+                new_answer.selection_identifiers += selection
+              else
+                new_answer.selection_identifiers << selection
+              end
+              new_answer.other_selection_text = answer_data["OtherSelectionText"]
+
+              @answers << new_answer
+            end
+          end
+        end
+
+        def get_answer(question_identifier, index = 0)
+          @answers.select {|a| a.question_identifier == question_identifier}[index] rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/operations/approve_assignment.rb

@@ -0,0 +1,17 @@
+module Kempelen
+  module API
+    module Operations
+      class ApproveAssignment < AssignmentOperation
+        AWS_OPERATION_NAME = "ApproveAssignment".freeze
+        AWS_RESPONSE_OBJECT = "ApproveAssignmentResponse".freeze
+
+        def initialize(client, assignment_id, requester_feedback = nil)
+          super(client, assignment_id, requester_feedback)
+
+          @operation_name = AWS_OPERATION_NAME
+          @response_object = AWS_RESPONSE_OBJECT
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/operations/assignment_operation.rb

@@ -0,0 +1,36 @@
+module Kempelen
+  module API
+    module Operations
+      class AssignmentOperation < Base
+        attr_accessor :assignment_id
+        attr_accessor :requester_feedback
+        attr_accessor :operation_name
+
+        FEEDBACK_MAX_SIZE = 1024
+
+        def initialize(client, assignment_id, requester_feedback = nil)
+          super(client)
+
+          @assignment_id = assignment_id
+          @requester_feedback = requester_feedback
+        end
+
+        def create_parameters
+          @parameters[:operation] = @operation_name
+          @parameters[:assignment_id] = @assignment_id
+          @parameters[:requester_feedback] = @requester_feedback.slice(0, FEEDBACK_MAX_SIZE) unless @requester_feedback.nil?
+
+          super
+        end
+
+        def perform_operation
+          create_request_string
+
+          super
+
+          Kempelen::API::Responses::EmptyResponse.new(@raw_response)
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/operations/base.rb

@@ -0,0 +1,71 @@
+require 'date'
+require 'hmac-sha1'
+require 'digest/sha1'
+require 'base64'
+
+module Kempelen
+  module API
+    module Operations
+      class Base
+        attr_accessor :client
+        attr_accessor :parameters
+        attr_accessor :timestamp
+        attr_accessor :response_object
+        attr_accessor :query_string
+        attr_accessor :raw_response
+
+        def initialize(client)
+          @client = client
+          @parameters = {}
+        end
+
+        def create_parameters
+          @parameters[:service] = client.service_name
+          @parameters[:access_key] = client.access_key
+          @parameters[:timestamp] = DateTime.now
+
+          string_to_sign = [@parameters[:service], @parameters[:operation], @parameters[:timestamp]].join
+          @parameters[:signature] = (Base64.encode64 HMAC::SHA1.digest(client.secret_key, string_to_sign)).strip
+        end
+
+        # TODO: Reduce the complexity of this method.
+        def create_request_string
+          create_parameters
+
+          request_str = ""
+
+          @parameters.each do |name, value|
+            aws_name = Kempelen::API::Operations::PARAMETERS[name]
+            if !aws_name.nil?
+              unless value.nil?
+                request_str += "&" unless request_str.empty?
+                request_str += "#{aws_name}=#{CGI.escape(value.to_s)}"
+              end
+            else
+              aws_name = Kempelen::API::Operations::ARRAY_PARAMETERS[name]
+              unless aws_name.nil?
+                value.each_index do |idx|
+                  hash_value = value[idx]
+
+                  if hash_value.respond_to?(:each)
+                    hash_value.each do |k, v|
+                      request_str += "&" unless request_str.empty?
+                      request_str += "#{aws_name}.#{idx + 1}.#{k}=#{CGI.escape(v.to_s)}"
+                    end
+                  end
+                end
+              end
+            end
+          end
+
+          @query_string = "#{client.service_url}?#{request_str}"
+        end
+
+        def perform_operation
+          @raw_response = @client.perform_request(@query_string, @response_object)
+        end
+
+      end
+    end
+  end
+end

data/lib/kempelen/API/operations/create_hit.rb

@@ -0,0 +1,55 @@
+module Kempelen
+  module API
+    module Operations
+      class CreateHit < Base
+        attr_accessor :hit_type_id
+        attr_accessor :layout_id
+        attr_accessor :layout_parameters
+        attr_accessor :lifetime_in_seconds
+        attr_accessor :max_assignments
+        attr_accessor :requester_annotation
+        attr_accessor :unique_request_token
+
+        AWS_OPERATION_NAME = "CreateHIT".freeze
+        AWS_RESPONSE_OBJECT = "CreateHITResponse".freeze
+
+        def initialize(client, hit_type_id, lifetime_in_seconds, &block)
+          super(client)
+
+          @hit_type_id = hit_type_id
+          @lifetime_in_seconds = lifetime_in_seconds.to_i
+          @layout_parameters = []
+          @max_assignments = 1
+          @response_object = AWS_RESPONSE_OBJECT
+
+          yield self unless block == nil
+        end
+
+        def add_layout_parameter(name, value)
+          @layout_parameters << {Name: name, Value: value}
+        end
+
+        def create_parameters
+          @parameters[:operation] = AWS_OPERATION_NAME
+          @parameters[:hit_type_id] = @hit_type_id
+          @parameters[:lifetime_in_seconds] = @lifetime_in_seconds
+          @parameters[:max_assignments] = @max_assignments
+          @parameters[:layout_id] = @layout_id unless @layout_id.nil?
+          @parameters[:layout_parameters] = @layout_parameters unless @layout_parameters.empty?
+          @parameters[:requester_annotation] = @requester_annotation unless @requester_annotation.nil?
+          @parameters[:unique_request_token] = @unique_request_token unless @unique_request_token.nil?
+
+          super 
+        end
+
+        def perform_operation
+          create_request_string
+
+          super
+
+          Kempelen::API::Responses::HitResponse.new(@raw_response)
+        end
+      end
+    end
+  end
+end

data/lib/kempelen/API/operations/force_expire_hit.rb

@@ -0,0 +1,25 @@
+module Kempelen
+  module API
+    module Operations
+      class ForceExpireHit < HitOperation
+        AWS_OPERATION_NAME = "ForceExpireHIT".freeze
+        AWS_RESPONSE_OBJECT = "ForceExpireHITResponse".freeze
+
+        def initialize(client, hit_id)
+          super(client, hit_id)
+
+          @operation_name = AWS_OPERATION_NAME
+          @response_object = AWS_RESPONSE_OBJECT
+        end
+
+        def perform_operation
+          create_request_string
+
+          super
+
+          Kempelen::API::Responses::EmptyResponse.new(@raw_response)
+        end
+      end
+    end
+  end
+end