A Short Introduction to the Evil Innards of the Toolset

 What the toolset does, is take defining forms presented by the
user and use them to build objects, called dragons. These objects
perform actions in response to messages. There are different types
of dragons, which do different things by default, and take different
user specifications. The types of dragons, what they do, and
how to specify them are discussed in detail in the user's guide to
the toolset. Here, I'm just going to talk about the commonalities
among dragon types, how they're built, how they run once they're
built, and the assorted support facilities that have sprung up 
around them.

 In this guide is a general overview of most of the main machinery of
the toolset, and then a set of lists of class, function, method, setf,
and macro definitions with their locations and a bit of explanation.

Building Dragons:

 First of all, a dragon is an instance of a CLOS class, defined in dragon.lsp.
None of the objects built by the toolset are just members of the class
dragon -- they are all members of the subclasses of dragon.
 Each dragon definition starts with a define form. This is a macro, and
is the form the user actually uses to define a dragon of a given type.
There are several of these macros: define-recognition-agent, define-idb,
define-classifier, and define-classification-specialist, all of which
live alone in files corresponding to their names. 
 Define-classifier and define-classification-specialist actually define
classifiers and classification-specialists -- the only arguments they
take are the name to give the new instance and the specifiers (see
user's guide) given by the user. Define-recognition-agent and define-idb,
on the other hand, incorporate on more level of indirection. Along with
the name argument and the set of specifiers, they also take a type
argument. In the case of define-recognition-agent, the type argument
must be a subtype of recognition-agent (ditto with define-idbs and idb).
The define form then builds an instance of that subtype.
 Apart from this small difference, all define forms are basically
identical.  They make an instance of the desired type, defparameter
the name to point at the instance (defparameter instead of defvar so
that a new value will be given each time the define form is evaluated)
(someday dragons won't have to have global names...), set the dragon's
unique-name slot to contain the name (so you have a complete dragon
--> name --> dragon mapping), and call the method compile-dragon-type
on the instance and the specifiers to fill the rest of the dragon's
slots.  Before creating the new instance, if a dragon already exists
with the specified name (any type of dragon), that old instance is
destroyed to remove circularity and allow for garbage collection.
 
 The compile-dragon-type method does the rest of the work in building
the instance and making it ready to run. There is a single compile-dragon-type
method for each dragon type. The first thing it does is to parse the
specifications given by the user, and install them into slots in the
instance for later processing. This is done by a function called something
like stuff-agent-type-slots usually, but may be done inline in
compile-dragon-type if there aren't many legal specifiers for the type.
Very little specification parsing is done in the stuff function (see
examples in csrl.lsp and stuff-ra-slots.lsp). There is almost always
a slot for each user specification in the dragon. What the user specified
is put there verbatim. It is parsed up later, and the parsed form which
the dragon will actually use for computation is stored in another slot.
The user-specified forms are saved for explanation purposes, mostly.
Most user-specified versions of things are in slots whose name starts
with display- (as in display-match-action, the user-specified version,
vs. match-action, the version used by the system).
 After stuffing the slots, any defaults the system has for things the
user didn't specify are installed. For example, if the user didn't
give the dragon a display-name, it is defaulted to the print-name of
the dragon's unique-name.
 Then, compile-dragon-type goes through and does all the type-specific
parsing of specifications. (Described below if I have time, pretty
heavily commented, if you don't understand any of them, just ask.)
 Once all the type-specific parsing has been done, the agent's
controller is built. The dragon's controller is a list of the form:
((verb lambda) (verb lambda)...). Where verb is a message the dragon
can respond to, and lambda is the lisp form the system runs in
response to that message being sent to that dragon. (In fact, all the
system does to deliver a message is uses assoc to get the lambda for a
given message, and apply's it the arguments, if any.) There are a set
of default verb-lambda pairs for any given dragon type, which are
created by the controllers method for that type. The user may also
specify additional verb-lambda pairs, either specifying new verbs or
redefining system verbs. The set of all verb-lambda pairs gotten by
parsing the user specification and from the controllers method is
stuck onto the dragon's parsed-controller slot. In that slot, the
lambdas are uncompiled. The parsed-tracing-controller slot stores
lambdas to be used in response to verbs when tracing is turned on for
the dragon.  If any verb specified for the dragon's controller doesn't
have its own tracing-controller specification in either the
tracing-controllers method or the user specification, the non-tracing
lambda is copied into the parsed-tracing-controller slot. At the very
end, the function compile-controller takes the list of verb-lambda
pairs and compiles each lambda, giving ((verb #<compiled lambda
object>)....). This new list is stuck into the dragons actions slot,
and is the list actually used when the dragon runs. The
parsed-controller-slot and the compile-controller function work
together so that in the actions slot, any user-specified verb-lambda
pair comes before any system-specified verb-lambda pair. This allows
the user to redefine system-specified verbs, as the one earlier in the
actions list (the user-specified one) will overshadow the one later in
the list (assoc returns only the first one). If the global variable
*compile-controller* is set to nil before the draogn definition is
loaded (before compile-dragon-type is run), the lambdas will not be
compiled. A copy of the parsed-controller list will be installed in
the actions slot (with verb order as above to allow system verb
redefinition), aiding debugging and making load time much shorter.
(All of the above happens with tracing-controllers too, except they
end up in the alt-actions slot. The function trace-ra simply swaps
the contents of the actions and alt-actions slots on the dragon,
and untrace-ra puts them back.)


Running Dragons:

 The function Invoke (in invoke.lsp) takes care of all the run-time
work for dragons. The bulk of its work is involved in setting up the
dragon's memory structures, recording most of the details of each
dragon-dragon transaction. The form of these memory structures is
very complex (every 4 months or so, I decide I need to understand
them for some reason, so I go draw lots of pictures). If you get
totally lost, and really want to understand them (I only partially
do), ask Rich Fox.
 As to calling on dragon processing, invoke sets the global variable
*current-dragon* to point at the dragon being called, and then looks
down that dragon's action list to find the action corresponding to the
verb (which was an argument to invoke). It takes the lambda paired
with that verb, and applies it to the arguments given to invoke, if
any. During the body of that lambda, the dragon can get at the
contents of its own slots using the *current-dragon* variable (a
kludge to get around the lack of a self variable in CLOS).
 The CLOS classes engram, transaction-record, action-record, and
consultation-record are all involved in dragon memory.

Saving Dragons:

 This set of stuff takes an existing dragon, and writes out to a file 
a form that will recreate that dragon when the file is loaded, without a
lot of the parsing that goes on when you load a define-form. The slots
of the dragon are filled using the CLOS initialization protocol and
the dragon's initargs. The actions lambdas are created by writing the
uncompiled versions of these lambda out first in the file, with each
lambda wrapped in a call to compile and a name for the lambda defparametered
to the compile form, as such:

(defparameter buffys-judge-lambda
	(compile nil '(lambda (x).....)))

when this form is loaded, the variable buffys-judge-lambda has as its
value the compiled lambda object (note: buffys-judge-lambda has no
function definition, the lambda object is stored in its value cell,
not its function cell). When buffy's definition is loaded, the form
that builds her actions slot evaluates the variable buffys-judge-lambda
to get the compiled lambda to stick in the actions slot. The advantage
of doing it this way is that if you compile the file before loading
it, all the actions lambdas get precompiled, and don't have to be compiled
at load time. The only bad thing about it is that it won't work on
non-reentrant compilers, who barf on the call to compile inside the
file they are trying to compile. KCL won't even load these without
compiling them, as it spontaneously compiles things on the fly for fun
while you load them, and may happen to decide to try to compile one
of these things, barfing on a non-reentrant compiler error even when
you only explicitly called the compiler once. 
 The main function in the file save-dragon.lsp is save-dragon, which
opens the file you want, and then calls write-dragon on each dragon
you tell it to write into that file. Write-dragon writes out the forms
to rebuild a given dragon: first, a form to destroy any dragon of that
name that exists, second, the actions lambdas, and third, a
defparameter which contains a call to make-instance with all the
appropriate initializations to rebuild that dragon. That list of
initializations is what the rest of the save-dragon file builds.
The initialization list if built by climbing up the inheritance tree
backwards, from most specific superclass of that dragon to least specific
superclass (DRAGON itself). At each level, the slots defined for that
class are written out. So, you end up with progressions like the following:

classifier   classification-specialist  idb    match-1-ra (or disc-patt or
    |			|		 |	  |	     free-form)
    v			v		 v	  v
 dragon		     dragon	       dragon   recognition-agent
						  |
						  v
						dragon

The top line have their innards written out by the method
dragon-type-innards, which in all cases by the recognition-agents
immediately calls dragon-innards to write out the slots common to all
dragons. In recognition agents, ra-innards is called, which in turn
calls dragon-type-innards. The method for the most specific supertype
of a dragon attatches the name of that type to the front of the
initialization list, to be used as the class argument for make-instance.
(So, you find out what type of dragon you're building by which of the
dragon-type-innards methods gets called.) 
 The forms which build the initialization lists are an adventure in
backquotes, in an attempt to get everything to rebuild right. Several
macros (defined in utility-functions.lsp) are used to write out
various types of slots -- these are mostly to get the quoting right or
to take a slot which contains an array and return a form which will
rebuild that array with the same contents. Any new dragon type should
have appropriate save forms written for it so that all this will work
transparently. (None of this has been done for the new Peirce dragons
as of yet.) It's not hard, provided you follow the templates provided
by the ones that already exist.



Other stuff:

Confidence sets:

 The stuff to handle confidence sets lives in three files:
define-confidence-set.lsp, confidence.lsp, and
confidence-conversions.lsp. Define-confidence-set.lsp contains all the
machinery to define new types of confidence sets, plus the class
definitions for the root of the confidence set hierarchy:
confidence-set.  Confidence.lsp contains the definitions of every
confidence set used by the system. All of these are defined using the
define-confidence-set mechanism (so it does work :-).
Confidence-conversions.lsp provides methods to generate a form to
convert a value from one confidence set to another or to invert a vlue
within its confidence set (so it doesn't convert values, instead,
given two confidence sets to convert between, or a conf set to invert
within, it will return a lisp lambda which will later perform the
desired conversion or inversion, given appropriate arguments).

 The specifiers for confidence sets and the use of define-confidence-set
are all outlined pretty well in the users guide. Right now I'll go over
pretty quick how it works.
 Basically, the user specifies some things for a new type of confidence
set. The system takes that specification and defines a new class, a
subclass of any subclass of confidence set or of confidence-set itself.
(This class-defining form paradigm is used heavily in parts of Peirce,
and is pretty similar everywhere, though more complex in the case of 
defining new dragon types.)
 The whole thing starts out with the class confidence-set. Each confidence-set
is specified in one of two ways: either the confidence values in the
set are continuous (it is a subclass of continuous-confidence-set), in
which the maximum and minimum values of the set are given, or they
are discrete (it is a subclass of discrete-confidence-set), and so contains
a finite number of values which are stored, in order, as a list.
 The confidence set also contains a specification for the type of the
values in the set (number or symbol, usually), any aliases for values
in the set (ex. when I say yup in usual-3-val I mean yes), the neutral
equivalent for the set, if any (neutral is an alias for this), and
a set of comparison functions for comparing values in the set: gt, lt,
le, ge, eq, and member-confidence-set, which determines if a value is
a member of the set. These functions can be specified by the user,
or if not specified, the system can generate them. The method of 
generation depends on whether the set is continuous or discrete.
 The parsing of a define-confidence-set specification is very similar
to that for a dragon specification: there is a minimal define-form macro,
and a compile-confidence-set function which takes care of stuffing
the slots (using the function parse-confidence-spec), building and
evaluating the class definition form, and making the generic instance.
A word about generic instances: as you can't get slot values off the class
object, and you need the slot values of a confidence set to use its
comparison functions, the system doesn't actually operate on confidence
set class objects, it instead passes around instances of confidence sets.
Since you don't need a plethora of these, as they never change, there
is one instance of each conf set created when that set is defined. That
instance is the value of the global variable conf-set-name-generic-instance
for each conf-set-name. The function return-generic-instance takes the
name of a confidence-set and returns its generic instance. The function
confidence-set-p returns t if a symbol names a confidence set.
 The hard part of all this is building the comparison functions. The
user-defined functions get absolute precedence. If one exists, we take
it. If a user-defined function exists for lt or eq (or both), then we
build the le function out of the user-defined eq method and a
system-defined lt method (or vice versa or entirely user). If the user
defined the superclass of this new class, and gave it user-defined
comparison functions, then we inherit those instead of taking the
system-defined ones. To make this more efficient, if the super has a
binding for a given function, and we don't have a user spec for it in
this class, we take the super's version, which may be a user-defined
version or a system-defined version, we don't know. We only actually
generate comparison fns when the super has no binding for a function.
To account for class-dependencies, type-dependent values, such as the
list of values for a discrete-conf-set or the max or min values for a
continuous confidence set are surrounded by noops when they appear in
comparison functions. This allows the comparison function to run as-is
(ex. (max-val yes) returns yes), but also allows us to take the
superclass's comparison methods, and replace the values specific to
the superclass with the appropriate values for the new class (ex.
transform (max-val superclass-max) to (max-val new-class-max), using
the transform-noop-references function). There are a few syntactic
sugar things users are allowed to use to make writing their fns easier
(see users guide), these are translated by the transform-user-fn
function. If, as a last resort, we have to generate a function, this is
done with the function generate-standard-fn. 
 After building the functions, the system sets up the alias list, used
by the function unalias. Then everything is gathered up into a list of
slot specifications to be handed back to compile-confidence-set, which
will then hand them off to defclass.


Justification:
 Prints out interesting information about a dragon's previous run. Pretty
easy to understand from the code, if not ask Rich.

Monitors:
 Very cryptic stuff. I don't understand it. I wrote the docs from the
comments. 



Description of functions, methods, classes, and macros, by file they are in:
(except where obvious)

action-record.lsp:
 (defclass action-record (data-structures) 
	;; class used in dragon memory (see invoke.lsp)

apply-test.lsp:
 (defun apply-test (test feature-value dragon)
	;; used by justification system to simulate match-1 execution

ask-idb.lsp:
 (defmethod controllers ((idb-instance stub-idb))
	;; builds idb controllers (see above on building dragons)
 (defun cached-saved-cases (idb case)
	;; builds answer-cache for a new case based on saved cases
 (defun increase-answer-cache-space (idb)
	;; increases limit on number of cases idb can save

build-discrete-pattern-jl.lsp:
 (defmethod tracing-controllers
	;; tracing controllers for disc-patt
 (defmethod controllers ((ra discrete-pattern-recognition-agent)) 
	;; non-tracing controllers for disc-patt

build-match-1-jl.lsp:
 (defmethod tracing-controllers ((ra match-1-recognition-agent)) 
	;; tracing controllers for match-1
 (defmethod controllers ((ra match-1-recognition-agent)) 
	;; non-tracing controllers for match-1

classification-specialist.lsp:
 (defclass classification-specialist (dragon) 
	;; predominant type of csrl agent (see user guide)

classifier.lsp:
 (defclass classifier (dragon)
	;; csrl administrative agent (see user guide)

compile-disc-patt-ra.lsp:
 (defmethod compile-dragon-type (ra-name (ra-instance 
	;; sets up a disc-patt instance

compile-free-form-ra.lsp:
 (defmethod compile-dragon-type 
	;; sets up a free-form instance (combination of match-1 and
	;; disc-patt compile-dragon-types)

compile-match-1-ra.lsp:
 (defmethod compile-dragon-type (ra-name (ra-instance 
	;; sets up match-1 instance

confidence-conversions.lsp:
	;; the following all produce a form to convert a confidence
	;; value from the source conf-set to the dest conf-set, and
	;; just differ on whether they are handed the names of the
	;; conf-sets or their generic instances
 (defmethod convert-form ((src symbol) (dest symbol))
 (defmethod convert-form ((src confidence-set) (dest symbol))
 (defmethod convert-form ((src symbol) (dest confidence-set))
 (defmethod convert-form ((src confidence-set) (dest confidence-set))
	;; the following function takes a conf set (name or gen. inst.)
	;; and returns a form to invert a value within that set
 (defun invert-form (conf-set-instance)

confidence.lsp:
	;; definitions of confidence sets used by the system
 (define-confidence-set continuous-confidence-set
 (define-confidence-set discrete-confidence-set
 (define-confidence-set usual-2-val
 (define-confidence-set usual-3-val 
 (define-confidence-set usual-9-val
 (define-confidence-set usual-continuous-val

context.lsp:
	;; functions used to define classifiers
 (defmethod controllers ((c-instance classifier)) 
	;; controllers for a classifier
 (defun get-context
	;; finds out if this classifier could have established by making
	;; sure its parents can establish, (depending on context-type,
	;; see users guide), could now be part of dragon controller
	;; (not before because of recursive invoke problem)

controllers.lsp:
 (defun parse-controller-slot (ra-instance ra-type)
	;; parses up a control-additions spec, translates syntactic sugar
	;; into run-time forms, etc
 (defun compile-controller (controller-list)
	;; compiles the actions lambdas

copyright-string.lsp:
 (defparameter toolbed::*copyright-string*
	;; used in load function to print out appropriate message for site

cs-queries.lsp:
 (defmacro get-establish-threshold (cs)
	;; gets a CS's establish-threshold
 (defmacro get-suspend-threshold (cs)
	;; " " suspend-threshold
 (defmacro get-last-establish-threshold (cs)
	;; gets the establish-thresh used by a CS in the last case it ran in
 (defmacro get-last-suspend-threshold (cs) 
	;; " " suspend-threshold
 (defun get-refine-result (cs &optional (case *current-case*))
	;; gets the result of the cs refining in its last case (or nil,
	;; if case is not the last case it refined in)
 (defun get-status (cs &optional (case *current-case*))
	;; gets the status of the CS for the last case it ran in, if it is
	;; case: established, suspended, ruled-out, or not-run
 (defun get-last-result (cs &optional (case *current-case*))
	;; gets the value the CS returned in is last case (if it ran in case)
 (defmacro hierarchy-complete? (classifier) 
	;; makes sure a classifier's hierarchy isn't expecting any nodes
	;; that haven't been defined yet
 (defun hierarchy-ok? (classifier)
	;; checks hierarchy on some rudimentary correctness measures
 (defmacro get-case (dragon)
	;; returns the last case the dragon ran in
 (defmacro local-establish-threshold? (cs) 
	;; does the CS have its own estab-thresh, or does it use the global
 (defmacro local-suspend-threshold? (cs) 
	;; "" suspend-thresh
 (defmacro run-yet? (cs &optional (case *current-case*))
	;; is case the last case the CS ran in
 (defmacro propagate? (classifier)
	;; does the clasifier propagate established status upwards (see
	;; user guide)
 (defmacro propagation-on (classifier)
	;; turns propagation on
 (defmacro propagation-off (classifier)
	;; turns propagation off


csrl.lsp:
 (defun stuff-cs-slots (cs-instance body mandatories forbidden)
	;; puts the user specifications into the CS's slots
 (defmethod controllers ((cs-instance classification-specialist))
	;; CS controllers
 (defun parse-establish-reject (estab-list)
	;; makes the CS's establish-reject specification into a
	;; runnable form (see user's guide)
 (defun parse-threshold (thresh) 
	;; sets up estab and suspend thresholds
 (defun parse-refine-form (form cs-instance classifier)
	;; takes the CS's refine-form= specification and returns a
	;; runnable form to do that
 (defun transform-sub-forms (tree instance-name classifier)
	;; transforms syntactic-sugar references to subs in refine-forms
 (defun transform-get-subs (tree instance-name classifier)
	;; ""
 (defun parse-translator (trans conf-set) (cond
	;; makes runnable form from translator= specification
 (defun add-to-classifier 
	;; adds the newly defined CS to its classifier's hierarchy
 (defmethod compile-dragon-type (cs-name (cs-instance
	;; parses & builds a CS
 (defun add-unresolved-relations (new-relations old-list)
	;; bookkeeping fn that tracks undefined dragons mentioned by other
	;; members of the hierarchy
 (defun new-case (drags)
	;; nulls out the dragons' last case, so they can be rerun in a
	;; case of the same name but will treat it as a new case

data-structures.lsp:
 (pcl:defclass data-structures (lair-object) nil)
	;; placeholder in the class hierarchy

define-classifier.lsp:
 (defmacro define-classifier (c-name &body gt-code)
	;; define form for classifiers
 (defmethod compile-dragon-type (c-name (c-instance classifier)
	;; parses & builds classifier
 (defun stuff-c-slots (c-instance body mandatories forbidden)
	;; puts user spec into classifier slots

define-confidence-set.lsp:
 (defclass confidence-set (toolbed::data-structures) 
	;; top of confidence class hierarchy
 (defparameter confidence-set-generic-instance 
	;; generic instance for confidence-set
 ;; the rest of these were all described in the section on conf sets, above
 ;; just search back for them
 (defmacro define-confidence-set (set-name &body gt-code)
 (defun compile-confidence-set (set-name code-body)
 (defun parse-confidence-spec (set-name body missing)
 (defun transform-noop-references (tree max min values-list)
 (defun generate-standard-fn (which-fn type max min values-list gt lt eq ge le)
 (defun transform-user-fn (fn-spec max min values-list)
 (defun parse-alias-list (alias-list member-confidence-fn)
 (defun return-generic-instance (conf-set &optional (no-scream nil))
 (defmacro confidence-set-p (set)
 (defun conf-set-name (vocab)
	;; returns the name of a conf set instance
 (defun check-alias-compare-form (fn arg1 arg2 vocabulary)
	;; returns a form to compare arg1 and arg2 (which may be variable
	;; names to be evaled later) with function fn in vocabulary
 (defmethod confidence-values ((conf-set symbol))
	;; returns the value-list or max and min for the conf set
 (defmethod confidence-values ((conf-set confidence-set))
	;; "" 
 (defmethod member-confidence (conf-value (conf-set symbol))
	;; returns t if value is a member of the conf-set
 (defmethod member-confidence (conf-value (conf-set confidence-set))
	;; ""
 (defmethod confidence-compare (fn arg1 arg2 (vocabulary confidence-set))
	;; returns t if applying fn to arg1 and arg2 in vocabulary returns t
 (defmethod confidence-compare (fn arg1 arg2 (vocab symbol))
	;; ""
 (defmethod unalias (value (vocabulary confidence-set))
	;; returns real name of value in confidence set, whether value is an
	;; alias or just a member of the set
 (defmethod unalias (value (vocab symbol))
	;; ""
 (defmethod maximum-value (value (vocab symbol))
	;; t if value is the max value for the conf vocab (discrete or contin)
 (defmethod maximum-value (value (vocabulary confidence-set))
	;; ""
 (defmethod minimum-value (value (vocab symbol))
	;; for minimum
 (defmethod minimum-value (value (vocabulary confidence-set))
	;; ""
 (defmacro min-val (x)
	;; syntactic sugar for inheriting comparison fns (see above -- noops)
 (defmacro max-val (x) `,x)
	;; ""
 (defmacro v-list (x) `,x)
	;; ""

define-cs.lsp:
 (defmacro define-classification-specialist (cs-name &body gt-code)
	;; define form for cs's

define-idb.lsp:
 (defmethod compile-dragon-type (idb-name (stub-idb-instance stub-idb)
	;; parses and builds an idb
 (defmacro define-idb (idb-name idb-type &body gt-code) 
	;; define form for idbs
 (defun cases-saved (idb)
	;; returns the names of the cases the idb has saved
 (defun save-case (idb &optional &key (delete nil))
	;; stores the current case in the idbs saved-case-cache
 (defmacro saved-case-limit (idb)
	;; returns how many cases the idb can save
 (defmacro set-saved-case-limit (idb val)
	;; sets how many cases the idb can save
 (defun forget-case (case idb)
	;; removes case from idb's cache
 (defmacro case-saved? (case idb)
	;; t if idb has case saved

define-ra.lsp:
 (defmacro define-recognition-agent (ra-name ra-type &body gt-code)
	;; define form for all RA types

defsystem.lsp:
 ;;; defsystem stuff, ripped off from march 17th pcl, and only very
 ;;; gently bashed on

discrete-pattern-ra.lsp:
 (defclass discrete-pattern-recognition-agent (recognition-agent)

displays.lsp:
 (defmethod display ((engram toolbed::engram)
	;; shows the engram's contents

dragon-concepts.lsp:
 (defun add-dragon-to-concepts (name concepts)
	;; takes care of a dragon's associated-concepts= specifier (see user's)
 (defun return-associated-concepts (dragon)
	;; returns what concepts a dragon is associated with
 (defun return-associated-dragons (concept)  
	;; returns what dragons are associate with a concept

dragon.lsp:
 (defclass dragon (lair-agent) 
	;; superclass for all dragon types

engram.lsp:
 (defclass engram (data-structures)
	;; used in dragon memory (see invoke.lsp)

fetch-feature.lsp:
 (defun check-feature (feature-number) 
	;; used in match-1's runtime actions
 (defun fetch-transformed-feature (feature-number)
 	;; ""
 (defun flush-feature-cache nil 
	;; flushes cached features between cases

free-form-ra.lsp:
 (defclass free-form-recognition-agent (recognition-agent)

hierarchy.lsp:
	;; stores hierarchy information, used in CSRL by classifiers
 (defclass hierarchy (toolbed::data-structures)
	;; all documented in user guide
 (defmacro make-hierarchy (&optional (node-type t))
 (defmacro get-nodes (hier) 
 (defmacro hierarchy-contents (hier)
 (defmacro is-node (node-name hier) 
 (defmacro is-sub (child parent hier) 
 (defmacro is-super (parent child hier)
 (defmethod get-subs (obj (hier hierarchy)) 
 (defmethod get-subs (obj (class classifier))
 (defmethod get-subs (obj (classifier-name symbol))
 (defun get-subs-preserving-structure (node hier)
 (defmethod get-supers (obj (hier hierarchy)) 
 (defmethod get-supers (obj (class classifier)) 
 (defmethod get-supers (obj (classifier-name symbol)) 
 (defsetf get-subs (obj hier)
 (defsetf get-supers (obj hier)
 (defun get-all-subs (node-name hier)
 (defun get-all-supers (node-name hier)
 (defmacro tip-nodep (node hier)
 (defmacro get-tip-nodes (hier) 
 (defmacro top-nodep (node hier)
 (defmacro get-top-node (hier)
 (defmacro treep (hier)
 (defun break-link (node1 node2 hier &key (delete nil))
 (defun add-link (node1 node2 hier)
 (defun change-node (old-obj new-obj hier)
 (defun destroy-hier (hier) 
 (defun add-node (node parent-list child-list hier 
 (defun delete-node (node hier &key (recursive nil))
 (defun insert-node (new-node node1 node2 hier)
 (defun move-node (node new-parent-list new-child-list hier 

idb-classes.lsp:
 (defclass intelligent-data-base (toolbed:dragon)
 (defclass stub-idb (intelligent-data-base)
	;; not really needed anymore, but still there

import-export-symbols.lsp:
 (defun import-export-symbols nil (in-package "toolbed")
	;; to deal with package problems

invoke.lsp:
 (defun create-engram (dragon verb more-args)
	;; build memory entry for transaction
 (defun fill-engram (dragons-engram callers-engram user-answer result)
	;; records transaction in memory space built by create-engram
 (defun get-user-result (dragon result)
	;; used by user-override system
 (defun invoke (dragon verb &rest more-args) 
	;; main runtime processing function

justification.lsp:
 (defparameter *justification-output* *trace-output*)
	;; stream to print to
 (defmethod justifier ((dragon classification-specialist) 
 (defmethod justifier ((dragon classification-specialist) (type (eql '2)) 
 (defmethod justifier ((dragon classification-specialist) 
 (defmethod justifier ((dragon classification-specialist) (type (eql '4)) 
 (defmethod explainer ((dragon discrete-pattern-recognition-agent) engram 
 (defmethod explainer ((dragon match-1-recognition-agent) 
 (defmethod display-pattern ((dragon match-1-recognition-agent) 
 (defmethod display-pattern ((dragon discrete-pattern-recognition-agent) 
 (defun fetch-establish-reject-test (list-of-values)
 (defun fetch-features-for-display (dragon) 
 (defmethod fetch-pattern ((dragon discrete-pattern-recognition-agent))
 (defmethod fetch-pattern ((dragon match-1-recognition-agent) pattern-number)
 (defmethod fetch-results ((dragon classification-specialist) engram) 
 (defmethod fetch-results ((dragon recognition-agent) engram) 
 (defun find-failure-in-pattern (dragon pattern pattern-name 
 (defun get-case-from-memory (dragon &optional (case nil)) 
 (defun get-parent-status (dragon case)
 (defmethod justify ((dragon classification-specialist) &optional (case nil))
 (defmethod justify ((dragon discrete-pattern-recognition-agent) 
 (defmethod justify ((dragon match-1-recognition-agent) &optional (case nil)) 
 (defmethod menu-and-execute ((dragon classification-specialist) 
 (defmethod menu-and-execute ((dragon recognition-agent)
 (defmethod justifier ((dragon recognition-agent) (type (eql '1)) 
 (defmethod justifier ((dragon recognition-agent) (type (eql '2)) 
 (defmethod justifier ((dragon recognition-agent) (type (eql '3)) 
 (defmacro return-run-time-value (results)
 (defun test-failed (test-value current-value dragon number) 

lair-agent.lsp:
 (defclass lair-agent (lair-object) nil)
	;; placeholder in type hierarchy

lair-object.lsp:
 (defclass lair-object (pcl::object) nil)
	;; placeholder in type hierarchy

load-toolset.lsp:
;;; load file using pcl's defsys for gt toolset fafner release 1.1-dod
 (defparameter *pcl-defsys-directory*
 (defparameter *pcl-defsys-extensions*
 (defparameter *gt-directory*
 (defvar *pathname-extensions*
 (pcl::defsystem toolbed::gt-toolbed *gt-directory*
 (pcl::defsystem gt-toolset toolbed::*gt-directory*
 (pcl::defsystem gt-user-interface toolbed::*gt-directory*
 (defun toolbed::load-toolset 
 (defparameter toolbed::*invocation-single-step* nil)
 (defparameter toolbed::*invocation-trace-flag* t)
 (defparameter toolbed::*decision-support-mode* nil)
 (defparameter toolbed::*memory-on-flag* t)
 (defparameter toolbed::*idb-flushed-list* '())
 (defparameter toolbed::*puff* nil)
 (defparameter toolbed::*current-dragon* nil)
 (defparameter toolbed::*current-case* nil)
 (defparameter toolset::*verb-list* 
 (defparameter toolset::*associated-concepts-list* nil)
 (defparameter toolset::*csrl-establish-threshold* 
 (defparameter toolset::*csrl-suspend-threshold* 
 (defparameter toolset::*compile-controller* t)
 (defparameter toolset::*idb-use-saved-cases* t)
 (defparameter toolset::*cs-use-cache* t)
 (defparameter toolset::*context-type-default* 
 (defun toolbed::compile-toolset (&optional (all nil))
 (defparameter toolbed::*invocation-single-step* nil)
 (defparameter toolbed::*invocation-trace-flag* t)
 (defparameter toolbed::*decision-support-mode* nil)
 (defparameter toolbed::*memory-on-flag* t)
 (defparameter toolbed::*idb-flushed-list* '())
 (defparameter toolbed::*puff* nil)
 (defparameter toolbed::*current-dragon* nil)
 (defparameter toolbed::*current-case* nil)
 (toolbed::import-export-symbols)
 (defparameter toolset::*verb-list* 
 (defparameter toolset::*associated-concepts-list* nil)
 (defparameter toolset::*csrl-establish-threshold* 
 (defparameter toolset::*csrl-suspend-threshold* 
 (defparameter toolset::*compile-controller* t)
 (defparameter toolset::*idb-use-saved-cases* t)
 (defparameter toolset::*cs-use-cache* t)
 (defparameter toolset::*context-type-default*

match-1-ra.lsp:
 (defclass match-1-recognition-agent (recognition-agent)

match-pattern.lsp:
 (defun match-pattern (pattern-number)
	;; match a pattern to features (as in one pattern of a 
	;; match-1-recognition_agent), return 'succeeded or nil
 (defun match-the-pattern
	;; same for discret-pattern-ra patterns

monitor-code.lsp:
	;; in users guide
 (defun create-monitor-handle (associate-with report-to eval-form 
 (defun get-monitor-handle (associated-with report-to eval-form 
 (defun poke-monitor (monitor-handle) 
 (defun remove-monitor (monitor-handle) 
 (defun remove-parent-from-monitor (child parent) 

monitor-ra.lsp:
	;; in users guide
 (defmethod cast-spell ((drag recognition-agent)

monitor.lsp:
	;; in users guide
 (defclass monitor-handle (data-structures) (

nuke-em-file.lsp:
	;; destorys a circular object so it can be gc'ed
 (defmethod destroy ((engram engram))
 (defmethod destroy ((dragon dragon))
 (defun flush-case (case)
	;; nukes a case from a dragon's memory
 (defun flush-memory
	;; nukes the whole memory
 (defun memory-virus (engram)
	;; used to nuke the memory by eating it away from inside

parse-ra-slots.lsp:
 (defun parse-features (ra-instance) 
	;; parses ra's features= specification
 (defun parse-test (test expected-feature test-number transform) 
	;; parses ra's pattern specifications
 (defun parse-confidence (confidence-spec)
	;; parses match-confidences and no-match-confidences
 (defun transform-pattern-references (tree)
	;; parses syntactic-sugar (pattern i) forms
 (defun transform-confidence-references (tree)
	;; parses syntactic-sugar (conf i) forms

parse-transforms.lsp:
 (defun parse-transforms (transform-spec-vector conf-set 
	;; parses transforms for ra's

puff-start.lsp:
 (defun hatch-puff nil
	;; builds puff the magic dragon
 (defparameter toolbed::*puff* (pcl::*make-instance 'dragon))
 (defmacro start-solving (case classifier verb &rest args)
	;; macro to run a case

recognition-agent.lsp:
 (defclass recognition-agent (dragon) 

remember.lsp:
 (defun remember (&rest stuff) 
	;; stores stuff in *current-dragon*'s memory

save-dragon.lsp:
	;; all described above in section on saving dragons
 (defmethod dragon-innards ((drag dragon))
 (defmethod ra-innards ((drag recognition-agent))
 (defmethod dragon-type-innards ((drag match-1-recognition-agent))
 (defmethod dragon-type-innards ((drag discrete-pattern-recognition-agent))
 (defmethod dragon-type-innards ((drag free-form-recognition-agent))
 (defmethod dragon-type-innards ((drag classification-specialist))
 (defmethod dragon-type-innards ((drag classifier))
 (defun write-hierarchy (hier)
 (defmethod dragon-type-innards ((drag stub-idb))
 (defun make-drag-def-name (drag-name slot-name verb) 
 (defun save-dragon (dragons &optional (fpath nil fpathp)
 (defun write-dragon (drag-list) 

stuff-ra-slots.lsp:
 (defun stuff-ra-slots (ra-instance body mandatories forbidden)
	;; parses & stuffs ra specs
 (defun extract-confidences (pattern-confidence-spec-list) 
	;; pull apart the patterns= spec of a match-1, extract the 
	;; confidences, stuff vector."
 (defun extract-thresholds (pattern-confidence-spec-list) 
	;; pull out the success-thresholds from patterns= spec
 (defun extract-match-actions (pattern-confidence-spec-list) 
	;; pull out the match-actions form patterns= spec

trace-functions.lsp:
	;; dumb terminal displaying trace functions
 (defun considering-table-cell (x y &optional (trace-window *trace-output*))
 (defun deconsidering-table-cell (x y &optional (trace-window *trace-output*))
 (defun yes-table-cell (x y &optional (trace-window *trace-output*))
 (defun no-table-cell (x y &optional (trace-window *trace-output*))
 (defun considering-consequent (i &optional (trace-window *trace-output*))
 (defun deconsidering-consequent (i &optional (trace-window *trace-output*))
 (defun stuff-consequent (result &optional (trace-window *trace-output*))
 (defun stuff-no-match (result &optional (trace-window *trace-output*))

trace-ra.lsp:
 (defmethod trace-ra ((ra toolset::recognition-agent)) 
	;; swap tracing actions for untracing actions
 (defmethod untrace-ra ((ra toolset::recognition-agent)) 
	;; undo trace-ra

traced-tests.lsp:
	;; works with the display fns above
 (defun trace-a-test (i) 
	;; evals a discrete pattern test with tracing
 (defun trace-the-consequent nil
	;; evals a disc patt consequent with tracing
 (defun traced-consequent (i) 
	;; evaluates a confidence with tracing in a match-1
 (defun traced-no-match nil 
	;; evals no-match clause with tracing
 (defun traced-test (i j) 
	;; evals a match-1 test with tracing

transaction-record.lsp:
	;; used in dragon memory (see invoke.lsp)
 (defclass transaction-record (action-record)
 (defclass consultation-record (transaction-record)

transform-invokes.lsp:
 (defun transform-invoke-forms (tree) 
	;; transforms a form, changing the user-visible syntactic-sugar
	;;  verb-concept form of invocations to invoke form
	;; (goes from (verb dragon) form to calls to the invoke function
 (defun translate-invoke-form (form)
	;; does the detail work for the above

user-dragon.lsp:
 (define-recognition-agent *user* free-form-recognition-agent
	;; handles ask-users

utility-functions.lsp:
 (defmacro slot-empty-p (instance slot-name) 
	;; returns t if slot is unbound or null
 (defmacro slot-unbound (instance slot-name)
	;; returns t if slot is unbound (localize calls to fn in pcl package)
 (defmacro subclassp (sub super)
	;; returns t if super is a superclass of sub (or if super = sub)
 (defun quote-list (list)
	;; returns a list containing all the elements of list, quoted
 (defmethod list-contents ((a t)) 
	;; lists gives error -- list-contents not handed array or vector
 (defmethod list-contents ((a array)) 
	;; returns contents of array in form suitable to be init argument
	;; to make-array
 (defmethod list-contents ((a vector))
	;; returns contents of vector in form suitable to be init argument
	;; to make-array
 (defun make-slot-array (instance slot-name &optional (size nil size-given))
	;; takes an instance and the name of a slot containing an array
	;; and returns a form to rebuild that array
 (defmacro write-string-slot (obj slot) 
	;; copes with correct quoting of slots filled with strings, symbols,
	;; and null or slot-unbound

