KWI Reference

(Full Version)

Preparing to Run a Knowledgebase

Before the knowledgebase can be run, the KWI must be initialized, a knowledgebase file opened and session started. The following KWI calls provide those services.

initialize

kwi(kw_init, initialize([directory = <kb_pathname>, session_directory = <session_pathname>, log_file = <log_file>, message_level = <level>, goals=<list>, save_session = <true | false>]), INFO)

Parameters:

• <kb_pathname> The fully qualified name of the directory where the knowledgebase is located and the log file will be opened.
• <session_pathname> The fully qualified name of the directory where the temporary session files will be created.
• <log_file> The name of the log file. OPTIONAL.
• <level> The message level for the log file: hi, medium, low, none. OPTIONAL.
• <list> The list of goals to solve the knowledgebase for. This list supercedes the goals in the 'main' knowledgebase object. OPTIONAL.
• save_session Determines whether or not the session state is saved to disk after each KWI call to get the actions. This is used in environments like CGI programs on webservers that restart the reasoning engine each time the user answers some questions.

Returns the property list INFO containing:

• system = <string> The name of the reasoning engine.
• version = <string> The version number of the reasoning engine.

Initializes the reasoning engine.

Examples:

kwi(kw_init, initialize([directory = \"" + doubleSlashes(App.path) 
+ "\\", session_directory = \"" + doubleSlashes(App.path) + "\\", 
log_file = "vbrun.log", message_level = high]), INFO) INFO = [system 
= "basic", version = "4-1-1"] kwi(kw_init, initialize([directory 
= \"" + doubleSlashes(App.path) + "\\", session_directory = \"" 
+ doubleSlashes(App.path) + "\\"]), INFO) INFO = [system = "support", 
version = "4-2-2"]

open

kwi(kw_init, open(<knowledgebase_file>), _)

Parameters:

• <knowledgebase_file> The name of the knowledgebase file. It must reside in the directory specified in kwi / initialize.

Returns:

• Nothing.

Opens the specified knowledgebase file.

Examples:

kwi(kw_init, 
open("amzi_website_advisor.kb"), _)

new_session

kwi(<id>, new_session, _)

Parameters:

• <id> The identifier for this session.

Returns:

• Nothing.

Creates a new reasoning session with the specified identifier. The identifier is used in all subsequent KWI calls.

Examples:

kwi(s22, 
new_session, _)

Running the Knowledgebase

solve

kwi(<id>, solve, MORE)

Parameters:

• <id> The identifier for this session.

Returns:

• MORE = 'more' if the reasoning process has more work to do, else 'no_more'

Tells the inference engine to start or continue reasoning. After each call to solve, get_action needs to be called and acted upon until there are no more actions.

Examples:

kwi(session0, solve, MORE) MORE = more kwi(s22, solve, 
MORE) MORE = no_more

backup

kwi(<id>, backup(fact(<name>, <value>), SUCCESS)

Parameters:

• <fact> The name of the fact.
• <value> The value of the fact (currently ignored).

Returns:

• SUCCESS = 'true' if the reasoning process was able to backup to when the specified fact became known

Tells the inference engine to backup the reasoning process to when the specified fact became known. This truncates the list of known facts back to and including named fact, so that all questions asked since that fact will be re-asked. Also, all intermediate goals proven, will be reproven. This call is useful for CGI programs on web servers that back-up to prior screens. It can be used in any application where the inputs to the reasoning process need to be changed.

Examples:

kwi(session0, 
backup(fact(colors, _)), SUCCESS) SUCCESS = true kwi(s22, backup(fact(name, _)), 
SUCCESS) SUCCESS = false

Interacting with the User

get_action

kwi(<id>, get_action, ACTION)

Parameters:

• <id> The identifier for this session.

Returns the property list ACTION containing:

• ask(user, object_name, <property_list>) The list of properties from the question object that the reasoning engine needs a value for.
• tell(user, <property_list>) The list of properties from the text object for the goal the reasoning engine has deduced is true.
• none No more actions to perform. Call solve again.

Returns an action to be performed. It can be a question to ask the user, in which case the reasoning engine expects an KWI assert to tell the reasoning engine what the user answered. The action can also be a conclusion the reasoning engine has determined is true. If that conclusion is associated with a text object, the fields of that object are returned.

The list of 'ask' actions always contains a special action to ask 'html' that provides all the questions already formatted for display in a browser according to the values in the main knowledgebase object.

Examples:

kwi(session0, 
get_action, ACTION) ACTION = ask(user, colors, [prompt = "What are your favorite 
colors?", question_type = menu_multiple_choices, choices = ["red", 
"orange", "yellow", "green", "blue", "idigo", 
"violet"] ]) ACTION = ask(html, colors, [html = "<FORM METHOD="POST" 
ACTION="/cgi-bin/knowledgewright4/kwcgibasic?[kb_file='amzi_website_advisor.kb']"> 
What are your favorite colors<BR> <INPUT NAME="colors" TYPE=CHECKBOX 
VALUE="red">red</INPUT><BR> <INPUT NAME="colors" 
TYPE=CHECKBOX VALUE="orange">orange</INPUT><BR> ... <INPUT 
NAME="colors" TYPE=CHECKBOX VALUE="violet">violet</INPUT><BR> 
<P><INPUT NAME="submit" TYPE="submit" VALUE="Continue"></INPUT>
 
</FORM>" ]) kwi(s22, get_action, ACTION) ACTION = tell(user, [goal 
= "moods", text = "Your colors indicate you are in a good mood."] 
)

Asserting New Fact Values

assert

kwi(<id>, assert(fact(<name>, <value>)), _)

Parameters:

• <id> The identifier for this session.
• <name> The name of the question (fact).
• <value> The value selected by the user using appropriate quoting, if needed, for strings, and square brackets for lists (multiple values).

Returns:

• Nothing.

Asserts a new fact value for the reasoning engine to use. String values should be passed in "'s. Lists of values are passed in square brackets, separated by commas (also quoted if necessary).

Examples:

kwi(session0, assert(fact(age, 33)), _)
 
kwi(s22, assert(fact(colors, ["blue", "orange", "violet"])), 
_)

Getting Session State

get_session

kwi(<id>, get_session, SESSION)

Parameters:

• <id> The identifier for this session.

Returns the property list SESSION containing:

• known = LIST The list of known and deduced facts and objects during the reasoning process.
• Various internal settings.

Returns the state of the reasoning process. This is usually used after an answer has been obtained to generate a results log for later analysis.

Examples:

kwi(session0, get_session, SESSION), 
member(known = KLIST, SESSION), 
write_results_log(RFILE, KLIST)