turkee-mongoid 2.0.2

data/Rakefile

@@ -0,0 +1,50 @@
+require 'rubygems'
+require 'rake'
+require 'bundler'
+require 'rspec/core/rake_task'
+Bundler::GemHelper.install_tasks
+
+$:.push File.expand_path("../lib", __FILE__)
+
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Default: run specs.'
+task :default => :spec
+
+begin
+  INSTALL_MESSAGE = %q{
+  ========================================================================
+  Turkee Installation Complete.
+  ------------------------------------------------------------------------
+  If you're upgrading Turkee (1.1.1 and prior) or installing for the first time, run:
+
+    rails g turkee --skip
+
+  For full instructions on gem usage, visit:
+    http://github.com/aantix/turkee#readme
+
+  ** If you like the Turkee gem, please click the "watch" button on the
+  Github project page.  You'll make me smile and feel appreciated. :)
+    http://github.com/aantix/turkee
+
+  ========================================================================
+  }
+
+  Gem::Specification.new do |gem|
+    gem.name = "turkee"
+    gem.summary = "Turkee makes dealing with Amazon's Mechnical Turk a breeze."
+    gem.description = "Turkee will help you to create your Rails forms, post the HITs, and retrieve the user entered values from Mechanical Turk."
+    gem.email = "jjones@aantix.com"
+    gem.homepage = "http://github.com/aantix/turkee"
+    gem.authors = ["Jim Jones"]
+    gem.add_dependency(%q<rails>, [">= 3.1.1"])
+    gem.add_dependency(%q<rturk>, [">= 2.4.0"])
+    gem.add_dependency(%q<lockfile>, [">= 1.4.3"])
+
+    gem.post_install_message = INSTALL_MESSAGE
+    gem.require_path = 'lib'
+    gem.files = %w(MIT-LICENSE README.textile Gemfile Rakefile init.rb) + Dir.glob("{lib,spec}/**/*")
+
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+2.0.0

data/lib/generators/turkee/templates/turkee.rb

@@ -0,0 +1,8 @@
+# Go to this page https://aws-portal.amazon.com/gp/aws/developer/account/index.html?action=access-key
+# to retrieve your AWS/Mechanical Turk access keys.
+
+AWSACCESSKEYID      = 'XXXXXXXXXXXXXXXXXX'
+AWSSECRETACCESSKEY  = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+
+RTurk::logger.level = Logger::DEBUG
+RTurk.setup(AWSACCESSKEYID, AWSSECRETACCESSKEY, :sandbox => (Rails.env == 'production' ? false : true))

data/lib/generators/turkee/turkee_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators'
+
+class TurkeeGenerator < Rails::Generators::Base
+  
+  source_root File.expand_path("../templates", __FILE__)
+
+  desc "Creates initializer and migrations."
+
+  def create_initializer
+    template "turkee.rb", "config/initializers/turkee.rb"
+  end
+
+end

data/lib/helpers/turkee_forms_helper.rb

@@ -0,0 +1,69 @@
+module Turkee
+
+  module TurkeeFormHelper
+    def turkee_form_for(record, params, options = {}, &proc)
+      raise ArgumentError, "turkee_form_for now requires that you pass in the entire params hash, instead of just the assignmentId value. " unless params.is_a?(Hash)
+
+      options.merge!({:url => mturk_url})
+
+      capture do
+        form_for record, options do |f|
+          params.each do |k,v|
+            unless ['action','controller'].include?(k) || !v.is_a?(String)
+              concat hidden_field_tag(k, v)
+              cookies[k] = v
+            end
+          end
+
+          ['assignmentId', 'workerId', 'hitId'].each do |k|
+            concat hidden_field_tag(k, cookies[k]) if !params.has_key?(k) && cookies.has_key?(k)
+          end
+
+          concat(capture(f, &proc))
+        end
+      end
+    end
+
+    def turkee_study(id = nil)
+      task     = id.nil? ? Turkee::TurkeeTask.last : Turkee::TurkeeTask.find(id)
+      study    = Turkee::TurkeeStudy.new
+      disabled = Turkee::TurkeeFormHelper::disable_form_fields?(params[:assignmentId])
+
+      if task.present?
+        style =  "position: fixed; top: 120px; right: 30px; color: #FFF;"
+        style << "width: 400px; height: 375px; z-index: 100; padding: 10px;"
+        style << "background-color: rgba(0,0,0, 0.5); border: 1px solid #000;"
+
+        div_for(task, :style => style) do
+          capture do
+            concat content_tag(:h3, "DIRECTIONS", :style => 'text-align: right; color:#FF0000;')
+            concat task.hit_description.html_safe
+            concat '<hr/>'.html_safe
+            concat(turkee_form_for(study, params) do |f|
+              concat f.label(:feedback, "Feedback?:")
+              concat f.text_area(:feedback, :rows => 3, :disabled => disabled)
+              concat f.label(:gold_response, "Enter the fourth word from your above feedback :")
+              concat f.text_field(:gold_response, :disabled => disabled)
+              concat f.hidden_field(:turkee_task_id, :value => task.id)
+              concat '<br/>'.html_safe
+              concat f.submit('Submit', :disabled => disabled)
+            end)
+          end
+        end
+      end
+    end
+
+    # Returns the external Mechanical Turk url used to post form data based on whether RTurk is cofigured
+    #   for sandbox use or not.
+    def mturk_url
+      RTurk.sandbox? ? "https://workersandbox.mturk.com/mturk/externalSubmit" : "https://www.mturk.com/mturk/externalSubmit"
+    end
+
+    # Returns whether the form fields should be disabled or not (based on the assignment_id)
+    def self.disable_form_fields?(assignment)
+      assignment_id = assignment.is_a?(Hash) ? assignment[:assignmentId] : assignment
+      (assignment_id.nil? || assignment_id == 'ASSIGNMENT_ID_NOT_AVAILABLE')
+    end
+  end
+
+end

data/lib/models/turkee_imported_assignment.rb

@@ -0,0 +1,19 @@
+module Turkee
+  class TurkeeImportedAssignment
+    include Mongoid::Document
+    include Mongoid::Timestamps
+
+    field :assignment_id, type: String # TODO validates assignment_id, uniqueness: true ?
+    field :turkee_task_id, type: Integer
+    field :worker_id, type: String
+    field :result_id, type: Integer
+
+    def self.record_imported_assignment(assignment, result, turk)
+      TurkeeImportedAssignment.create!(:assignment_id => assignment.id,
+                                       :turkee_task_id => turk.id,
+                                       :worker_id => assignment.worker_id,
+                                       :result_id => result.id)
+    end
+
+  end
+end

data/lib/models/turkee_study.rb

@@ -0,0 +1,17 @@
+module Turkee
+  class TurkeeStudy
+    include Mongoid::Document
+    include Mongoid::Timestamps
+
+    field :turkee_task_id, type: Integer
+    field :feedback, type: String
+    field :gold_response, type: String
+
+    GOLD_RESPONSE_INDEX = 3
+
+    def approve?
+      words = feedback.split(/\W+/)
+      gold_response.present? ? (gold_response == words[GOLD_RESPONSE_INDEX]) : true
+    end
+  end
+end

data/lib/models/turkee_task.rb

@@ -0,0 +1,273 @@
+require 'rubygems'
+require 'socket'
+require 'rturk'
+require 'lockfile'
+require "active_support/core_ext/object/to_query"
+require 'action_controller'
+
+module Turkee
+
+  class TurkeeTask
+    include Mongoid::Document
+    include Mongoid::Timestamps
+
+    field :sandbox, type: Boolean
+    field :hit_title, type: String #TODO text
+    field :hit_description, type: String #TODO text
+    field :hit_reward, type: BigDecimal # :precision => 10, :scale => 2
+    field :hit_num_assignments, type: Integer
+    field :hit_lifetime, type: Integer
+    field :hit_duration, type: Integer
+    field :form_url, type: String
+    field :hit_url, type: String
+    field :hit_id, type: String
+    field :task_type, type: String
+    field :complete, type: Boolean
+    field :completed_assignments, type: Integer, default: 0
+    field :expired, type: Integer
+
+    HIT_FRAMEHEIGHT = 1000
+
+    scope :unprocessed_hits, lambda { where('complete = ? AND sandbox = ?', false, RTurk.sandbox?) }
+
+    # Use this method to go out and retrieve the data for all of the posted Turk Tasks.
+    #  Each specific TurkeeTask object (determined by task_type field) is in charge of
+    #  accepting/rejecting the assignment and importing the data into their respective tables.
+    def self.process_hits(turkee_task = nil)
+
+      begin
+        # Using a lockfile to prevent multiple calls to Amazon.
+        Lockfile.new('/tmp/turk_processor.lock', :max_age => 3600, :retries => 10) do
+
+          turks = task_items(turkee_task)
+
+          turks.each do |turk|
+            hit = RTurk::Hit.new(turk.hit_id)
+
+            callback_models = Set.new
+            hit.assignments.each do |assignment|
+              next unless submitted?(assignment.status)
+              next if assignment_exists?(assignment)
+
+              model, param_hash = map_imported_values(assignment, turk.task_type)
+              next if model.nil?
+
+              callback_models << model
+
+              result = save_imported_values(model, param_hash)
+
+              # If there's a custom approve? method, see if we should approve the submitted assignment
+              #  otherwise just approve it by default
+              turk.process_result(assignment, result)
+
+              TurkeeImportedAssignment.record_imported_assignment(assignment, result, turk)
+            end
+
+            turk.set_expired?(callback_models) if !turk.set_complete?(hit, callback_models)
+          end
+        end
+      rescue Lockfile::MaxTriesLockError => e
+        logger.info "TurkTask.process_hits is already running or the lockfile /tmp/turk_processor.lock exists from an improperly shutdown previous process. Exiting method call."
+      end
+
+    end
+
+    def self.save_imported_values(model, param_hash)
+      key = model.to_s.underscore.gsub('/','_') # Namespaced model will come across as turkee/turkee_study,
+                                                #  we must translate to turkee_turkee_study"
+      model.create(param_hash[key])
+    end
+
+    # Creates a new Mechanical Turk task on AMZN with the given title, desc, etc
+    def self.create_hit(host, hit_title, hit_description, typ, num_assignments, reward, lifetime,
+                        duration = nil, qualifications = {}, params = {}, opts = {})
+      model = typ.to_s.constantize
+      f_url = build_url(host, model, params, opts)
+
+      h = RTurk::Hit.create(:title => hit_title) do |hit|
+        hit.max_assignments = num_assignments if hit.respond_to?(:max_assignments)
+        hit.assignments = num_assignments if hit.respond_to?(:assignments)
+
+        hit.description = hit_description
+        hit.reward = reward
+        hit.lifetime = lifetime.to_i.days.seconds.to_i
+        hit.duration = duration.to_i.hours.seconds.to_i if duration
+        hit.question(f_url, :frame_height => HIT_FRAMEHEIGHT)
+        unless qualifications.empty?
+          qualifications.each do |key, value|
+            hit.qualifications.add key, value
+          end
+        end
+      end
+
+      TurkeeTask.create(:sandbox => RTurk.sandbox?,
+                        :hit_title => hit_title, :hit_description => hit_description,
+                        :hit_reward => reward.to_f, :hit_num_assignments => num_assignments.to_i,
+                        :hit_lifetime => lifetime, :hit_duration => duration,
+                        :form_url => f_url, :hit_url => h.url,
+                        :hit_id => h.id, :task_type => typ,
+                        :complete => false)
+
+    end
+
+    ##########################################################################################################
+    # DON'T PUSH THIS BUTTON UNLESS YOU MEAN IT. :)
+    def self.clear_all_turks(force = false)
+      # Do NOT execute this function if we're in production mode
+      raise "You can only clear turks in the sandbox/development environment unless you pass 'true' for the force flag." if Rails.env == 'production' && !force
+
+      hits = RTurk::Hit.all
+
+      logger.info "#{hits.size} reviewable hits. \n"
+
+      unless hits.empty?
+        logger.info "Approving all assignments and disposing of each hit."
+
+        hits.each do |hit|
+          begin
+            hit.expire!
+            hit.assignments.each do |assignment|
+              logger.info "Assignment status : #{assignment.status}"
+              assignment.approve!('__clear_all_turks__approved__') if assignment.status == 'Submitted'
+            end
+
+            turkee_task = TurkeeTask.where(hit_id: hit.id).first
+            turkee_task.complete_task if turkee_task.present?
+
+            hit.dispose!
+          rescue Exception => e
+            # Probably a service unavailable
+            logger.error "Exception : #{e.to_s}"
+          end
+        end
+      end
+
+    end
+
+    def complete_task
+      self.complete = true
+      save!
+    end
+
+    def set_complete?(hit, models)
+      if completed_assignments?
+        hit.dispose!
+        complete_task
+        initiate_callback(:hit_complete, models)
+        return true
+      end
+
+      false
+    end
+
+    def set_expired?(models)
+      if expired?
+        self.expired = true
+        save!
+        initiate_callback(:hit_expired, models)
+      end
+    end
+
+    def initiate_callback(method, models)
+      models.each { |model| model.send(method, self) if model.respond_to?(method) }
+    end
+
+    def process_result(assignment, result)
+      if result.errors.size > 0
+        logger.info "Errors : #{result.inspect}"
+        assignment.reject!('Failed to enter proper data.')
+      elsif result.respond_to?(:approve?)
+        logger.debug "Approving : #{result.inspect}"
+        self.increment_complete_assignments
+        result.approve? ? assignment.approve!('') : assignment.reject!('Rejected criteria.')
+      else
+        self.increment_complete_assignments
+        assignment.approve!('')
+      end
+    end
+
+    def increment_complete_assignments
+      raise "Missing :completed_assignments attribute. Please upgrade Turkee to the most recent version." unless respond_to?(:completed_assignments)
+
+      self.completed_assignments += 1
+      save
+    end
+
+    private
+
+    def logger
+      @logger ||= Logger.new($stderr)
+    end
+
+    def self.map_imported_values(assignment, default_type)
+      params     = assignment_params(assignment.answers)
+      param_hash = Rack::Utils.parse_nested_query(params)
+
+      model      = find_model(param_hash)
+      model      = default_type.constantize if model.nil?
+
+      return model, param_hash
+    end
+
+    def self.assignment_exists?(assignment)
+      TurkeeImportedAssignment.find_by_assignment_id(assignment.id).present?
+    end
+
+    def completed_assignments?
+      completed_assignments == hit_num_assignments
+    end
+
+    def expired?
+      Time.now >= (created_at + hit_lifetime.days)
+    end
+
+    def self.task_items(turkee_task)
+      turkee_task.nil? ? TurkeeTask.unprocessed_hits : Array.new << turkee_task
+    end
+
+    def self.submitted?(status)
+      (status == 'Submitted')
+    end
+
+    def self.assignment_params(answers)
+      answers.to_query
+    end
+
+    # Method looks at the parameter and attempts to find an ActiveRecord model
+    #  in the current app that would match the properties of one of the nested hashes
+    #  x = {:submit = 'Create', :iteration_vote => {:iteration_id => 1}}
+    #  The above _should_ return an IterationVote model
+    def self.find_model(param_hash)
+      param_hash.each do |k, v|
+        if v.is_a?(Hash)
+          model = k.to_s.camelize.constantize rescue next
+          return model if model.ancestors.include?(Mongoid::Document) rescue next
+        end
+      end
+      nil
+    end
+
+    # Returns custom URL if opts[:form_url] is specified.  Otherwise, builds the default url from the model's :new route
+    def self.build_url(host, model, params, opts)
+      if opts[:form_url]
+        full_url(opts[:form_url], params)
+      else
+        form_url(host, model, params)
+      end
+    end
+
+    # Returns the default url of the model's :new route
+    def self.form_url(host, typ, params = {})
+      @app ||= ActionController::Integration::Session.new(Rails.application)
+      url = (host + @app.send("new_#{typ.to_s.underscore}_path"))
+      full_url(url, params)
+    end
+
+    # Appends params to the url as a query string
+    def self.full_url(u, params)
+      url = u
+      url = "#{u}?#{params.to_query}" unless params.empty?
+      url
+    end
+  end
+end