shared_workforce 0.1.2 → 0.2.0

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  # - rbx-19mode # currently in active development, may or may not work for your project
+# uncomment this line if your project needs to run something other than `rake`:
+script: bundle exec rspec spec

data/Gemfile

@@ -2,3 +2,7 @@ source "http://rubygems.org"
 
 # Specify your gem's dependencies in hci.gemspec
 gemspec
+
+platforms :jruby do
+  gem "jruby-openssl"
+end

data/README.markdown

@@ -1,6 +1,8 @@
 Shared Workforce Client
 =======================
 
+[![Build Status](https://secure.travis-ci.org/samoli/shared-workforce.png)](http://travis-ci.org/#!/samoli/shared-workforce)
+
 Shared Workforce is a platform for managing and completing repetitive tasks that require human intelligence. For example, tagging photos, approving text and answering simple questions.
 
 It differs from other similar services in the following ways:
@@ -43,47 +45,47 @@ If you're not using Rails, simply require the gem or include it in your Gemfile,
 
 Create a directory called 'tasks' in the root of your app. This is where you define your tasks - all files in this directory will be loaded.
 
-If, for example, you would like to have a photo tagged on upload, create your first task in a file called tasks/tag_photo.rb
+If, for example, you would like to approve a photo on upload, create your first task in a file called tasks/approve_photo.rb   
+    
+    class ApprovePhotoTask
+      include SharedWorkforce::Task
 
-    SharedWorkforce::Task.define "Tag photo" do |t|
-  
-      t.directions = "Look at this photo. Please tick all that apply."
-      t.answer_options = ['Offensive', 'Contains Nudity', 'Blurry or low quality']
-      t.answer_type = :tags
-      t.responses_required = 1
-      t.replace = true
-
-      t.on_completion do |result|
-        photo = Photo.find(result.callback_params['photo_id'])
-        if result.answers.include?('Offensive')
+      title 'Approve Photo'
+
+      instruction 'Look at this photo. Please tick all that apply.'
+      responses_required 1
+
+      answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
+      answer_type :tags
+      image_url "http://www.google.com/logo.png"
+
+      on_success :moderate_photo
+
+      def moderate_photo(photo, responses)
+        if responses.map { |r| r[:answer] }.include?('Offensive')
           photo.hide!
-          photo.add_comment("Photo hidden because it was offensive")
-        elsif result.answers.include?('Contains Nudity')
-          photo.refer!
-          photo.add_comment("Photo referred because it contains nudity")
-        else
-          photo.approve!
+          photo.add_comment("Photo is offensive")
         end
+        puts "Photo Moderated"
       end
-
+      
     end
+    
 
 ### Step 4 - request tasks
 
-Publishing tasks is simply a case of calling SharedWorkforce::Task.request(name, options).  If you are using Rails, this could be done in an after save callback on a model:
+Publishing tasks is simply a case of calling `TaskClass.create()`.  If you are using Rails, this could be done in an after save callback on a model:
 
     class Photo < ActiveRecord::Base
     
-      after_create :request_tags
+      after_create :approve_photo
     
-      def request_tags
-        SharedWorkforce::Task.request "Tag photo", {:image_url => self.url, :callback_params => { :photo_id => self.id} }
+      def approve_photo
+        ApprovePhotoTask.create(self)
       end
     end
 
 
-That's it - once your task is completed the callback you have defined in the task definition will be called. Everything you define in the :callback_params option will be sent back to your callback as shown in the example.
-
 Advanced definition options
 ----------------------------------------
 
@@ -99,27 +101,34 @@ SharedWorkforce currently supports 2 types of task. :tags (multiple select) and
 
 SharedWorkforce supports multiple responses for each task. The callback method provides you with an array of responses from multiple workers. You can create your own logic to decide what to do. This is useful if you want to prevent destructive action unless a number of workers agree.
 
-    SharedWorkforce::Task.define "Tag photo" do |t|
-  
-      t.directions = "Look at this photo. Please tick all that apply."
-      t.answer_options = ['Offensive', 'Contains Nudity', 'Blurry or low quality']
-      t.answer_type = :tags
-      t.responses_required = 3
-
-      t.on_completion do |result|
-        photo = Photo.find(result.callback_params['photo_id'])
-        photo.hide! if result.answers.all? { |a| a == 'Contains Nudity' }
+    class ApprovePhotoTask
+      include SharedWorkforce::Task
+
+      title 'Approve Photo'
+
+      instruction 'Look at this photo. Please tick all that apply.'
+      responses_required 3
+
+      answer_options ['Offensive', 'Contains Nudity', 'Blurry or low quality', 'Upside down or sideways']
+      answer_type :tags
+
+      on_complete :moderate_photo
+
+      def moderate_photo(photo, responses)
+        photo.hide! if responses.map { |r| r[:answer] }.all? { |a| a.include?('Contains Nudity') }
       end
 
     end
+    
 
 ###Replacing tasks
 
 The "replace" option allows you to overwrite or update any existing tasks with the same name and callback params. This could be useful in the example to handle the situation where a user re-uploads their photo - you may only care about the latest one.
 
-    SharedWorkforce::Task.define "Tag photo" do |t|
+    class ApprovePhotoTask
+      include SharedWorkforce::Task
       ...
-      t.replace=true
+      replace true
       ...  
     end
 
@@ -127,11 +136,11 @@ The "replace" option allows you to overwrite or update any existing tasks with t
 
 You can cancel tasks when they are no longer relevant.
  
-    class Photo < ActiveRecord::Base
+    class Photo
       after_destroy :cancel_tagging_request
 
       def cancel_tagging_request
-        SharedWorkforce::Task.cancel "Classify photo", :callback_params=>{:photo_id=>self.id})
+        ApprovePhotoTask.cancel(self)
       end
     end
 

data/lib/shared_workforce/client.rb

@@ -1,17 +1,9 @@
 module SharedWorkforce
   class Client
     class << self
-      attr_accessor :load_path
-      
       def version
         SharedWorkforce::VERSION
       end
-    
-      def load!
-        Dir[File.join(load_path, "*.rb")].each do |file|
-          load file
-        end
-      end
     end
   end
 end

data/lib/shared_workforce/configuration.rb

@@ -2,7 +2,6 @@ module SharedWorkforce
   class Configuration
     
     attr_accessor :api_key
-    attr_accessor :load_path
     attr_accessor :http_end_point
     attr_accessor :callback_host
     attr_accessor :request_class
@@ -10,7 +9,6 @@ module SharedWorkforce
     
     def initialize
       @http_end_point = "http://api.sharedworkforce.com"
-      @load_path = "tasks"
       @request_class = TaskRequest::Http
     end
     

data/lib/shared_workforce/exceptions.rb

@@ -1,4 +1,5 @@
 module SharedWorkforce
   class Error < RuntimeError; end
   class ConfigurationError < Error; end
+  class TaskNotFound < Error; end
 end

data/lib/shared_workforce/frameworks/rails.rb

@@ -2,13 +2,6 @@ if defined?(ActionController::Metal)
   class Railtie < Rails::Railtie
     initializer 'shared_workforce' do |app|      
       app.config.middleware.use SharedWorkforce::EndPoint
-      SharedWorkforce::Client.load_path = Rails.root + SharedWorkforce.configuration.load_path
-      SharedWorkforce::Client.load!
     end
   end
-else
-  Rails.configuration.after_initialize do
-    SharedWorkforce::Client.load_path = Rails.root + SharedWorkforce.configuration.load_path
-    SharedWorkforce::Client.load!
-  end
 end

data/lib/shared_workforce/task.rb

@@ -1,94 +1,146 @@
 module SharedWorkforce
-  class Task
-    
-    class << self
-    
-      attr_accessor :tasks
-    
-      def tasks
-        @tasks ||= {}
+  module Task
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.default_attributes(
+        :title,
+        :answer_type,
+        :instruction,
+        :responses_required,
+        :replace,
+        :answer_options,
+        :image_url,
+        :text,
+        :on_success,
+        :on_failure,
+        :on_complete
+      )
+    end
+
+    module ClassMethods
+      
+      def default_attributes(*args)
+        if args.count > 0
+          args.each do |name|
+           class_eval %(
+              class << self
+                def #{name}(value)
+                  set_default_attribute(:#{name}, value)
+                end
+              end
+
+              attr_accessor :#{name}
+            )
+          end
+        else
+          @default_attributes || {}
+        end
       end
 
-      def define(name, &block)
-        task = self.new
-        task.name = name
-        yield task
-        self.tasks[name] = task
+      def set_default_attribute(name, value)
+        @default_attributes ||= {}
+        @default_attributes[name] = value
       end
-    
-      def request(name, options)
-        @tasks[name].request(options)
+
+      def get_default_attribute(name)
+        @default_attributes ||= {}
+        @default_attributes[name]
       end
-      
-      def cancel(name, options)
-        @tasks[name].cancel(options)
+
+      def create(*args)
+        task = new(*args)
+        task.request
+        task
       end
-    
-      def find(name)
-        self.tasks[name]
+
+      def cancel(*args)
+        task = new(*args)
+        task.cancel
+        task
       end
-    
-      def clear!
-        @tasks = {}
+
+    end # ends ClassMethods
+
+    attr_reader :attributes
+
+    def initialize_default_attributes
+      self.class.default_attributes.each do |name, value|
+        instance_variable_set("@#{name}", value)
       end
-  
     end
-  
-    attr_accessor :name
-    attr_accessor :directions
-    attr_accessor :image_url
-    attr_accessor :answer_options
-    attr_accessor :answer_type
-    attr_accessor :responses_required
-    attr_accessor :replace # whether tasks with the same resource id and name should be overwritten
-
-    def replace
-      @replace ||= false
+
+    def initialize(resource_or_result=nil, attributes=nil)
+      initialize_default_attributes
+      if resource_or_result.is_a?(TaskResult)
+        @result = resource_or_result
+        process_result(@result)
+      elsif resource_or_result
+        unless resource_or_result.respond_to?(:id) && resource_or_result.class.respond_to?(:find)
+          raise ArgumentError, "The resource you pass to new should respond to #id and it's class should respond to .find (or be an instance of ActiveRecord::Base) so it can be reloaded."
+        end 
+        @resource = resource_or_result
+        initialize_attributes(attributes)
+      end
+      
+      setup(resource) if respond_to?(:setup)
     end
-  
-    def request(options)
+
+    def process_result(result)
+      initialize_attributes(result.callback_params)
+      success!(result)
+      complete!(result)
+    end
+
+    def success!(result)
+      send(@on_success.to_sym, resource, result.responses) if @on_success
+    end
+
+    def complete!(result)
+      send(@on_complete.to_sym, resource, result.responses) if @on_complete
+    end
+
+    def fail!(result)
+      send(@on_failure.to_sym, resource, result.responses) if @on_failure
+    end
+
+    def resource
+      @resource ||= find_resource
+    end
+
+    def request(options = {})
       task_request = remote_request(self, options)
       task_request.create
     end
     
-    def cancel(options)
+    def cancel(options = {})
       task_request = remote_request(self, options)
       task_request.cancel
     end
   
     def to_hash
       {
-        :name=>name,
-        :directions => directions,
+        :title => title,
+        :instruction => instruction,
         :image_url => image_url,
         :answer_options => answer_options,
         :responses_required => responses_required,
         :answer_type => answer_type.to_s,
         :callback_url => callback_url,
-        :replace => replace
-      }
-    end
-  
-    # Callbacks
-  
-    def on_completion(&block)
-      @on_complete_proc = block
-    end
-  
-    def complete!(results)
-      @on_complete_proc.call(results) if @on_complete_proc
-    end
-  
-    def on_failure(&block)
-      @on_failure_proc = block
+        :replace => replace,
+        :text => text,
+        :callback_params => attributes
+      }.reject {|k,v| v.nil? }
     end
-  
-    def fail!(results)
-      @on_failure_proc.call(results) if @on_failure_proc
+
+  private
+
+    def find_resource
+      if @result && @result.callback_params[:_task] && resource_params = @result.callback_params[:_task][:resource]
+        resource_params[:class_name].constantize.find(resource_params[:id])
+      end
     end
     
-    private
-    
     def callback_url
       SharedWorkforce.configuration.callback_url
     end
@@ -96,5 +148,17 @@ module SharedWorkforce
     def remote_request(*args)
       SharedWorkforce.configuration.request_class.new(*args)
     end
+
+    def initialize_attributes(attributes)
+      @attributes = if attributes
+        attributes.with_indifferent_access
+      else
+        {}
+      end
+
+      @attributes[:_task] = {:class_name => self.class.name}
+      @attributes[:_task][:resource] = {:class_name => @resource.class.name, :id => @resource.id} if @resource
+    end
+
   end
 end

data/lib/shared_workforce/task_request/task_request.rb

@@ -24,6 +24,10 @@ module SharedWorkforce
     def api_key
       SharedWorkforce.configuration.api_key
     end
+
+    def task
+      @task
+    end
     
   end
 end

data/lib/shared_workforce/task_response.rb

@@ -4,7 +4,11 @@ module SharedWorkforce
     def self.create_collection_from_array(ary)
       ary.collect {|r| TaskResponse.new(r) }
     end
-  
+    
+    def to_hash
+      {:answer=>answer, :answered_by=>username}
+    end
+
     attr_accessor :answer, :callback_params, :username
     
     def initialize(params)

data/lib/shared_workforce/task_result.rb

@@ -7,26 +7,31 @@ module SharedWorkforce
     attr_accessor :status
     
     def initialize(params)
-      self.callback_params = params['callback_params']
-      self.responses = TaskResponse.create_collection_from_array(params['responses'])
-      self.name = params['name']
+      params = params.with_indifferent_access
+      self.callback_params = params[:callback_params]
+      @responses = TaskResponse.create_collection_from_array(params[:responses]) if params[:responses]
+      self.name = callback_params[:_task][:class_name] if callback_params && callback_params[:_task] && callback_params[:_task][:class_name]
     end
     
-    def answers
-      responses.map(&:answer).flatten
+    def responses
+      @responses.map(&:to_hash)
     end
     
     def usernames
-      responses.map(&:username).flatten
+      @responses.map(&:username).flatten
     end
     
     def process!
-      if task = Task.find(name)
-        task.complete!(self)
+      if name && task = find_task(name)
+        task.new(self)
       else
-        raise "The task #{name} could not be found"
+        raise TaskNotFound, "The task #{name} could not be found"
       end
     end
    
+  private
+    def find_task(name)
+      name.constantize
+    end
   end
 end

data/lib/shared_workforce/version.rb

@@ -1,4 +1,4 @@
 module SharedWorkforce
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 
 end

data/lib/shared_workforce.rb

@@ -10,6 +10,8 @@ require 'shared_workforce/task_result'
 require 'shared_workforce/task_response'
 require 'shared_workforce/end_point'
 require 'shared_workforce/frameworks/rails' if defined?(Rails)
+require 'active_support/inflector'
+require 'active_support/core_ext/hash/indifferent_access'
 
 module SharedWorkforce
   

data/shared_workforce.gemspec

@@ -8,14 +8,15 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Sam Oliver"]
   s.email       = ["sam@samoliver.com"]
-  s.homepage    = "http://github.com/pigment/shared_workforce"
+  s.homepage    = "http://github.com/sharedworkforce/sharedworkforce"
   s.summary     = %q{Shared Workforce Client}
   s.description = %q{Shared Workforce is a service and simple API for human intelligence tasks}
 
-  s.rubyforge_project = "shared_workforce_client"
+  s.rubyforge_project = "shared_workforce"
   
   s.add_dependency "rest-client"
   s.add_dependency "json"
+  s.add_dependency "activesupport"
   s.add_development_dependency "rspec", ">= 1.2.9"
   s.add_development_dependency "webmock"
   

data/spec/client_spec.rb

@@ -1,13 +1,6 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
 describe "Client" do
-  it "should load tasks" do
-    SharedWorkforce::Client.load_path = File.dirname(__FILE__) + '/tasks'
-    SharedWorkforce::Client.load!
-    
-    SharedWorkforce::Task.find("Approve photo").should_not == nil
-  end
-  
   it "should return the current version number" do
     SharedWorkforce::Client.version.should == SharedWorkforce::VERSION
   end

data/spec/spec_helper.rb

@@ -8,12 +8,10 @@ require 'webmock/rspec'
 # Requires supporting ruby files with custom matchers and macros, etc,
 # in spec/support/ and its subdirectories.
 Dir[File.join(File.expand_path('../support', __FILE__), '**/*.rb')].each {|f| require f}
+Dir[File.join(File.expand_path('../tasks', __FILE__), '**/*.rb')].each {|f| require f}
 
 RSpec.configure do |config|
   config.color_enabled = true
-  config.after :each do
-    SharedWorkforce::Task.clear!
-  end
   
   config.before :each do
     SharedWorkforce.configure do |config|

data/spec/task_request/black_hole_spec.rb

@@ -3,7 +3,7 @@ require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
 describe "TaskRequest::BlackHole" do
   describe "#create" do
     it "should not make an HTTP request" do
-      task_request = SharedWorkforce::TaskRequest::BlackHole.new(SharedWorkforce::Task.find("Approve photo"), :callback_params=>{:resource_id=>'1234'})
+      task_request = SharedWorkforce::TaskRequest::BlackHole.new(ApprovePhotoTask.new, :callback_params=>{:resource_id=>'1234'})
       task_request.create
       a_request(:any, "api.sharedworkforce.com/tasks").should_not have_been_made
     end
@@ -11,7 +11,7 @@ describe "TaskRequest::BlackHole" do
   
   describe "#cancel" do
     it "should not make an HTTP request" do
-      task_request = SharedWorkforce::TaskRequest::BlackHole.new(SharedWorkforce::Task.find("Approve photo"), :callback_params=>{:resource_id=>'1234'})
+      task_request = SharedWorkforce::TaskRequest::BlackHole.new(ApprovePhotoTask.new, :callback_params=>{:resource_id=>'1234'})
       task_request.create
       a_request(:any, "api.sharedworkforce.com/tasks/cancel").should_not have_been_made
     end