define-ks

Purpose
Define or redefine a knowledge source (KS).

Package   :agenda-shell

Module   :agenda-shell

Arguments and values

Returns
The unit instance representing the KS

Detailed syntax

The shorthand + subevents specifier is equivalent to :plus-subevents and = to :no-subevents.

The shorthand + subclasses specifier is equivalent to :plus-subclasses and = to :no-subclasses.

Description
A KS definition creates a unit instance of class ks-class which specifies how activations of the KS are created and executed. The lifetime of each KS activation involves the following sequence:

• When an event matching one of the event specifications in trigger-events occurs and the KS is enabled:
  • the activation-predicate, if specified, is called and must return true for potential activation to continue
  • the precondition-function, if specified, is called and must return an integer rating for potential activation to continue
• The KS is activated (a unit instance of class ksa-class is created) and given the rating returned by the precondition-function or the constant rating value defined for the KS if no precondition-function was specified. The current control-shell cycle number is stored in the activation-cycle slot of the KSA unit instance.
• The KSA is placed on the queue of pending KSAs.
• If an event matching one of the event specifications in obviation-events occurs, the obviation-predicate, if specified, is called. If it returns true, the pending KSA is removed from the pending KSAs queue, the current control-shell cycle number is stored in the obviation-cycle slot of the KSA, and the KSA is placed on the queue of obviated KSAs.
• If an event matching one of the event specifications in retrigger-events occurs, the retrigger-function, if specified, is called. A retrigger-function is often used to change the triggering context of the KSA or its rating.
• When the pending KSA is selected for execution (typically because has the highest rating above the minimum-ksa-execution-rating currently in effect for the control shell), the revalidation-predicate, if specified, is called. If the revalidation-predicate returns nil, the pending KSA is removed from the pending KSAs queue, the current control-shell cycle number is stored in the obviation-cycle slot of the KSA, and the KSAis placed on the queue of obviated KSAs.
• The pending KSA is removed from the pending KSAs queue, the current control-shell cycle number is stored in the execution-cycle slot of the KSA unit instance, and the execution-function is called.
• The executed KSA is placed on the queue of executed KSAs.

KS functions and predicates

The Agenda Shell provides a rich set of KS functions and predicates to manage the progression of KSAs from initial triggering and activation through obviation or execution. A typical KS will only require a subset of these functions and predicates.

An activation-predicate is a function that is called with two arguments, the unit instance representing the KS and the object representing the triggering event. The activation-predicate should return a generalized boolean that indicates whether the KS should continue to be considered for activation in response to the event. Typically, an activation-predicate is specified for a KS that does not require a precondition-function rating computation, but that does require an activate/don't-activate decision.

A precondition-function is a function that is called with two arguments, the unit instance representing the KS and the object representing the triggering event. The precondition-function should return one of the following sets of values:

• nil indicating the KS is not to be activated in response to the event
• :stop (and, optionally, additional values to be returned by the control shell) indicating that the control shell is to exit immediately
• An integer execution rating for the KSA (and, optionally, initialization arguments to be used when creating the KSA unit instance)

An execution-function is a function that implements the KS. When an activation of the KS is executed, this function is called with one argument, the unit instance representing the KSA. If the execution function returns the value :stop (and, optionally, a additional values to be returned by the control shell), the control shell will exit immediately.

An obviation-predicate is a function that is called with two arguments, the unit instance representing the KSA and the object representing the obviation event. The obviation-predicate should return a generalized boolean that indicates whether the KSA should be obviated.

A retrigger-function is a function that is called with two arguments, the unit instance representing the KSA and the object representing the retrigger event. The retrigger-function can perform whatever activities are needed in response to the event. Typically this involves augmenting the triggering context of the KSA or changing its execution rating.

A revalidation-predicate is a function that is called with one argument, the unit instance representing the KSA. The revalidation-predicate is called immediately before a KSA is executed and should return a generalized boolean that indicates whether the KSA should be executed (if true) or obviated (if false).

See also
    define-ks-class
    define-ksa-class
    describe-ks
    ensure-ks
    ks
    ks-enabled-p
    standard-event-instance
    undefine-ks

Examples
Define an initial KS that is triggered when the control shell is started:

  (define-ks initial
     :trigger-events ((control-shell-started-event)) 
     :execution-function #'initial-ks-function)

Define a KS named aggregate-hyps that is triggered whenever a hyp unit instance is created:

  (define-ks aggregate-hyps
     :trigger-events ((instance-created-event hyp))
     :precondition-function #'aggregate-hyps-precondition-function
     :execution-function #'aggregate-hyps-ks-function)

Note
Unit-instance-specific KS triggers are not yet implemented in GBBopen.

define-ks