IBM Agent Building Environment Developer's Toolkit


Chapter 11. Engine

RAISE Inference Engine

The RAISE inference engine is the only engine shipped as part of this package. The RAISE inference engine is a forward-chaining inference engine. The RAISE inference engine can be configured in an agent to attach to any number of adapters. Adapters exist outside of RAISE and fulfill the following roles:

The user can specify the conduct sets that RAISE will use. The conduct sets consists of rules (RuleSet(s) and optionally long term facts (LTFactSet(s)). They can be loaded when when the agent is first started or dynamically loaded/replaced after the agent/engine have been running. Conduct set loading (and unloading) is controlled:

When an adapter passes a trigger event to the RAISE engine, RAISE uses the long term facts specified in the conduct set and short term facts specified by the adapter to inference on the rule set in the user's conduct set. The user can also specify whether RAISE is to log inferencing episodes.

Configuration information about RAISE can be found in Chapter 6. "Building and Starting Your Agent". Information about creating RAISE rules can be found in Chapter 2. "Writing Rules and Understanding Rule Inferencing". Information about supplied adapters that can be configured with RAISE into an engine can be found in Chapter 3. "Adapter Reference Material" of the Components and Adapter Reference book.

Selector Handling by RAISE

Each conduct set that is loaded into RAISE is associated with a selector. The association between a conduct set and a selector is defined:

An adapter can associate a trigger event with a selector by setting the selector in the IAEventHeader object contained by the IATriggerEvent object. When a trigger event is handled by RAISE, it uses the selector information in the trigger event to determine which conduct sets are used for inferencing. RAISE searches all the loaded conduct sets for the conduct sets with a matching selector. For all that it finds, RAISE will use the trigger event and that conduct set for an inferencing episode. If it does not find one, RAISE will discard the trigger event without performing any inferencing.

All selectors that begin with AGENT are reserved for usage by the IBM Agent Building Environment Developer's Toolkit.

The selector AGENT is a special case selector, a broadcast selector. When it is assigned to a trigger event, then RAISE will perform an inferencing episode for every loaded conduct set for that trigger event. However, RAISE will manipulate the trigger event selector prior to starting the inferencing episode to make it appear as if each inferencing episode were started by a trigger event with a matching selector. In other words, if a conduct set is associated with a selector when it is loaded, then every inferencing episode involving that trigger event will look like it was started by a trigger event with a matching selector.

To illustrate the above point, consider the following example, where the configuration file has the following lines:


   conductset RAISE logxmp
   conductset RAISE sampsel myselect

This means that conduct set sampsel is associated with the selector myselect when it is loaded. By default, conduct set logxmp is associated with a selector equal to the null string when it is loaded.

When the agent is being started, RAISE will be notified of the "AGENT:STARTING" trigger event. The AGENT:STARTING trigger event has a selector of "AGENT". RAISE will perform 2 inferencing episodes for the trigger event. For the inferencing episode using the logxmp conduct set, the trigger event and short term facts will show a selector of the null string. For the inferencing episode using the sampsel conduct set, the trigger event and short term facts will show a selector of myselect.

To continue the example, assume that the sampsel conduct set had a rule which used the Time adapter to set an interval alarm and that rule was evaluated to true during the inferencing episode for the AGENT:STARTING trigger event. When the Time adapter sets an alarm, it stores the selector associated with the inferencing episode. It then uses that selector for any new trigger events created when the alarm goes off. In this example, when the interval alarm went off, the Time adapter would create a "Time:IntervalAlarm" trigger event with a selector of myselect, since myselect was the selector when the alarm was set.

When RAISE is notified of the Time:IntervalAlarm trigger event, it will perform one inferencing episode for that trigger event with the sampsel conduct set, since that is the conduct set with the matching selector. Note that an inferencing episode for the logxmp conduct set will not be performed, since the trigger event selector does not match the selector associated with that conduct set.

Note: The IBM Agent Building Environment Developer's Toolkit generated event AGENT:CONFIG, contrasted to the AGENT:STARTING event, has a selector AGENT_CONFIG. This selector is NOT a broadcast selector and causes inferencing episodes only for conduct sets that have been assigned to the AGENT_CONFIG selector.

RAISE Log Output

RAISE has the ability to log every inferencing episode it performs. The user can control the type of logging through the use of the environmental variable IAG_LOGGING. Valid settings for IAG_LOGGING are:

0
RAISE will not perform any logging.

1
RAISE will perform full logging. The result of the evaluation of every rule will be shown. Also, any errors encountered will also be logged.

2
RAISE will log only those rules which had an antecedent evaluating to true.

3
RAISE will log only those rules which had an antecedent evaluating and had at least one effector associated with a predicate in the consequent of the rule.

4
RAISE will log only errors that it has detected. If an inferencing episode was able to complete without error, then no log entries will be made.

The setting of IAG_LOGGING applies to every inferencing episode that RAISE performs. The default behavior is for RAISE not to perform logging.

When RAISE logging is on (IAG_LOGGING is 1, 2, 3 or 4), the location of the log is in the current directory. The name of the log is raise.log.

In addition to the information about rule evaluation, these different pieces of information are also logged when IAG_LOGGING is equal to 1, 2 or 3.

The log contains simple text entries, so no special tools are needed for viewing or printing the log.

Note: The log is currently allowed to grow without bounds. Logging is always a simple append operation, there is no automated log wrapping or log pruning.

RAISE Rule Set and Log Example

The following sequence of figures shows an example of the current IBM Agent Building Environment Developer's Toolkit Library implementation file storage view of a conduct set and the contents of the RAISE log for an inferencing episode with that conduct set. For the "file" implementation by the IBM Agent Building Environment Developer's Toolkit Library, there are currently three separate files that compose the conduct set. They are the rule set file, the long term facts set file, and the metadata file.
Note:The preferred way to manipulate the contents of a conduct set is through the IBM Agent Building Environment Developer's Toolkit Library interface which are described in Chapter 7. "Using the ABE Library". In this way you avoid dependencies on the current implementation and the file formats employed by that implmentation which may change. Therefore you avoid future compatibility problems that could result from going around the official logical interface. You may also avoid these dependencies on the implementation by using the IBM Agent Building Environment Developer's Toolkit Rule Editor, which itself uses the IBM Agent Building Environment Developer's Toolkit Library interface. The rule editor is described in Chapter 8. "Using the ABE Rule Editor".

However, should you decide to take your chances and manipulate conduct sets directly in the files that are the current implementation, the following will assist you to understand that implementation.

The rule set shown in Figure 11-1 contains the rules for the inferencing episode. There are four rules in the conduct set. The first line is the version of the ruleset, the second line is the ruleset name, the third line (null) is the ruleset id, and the fourth line is the active (A)/inactive (I) state of the ruleset. Then there are sets of four lines each for each rule in the ruleset. Each such rule has a line for rule name, a line for rule id (null in this case), a line for state flag (A), and a line for the rule itself. In the following illustration it may appear that the KIF rule itself has more than on line, but this is just for purposes of fitting a rule on a page for the current illustration. For more information about the format of a rule, see Chapter 2. "Writing Rules and Understanding Rule Inferencing".

Figure 11-1. Example rule set. This shows the contents of the logxmp.rls file, which is the rule set used in the inferencing episode. Note that in this example, the second rule has been split across multipe lines for formatting purposes. In the actual file, each rule occupies one line.

1
logxmp

A
MakeExample

A
(=>  ( EventType ?x)(IsExample (integer 1)))
DisplayExecutionTime

A
(=>  (AND (IsExample (integer 1))( EventTime ?date ?time) )
          ( AppendFile  "C:\" "logxmp.run"   "Sample run on " ?date ))
UseLTFact

A
(=>  (Beauty ?x) ( AppendFile  "C:\" "logxmp.run"   ?x " is beautiful. ))
FailingRule

A
(=>  (AND (IsExample (integer 0))( EventTime ?date ?time) )
         ( AppendFile  "C:\" "logxmp.run"   "Non-sample run on " ?date ))


Figure 11-2 shows the long term facts within this conduct set. In this example, there is only 1 long term fact and it is a fact about the Beauty predicate.

Figure 11-2. Example long term fact set. This shows the contents of the logxmp.lfs file, which is the long term fact set associated with the conduct set.


1
logxmp

A
LTFact1

A
( Beauty "Nicole")


The metadata associated with the rule set is shown in Figure 11-3. This is described in further detail in "RuleSet Metadata Required for RuleSets". RAISE requires that the signature for each predicate used in the rule set be defined in the metadata associated with the rule set. Also, the mappings of predicates to sensors and effectors is defined in the metadata. In this conduct set, the predicate AppendFile is mapped to the AppendFile effector of the File adapter.

Figure 11-3. Example metadata file. This shows the contents of the logxmp.ms0 file, which is the metadata file associated with the rule set.


CONDUCTSET logxmp
BEGIN PREDICATES
AppendFile(string,string,string,string);
Beauty(string);
EventDomain(string);
EventId(string);
EventName(string);
EventSelector(string);
EventTime(string, string);
EventType(string);
IsExample(integer);
END PREDICATES
BEGIN SENSORS
END SENSORS
BEGIN EFFECTORS
EFFECTOR  AppendFile File:AppendFile;
END EFFECTORS


In Figure 11-4, the first part of the RAISE log is shown (the setting of IAG_LOGGING=1 was used for this example). This part of the RAISE log shows the logging level, the conduct set name, the short term facts, the long term facts and the agenda. The the syntax of the rules and the rule atoms is a little different than that defined for the KIF syntax. (We hope that the logging can be changed later to conform to KIF syntax.)

Figure 11-4. First part of RAISE log. This is the first part of an example of the contents of the RAISE log for an inferencing episode. Splitting up the RAISE log into two parts was only done for documentation readability. Also note that some lines from the log have been split across multiple lines.



-------------IAE BEGINS---------------
Wed Dec  4 08:18:02 1996

IAE LOGGING LEVEL:   full (default=full)
USING PRECOMPUTED AGENDA
ConductSet Name: logxmp
SHORT TERM FACT: EventName("AGENT:STARTING")
SHORT TERM FACT: EventDomain("AGENT")
SHORT TERM FACT: EventType("STARTING")
SHORT TERM FACT: EventId("1")
SHORT TERM FACT: EventSelector("")
SHORT TERM FACT: EventTime("1996-12-04","08:18:02")
LONG TERM FACT:  Beauty("Nicole")

------------- AGENDA --------------
ORULE:  EventType($x) > IsExample(1);
ORULE:  IsExample(1) & EventTime($date,$time) >
               AppendFile("C:\","logxmp.run","Sample run on ",$date);
ORULE:  Beauty($x) > AppendFile("C:\","logxmp.run",$x," is beautiful.");
ORULE:  IsExample(0) & EventTime($date,$time) >
               AppendFile("C:\","logxmp.run","Non-sample run on ",$date);




The rest of the log is shown in Figure 11-5. This section shows how the long term facts, short term facts and derived facts are used in an inferencing episode. The result of each rule evaluation is shown. If the antecedent is found to be true,

If the antecedent is found to be false, the rule is followed by the phrase "THIS ORULE FAILS -- FIRST FAILED ATOM:" The first atom in the rule that was not true is also logged.

Figure 11-5. Second part of RAISE log. This is the conclusion of the example of the contents of the RAISE log for an inferencing episode.



-------------- BEGIN RULE EVALUATION ------------

ORULE:  EventType($x) > IsExample(1);
LOOKUP SUCCESS:  EventType("STARTING")
CONCLUSION (NEW): IsExample(1)

ORULE:  IsExample(1) & EventTime($date,$time) >
                   AppendFile("C:\","logxmp.run","Sample run on ",$date);
LOOKUP SUCCESS:  IsExample(1)
LOOKUP SUCCESS:  EventTime("1996-12-04","08:18:02")
CONCLUSION (NEW): AppendFile("C:\","logxmp.run","Sample run on ","1996-12-04")
EFFECTOR CALL:   [Procedure Handle: AppendFile]
                   AppendFile("C:\","logxmp.run","Sample run on ","1996-12-04")

ORULE:  Beauty($x) > AppendFile("C:\","logxmp.run",$x," is beautiful.");
LOOKUP SUCCESS:  Beauty("Nicole")
CONCLUSION (NEW): AppendFile("C:\","logxmp.run","Nicole"," is beautiful.")
EFFECTOR CALL:   [Procedure Handle: AppendFile]
                   AppendFile("C:\","logxmp.run","Nicole"," is beautiful.")

ORULE:  IsExample(0) & EventTime($date,$time) >
                   AppendFile("C:\","logxmp.run","Non-sample run on ",$date);
THIS ORULE FAILS -- FIRST FAILED ATOM: IsExample(0)

Wed Dec  4 08:18:02 1996

-------------IAE ENDS -------------------




[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]