Reference Manual

| Table of Contents |

Rule Editor

The Rule Editor tool is used to specify the behavioral rules used by the agent. (Note: Throughout this section behavioral rules are simply called rules). Rules are the basic control mechanism for AgentBuilder agents; they determine how the agent responds to external and internal stimuli. Each rule consists of a set of conditions and the desired actions or mental changes that will occur when those conditions are met. The set of conditions is sometimes referred to as the rule's the left-hand side, or LHS; the actions and mental changes are the rule's right-hand side, or RHS. The Rule Editor has separate panels for constructing the two sides of a rule.

The Rule Editor allows you to create two different types of conditions for the left-hand side of a rule. One type of condition is based upon external events and is termed a message condition. A message condition is a test performed on any new messages arriving in the agent's input buffers (e.g., comparing the name of the message sender against an expected sender name). The second type of condition is based upon the agent's internal state and is termed a mental condition. A mental condition is a test performed on beliefs in the mental model of the agent.

Patterns on the left-hand side of a rule generally consist of a combination of operators, variables, constant values, and references to named instances in the mental model. Most variables will bind to all instances of a specified type in the mental model. For example, assume ?i is the name of an Integer variable. In the pattern (?i >= 4) the variable ?i will bind to every Integer instance in the mental model and the value of each binding will be used in the comparison. In contrast, a named instance variable is a special type of variable which will bind only to a named instance with the specified name and type. For example, the pattern ( currentCount >= 4 ) contains the named instance variable currentCount , which can bind only to the named instance currentCount in the mental model. A named instance variable is similar to a global variable in that it can be used in any of the agent's rules and will always bind to the same instance in the mental model.

The following example illustrates the difference between the two types of variables, using a trivial mental model with three Integer beliefs.

Mental Model

Integer<width> 8

Integer<length> 3

Integer<currentCount> 5

Rule 1

IF ( ?i >= 4)

THEN ( DO SystemOutPrintln( "Rule 1 Fired." )

Rule 2

IF ( currentCount >= 4)

THEN ( DO SystemOutPrintln( "Rule 2 Fired." )

In Rule 1 the Integer variable ?i will bind to each of the Integer values in the mental model and each value will be compared to 4. Rule 1 will fire twice: once with ?i bound to 8, then once with ?i bound to 5. The binding of ?i to 3 does not satisfy the pattern in Rule 1 so the rule will not fire with that binding. In Rule 2 the named instance variable currentCount will bind to the value 5 from the currentCount named instance (which satisfies the pattern) and so Rule 2 fires once.

Technically there's a difference between a named instance and a named instance variable: a named instance is part of the mental model (i.e., it's a belief), but a named instance variable is a component of a pattern in a rule. In some situations it's important to understand this distinction. It's possible (and fairly common) for a pattern in a rule to refer to a named instance which does not always exist in the mental model. Adding a named instance variable to a pattern in a rule does not guarantee that the associated named instance will be present in the mental model.

For example, consider the Print rule of Example Agent 3 in the AgentBuilder User's Guide. The second IF pattern in that rule contains a Boolean named instance variable named Ready_to_print :

( Ready_to_print EQUALS true )

The Ready_to_print named instance variable refers to an instance that does not exist in the agent's mental model until it gets asserted during execution, by the Connect rule. Even though at the start there is no instance named Ready_to_print in the mental model, the Print rule does contain a Ready_to_print named instance variable. This pattern evaluates to true only if the Ready_to_print instance exists in the mental model and has the value true . The pattern evaluates to false if the mental model does not contain a named instance that matches the named instance variable in the pattern. In this example, the Print rule is prevented from firing until the Ready_to_print instance is found in the mental model.

When the Connect rule is fired it performs the mental change:

( ASSERT ("Ready_to_print" true) )

This is the mental change that actually creates the Ready_to_print instance and assigns it a name and a value. After this instance has been asserted into the mental model the pattern for the Print rule (shown above) will evaluate to true and the Print rule will be activated.

A named instance variable is similar to a global variable in that it can be used in any of the agent's rules and will always bind to the same instance in the mental state. In the previous example with the currentCount named instance, several rules could have patterns that refer to currentCount and all of them would access the same value each cycle.

For the right-hand side of a rule, the Rule Editor allows you to specify the actions that occur when the rule's conditions are satisfied. Actions can be created so that they affect the agent's mental model of the external world.

Overview

The Rule Editor is divided into two major panels; one panel for editing the left-hand side of a rule and one panel for editing the right-hand side. The editor for the left-hand side of the rule is referred to as the LHS editor; the editor for the right-hand side is referred to as the RHS editor.

The Rule Editor contains a menu bar with four items: File , Edit , Windows and Help . The File menu allows you to open (i.e., load and start editing) previous rules as well as save the current one. Selecting File < New < New Rule creates a completely new rule, or selecting other items under File < New will clear selected sections in the existing rule. For example, choosing File < New Condition causes the condition accumulator line to be cleared.

The main features of the Rule Editor are the accumulator text fields and the pattern lists. Each editor has accumulator text fields; these are single-line text fields with a New and Add button directly below them. The accumulators are used to accumulate the components of arbitrarily complex conditions or action expressions. The pattern lists are at the middle and bottom of the LHS editor; the action/mental change list is at the bottom of the RHS editor.

A rule is made up of individual patterns which are built up one at a time in the accumulator line and then added to the lists. By utilizing the pull-down menus as well as context sensitive pop-up menus, you can construct complex expressions as desired. Several of the dialogs used in constructing the rule use a tree paradigm. In addition, the Up and Down buttons at the right side allow you to change the ordering of individual lines. Thus it's easy for you to rearrange ordering of patterns (or actions or mental changes) within the rule.1

Rule Properties

Edit < Properties allows the user to access the rule properties. The two basic parts of the Rule Properties dialog are the name of the rule and the rule description. There are few constraints on the name of a rule; only that it be unique within the rule set and that it not use hidden characters. You're encouraged to choose descriptive rule names; you may even find that descriptive phrases work well as rule names. The description window allows you to add a description to accompany the rule. No size limitations are imposed, but generally only a few sentences are required.

LHS Editor

Figure 56 shows the LHS Editor. There are three main panels: the Conditions panel, the message conditions pattern list and the mental conditions pattern list.

Figure 56. Rule Editor LHS

The Conditions panel is composed of two pull-down menus and three pop-up dialogs, an accumulator, a New button, and Add button, a Message Conditions panel, and a Mental Conditions panel. The Operators menu is common to all panels in both the LHS and RHS editors, but the items available in each Operators menu will differ depending on the panel. In the Conditions panel, the Operators menu contains various relations and pattern modifiers that are useful in patterns. The operator elements in this menu fall into several different categories shown below. See Operators and Patterns for a detailed description of the operations.

  • equality relations ( EQUALS, NOT_EQUALS )
  • boolean relations ( AND, OR, NOT )
  • binding relation ( BIND )
  • quantified relations ( FOR_ALL, EXISTS )
  • numerical relations ( <=,<, !=, =, ...)
  • string functions ( concat, substring , ...)
  • arithmetic functions ( +, -, *, / )
  • mathematical functions (tan, arctan, cos, arccos, sqrt , ...)
  • miscellaneous functions (SET_TEMPORARY)

The Values menu allows you to construct an instance of any Java type, a KQMLMessage type, a Time type, or a Class type and insert it into the current pattern. This is useful when you want to specify a comparison against a constant value. For example, if you want to test whether a field in an object is less than 4, you could specify the constant value (i.e., 4, probably as an integer or float ) in the Values menu.

For the Java types, you will be presented with a dialog for entering a literal value. For the KQMLMessage , TIME and Class type, the user is present with a specific dialog for entering each of the aforementioned types.

There are three different pop-up dialogs. The first is the New Variable dialog. This dialog allows you to construct new variables that will be available for use in patterns.Figure 57 shows the New Variable dialog. To create a new variable, you would first select the PACs or Java Types radio button. Once a radio button has been selected, a list of available variables types will be displayed. You can then select a PAC or Java type. Once a variable type has been selected, the focus will be transferred to the Variable Name text field. Type in a name for the new variable and select the Add button. Selecting the Add button will add the new variable to the list at the bottom of the dialog.

Figure 57. New Variable Dialog

The creation of a KqmlMessag e variable differs in that a different pop-up dialog is displayed when you click on the Add button. You will be shown a Binding Dialog for the KqmlMessage variable, as shown in Figure 58. You can specify the KQML message binding to be an incoming or mental model message by using the pull-down menu. Once selected, you can click on the OK button so that the KqmlMesage variable can be added to the list of new variables and the dialog can be dismissed.

Figure 58. KQML Message Binding Dialog

The Rule Editor supports the creation of an Array variable. The Array type is listed in the Java Types panel. Like the creation of the KqmlMessage , a different pop-up dialog is displayed when you click on the Add button. You will be shown an Array Dialog for the Array variable, as shown in Figure 59. You can specify the array type by selecting a type from the list. Notice that you will be able to create an array of Java types, Vector, Hashtable, Enumeration, and PAC types. Once selected, you can click on the OK button so that the array variable can be added to the list of new variables and the dialog can be dismissed.

Figure 59. Array Dialog

The Defined Variables dialog allows you to select previously defined variables for use in a message or mental pattern. Figure 60 shows the Defined Variables dialog. For any array types in the Java Types panel, the array variable will only have attributes for the component type and length. This dialog also allows you to cast the selected variable to a different type. To cast a selected variable, select from the Casting Type combo box. The combo box contains a list of all available PACs and Java types. Once a casting types has been selected, the type of the selected variable will be updated in the dialog. You can no click on the OK button to add the selected variable to the Condition panel's accumulator text field.

Figure 60. Defined Variable Dialog

The Instances pop-up dialog allows you to specify conditions based on named instances in the mental state. Figure 61 shows the Instances dialog.

Figure 61. Instances Dialog

Like the Defined Variables dialog, the Instances dialog allows you to cast named instances to an available PAC or Java type. To cast a named instance, use the same method as was described in the Defined Variables dialog.

The New button allows the user to create a new message or mental condition. The same can also be done by selecting File < New < New Condition . Pressing the Add button will cause AgentBuilder to check to see if the pattern in the accumulator is valid. If the pattern is valid, it will be added to either the Message Conditions list or the Mental Conditions list.

RHS Editor

Figure 62 shows the RHS Editor. There are two main panels: the Actions panel and the Defined RHS Elements panel. The created patterns from the actions panels supply the Defined RHS Elements list with action statements.

Figure 62. Rule Editor (RHS)

Action Panel

The Actions panel is composed of four pull-down menu, four pop-up dialogs, an accumulator line, a New button and an Add button. By using these dialogs and menus, you can create arbitrarily complex arguments and mental change statements.

The Operators pull-down menu allows access to various functional operators. This menu supplies a subset of the operators in the LHS operator lists. These operators (along with their operands) can be used as arguments for actions. These operators include:

  • string functions
  • arithmetic functions
  • mathematical functions
  • miscellaneous functions (ASSERT, RETRACT, SET_TEMPORARY)

The Actions pull-down menu allows access to the user-defined actions. The user-defined actions must first be defined in the Action Editor before they can be used in the Rule Editor. Please see the Action Editor section for more information about defined actions.

The built-in Actions pull-down allows access to the system-defined actions supported by the Run-Time System. For a more detailed description of the built-in actions please see Intrinsics.

There are three key components which are identical to their counterparts in the Conditions panel in the LHS editor: the Values pull-down menu, the Defined Variables dialog, and the Instances dialog.

The New Object dialog is used when defining new instances of PACs or Java types. Figure 63 shows the New Object dialog. To specify a new object, you must first select the type of object that you want to create. Once you have selected a type, you must then select the constructor to use for that type. The new object will then be inserted into the action pattern. Any parameters for the new object will need to be specified in the action pattern. The New Object dialog is used when specifying a parameter to an action that needs to be built at rule execution time.

Figure 63. New Object Dialog

The Return Variable dialog is used to rename any automatically generated return variable. Figure 64 shows the Return Variable dialog. Return variables are automatically created for any private action, built-in action, or method that returns something. To change the name of a return variable, you first select the return variable in the Action pattern's accumulator. Then click on the Return Variable button to pop-up the dialog. Once the dialog is displayed, you select the type of the return variable that you are replacing. Once the type is selected, you can enter a variable name. Clicking on the OK button will then rename the selected return variable.

Figure 64. Return Variable Dialog

The New button allows you to create an action. You can also do this by selecting File < New < New Action . The Add button will check to see if the pattern in the accumulator is valid. If the pattern is valid, it will be added to the Defined RHS Elements list.

Defined RHS Elements Panel

The last panel in the RHS editor is the Defined RHS Elements panel which contains the list of private actions and mental changes on the RHS of the rule. The Up and Down buttons on the right of the panel can be used to rearrange the elements in the list, and the Delete button can be used to delete a selected element. It is crucial to maintain the integrity of the ordering within this list. Actions, except for the built-in SendKqmlMessage , will always be executed before the mental changes are performed. You may change the ordering within the list of actions, but if any action uses the returned value from another action, it must follow that action in the list. For example, if action Foo returns an Integer which is to be used as an argument for action Bar , then Foo must be listed ahead of Bar in the Defined RHS Elements list; this will cause Foo to be executed first and the return value will then be available for use in Bar .

Rule Editor Operations

Creating a New Rule

Constructing a new rule is relatively simple. Select the File < New < New Rule menu item. This clears all elements from the Rule Editor. If a rule was currently loaded, and it was modified, a dialog will be displayed asking if the current rule is to be saved. Figure 65 shows the dialog that will be displayed in creating a new rule.

Figure 65. Rule Properties Dialog

The Rule Properties Dialog allows you to provide a name and description for the new rule. This information can later be changed by selecting the Properties menu item from the Edit menu. Once the information for the rule has been entered, select the OK button to apply the changes. Selecting Cancel button will cancel any changes to the rule's name or description. If this dialog was displayed as a result of selecting the New Rule menu item, selecting Cancel will defer naming the new rule.

Loading an Existing Rule

To load an existing rule, select File < Open . A list of the rules previously defined for the agent will appear. Load the existing rule by either double clicking on its name or by clicking on its name and clicking on the OK button. Either selection method causes the rule to be loaded into the editor.

Constructing a Simple Mental Condition

The first step in constructing a simple mental condition is to choose the operator to be used, usually the EQUAL or NOT_EQUAL operators. Next, specify the operands that are to be compared, starting with the operand to the left of the operator. For example, a mental condition might test for equality between an attribute in a PAC variable and a string constant. Each operand can be an instance, a defined variable, a constant value, or the result returned from a function (e.g., the concatenation of two strings). To specify an operand, choose the correct dialog and select the desired element. Finally, specify the operand on the right side of the operator. Figure 66 shows the Values dialog where the string constant is defined. Enter the desired string and click on OK . This causes the string value to be entered into the current pattern. When the pattern is complete, click on Add to add the current pattern to the list of mental patterns.

Figure 66. String Value Dialog

Direct Method Invocation

Directly invoking methods allows you to bypass creating a private action for a method you want to use in an action pattern. To use direct method invocation, you can either pop-up the Defined Variable or Instances dialog. In both dialogs, each non-primitive type is represented with a folder icon, and will contain zero or more child nodes. The child nodes represent field attributes of the type as well as any methods, with attributes listed first. To specify a method to be invoked, you must select the desired method and click on the OK button. The method invocation will then be inserted into the action pattern being built. Now, actions need only be created when you want to use the private action to create an initial commitment. Figure 67 shows this process.

Figure 67. Direct Method Dialog

Return Variable Naming

Anytime a method invocation or a built-in action that has a return variable is chosen, a Return Variable Name Dialog is displayed, as shown in Figure 68. You can either name the variable or accept a default name provided by AgentBuilder. Choosing OK , accepts the default name. There is no way to rename this variable after this operation, although you can easily recreate a pattern. The alternative is to type in the name you want the variable to have. If you enter a duplicate variable name, then an error dialog will be displayed and you must re-enter the name.

Figure 68. Return Variable Name Dialog

Using a Predicate Method

Predicate methods (i.e., methods that return a Boolean value) defined in the PACs may be used to construct mental conditions. The available predicate methods are displayed in the Defined Variables and Instances dialogs in the same way that the PAC attributes are displayed. Click on the method name to select it, then click on OK to insert the predicate method into the current pattern. After selecting the predicate method you'll need to specify values for any parameters required by the method. Figure 69 shows the format for the predicate methods on an example PAC in the Defined Variables dialog.

Figure 69. Predicate Methods in the Defined Variable Dialog

Constructing an Action Statement

Constructing an action statement is straightforward. Select the desired action from the Actions or Built-in Actions lists. Next, specify all parameters for the selected action. The Rule Editor automatically creates a variable to hold the value returned by each action statement so that the returned value can be used as a parameter in other actions or in mental changes. The tool adds these variables to the Defined Variables list so they can be selected for use in other RHS patterns.

Note: If an action has not been associated with an instance of a PAC, the ConnectAction built-in action must be executed first. For example, if an action named Print has been defined to use the print(String) method on a PAC instance named myControlPanelPac and the action has not been associated with the instance, ConnectAction(Print, myControlPanelPAC) must be executed before Print is executed. The section, PAC Editor, provides more information about actions and PACs.

Building an Assertion with a New Object

As previously mentioned, an assertion adds a new instance of a class to the agent's mental model. To specify an assertion, first select the ASSERT item in the Operators menu from the Actions panel. This causes a dialog to appear with a text field and a prompt. If you want to associate a name with the instance that will be asserted (e.g., you may want to assert a new Location instance named currentLocation ), type the name into the text field and click OK . If you're not interested in providing a name for the instance, just leave the text field blank and click OK to close the dialog. After the dialog is closed the assertion template, ASSERT(<>) will be added to the mental change accumulator.

Next, click on the New Object button, which will cause the New Object dialog to appear, as shown in Figure 70. This allows you to select the class type for the instance. Click on the name of a class to select it. After you have selected a class type, select a constructor from the pull-down menu at the bottom of the dialog, then click on OK . This inserts the new object into the mental change accumulator. At this point you must specify the parameters for the constructor. The parameters can be existing objects found in the Instances or Defined Variables dialogs, or they can be other new objects created in the New Objects dialog. It is possible to use new objects as parameters to constructors, actions or other functions.

Figure 70. The New Object Dialog

Closing the Rule Editor

You can close the Rule Editor by selecting the Close item in the File menu. If necessary, AgentBuilder will ask you whether you want to save your changes or not. By selecting Yes you can save all of your changes since the previous save. If you select No you'll revert to the rule configuration last saved.


 

| Table of Contents |


AgentBuilder is a registered trademark of Reticular Systems, Inc.
Copyright © 1998-2001 Reticular Systems, Inc.