leap 0.4.6 → 0.5.0

data/.gitignore

@@ -20,3 +20,4 @@ pkg
 
 ## PROJECT::SPECIFIC
 Gemfile.lock
+.yardoc

data/README.markdown

@@ -0,0 +1,250 @@
+# Leap
+
+See also: [RDoc](http://rubydoc.info/github/rossmeissl/leap/master/frames).
+
+Leap is a system for:
+
+1. describing decision-making strategies used to determine a potentially non-obvious attribute of an object
+2. computing that attribute by choosing appropriate strategies given a specific set of input information
+
+At [Brighter Planet](http://brighterplanet.com), we use Leap to determine the carbon footprint of activities like flights that produce some quantity of CO2 emissions. Given, for example, an arbitrary real-life flight, for which we know some subset of its real-life details, Leap uses the most appropriate methodology to arrive at a result.
+
+## Quick start and silly example
+
+``` console
+$ gem install leap
+```
+
+``` ruby
+class Person
+  # attributes: name, age, gender
+
+  include Leap
+  decide :lucky_number do
+    committee :lucky_number do
+      quorum 'look it up in the magic book', :needs => [:name, :age] do |characteristics|
+        MagicBook.lookup(characteristics[:name], characteristics[:age]).lucky_number
+      end
+      quorum 'from lucky color', :needs => :lucky_color do |characteristics|
+        characteristics[:lucky_color].chars.first.unpack('C')
+      end
+    end
+
+    committee :lucky_color do
+      quorum 'guess by gender', :needs => :gender do |characteristics|
+        case characteristics[:gender].to_sym
+        when :male
+          'blue'
+        when :female
+          'pink'
+        end
+      end
+      quorum 'guess by age', :needs => :age do |characteristics|
+        if 14..17.include? characteristics[:age]
+          'black'
+        elsif characteristics[:age] < 5
+          'rainbow'
+        end
+      end
+    end
+    
+    committee :gender do
+      quorum 'look up in a name book', :needs => :name do |characteristics|
+        NameBook.lookup(characteristics[:name]).gender
+      end
+    end
+  end
+end
+```
+
+``` irb
+> Person.new(:age => 28).lucky_number
+ => 42
+```
+
+
+## Extended example
+
+Let's say that somewhere in our Ruby application we need to figure out what time of day it is. Because time of day depends on a frame of reference, we'll consider it as a computable property of a Person.
+
+``` ruby
+class Person < ActiveRecord::Base # using Rails, which is totally optional
+  has_one :watch
+end
+```
+
+Obviously if you have a watch, this is a pretty straightforward problem:
+
+``` ruby
+class Person
+  has_one :watch
+  
+  include Leap
+  decide :time do
+    committee :time do
+      quorum 'look at your watch', :needs => :watch do |characteristics|
+        characteristics[:watch].time
+      end
+    end
+  end
+end
+```
+The `decide :time do . . . end` block is called the *decision*. In this case, we're describing how to decide *time* for a given Person; we say that time is the *goal* of the decision. Leap will define a method on the object named after the decision (in this case, `Person#time`). Calling this method computes the decision.
+
+The `committee :time do . . . end` block is called a *committee*. Committees represent a set of methodologies, all of which are appropriate means of determining its namesake property, in this case *time*. All decision blocks must at the very least provide a committee for the goal; this is implicitly the *master committee*. Typically Leap decisions will involve many more committees, each of which is tasked with determining some intermediate result necessary for the master committee to arrive at a conclusion.
+
+The `quorum 'look at your watch' . . . end` block is called a *quorum*. Quorums describe *one particular way* of reaching the committee's conclusion, along with a list (`:needs`) of what they need to be employed. The `characteristics` blockvar is a curated subset of the object's attributes presented to the quorum (which is in this sense a *closure*) for consideration.
+
+Back to the example. Having a watch does indeed make telling time easy. Complexities arise when you don't; you have to fallback to more intuitive methods.
+
+For example, we can look at the angle of the sun. (I'm going to start abbreviating the code blocks at this point.)
+
+``` ruby
+decide :time do
+  committee :time do
+    quorum 'look at your watch', :needs => :watch do |characteristics|
+      characteristics[:watch].time
+    end
+    quorum 'use a sun chart', :needs => [:solar_elevation, :location] do |characteristics|
+      SunChart.for(characteristics[:location]).solar_elevation_to_time(characteristics[:solar_elevation])
+    end
+  end
+end
+```
+
+But how do we know solar elevation? Or location for that matter? Committees! (Note that committees are always convened in reverse order, from last to first.)
+
+``` ruby
+decide :time do
+  committee :time do
+    quorum 'look at your watch', :needs => :watch # . . .
+    quorum 'use a sun chart', :needs => [:solar_elevation, :location] # . . .
+  end
+  committee :solar_elevation do
+    quorum 'use a solar angle gauge', :needs => :solar_angle_gauge # . . .
+    quorum 'ask a friend', :needs => :friend # . . .
+  end
+  committee :location do
+    quorum 'find out from your GPS', :needs => :gps_device # . . .
+    quorum 'geocode it', :needs => :current_address # . . .
+  end
+end
+```
+
+Surely there is more than one way of determining the Person's current address, so, as you can see, a dozen or more committees, each with several quorums, would be necessary to completely describe the intuitive process that we humans use to figure out something as simple as the likely time of day. This is a useful way to think about Leap: it's a non-learning artifical intelligence system that attempts to model human intuition by describing heuristic strategies.
+
+Now that we've looked at an overview of the Leap system, let's look at each component in depth, from the inside (characteristics) out (decisions).
+
+## Characteristics
+
+The computation of a Leap decision requires a curated set of properties of the host object. In the examples above, you'll see that each quorum receives a `characteristics` hash. Where does this come from?
+
+By default, Leap will dynamically construct a characteristics hash out of the object's instance variables. This is definitely a stopgap solution though; much better is to provide a method on the object that returns a *curated* set of properties ("characteristics") and specify it to Leap using the `:with` option on the `decide` block:
+
+``` ruby
+class Person < ActiveRecord::Base
+  def characteristics
+    attributes.slice :name, :age, :gender
+  end
+  
+  include Leap
+  decide :lucky_number, :with => :characteristics
+    # . . .
+  end
+end
+```
+
+Even better is to use a library like [Charisma](http://github.com/brighterplanet/charisma) that does the curation for you:
+
+``` ruby
+class Person < ActiveRecord::Base
+  include Charisma
+  characterize do
+    has :name
+    has :age
+    has :gender
+  end
+  
+  include Leap
+  decide :lucky_number, :with => :characteristics
+    # . . .
+  end
+end
+```
+
+When it comes time to compute your decision block, Leap will call your characteristics method, duplicate the resulting hash, and send it into the decision. The hash gets handed from one committee to the next, with each committee inserting its conclusion. In this way, the hash accumulates increasing knowledge about the object until it reaches the master committee for final determination.
+
+It's worth noting that often a decision block will have committees that correspond exactly (by name) with attributes in the characteristics hash. That's because there's never a guarantee that all of the object's attributes will be non-nil. If an attribute is directly provided by the object, the corresponding committee will never be called.
+
+## Defining quorums
+
+Quorums are encapsulated methodologies for determining something, given a
+specific set of inputs.
+
+``` ruby
+class Automobile
+  include Leap
+  decide :total_cost_of_ownership do
+    # . . .
+    committee :annual_insurance_premium do
+      # . . .
+      quorum 'from type of automobile', :needs => [:make, :model], :appreciates => :color do |characteristics|
+        premium = Automobile.scoped(:make => characteristics[:make], :model => characteristics[:model]).average(:annual_claims_total) * 1.2 # profit!
+        premium += 100 if characteristics[:color] == 'red'
+        premium
+      end
+      # . . .
+    end
+    # . . .
+  end
+end
+```
+
+This is an example from a total cost of ownership model. In this case, the annual insurance premium can, among other ways, be calculated from the type of automobile. In order for this methodology to be employable, we need to know, or Leap must have already determined (by a prior committee) the automobile's make and model. If it's available, the automobile's color will also help.
+
+The quorum block gets stored as a closure for later use; the `:needs` act as a gatekeeper. If, during computation, available characteristics satisfy the quorum's requirements, then the *subset* of those characteristics that are actually *asked for* (via `:needs` or `:appreciates`) is provided to the block.
+
+## Committees
+
+Committees are charged with producing a single value, as defined by its name, and, in pursuit of this value, identifying and acknowledging its most appropriate quorum to return this value, given available input information.
+
+Quorums are always considered top-to-bottom. When called, the committee assesses each quorum, checking to see if its needs are satisfied by available information. The first satisfied quorum is acknowledged. If its conclusion is non-nil, it becomes the committee's conclusion; if it is nil, then the committee continues to the next satisfied quorum. If no conclusion is possible, the committee returns a nil result.
+
+## Decisions
+
+Decisions are ordered groups of committees fashioned to provide a number of pathways to a single result (the goal). Committees are always called bottom-to-top, so that progressively more information becomes known about the object, ultimately reaching the master committee that provides the result of the decision. Leap begins with the curated characteristics hash described above. It submits this hash to the first committee (the bottom one), which produces some result. This result is added to the characteristics hash, which is then submitted to the next committee, and so on, until the final (top) committee is called, benefiting from all of the intermediate committee conclusions.
+
+## Compliance
+
+Leap is all about providing numerous methods for arriving at a conclusion. But inevitably that means that some <del>unsavory</del> unorthodox quorums will make their way into your committees, and sometimes you'll want to restrict your decisions to conventional approaches. Leap supports this with its *compliance system*.
+
+Just mark certain quorums as complying with certain protocols:
+
+``` ruby
+quorum 'outside the box', :needs => :type do |characteristics|
+  # . . .
+end
+quorum 'mind the red tape', :needs => :type, :complies => :the_rules do |characteristics|
+  # . . .
+end
+```
+
+and then perform your decision with a protocol constraint:
+
+``` irb
+> Person.lucky_number :comply => :the_rules
+ => 99
+```
+
+You can name your protocols how ever you want; they just have to match between the quorum assertions and the decision option.
+
+## Internals
+
+Normally you'll construct your decision strategies using `decide :foo . . . end` blocks and perform them using the resulting `#foo` methods, but sometimes you'll want access to Leap's internals.
+
+* All decisions are stored as Leap::Decision objects in the host class's `@decisions` variable. Leap provides a `#decisions` accessor.
+* When a decision is *computed* for a specific instance, it is stored as a Leap::Deliberation in the instance's `@deliberations` variable. Leap provides a `#deliberations` accessor. 
+
+## Copyright
+
+Copyright (c) 2010 Andy Rossmeissl.

data/Rakefile

@@ -1,6 +1,9 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
+require 'bueller'
+Bueller::Tasks.new
+
 require 'rake'
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
@@ -8,6 +11,7 @@ Rake::TestTask.new(:test) do |test|
   test.pattern = 'test/**/test_*.rb'
   test.verbose = true
 end
+task :default => :test
 
 begin
   require 'rake/rdoctask'

data/leap.gemspec

@@ -1,27 +1,28 @@
-# -*- encoding: utf-8 -*-
-$:.push File.expand_path("../lib", __FILE__)
-require "leap/version"
-
-Gem::Specification.new do |s|
-  s.name        = "leap"
-  s.version     = Leap::VERSION
-  s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Andy Rossmeissl", "Seamus Abshere"]
-  s.email       = "andy@rossmeissl.net"
-  s.homepage    = "http://github.com/rossmeissl/leap"
-  s.summary     = %Q{A heuristics engine for your Ruby objects}
-  s.description = %Q{Leap to conclusions}
-
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  s.require_paths = ["lib"]
-  
-  s.add_development_dependency "characterizable", ">=0.0.11"
-  s.add_development_dependency "shoulda"
-  s.add_dependency 'blockenspiel', '>=0.3.2'
-  s.add_dependency 'activesupport', '>=2.3.4'
-  # sabshere 1/27/11 for activesupport - http://groups.google.com/group/ruby-bundler/browse_thread/thread/b4a2fc61ac0b5438
-  s.add_dependency 'i18n'
-  s.add_dependency 'builder'
-end
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "leap/version"
+
+Gem::Specification.new do |s|
+  s.name        = "leap"
+  s.version     = Leap::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Andy Rossmeissl", "Seamus Abshere", "Derek Kastner"]
+  s.email       = "andy@rossmeissl.net"
+  s.homepage    = "http://github.com/rossmeissl/leap"
+  s.summary     = %Q{A heuristics engine for your Ruby objects}
+  s.description = %Q{Leap to conclusions}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_development_dependency "charisma", '~>0.2.0'
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency 'bueller'
+  s.add_dependency 'blockenspiel', '>=0.3.2'
+  s.add_dependency 'activesupport', '>=2.3.4'
+  # sabshere 1/27/11 for activesupport - http://groups.google.com/group/ruby-bundler/browse_thread/thread/b4a2fc61ac0b5438
+  s.add_dependency 'i18n'
+  s.add_dependency 'builder'
+end

data/lib/leap.rb

@@ -9,7 +9,6 @@ end if ActiveSupport::VERSION::MAJOR == 3
 require 'blockenspiel'
 
 require 'leap/core_ext'
-require 'leap/xml_serializer'
 require 'leap/subject'
 require 'leap/committee'
 require 'leap/quorum'
@@ -17,11 +16,16 @@ require 'leap/decision'
 require 'leap/report'
 require 'leap/deliberation'
 require 'leap/implicit_attributes'
+require 'leap/no_solution_error'
+require 'leap/deliberations_accessor'
+require 'leap/goal_methods_documentation'
 
+# Leap is a system for: 1) describing decision-making strategies used to determine a potentially non-obvious attribute of an object and 2)
+# computing that attribute by choosing appropriate strategies given a specific set of input information
 module Leap
+  # Injects <tt>Leap::Subject</tt> into the host class
+  # @see Subject
   def self.included(base)
     base.extend ::Leap::Subject
   end
-  
-  class NoSolutionError < ArgumentError; end
 end

data/lib/leap/committee.rb

@@ -1,44 +1,70 @@
 module Leap
+  # One of the basic building blocks of a Leap decision.
+  #
+  # Committees represent computable attributes of a subject instance and facilitate multiple means of computing these attributes. In some cases, you will
+  # define committees that match the names of attributes that can be explicitly set on a subject; in this case, the committees are only useful when
+  # a particular instance does not have this attribute set. In other cases, committees are part of internal logic within the Leap decision, providing
+  # intermediate results in pursuit of the decision's ultimate goal.
+  #
+  # As a Leap decision is made, it approaches each committee in turn, providing it with its current knowledge of the subject. The committee accepts this information, determines an appropriate methodology, and returns additional information about the subject. This newly-augmented knowledge about the subject is then passed to the next committee for further augmentation, and so forth. 
+  #
+  # Committees are composed of one or more quorums (<tt>Leap::Quorum</tt> objects) that encapsulate specific methodologies for drawing the committee's conclusion. This composition is defined within the <tt>Leap::Decision#committee</tt> block using the <tt>Leap::Committee#quorum</tt> DSL.
+  # @see Leap::Quorum
   class Committee
-    include XmlSerializer
 
-    attr_reader :name, :quorums
+    # The name of the committee, traditionally formulated to represent a computable attribute of the subject.
+    attr_reader :name
     
+    # The array of quorums defined within the committee.
+    attr_reader :quorums
+    
+    # Creates a new <tt>Leap::Committee</tt> with the given name.
+    #
+    # Generally you don't create these objects directly; <tt>Leap::Decision#committee</tt> does that for you.
+    #
+    # @see Leap::Decision#committee
+    # @param [Symbol] name The name of the committee, traditionally formulated to represent a computable attribute of the subject.
     def initialize(name)
       @name = name
       @quorums = []
     end
     
-    def report(subject, characteristics, considerations, options = {})
+    # Instructs the committee to draw its conclusion.
+    #
+    # Steps through each quorum defined within the committee in search of one that can be called with the provided characteristics and is compliant with the requested protocols. Upon finding such a quorum, it is called. If a conclusion is returned, it becomes the committee's conclusion; if not, the quorum-seeking process continues.
+    #
+    # Generally you will not call this method directly; <tt>Leap::Decision#make</tt> requests reports at the appropriate time.
+    # @param [Hash] characteristics What we know so far about the subject.
+    # @param [Array] considerations Auxiliary contextual details about the decision (see <tt>Leap::GoalMethodsDocumentation</tt>)
+    # @param [optional, Hash] options
+    # @option comply Compliance constraint. See <tt>Leap::GoalMethodsDocumentation</tt>.
+    # @see Leap::GoalMethodsDocumentation
+    # @return Leap::Report
+    def report(characteristics, considerations, options = {})
       quorums.grab do |quorum|
         next unless quorum.satisfied_by? characteristics and quorum.complies_with? Array.wrap(options[:comply])
         if conclusion = quorum.acknowledge(characteristics.slice(*quorum.characteristics), considerations.dup)
-          ::Leap::Report.new subject, self, quorum => conclusion
-        end
-      end
-    end
-
-    def as_json(*)
-      {
-        'name' => name.to_s,
-        'quorums' => quorums.map(&:as_json)
-      }
-    end
-
-    def to_xml(options = {})
-      super options do |xml|
-        xml.committee do |committee_block|
-          committee_block.name name.to_s, :type => 'string'
-          array_to_xml(committee_block, :quorums, quorums)
+          ::Leap::Report.new self, quorum => conclusion
         end
       end
     end
     
     include ::Blockenspiel::DSL
+    
+    # Defines a quorum within this committee.
+    #
+    # A quorum encapsulate a specific methodology for drawing the committe's conclusion.
+    # @param [String] name A descriptive name for this methodology.
+    # @param [optional, Hash] options
+    # @yield The quorum's methodology, as a Ruby closure. You may define your block with any number of block vars. If zero, the methodology requires no outside information (useful for "default" quorums). If one, Leap will provide the characteristics hash, accumulated over the course of the deliberation, that represents its total knowledge of the subject at the time. (Note that Leap will actually provide only a subset of the characteristics hash--namely, only attributes that are specifically requested by the <tt>:needs</tt> and <tt>:wants</tt> options below.) If more than one, additional block vars will be filled with as many considerations (given during <tt>Leap::Decision#make</tt>) as is necessary.
+    # @option [Symbol, Array] needs An attribute (or array of attributes) which must be known at the time of the committee's assembly for the quorum to be acknowledged.
+    # @option [Symbol, Array] wants An attribute (or array of attributes) which are useful to the methodology, but not required.
+    # @option complies A protocol (or array of protocols) with which this particular quorum complies. See <tt>Leap::GoalMethodsDocumentation</tt>.
     def quorum(name, options = {}, &blk)
       @quorums << ::Leap::Quorum.new(name, options, blk)
     end
     
+    # Convenience method for defining a quorum named "default" with no needs, wants, or compliances.
     def default(options = {}, &blk)
       quorum 'default', options, &blk
     end

data/lib/leap/core_ext.rb

@@ -1,5 +1,5 @@
 class Array
-  # like detect, but returns the calculated value
+  # Like <tt>Array#detect</tt>, but returns the calculated value
   def grab(&blk)
     result = each do |element|
       value = yield element