How To Register an Engine

The Inference Web registration of an engine involves two steps: the registration of meta-information about the engine and its rules in the IWBase (Step 1); and the process of enabling the engine to generate PML documents (Step 2). If your engine is already registered in IWBase (check here), you may skip Step 1.

Step 1: Using the IWBase Core Node's registrar, add meta-information about your engine and its rules in IWBase

1. Ask for an IWBase Core node login and password, if you don't have one

You should send a message to pp@ksl.stanford.edu in order to have a login and password for the IWBase Core node.



2. Add an entry for the new engine

You need to be logged in the IWBase Core node to maintain your entries. Every entry in the registry is associated to a submitter and you are the submitter of your entries.

Once logged, you can add a new engine by selecting the Add Inference engine option and update an existing engine that belongs to you by selecting the Update inference engine. An entry for your engine needs a name to become operational.

Rules are an important kind of information related to engines. This does not mean that you need to register all the primitive rules that your engine implements since rules can be added to, associated with engines gradually.



3. Identify the primitive rules supported by your engine

Rules can be either primitive or derived. A rule is primitive with respect to an engine. Thus, a rule may be a primitive rule to one engine at the same time that it can be a derived rule to another engine.

The identification of the primitive rules may be a difficult task since, for example, some of the primitive rules can be very specific to your engine and you may never considered to describe their implementations as rules.

In general, a rule entry needs just a name to become operational. In terms of explaining the rule, however, it will be appropriate if the rule has also a description and an example in English. In terms of verifying the rule, it is required that it should have either

• a definition of its premises, conclusion and side conditions in terms of KIF patterns if it is a declarative rule or
• a verification function that is able to check the correct application of the rule.

KIF patterns or procedural attachments can be added later in the process of verifying proofs.



4. Add rules implemented by your engine that are not registered in IWBase, if any

The process is pretty much similar of adding an engine.

5. Associate rules with your engine

A rule can be implemented by many engines. So, rules are registered in an independent way w.r.t. engines. This means that rules need to be explicitly associated to engines by updating engine entries.

Step 2: Preparing your engine to dump proofs in the PML format

Engines can use any strategy for creating PML documents including the use of PML generation services (PGS), the use of the PML API, or even the implementation of their own code to generate PML code. We strongly suggest the use of PGS to dumping PML documents since they already have support for querying the IWBase in order to include the proof-related meta-data to the PML documents. Also, PGS provide an uniform way of generating PMLs in case the PML specification evolves.
In this document we describe the use of PGS for generating PML documents.

1. Implement a routine for calling the PML generation services

PML Generation Services (PGS)

Beta versions of these services are currently available on iw.stanford.edu/iwregistrar/. Also, you can have your own PGS running locally if you install a copy of the of the IWBase Domain node in your computer, which is strongly suggested. The API for using these services is also displayed if you click on the service links below.

General comments on the use of these services:

• Parameters requiring URIref values, i.e., CreateNodeSet's ns, ie, lg, must be valid URIs. IWBase entries, i.e., http://inferenceweb.stanford.edu/registry/IE/JTP.owl#JTP, are already valid URIs. Thus, problems with URIrefs are normally related to parameters requiring either node set URIs or query URIs such as CreateNodeSet's ns, qy, and nsant. If your proof is going to be published locally, then you may have some value like http://localhost:8080/foo.owl#foo for ns, for example.
  
• All URIrefs need to be encoded before they are used to call services. For example, you may get the error message "21 Service could not read the URI provided for the inference engine" from the CreateNodeSet service if you use a valid URIref for an engine, which is registered in the IWBase, but you do not encode the URIref.
• Once your engine is generating PML documents, you may have problems browsing proofs because of the way you are encoding/decoding URIrefs. For instance, if you add a URL to the address field of your standard browser, i.e., IE Explorer or Netscape, then #'s in the URL need to be replaced by %23's (and we cannot do anything to fix this). However, if you add the URL to the PML URI field in the IWBrowser, then its #'s cannot be translated into %23's now.
• Once your engine is generating PML documents, you may have problems browsing proofs because of the configuration of your web server. For instance, please check if 'owl' is in the mime list on your Tomcat (Task 2 of thebrowser installation instructions) if you get the following error:
  java.net.UnknownServiceException: no content-type at
java.net.URLConnection.getContentHandler(URLConnection.java:1062) at
java.net.URLConnection.getContent(URLConnection.java:586)
  
  

The PML generation services:

• CreateNodeSet (http://iw.stanford.edu/iwregistrar/CreateNodeSet) generates PML node sets, which are the building blocks of PML proofs and explanations. Engines use this service to facilitate the generation of their proofs into the PML format.
  
  Description of the parameters:
  

  Parameter Name	Function	Is Mandatory
  ns	URIref of the node set to be created	YES
  qy	URIref for the query file	NO
  nsroot	URIref for the root node set	NO
  ie	URIref for the associated inference engine	YES
  nscont	Node set conclusion (as a string)	YES
  lg	URIref for the language used to write the node set conclusion	YES
  rl	URIref of inference rule applied	NO
  trlist	A list of terms for variable bindings separated by comma	only if vrlist is provided
  vrlist	A list of variables for variable bindings separated by comma. Variables are preceeded by a question mark (?). The list should have the same number of elements of trlist	only if trlist is provided
  nsant	List of URIrefs of antecedent node sets separated by comma	NO
  nsdis	List of URIrefs of discharged node sets separated by comma	NO
  kslist	List of URIrefs of associated knowledge sources separated by comma	NO

  
  
  

  • CreateNodeSet creates one node set and one inference step associated with the new node set.
    
  • The qy parameter associates a node set with a query.
    
  • The nsroot parameter associates a node with the main node set answering the query (that may not necessarily be the next consequent node in a given proof).
    
  • A node set cannot be associated with a query and a root node set at the same time.
    
  • The AddInferenceStep service adds a new inference steps into an existing node set.
    
  • The GetURIFromURL service retrieves the URIref of a registry entry from its URL.
    

  
  
  
  The response is a text tagged with one or more of the following elements:
  

  Tag	Name	Meaning
  RC	Return Code	0 if successful; >0 if fail
  result	DAML file	A DAML file representing the requested node set.
  errormsg	Error message	A description of the error when RC>0

  
  

• CreateQuery (http://iw.stanford.edu/iwregistrar/CreateQuery) generates a IW query file. Engines can use this service to generate PML query files. Queries used to answer questions can be presented to users once they are stored in the PML format.
  
  Description of the parameters:
  

  Parameter Name	Function	Is Mandatory
  qy	URIref for the query file to be created	YES
  qycont	The query itself	YES
  ie	URIref of the inference engine performing the query	YES
  qt	URIref of associated question	NO
  nslist	URIref of associated node sets that are answers for the query	NO

  
  
  Answers can be added to this query later by using the AddAnswers services.
  
  

• CreateQuestion (http://iw.stanford.edu/iwregistrar/CreateQuestion) generates an IW question file. Agents with embedded engines can use this service to generate PML documents storing questions probably written in a natural language, i.e., English, for future use in the process of presenting and explaining question answers.
  
  Description of the parameters:
  

  Parameter Name	Function	Is Mandatory
  qt	URIref of the question file to be created	YES
  qtcont	A question in natural language, e.g., 'What is a cat?'	YES
  ap	Answer pattern - a sentence in natural language where variables are identified with a question mark sign, e.g., 'A cat is a ?answer'	NO
  qylist	List of URIrefs of associated queries	NO

  
  
  

• GetURIfromURL (http://iw.stanford.edu/iwregistrar/GetURIFromURL) service retrieves a URIref from any URL related to a concept in the IWBase. This service may be used in combination with the other services using URIrefs.
  
  Description of parameter:
  

  Parameter Name	Function	Is Mandatory
  url	A URL	YES


The following rarely used services are also available:

• AddAnswer (http://iw.stanford.edu/iwregistrar/AddAnswers) service associates node sets with queries. Labeling sentences and variable bindings in node sets associated with queries are the answers of the query.
  
  
• AddQueries (http://iw.stanford.edu/iwregistrar/AddQueries) service associates queries with questions.
  
  

Typical Uses of PGS

A short process of generating proofs may involves the creation of Node Sets only. If you have never generated a set of PML documents, this is the preferred way of testing the capability of your engine of generating PML proofs.

1. Task 1: For the proof of each answer of a query, the engine can traverse the proof, proof step by proof step, calling the CreateNodeSet service for each step of the proof passing the appropriate parameters. For testing purposes, the first run of this task may pass only mandatory parameters to CreateNodeSet.

A complete process of generating proofs may involves the creation of Questions, Queries and Node Sets. The use of these services may vary from engine to another. However, they are not expected to be much different of the typical process described as follows.

1. Task 1: An agent answering a question can use the CreateQuestion service to store the original question for future use.
2. Task 2: The agent may reformulate the question into queries and call one or more engines to answer these queries.
3. Task 3: Engine can use the CreateQuery service to store queries. Alternatively,the CreateQuery service can be called later in the process, after the answers are generated. Thus, the engine should be able to pass the URIs of the newly created node sets that are going to be associated with the new query as answers (Task 5 is not needed in this case).
4. Task 4: For the proof of each answer of a query, the engine can traverse the proof, proof step by proof step, calling the CreateNodeSet service for each step of the proof passing the appropriate parameters.
5. Task 5: Last node sets in a set of connected PML documents are usually query answers. The AddAnswers service associates node sets with queries as query answers.
6. Task 6: The AddQueries associated service associates questions with queries.
   
   

Since node sets are the building blocks of proofs represented in sets of PML documents, engines just need to perform Task 4 in order to generate proofs. However, proofs from engines performing Tasks 3, 4 and 5 may have a better presentation since users should be able to visualize the queries associated with proofs and answers associated with the queries.

2. Publish successful results of PGS

The routine calling the PGS need to strip off the successful results of PGS calls and to put them in a place on the local filesystem corresponding to the nodeset URI.

Step 3: Use IWBrowser to browse your PML documents

In the process of generating PML documents, it is an good idea to keep records of the URIrefs either of generated queries or the node sets concluding the answers of queries. Thus, using these URIrefs, you our a software using your engine (i.e., an agent) may be able to call the IWBrowser that is going to render proofs from the given node sets.