AutoMan: Human-Computation Runtime v0.3
---------------------------------------

This is a preliminary release of AutoMan.  Please report any bugs you
may find to the project maintainer, Dan Barowy <[email protected]>.

Presently, we have only tested AutoMan with Scala programs.  In
principle, Java can use AutoMan as-is, but adding official support is
currently on our TODO list.

License
-------

AutoMan is licensed under the GPLv2, Copyright (C) 2011-2012 The
University of Massachusetts, Amherst.

Compiling AutoMan
-----------------

To use AutoMan, you will need to compile a JAR.  Currently, this is
a manual process, and you will need to fetch all of the required
libraries manually.  We are putting together an Apache Buildr script
that will do this for you, and we will add this file to the repository
shortly.

Building the JAR
----------------

This release incorporates a Buildr script that can build the AutoMan JAR
for you, including downloading all of AutoMan's dependencies.  The build
script can also build the sample applications that are located in the
'apps' directory.  These applications are the ones used in our paper.

Buildr is a build dependency system somewhat like a cross between 'make'
and Maven.  It is based on the 'rake' program that ships with Ruby.  If
you already have Ruby and RubyGems installed on your system (comes with
most Macs), simply issue the following command to install Buildr:

  sudo gem install buildr

You can build the entire project using the following Buildr command when
your current working directory is at the root of the AutoMan project
directory:

  buildr build
  
You can build specific applications like:

  buildr build automan:apps:anpr
  
Consult the Buildr documentation if you are interested in learning more
of Buildr's commands (http://buildr.apache.org/).

Using AutoMan in Your Project
-----------------------------

In your source file, import the Mechanical Turk adapter (Scala syntax):

  import edu.umass.cs.automan.adapters.MTurk.MTurkAdapter

After that, initialize the AutoMan runtime with an MTurk config and
define your tasks.  You may then call those tasks like regular
functions.  Note that these functions return immediately, as calling
a human function runs in a separate background thread.

In order to access data returned by the function, you must call
apply on the object returned by the function and then access the
"value" field in the Answer object, as human functions return
Future[Answer] objects.  E.g.,

  val answer = human_function(args)
  answer().value

Please see the collection of sample programs in the "sample_programs"
directory. This folder contains the programs we used in the technical
report (see below).

Using AutoMan with a Different Crowdsourcing Backend
----------------------------------------------------

We currently only support Amazon's Mechanical Turk.  However, AutoMan
was designed to accommodate arbitrary backends.  If you are interested
in seeing your backend supported, please contact Dan Barowy.

However, we are happy to work with you to ensure that you have all of
the information you need to write your adapter library. We will also fix
any compatibility problems with the AutoMan runtime that you might
encounter along the way.

Memoization
-----------

AutoMan saves all intermediate human-computed results.  In the event
of a program exception or unexpected termination, the programmer may
restart AutoMan and it will reuse any previously-obtained results.  If
you want to discard these intermediate results, delete the
AutomanMemoDB file.  The format of this database is Apache Derby 10.8.

More Information
----------------

More detailed information is available in a preprint of our paper
(to appear at OOPSLA 2012):

  AutoMan: A Platform for Integrating Human-Based and Digital Computation
  Daniel W. Barowy, Charlie Curtsinger, Emery D. Berger, and Andrew McGregor

  http://www.cs.umass.edu/~emery/pubs/res0007-barowy.pdf
  
Please contact us if you plan to cite this work as there may be a more
up-to-date citation.

Contact information:

  Emery Berger, [email protected]
  Dan Barowy, [email protected]
  
CHANGELOG:
----------
0.3:	Maintenance release.
		• Buildr Buildfile, including reorganization of project directory.
0.2.1:	Maintenance release.
		• Update to work with latest MTurk API (1.6.0).  
		• Better log output, including scheduler object logging.
		• New Automatic Number Plate Recognition (ANPR) app.
0.2:	Major rewrite to simplify syntax.
0.1:	First release.