# SCRIPTER
# Author: Nate Derbinsky (2012)
#
# Purpose: takes as input a hierarchical, probabilistic plan template and outputs a script
#
# Description:
#   A plan comprises either a set or sequence of actions (i.e. fixed/arbitrary ordering).
#   Actions are added to the script based upon a conjunctive set of constraints (variable name/value pairs).
#   Actions themselves may themselves be a plan; script generation proceeds in a depth first manner (arbitrarily deep, limited by Soar stack depth).
#
#   Plan variables are symbolic and have at least a type and name.
#   The only supported types are { multi, given, binary }.
#   "multi" variables are controlled via a "cpt" (conditional-probability table) which is a set of "entry" rows.
#   Entries pair conjunctive-variable constraints with probabilistic value probabilities (i.e. "under these conditions, these are the chances of the following variable values").
#   Two time-saving options are supported: a "default" value can be supplied (in case no condition rules match) and more specific rules (i.e. more constraints) are automatically chosen over less specific (similar to conflict resolution in rule-based systems).
#   "given" and "binary" are just special cases of "multi" supplied to save time.
#   "given" variables are supplied a single "value" (designed for inputs supplied by the user).
#   "binary" variables are full "multi" variables which assumes special values of "true" and "false" such that the system automatically fills in the unsupplied value for each entry with (1-p) probability.
#
#   Before appending plan actions to the script, variables are assigned values in the "kb" (knowledge base) based upon other variable values and constraints.
#   Variable-value assignment proceeds opportunistically as constraints are met (with random assignment between mutually satisfiable variables).
#   Cyclic variable dependencies are not supported (i.e. acyclic constraints only).
#   Probabilistic selection is from a softmax distribution; alternative distributions (e.g. normal) should be handled externally (e.g. via "given" variables).
#
#   An example plan is supplied in fake-plans and fake-vars files.
#   They condition upon there not existing <input-link>.real, an easy flag to bypass their firing for input via custom rules or SML.
#
#
# Inputs (see fake-plans, fake-vars for examples):
#  <input-link>.plan <p1>
#   ^type << seq set >> : is the template comprise a [seq]uence or [set] of actions
#
#   ^actions <a1> (if type=set, optionally <a2>, <a3> ...)
#      ^name |action name|
#      ^conditions <conds>
#        ^<variable-name> <variable-value> : set of variable name/value pairs that must hold for this action to exist within the script
#      ^sub-plan << nil <p2> >> : if hierarchical, reference to another [recursive] plan
#      ^next << nil <a2> >> : if type=seq, optionally next possible action
#
#   ^vars.var <v1> (optionally <v2>, <v3> ...)
#      ^type << multi given binary >>
#      ^name |Variable Name|
#      ^value : only for type=given
#      ^cpt <cpt> : only for type<>given
#         ^default : optional, provides a value if no rules apply
#         ^entry <e1> (optionally <e2>, <e3>, ...)
#            ^conditions.<variable name> <variable value>
#            ^values.<value> <probability>
#
#
# Outputs:
#  <output-link>
#    ^kb.<variable name> <variable value> : at the conclusion of script generation, the value of all variable assignments
#    ^script << nil <a1> >> : linked list of actions
#       ^name |action name|
#       ^next << nil <a2> >>


